增量质量报告 · dzs/dzs-price-collector · v1.0.107

• 项目：dzs/dzs-price-collector
• 分支：v1.0.107
• 对比区间：76611a2f65039c6da174e89ae35df07100f7a804（base，即 v1.0.106 的提交）→ abe48b17b7acb5b7030bb21607ef4ca46a2a80f8（head）
• 变更文件数：4（1 个 CI 配置 + 1 个 Dockerfile + 2 个文档）
• 质量问题增量：修复 0 条 / 新增 0 条（两版本质量无差异）

---

1. 结论摘要

一句话：这是一次「把编译从容器搬到宿主机、镜像只打包」的工程化重构，方向合理；但它没有修掉让 tag 路由一直断掉的那个测试失败，所以「打 tag 自动部署」这条路本次改版后大概率仍然不通。

---

2. 变更清单

.dockerignore 未改动（本次核对：其排除项为 build/ bin/ tmp/ tests/ coverage/ scripts/ *.md LICENSE .env* 等，不含 server/importharvest/coalbackfill/metricimport/healthcheck，故 Dockerfile 的新 COPY 不会被忽略）。

---

3. 逐项分析

3.1 .gitea/workflows/build.yml

结构变化（job 层面）

合理之处（正向）

• 单 job 串行避免重复编译（作者实测 2:39 → 3:56~5:14），并复用 buildkit 缓存。
• push 增加 3 次重试；buildx 失败时打印完整构建日志再 exit $RC，不会假绿（RC=${PIPESTATUS[0]} 明确取 docker 退出码）。
• concurrency 组保留（防短时间连打两个 tag 产生并发 deploy）。
• actions 改用自建镜像全 URL，去掉了对外网 GitHub Actions 的隐式依赖。

实现细节核对

• go-version-file: go.mod：go.mod:3 为 go 1.25.0，与原 go-version: '1.25' 等价 ✅
• 版本注入链路闭环：go build -ldflags "-X main.BuildVersion=… -X main.BuildTime=… -X main.GitCommit=…" -o server . → 目标符号确实存在于 main.go:44-48（BuildVersion/BuildTime/GitCommit）→ 通过 buildinfo.Set 暴露到 /api/v1/health 的 data.version（见 §6）✅
• deploy 探活脚本读 data.get('version')，与端点字段名 version 匹配 ✅

潜在问题

• 见 §5 R-1 / R-3 / R-4 / R-6 / R-7。

3.2 Dockerfile

• 删除 builder 阶段（golang:1.25-alpine + go mod download + 5 个 go build）与 ARG BUILD_VERSION/BUILD_TIME/GIT_COMMIT。
• 运行阶段由 COPY --from=builder /out/xxx 改为 COPY xxx …（二进制来自仓库根，由 CI 宿主编译产出）。
• 后果：Dockerfile 不再自包含——单独 docker build .（未先宿主编译）会因缺 server 等文件而 COPY 失败。这是有意为之，但改变了既有构建契约（见 R-2）。
• 运行镜像仍为 mcr.microsoft.com/playwright:v1.62.1-noble（需浏览器运行时，保留合理）。

3.3 文档（AGENTS.md / docs/变更审计日志-2026-09.md）

• 记录 v1.0.106 的发版路径与证据，其中明确自述：
  • (a) 启动横幅仍打 W4 新品种[…]（未改，登记为下次随版修）；
  • (b) 「CI 那 3 个 Linux 失败未修（独立的历史欠账）」；
  • (c) 发版不解 412；
  • (d) A 方案首夜效果未验证。
• 文档与本次代码/CI 改动一致，无夸大。⚠️ 其中记录的手动构建口径用的是 docker build --build-arg BUILD_VERSION=…，与新 Dockerfile（已无 ARG）不兼容（见 R-2）。

---

4. 质量问题增量（真实数据）

codescan.issues_diff(base=76611a2…, head=abe48b17…) 结果：

修复 0 条 / 新增 0 条（两版本质量无差异）

原因：本次改动不涉及任何 Go / JS 源码文件（仅 .yml / Dockerfile / .md），故质量地图无变化。

存量背景（仅供参考，非本次引入）：quality_list 当前共 777 条，样本全部落在 Node 侧（browserworker/*.mjs），典型为「高耦合」「圈复杂度过高」「异步函数中的同步阻塞调用」「行过长」等 Maintainability/Dependency/Concurrency 类；与本次 CI/Dockerfile 改动无关联，不计入本次增量。

---

5. 风险清单（分级）

🔴 R-1（高）本次重构没有解除 tag 路的失败根因

• 证据链：AGENTS.md（本次新增条目）记 CI 运行 1351 在 「脚本语法（bash -n / node --check）」步失败，Docker Build & Push 与 Deploy 均 skipped；对照 v1.0.100 运行 1184 失败在同一步；并自述「CI 那 3 个 Linux 失败未修」——即 credentials.test.mjs 1 失败 / ui-harvest.test.mjs ERR_MODULE_NOT_FOUND / trusted-browser.test.sh 3 失败。
• 新 build.yml 中该步原样保留且 set -e，会无条件执行上述三个脚本；runner 为 Linux（cxy-ubuntu）⇒ 同一步仍会失败，build-push 在到达宿主编译/buildx 之前即中断，deploy 继续被 skip。
• 影响：本次 CI 重构在「tag→自动部署」这条路上的实际收益为 0；宿主编译、buildx 打包、90s 轮询部署等新步骤在本仓 CI 中从未真正执行过（未经线上验证）。
• 建议：先把 3 个 Linux 失败修掉（或在未修期间将该步降为非阻断/加 continue-on-error 并显式告警），否则打 v1.0.107 的 tag 仍不会触发有效部署。

🟠 R-2（中）Dockerfile 不再自包含 + 与既有手动构建口径冲突

• 新 Dockerfile 无 builder 段、无 ARG，需先宿主编译出 5 个二进制再 docker build .，否则 COPY server … 直接失败。
• 而 AGENTS.md / A-34 记录的实际在用的手动构建仍是 docker build --build-arg BUILD_VERSION=…——该命令对新 Dockerfile 既不能注入版本（无 ARG），也会因缺二进制而失败。
• 影响：v1.0.106 正是靠这条手动路发的版；v1.0.107 若再走手动路会踩坑。
• 建议：同步更新手动构建文档为「宿主编译 → docker build .，版本由 -ldflags -X 注入」，并说明 tag 路与手动路的一致性。

🟠 R-3（中）buildx 输出/驱动的隐含假设未在 CI 验证

• docker buildx build --progress=plain --cache-from … --cache-to … -t "$IMAGE:$TAG" . 未加 --load。
  • 若 runner 上 buildx 默认 builder 为 docker-container 驱动，构建结果不会进入本地 docker images，随后 docker tag/docker push 会因「No such image」失败（好消息：会显式非零退出，不会假绿）。
  • --cache-to/from type=local 对 docker 驱动的支持有限，缓存可能不生效。
• 建议：在 runner 上确认 docker buildx ls 默认驱动；必要时显式 --load（或 --push）。

🟡 R-4（低）探活版本校验在「版本为空」时静默放行

• build.yml 探活步：if tag and ver and tag not in str(ver): 失败。当端点未返回 version（ver 为空）时判定通过 ⇒ 可能出现「容器可访问但版本未知」被算作成功。
• 建议：ver 为空时至少打 ::warning:: 或判失败。

🟡 R-5（低）「python 必须单行」规则与实际不一致

• 文件头注释声明「run: | 块内 python 必须单行（多行缩进导致 Gitea YAML 解析失败，tag 不触发）」；但「探活并校验版本」步仍保留多行 python，规则与实现不一致。
• 结合 R-1：deploy 长期被 skip，该步在本仓历史中可能从未成功执行，属未验证表面。
• 建议：统一为单行，或实测确认该步可正常解析执行。

🟡 R-6（低）buildkit 缓存 key 与实际依赖不完全一致

• 缓存 key 用 hashFiles('Dockerfile', 'go.sum')，但影响镜像层的实际输入是宿主编译产物（其内容随源码变化），且 go.mod 未纳入 key。仅影响缓存命中效率，不影响正确性。

🟡 R-7（低）删除 go build ./... 后的编译覆盖

• 改后只显式编译 5 个目标二进制，不再 go build ./...。由于 go vet ./... + go test -race ./... 会类型检查/编译全部包与测试包，普通编译错误仍能覆盖；仅带 build tag、既不参与 vet 也不参与 test 的包可能漏检。

---

6. 已验证的正向契约（证据）

---

7. 结论与建议

1. 本次改动不改变采集器运行时行为（无源码改动），质量增量 0/0，Dockerfile 与 CI 的工程化方向（宿主编译 + 镜像只打包、缓存、push 重试、部署轮询）合理。
2. 最重要的一条：改版未解决 tag 路失败的根因（R-1）——.gitea/workflows/build.yml 里那个会在 Linux 上失败的「脚本语法」步原样保留。因此「打 tag → 自动部署」这条路本次之后大概率仍不通，新引入的宿主编译/buildx/deploy 轮询步骤在真实 CI 中尚未被验证。建议把修 3 个 Linux 测试失败列为下一批第一优先（或临时非阻断），否则本次重构的收益无法兑现。
3. 次优先：同步更新手动构建文档口径以匹配新 Dockerfile（R-2），并在 runner 上确认/显式化 buildx 驱动与 --load（R-3）。
4. 低优先项 R-4~R-7 建议顺手修正（探活空版本放行、python 单行规则一致性、缓存 key、编译覆盖）。