docs: ocg_router spec file (human help + AI spec)
This commit is contained in:
@@ -0,0 +1,95 @@
|
|||||||
|
{
|
||||||
|
"module": "ocg_router",
|
||||||
|
"version": "1.0",
|
||||||
|
"purpose": "OCG 路由代理。OpenAI 兼容代理(:19878)，背后池化 6 个 OpenCode Go API key，按剩余 quota 智能路由，402/429/5xx 自动故障切换。替代写死的 key3 配置，让所有 OMO 子 agent 自动使用最空闲的 key。",
|
||||||
|
"ui_location": "I Tab (Infrastructure) → OCG 路由代理 section (API 用量下方)",
|
||||||
|
|
||||||
|
"human_help": {
|
||||||
|
"title": "OCG 路由代理",
|
||||||
|
"description": [
|
||||||
|
"把 6 个 OpenCode Go key 池化成一个 OpenAI 兼容的 API 端点(:19878)。",
|
||||||
|
"每次请求自动选剩余 quota 最多的 key，用完后自动切下一个。",
|
||||||
|
"402(余额不足)、429(限流)、5xx(服务器错误) 自动标记故障 key 并切换，5 分钟后恢复。",
|
||||||
|
"取代原来写死 key3 的配置——key3 订阅已取消，不改的话所有子 agent 都会 Insufficient balance。",
|
||||||
|
"Dashboard 可以看到当前路由到哪个 key、各 key 用量、命中次数。"
|
||||||
|
],
|
||||||
|
"usage": [
|
||||||
|
"1. 确保 systemd 服务 ocg-router 在运行 (systemctl status ocg-router)",
|
||||||
|
"2. OMO 配置指向 http://192.168.1.246:19878/v1（已在 oh-my-openagent.jsonc 和 config.json 配置好）",
|
||||||
|
"3. 本区块自动每 10 秒刷新，显示当前路由 key 和池状态",
|
||||||
|
"4. 如果代理挂了，Dashboard 会显示「代理未运行」并给出错误信息"
|
||||||
|
],
|
||||||
|
"troubleshooting": [
|
||||||
|
"代理未运行 → ssh 246 systemctl restart ocg-router",
|
||||||
|
"所有 key 故障 → 检查 246 到 opencode.ai 网络是否通 (curl https://opencode.ai/zen/go/v1/models)",
|
||||||
|
"某个 key 一直在冷却中 → 等 5 分钟冷却期过去，或重启代理清冷却 (systemctl restart ocg-router)",
|
||||||
|
"当前路由 key 为空 → 代理刚启动还没收到请求，先发一个请求就会显示"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
|
||||||
|
"ai_spec": {
|
||||||
|
"apis": [
|
||||||
|
{"method": "GET", "path": "http://192.168.1.246:19878/health", "returns": "{ok, time}", "proxied_to": "ocg_router.py status"},
|
||||||
|
{"method": "GET", "path": "http://192.168.1.246:19878/v1/models", "returns": "OpenAI 兼容模型列表", "proxied_to": "ocg_router.py → opencode.ai"},
|
||||||
|
{"method": "POST", "path": "http://192.168.1.246:19878/v1/chat/completions", "returns": "OpenAI 兼容响应 (含 stream)", "proxied_to": "ocg_router.py → opencode.ai"},
|
||||||
|
{"method": "GET", "path": "http://192.168.1.246:19878/api/status", "returns": "代理状态 {current_key, pool, hits}", "proxied_to": "ocg_router.py internal"},
|
||||||
|
{"method": "GET", "path": "/api/proxy/status", "returns": "代理状态(通过 dashboard 代理)", "proxied_to": "dashboard.py → 19878"}
|
||||||
|
],
|
||||||
|
"dependencies": [
|
||||||
|
"ocg_router.py — 代理核心，systemd 常驻 (:19878)",
|
||||||
|
"usage_stats.json — 每 2 分钟刷新，提供各 key 用量数据",
|
||||||
|
"accounts.json — 提供 key 列表和 API key",
|
||||||
|
"dashboard.py — /api/proxy/status 代理端点",
|
||||||
|
"dashboard.html — OCG 路由代理 section (id=proxy-router-section)",
|
||||||
|
"oh-my-openagent.jsonc — OMO 配置，所有 agent/category 指向 ocg-router",
|
||||||
|
"~/.config/opencode/config.json — ocg-router provider 定义"
|
||||||
|
],
|
||||||
|
"architecture": {
|
||||||
|
"flow": "OMO(Windows) → ocg-router(:19878, 246) → 按 usage_stats.json 选最空闲 key → opencode.ai/zen/go/v1",
|
||||||
|
"key_selection": "健康度 score = rolling%*0.6 + weekly%*0.3 + monthly%*0.1。score 最低的 key 被选中。订阅取消/采集错误的 key score=999，故障冷却期内 score=888",
|
||||||
|
"failover": "402/429/5xx → 标记 key 故障 5 分钟 → 自动重试下一个 key",
|
||||||
|
"providers": ["ocg-key1 (staymo7777@gmail.com)", "ocg-key2 (hua65111@gmail.com)", "ocg-key3 (staymo@163.com — 订阅已取消, 不可用)", "ocg-key4 (staywithmo@163.com)", "ocg-key5 (damnedmoon@163.com)", "ocg-key6 (ycdennismo@163.com)"],
|
||||||
|
"port": "19878"
|
||||||
|
},
|
||||||
|
"constraints": [
|
||||||
|
"代理必须跑在 246 上 — usage_stats.json 在 246 本地",
|
||||||
|
"firewall: ufw allow 19878/tcp from 192.168.1.0/24",
|
||||||
|
"pid lock: proc_guard('ocg_router') — 防止重复启动",
|
||||||
|
"冷却期 300 秒 — key 被标记故障后 5 分钟自动恢复",
|
||||||
|
"用量刷新间隔 120 秒",
|
||||||
|
"User-Agent 必须用 Mozilla/5.0 — 否则 Cloudflare 1010 拦截"
|
||||||
|
],
|
||||||
|
"must_not": [
|
||||||
|
"不要把代理跑在 206 上 — 206 是阿里云，到 opencode.ai 的网络被 Cloudflare 按数据中心 IP 拦截",
|
||||||
|
"不要绕过代理直接配 ocg-key3 — key3 订阅已取消，会 Insufficient balance",
|
||||||
|
"不要改 baseURL 从 http 到 https — 内网走 HTTP 性能更好",
|
||||||
|
"不要在 Windows 本机直接拉 usage_stats.json — 数据在 246 上，代理跑 246 避免网络依赖"
|
||||||
|
],
|
||||||
|
"related_modules": [
|
||||||
|
{"module": "usage_monitor", "relation": "提供 usage_stats.json 用量数据，代理依赖它做 key 选择"},
|
||||||
|
{"module": "dashboard", "relation": "/api/proxy/status 端点代理到路由器；前端 OCG 路由代理 section 展示状态"}
|
||||||
|
],
|
||||||
|
"tests": [
|
||||||
|
{"id": "ROUTER01", "name": "GET /health returns ok", "endpoint": "GET http://192.168.1.246:19878/health"},
|
||||||
|
{"id": "ROUTER02", "name": "GET /v1/models returns model list", "endpoint": "GET http://192.168.1.246:19878/v1/models"},
|
||||||
|
{"id": "ROUTER03", "name": "POST /v1/chat/completions non-stream", "endpoint": "POST http://192.168.1.246:19878/v1/chat/completions"},
|
||||||
|
{"id": "ROUTER04", "name": "GET /api/status returns pool health", "endpoint": "GET http://192.168.1.246:19878/api/status"},
|
||||||
|
{"id": "ROUTER05", "name": "Dashboard /api/proxy/status proxies correctly", "endpoint": "GET http://192.168.1.246:5803/api/proxy/status"}
|
||||||
|
],
|
||||||
|
"known_issues": [
|
||||||
|
"Cloudflare 1010: opencode.ai API 需要真实 User-Agent（Mozilla/5.0），代理已内置",
|
||||||
|
"阿里云到 opencode.ai: 数据中心 IP 可能被 Cloudflare WAF 拦截，所以代理必须跑在 246（家庭宽带 IP）",
|
||||||
|
"key3 订阅已取消: key3 在池中但 score=999（不可用），自动跳过"
|
||||||
|
],
|
||||||
|
"related_files": [
|
||||||
|
"gateway/scripts/ocg_router.py — 代理核心",
|
||||||
|
"gateway/scripts/dashboard.py — /api/proxy/status",
|
||||||
|
"gateway/scripts/templates/dashboard.html — proxy-router-section",
|
||||||
|
"gateway/scripts/specs/ocg_router.json — 本 spec 文件",
|
||||||
|
"gateway/temp/usage_stats.json — 用量数据源",
|
||||||
|
"gateway/scripts/usage_monitor/accounts.json — key 配置",
|
||||||
|
"~/.config/opencode/oh-my-openagent.jsonc — OMO 配置",
|
||||||
|
"/etc/systemd/system/ocg-router.service — systemd 服务定义"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user