# 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 | 否 | 邮箱地址 |

**其他注意事项：**
- 仅在没有用户时生效，已有用户则跳过