OneAuth/docs/configuration.md

# VBase 配置文档

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

## 配置分层

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

---

## 一、本地配置（Local Config）

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

### 1.1 配置项列表

```yaml
# 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` 均已配置

```yaml
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"]` | 密码登录支持的身份标识 |

**配置组合示例：**

```json
// 仅用户名登录（最小化配置）
{
  "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 配置示例：**

```json
{
  "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）

| 配置键 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `oauth.google.enabled` | bool | `false` | 启用 Google 登录 |
| `oauth.google.config` | json | `{}` | Google OAuth 配置 |
| `oauth.github.enabled` | bool | `false` | 启用 GitHub 登录 |
| `oauth.github.config` | json | `{}` | GitHub OAuth 配置 |
| `oauth.wechat.enabled` | bool | `false` | 启用微信登录 |
| `oauth.wechat.config` | json | `{}` | 微信 OAuth 配置 |

**Google OAuth 配置示例：**

```json
{
  "oauth.google.enabled": "true",
  "oauth.google.config": "{\"client_id\":\"xxx\",\"client_secret\":\"yyy\",\"scopes\":[\"openid\",\"email\",\"profile\"]}"
}
```

---

## 三、配置管理 API

### 3.1 获取配置

```http
# 获取所有配置
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 更新配置

```http
# 批量更新（管理员权限）
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 开发环境

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

### 5.2 生产环境

```yaml
# 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 | 支持动态修改登录注册策略 |