From cb20227c58f45499f5466fd9406991158cfd4a39 Mon Sep 17 00:00:00 2001 From: "CJACK." Date: Sun, 1 Mar 2026 05:32:23 +0800 Subject: [PATCH] docs: refresh onboarding and deployment documentation --- README.md | 1 + docs/README.md | 10 +- docs/api-usage.md | 65 ++++++++- docs/auth-rotation-cookie-refresh.md | 49 ++++--- docs/configuration-reference.md | 152 ++++++++++++++------- docs/deployment-and-operations.md | 189 +++++++++++++++++++++++++++ docs/development-and-release.md | 41 +++--- docs/quick-start.md | 77 ++++++++--- docs/troubleshooting.md | 91 ++++++++++--- 9 files changed, 541 insertions(+), 134 deletions(-) create mode 100644 docs/deployment-and-operations.md diff --git a/README.md b/README.md index 4814e38..f488c8f 100644 --- a/README.md +++ b/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) diff --git a/docs/README.md b/docs/README.md index 68ea919..ef820d0 100644 --- a/docs/README.md +++ b/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/` diff --git a/docs/api-usage.md b/docs/api-usage.md index 03d9aa6..dfba5a5 100644 --- a/docs/api-usage.md +++ b/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 `（推荐） - `X-API-Key: `（兼容） -密钥与状态可通过管理路由维护（见 `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 服务；若你要对外暴露，请在网关层做访问控制。 + diff --git a/docs/auth-rotation-cookie-refresh.md b/docs/auth-rotation-cookie-refresh.md index eebd8c5..d735dd6 100644 --- a/docs/auth-rotation-cookie-refresh.md +++ b/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_`：模型粒度阈值 -## 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。 diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md index 2b8276e..88b801a 100644 --- a/docs/configuration-reference.md +++ b/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_` | 空 | 某模型的专属阈值（高级用法）。 | +| `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` + diff --git a/docs/deployment-and-operations.md b/docs/deployment-and-operations.md new file mode 100644 index 0000000..e3eb1d3 --- /dev/null +++ b/docs/deployment-and-operations.md @@ -0,0 +1,189 @@ +# 部署与运维指南 + +本文档聚焦“可落地部署”和“稳定运行”两件事： + +- 本机/服务器长期运行 +- Docker 部署与升级 +- 日常运维检查与常见操作 + +--- + +## 1. 部署模式选择 + +### 模式 A：直接运行（推荐调试、灵活控制） + +适合：首次接入、需要手动登录、需要快速排障。 + +核心命令： + +```bash +poetry run python launch_camoufox.py --debug +poetry run python launch_camoufox.py --headless +``` + +### 模式 B：Docker（推荐稳定托管） + +适合：长期驻留、标准化部署、跨机器迁移。 + +核心命令： + +```bash +cd docker +docker compose up -d --build +``` + +--- + +## 2. 直接运行：生产化建议 + +## 2.1 必要目录与文件 + +确保以下目录存在（程序会自动创建，但建议提前理解结构）： + +- `auth_profiles/active/`：当前启用认证 +- `auth_profiles/saved/`：可切换认证池 +- `auth_profiles/emergency/`：紧急认证池 +- `logs/`：应用日志 + +## 2.2 启动参数建议 + +- 首次登录：`--debug` +- 日常运行：`--headless` +- 无 GUI Linux：`--virtual-display` +- 关闭流代理：`--stream-port 0` +- 指定端口：`--server-port 2048 --stream-port 3120` + +## 2.3 systemd（Linux）示例 + +可使用如下服务文件（示例路径 `/etc/systemd/system/aistudio-proxy.service`）： + +```ini +[Unit] +Description=AI Studio Proxy API +After=network.target + +[Service] +Type=simple +WorkingDirectory=/opt/AIstudioProxyAPI +ExecStart=/usr/bin/env poetry run python launch_camoufox.py --headless +Restart=always +RestartSec=5 +Environment=PYTHONUNBUFFERED=1 + +[Install] +WantedBy=multi-user.target +``` + +启用与查看： + +```bash +sudo systemctl daemon-reload +sudo systemctl enable --now aistudio-proxy +sudo systemctl status aistudio-proxy +journalctl -u aistudio-proxy -f +``` + +--- + +## 3. Docker 部署 + +## 3.1 关键前提 + +Docker 方式通常运行在无头模式，不适合做首次交互登录。因此请先准备认证文件： + +- 在宿主机本地执行一次 `--debug` 登录 +- 确保 `auth_profiles/active/*.json` 存在 + +## 3.2 首次启动 + +```bash +cd docker +cp .env.docker .env +# 编辑 docker/.env + +docker compose up -d --build +``` + +## 3.3 运行与检查 + +```bash +docker compose ps +docker compose logs -f +curl http://127.0.0.1:2048/health +``` + +## 3.4 常用维护命令 + +```bash +# 重启 +docker compose restart + +# 停止 +docker compose down + +# 更新（项目提供脚本） +bash update.sh + +# 进入容器排查 +docker compose exec ai-studio-proxy /bin/bash +``` + +--- + +## 4. 生产配置建议（重点） + +## 4.1 网络与代理 + +- 优先使用 `UNIFIED_PROXY_CONFIG` +- 仅在兼容场景下再使用 `HTTP_PROXY` / `HTTPS_PROXY` +- 有内网例外地址时补充 `NO_PROXY` + +## 4.2 稳定性参数 + +- `RESPONSE_COMPLETION_TIMEOUT` +- `SILENCE_TIMEOUT_MS` +- `WAIT_FOR_ELEMENT_TIMEOUT_MS` +- `STREAM_MAX_INITIAL_ERRORS` + +建议逐步小幅调整，并通过 `logs/` 观察变化。 + +## 4.3 认证与轮转 + +推荐开启： + +- `AUTO_ROTATE_AUTH_PROFILE=true` +- `COOKIE_REFRESH_ENABLED=true` +- `COOKIE_REFRESH_ON_SHUTDOWN=true` + +如配额波动明显，再结合： + +- `QUOTA_SOFT_LIMIT` +- `QUOTA_HARD_LIMIT` +- `QUOTA_LIMIT_`（按模型单独阈值） + +--- + +## 5. 运维巡检清单 + +- `/health` 是否为 200 +- `/v1/models` 是否返回有效模型 +- 队列积压是否异常：`/v1/queue` +- 浏览器与页面状态是否 ready（`/health.details`） +- 日志中是否持续出现 quota / reconnect / timeout + +建议至少做一个简单定时巡检： + +```bash +curl -sf http://127.0.0.1:2048/health >/dev/null || echo "health check failed" +``` + +--- + +## 6. 版本升级建议流程 + +1. 备份 `.env`、`auth_profiles/`。 +2. 拉取新代码并更新依赖。 +3. 先在 `--debug` 或测试环境验证关键模型。 +4. 再切到生产 headless。 +5. 观察 15~30 分钟日志后再宣告升级完成。 + diff --git a/docs/development-and-release.md b/docs/development-and-release.md index 83706fa..4148e95 100644 --- a/docs/development-and-release.md +++ b/docs/development-and-release.md @@ -1,6 +1,6 @@ # 开发、测试与发布 -## 本地开发 +## 1. 本地开发 ```bash poetry install --with dev @@ -9,33 +9,34 @@ poetry run pyright poetry run pytest ``` -前端： +## 2. 常用测试建议 -```bash -cd static/frontend -npm ci -npm run build -npm run test -``` +- 先跑变更相关测试（模块级） +- 再跑全量 `pytest` +- 变更配置/轮转/队列逻辑时，优先覆盖对应 `tests/test_*` 用例 -## 推荐测试分层 +## 3. 调试建议 -- 单元与组件测试：`pytest` 默认集合 -- 关键集成验证：`tests/integration/` 相关用例 -- 前端构建与基础交互冒烟 +- 启动模式：`poetry run python launch_camoufox.py --debug` +- API 观察：`/health`、`/v1/queue`、`/ws/logs` +- Function Calling 排障：开启 `FUNCTION_CALLING_DEBUG` + 精确 `FC_DEBUG_*` -## GitHub Actions +## 4. CI/CD（仓库工作流） -- `PR Check`：代码质量与测试检查 -- `Release`： - - tag 触发稳定版 - - main push 触发 nightly - - 支持手动输入版本发布 -- `Sync with Upstream`：从 `CJackHwang/AIstudioProxyAPI` 同步并自动建 PR +- PR 检查：lint + type check + tests +- Release：支持 tag / nightly / 手动触发 +- Upstream Sync：同步上游并自动建 PR -## 发布示例 +## 5. 发布最小流程（建议） ```bash +# 1) 保证主分支干净并通过测试 +poetry run ruff check . +poetry run pyright +poetry run pytest + +# 2) 打 tag git tag v0.1.0 git push origin v0.1.0 ``` + diff --git a/docs/quick-start.md b/docs/quick-start.md index 56ab9f3..c09aa39 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -1,13 +1,15 @@ # 快速开始 -## 环境要求 +> 目标：用最短路径把服务跑起来，并完成一次可用请求。 -- Python `>=3.9,<4.0` +## 1. 运行前确认 + +- Python `>=3.9,<4.0`（推荐 3.10/3.11） - Poetry -- Node.js（仅前端开发/构建需要） -- 可访问 Google AI Studio 的网络环境 +- 可访问 Google AI Studio 的网络（如需要可配置 `UNIFIED_PROXY_CONFIG`） +- 首次登录建议有图形界面（或使用你已经准备好的 `auth_profiles/active/*.json`） -## 安装 +## 2. 安装依赖 ```bash git clone https://github.com/CJackHwang/AIstudioProxyAPI.git @@ -15,37 +17,80 @@ cd AIstudioProxyAPI poetry install --with dev ``` -## 初始化配置 +> 可选：如果你希望用项目脚本一键安装，可使用 `scripts/install.sh`（Linux/macOS）或 `scripts/install.ps1`（Windows）。 + +## 3. 初始化配置 ```bash cp .env.example .env ``` -建议先配置： +建议至少先检查这些配置： -- `PORT=2048` -- `STREAM_PORT=3120`（不需要流式代理可设为 `0`） -- `UNIFIED_PROXY_CONFIG`（按需） -- `LAUNCH_MODE=debug`（首次认证） -- `AUTO_SAVE_AUTH=true`（首次认证可开启） +- `PORT`：主 API 端口（默认 `2048`） +- `STREAM_PORT`：流代理端口（默认 `3120`，设 `0` 可关闭） +- `UNIFIED_PROXY_CONFIG`：统一代理（有网络限制时必填） +- `LAUNCH_MODE`：建议首次使用 `debug` +- `AUTO_SAVE_AUTH`：首次登录调试时可设为 `true` -## 启动 +## 4. 首次认证（推荐流程） -首次认证： +首次运行建议用可见浏览器进行登录并保存认证态： ```bash poetry run python launch_camoufox.py --debug ``` -完成认证文件保存后，日常运行： +登录成功后，确认 `auth_profiles/active/` 下已有可用 `.json` 文件。后续可切换为无头模式。 + +## 5. 日常运行 ```bash poetry run python launch_camoufox.py --headless ``` -## 最小验证 +Linux 无桌面环境可选： + +```bash +poetry run python launch_camoufox.py --virtual-display +``` + +## 6. 最小可用验证 ```bash +# 健康检查 curl http://127.0.0.1:2048/health + +# 模型列表 curl http://127.0.0.1:2048/v1/models + +# 聊天补全 +curl -X POST http://127.0.0.1:2048/v1/chat/completions \ + -H "Content-Type: application/json" \ + -d '{"model":"gemini-2.5-pro","messages":[{"role":"user","content":"你好"}]}' ``` + +## 7. Docker 快速路径（已有认证文件时） + +1. 确保宿主机已有 `auth_profiles/active/*.json`。 +2. 进入 Docker 目录并准备配置： + +```bash +cd docker +cp .env.docker .env +``` + +3. 启动： + +```bash +docker compose up -d --build +``` + +4. 检查： + +```bash +docker compose ps +docker compose logs -f +``` + +> 详细部署、更新与排障见 `docs/deployment-and-operations.md`。 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index a7ccdeb..8c0afc5 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,34 +1,83 @@ # 排障指南 -## 1. 启动后无法连接 AI Studio +## 1. 启动阶段失败 -排查顺序： +### 现象 A：浏览器相关初始化失败 -1. 检查代理配置：`UNIFIED_PROXY_CONFIG`。 -2. 检查认证文件是否有效：`auth_profiles/active/`。 -3. 用 `--debug` 复现，确认页面可打开并正常提交。 +优先检查： -## 2. `/v1/chat/completions` 超时 +1. `CAMOUFOX_WS_ENDPOINT` 是否被 launcher 正确注入（或你是否手动提供了有效地址） +2. 网络与代理配置（`UNIFIED_PROXY_CONFIG`） +3. 是否已有可用认证文件（`auth_profiles/active/*.json`） -建议： +### 现象 B：`/health` 一直是 503 -- 调整 `RESPONSE_COMPLETION_TIMEOUT` 与 `SILENCE_TIMEOUT_MS`。 -- 检查模型是否可用、页面是否卡住。 -- 查看 `logs/` 与 `errors_py/` 日志。 +查看响应中的 `details`： -## 3. 函数调用异常 +- `is_playwright_ready` +- `is_browser_connected` +- `is_page_ready` +- `workerRunning` -- 将 `FUNCTION_CALLING_MODE` 切换到 `auto`。 -- 开启 `FUNCTION_CALLING_DEBUG=true` 与对应 `FC_DEBUG_*` 模块。 -- 检查 `config/selectors.py` 是否需要更新到新 UI。 +如果 `launchMode=direct_debug_no_browser`，browser/page 不是硬依赖。 -## 4. 认证轮转行为不符合预期 +--- -- 检查 `AUTO_ROTATE_AUTH_PROFILE` 与 `AUTO_AUTH_ROTATION_ON_STARTUP`。 -- 检查 `QUOTA_SOFT_LIMIT` / `QUOTA_HARD_LIMIT`。 -- 确保存在可轮转 profile。 +## 2. 聊天接口超时或挂起 -## 5. GUI 启动异常 +### 排查步骤 + +1. 检查请求是否持续积压：`GET /v1/queue` +2. 查看日志中的 timeout/silence 关键字 +3. 调整超时参数： + - `RESPONSE_COMPLETION_TIMEOUT` + - `SILENCE_TIMEOUT_MS` + - `WAIT_FOR_ELEMENT_TIMEOUT_MS` +4. 在 debug 模式观察 AI Studio 页面是否卡住 + +--- + +## 3. Function Calling 异常 + +建议顺序： + +1. `FUNCTION_CALLING_MODE=auto` +2. 开启 `FUNCTION_CALLING_DEBUG=true` +3. 仅打开必要 `FC_DEBUG_*` 模块（先 `ORCHESTRATOR/UI/WIRE`） +4. 观察 `logs/fc_debug/` 具体报错 + +如是 UI 结构变化导致，可核查 `config/selectors.py` 相关选择器。 + +--- + +## 4. 认证轮转不生效 / 频繁触发 + +检查： + +- `AUTO_ROTATE_AUTH_PROFILE` +- `AUTO_AUTH_ROTATION_ON_STARTUP` +- `QUOTA_SOFT_LIMIT` / `QUOTA_HARD_LIMIT` +- `saved/` 或 `emergency/` 是否有可用 profile + +如果“轮转后仍很快触发”，优先确认账号是否都已接近配额。 + +--- + +## 5. Docker 常见问题 + +### 认证文件问题 + +容器无头运行时不能完成交互登录。必须先在宿主机生成认证文件，再挂载 `auth_profiles/`。 + +### 健康检查失败 + +```bash +docker compose logs -f +docker compose exec ai-studio-proxy /bin/bash +curl -v http://127.0.0.1:2048/health +``` + +### 日志/权限问题 + +如果你挂载了 `../logs:/app/logs`，需保证目录可写。 -- 检查 `customtkinter`、`pillow` 是否安装。 -- 通过 CLI 先验证服务可启动，再回到 GUI。