Dagger TypeScript SDK 指南：使用 ContainerWithDockerHealthcheckOpts 为容器配置 Docker 健康检查

Dagger TypeScript SDK 指南使用 ContainerWithDockerHealthcheckOpts 为容器配置 Docker 健康检查【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger导读本文围绕 Dagger 项目 TypeScript SDK 参考文档中的ContainerWithDockerHealthcheckOpts类型别名完整讲解如何通过withDockerHealthcheck为容器配置 Docker 风格的健康检查HEALTHCHECK。你会掌握interval、retries、shell、startInterval、startPeriod、timeout六个可选参数的语义与取值范围并通过仓库源码core/schema/container.go理解它们如何映射为 OCI 镜像配置中的Healthcheck字段最终能在实际流水线如服务就绪探测、集成测试中编写可运行的类型安全代码。类型别名定义ContainerWithDockerHealthcheckOpts是 Dagger TypeScript SDK 自动生成的选项对象类型用作Container.withDockerHealthcheck()的可选参数。根据 关联文档 的定义ContainerWithDockerHealthcheckOpts object它是一个纯对象类型所有属性均为可选项结构如下属性类型必填说明示例intervalstring否两次健康检查之间的间隔时长30sretriesnumber否容器被标记为 unhealthy 之前允许的连续失败次数上限3shellboolean否为 true 时args必须是单个元素并通过容器的 shell 执行truestartIntervalstring否启动阶段startup phase内两次检查之间的间隔时长5sstartPeriodstring否启动初始期内允许失败而不计入重试次数上限0stimeoutstring否单次健康检查的超时时间3s该类型与 Dockerfile 中的HEALTHCHECK指令语义一一对应便于熟悉 Docker 的开发者零成本迁移。在 Dagger 中健康检查最终被写入容器的 OCI 镜像配置cfg.Healthcheck从而在服务运行阶段被引擎/编排系统感知。典型用法在 TypeScript 中配置健康检查withDockerHealthcheck的第一个参数args健康检查命令是必填的选项对象作为第二个参数传入import { dag } from dagger.io/dagger const ctr dag .container() .from(nginx:alpine) .withDockerHealthcheck([curl, -f, http://localhost/ ], { interval: 30s, // 检查间隔 timeout: 3s, // 单次检查超时 startPeriod: 0s, // 启动宽限期 startInterval: 5s, // 启动阶段内的检查间隔 retries: 3, // 连续失败 3 次后标记为 unhealthy })也可以使用 shell 模式将命令合并为单个字符串交由容器 shell 执行const ctr dag .container() .from(node:20-alpine) .withDockerHealthcheck([wget -qO- http://localhost:3000/health || exit 1], { shell: true, interval: 10s, retries: 5, })当shell为true时args数组必须且只能包含一个元素该元素会以CMD-SHELL形式写入否则args会被包装为CMD形式的可执行命令数组。参数逐一详解与底层实现args 与 shell命令形态的两种模式withDockerHealthcheck的 GraphQL 定义见 base_schema.graphqls中args为必填的[String!]!shell为可选布尔值。在 Go 端WithHealthcheckArgs结构体完整对应这些字段core/schema/container.gotype WithHealthcheckArgs struct { Args []string Shell dagql.Optional[dagql.Boolean] Timeout dagql.Optional[dagql.String] Interval dagql.Optional[dagql.String] StartPeriod dagql.Optional[dagql.String] StartInterval dagql.Optional[dagql.String] Retries dagql.Optional[dagql.Int] }核心处理逻辑位于withHealthcheckcore/schema/container.goshelltrue时若args长度不等于 1直接返回错误WithHealthcheck args must be a single element when shell mode is set并将Test前缀设为CMD-SHELLshellfalse默认时若args为空则报错WithHealthcheck args is missingTest前缀为CMD。这与 Docker 的HEALTHCHECK CMD与HEALTHCHECK CMD-SHELL两种形态完全对齐CMD直接执行命令数组不做 shell 解析CMD-SHELL则交给容器默认 shell 解释执行支持管道、环境变量展开等。interval检查间隔interval表示两次健康检查之间的间隔类型为 Go 侧的time.Duration字符串因此必须符合time.ParseDuration语法如30s、1m、500ms。未设置时不写入该字段由运行时采用默认值Docker 默认 30s。源码中通过time.ParseDuration解析后赋值给healthcheck.Intervalcore/schema/container.go解析失败会直接返回错误。timeout单次检查超时timeout限制单次健康检查命令的执行时长超时即视为本次失败。同样使用time.ParseDuration解析core/schema/container.go文档示例值为3s。startPeriod启动宽限期startPeriod是容器刚启动时的宽限期在此期间发生的检查失败不计入retries上限适合冷启动较慢的服务如 JVM 应用、加载大模型的推理服务。文档示例默认0s即默认无宽限。解析逻辑见 core/schema/container.go。startInterval启动阶段检查间隔startInterval控制启动阶段startup phase内两次检查之间的间隔。与startPeriod配合使用时可以让启动期间采用更密集/更宽松的探测节奏待服务就绪后再切换为常规interval。示例值5s解析逻辑见 core/schema/container.go。retries连续失败次数上限retries为整数类型表示在容器被标记为unhealthy之前允许的连续失败次数。文档示例值为3。在源码中被转换为 Go 的int后写入healthcheck.Retriescore/schema/container.go。结果写入 OCI 镜像配置无论设置哪些参数最终都会通过UpdateImageConfig将完整的HealthcheckConfig写入容器的 OCI 镜像配置core/schema/container.goreturn parent.UpdateImageConfig(ctx, func(cfg dockerspec.DockerOCIImageConfig) dockerspec.DockerOCIImageConfig { cfg.Healthcheck healthcheck return cfg })这意味着健康检查信息是镜像配置的一部分与 Docker/OCI 运行时生态天然兼容。同时Dagger 采用惰性求值lazy evaluation架构withDockerHealthcheck会创建一个ContainerWithHealthcheckLazy节点见 core/container.go只有当该容器真正被使用时如执行、导出镜像才会物化并生效从而避免无谓的计算开销。读取与移除健康检查与设置配套Dagger 容器 API 还提供了两个相关操作dockerHealthcheck()读取容器当前已配置的健康检查返回HealthcheckConfig对象包含args、shell、interval、timeout、startPeriod、startInterval、retries字段见 core/schema/container.gowithoutDockerHealthcheck()移除容器上已配置的健康检查实现为将cfg.Healthcheck置为nilcore/schema/container.go。三者均为不可变操作每次调用都返回一个新的容器对象原容器不受影响这符合 Dagger 的纯函数式构建模型。从 GraphQL 到 SDK 的代码生成链路ContainerWithDockerHealthcheckOpts并非手写代码而是由 Dagger 的代码生成器从 GraphQL Schema 自动生成的。Schema 中withDockerHealthcheck的参数定义base_schema.graphqls同时驱动了 Go、TypeScript、Python 等多个 SDK 的客户端生成。以 Go 客户端为例生成的调用签名保留了所有选项参数见 dagger.gen.gofunc (r *Container) WithDockerHealthcheck(args []string, opts ...ContainerWithDockerHealthcheckOpts) *Container { q : r.query.Select(withDockerHealthcheck) // shell optional argument if !querybuilder.IsZeroValue(opts[i].Shell) { q q.Arg(shell, opts[i].Shell) } // ... interval / timeout / startPeriod / startInterval / retries 同理 }生成器只把非零值的选项追加为 GraphQL 查询参数因此未设置的字段不会出现在请求中服务端将按默认行为处理。这套从 GraphQL Schema 到各语言类型化客户端的生成管线保证了ContainerWithDockerHealthcheckOpts的属性与 core/schema/container.go 中定义的参数完全一致文档、Schema、实现三者不会漂移。实战建议冷启动服务为 JVM/推理模型等启动缓慢的服务设置startPeriod如30s并在启动阶段使用独立的startInterval避免误判短生命周期任务在withExec之前调用withDockerHealthcheck配合dockerHealthcheck()在流水线内断言服务就绪后再执行依赖该服务的测试步骤严格校验注意shell: true时args必须是单元素数组且所有时长字段必须符合 Go 的time.ParseDuration格式支持h、m、s、ms、us、ns单位否则 Dagger 引擎会返回解析错误。延伸阅读类型别名原始参考ContainerWithDockerHealthcheckOpts服务端参数定义与校验逻辑core/schema/container.go 与 withHealthcheck 实现GraphQL Schema 定义base_schema.graphqls惰性求值节点core/container.go各语言 SDK 的生成客户端示例dagger.gen.go【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考