Cortex 仓库开发指南：构建、测试、架构约定与 CI 排障（基于 AGENTS.md）

• 可观测性
• 时序数据库
• 后端
• 指标监控

本文围绕 Cortex 仓库根目录的 AGENTS.md 展开，这份文件是官方提供给 AI 编码代理（以及人类开发者）在本仓库中开展工作的技术指引，涵盖构建命令、vendored 依赖管理、单元测试与集成测试的运行方式、代码格式与命名约定、写/读路径的架构概览，以及 CI 构建失败的排障流程。读完后你将能够独立完成：本地编译 Cortex 二进制与 Docker 镜像、按 CI 相同配置运行全量测试、理解各组件在数据流中的职责边界，并遵循仓库既定的代码规范提交变更。

项目定位：一个可水平扩展的多租户长期 Prometheus 存储

AGENTS.md 对项目的定位是：Cortex 是一个水平可扩展、高可用、多租户的 Prometheus 指标长期存储方案，采用微服务架构，各组件既可以作为独立进程运行，也可以组合成单一二进制（single binary）运行。这一设计与仓库的实际组织方式是吻合的：

• 主入口位于 cmd/cortex/main.go，负责解析-config.file、注册所有 flag、加载并校验配置，最终调用cortex.New(cfg)启动服务编排；
• 服务编排与配置定义在 pkg/cortex/cortex.go 与 pkg/cortex/modules.go 中，-modules命令行参数可以列出所有可用的 target 模块及其在Alltarget 中的包含关系（见 cmd/cortex/main.go）；
• 仓库同时提供了cmd/query-tee、cmd/test-exporter、cmd/thanosconvert等辅助二进制，Makefile 的约定是"每个含 main.go 的./cmd/*目录都会构建为一个二进制"。

构建命令：Makefile 是主要入口

AGENTS.md 给出的构建命令集合如下，均可直接在仓库根目录执行：

make # Build all (runs in Docker container by default) make BUILD_IN_CONTAINER=false # Build locally without Docker make exes # Build binaries only make protos # Generate protobuf files make lint # Run all linters (golangci-lint, missspell, etc.) make doc # Generate config documentation (run after changing flags/config) make ./cmd/cortex/.uptodate # Build Cortex Docker image for integration tests

结合 Makefile 的源码可以补充这些目标的实际行为：

默认在容器内构建

BUILD_IN_CONTAINER默认值为true（Makefile）。当容器内构建开启时，exes、protos、lint、test、cover、shell、mod-check、check-protos、doc这些目标都会先依赖build-image/.uptodate，然后通过docker run在构建镜像中执行同名目标（Makefile）。这样做的好处是构建环境与 CI 完全一致，本地开发不需要预装 protoc 等工具链。如果本地环境不便使用 Docker，可以用make BUILD_IN_CONTAINER=false回退到宿主机直接构建，此时exes会对 amd64 和 arm64 两个架构分别执行CGO_ENABLED=0 GOARCH=<arch> GOOS=linux go build（Makefile）。

构建产物会打上版本信息：GO_FLAGS通过-ldflags "-X main.Branch=... -X main.Revision=... -X main.Version=..."将 git 分支、短 revision 和 VERSION 文件内容注入到 cmd/cortex/main.go 中声明的Version、Branch、Revision变量，编译标签固定为"netgo slicelabels"（Makefile）。

exes：自动化发现可构建二进制

EXES列表由find . -name 'main.go'动态生成（Makefile），约定是"每个./cmd/<name>/main.go对应构建./cmd/<name>/<name>二进制"。因此 cmd/cortex/main.go、cmd/query-tee/main.go、cmd/test-exporter/main.go、cmd/thanosconvert/main.go 都会被自动纳入构建，无需手工维护目标列表。

protos：protobuf 代码生成

make protos会为仓库中每一个.proto文件生成对应的.pb.go（Makefile）。由于 store gateway 的 RPC 基于 Thanos，其 proto 之间存在相对引用，生成时需要把vendor/github.com/thanos-io/thanos/pkg、vendor/github.com/gogo/protobuf等多个路径一并加入 protoc 的 include 搜索路径（Makefile）。Makefile 中还显式声明了pkg/ring/ring.proto、pkg/ruler/rulespb/rules.proto、pkg/scheduler/schedulerpb/scheduler.proto、pkg/storegateway/storegatewaypb/gateway.proto等关键 proto 与生成文件的依赖关系。CI 会用check-protos（clean-protos protos后执行git diff --exit-code）确保提交的.pb.go与 proto 定义保持同步（Makefile）。

lint：除了 golangci-lint 还有 faillint 包结构检查

make lint不止运行 golangci-lint 和 misspell，还通过go tool faillint强制执行一批包结构约束（Makefile），从源码结构看，这些约束包括：

• 禁止导入黑名单包，例如禁止使用golang.org/x/net/context（应用标准库context）、禁止使用github.com/weaveworks/common/user.ExtractOrgID（应改用github.com/cortexproject/cortex/pkg/tenant包中的TenantID/TenantIDs）；
• pkg/querier不允许依赖pkg/scheduler、pkg/frontend等查询前端相关包，反向亦然，保证查询执行与查询调度的分层清晰；
• 查询路径（scheduler、frontend、tripperware、tenantfederation）必须支持多租户，即要求使用TenantIDs而非单数TenantID；
• 若干包（ingester、flusher、querier、ruler 等）被禁止重新引入全局 loggergithub.com/cortexproject/cortex/pkg/util/log.Logger，以维持依赖注入式的日志传递。

这意味着开发者在新增 import 时，如果不了解这些隐藏约束，代码可能在本地go build通过但make lint失败。

doc：配置文档是生成物

make doc会运行 tools/doc-generator 从 flag 定义出发重新生成配置文档，产物包括 docs/configuration/config-file-reference.md、docs/blocks-storage/compactor.md、docs/blocks-storage/store-gateway.md、docs/blocks-storage/querier.md、docs/guides/encryption-at-rest.md 以及 schemas/cortex-config-schema.json 等（Makefile）。因此 AGENTS.md 才强调"修改 flag/配置后必须运行make doc"，否则提交会造成生成文档与代码不一致。CI 侧对应check-doc目标（doc后校验 git diff 为空，Makefile）。

Vendored 依赖：vendor/ 目录的使用与升级流程

Cortex 使用 Go modules，并且将依赖 vendored 到vendor/目录。AGENTS.md 给出的升级依赖流程是：

go get github.com/some/dependency@version # Update go.mod go mod vendor # Sync vendor folder go mod tidy # Clean up go.mod/go.sum

AGENTS.md 特别强调两点，仓库中都能找到对应证据：

1. 查上游库代码要去 vendor/ 里找。例如 Alertmanager 的内部实现可以直接看vendor/github.com/prometheus/alertmanager/，而不是猜测或拉取远程版本。
2. 不要直接修改 vendored 代码。所有修改都应走上游升级流程。

仓库还内置了make mod-check目标来机器化验证这一点：依次执行go mod download、go mod verify、go mod tidy、go mod vendor，最后用git diff --exit-code -- go.sum go.mod vendor/确认三者一致（Makefile）。提交前跑一次make mod-check可以避免 CI 上的 mod-check 失败。

测试体系：单元测试与集成测试

单元测试

AGENTS.md 给出 CI 配置的单元测试命令：

go test -timeout 2400s -tags "netgo slicelabels" ./...

这与 Makefile 中的test目标一致，差异在于 Makefile 版本额外带-race -count 1（Makefile）。netgo slicelabels这两个构建标签不是随意的：slicelabels标签被广泛用于标签相关的代码路径与测试，netgo则强制使用纯 Go 网络实现。-race开启竞态检测，-count 1禁用缓存保证真实执行。

集成测试

集成测试位于 integration/ 目录，基于 Docker 拉起真实的 Cortex 服务（distributor、ingester、querier、ruler、alertmanager 等）进行端到端验证。运行步骤如下：

make ./cmd/cortex/.uptodate # Build Cortex Docker image first # Run all integration tests go test -v -tags=integration,requires_docker,integration_alertmanager,integration_memberlist,integration_querier,integration_ruler,integration_query_fuzz ./integration/... # Run a specific integration test go test -v -tags=integration,integration_ruler -timeout 2400s -count=1 ./integration/... -run "^TestRulerAPISharding$"

几个值得注意的细节：

• 必须先用make ./cmd/cortex/.uptodate构建本地 Cortex 镜像。该目标触发cmd/cortex/Dockerfile的 docker buildx 构建（同时构建 amd64 与 arm64 平台，Makefile），产物镜像名为quay.io/cortexproject/cortex并打上本地版本号标签。
• build tag 决定启用哪些场景。integration/ 下各测试文件按功能打 tag：integration_ruler对应 ruler 相关测试（如 integration/ruler_test.go）、integration_querier对应查询路径、integration_alertmanager、integration_memberlist（memberlist 版本的 ring）、integration_query_fuzz等。Makefile 的 lint 目标中列出的完整 tag 集合还包括integration_backward_compatibility、integration_configs_db、integration_remote_write_v2等（Makefile）。
• 环境变量控制测试行为。CORTEX_IMAGE指定要测试的 Docker 镜像，未设置时回退到quay.io/cortexproject/cortex:latest，这一逻辑可以直接在 integration/e2ecortex/services.go 的GetDefaultImage()中验证；E2E_TEMP_DIR指定测试临时文件目录，读取逻辑在 integration/e2e/util.go。
• 集成测试框架本身由 integration/e2e/（通用服务编排）与 integration/e2ecortex/（Cortex 特定封装，如NewDistributor、NewIngester等工厂函数）组成，测试用例文件则以*_test.go形式平铺在 integration/ 下，例如 integration/querier_test.go、integration/remote_write_v2_test.go、integration/otlp_test.go。

此外，development/ 目录下提供了多套 docker-compose 开发环境（tsdb-blocks-storage-s3、tsdb-blocks-storage-s3-gossip、tsdb-blocks-storage-s3-single-binary、tsdb-blocks-storage-swift-single-binary），配有compose-up.sh/compose-down.sh脚本，适合在不跑完整集成测试套件的情况下手动调试单个部署形态；docs/getting-started/docker-compose.yaml 则对应"快速入门"文档中的演示环境。

代码格式：goimports 与 Cortex 专属的 import 分组

AGENTS.md 要求使用带-local参数的 goimports：

goimports -local github.com/cortexproject/cortex -w ./path/to/file.go

import 顺序为：标准库、第三方包、Cortex 内部包，三组之间以空行分隔。仓库提供了对应的 IDE 配置参考 docs/contributing/vscode-goimports-settings.json，可以在 VS Code 中直接复用，保证提交前的格式化与仓库一致。

架构概览：写路径、读路径与存储层

AGENTS.md 用简短的分层描述概括了 Cortex 的组件职责，这是理解代码库布局的地图。

写路径

• Distributor（无状态）：通过 remote write 接收样本，做校验后利用一致性哈希分发到 ingester。实现位于 pkg/distributor/distributor.go，其环与客户端池分别在 pkg/distributor/distributor_ring.go 与 pkg/distributor/ingester_client_pool.go。
• Ingester（半有状态）：在内存中保存样本，周期性 flush 成长期存储中的 TSDB block。实现位于 pkg/ingester/ingester.go，flush 逻辑在 pkg/ingester/flush.go。

读路径

• Querier（无状态）：跨 ingester（活跃数据）与长期存储执行 PromQL 查询，入口在 pkg/querier/querier.go；
• Query Frontend（可选，无状态）：查询缓存、拆分与排队，位于 pkg/frontend/；
• Query Scheduler（可选，无状态）：把队列从 frontend 中分离出来以独立伸缩，位于 pkg/scheduler/scheduler.go。

存储层

• Compactor（无状态）：对对象存储中的 TSDB block 做压缩与清理，实现位于 pkg/compactor/compactor.go，并包含 shuffle sharding 规划（pkg/compactor/shuffle_sharding_planner.go）与 partitioned group 相关逻辑；
• Store Gateway（半有状态）：从对象存储按需加载并缓存 block 供查询，位于 pkg/storegateway/gateway.go。

可选服务

• Ruler：执行 recording rules 与告警，位于 pkg/ruler/ruler.go 及 pkg/ruler/manager.go；
• Alertmanager：多租户告警路由，位于 pkg/alertmanager/alertmanager.go；
• Configs API：租户配置管理，位于 pkg/configs/（含 pkg/configs/api/ 与 pkg/configs/db/）。

三个关键模式

AGENTS.md 总结了三个贯穿全仓库的模式，均可在源码中找到落点：

1. Hash Ring：一致性哈希环，后端支持 Consul、Etcd 以及 memberlist gossip，核心实现在 pkg/ring/ring.go，KV 后端适配在 pkg/ring/kv/（含 pkg/ring/kv/memberlist/）。ingester 使用 pkg/ring/lifecycler.go 管理自身在环中的生命周期，store gateway 等组件使用 pkg/ring/basic_lifecycler.go。
2. 多租户：租户隔离通过X-Scope-OrgID请求头实现，租户 ID 的提取与传递统一收敛在pkg/tenant包（前面提到 faillint 禁止使用 weaveworks 旧版user.ExtractOrgID，正是为了把租户语义统一到这个包）。
3. Blocks Storage：基于 TSDB 的存储，block 时间范围为 2 小时，支持 S3/GCS/Azure/Swift 等对象存储后端，bucket 抽象位于 pkg/storage/bucket/，TSDB 相关逻辑位于 pkg/storage/tsdb/。

完整的组件关系与部署形态还可以参考 docs/architecture.md、docs/architecture-diagram.md 与 docs/configuration/arguments.md。

代码约定：写代码前必须知道的四条硬规则

AGENTS.md 列出的代码约定是 CI lint 与 code review 都会检查的内容：

• 禁止全局变量，使用依赖注入。从源码结构看，各组件普遍以结构体 + 构造函数接收依赖（例如 metrics、logger 通过参数传入），这正是 faillint 禁止部分包重新引入全局 logger 的原因。
• Metrics 必须用promauto.With(reg)注册，禁止使用 prometheus 全局 registerer。这样每个组件持有独立的 registerer，避免指标重复注册 panic，并支持测试中单独采集指标。仓库中promauto.With(的用法遍布 pkg/alertmanager/、pkg/api/、pkg/chunk/cache/ 等包，是该约定的直接体现。
• 配置命名：YAML 配置键使用snake_case，CLI flag 使用kebab-case。两者通过 pkg/util/flagext/ 的 flag 注册机制与 pkg/cortex/cortex.go 中的配置结构体映射关联，cmd/cortex/main.go 中的flagext.RegisterFlags(&cfg)正是"先注册 flag 默认值、再加载配置文件覆盖"的关键顺序。
• 日志使用github.com/go-kit/log，而不是旧路径github.com/go-kit/kit/log。仓库代码（如 cmd/cortex/main.go 的github.com/go-kit/log/level导入）统一采用前者。

提交与 PR 要求

AGENTS.md 对提交的硬性要求有三条：

1. DCO 签名：git commit -s -m "message"，为每次提交附带 Signed-off-by 行；
2. 修改 flag 或配置后运行make doc，保证 docs/configuration/config-file-reference.md 等生成文档同步；
3. 用户可见的变更必须在 CHANGELOG 中留条目，仓库根目录的 CHANGELOG.md 即维护位置。

CI 构建失败排查流程

AGENTS.md 中专门给出了一套面向 GitHub Actions 的排障方法论，当需要调查某个 CI run 失败时可以按序执行：

1. 拉取 job 详情：gh api repos/cortexproject/cortex/actions/runs/<run-id>/jobs，先定位失败的 job 与 step。注意gh run view --log只在整个 run 完成后才可用，个别 job 失败时拿不到完整日志；
2. 取 annotations：gh api repos/cortexproject/cortex/check-runs/<job-id>/annotations，在完整日志不可用时仍能拿到关键错误信息；
3. 完整日志：run 结束后用gh run view <run-id> --job <job-id> --log拉全量日志；
4. 定位根因：区分基础设施类失败（如镜像仓库限流、runner 故障）与代码类失败（如测试回归），用git log和gh pr diff判断失败是否与本次 PR 的改动相关；
5. flaky/基础设施问题追溯：用git log、git log -p追查失败代码是何时、由哪个 PR 引入的；
6. （经用户同意后）提交 issue：内容应包含完整错误输出（放在<details>折叠块中，因为 job 链接会过期）、根因分析、引入问题的 PR，以及建议的解决方案；未经授权不要指派或 @ 具体个人。

与 AGENTS.md 的边界：它不覆盖人类使用 AI 工具的政策

AGENTS.md 的最后一节明确了自身定位：它提供的是给 AI 编码代理的技术指引（构建命令、架构、代码约定），而人类在使用 AI 工具准备贡献时应遵守的政策见 GENAI_POLICY.md。此外，贡献流程的通用约定可以在 CONTRIBUTING.md 与 docs/contributing/design-patterns-and-conventions.md 中进一步阅读。

小结

AGENTS.md 实际上浓缩了在本仓库中高效开展开发工作的全部关键信息：以 Makefile 为构建与校验的统一入口（make/make exes/make protos/make lint/make doc/make mod-check），以vendor/目录为准查阅上游依赖，以带构建标签的go test运行与 CI 对齐的单元与集成测试，以 goimports 的-local分组保持 import 风格，以promauto.With(reg)、kebab-case flag、go-kit/log 等约定约束代码风格，并以一套可复制的gh api流程处理 CI 失败。将这些流程内化后，无论是本地开发、提交 PR 还是排查 CI 问题，都能与上游 CI 的判定标准保持一致。

• 可观测性
• 时序数据库
• 后端
• 指标监控