|
|
# 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 | 否 | 邮箱地址 |
|
|
|
|
|
|
**其他注意事项：**
|
|
|
- 仅在没有用户时生效，已有用户则跳过
|