OneAuth/docs/configuration.md

VBase 配置文档

本文档说明 VBase 系统的配置架构，包括本地配置文件和线上运行时配置。

配置分层

层级	存储位置	作用域	修改方式
本地配置	cfg/cfg.go + 配置文件	单实例	修改配置文件 + 重启
线上配置	数据库 settings 表	全局	管理后台/API 实时生效

---

一、本地配置（Local Config）

存储在 cfg/cfg.go，仅包含系统启动必需的配置项。

1.1 配置项列表

# config.yaml 示例

dsn: "root:123456@tcp(127.0.0.1:3306)/vbase?charset=utf8&parseTime=True&loc=Local"
db: "mysql"

redis:
  addr: "localhost:6379"
  password: ""
  db: 0

# 系统密钥，用于加密敏感数据（JWT、数据库加密字段等）
# 生产环境务必修改，建议 32 位以上随机字符串
key: "your-secret-key-change-in-production-min-32-characters"

host: "0.0.0.0"
port: 8080

storage_path: "./data"

# 初始管理员配置（无人值守部署时使用）
# 当用户表为空且 username/password 都有值时，启动会自动创建该管理员
init_admin:
  username: "admin"
  password: ""           # 生产环境务必设置强密码
  email: "admin@example.com"

1.2 配置项说明

配置项	类型	必填	说明
dsn	string	是	数据库连接字符串
db	string	是	数据库类型：mysql/postgres/sqlite
redis	object	是	Redis 配置，addr: "memory" 使用内存模式
key	string	是	系统密钥，用于加密敏感数据（建议 32 位以上）
host	string	否	服务监听地址，默认 0.0.0.0
port	int	否	服务监听端口，默认 8080
storage_path	string	否	文件存储路径，默认 ./data
init_admin	object	否	初始管理员配置（无人值守部署时使用）

init_admin 详细说明：

系统提供两种互斥的初始化管理员方式：

方式	触发条件	适用场景
自动创建（本配置）	username 和 password 均已配置	无人值守部署、容器化环境
首注成为 admin	password 为空，首个用户注册时	交互式部署、开发测试

方式一：配置 init_admin（推荐用于生产）

当满足以下条件时，系统启动时自动创建管理员：

• 用户表为空（首次部署）
• init_admin.username 和 init_admin.password 均已配置

init_admin:
  username: "admin"
  password: "YourStrongPassword"
  email: "admin@example.com"

效果：启动时自动创建 admin，后续注册的用户均为普通 user。

方式二：首个注册用户成为 admin（默认行为）

当 init_admin.password 为空时，保持原有逻辑：

• 第一个注册用户自动被授予 admin 角色
• 从第二个用户开始均为普通 user

字段说明：

字段	类型	必填	说明
username	string	是	管理员用户名
password	string	条件	密码（配置则启用方式一，为空则启用方式二）
email	string	否	邮箱地址

其他注意事项：

• 仅在没有用户时生效，已有用户则跳过
• 密码会被 bcrypt 加密存储
• 自动授予 admin 角色（系统级权限）
• 启动成功后会打印日志：[vbase] Initial admin user 'xxx' created successfully

1.3 使用场景

• 多环境部署（开发/测试/生产使用不同的数据库）
• 容器化部署（通过环境变量注入）
• 密钥管理（密钥文件不进入版本控制）

1.4 注意事项

• 修改后需要重启服务才能生效
• 敏感信息（密码、密钥）建议通过环境变量注入
• 生产环境务必修改默认密钥

---

二、线上配置（Runtime Config）

存储在数据库 settings 表，支持运行时动态修改，无需重启服务。

2.1 配置分类

分类	前缀	说明
auth	auth.*	登录注册策略
email	email.*	邮件服务配置
sms	sms.*	短信服务配置
security	security.*	安全策略
oauth	oauth.*	第三方登录配置

2.2 认证配置（auth）

配置键	类型	默认值	说明
auth.reg.require_email	bool	false	注册是否要求填写邮箱
auth.reg.require_phone	bool	false	注册是否要求填写手机号
auth.login.methods	json	["password"]	启用的登录方式：password/email_code/phone_code
auth.login.password_fields	json	["username"]	密码登录支持的身份标识

配置组合示例：

// 仅用户名登录（最小化配置）
{
  "auth.reg.require_email": "false",
  "auth.reg.require_phone": "false",
  "auth.login.methods": "[\"password\"]",
  "auth.login.password_fields": "[\"username\"]"
}

// 用户名+邮箱，支持邮箱验证码登录
{
  "auth.reg.require_email": "true",
  "auth.reg.require_phone": "false",
  "auth.login.methods": "[\"password\", \"email_code\"]",
  "auth.login.password_fields": "[\"username\", \"email\"]"
}

// 用户名+手机，支持手机验证码登录
{
  "auth.reg.require_email": "false",
  "auth.reg.require_phone": "true",
  "auth.login.methods": "[\"password\", \"phone_code\"]",
  "auth.login.password_fields": "[\"username\", \"phone\"]"
}

2.3 验证码配置（security）

配置键	类型	默认值	说明
code.expiry	int	5	验证码有效期（分钟）
code.length	int	6	验证码长度
code.max_attempt	int	3	最大验证尝试次数
code.send_interval	int	60	发送间隔（秒）
code.max_daily_count	int	100	单日最大发送次数（0=禁用，-1=不限制）

2.4 邮件配置（email）

配置键	类型	默认值	说明
email.enabled	bool	false	是否启用邮件服务
email.provider	string	"smtp"	邮件服务商：smtp/sendgrid
email.smtp.host	string	""	SMTP 服务器地址
email.smtp.port	int	587	SMTP 端口
email.smtp.user	string	""	SMTP 用户名
email.smtp.pass	string	""	SMTP 密码（加密存储）
email.from	string	""	发件人地址
email.from_name	string	"VBase"	发件人显示名称

SMTP 配置示例：

{
  "email.enabled": "true",
  "email.provider": "smtp",
  "email.smtp.host": "smtp.gmail.com",
  "email.smtp.port": "587",
  "email.smtp.user": "noreply@example.com",
  "email.smtp.pass": "encrypted_password",
  "email.from": "noreply@example.com",
  "email.from_name": "MyApp"
}

2.5 短信配置（sms）

配置键	类型	默认值	说明
sms.enabled	bool	false	是否启用短信服务
sms.provider	string	"aliyun"	短信服务商：aliyun/tencent
sms.access_key	string	""	阿里云 AccessKey ID
sms.access_secret	string	""	阿里云 AccessKey Secret（加密存储）
sms.sign_name	string	""	短信签名
sms.template_code	string	""	验证码模板 CODE
sms.endpoint	string	""	自定义接入点（可选）

2.6 第三方登录（OAuth Providers）

OAuth Provider 配置存储在数据库中，支持动态添加、修改、启用/禁用。系统内置常用 Provider 模板，也可自定义接入任意支持 OAuth 2.0 的平台。

内置模板：

模板名称	说明
google	Google 账号登录
github	GitHub 账号登录
wechat	微信登录
feishu	飞书登录
dingtalk	钉钉登录

Provider 数据结构：

字段	类型	说明
code	string	唯一标识，如 google、github
name	string	显示名称
enabled	bool	是否启用
client_id	string	OAuth Client ID
client_secret	string	OAuth Client Secret
auth_url	string	授权端点 URL
token_url	string	Token 交换端点 URL
user_info_url	string	用户信息端点 URL
scopes	[]string	请求的权限范围
user_id_path	string	从用户信息中提取 ID 的字段路径
user_name_path	string	从用户信息中提取用户名的字段路径
user_email_path	string	从用户信息中提取邮箱的字段路径
user_avatar_path	string	从用户信息中提取头像的字段路径
extra_config	json	额外配置参数

Field Path 说明：

用于从 OAuth 服务商返回的用户信息 JSON 中提取字段，支持点号路径：

• id - 直接取根级 id 字段
• data.employee_id - 取 data 对象下的 employee_id
• sub - OpenID Connect 标准字段

使用内置模板创建 Provider：

POST /api/v1/oauth/providers

{
  "template": "google",
  "name": "Google",
  "client_id": "your-client-id.apps.googleusercontent.com",
  "client_secret": "your-client-secret",
  "enabled": true
}

自定义 Provider 示例（企业微信）：

POST /api/v1/oauth/providers

{
  "code": "wecom",
  "name": "企业微信",
  "client_id": "wwxxxxxxxxxxxxxxxx",
  "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "auth_url": "https://open.weixin.qq.com/connect/oauth2/authorize",
  "token_url": "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
  "user_info_url": "https://qyapi.weixin.qq.com/cgi-bin/user/getuserinfo",
  "scopes": ["snsapi_base"],
  "user_id_path": "UserId",
  "user_name_path": "name",
  "extra_config": {
    "agent_id": "1000002"
  }
}

---

三、配置管理 API

3.1 获取配置

# 获取所有配置
GET /api/v1/settings

# 获取指定分类
GET /api/v1/settings?category=auth

# 响应示例
{
  "data": [
    {
      "key": "auth.reg.require_email",
      "value": "false",
      "type": "bool",
      "category": "auth",
      "desc": "注册是否要求邮箱"
    }
  ]
}

3.2 更新配置

# 批量更新（管理员权限）
PATCH /api/v1/settings

{
  "settings": [
    {"key": "auth.reg.require_email", "value": "true"},
    {"key": "auth.login.methods", "value": "[\"password\", \"email_code\"]"}
  ]
}

# 响应
{
  "message": "配置已更新",
  "updated": 2
}

---

四、配置优先级

当配置存在冲突时，优先级从高到低：

1. 环境变量 - 如 VBASE_DSN、VBASE_PORT
2. 配置文件 - config.yaml
3. 代码默认值 - cfg/cfg.go 中的默认值
4. 运行时配置 - 数据库 settings 表（仅适用于线上配置项）

---

五、部署建议

5.1 开发环境

# config.yaml
db: "sqlite"
dsn: "file:./dev.db?cache=shared"
redis:
  addr: "memory"

5.2 生产环境

# config.yaml（最小化）
dsn: ${DB_DSN}
redis:
  addr: ${REDIS_ADDR}
  password: ${REDIS_PASSWORD}
key: ${SECRET_KEY}  # 32位以上随机字符串
storage_path: /data/storage

线上配置通过管理后台设置：

1. 首次启动后访问 http://host:port/admin
2. 使用初始管理员账号登录
3. 进入「系统设置」配置邮件/短信/登录策略

---

六、变更日志

版本	变更内容
v1.0	分离本地配置和线上配置
v1.0	统一验证码模块（支持邮箱+短信）
v1.0	支持动态修改登录注册策略
v1.0	支持动态 OAuth Provider（内置模板+自定义接入）
v1.0	统一登录方式配置（密码/邮箱验证码/手机验证码/OAuth）