OneAuth/docs/configuration.md

VBase 配置文档

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

配置分层

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

---

一、本地配置（Local Config）

存储在 cfg/cfg.go，仅包含系统启动必需的配置项。默认使用 SQLite 内存数据库，无需任何外部依赖即可运行。

1.1 YAML 配置示例

# config.yaml 示例

db:
  type: "sqlite"                    # sqlite / mysql / postgres
  dsn: "/tmp/vbase.db"             # 数据库连接字符串
  prefix: "vb_"                    # 表名前缀

redis:
  addr: "memory"                   # memory（内存模式）或 redis://localhost:6379
  password: ""
  db: 0

key: "your-secret-key-change-in-production-min-32-characters"

jwt:
  secret: ""                       # JWT 密钥（为空则使用 Key）
  access_expiry: 900               # Access Token 有效期（秒），默认 15m
  refresh_expiry: 2592000          # Refresh Token 有效期（秒），默认 30d
  issuer: "vbase"                  # JWT 签发者
  cookie_path: "/"                 # Cookie Path，默认 / 全站
  cookie_prefix: "vb_"             # Cookie Key 前缀

init_admin:
  username: "admin"                # 管理员用户名
  password: ""                     # 密码（为空则首注成为 admin）
  email: "admin@example.com"

1.2 配置项说明

配置项	类型	必填	默认值	说明
db.type	string	否	sqlite	数据库类型：sqlite / mysql / postgres
db.dsn	string	否	/tmp/vbase.db	数据库连接字符串
db.prefix	string	否	vb_	表名前缀
redis.addr	string	否	memory	Redis 地址，memory 使用内存模式
redis.password	string	否	—	Redis 密码
redis.db	int	否	0	Redis 数据库编号
key	string	是	—	系统密钥，用于加密敏感数据（建议 32 位以上）
jwt.secret	string	否	—	JWT 密钥（为空则使用 key）
jwt.access_expiry	duration	否	15m	Access Token 有效期
jwt.refresh_expiry	duration	否	30d	Refresh Token 有效期
jwt.issuer	string	否	vbase	JWT 签发者名称
jwt.cookie_path	string	否	/	Cookie Path 限定路径
jwt.cookie_prefix	string	否	vb_	Cookie Key 前缀

1.3 Token 传送方式

VBase 支持三种 Token 提取方式，优先级从高到低：

1. Cookie（HttpOnly，浏览器自动携带）：Key 为 {cookie_prefix}access
2. Authorization Header：Bearer <token>
3. Query 参数：?access_token=<token>

1.4 初始管理员配置

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

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

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

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

启动时自动创建管理员，后续注册的用户均为普通 user。

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

当 init_admin.password 为空时，第一个注册用户自动被授予 admin 角色。

1.5 运行时钩子

// OnUserCreate 用户创建成功后的回调钩子
// 可用于发送欢迎邮件、初始化用户资源等
cfg.OnUserCreate = func(userID string) error {
    // 自定义逻辑
    return nil
}

---

二、线上配置（Settings）

线上配置存储在数据库 settings 表中，通过管理后台或 API 实时修改，无需重启。

包括：应用名称、登录方式、密码字段配置、验证码开关、邮件/SMS 开关、OAuth 提供商等。

详见 API 的 /api/settings 和 /api/info 接口。