平台管理员手册

把模型 Token、渠道账号、API Key、Agent 工具与远程节点配置成可使用、可限制、可观察的生产能力——不管这套平台是你一个人用，还是多人共用。

本页目录首次登录管理入口渠道账号池模型路由 API Key 日志观测 MCP 工具节点上线验收

管理端统一入口为 /manager。认证优先使用平台用户 session 中的 role=admin；/manager/login 是尚无管理员用户或兼容层异常时的 break-glass 单密码入口。

引导平台管理员

[monkeycode]
compat_enabled = true
bootstrap_admin_email = admin@example.com
bootstrap_admin_password = <强密码>
bootstrap_admin_name = admin

引导是幂等的：相同邮箱已存在则跳过，重启不会重置密码。创建后从 .env 移除明文密码并转入 Secret 管理。

应急管理员首次提交即设密码旧管理配置没有 password_hash 时，第一次向 /admin/login 提交的密码会成为初始管理员密码。部署初期先限制来源，由可信管理员访问 /manager/login 设置强密码，再开放管理入口。

2. 管理能力入口

数据仪表盘

/manager/data-dashboard：请求、成功率、Token 和趋势。

渠道

/manager/channels：Provider、账号池、认证、模型和限流。

模型路由

/manager/model-routing：对外模型、模型组和候选渠道。

API Keys

/manager/api-keys：权限、额度、状态、使用量与轮换。

请求日志

/manager/request-logs：请求级路由、渠道尝试、耗时与 Token。

节点

/manager/nodes：onboard、审批、分组、容量与终端。

MCP 市场

/manager/mcp-market：内置插件、远程 MCP 与服务状态。

安全

/manager/security：安全状态与相关治理配置。

3. 接入模型渠道与账号池

进入“渠道”，新增内置 Provider 类型或自定义 OpenAI / Anthropic / Responses 兼容渠道。
配置上游 base URL、协议路径、认证方式和渠道限流；不要直接在生产 Key 上试错。
新增一个或多个账号，设置启停、优先级、权重、RPM/TPM/并发与代理。
使用账号测试功能验证认证与基础请求；刷新上游模型列表。
核对模型 ID、别名、白名单、上下文与 output_modalities；图片/视频生成能力由输出模态决定。
观察认证状态、配额与失败原因，再进入模型路由配置。

凭据与测试边界Cookie、Bearer/refresh token、账号密码只进入安全字段。测试入参在入口一次构造，dispatch 不应加临时补丁；测试结束后撤销临时凭据。

Ai Lubricant 渠道列表 — **渠道中心：**统一管理模型供应来源，而不是让每个应用保存上游配置。

4. 配置模型路由

定义稳定的对外模型名；客户端只依赖此名称。
把外部名映射到实际模型或模型组；为组配置多个 Provider/模型候选。
按 API Key scope 限制可用模型与 Provider，避免高成本/敏感渠道被全局使用。
验证同协议直通：上游与客户端协议一致时保持原始语义；仅跨协议路径做字段映射。
用测试 Key 验证非流式、流式、工具调用、错误和上下文超限。
在请求日志确认实际 routed model、Provider、account 和 request path。

账号选择会综合启停、认证、冷却、限流、配额、优先级、权重和渠道评分。评分全部为零时交给模型组回退或返回 429，不用 LRU 反复探测故障渠道。

Ai Lubricant 模型路由 — **业务解耦：**客户端使用稳定模型名，供应商和账号变化由管理员在平台内处理。

5. API Key 生命周期

创建与授权

使用“业务-环境”命名，如 order-agent-prod。
按最小权限授权模型、Provider 与功能，不默认允许全部。
设置 RPM/RPD、TPM、并发、Token 或累计用量限制。
明文只交给目标 Secret 管理系统；不进入浏览器前端、Git、日志或截图。

观察、轮换与撤销

按 Key 查看请求量、Token、错误、模型和渠道使用。
轮换顺序：新建 → 应用切换并验证 → 禁用旧 Key → 删除。
疑似泄露立即禁用；查询 request ID 与用量，轮换关联上游凭据。
定期清理闲置 Key、离职用户和下线项目。

生产不可关闭全局 Key 校验api_keys_enabled() 关闭时模型 API 主链路可接受无 Key 请求，只适合隔离调试环境。

API Key 权限与额度管理 — **将 Token 变成治理单元：**应用只拿到平台 Key，实际模型凭据留在渠道账号池。

6. 用请求日志定位问题

请求日志不是简单访问记录；它关联一次客户端请求和多次渠道尝试：

request ID / parent request ID
API Key lineage 快照
请求模型与 routed model
Provider、账号和实际请求路径
成功/失败、状态码、错误与 retry path
总耗时、首 Token、prompt/completion/total/cached token
脱敏头与按策略保留的正文

排障先从客户端 request ID 进入详情，按时间顺序查看每次渠道尝试；不要只看最终错误。

Ai Lubricant 请求日志 — **列表定位：**按模型、Provider、状态和 Key 找到异常请求。

请求路由与渠道尝试详情 — **请求级证据：**查看一次请求在多个渠道账号之间的真实路径。

7. 管理 MCP 与内置工具

平台 MCP 市场

在 /manager/mcp-market 管理内置插件和远程 SSE MCP。
custom 插件版本需完成 security review 并为 passed 才能激活。
内置 CDP/Mail 常驻运行；start/reload 会确保注册并推送最新配置。
修改 CDP client 或 Mail 明细后必须 resync，将配置快照下发到运行时。

CDP 与 Mail token

用户只创建“对外开放” token；Agent/节点/用户内部 token 由服务按身份自动签发。
CDP 外部 MCP token 必须绑定具体 client；未绑定会得到“not authorized to operate any CDP client”。
Chrome 扩展 connection token 只用于 WebSocket 握手，不是 MCP access token。
Mail token 只能访问自己的实例；插件按 instance key 过滤上游账户。

8. 节点治理

在 /manager/nodes 创建 passive_management 分组，或 onboard execution/management 客户端。
核对节点身份、OS/arch、标签与版本后 Approve；在线但 pending 的节点不参与调度。
配置容量、父分组和授权；定期审计活跃会话与最后心跳。
异常/泄露节点立即 Revoke；管理节点删除前处理其 execution 子节点。
浏览器终端与 host exec 是高权限能力，只向可信管理员开放。

详细接入、安装、终端、文件、代理和安全说明见节点管理员手册。

9. 上线验收清单

☐ 至少两个独立 Provider/账号（如有）完成认证、模型刷新和基础请求测试。
☐ 外部模型名和模型组已定义，Key 只看见授权模型。
☐ OpenAI 非流式/流式、Anthropic Messages、工具调用与错误路径已验证。
☐ 429、账号冻结、Provider 故障时路由行为和日志符合预期。
☐ API Key 全局鉴权开启；生产 Key 有模型/渠道/额度限制。
☐ 请求日志头脱敏；payload capture 与保留期通过审批。
☐ 节点 approved、终端/文件可用，控制面只有一个 Registry。
☐ CDP/Mail token 绑定正确实例，不存在跨用户访问。
☐ 管理员、普通用户、节点管理员权限边界已验证。
☐ TLS、备份、Secret、升级与事件响应流程已演练。

1. 首次登录与管理员身份