企业官网建设流程全解析

• 云原生
• 运维
• 测试
• 可观测性

本篇技术指南以 Chaos Mesh 仓库根目录的 AGENTS.md 为骨架，系统讲解这个 Kubernetes 混沌工程平台代码库的结构、开发命令、控制器设计约束与代码生成流程。读者将掌握如何安全地在这套多 Go 模块仓库中运行聚焦测试与全仓校验、正确触发 CRD/客户端/Swagger 等生成器、遵循控制器"单一写入者"设计规则，并了解从 API 类型改动到 Helm 配置变更的逐类检查清单，从而让人类开发者与 AI 编码代理都能高效、不破坏仓库地参与开发。

项目概览：三大运行时组件

Chaos Mesh 是一个面向 Kubernetes 的云原生混沌工程平台（cloud-native chaos engineering platform）。其运行期组件分为三大部分，它们相互配合完成从"用户声明混沌实验"到"节点注入真实故障"的完整闭环：

1. Chaos Controller Manager：协调（reconcile）Chaos Mesh 的各类 CRD 资源，包括混沌实验（Chaos）、定时调度（Schedule）、工作流（Workflow）、状态检查（StatusCheck）以及多集群（Multi-cluster）资源。
2. Chaos Daemon：以特权 DaemonSet 形式运行在每个节点上，通过容器运行时、网络设备、文件系统、进程与内核设施执行节点级故障注入。
3. Chaos Dashboard：一个 Go API 服务端加上 React Web 界面，用于创建与观测混沌实验。

从源码装配上看，Controller Manager 通过 Uber Fx 依赖注入框架组装所有控制器：controllers/fx.go中的controllers.Module同时提供 Chaos Daemon 客户端构建器、事件记录器、公共 pipeline 步骤与远程集群注册表，并加载chaosimpl.AllImpl中注册的全部故障注入实现，最终由 cmd/chaos-controller-manager 入口加载，细节可参考 controllers/README.md。

仓库地图：四大 Go 模块与关键目录

需要注意，当前仓库共包含四个 Go module：根模块、api/、e2e-test/、e2e-test/cmd/e2e_helper/，全部声明 Go 1.25.11（见根目录 go.mod 第 3 行）。UI 侧 CI 使用 Node.js 24 与 pnpm 11。一旦这些版本发生变化，应以仓库内检入的go.mod、UI 包清单与 CI 工作流为准，它们是版本事实的唯一来源。

在仓库中安全工作

开发前应养成几条工作纪律，这也是为 AI 编码代理设定的硬性约束：

• 编辑前先执行git status --short查看现场，保留用户无关的改动；未经确认不要丢弃任何生成或格式化产生的变更。
• 迭代时优先运行"最窄的相关测试"，仅在聚焦检查通过、且 Docker/时间成本合适时才运行全仓库检查。
• 绝大多数顶层 Make 目标使用容器化的 dev/build 环境，首次运行可能构建 Docker 镜像；宿主机专属的二进制目标会显式以local/前缀命名。
• make check、make test、make generate并非只读操作：它们可能重写生成代码、清单、模块文件、格式化后的 Go 文件或测试产物。运行后务必审查 diff，只保留与任务相关的改动。
• 除非任务确实需要且具备可随时销毁的 Kubernetes 集群，否则不要运行 e2e 测试——该套件会安装资源并注入真实故障。
• 不要直接编辑生成文件：应修改其源文件，再运行对应的生成器。

开发命令总览

运行make help可查看当前检出支持的完整目标列表。由于 Makefile 求值会计算镜像标签，即使 Docker 不可用，make help也可能输出一条 Docker socket 警告，但目标列表本身依然可用。

构建环境

make image-dev-env make image-build-env make enter-devenv make enter-buildenv

dev 环境包含代码生成、lint 与测试工具；build 环境用于产出生产二进制与原生辅助对象。

聚焦的 Go 测试

当宿主机具备所需的 Go/CGO 与 envtest 依赖时，直接用常规 Go 包选择方式快速迭代：

go test ./path/to/package go test ./path/to/package -run TestName (cd api && go test ./v1alpha1/...)

注意从拥有该包的 module中运行测试。仓库级的标准测试是：

make test

从 Makefile 的test目标可见其完整流程：先生成代码与原生测试工具（generate manifests test-utils），再启用 failpoint 插桩，以串行方式（-p 1）带覆盖率运行根模块与api/模块的全部包测试，最后禁用 failpoint。若该目标中途被中断或失败，请先运行make failpoint-disable再继续。make coverage基于已存在的cover.out渲染报告，文件不新鲜时应先跑make test。

验证：make check 与独立检查

日常开发中不要动辄跑make check，而应使用聚焦的包测试、编译与变更相关检查；仅当变更范围有限时，才运行对应的小范围独立检查。全量校验应保留给最终验证、跨领域大改动或显式要求：

make check

make check是 CI 主验证任务的核心，其目标依赖链为generate vet lint fmt tidy helm-values-schema（见 Makefile），覆盖仓库级代码生成、go vet、revive（配置见 revive.toml）、goimports、全部四个 module 的go mod tidy以及 Helm values schema 生成。部分步骤会重写已跟踪文件，之后务必检查git diff；CI 随后执行git diff --quiet，要求这些检查不留下任何未提交的生成或格式化输出。

• make fmt使用goimports格式化所有手写 Go 文件，并带-local github.com/chaos-mesh/chaos-mesh分组参数，它不是单包命令。
• 独立的make vet、make lint、make tidy分别执行make check的对应环节。
• make gosec-scan是独立的、非阻塞的安全报告，不属于make check的一部分。

代码生成

make generate make proto make generate-makefile

• make generate是 CRD/Helm 清单、deepcopy 方法、类型化 clients/informers/listers、Chaos Mesh API 辅助代码与 Dashboard Swagger 输出的"总生成器"，其依赖链为manifests/crd.yaml generate-deepcopy generate-client chaos-build swagger_spec。它已包含manifests/crd.yaml，除非只需要合并清单，否则不要单独再跑该目标。
• 修改 daemon 或 kernel 的 protobuf 定义后运行make proto，它会遍历 pkg/chaosdaemon/pb 与 pkg/chaoskernel/pb 生成.pb.go。
• 根目录的 binary.generated.mk、local-binary.generated.mk、container-image.generated.mk 都标注DO NOT EDIT：应修改 cmd/generate-makefile 下的生成器，再运行make generate-makefile。
• 名为zz_generated.*的文件、pkg/client/下的客户端、protobuf 输出、Swagger 文档以及带自动生成头部的 UI 文件，都必须从源文件重新生成，不能手工修补。

API/CRD 变更后，应把生成的 Go 代码、config/crd/bases、helm/chaos-mesh/crds 与 manifests/crd.yaml 的改动放在一起检查。

构建二进制与镜像

宿主机构建仅针对local-binary.generated.mk中声明的两个目标：

make local/chaos-controller-manager make local/chaos-dashboard

没有local/chaos-daemon目标：daemon 依赖 CGO 与原生辅助对象（从 binary.generated.mk 可见其构建依赖pkg/time/fakeclock/fake_clock_gettime.o等），必须走生成的 build 环境目标或以镜像方式构建。

make image make all

make image构建 controller-manager、daemon 与 dashboard 三个容器镜像；make all额外生成合并后的 CRD 清单。两者都是昂贵的 Docker 构建，不能替代聚焦编译或测试。

UI 开发

当前 UI 技术栈为 React、TypeScript、Vite、Material UI、TanStack Query 与 Zustand，相关命令在ui/目录下执行：

pnpm install --frozen-lockfile pnpm build pnpm test pnpm -F @ui/app lint VITE_API_BASE_URL=http://localhost:2333 pnpm start

Vite dev server 监听 3000 端口，并将/api代理到VITE_API_BASE_URL（见 ui/vite.config.ts）。非交互/CI 安装时，如不希望安装 Git hooks 可设置HUSKY=0。顶层 Make 目标仅在设置UI=1时才构建并内嵌 UI 资产：

UI=1 make ui

控制器设计规则

变更协调器时必须遵循 controllers/README.md 中沉淀的设计约束：

1. 一个字段至多由一个控制器拥有：不要为同一期望状态引入竞争写入者。多个协调器写同一字段，轻则产生冲突重试，重则造成矛盾的状态迁移。
2. 控制器必须有可独立理解的单机行为，不得依赖独立控制器之间未文档化的执行顺序。
3. 保持控制器行为小而清晰，并为其编写文档；若无法清晰概括其行为，就应重新考虑资源或控制器的边界。
4. 对于应使用 workqueue 限速器的可重试条件，仓库约定是ctrl.Result{Requeue: true}, nil；应保留周边控制器既有的错误语义，而不是机械套用到每个错误上。

同时在职责分层上保持一致：API 校验/默认值留在 api/v1alpha1，编排与状态迁移放在控制器层，特权节点操作全部收敛在 Chaos Daemon API 之后。应复用公共 action/pipeline、selector、recorder 与 daemon client 抽象，而不是在某个混沌类型内部绕过它们。

单一写入者与公共 pipeline

从源码结构看，公共混沌生命周期的字段所有权被刻意划分：desiredphase拥有.status.experiment.desiredPhase，condition拥有.status.conditions，records拥有.status.experiment.containerRecords，finalizers拥有公共 finalizer 生命周期。混沌实现中的Apply/Recover只应作用于一个选定目标并返回结果 phase，目标选择、迭代、状态迁移、持久化与重试全部归属公共 pipeline。

公共 pipeline 的具体步骤顺序是不可变约定，见 controllers/common/pipeline/README.md：

CleanStep 必须位于 records 之后，否则删除中的对象会在恢复完成前被提前释放。另外要注意一个启用陷阱：Pipeline.AddSteps在某个步骤工厂返回nil时会停止添加后续所有步骤，而不是只跳过该步骤，因此公共阶段应作为一个有序整体对待。

错误与 requeue 语义

仓库当前使用 controller-runtime v0.21，其 reconcile 契约如下：

• return ctrl.Result{}, err：结果被忽略，非终结性错误按指数退避重试；
• return ctrl.Result{RequeueAfter: delay}, nil：在已知延迟后再次协调，适合期限或显式轮询；
• return ctrl.Result{}, nil：协调完成，直到被观察事件再次入队；
• return ctrl.Result{}, reconcile.TerminalError(err)：记录错误但不重试，仅当重试无法推进时才使用。

不要同时返回非零 Result 与非 nil error，因为 controller-runtime 会忽略该 Result。ctrl.Result.Requeue在当前版本已被弃用：只有真正的可重试失败才应返回错误（错误会被记录并计入协调错误指标），预期等待优先用被观察事件或显式RequeueAfter。既有的Requeue: true路径提供带限速的 requeue 且不报错，应保留其行为直到被刻意迁移。此外，当删除是预期解释时，把NotFound当作成功完成处理。

新增或修改控制器

修改既有控制器时：识别它拥有的字段与外部副作用；把业务逻辑放在可测试的协调器或 helper 而非 Fx bootstrap 中；优先使用 controllers/utils/builder 的Default构建器；为新的顶层控制器用稳定的ShouldSpawnController名称做开关（pkg/config/controller.go中ENABLED_CONTROLLERS环境变量默认值为"*"）；在最窄的 Fx 模块中注册新 provider/bootstrap，再按需并入controllers.Module；为正常协调、删除、冲突、重试与幂等性补充聚焦测试。

新增顶层混沌 Kind 时还需：在 api/v1alpha1 定义并标记 API 类型；在chaosimpl/下实现单目标的Apply/Recover；由实现的 Fx 模块提供ChaosImplPair并纳入chaosimpl.AllImpl；最后运行make generate并检查生成的 API 代码、客户端、CRD、workflow/schedule 注册与前端映射。

变更特定检查清单

按改动类型选择最小必要的验证组合：

• Go 实现：聚焦包测试与格式化；确需全量验证时再跑make check/make test。
• CRD 或 Webhook：运行make generate、聚焦的api/测试，并检查全部清单与生成的客户端。
• Protobuf：运行make proto，客户端与服务端包都要测试。
• Dashboard Go API：运行聚焦的pkg/dashboard/...测试，API 表面变化时重新生成 Swagger/OpenAPI 相关产物。
• UI：从ui/运行pnpm -F @ui/app lint、pnpm build、pnpm test。
• Helm values/chart：用make helm-values-schema重新生成 helm/chaos-mesh/values.schema.json，并运行相关pkg/helm/...测试。
• 生成的构建清单：修改 cmd/generate-makefile，运行make generate-makefile，检查三个生成的 Makefile。

若需要创建提交，请使用git commit --signoff以满足 DCO 合规要求；除非任务显式要求，否则不要创建提交。

总结

这份指南把 Chaos Mesh 仓库的开发实践浓缩为一套可执行的规则与命令体系：先通过仓库地图理解四个 Go module 与生成产物的边界，再按"最窄测试优先、全量检查收尾"的节奏推进；代码生成全部走 Makefile 目标而绝不手改生成文件；控制器开发坚守单一写入者、level-based 幂等与显式 pipeline 顺序；最后按变更类型对照检查清单逐项验证。无论由人还是由 AI 编码代理执行，这套流程都能保证改动在进入 CI 前就已满足仓库的格式、生成与测试约定。

• 云原生
• 运维
• 测试
• 可观测性