| # External API 网站内管理与 API Key 生成方案 |
|
|
| 本文档是**内部实现方案文档**，用于后续开发“在网站设置页直接启用/关闭 External API，并生成/管理 API Key”功能。 |
|
|
| 这不是给第三方调用方看的文档。 |
| 第三方对接请看： |
|
|
| - [第三方技术对接文档](third-party-integration-guide.md) |
| - [External API 调用示例](external-api-examples.md) |
| - [Temp Mail 域名池与外部注册 API 说明](temp-mail-external-api.md) |
|
|
| --- |
|
|
| ## 1. 目标 |
|
|
| 在网站设置页中直接提供一块 **External API 管理区域**，让管理员可以： |
|
|
| - 启用 / 关闭 External API |
| - 查看当前是否已配置 API Key |
| - 一键生成新的 API Key |
| - 手动设置自定义 API Key |
| - 复制对接所需的 Base URL / Header / 文案 |
|
|
| 目标结果是： |
|
|
| 1. 管理员不需要手动改数据库或配置文件 |
| 2. 第三方对接信息可以直接从网站界面获得 |
| 3. API Key 的展示与重置行为可控，不泄漏旧 Key |
|
|
| --- |
|
|
| ## 2. 当前基础 |
|
|
| 项目当前已经具备以下底座能力： |
|
|
| ### 2.1 配置项已存在 |
|
|
| 系统配置中已经有： |
|
|
| - `external_api_enabled` |
| - `external_api_key` |
|
|
| ### 2.2 外部鉴权已存在 |
|
|
| 当前 External API 鉴权已经生效，固定使用： |
|
|
| ```http |
| X-API-Key: <api_key> |
| ``` |
|
|
| 并读取 `external_api_enabled`、`external_api_key` 进行校验。 |
|
|
| ### 2.3 设置页架构已存在 |
|
|
| 当前设置页已经采用成熟的三层模式： |
|
|
| - `templates/settings.html` |
| - `static/js/settings.js` |
| - `src/web/routes/settings.py` |
|
|
| 因此本次不是重做设置系统，而是在现有模式上新增一个“外部 API”分区。 |
|
|
| --- |
|
|
| ## 3. 页面设计 |
|
|
| ### 3.1 新增标签页 |
|
|
| 在设置页 tabs 中新增一个标签： |
|
|
| - `外部 API` |
|
|
| 该标签页内新增一张独立卡片，用于配置和展示 External API 状态。 |
|
|
| ### 3.2 页面展示内容 |
|
|
| 页面需要展示： |
|
|
| - `启用 External API` 开关 |
| - 当前状态： |
| - 未启用 |
| - 已启用但未配置 Key |
| - 已启用且已配置 Key |
| - Base URL |
| - Auth Header |
| - 当前 Key 状态（仅掩码） |
| - 操作按钮 |
|
|
| ### 3.3 页面按钮 |
|
|
| 页面提供以下按钮： |
|
|
| - `保存设置` |
| - `生成新 API Key` |
| - `复制当前 Key` |
| - `复制对接信息` |
|
|
| 说明： |
|
|
| - `复制当前 Key` 仅在“本次刚生成 / 本次刚手动保存新 Key”后可用 |
| - 页面刷新后只保留掩码，不长期展示完整旧 Key |
|
|
| ### 3.4 页面固定文案 |
|
|
| 页面上必须明确展示： |
|
|
| - `Base URL: ${location.origin}/api` |
| - `Auth Header: X-API-Key` |
| - “重新生成后旧 Key 立即失效” |
| - “第三方应先调用 /api/external/capabilities 获取 service_id 对应关系” |
| |
| --- |
| |
| ## 4. 后端接口设计 |
| |
| 在 `src/web/routes/settings.py` 中新增一组专用接口： |
| |
| - `GET /api/settings/external-api` |
| - `POST /api/settings/external-api` |
| - `POST /api/settings/external-api/generate` |
| |
| ### 4.1 GET /api/settings/external-api |
| |
| 作用： |
| |
| - 返回当前 External API 状态与展示信息 |
| |
| 返回字段： |
| |
| ```json |
| { |
| "enabled": true, |
| "has_api_key": true, |
| "api_key_masked": "sk_live_****abcd", |
| "api_key_header": "X-API-Key", |
| "base_url": "http://example.com/api" |
| } |
| ``` |
| |
| 规则： |
| |
| - 不返回完整旧 Key |
| - `base_url` 可后端返回，也可前端覆盖展示为 `${location.origin}/api` |
| - `api_key_header` 固定为 `X-API-Key` |
| |
| ### 4.2 POST /api/settings/external-api |
| |
| 作用： |
| |
| - 保存启用状态 |
| - 可选手动设置新的 API Key |
| |
| 请求体： |
| |
| ```json |
| { |
| "enabled": true, |
| "api_key": "custom_key_optional" |
| } |
| ``` |
| |
| 规则： |
| |
| - `enabled` 必填 |
| - `api_key` 可选 |
| - 若 `api_key` 未传或为空字符串，则保持原值不变 |
| - 若 `api_key` 有值，则覆盖旧 Key |
|
|
| 返回体： |
|
|
| ```json |
| { |
| "success": true, |
| "message": "External API settings updated", |
| "generated_api_key": "only_when_new_key_is_set", |
| "api_key_masked": "sk_live_****abcd" |
| } |
| ``` |
|
|
| 规则： |
|
|
| - 只有本次确实设置了新 Key 时，才返回一次性明文 |
| - 否则只返回掩码 |
|
|
| ### 4.3 POST /api/settings/external-api/generate |
|
|
| 作用： |
|
|
| - 一键生成新 API Key |
|
|
| 生成策略固定为： |
|
|
| ```python |
| secrets.token_urlsafe(32) |
| ``` |
|
|
| 返回体： |
|
|
| ```json |
| { |
| "success": true, |
| "message": "External API key regenerated", |
| "generated_api_key": "new_generated_key", |
| "api_key_masked": "new_****mask" |
| } |
| ``` |
|
|
| 规则： |
|
|
| - 新 Key 生成后立即覆盖旧 Key |
| - 旧 Key 立即失效 |
| - 完整明文只在本次响应里返回一次 |
|
|
| --- |
|
|
| ## 5. 前端交互规则 |
|
|
| 在 `static/js/settings.js` 中新增一组 External API 专用逻辑。 |
|
|
| ### 5.1 页面加载 |
|
|
| 设置页加载时： |
|
|
| 1. 请求 `GET /api/settings/external-api` |
| 2. 渲染启用状态 |
| 3. 渲染 `has_api_key` |
| 4. 渲染掩码值 |
| 5. 渲染 Base URL / Header |
|
|
| ### 5.2 保存行为 |
|
|
| 点击“保存设置”时： |
|
|
| - 如果 Key 输入框为空： |
| - 仅保存 `enabled` |
| - 不修改现有 Key |
| - 如果 Key 输入框非空： |
| - 将该值作为新 Key 保存 |
| - 成功后前端显示本次返回的明文 Key |
|
|
| ### 5.3 生成行为 |
|
|
| 点击“生成新 API Key”时： |
|
|
| 1. 弹确认提示 |
| 2. 调用 `POST /api/settings/external-api/generate` |
| 3. 成功后显示： |
| - 新生成的完整 Key |
| - 复制按钮 |
| - “旧 Key 已失效”提示 |
|
|
| ### 5.4 复制行为 |
|
|
| #### 复制当前 Key |
|
|
| 仅当页面内存中存在“本次刚生成 / 刚保存”的完整 Key 时启用。 |
|
|
| #### 复制对接信息 |
|
|
| 自动拼接一段文本，包含： |
|
|
| - Base URL |
| - `X-API-Key` |
| - 4 个 external API 接口 |
| - `service_id` 来自 capabilities 的说明 |
|
|
| 建议复制内容固定为： |
|
|
| ```text |
| Base URL: |
| http://your-domain:8000/api |
| |
| Auth Header: |
| X-API-Key: your_api_key |
| |
| Available Endpoints: |
| GET /external/capabilities |
| POST /external/registration/batches |
| GET /external/registration/batches/{batch_uuid} |
| POST /external/registration/batches/{batch_uuid}/cancel |
| |
| 注意： |
| service_id 不要猜，必须来自 GET /external/capabilities 返回的 id。 |
| ``` |
|
|
| ### 5.5 Base URL 显示规则 |
|
|
| 前端展示统一使用： |
|
|
| ```js |
| `${location.origin}/api` |
| ``` |
|
|
| 这样可以兼容： |
|
|
| - 直接 IP 访问 |
| - 域名访问 |
| - 反向代理 |
|
|
| --- |
|
|
| ## 6. 安全策略 |
|
|
| 本期实现固定采用以下策略： |
|
|
| ### 6.1 不返回完整旧 Key |
|
|
| - `GET /api/settings/external-api` 不允许返回完整旧 Key |
| - 页面刷新后只显示掩码 |
|
|
| ### 6.2 一次性明文展示 |
|
|
| 完整明文只允许在以下场景返回一次： |
|
|
| - 手动设置了新 Key |
| - 点击生成了新 Key |
|
|
| ### 6.3 重新生成立即失效 |
|
|
| - 新 Key 生效后旧 Key 立即作废 |
| - 不支持新旧 Key 并存 |
|
|
| ### 6.4 本期不做项 |
|
|
| 本期明确不做： |
|
|
| - 多 Key 并存 |
| - Key 历史记录 |
| - Key 过期时间 |
| - Key 权限分级 |
| - Key 审计日志 |
| - 第三方自助申请 Key |
|
|
| --- |
|
|
| ## 7. 测试与验收 |
|
|
| ### 7.1 后端测试 |
|
|
| 至少覆盖以下场景： |
|
|
| - `GET /api/settings/external-api` |
| - 未启用、未配置 Key |
| - 已启用、已配置 Key |
| - `POST /api/settings/external-api` |
| - 仅更新 `enabled` |
| - 手动设置新 Key |
| - `POST /api/settings/external-api/generate` |
| - 成功生成新 Key |
| - 鉴权联动 |
| - 新 Key 可用 |
| - 旧 Key 失效 |
| - External API 关闭后统一返回 `403` |
|
|
| ### 7.2 前端测试 |
|
|
| 至少覆盖： |
|
|
| - 设置页新增“外部 API”标签 |
| - 区块成功渲染 |
| - 能展示 Base URL / Header / 掩码状态 |
| - 能显示生成按钮、保存按钮、复制按钮 |
|
|
| ### 7.3 集成验收 |
|
|
| 手工验收闭环： |
|
|
| 1. 在设置页启用 External API |
| 2. 点击生成新 Key |
| 3. 用新 Key 调 `/api/external/capabilities` 成功 |
| 4. 用旧 Key 调用返回 `401` |
| 5. 关闭 External API 后调用返回 `403` |
|
|
| --- |
|
|
| ## 8. 实施范围与不做项 |
|
|
| ### 本次实施范围 |
|
|
| - 网站设置页内管理 External API 开关 |
| - 网站内生成 / 手动设置 API Key |
| - 网站内复制对接信息 |
| - 与现有 External API 鉴权打通 |
|
|
| ### 本次不做 |
|
|
| - 对接方账号体系 |
| - 多租户 API Key |
| - Key 权限模型 |
| - 调用次数限流 |
| - WebHook / 回调机制 |
| - API 文档自动生成页面 |
|
|
| --- |
|
|
| ## 9. 实施结论 |
|
|
| 这是一个 **中低复杂度** 的增强项。 |
|
|
| 原因： |
|
|
| - 配置项已经存在 |
| - 鉴权已经存在 |
| - 设置页框架已经存在 |
| - 不需要数据库迁移 |
|
|
| 因此实现重点不在底层，而在： |
|
|
| - 设置接口补全 |
| - 设置页交互补全 |
| - Key 展示与重置策略收口 |
|
|
| 按当前代码结构，适合直接在现有 settings 模块内增量实现。 |
|
|
