Update README.md: add Server Configuration UI documentation and deployment guide

This commit is contained in:
wangdong 2026-07-28 01:28:57 +08:00
parent 75079c05d3
commit 8729500d2a

View File

@ -124,6 +124,7 @@ _✨ 通过标准的 OpenAI API 格式访问所有的大模型,开箱即用
+ 微信公众号授权(需要额外部署 [WeChat Server](https://github.com/songquanpeng/wechat-server))。 + 微信公众号授权(需要额外部署 [WeChat Server](https://github.com/songquanpeng/wechat-server))。
23. 支持主题切换,设置环境变量 `THEME` 即可,默认为 `default`,欢迎 PR 更多主题,具体参考[此处](./web/README.md)。 23. 支持主题切换,设置环境变量 `THEME` 即可,默认为 `default`,欢迎 PR 更多主题,具体参考[此处](./web/README.md)。
24. 配合 [Message Pusher](https://github.com/songquanpeng/message-pusher) 可将报警信息推送到多种 App 上。 24. 配合 [Message Pusher](https://github.com/songquanpeng/message-pusher) 可将报警信息推送到多种 App 上。
25. 支持**服务器配置管理界面**,所有环境变量和命令行参数均可通过 Web UI 查看和修改,无需再编辑命令行或 `.env` 文件。[详见此处](#服务器配置管理)。
## 部署 ## 部署
### 基于 Docker 进行部署 ### 基于 Docker 进行部署
@ -416,7 +417,99 @@ graph LR
29. `ENFORCE_INCLUDE_USAGE`:是否强制在 stream 模型下返回 usage默认不开启可选值为 `true``false` 29. `ENFORCE_INCLUDE_USAGE`:是否强制在 stream 模型下返回 usage默认不开启可选值为 `true``false`
30. `TEST_PROMPT`:测试模型时的用户 prompt默认为 `Print your model name exactly and do not output without any other text.` 30. `TEST_PROMPT`:测试模型时的用户 prompt默认为 `Print your model name exactly and do not output without any other text.`
### 命令行参数 ### 服务器配置管理
系统提供了一套完整的 Web UI 用于管理服务器配置,以 root 用户登录后进入 **设置 → 服务器配置** 即可查看和修改所有环境变量级配置。
#### 功能特性
- **分类展示**所有配置按类别分组展示数据库、Redis、性能调试、网络代理、速率限制、指标监控、其他设置
- **运行时配置**:部分配置可在运行时直接修改并立即生效,无需重启服务
- 例如:`DEBUG``DEBUG_SQL``MEMORY_CACHE_ENABLED``BATCH_UPDATE_ENABLED``THEME``RELAY_TIMEOUT`
- **需重启配置**数据库、Redis 等底层配置修改后需要重启服务才能生效,系统会显示"需要重启"标签提示
- 例如:`SQL_DSN``REDIS_CONN_STRING``PORT``SESSION_SECRET`
- **下载 .env**:一键导出当前所有配置为 `.env` 文件,方便备份或迁移
- **导入 .env**:上传 `.env` 配置文件到服务器,重启后自动生效
- **秘密值保护**:密码、密钥等敏感信息在 UI 中自动脱敏显示(如 `ab****cd`
#### 使用场景
**场景一:修改数据库配置**
1. 登录系统后进入 **设置 → 服务器配置 → 数据库**
2. 修改 `SQL_DSN` 为新的数据库连接字符串
3. 点击"下载 .env"按钮导出完整配置
4. 修改下载的 `.env` 文件中的 `SQL_DSN`
5. 回到页面点击"导入 .env"上传修改后的文件
6. 重启服务使配置生效
**场景二:运行时调整性能参数**
1. 进入 **设置 → 服务器配置 → 性能与调试**
2. 直接开关 `DEBUG``MEMORY_CACHE_ENABLED` 等开关
3. 修改 `BATCH_UPDATE_INTERVAL` 等数值参数后点击"保存"
4. 修改立即生效,无需重启
**场景三Docker 部署环境下的配置迁移**
1. 在旧容器中进入服务器配置页面,点击"下载 .env"
2. 获得完整的 `server-config.env` 文件
3. 启动新容器时挂载该文件:
```shell
docker run --name one-api -d -p 3000:3000 \
-v /path/to/server-config.env:/app/.env \
your-image:tag
```
4. 或其他方式,在导入后重启容器即可生效。注意如果容器没有挂载持久化卷,导入的 `.env` 文件会在容器重建后丢失,建议将文件保存到宿主机。
#### API 端点
新增的服务器配置 API 端点(需要 root 权限):
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/server/config/` | 获取所有服务器配置 |
| PUT | `/api/server/config/` | 更新运行时配置 |
| GET | `/api/server/config/download` | 下载 .env 配置文件 |
| POST | `/api/server/config/import` | 上传 .env 配置文件 |
#### 支持的配置项
| 类别 | 配置键 | 运行时修改 | 说明 |
|------|--------|-----------|------|
| 数据库 | `db_type` | ❌ 只读 | 当前数据库类型SQLite/MySQL/PostgreSQL自动检测 |
| 数据库 | `SQL_DSN` | ❌ 需重启 | 数据库连接字符串 |
| 数据库 | `LOG_SQL_DSN` | ❌ 需重启 | 日志数据库连接字符串 |
| 数据库 | `SQLITE_PATH` | ❌ 需重启 | SQLite 文件路径 |
| 数据库 | `SQLITE_BUSY_TIMEOUT` | ❌ 需重启 | SQLite 忙等待超时(毫秒) |
| 数据库 | `SQL_MAX_IDLE_CONNS` | ❌ 需重启 | 最大空闲连接数 |
| 数据库 | `SQL_MAX_OPEN_CONNS` | ❌ 需重启 | 最大打开连接数 |
| 数据库 | `SQL_MAX_LIFETIME` | ❌ 需重启 | 连接最大生命周期(秒) |
| Redis | `REDIS_CONN_STRING` | ❌ 需重启 | Redis 连接字符串 |
| Redis | `REDIS_PASSWORD` | ❌ 需重启 | Redis 密码 |
| Redis | `REDIS_MASTER_NAME` | ❌ 需重启 | 主节点名称(集群模式) |
| Redis | `SYNC_FREQUENCY` | ❌ 需重启 | 缓存同步频率(秒) |
| 性能 | `DEBUG` | ✅ 即时 | 调试模式 |
| 性能 | `DEBUG_SQL` | ✅ 即时 | SQL 调试日志 |
| 性能 | `MEMORY_CACHE_ENABLED` | ✅ 即时 | 内存缓存 |
| 性能 | `BATCH_UPDATE_ENABLED` | ✅ 即时 | 批量更新 |
| 性能 | `BATCH_UPDATE_INTERVAL` | ✅ 即时 | 批量更新间隔(秒) |
| 性能 | `GIN_MODE` | ❌ 需重启 | Gin 运行模式 |
| 网络 | `RELAY_TIMEOUT` | ✅ 即时 | 中转超时(秒) |
| 网络 | `RELAY_PROXY` | ✅ 即时 | 中转代理地址 |
| 网络 | `USER_CONTENT_REQUEST_PROXY` | ✅ 即时 | 用户内容代理 |
| 网络 | `USER_CONTENT_REQUEST_TIMEOUT` | ✅ 即时 | 内容请求超时(秒) |
| 网络 | `HTTPS_PROXY` | ✅ 即时 | HTTPS 代理 |
| 速率限制 | `GLOBAL_API_RATE_LIMIT` | ✅ 即时 | API 速率限制(次/3分钟 |
| 速率限制 | `GLOBAL_WEB_RATE_LIMIT` | ✅ 即时 | Web 速率限制(次/3分钟 |
| 指标 | `ENABLE_METRIC` | ✅ 即时 | 指标监控 |
| 指标 | `METRIC_QUEUE_SIZE` | ✅ 即时 | 指标队列大小 |
| 指标 | `METRIC_SUCCESS_RATE_THRESHOLD` | ✅ 即时 | 成功率阈值 |
| 指标 | `CHANNEL_TEST_FREQUENCY` | ❌ 需重启 | 渠道自动测试频率 |
| 其他 | `PORT` | ❌ 需重启 | 服务监听端口 |
| 其他 | `SESSION_SECRET` | ❌ 需重启 | Session 密钥 |
| 其他 | `NODE_TYPE` | ❌ 需重启 | 节点类型 |
| 其他 | `POLLING_INTERVAL` | ❌ 需重启 | 轮询间隔 |
| 其他 | `GEMINI_SAFETY_SETTING` | ✅ 即时 | Gemini 安全设置 |
| 其他 | `GEMINI_VERSION` | ✅ 即时 | Gemini API 版本 |
| 其他 | `THEME` | ✅ 即时 | 前端主题 |
| 其他 | `FRONTEND_BASE_URL` | ❌ 需重启 | 前端基础 URL |
| 其他 | `ONLY_ONE_LOG_FILE` | ✅ 即时 | 单日志文件 |
| 其他 | `ENFORCE_INCLUDE_USAGE` | ✅ 即时 | 强制返回 usage |
| 其他 | `TEST_PROMPT` | ✅ 即时 | 测试提示词 |
1. `--port <port_number>`: 指定服务器监听的端口号,默认为 `3000` 1. `--port <port_number>`: 指定服务器监听的端口号,默认为 `3000`
+ 例子:`--port 3000` + 例子:`--port 3000`
2. `--log-dir <log_dir>`: 指定日志文件夹,如果没有设置,默认保存至工作目录的 `logs` 文件夹下。 2. `--log-dir <log_dir>`: 指定日志文件夹,如果没有设置,默认保存至工作目录的 `logs` 文件夹下。