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
- 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>
7.4 KiB
7.4 KiB
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
幂等追加。两道防线:
- 源头护栏:
build_portal.py检测到门户当前n_libs > 4且未设置CLOUDLAB_ALLOW_PORTAL_RESET=1时直接抛错,杜绝单独重跑导致回退。 - 统一编排:
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 部署:
deployjob 仅在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*标签时releasejob 通过 Gitea API 创建/复用 Release 并上传归档包, 不依赖任何第三方 action。 - 密钥只在仓库 Settings → Actions → Secrets 中以
DEPLOY_SSH_KEY/GITEA_TOKEN等形式注入, 脚本本体与 Nginx 配置可入库,私钥永不入仓。
七、诚实边界
- 控制面只做编排与门禁,不改业务数据、不联网、不装依赖、不持有任何凭据。
- 13 套业务验证与 RK3588 真板验证仍需各自环境,不在控制面门禁内。
parts/分卷是可重建派生产物,不入库、不进归档;需要时用cloudlab.py build upload|deploy。