Chaos Mesh 仓库开发指南：面向 AI 编码代理与开发者的工程实践手册

云原生运维测试可观测性【免费下载链接】chaos-meshA Chaos Engineering Platform for Kubernetes.项目地址https://gitcode.com/gh_mirrors/ch/chaos-mesh点击查看免费下载本篇技术指南以 Chaos Mesh 仓库根目录的 AGENTS.md 为骨架系统讲解这个 Kubernetes 混沌工程平台代码库的结构、开发命令、控制器设计约束与代码生成流程。读者将掌握如何安全地在这套多 Go 模块仓库中运行聚焦测试与全仓校验、正确触发 CRD/客户端/Swagger 等生成器、遵循控制器单一写入者设计规则并了解从 API 类型改动到 Helm 配置变更的逐类检查清单从而让人类开发者与 AI 编码代理都能高效、不破坏仓库地参与开发。项目概览三大运行时组件Chaos Mesh 是一个面向 Kubernetes 的云原生混沌工程平台cloud-native chaos engineering platform。其运行期组件分为三大部分它们相互配合完成从用户声明混沌实验到节点注入真实故障的完整闭环Chaos Controller Manager协调reconcileChaos Mesh 的各类 CRD 资源包括混沌实验Chaos、定时调度Schedule、工作流Workflow、状态检查StatusCheck以及多集群Multi-cluster资源。Chaos Daemon以特权 DaemonSet 形式运行在每个节点上通过容器运行时、网络设备、文件系统、进程与内核设施执行节点级故障注入。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 模块与关键目录路径职责api/v1alpha1CRD 类型定义、校验/默认值 Webhook 与生成的 API 辅助代码。api/是一个独立的 Go module。controllerscontroller-runtime 协调器。chaosimpl/存放注入/恢复实现common/、action/、schedule/、statuscheck/、multicluster/提供外围控制逻辑。Pod 级的 HTTP、I/O、网络资源分别在podhttpchaos/、podiochaos/、podnetworkchaos/下有专属控制器。pkg共享运行期包包括 Daemon 服务、Dashboard API 与持久化、工作流控制器、选择器、指标与生成的客户端。cmd各二进制入口与仓库生成器。config、helm/chaos-mesh、manifestsKubernetes、Helm 与生成的部署产物。e2e-testGinkgo/Godog 端到端测试套件与 e2e helper其中包含两个额外的 Go module。uipnpm workspace包含 React/TypeScript/Vite 的 Dashboard 与 OpenAPI 代码生成器。build、hack、images容器化构建工具、辅助脚本与镜像定义。需要注意当前仓库共包含四个 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-buildenvdev 环境包含代码生成、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 checkmake 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 diffCI 随后执行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-makefilemake 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 allmake 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_URLhttp://localhost:2333 pnpm startVite dev server 监听 3000 端口并将/api代理到VITE_API_BASE_URL见 ui/vite.config.ts。非交互/CI 安装时如不希望安装 Git hooks 可设置HUSKY0。顶层 Make 目标仅在设置UI1时才构建并内嵌 UI 资产UI1 make ui控制器设计规则变更协调器时必须遵循 controllers/README.md 中沉淀的设计约束一个字段至多由一个控制器拥有不要为同一期望状态引入竞争写入者。多个协调器写同一字段轻则产生冲突重试重则造成矛盾的状态迁移。控制器必须有可独立理解的单机行为不得依赖独立控制器之间未文档化的执行顺序。保持控制器行为小而清晰并为其编写文档若无法清晰概括其行为就应重新考虑资源或控制器的边界。对于应使用 workqueue 限速器的可重试条件仓库约定是ctrl.Result{Requeue: true}, nil应保留周边控制器既有的错误语义而不是机械套用到每个错误上。同时在职责分层上保持一致API 校验/默认值留在 api/v1alpha1编排与状态迁移放在控制器层特权节点操作全部收敛在 Chaos Daemon API 之后。应复用公共 action/pipeline、selector、recorder 与 daemon client 抽象而不是在某个混沌类型内部绕过它们。单一写入者与公共 pipeline从源码结构看公共混沌生命周期的字段所有权被刻意划分desiredphase拥有.status.experiment.desiredPhasecondition拥有.status.conditionsrecords拥有.status.experiment.containerRecordsfinalizers拥有公共 finalizer 生命周期。混沌实现中的Apply/Recover只应作用于一个选定目标并返回结果 phase目标选择、迭代、状态迁移、持久化与重试全部归属公共 pipeline。公共 pipeline 的具体步骤顺序是不可变约定见 controllers/common/pipeline/README.md顺序步骤拥有的状态或效果1finalizers.InitStep为存活的混沌对象添加公共 records finalizer。2desiredphase.Step由删除、一次性行为、持续时间与暂停状态推导Run或Stop。3condition.Step依据当前持久化对象推导 selected/injected/recovered/paused 条件。4records.Step选择目标通过Apply/Recover驱动每条记录走向期望 phase。5finalizers.CleanStep删除恢复完成或强制清理后移除 finalizer。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 前就已满足仓库的格式、生成与测试约定。赞分享云原生运维测试可观测性【免费下载链接】chaos-meshA Chaos Engineering Platform for Kubernetes.项目地址https://gitcode.com/gh_mirrors/ch/chaos-mesh点击查看免费下载相关推荐Chaos Mesh 仓库开发指南为 AI 编码代理梳理的 Kubernetes 混沌工程平台工程手册Chaos Mesh 仓库开发指南为 AI 编码代理梳理的 Kubernetes 混沌工程平台工程手册 Chaos Mesh 是一个面向 Kubernetes云原生运维测试可观测性Lepton 仓库开发指南面向 AI 编码 Agent 与开发者的 Electron React 代码库导航与实践Lepton 仓库开发指南面向 AI 编码 Agent 与开发者的 Electron React 代码库导航与实践 导读 Lepton 是一个基于 Git桌面应用开发工具如何快速上手 Chaos Mesh面向开发者的完整混沌工程实践指南如何快速上手 Chaos Mesh面向开发者的完整混沌工程实践指南 Chaos Mesh 是一个强大的云原生混沌工程平台专门为 Kubernetes 环境设云原生运维测试可观测性创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考