diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..42d88e4
--- /dev/null
+++ b/docs/configuration.md
@@ -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 | 支持动态修改登录注册策略 |