docs: refresh onboarding and add deployment & operations guide

README.md

@@ -147,6 +147,7 @@ cp .env.example .env
 
 - [文档总览](docs/README.md)
 - [快速开始](docs/quick-start.md)
+- [部署与运维指南](docs/deployment-and-operations.md)
 - [API 使用说明](docs/api-usage.md)
 - [函数调用模式](docs/function-calling.md)
 - [认证轮转与 Cookie 刷新](docs/auth-rotation-cookie-refresh.md)

docs/README.md

@@ -1,14 +1,15 @@
 # 文档总览
 
-本目录为当前代码实现对应的中文文档。
+本目录文档以当前代码实现为准，重点覆盖：上手、部署、配置、运维与开发。
 
 ## 文档索引
 
 - [快速开始](quick-start.md)
+- [部署与运维指南](deployment-and-operations.md)
 - [配置参考](configuration-reference.md)
-- [认证轮转与 Cookie 刷新](auth-rotation-cookie-refresh.md)
-- [函数调用模式](function-calling.md)
 - [API 使用说明](api-usage.md)
+- [函数调用模式](function-calling.md)
+- [认证轮转与 Cookie 刷新](auth-rotation-cookie-refresh.md)
 - [排障指南](troubleshooting.md)
 - [开发、测试与发布](development-and-release.md)
 - [旧文档迁移说明](migration-notes.md)
@@ -18,4 +19,5 @@
 - 后端服务：`api_utils/`、`stream/`
 - 浏览器自动化：`browser_utils/`
 - 配置：`config/` 与 `.env`
-- UI：`static/frontend/` 与 `gui/`
+- 启动器：`launch_camoufox.py`、`gui/`
+- Docker：`docker/`

docs/api-usage.md

@@ -1,18 +1,22 @@
 # API 使用说明
 
-## 健康检查
+## 1. 核心 OpenAI 兼容接口
+
+## 1.1 健康检查
 
 ```bash
 curl http://127.0.0.1:2048/health
 ```
 
-## 列出模型
+返回 `200` 表示核心状态正常；`503` 时请关注 `details` 字段中的 browser/page/worker 状态。
+
+## 1.2 模型列表
 
 ```bash
 curl http://127.0.0.1:2048/v1/models
 ```
 
-## 对话补全（非流式）
+## 1.3 聊天补全（非流式）
 
 ```bash
 curl -X POST http://127.0.0.1:2048/v1/chat/completions \
@@ -24,7 +28,7 @@ curl -X POST http://127.0.0.1:2048/v1/chat/completions \
   }'
 ```
 
-## 对话补全（流式）
+## 1.4 聊天补全（流式）
 
 ```bash
 curl -X POST http://127.0.0.1:2048/v1/chat/completions \
@@ -36,11 +40,58 @@ curl -X POST http://127.0.0.1:2048/v1/chat/completions \
   }' --no-buffer
 ```
 
-## API Key 鉴权
+---
+
+## 2. API Key 鉴权
 
-支持：
+当密钥文件中存在有效 key 时，`/v1/*`（除公开白名单）将开启鉴权。
+
+支持两种请求头：
 
 - `Authorization: Bearer <token>`（推荐）
 - `X-API-Key: <token>`（兼容）
 
-密钥与状态可通过管理路由维护（见 `api_utils/routers/api_keys.py`）。
+管理接口：
+
+- `GET /api/keys`：查询密钥
+- `POST /api/keys`：新增密钥
+- `POST /api/keys/test`：测试密钥
+- `DELETE /api/keys`：删除密钥
+
+---
+
+## 3. 队列与请求控制
+
+- `GET /v1/queue`：查看排队请求、等待时长、是否被取消
+- `POST /v1/cancel/{req_id}`：取消排队中的请求
+
+示例：
+
+```bash
+curl http://127.0.0.1:2048/v1/queue
+curl -X POST http://127.0.0.1:2048/v1/cancel/abc1234
+```
+
+---
+
+## 4. 服务端管理接口（Web UI 同源使用）
+
+- `GET /api/info`
+- `GET /api/server/status`
+- `POST /api/server/restart`
+- `GET/POST /api/proxy/config`
+- `POST /api/proxy/test`
+- `GET/POST /api/helper/config`
+- `GET/POST /api/ports/config`
+- `GET /api/ports/status`
+- `POST /api/ports/kill`
+- `GET /api/auth/files`
+- `GET /api/auth/active`
+- `POST /api/auth/activate`
+- `DELETE /api/auth/deactivate`
+- `GET /api/model-capabilities`
+- `GET /api/model-capabilities/{model_id}`
+- `WS /ws/logs`
+
+> 这些接口主要为内置管理 UI 服务；若你要对外暴露，请在网关层做访问控制。
+

docs/auth-rotation-cookie-refresh.md

@@ -1,36 +1,51 @@
 # 认证轮转与 Cookie 刷新
 
-## 认证目录
+## 1. 目录角色
 
-- `auth_profiles/active/`：当前可用 profile。
-- `auth_profiles/saved/`：历史保存 profile。
-- `auth_profiles/emergency/`：应急 profile。
+- `auth_profiles/active/`：当前生效认证（运行时读取）
+- `auth_profiles/saved/`：可切换认证池
+- `auth_profiles/emergency/`：应急认证池
 
-## 推荐流程
+通常建议：
 
-1. 使用 `--debug` 完成登录。
-2. 将保存的 profile 放入 `active/`。
-3. 生产环境使用 `--headless`。
+1. 先在 debug 下登录并沉淀多个可用账号到 `saved/`
+2. 生产运行时确保 `active/` 始终至少有一个可用 profile
 
-## 自动轮转策略
+## 2. 推荐上线流程
 
-相关配置：
+1. `--debug` 完成登录。
+2. 验证 `/v1/models`、`/v1/chat/completions` 正常。
+3. 将稳定账号纳入 `saved/` 池。
+4. 切换 `--headless` 长期运行。
+
+## 3. 自动轮转策略
+
+关键配置：
 
 - `AUTO_ROTATE_AUTH_PROFILE=true`
 - `AUTO_AUTH_ROTATION_ON_STARTUP=true|false`
-- `QUOTA_SOFT_LIMIT`：触发“当前请求完成后轮转”
-- `QUOTA_HARD_LIMIT`：触发更强保护策略
+- `QUOTA_SOFT_LIMIT`：软阈值（倾向“当前请求结束后轮转”）
+- `QUOTA_HARD_LIMIT`：硬阈值（触发更强恢复策略）
+- `QUOTA_LIMIT_<MODEL_ID>`：模型粒度阈值
 
-## Cookie 自动刷新
+## 4. Cookie 自动刷新
 
-建议在长期运行场景开启：
+建议长期运行时开启：
 
 - `COOKIE_REFRESH_ENABLED=true`
 - `COOKIE_REFRESH_INTERVAL_SECONDS=1800`
 - `COOKIE_REFRESH_ON_REQUEST_ENABLED=true`
+- `COOKIE_REFRESH_REQUEST_INTERVAL=10`
 - `COOKIE_REFRESH_ON_SHUTDOWN=true`
 
-作用：
+效果：
+
+- 降低长期运行下 cookie 过期风险
+- 关停前自动落盘，减少重启失效
+
+## 5. 管理接口（便于运维）
+
+- `GET /api/auth/files`：列出 saved 文件与当前 active
+- `POST /api/auth/activate`：切换某个认证文件为 active
+- `DELETE /api/auth/deactivate`：清空 active
 
-- 减少认证过期导致的可用性波动。
-- 关闭服务时自动持久化最新 cookie。

docs/configuration-reference.md

@@ -1,61 +1,115 @@
 # 配置参考
 
-配置入口：`.env`（模板见 `.env.example`）。
-
-## 1. 端口与代理
-
-- `PORT`：主 API 端口。
-- `STREAM_PORT`：流式代理端口，`0` 为关闭。
-- `UNIFIED_PROXY_CONFIG`：统一代理配置，优先级最高。
-- `HTTP_PROXY` / `HTTPS_PROXY`：兼容旧代理配置。
-- `NO_PROXY`：代理绕过规则。
-
-## 2. 日志
-
-- `SERVER_LOG_LEVEL`：日志级别。
-- `SERVER_REDIRECT_PRINT`：是否重定向 `print`。
-- `JSON_LOGS`：JSON 日志输出。
-- `LOG_FILE_MAX_BYTES` / `LOG_FILE_BACKUP_COUNT`：日志滚动策略。
-
-## 3. 认证与轮转
-
-- `AUTO_SAVE_AUTH`：debug 登录后自动保存认证。
-- `AUTO_ROTATE_AUTH_PROFILE`：配额异常时自动轮转认证 profile。
-- `AUTO_AUTH_ROTATION_ON_STARTUP`：启动时自动选择 profile。
-- `QUOTA_SOFT_LIMIT` / `QUOTA_HARD_LIMIT`：轮转阈值。
-
-## 4. 浏览器与模型
-
-- `LAUNCH_MODE`：`normal` / `debug` / `headless` / `virtual_display`。
-- `CAMOUFOX_WS_ENDPOINT`：连接外部浏览器实例。
-- `ONLY_COLLECT_CURRENT_USER_ATTACHMENTS`：附件收集策略。
-
-## 5. 函数调用
-
-- `FUNCTION_CALLING_MODE`：`auto` / `native` / `emulated`。
-- `FUNCTION_CALLING_NATIVE_FALLBACK`：native 失败是否回退。
-- `FUNCTION_CALLING_UI_TIMEOUT`：UI 操作超时。
-- `FUNCTION_CALLING_CACHE_ENABLED`：启用 FC 缓存。
-
-## 6. Cookie 刷新
-
-- `COOKIE_REFRESH_ENABLED`
-- `COOKIE_REFRESH_INTERVAL_SECONDS`
-- `COOKIE_REFRESH_ON_REQUEST_ENABLED`
-- `COOKIE_REFRESH_REQUEST_INTERVAL`
-- `COOKIE_REFRESH_ON_SHUTDOWN`
-
-## 7. 超时与稳定性
+配置文件入口：项目根目录 `.env`（可由 `.env.example` 复制）。
+
+> 说明：下表“默认值”以 `.env.example` 为主；若未设置，代码里也有兜底值，少数项可能不同（例如 `FUNCTION_CALLING_MODE`）。
+
+## 1. 网络与端口
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `PORT` | `2048` | FastAPI 主服务端口。 |
+| `STREAM_PORT` | `3120` | 流代理端口；`0` 表示关闭流代理。 |
+| `DEFAULT_FASTAPI_PORT` | `2048` | 启动器默认端口（UI/CLI 提示用）。 |
+| `DEFAULT_CAMOUFOX_PORT` | `9222` | 启动器默认 Camoufox 调试端口。 |
+| `UNIFIED_PROXY_CONFIG` | 空 | 统一代理入口，优先级高于 HTTP/HTTPS 代理。 |
+| `HTTP_PROXY` / `HTTPS_PROXY` | 空 | 兼容代理配置。 |
+| `NO_PROXY` | 空 | 代理绕过规则。 |
+
+## 2. 启动与浏览器
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `LAUNCH_MODE` | `normal` | 启动模式：`normal/debug/headless/virtual_display/direct_debug_no_browser`。 |
+| `CAMOUFOX_WS_ENDPOINT` | 空 | 外部浏览器 WebSocket 地址；常规启动时由 launcher 注入。 |
+| `DIRECT_LAUNCH` | `false` | 跳过菜单直接按配置启动。 |
+| `ENDPOINT_CAPTURE_TIMEOUT` | `45` | 捕获浏览器 ws 端点超时时间（秒）。 |
+| `ONLY_COLLECT_CURRENT_USER_ATTACHMENTS` | `false` | 限制附件收集范围。 |
+
+## 3. 认证、轮转、Cookie 刷新
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `AUTO_SAVE_AUTH` | `false` | Debug 登录成功后自动保存认证。 |
+| `AUTH_SAVE_TIMEOUT` | `30` | 保存认证等待超时（秒）。 |
+| `AUTO_ROTATE_AUTH_PROFILE` | `true` | 配额/异常时自动轮转认证。 |
+| `AUTO_AUTH_ROTATION_ON_STARTUP` | `false` | 启动时自动选取可用 profile。 |
+| `AUTO_CONFIRM_LOGIN` | `true` | 自动确认登录流程。 |
+| `QUOTA_SOFT_LIMIT` | `850000` | 软阈值（请求完成后轮转）。 |
+| `QUOTA_HARD_LIMIT` | `950000` | 硬阈值（更强保护/更快触发恢复）。 |
+| `QUOTA_LIMIT_<MODEL_ID>` | 空 | 某模型的专属阈值（高级用法）。 |
+| `COOKIE_REFRESH_ENABLED` | `true` | 启用周期性 cookie 刷新。 |
+| `COOKIE_REFRESH_INTERVAL_SECONDS` | `1800` | 周期刷新间隔（秒）。 |
+| `COOKIE_REFRESH_ON_REQUEST_ENABLED` | `true` | 按请求计数触发刷新。 |
+| `COOKIE_REFRESH_REQUEST_INTERVAL` | `10` | 每成功 N 次请求触发保存。 |
+| `COOKIE_REFRESH_ON_SHUTDOWN` | `true` | 优雅关停时保存 cookie。 |
+
+## 4. API 默认采样与能力开关
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `DEFAULT_TEMPERATURE` | `1.0` | 默认温度。 |
+| `DEFAULT_MAX_OUTPUT_TOKENS` | `65536` | 默认输出 token 上限。 |
+| `DEFAULT_TOP_P` | `0.95` | 默认 `top_p`。 |
+| `DEFAULT_STOP_SEQUENCES` | `["User:"]` | 默认停用序列（JSON 字符串）。 |
+| `ENABLE_THINKING_BUDGET` | `true` | 启用 thinking budget。 |
+| `DEFAULT_THINKING_BUDGET` | `8192` | 默认 thinking budget。 |
+| `THINKING_BUDGET_LOW/MEDIUM/HIGH` | `10923/21845/32768` | 分级预算。 |
+| `DEFAULT_THINKING_LEVEL_PRO` | `high` | Pro 系列默认思考等级。 |
+| `DEFAULT_THINKING_LEVEL_FLASH` | `high` | Flash 系列默认思考等级。 |
+| `DISABLE_THINKING_BUDGET_ON_STREAMING_DISABLE` | `false` | 关闭 stream 时是否自动关闭 thinking budget。 |
+| `ENABLE_GOOGLE_SEARCH` | `false` | 开启 Google Search 能力映射。 |
+| `ENABLE_URL_CONTEXT` | `false` | 开启 URL Context 能力映射。 |
+
+## 5. Function Calling（核心）
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `FUNCTION_CALLING_MODE` | `.env` 为 `auto` | 模式：`auto/native/emulated`（代码兜底为 `emulated`）。 |
+| `FUNCTION_CALLING_NATIVE_FALLBACK` | `true` | native 失败后回退 emulated。 |
+| `FUNCTION_CALLING_UI_TIMEOUT` | `10000` | UI 操作超时（毫秒）。 |
+| `FUNCTION_CALLING_NATIVE_RETRY_COUNT` | `3` | native 重试次数。 |
+| `FUNCTION_CALLING_CLEAR_BETWEEN_REQUESTS` | `true` | 请求间是否清理函数定义。 |
+| `FUNCTION_CALLING_CACHE_ENABLED` | `true` | 开启 FC 状态缓存。 |
+| `FUNCTION_CALLING_CACHE_TTL` | `0` | 缓存 TTL（0 表示会话内不过期）。 |
+| `FUNCTION_CALLING_THOUGHT_SIGNATURE` | `true` | Gemini 3 兼容字段。 |
+| `FUNCTION_CALLING_UPPERCASE_TYPES` | `false` | schema type 大写兼容模式。 |
+
+调试相关：
+
+- `FUNCTION_CALLING_DEBUG`
+- `FC_DEBUG_*`（模块开关、级别、截断、合并日志）
+
+## 6. 日志与诊断
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `SERVER_LOG_LEVEL` | `INFO` | 主日志级别。 |
+| `SERVER_REDIRECT_PRINT` | `false` | 是否将 `print` 重定向到日志。 |
+| `DEBUG_LOGS_ENABLED` | `false` | DEBUG 级日志总开关。 |
+| `TRACE_LOGS_ENABLED` | `false` | TRACE 级日志总开关。 |
+| `JSON_LOGS` | `false` | JSON 结构化日志。 |
+| `LOG_FILE_MAX_BYTES` | `10485760` | 日志切割大小。 |
+| `LOG_FILE_BACKUP_COUNT` | `5` | 滚动日志保留份数。 |
+
+## 7. 超时与稳态参数
+
+常用项（按需调优）：
 
 - `RESPONSE_COMPLETION_TIMEOUT`
 - `SILENCE_TIMEOUT_MS`
 - `CLICK_TIMEOUT_MS`
 - `WAIT_FOR_ELEMENT_TIMEOUT_MS`
-- `STREAM_MAX_INITIAL_ERRORS` 等流式抑制参数。
+- `STREAM_MAX_INITIAL_ERRORS`
+- `STREAM_WARNING_INTERVAL_AFTER_SUPPRESS`
+- `STREAM_SUPPRESS_DURATION_AFTER_INITIAL_BURST`
+
+## 8. GUI 相关
 
-## 8. GUI 与前端
+仅 GUI 启动器会使用：
 
 - `GUI_DEFAULT_PROXY_ADDRESS`
 - `GUI_DEFAULT_STREAM_PORT`
 - `GUI_DEFAULT_HELPER_ENDPOINT`
-- `SKIP_FRONTEND_BUILD`：无 Node 环境时可跳过构建检查。
+- `SKIP_FRONTEND_BUILD`
+