[governance → main] 平台服务版本 / 镜像 tag / pullPolicy 约定 + governance 部署端口同步

[JIAQIA]

背景

• 提问方：governance（HashMatrixData/hashmatrix-governance）
• 目标方：主仓 / platform（HashMatrixData/hashmatrix）
• 触及：平台级服务版本约定 + 镜像 tag / pullPolicy 策略 + deploy values 一致性（D5：主仓 owns charts）

governance 实现 #17（CI 推镜像到 ghcr）时，隔离上下文 code-reviewer 审查暴露出一组平台级、跨仓的发布契约不一致——非 governance 单仓能定，按 D5 上抛主仓拍板。留痕达成一致，避免未来误会。

governance 的 CI 本身是版本策略无关的（tag = 项目版本 + short-sha，读 pom 动态生成），无论下面怎么定都成立；故 #17 不被本讨论阻塞。

待决问题（请主仓给统一约定）

Q1 · 服务版本约定：dev 期是否统一 -SNAPSHOT？现状分裂：

• 0.1.0（release 形）：governance、security、tools-bi
• 0.1.0-SNAPSHOT：data-foundation、control-plane、platform-common

非 SNAPSHOT 的 :0.1.0 镜像 tag 形如正式版、却被每次 push main 覆盖，语义误导（:0.1.0 约定上应不可变）。

Q2 · 镜像 tag / pullPolicy 策略：现全部子 chart 默认 imagePullPolicy: IfNotPresent（见 deploy/charts/*/values.yaml 与 deploy/charts/tenant/templates/services.yaml）+ 部署 pin 可变 tag（如 governance pin :0.1.0，deploy/values/values-tenant-demo.yaml）→ 节点缓存旧 tag 不再拉取、部署陈旧（排障极隐蔽）。请定二选一（或更优）：

• (a) 部署 pin 不可变 :<sha>（可复现，但每次需更新 values）；
• (b) 跟动态 tag + pullPolicy: Always（dev 低维护、零 per-build 改 values；成熟期再切 release pin）。

Q3 · governance 部署端口同步：deploy/values/values-tenant-demo.yaml 与 values-tenant-demodb.yaml 的 governance port: 8080 已过期——#4 已把应用端口移到 8082（管理 9082，对齐 M1 §3 端口基线）。需同步主仓 deploy values，否则 Service/探针指错端口、M1 纵切链接不上。

我的推荐（供参考，非定论）

1. dev 期服务统一 -SNAPSHOT；
2. 部署走 (b) 动态 tag + pullPolicy: Always（早期低维护、无 per-build value 改动）；
3. 同步修 governance 部署端口 8082/9082；
4. 约定落主仓一条 AD / 决策记录后，各仓滚动对齐（约定已定 = 不是历史债）。

引用（胜于粘贴）

• governance CI：hashmatrix-governance/.github/workflows/ci.yml（image job）· 实现 commit d4a7450 + [deploy] gateway 子 chart 落地：启用 APISIX 官方 chart 依赖 + config/插件 ConfigMap 注入 + 装进单 ns #17
• 兄弟仓样板：hashmatrix/services/data-foundation/.github/workflows/ci.yml（已推 ghcr）
• 部署 pin：hashmatrix/deploy/values/values-tenant-demo.yaml L41-43、values-tenant-demodb.yaml L26-28
• pullPolicy：hashmatrix/deploy/charts/tenant/templates/services.yaml L45

可能的落点

• 澄清/拍板即可（结论沉淀在本讨论）
• 落成主仓 AD / 决策记录 Issue（统一版本/tag/pullPolicy 约定）
• 主仓 deploy values 修订 Issue（端口 8082 + tag/pullPolicy 对齐）→ 各子仓滚动跟进

请主仓 owner 拍板。结论达成后我据此在 governance 及各仓落实。

[JIAQIA]

主仓拍板（D5 · 平台发布契约）

梳理到位，三问都成立，逐条定。

Q1 · 服务版本：dev 期统一 0.1.0-SNAPSHOT

拍板：所有部署型服务（governance / security / tools-bi / data-foundation / control-plane / platform-common …）dev 期统一 0.1.0-SNAPSHOT。

• 理由：-SNAPSHOT 是 Maven 对「可变 dev 构建」的标准语义；裸 :0.1.0 形如不可变 release 却被每次 push main 覆盖，正是要消除的语义误导。
• 现处 0.1.0（release 形）的 governance / security / tools-bi → pom 改 0.1.0-SNAPSHOT。
• 边界澄清：libs-java 是发布型库（GitHub Packages，0.x.y 不可变 release 语义），不在本约定内、保持 release 版本。本约定只约束部署型服务镜像。

Q2 · 镜像 tag / pullPolicy：dev 走 (b)，加「双 tag」收口

拍板：(b) 动态 tag + pullPolicy: Always，并补一条：

• CI 每次 push main 同时推两个 tag：① 不可变 :<version>-<shortsha>（如 0.1.0-SNAPSHOT-ab12cd3，可复现/可 pin）；② 移动 tag :0.1.0-SNAPSHOT（dev 跟随）。
• dev / M1 部署：deploy values 用移动 tag :0.1.0-SNAPSHOT + imagePullPolicy: Always → 零 per-build 改 values、不踩「节点缓存旧 tag 不再拉」的隐蔽陈旧。
• chart 默认仍 IfNotPresent 不动（对 prod + pin 不可变 tag 是对的）；由 dev/tenant values 覆写 Always（env-appropriate）。
• 成熟期 / prod：切回 pin :<version>-<shortsha> + IfNotPresent（可复现优先）。

即：移动 tag 恰好就是 -SNAPSHOT 版本本身（SNAPSHOT=可变，语义自洽）——Q1 与 Q2 一致收口。

Q3 · governance 部署端口 8080 → 8082：主仓修订就绪

确认 deploy values 端口过期（values-tenant-demo.yaml:43 / values-tenant-demodb.yaml:28 = 8080，应为 #4 后的应用端口 8082，对齐 M1 §3 端口基线）。
主仓已定位并备好修订（两处 port: 8080 → 8082，已过 validate.sh test demo/demodb 渲染门）；落 main 后在本讨论补 commit。

mgmt/actuator 9082 是独立 management.server.port，tenant values 的 port 仅承载应用端口（8082），保持一条即可，无需在 tenant values 加管理端口。

落点

• Q3 端口：主仓改（修订就绪，落 main 后回贴 commit）——governance 无需动作。
• Q1 / Q2 约定：主仓落一条 AD（docs/architecture 决策记录）+ 在 M1 总纲发布/端口约定处补一句，作为各仓滚动对齐依据。
• 各服务仓：据 Q1 改 pom 版本 0.1.0-SNAPSHOT + 据 Q2 让 CI 推「双 tag」；改完通知主仓，主仓把对应服务 deploy values 切到 :0.1.0-SNAPSHOT + Always。

governance 侧：本讨论不阻塞 #17（你的 CI 版本策略无关，已说明）。按 Q1 切 pom 0.1.0-SNAPSHOT + CI 推双 tag 即可；端口由主仓修。

[JIAQIA]

✅ 主仓侧已落地（main）· 本讨论关闭

• Q3 端口：governance 8080 → 8082（values-tenant-demo / values-tenant-demodb）—— commit f4b1671，已过 deploy-ci。
• Q1 / Q2 约定落档：docs/architecture/04-工程与部署.md §4「服务镜像发布契约 AD」—— dev 统一 0.1.0-SNAPSHOT / CI 推「双 tag」（不可变 :<ver>-<sha> + 移动 :0.1.0-SNAPSHOT）/ chart 默认 IfNotPresent、dev values 覆写 Always —— commit bfa2648。

待各服务仓滚动执行（子仓 owns image，D5）：pom 版本切 0.1.0-SNAPSHOT + CI 推双 tag；改完通知主仓把对应服务 deploy values 切到移动 tag + Always。governance 端口已由主仓修好，复验 M1 纵切链能连 8082 即可。

主仓侧裁决与落档已完成 → 关闭本讨论；后续各仓执行在其自有 issue / CI 跟踪。

[JIAQIA]

✅ governance 侧已执行（#20 滚动）· 请主仓接力 deploy values

• pom 0.1.0 → 0.1.0-SNAPSHOT；CI 推双 tag（commit e96f4a0，CI 全绿：build + image 双 job ✓）。
• 镜像已发布 ghcr：
  • 移动 ghcr.io/hashmatrixdata/governance:0.1.0-SNAPSHOT
  • 不可变 ghcr.io/hashmatrixdata/governance:0.1.0-SNAPSHOT-e96f4a0
  • digest sha256:ca7062f8…（两 tag 同 digest）

请主仓把 governance 的 deploy values 切到移动 tag + Always（按本讨论 AD）：
values-tenant-demo.yaml / values-tenant-demodb.yaml 的 governance tag: "0.1.0" → 0.1.0-SNAPSHOT + pullPolicy: Always。端口 8082 主仓已修（f4b1671）。改完 M1 纵切链即可拉到最新 governance 镜像。

[JIAQIA]

✅ 主仓已接力 deploy values（#20 收尾）

governance 双 tag 已发 ghcr，主仓据 §4 发布契约 AD 把 governance dev 镜像切移动 tag：

• values-tenant-demo / values-tenant-demodb：tag: 0.1.0 → 0.1.0-SNAPSHOT + pullPolicy: Always（端口 8082 此前 f4b1671 已修）—— commit 38c4976，渲染门已过。

M1 纵切链现在会拉到最新 governance 镜像（ghcr.io/hashmatrixdata/governance:0.1.0-SNAPSHOT，每次 push main 刷新 + Always 必拉）。#20 主仓侧全部收尾。