137 lines
6.3 KiB
Markdown
137 lines
6.3 KiB
Markdown
---
|
||
name: builder
|
||
description: >-
|
||
按统一契约构建并发布项目的 DEB 包与 Docker 镜像：先校验项目 Makefile 是否符合
|
||
builder 契约（check.py），再 make 构建产物，经授权后用 skill 自带脚本上传并验证。
|
||
触发词：构建 deb、发布 deb、上传 deb、推送 apt 仓库、打 Debian 包、构建镜像、
|
||
发布镜像、推送 Docker 镜像、make push、检查 Makefile 是否符合规范。仅分析打包
|
||
逻辑或只构建不上传时也可使用；不会在未获授权时执行任何上传。Docker 轨道保持
|
||
显式触发：用户点名（builder/publish docker）时才走镜像发布。
|
||
---
|
||
|
||
# Builder：DEB / Docker 构建发布
|
||
|
||
复用项目已有发布约定，安全地完成"校验 → 构建 → 检查 → 授权 → 上传 → 验证"。
|
||
|
||
分工原则：**make 管构建，skill 脚本管发布，本 SKILL.md 只留脚本做不了的决策。**
|
||
|
||
## 何时使用
|
||
|
||
- 用户要求构建、发布、上传 `.deb` 包或 Docker/OCI 镜像。
|
||
- 用户要求检查项目 Makefile 是否符合 builder 契约。
|
||
- 用户要求梳理或接通项目现有的 DEB/镜像发布流程。
|
||
|
||
不适用：本地安装/卸载 DEB；RPM/APK/语言包管理器；从零设计全新打包体系（先出方案）；
|
||
普通编码与 Dockerfile 编辑。
|
||
|
||
## 工作流
|
||
|
||
### 0. 校验契约
|
||
|
||
```bash
|
||
python3 -I -S <skill-dir>/scripts/check.py <project-dir> # 静态检查
|
||
python3 -I -S <skill-dir>/scripts/check.py <project-dir> --build # 额外实构 deb 并核对产物
|
||
```
|
||
|
||
任一 FAIL：停下修复（引导用 create-makefile skill 补齐），不要绕过校验继续发布。
|
||
完整要求见 [contract.md](references/contract.md)。存量项目未接契约时走第 6 节
|
||
fallback；成功交付一次后引导用户迁移到契约。
|
||
|
||
### 1. 确认发布边界
|
||
|
||
上传是外部写操作。仅当用户明确要求发布、上传或提交时执行；只要求查看、诊断或构建
|
||
则停在相应阶段。
|
||
|
||
执行上传前确认：
|
||
|
||
- 目标服务和仓库来自项目配置（`.env`）或用户输入，不猜测生产端点。
|
||
- 认证令牌已通过环境变量或密钥系统提供；绝不写入命令输出、文件、提交或回复，
|
||
不用 `set -x` 执行含凭据的命令。
|
||
- 相同版本是否允许覆盖；无法确认且可能覆盖时，先询问。
|
||
- Docker 轨道需要已确定 registry/repository；tag 未给出时按契约「版本号」推导。
|
||
|
||
脏工作树默认拒绝发布；用户明确接受时设置 `ALLOW_UNCOMMITTED=1` 并在汇报中注明
|
||
包含的未提交修改。
|
||
|
||
### 2. 构建
|
||
|
||
```bash
|
||
make build ARCH=<amd64|arm64> VERSION=<version> # 主产物
|
||
make deb ARCH=<amd64|arm64> # DEB 项目
|
||
```
|
||
|
||
版本缺省按契约「版本号」从 Git 祖先稳定 tag 推导（正式 = HEAD exact-match
|
||
的 `vX.Y.Z`；测试 = `X.Y.Z~分支.距离+gSHA`）。不要调用 manage-release 来算
|
||
产物版本，不要用全仓库最新 tag。构建目标若会自动上传而当前仅获构建授权，改用
|
||
纯构建目标。执行前确认所需工具可用（docker、dpkg-deb 等）。不得擅自清理宽泛
|
||
目录；脚本含 `rm -rf` 时先解析确认为受限构建目录。
|
||
|
||
### 3. 上传前检查
|
||
|
||
```bash
|
||
find $(DIST_DIR) -maxdepth 2 -type f -name '*.deb' -print
|
||
<skill-dir>/scripts/verify_deb.sh <exact-package-path.deb> [期望版本] [期望架构]
|
||
```
|
||
|
||
verify_deb.sh 输出元数据、关键内容清单和 SHA-256。匹配到多个包时不凭文件时间猜测，
|
||
向用户确认唯一产物。镜像轨道无需单独校验步骤（publish_docker.sh 自带远端 inspect）。
|
||
|
||
### 4. 发布
|
||
|
||
优先 `make push[-deb|-docker]`（契约要求的薄包装）；直接调用等价：
|
||
|
||
```bash
|
||
DEB_SERVER_URL=… DEB_TOKEN=… DEB_REPOSITORY=… \
|
||
<skill-dir>/scripts/upload_deb.sh <exact-package-path.deb>
|
||
|
||
DOCKER_REGISTRY=… \
|
||
<skill-dir>/scripts/publish_docker.sh # env 优先，flag 可覆盖
|
||
```
|
||
|
||
环境变量缺失时脚本会自动向上查找项目 `.env` 加载（shell 显式值优先）。不把 token
|
||
作为命令行参数；不把脚本复制进项目。upload_deb.sh 默认请求 `/api/v2/upload/package`
|
||
（multipart 字段 `package`/`token`/`repository_name`，接受 200/201），协议不符时设
|
||
`DEB_UPLOAD_PATH` 或改用项目专属逻辑。publish_docker.sh 用 buildx 一步完成构建+推送，
|
||
多平台只能走它，不能拆进 make。
|
||
|
||
### 5. 验证与汇报
|
||
|
||
发布成功不能只依据"curl 已执行"/"push 已执行"。综合检查：
|
||
|
||
- 上传命令退出码为零，HTTP 状态与响应体明确成功；镜像以 `imagetools inspect`
|
||
的远端 digest 为准。
|
||
- 若仓库提供查询/索引/下载地址，确认该版本已可见；索引异步时报告
|
||
"上传已接受，索引尚待更新"，不声称完全可用。
|
||
|
||
最终回复给出：包名/镜像引用、版本、架构/platform、产物路径与 SHA-256 或远端 digest、
|
||
源 commit 与工作区状态、各阶段验证结果、未完成项或覆盖风险。
|
||
|
||
## 存量项目 fallback（legacy）
|
||
|
||
从项目根目录查找，不预设文件位置：
|
||
|
||
```bash
|
||
rg -n -i --hidden --glob '!.git' \
|
||
'build-deb|upload-deb|publish-deb|dpkg-deb|debuild|curl.*deb|\.deb\b|aptly|reprepro'
|
||
```
|
||
|
||
重点检查 Makefile、CI 配置、`debian/`、构建脚本和发布文档中的入口、变量传递方式、
|
||
端点与认证方式。优先复用已有构建入口；上传仍用 builder 脚本。交付后引导迁移到契约
|
||
（create-makefile + check.py 通过为准）。
|
||
|
||
## 修改 builder 自身时
|
||
|
||
- 上传/发布脚本是 SSOT：通用行为修改落在 `skills/builder/scripts/`，不同步复制到
|
||
业务项目。产物版本只通过 `scripts/version.sh` 推导，不要在项目 Makefile 内联
|
||
`git describe` 或 `sort -V`。
|
||
- 契约变更先改 `scripts/check.py`，再同步 `references/contract.md`。
|
||
- 可用 `bash -n` 检查脚本语法；有 ShellCheck 时一并运行。
|
||
- 不通过真实生产上传测试脚本，除非用户明确授权并给出测试版本/仓库。
|
||
|
||
## 完成标准
|
||
|
||
- 仅分析：入口、调用链、配置来源和风险已被准确说明。
|
||
- 仅校验：check.py 结果逐条可解释，修复建议明确。
|
||
- 仅构建：产物已生成并通过 verify_deb.sh，未发生上传。
|
||
- 发布：构建检查通过，服务端接受上传，仓库可见性已验证或准确标记为待更新。
|