OptimusX
/
OneAuth
mirror of https://github.com/veypi/OneAuth.git
3
0
Fork 0
Code Issues Projects Releases Wiki Activity

add configuration.md

Browse Source
master
veypi 1 week ago
parent fa3719cf7d
commit 04997496d1
1 changed files with 338 additions and 0 deletions
Show Stats Download Patch File Download Diff File

338
docs/configuration.md
Unescape Escape View File

@ -0,0 +1,338 @@
# 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 | 支持动态修改登录注册策略 |
Write Preview
Loading…
Cancel
Save