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	否	邮箱地址

其他注意事项：

• 仅在没有用户时生效，已有用户则跳过