sub2api-cn-relay-manager/docs/PROJECT_STRUCTURE.md

项目目录说明

日期：2026-05-27

目的

这份文档用于回答两个问题：

1. 当前仓库各一级目录分别负责什么
2. 新增文件应该放到哪里，避免继续把运行时脚本、部署资产、验收证据混在一起

它不替代 README.md，而是补充更细的目录职责说明。

一级目录

cmd/

程序入口：

• cmd/server
  • 控制面 HTTP 服务入口
• cmd/cli
  • 导入、overlay、验证等命令行入口

internal/

控制面核心实现，按职责拆分：

• internal/access
  • access closure、自愈、gateway 验证
• internal/app
  • HTTP API、bootstrap、后台任务
• internal/batch
  • batch import 请求与状态投影
• internal/config
  • 配置装载
• internal/host/sub2api
  • 宿主适配器
• internal/overlay
  • host overlay 执行器
• internal/pack
  • pack 装载、校验、overlay 解析
• internal/probe
  • upstream / host smoke probes
• internal/provision
  • import / preview / rollback / reconcile 编排
• internal/reconcile
  • 后台对账
• internal/store
  • SQLite repo 与 migrations
• internal/testutil
  • 测试辅助
• internal/worker
  • 后台 runner

packs/

版本化模型包资产：

• packs/openai-cn-pack
  • provider manifests
  • checksums
  • overlay metadata

这层只放 pack 资产，不放远端站点静态页。

deploy/

面向部署目标的静态资产或配置模板。

当前已经纳入：

• deploy/tksea-portal/index.html
  • sub.tksea.top/portal/ 静态页
• deploy/tksea-portal/admin/index.html
  • sub.tksea.top/portal/admin/ 管理首页
• deploy/tksea-portal/admin/providers.html
  • sub.tksea.top/portal/admin/providers.html provider 目录、导入页与服务端草稿入口
• deploy/tksea-portal/admin/batch-import.html
  • sub.tksea.top/portal/admin/batch-import.html 结构化 batch-import 入口
• deploy/tksea-portal/admin-batch-import.html
  • sub.tksea.top/portal/admin-batch-import.html 最小管理页
• deploy/tksea-portal/nginx.sub.tksea.top.conf.example
  • 对应 Nginx 路由示例
  • 同时包含 /portal-proxy/ 和 /portal-admin-api/ 两组反代

这层的规则是：

• 放“部署产物模板”
• 不放需要编译的 Go 代码
• 不放临时 /tmp 产物

scripts/

运维、验收、部署脚本，当前已经按用途拆成三层目录：

• scripts/deploy/
  • 部署与环境拉起脚本
  • 例如 build_local_image.sh、setup_remote43_patched_stack.sh、deploy_tksea_portal.sh
  • 其中 setup_remote43_patched_stack.sh 现会同步生成 remote43 固定仓库工作副本：
    • /home/ubuntu/sub2api-cn-relay-manager-git-current
    • 供 SUB2API_CRM_REPO_ROOT 与 provider 草稿发布链复用
• scripts/acceptance/
  • 真实宿主验收与证据处理脚本
  • 例如 real_host_acceptance.sh、import_remote43_provider.sh、check_deepseek_completion_split.sh
• scripts/test/
  • 脚本资产回归
  • 例如 test_real_host_scripts.sh、test_tksea_portal_assets.sh

规则：

• 只放可执行运维脚本
• 新脚本必须先判断属于 deploy/、acceptance/ 还是 test/
• 脚本依赖的静态模板应尽量放到 deploy/ 或 docs/

docs/

所有长期保留文档：

• 真相入口
• 执行板
• 验收 runbook
• provider 矩阵
• 外部 OpenClaw 验证
• 目录与部署说明

tests/

集成测试套件：

• tests/integration

artifacts/

真实验收产物与归档证据。

规则：

• artifacts/real-host-acceptance/
  • 当前最终证据
• artifacts/real-host-acceptance-archive/
  • 历史调试样本与归档

不要把部署模板、静态页、脚本说明放到这里。

web/

保留给未来管理端前端实现。

当前公网 portal 已经独立作为 deploy/tksea-portal/ 静态资产纳管，不应误放进 web/，因为它不是控制面管理后台。

当前推荐放置规则

新增文件时，优先按下面规则归类：

• 新的 provider / pack 元数据
  • 放 packs/
• 新的 Go 业务逻辑
  • 放 internal/
• 新的 CLI 或 server 入口
  • 放 cmd/
• 新的线上静态部署页 / 反向代理模板
  • 放 deploy/
• 新的运维或验收命令脚本
  • 放 scripts/deploy、scripts/acceptance 或 scripts/test
• 新的长期说明文档
  • 放 docs/
• 新的验收证据
  • 放 artifacts/

当前整理结果

截至 2026-05-27，最近一轮目录整理主要做了三件事：

1. 把原来只存在 /tmp 的 sub.tksea.top portal 静态页与 Nginx 规则正式纳入仓库
2. 把 portal 部署动作收口到 scripts/deploy/deploy_tksea_portal.sh
3. 把 scripts/ 从全平铺整理为 deploy/、acceptance/、test/ 三层，减少脚本入口混杂
4. 把“公网 portal / OpenClaw / remote43 验收”相关说明分别挂回 deploy/、scripts/、docs/