sub2api-cn-relay-manager/README.md

# 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
```