|
|
# 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` 接口。
|