From a1ba6cb145a4231b79882b874cb65421482740ec Mon Sep 17 00:00:00 2001 From: k2safe Date: Sun, 20 Sep 2026 18:26:00 +0800 Subject: [PATCH] feat: expose build identity for release verification --- Dockerfile | 10 ++++-- docs/21-container-deployment.md | 13 ++++++- docs/api/README.md | 1 + docs/api/health.md | 10 ++++++ docs/release-checklist.md | 2 +- docs/reports/phase-7-regression-status.md | 2 +- internal/buildinfo/buildinfo.go | 37 ++++++++++++++++++++ internal/transport/httpserver/server.go | 8 +++++ internal/transport/httpserver/server_test.go | 9 +++++ 9 files changed, 86 insertions(+), 6 deletions(-) create mode 100644 internal/buildinfo/buildinfo.go diff --git a/Dockerfile b/Dockerfile index 2c949fb..9bbe926 100644 --- a/Dockerfile +++ b/Dockerfile @@ -7,6 +7,9 @@ FROM golang:1.27.1-bookworm@sha256:69a7b9788769bec032d238959b61854e9ae87f57be902 ARG TARGETOS ARG TARGETARCH +ARG VERSION=dev +ARG REVISION=unknown +ARG BUILD_TIME=unknown WORKDIR /src ENV GOWORK=off @@ -14,9 +17,10 @@ COPY go.mod go.sum ./ RUN go mod download COPY . . -RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -trimpath -ldflags='-s -w' -o /out/orbit ./cmd/orbit \ - && CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -trimpath -ldflags='-s -w' -o /out/orbit-migrate ./cmd/orbit-migrate \ - && CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -trimpath -ldflags='-s -w' -o /out/orbit-admin ./cmd/orbit-admin +RUN BUILD_FLAGS="-s -w -X git.yuntuo.hk/k2safe/orbit/internal/buildinfo.Version=${VERSION} -X git.yuntuo.hk/k2safe/orbit/internal/buildinfo.Revision=${REVISION} -X git.yuntuo.hk/k2safe/orbit/internal/buildinfo.BuiltAt=${BUILD_TIME}" \ + && CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -trimpath -ldflags="${BUILD_FLAGS}" -o /out/orbit ./cmd/orbit \ + && CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -trimpath -ldflags="${BUILD_FLAGS}" -o /out/orbit-migrate ./cmd/orbit-migrate \ + && CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -trimpath -ldflags="${BUILD_FLAGS}" -o /out/orbit-admin ./cmd/orbit-admin FROM scratch diff --git a/docs/21-container-deployment.md b/docs/21-container-deployment.md index 52be846..a217559 100644 --- a/docs/21-container-deployment.md +++ b/docs/21-container-deployment.md @@ -17,7 +17,17 @@ docker build --platform linux/amd64 -t registry.example/orbit:dev . docker image inspect registry.example/orbit:dev --format '{{.Id}}' ``` -生产发布应把标签绑定到不可变提交和镜像摘要，并在目标架构重新构建或执行等价的交叉构建核验。`registry.example` 只是占位符，不是平台依赖。 +生产发布应把标签绑定到不可变提交和镜像摘要，并在目标架构重新构建或执行等价的交叉构建核验。构建时可注入版本身份： + +```sh +docker build --platform linux/amd64 \ + --build-arg VERSION=1.0.0 \ + --build-arg REVISION="$(git rev-parse HEAD)" \ + --build-arg BUILD_TIME="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ + -t registry.example/orbit:1.0.0 . +``` + +节点启动后通过 `GET /version` 核对这些值。`registry.example` 只是占位符，不是平台依赖。 ## 2. 迁移、核验和启动 @@ -53,6 +63,7 @@ docker run --rm \ ```text GET /health/live 进程存活 GET /health/ready MySQL、迁移账本及零外键检查 +GET /version 版本、提交和协议身份 ``` `ready` 返回 `503` 时应摘除节点并保留原幂等键；不能把数据库连接失败解释为业务失败。metrics 监听由 `ORBIT_METRICS_ADDR` 单独启用，默认关闭，不应通过公共业务入口暴露。 diff --git a/docs/api/README.md b/docs/api/README.md index 1bf473e..1db68f2 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -8,6 +8,7 @@ | --- | --- | --- | | `GET /health/live` | 已实现 | [健康检查](health.md) | | `GET /health/ready` | 已实现，验证数据库、迁移记录及零外键要求 | [健康检查](health.md) | +| `GET /version` | 已实现，返回版本、提交、构建时间及协议版本，不包含数据库、凭据或租户信息 | [健康检查](health.md) | | 独立监听的 `GET /metrics` | 已实现基础运行指标，默认关闭 | [运行观测](observability.md) | | `/v1/tasks` 提交、查询、分页与待执行取消 | 已实现，P3扩展业务键与创建时间筛选 | [任务接口](tasks.md) / [查询契约](task-queries.md) | | `GET /v1/tasks/{task_id}/source` | 已实现普通、人工重试、计划固定版本及流程历史激活/轮次来源 | [来源查询](task-source.md) | diff --git a/docs/api/health.md b/docs/api/health.md index 22b30a6..d255f94 100644 --- a/docs/api/health.md +++ b/docs/api/health.md @@ -38,6 +38,16 @@ curl -i http://127.0.0.1:8080/health/ready 响应不包含 DSN、数据库错误文本或凭据。检查迁移记录不能发现所有人工 DDL 漂移，运行账户权限和迁移流程仍需受控。 +## GET /version + +返回当前服务的构建和协议身份，不访问数据库，也无需鉴权。该接口适合在滚动发布或故障接管后核对节点是否运行了预期版本。 + +```sh +curl -fsS http://127.0.0.1:8080/version +``` + +响应字段包括 `version`、`revision`、`built_at`、`go_version`、HTTP/Worker/Event 协议版本和 Weave 定义结构版本。默认本地构建使用 `dev`、`unknown`；发布镜像应通过构建参数注入不可变提交和构建时间。响应不包含主机、数据库、凭据或租户信息。 + ## SDK 与运行限制 对应 `Client.Liveness(ctx)` 和 `Client.Readiness(ctx)`，见 [SDK 接入](../sdk/README.md)。HTTP 503 返回 `*orbit.HTTPError`。 diff --git a/docs/release-checklist.md b/docs/release-checklist.md index 13dde46..0441857 100644 --- a/docs/release-checklist.md +++ b/docs/release-checklist.md @@ -8,7 +8,7 @@ | --- | --- | --- | | 服务端与 SDK 代码来自同一提交 | `git rev-parse HEAD`；发布时记录不可变提交 | 待发布候选冻结 | | Go 工具链 | Go 1.27.1；Docker `golang:1.27.1`，真实 `go.mod`/`GOWORK=off` | 模块级 race/vet/build、MySQL 存储/进程组、24 个 SDK 示例及两个独立业务模块真实集成已通过；发布环境仍需复核 | -| 容器发布物 | `make image`；[容器发布说明](21-container-deployment.md) | native linux/arm64 与显式 linux/amd64 镜像构建已通过；生产镜像标签、摘要、签名和目标编排环境仍需冻结 | +| 容器发布物 | `make image`；[容器发布说明](21-container-deployment.md) | native linux/arm64 与显式 linux/amd64 镜像构建已通过，支持注入版本身份并由 `/version` 核对；生产镜像标签、摘要、签名和目标编排环境仍需冻结 | | 服务端单元、竞态、vet、build | `make test && make vet && make build` | Go 1.27.1 Docker 等价命令已通过；宿主机 `make` 因未安装 Go 不能作为本机证据 | | 当前协议线一致 | `make protocol-check` | 已通过：HTTP `/v1`、Worker/Event v1、流程 schema 1 | | SDK 独立性和发布门禁 | `make sdk-check` | Go 1.27.1 Docker 下独立 module、示例和业务模块 race/vet/build 已通过 | diff --git a/docs/reports/phase-7-regression-status.md b/docs/reports/phase-7-regression-status.md index cbb31ad..32b7920 100644 --- a/docs/reports/phase-7-regression-status.md +++ b/docs/reports/phase-7-regression-status.md @@ -8,7 +8,7 @@ | --- | --- | --- | | 服务端单元与竞态、vet、构建 | Docker `golang:1.27.1`，仓库声明版本；`GOWORK=off go test -race ./... && go vet ./... && go build ./...` | PASS | | SDK 与独立示例竞态、vet、构建 | Docker `golang:1.27.1`；SDK 全 module、全部示例、`orbit-load`、`orbit-exec-load`、`orbit-schedule-load`、`orbit-workflow-load`，以及 result-inbox/task-outbox | PASS | -| 容器发布物构建 | `make image`；宿主平台 linux/arm64；显式 `docker build --platform linux/amd64`；镜像内 `GOWORK=off` | PASS；native 与 amd64 镜像均构建成功，包含 `orbit`、`orbit-migrate`、`orbit-admin`，运行用户为非 root；无 DSN 时服务按预期拒绝启动 | +| 容器发布物构建 | `make image`；宿主平台 linux/arm64；显式 `docker build --platform linux/amd64`；带 `VERSION`、`REVISION`、`BUILD_TIME` 构建参数的版本化镜像；镜像内 `GOWORK=off` | PASS；native 与 amd64 镜像均构建成功，包含 `orbit`、`orbit-migrate`、`orbit-admin`，运行用户为非 root；版本化 amd64 二进制包含注入的构建身份，`GET /version` 契约单测通过；无 DSN 时服务按预期拒绝启动 | | 当前协议门禁 | `make protocol-check` | PASS，当前 v1 契约同步 | | 历史 SDK / 服务端任务 API 双向演练 | Go 1.27.1、MySQL 8.4 一次性环境；`make mysql-compatibility`；历史提交 `a50d5fa` | PASS；旧服务端+当前 SDK、当前服务端+旧 SDK 均完成真实任务受理、幂等、查询、分页和取消；不是正式标签或全协议矩阵 | | 外键迁移防回归 | `TestPostRemovalMigrationGuard`；服务端迁移运行时校验 | PASS；000008 以前仅保留兼容清理历史，后续迁移在执行前拒绝引用约束 DDL | diff --git a/internal/buildinfo/buildinfo.go b/internal/buildinfo/buildinfo.go new file mode 100644 index 0000000..20c87b5 --- /dev/null +++ b/internal/buildinfo/buildinfo.go @@ -0,0 +1,37 @@ +// Package buildinfo 提供不包含凭据和业务数据的构建身份信息。 +package buildinfo + +import "runtime" + +// 这些变量由发布构建通过 -ldflags 注入；本地开发保持安全的默认值。 +var ( + Version = "dev" + Revision = "unknown" + BuiltAt = "unknown" +) + +// Info 是服务版本端点返回的固定结构，不包含主机、数据库或租户信息。 +type Info struct { + Version string `json:"version"` // Version 发布版本或本地开发标识。 + Revision string `json:"revision"` // Revision 不可变源码提交标识。 + BuiltAt string `json:"built_at"` // BuiltAt 构建时间，由发布流水线提供。 + GoVersion string `json:"go_version"` // GoVersion 编译器版本。 + HTTPProtocolVersion string `json:"http_protocol_version"` // HTTPProtocolVersion HTTP接口主版本。 + WorkerProtocolVersion string `json:"worker_protocol_version"` // WorkerProtocolVersion Worker WebSocket子协议版本。 + EventProtocolVersion string `json:"event_protocol_version"` // EventProtocolVersion Event WebSocket子协议版本。 + WorkflowSchemaVersion int `json:"workflow_schema_version"` // WorkflowSchemaVersion Weave定义结构版本。 +} + +// Current 返回当前进程的静态构建信息。 +func Current() Info { + return Info{ + Version: Version, + Revision: Revision, + BuiltAt: BuiltAt, + GoVersion: runtime.Version(), + HTTPProtocolVersion: "1", + WorkerProtocolVersion: "1", + EventProtocolVersion: "1", + WorkflowSchemaVersion: 1, + } +} diff --git a/internal/transport/httpserver/server.go b/internal/transport/httpserver/server.go index 0c762fa..646fc08 100644 --- a/internal/transport/httpserver/server.go +++ b/internal/transport/httpserver/server.go @@ -7,6 +7,7 @@ import ( "net/http" "time" + "git.yuntuo.hk/k2safe/orbit/internal/buildinfo" "git.yuntuo.hk/k2safe/orbit/internal/observability" "git.yuntuo.hk/k2safe/orbit/pulse/service" ) @@ -32,6 +33,13 @@ func New(addr string, ready Checker, tasks ...*service.Service) *http.Server { } write(w, http.StatusOK, map[string]string{"status": "ready", "scope": "database_and_schema"}) }) + mux.HandleFunc("GET /version", func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Cache-Control", "no-store") + w.Header().Set("X-Content-Type-Options", "nosniff") + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusOK) + _ = json.NewEncoder(w).Encode(buildinfo.Current()) + }) if len(tasks) > 0 && tasks[0] != nil { registerTasks(mux, tasks[0]) registerHistory(mux, tasks[0]) diff --git a/internal/transport/httpserver/server_test.go b/internal/transport/httpserver/server_test.go index 91900b0..4d5ec92 100644 --- a/internal/transport/httpserver/server_test.go +++ b/internal/transport/httpserver/server_test.go @@ -22,6 +22,15 @@ func TestHealthSeparatesLivenessAndReadiness(t *testing.T) { } } +func TestVersionIsPublicAndBounded(t *testing.T) { + server := New("127.0.0.1:0", nil) + rr := httptest.NewRecorder() + server.Handler.ServeHTTP(rr, httptest.NewRequest(http.MethodGet, "/version", nil)) + if rr.Code != http.StatusOK || !strings.Contains(rr.Body.String(), `"http_protocol_version":"1"`) || strings.Contains(rr.Body.String(), "ORBIT_MYSQL_DSN") { + t.Fatalf("unexpected version response: %d %s", rr.Code, rr.Body.String()) + } +} + func TestMetricsListenerIsSeparateAndOptional(t *testing.T) { metrics := observability.NewRegistry() business := New("", nil)