150 lines
6.0 KiB
Markdown
150 lines
6.0 KiB
Markdown
# sub2api-cn-relay-manager
|
||
|
||
`sub2api-cn-relay-manager` 是一个独立于 `sub2api` 宿主仓库的外部伴生安装器 / 控制面项目。
|
||
|
||
目标不是修改 `sub2api`，也不是把国产模型能力硬塞进宿主源码，而是通过 `sub2api` 已有的管理 API，把“国产模型 OpenAI 兼容中转能力”以独立交付物的形式安装到任意一台已部署的 `sub2api` 实例上。
|
||
|
||
## 项目定位
|
||
|
||
- 宿主：第三方开源系统 `sub2api`
|
||
- 约束：不修改宿主代码，不 fork 宿主，不要求宿主内置原生插件运行时
|
||
- 交付：一个独立控制面项目 + 一个或多个 `model_pack`
|
||
- 结果：管理员可一键导入多个国产模型 key，普通用户继续只用 `sub2api` 标准 API
|
||
|
||
## 这个项目解决的问题
|
||
|
||
- 不同机器部署了 `sub2api` 后，如何用同一套交付物补齐国产模型中转能力
|
||
- 如何把多个国产模型 key 批量导入为可用的宿主资源
|
||
- 如何在不改宿主的前提下实现热生效、探测、对账和漂移发现
|
||
- 如何让普通用户完全无感，继续走 `sub2api` 标准接口
|
||
|
||
## 非目标
|
||
|
||
- 不做宿主原生插件系统
|
||
- 不做任意第三方 Go 代码动态加载
|
||
- 不要求宿主识别“插件”概念
|
||
- 不接管宿主网关流量
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
sub2api-cn-relay-manager/
|
||
cmd/ # CLI / server 入口
|
||
internal/ # 控制面核心实现
|
||
packs/ # provider packs / overlay metadata
|
||
deploy/ # 部署资产（portal 静态页、Nginx 模板）
|
||
scripts/ # deploy / acceptance / test 三层脚本
|
||
docs/ # 真相入口、执行板、runbook、目录说明
|
||
tests/ # 集成测试
|
||
artifacts/ # 真实验收证据与归档
|
||
web/ # 预留给未来管理端前端
|
||
```
|
||
|
||
如果你想看更细的目录职责，而不是只看一级树结构，读：
|
||
|
||
- [docs/PROJECT_STRUCTURE.md](./docs/PROJECT_STRUCTURE.md)
|
||
|
||
## 交付模型
|
||
|
||
本项目最终会拆成两个可独立发布的产物：
|
||
|
||
1. `sub2api-cn-relay-manager`
|
||
- 外部控制面 / 安装器
|
||
- 连接已有 `sub2api`
|
||
- 安装模型包
|
||
- 调用宿主管理 API 创建资源
|
||
- 做 smoke test、对账和状态展示
|
||
|
||
2. `model_pack`
|
||
- 只包含 provider 定义、默认模板、导入规则和校验信息
|
||
- 不携带宿主执行代码
|
||
- 可以跨机器复用
|
||
|
||
## 当前文档
|
||
|
||
先读这些：
|
||
|
||
- [docs/README.md](./docs/README.md) —— docs 目录导航首页；如果你准备从文档集入口开始读，先看这里
|
||
- [docs/SOURCE_OF_TRUTH.md](./docs/SOURCE_OF_TRUTH.md) —— 当前文档真相入口；先看这份，避免把历史审查/历史 artifact 误读为当前结论
|
||
- [docs/EXECUTION_BOARD.md](./docs/EXECUTION_BOARD.md) —— 当前执行状态、最新 gate、剩余阻断
|
||
- [docs/PRODUCTION_CLOSURE_BOARD.md](./docs/PRODUCTION_CLOSURE_BOARD.md) —— 当前是否可按 PRD 首版范围放行
|
||
- [docs/PROVIDER_ONBOARDING_PLAYBOOK.md](./docs/PROVIDER_ONBOARDING_PLAYBOOK.md) —— 新增 provider、宿主版本变更后重验、稳定导入与快速诊断的完整作业手册
|
||
- [docs/PROVIDER_VALIDATION_MATRIX.md](./docs/PROVIDER_VALIDATION_MATRIX.md) —— 官方 provider 模板覆盖度、key 覆盖度、live 验收进度矩阵
|
||
- [docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md](./docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md) —— 真实宿主验收标准步骤
|
||
- [docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md](./docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md) —— 已调通细节、典型误判点、诊断顺序
|
||
- [docs/OPENCLAW_EXTERNAL_VALIDATION.md](./docs/OPENCLAW_EXTERNAL_VALIDATION.md) —— OpenClaw 最后一跳真实使用验证
|
||
- [docs/PROJECT_STRUCTURE.md](./docs/PROJECT_STRUCTURE.md) —— 当前仓库目录职责说明
|
||
- [scripts/README.md](./scripts/README.md) —— 脚本目录分层说明与常用入口
|
||
- [deploy/tksea-portal/admin/index.html](./deploy/tksea-portal/admin/index.html) —— 管理入口首页
|
||
- [deploy/tksea-portal/admin/providers.html](./deploy/tksea-portal/admin/providers.html) —— provider 目录 / preview-import / import / manifest 草稿页（含服务端草稿保存）
|
||
- [deploy/tksea-portal/admin-batch-import.html](./deploy/tksea-portal/admin-batch-import.html) —— 最小 batch-import 管理页
|
||
|
||
背景/设计文档：
|
||
|
||
- [docs/2026-05-12-sub2api-cn-relay-manager-solution.md](./docs/2026-05-12-sub2api-cn-relay-manager-solution.md)
|
||
- [docs/PRD.md](./docs/PRD.md)
|
||
- [docs/TDD_PLAN.md](./docs/TDD_PLAN.md)
|
||
- [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md)
|
||
- [deploy/README.md](./deploy/README.md)
|
||
|
||
## 当前 MVP 能力
|
||
|
||
当前仓库已经具备一个最小可运行闭环：
|
||
|
||
- `packs/openai-cn-pack/` 提供真实 `pack.json + provider + checksums`
|
||
- `internal/pack` 负责 pack 装载、checksum 校验、provider schema 校验
|
||
- `internal/provision` 负责多 key 导入编排、账号探测和访问闭环判定
|
||
- `cmd/cli import-provider` 提供一键导入入口
|
||
|
||
示例：
|
||
|
||
```bash
|
||
go run ./cmd/cli import-provider \
|
||
--host-base-url https://sub2api.example.com \
|
||
--host-api-key <admin-api-key> \
|
||
--pack-dir ./packs/openai-cn-pack \
|
||
--provider-id deepseek \
|
||
--keys sk-a,sk-b \
|
||
--access-mode self_service \
|
||
--access-api-key <user-api-key>
|
||
```
|
||
|
||
|
||
## 运行方式
|
||
|
||
服务端：
|
||
|
||
```bash
|
||
SUB2API_CRM_ADMIN_TOKEN=replace-me go run ./cmd/server
|
||
```
|
||
|
||
Docker Compose：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env 中的 SUB2API_CRM_ADMIN_TOKEN
|
||
scripts/deploy/build_local_image.sh
|
||
docker run --rm -p 8080:8080 \
|
||
--env-file .env \
|
||
-v "$(pwd)/data:/data" \
|
||
sub2api-cn-relay-manager:local
|
||
curl -fsS http://127.0.0.1:8080/healthz
|
||
```
|
||
|
||
真实宿主验收：
|
||
|
||
```bash
|
||
CRM_BASE_URL=http://127.0.0.1:8080 \
|
||
CRM_ADMIN_TOKEN='<crm-admin-token>' \
|
||
HOST_NAME=prod-sub2api \
|
||
HOST_BASE_URL=https://sub2api.example.com \
|
||
HOST_API_KEY='<sub2api-admin-key>' \
|
||
PACK_PATH=/app/packs/openai-cn-pack \
|
||
PROVIDER_ID=deepseek \
|
||
KEYS=sk-live-1 \
|
||
ACCESS_MODE=self_service \
|
||
ACCESS_API_KEY='<user-gateway-key>' \
|
||
DRY_RUN=1 \
|
||
scripts/acceptance/real_host_acceptance.sh
|
||
```
|