Files
CloudLab/ARCHITECTURE.md
CloudLabandWorkBuddy 54876a5f26
CloudLab CI/CD / 门禁 doctor (push) Failing after 30s
CloudLab CI/CD / 单元测试 (push) Skipped
CloudLab CI/CD / 归档完整性 (push) Skipped
CloudLab CI/CD / 构建站点与归档 (push) Skipped
CloudLab CI/CD / 部署到 lab.hdtime.space(rsync) (push) Skipped
CloudLab CI/CD / 构建镜像并推送 Gitea 容器仓库 (push) Skipped
CloudLab CI/CD / 容器部署到 lab.hdtime.space (push) Skipped
CloudLab CI/CD / 发布版本(Tag) (push) Skipped
fix(deploy): 容器部署改用 8080 端口,避开被占用的 80
- docker-compose / deploy-container.sh / CI deploy-container 均改宿主机发布端口 80→8080
  (容器内 nginx 仍监听 80);端口可用 CLOUDLAB_SITE_PORT 覆盖
- VERSION 3.7.3;同步 ARCHITECTURE/CONTRIBUTING/CHANGELOG

Co-Authored-By: WorkBuddy <noreply@workbuddy.ai>
2026-11-11 07:59:40 +08:00

7.4 KiB
Raw Permalink Blame History

CloudLab 架构与演进契约

版本 v3.7.0 | 目标:把「一批能跑的一次性脚本」变成可不断修正和进化的工程。 原则:不重写业务代码,用一层薄控制面把散落的规则收敛;历史资产保字节完整,新代码走统一契约。

一、分层

┌─────────────────────────────────────────────────────────────┐
│  入口层   cloudlab.py(唯一推荐入口)                          │
│           doctor / test / verify / snapshot / list / build     │
├─────────────────────────────────────────────────────────────┤
│  控制面   cloudlab_core/  ← 单一事实来源(纯标准库、零依赖)    │
│           paths      工作区根与路径契约                        │
│           policy     归档/上传/部署共用排除规则                 │
│           registry   资产表、交付表、构建流水线、版本号          │
│           integrity  清单 / SHA256 / 修订登记                  │
│           doctor     自检与回归门禁                            │
├─────────────────────────────────────────────────────────────┤
│  门禁层   tests/(unittest)  ·  .gitea/workflows/ci.yml       │
├─────────────────────────────────────────────────────────────┤
│  资产层   7 套资料库 + 云端实验室 + 两套部署准备(原样保留)     │
│  交付层   归档打包.py / build_upload_package.py /              │
│           build_deploy_package.py / build_site.py / 校验归档.py │
│  部署层   deploy/(rsync 或容器两种部署,基础设施即代码)        │
└─────────────────────────────────────────────────────────────┘

二、单一来源契约(改一处,全工程跟着变)

要改什么 只改这里 自动影响
工作区根解析 cloudlab_core/paths.py 所有生成器、校验器、CLI
排除规则 / 白名单 cloudlab_core/policy.py 归档、完整性校验、doctor
新增资产目录 / 交付文件 cloudlab_core/registry.py 归档纳入范围、doctor 实体检查
门户构建顺序 registry.PORTAL_PIPELINE cloudlab.py build portal --apply、doctor
版本号 registry.VERSION CLI、快照登记、doctor 输出
新增自检项 doctor.CHECKS 追加函数 本地门禁与 CI 同时生效

归档打包.py 与 校验归档.py 不再自带规则:前者从控制面读纳入范围与排除规则, 后者只是 cloudlab_core.integrity.main() 的兼容入口。归档说明以 归档说明.md 为模板,打包时只回填统计数字。

三、路径契约

  • 唯一入口:paths.WORKSPACE(CLOUDLAB_ROOT 可覆盖,否则向上找双标志文件)。
  • 禁止在任何 .py 中出现以 /workspace 开头的路径字符串常量; doctor 用 AST 全仓扫描,命中即门禁失败。
  • 历史一次性脚本(13 个)已统一注入路径引导 + _CL_WS;它们是冻结的历史资产, 主流程不依赖,但同样受门禁保护,不允许再引入硬编码。

四、门户构建:幂等编排 + 回退护栏

build_portal.py 只生成 4 套基础资产,第 5~7 套由各库 register_to_portal.py 幂等追加。两道防线:

  1. 源头护栏:build_portal.py 检测到门户当前 n_libs > 4 且未设置 CLOUDLAB_ALLOW_PORTAL_RESET=1 时直接抛错,杜绝单独重跑导致回退。
  2. 统一编排:cloudlab.py build portal --apply 按 PORTAL_PIPELINE 顺序执行 4 步, 每步校验 n_libs 达到 4/5/6/7,失败即中止;完成后自动 snapshot 登记修订。 不带 --apply 时只打印编排,零写入。

五、完整性:快照证据 vs 持续演进

  • 归档文件清单.csv 是 v3.6 快照证据,默认永不覆盖。
  • 本轮及后续每次主动修订 / 新增写入 修订记录.json(cloudlab.py snapshot 自动登记)。
  • verify 把已登记变更标 EXPECTED,其余失配 / 缺失 / 未登记新增一律 FAIL。 所以工程可以持续改,但意外损坏永远不会被掩盖。
  • 只有显式 python3 cloudlab.py verify --refresh(或 校验归档.py --refresh) 才会把清单刷新为当前状态。

六、演进循环(每次改动都走这条)

改代码 / 加资产
  → python3 cloudlab.py snapshot      登记变更
  → python3 cloudlab.py doctor       自检门禁
  → python3 cloudlab.py test         单元测试
  → python3 cloudlab.py verify       字节级完整性
  → 写 CHANGELOG.md → git commit

CI 在 push / PR 上自动重跑后四步中的 doctor / test / verify / portal dry-run, 失败即阻断合并。详见 CONTRIBUTING.md 与 .gitea/workflows/ci.yml。

八、CI/CD 流水线(基础设施即代码)

工作流位于 .gitea/workflows/ci.yml(GitHub 兼容,已镜像到 .github/workflows/ci.yml): gate(doctor) → test → verify → build(站点+归档产物) → deploy(→ lab.hdtime.space) / release(→ Tag)。

  • CI 全链路纯标准库、零联网取数、不装第三方依赖、不持有任何凭据,与控制面设计纪律一致。
  • 构建可复现:站点由 build_site.py(规则来自 cloudlab_core)从仓库过滤生成, 不依赖手改的 CloudLab-Site/;归档由 归档打包.py 同源生成。构建产物通过 artifact 在 job 间传递。
  • CD 部署:deploy job 仅在 master 推送且配置了 DEPLOY_SSH_KEY 时触发, 用仓库内 deploy/deploy.sh 经 rsync 上传(无 --delete),Nginx 配置由同一脚本安装并 nginx -t 校验。
  • CD 容器部署(可选):把 DEPLOY_MODE 仓库变量设为 container 后,流水线改为 docker-build(多阶段镜像:容器内 build site → nginx:alpine 提供静态服务,推送 Gitea 容器仓库)
    • deploy-container(服务器 docker pull + docker run)。两种部署互斥,由 DEPLOY_MODE 切换。 宿主机发布端口默认 8080(容器内 nginx 仍监听 80),避开服务器上已占用的 80 端口(如 Gitea 自带 nginx); 可用环境变量 CLOUDLAB_SITE_PORT 覆盖,访问地址 http://lab.hdtime.space:8080/。
  • CD 发布:推送 v* 标签时 release job 通过 Gitea API 创建/复用 Release 并上传归档包, 不依赖任何第三方 action。
  • 密钥只在仓库 Settings → Actions → Secrets 中以 DEPLOY_SSH_KEY / GITEA_TOKEN 等形式注入, 脚本本体与 Nginx 配置可入库,私钥永不入仓。

七、诚实边界

  • 控制面只做编排与门禁,不改业务数据、不联网、不装依赖、不持有任何凭据。
  • 13 套业务验证与 RK3588 真板验证仍需各自环境,不在控制面门禁内。
  • parts/ 分卷是可重建派生产物,不入库、不进归档;需要时用 cloudlab.py build upload|deploy。