OneAuth/docs/configuration.md

# VBase 配置文档

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

## 配置分层

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

---

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

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

### 1.1 YAML 配置示例

```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（推荐用于生产）**

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

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

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

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

### 1.5 运行时钩子

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

---

## 二、线上配置（Settings）

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

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

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