179 lines
4.8 KiB
Markdown
179 lines
4.8 KiB
Markdown
# 项目目录说明
|
||
|
||
日期：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/`
|