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 代码动态加载
• 不要求宿主识别“插件”概念
• 不接管宿主网关流量

目录结构

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

交付模型

本项目最终会拆成两个可独立发布的产物：

1. sub2api-cn-relay-manager

   • 外部控制面 / 安装器
   • 连接已有 sub2api
   • 安装模型包
   • 调用宿主管理 API 创建资源
   • 做 smoke test、对账和状态展示

2. model_pack

   • 只包含 provider 定义、默认模板、导入规则和校验信息
   • 不携带宿主执行代码
   • 可以跨机器复用

当前文档

先读这些：

• docs/README.md —— docs 目录导航首页；如果你准备从文档集入口开始读，先看这里
• docs/SOURCE_OF_TRUTH.md —— 当前文档真相入口；先看这份，避免把历史审查/历史 artifact 误读为当前结论
• docs/EXECUTION_BOARD.md —— 当前执行状态、最新 gate、剩余阻断
• docs/PRODUCTION_CLOSURE_BOARD.md —— 当前是否可按 PRD 首版范围放行
• docs/PROVIDER_ONBOARDING_PLAYBOOK.md —— 新增 provider、宿主版本变更后重验、稳定导入与快速诊断的完整作业手册
• docs/PROVIDER_VALIDATION_MATRIX.md —— 官方 provider 模板覆盖度、key 覆盖度、live 验收进度矩阵
• docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md —— 真实宿主验收标准步骤
• docs/REAL_HOST_ACCEPTANCE_LEARNINGS.md —— 已调通细节、典型误判点、诊断顺序
• docs/OPENCLAW_EXTERNAL_VALIDATION.md —— OpenClaw 最后一跳真实使用验证
• docs/PROJECT_STRUCTURE.md —— 当前仓库目录职责说明
• scripts/README.md —— 脚本目录分层说明与常用入口
• deploy/tksea-portal/admin/index.html —— 管理入口首页
• deploy/tksea-portal/admin/providers.html —— provider 目录 / preview-import / import / manifest 草稿页（含服务端草稿保存）
• deploy/tksea-portal/admin-batch-import.html —— 最小 batch-import 管理页

背景/设计文档：

• docs/2026-05-12-sub2api-cn-relay-manager-solution.md
• docs/PRD.md
• docs/TDD_PLAN.md
• docs/DEPLOYMENT.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 提供一键导入入口

示例：

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>

运行方式

服务端：

SUB2API_CRM_ADMIN_TOKEN=replace-me go run ./cmd/server

Docker Compose：

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

真实宿主验收：

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