Dagger TypeScript SDK 中 ContainerWithExposedPortOpts 详解用withExposedPort声明容器端口、协议与健康检查【免费下载链接】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导读ContainerWithExposedPortOpts是 Dagger TypeScript SDK 中Container.withExposedPort(port, opts?)方法的可选参数对象类型用于在构建 Dagger 容器时声明对外暴露的端口及其网络协议、描述信息和健康检查行为。本文基于 Dagger 仓库 v0.19 版本文档与核心源码完整讲解该类型的三个可选属性protocol、description、experimentalSkipHealthcheck的语义、默认值、底层实现原理并结合仓库中的 Schema 定义、核心实现与集成测试给出可运行的实战示例帮助你正确使用 Dagger 暴露端口以驱动服务健康检查与镜像 EXPOSE 元数据。一、类型别名速览ContainerWithExposedPortOpts 是什么ContainerWithExposedPortOpts在 Dagger TypeScript SDK 的生成客户端中是一个对象类型别名Type Alias全部三个属性都是可选的ContainerWithExposedPortOptsobject属性类型必填说明description?string可选端口描述示例payment API endpointexperimentalSkipHealthcheck?boolean可选作为服务运行时跳过健康检查protocol?NetworkProtocol可选网络协议示例tcp该类型对应的官方参考文档位于 ContainerWithExposedPortOpts.md它是withExposedPortGraphQL API 在 TypeScript 客户端中的类型投影定义由代码生成器自动产出。在生成的 TypeScript SDK 源码中其定义位于 sdk/typescript/src/api/client.gen.ts#L721-L736export type ContainerWithExposedPortOpts { /** * Network protocol. Example: tcp */ protocol?: NetworkProtocol /** * Port description. Example: payment API endpoint */ description?: string /** * Skip the health check when run as a service. */ experimentalSkipHealthcheck?: boolean }protocol字段引用自NetworkProtocol枚举见 NetworkProtocol.md因此写代码时可以通过NetworkProtocol.Tcp这样的枚举成员获得编译期类型校验。二、使用场景withExposedPort与 DockerfileEXPOSE的异同ContainerWithExposedPortOpts是Container.withExposedPort(port, opts?)的第二个参数。该方法的作用是暴露一个网络端口其 GraphQL Schema 文档明确说明见 core/schema/container.go#L894-L904Expose a network port. Like EXPOSE in Dockerfile (but with healthcheck support). Exposed ports serve two purposes:For health checks and introspection, when running servicesFor setting the EXPOSE OCI field when publishing the container翻译过来即暴露的端口有两大用途服务健康检查与自省introspection当容器作为 Dagger Service 运行时Dagger 引擎使用暴露的端口对服务进行健康检查和信息探测写入镜像 OCI 元数据当容器被发布publish为镜像时暴露的端口会写入镜像配置的EXPOSE字段与 Dockerfile 中EXPOSE指令的效果一致。这也是withExposedPort与普通 DockerfileEXPOSE的关键差异多了一层健康检查支持——ContainerWithExposedPortOpts.experimentalSkipHealthcheck正是为这一能力服务的详见下文第四部分。Schema 中四个参数的定义与本文类型一一对应// core/schema/container.go#L900-L903 dagql.Arg(port).Doc(Port number to expose. Example: 8080), dagql.Arg(protocol).Doc(Network protocol. Example: tcp), dagql.Arg(description).Doc(Port description. Example: payment API endpoint), dagql.Arg(experimentalSkipHealthcheck).Doc(Skip the health check when run as a service.),三、属性详解protocol、description 的语义与默认值3.1protocol?:NetworkProtocol指定端口的网络协议示例值为tcp。该字段映射到核心层的core.NetworkProtocol枚举并在解析参数时带有默认值TCP。这一点可以从核心 Schema 的参数结构体得到证实core/schema/container.go#L4507-L4512type containerWithExposedPortArgs struct { Port int Protocol core.NetworkProtocol default:TCP Description *string ExperimentalSkipHealthcheck bool default:false }也就是说如果不传protocolDagger 默认按 TCP 协议处理protocol也可选udp等NetworkProtocol枚举中定义的其他取值。NetworkProtocol枚举在 TypeScript 端以值到名称的映射参与序列化withExposedPort生成代码中可以看到该枚举被标记为is_enum并通过NetworkProtocolValueToName进行转换sdk/typescript/src/api/client.gen.ts#L5292-L5294。3.2description?:string为端口附加一段人类可读的描述示例payment API endpoint。描述信息会随Port对象一并存储可用于服务自省、调试输出或生成文档是纯元数据字段不影响端口连通性。在核心实现中它被建模为core.Port结构体上的可选字段*stringport : core.Port{ Protocol: args.Protocol, Port: args.Port, Description: args.Description, ExperimentalSkipHealthcheck: args.ExperimentalSkipHealthcheck, }四、属性详解experimentalSkipHealthcheck 与服务健康检查experimentalSkipHealthcheck?: boolean的官方解释为“作为服务运行时跳过健康检查”Skip the health check when run as a service。从名称中的experimental前缀可以看出这是一个带有实验性质、面向服务Service场景的选项。Dagger 的 Service 机制会在容器作为后台服务启动时对暴露的端口执行健康检查以判断服务是否就绪当该选项为true时这一自动健康检查会被跳过。这在以下场景中很有价值端口本身并不承载可探测的健康检查端点例如纯 UDP 端口服务启动慢且无法提供就绪信号希望避免健康检查导致的误判希望完全由调用方自行控制就绪逻辑。其默认值为false见 core/schema/container.go#L4511 中default:false即默认情况下不跳过健康检查。注意该选项名为experimental表示 API 可能在后续版本演进或调整生产使用前请关注版本迁移说明相关参考CHANGELOG.md、RELEASING.md。五、源码级原理端口如何被记录进容器配置理解了参数语义后再看核心层如何落地这些选项。withExposedPort的 GraphQL 处理器位于 core/schema/container.go#L4514-L4537它会克隆当前容器不可变快照模型把参数组装成core.Port后调用ctr.WithExposedPort(port)并支持惰性执行ContainerWithExposedPortLazy见 core/container.go#L286。真正的状态变更发生在 core/container.go#L6840-L6865 的WithExposedPort实现中其行为要点如下// mutates container caller must have handled cloning or creating a new child. func (container *Container) WithExposedPort(port Port) (*Container, error) { // replace existing port to avoid duplicates gotOne : false for i, p : range container.Ports { if p.Port port.Port p.Protocol port.Protocol { container.Ports[i] port gotOne true break } } if !gotOne { container.Ports append(container.Ports, port) } if container.Config.ExposedPorts nil { container.Config.ExposedPorts map[string]struct{}{} } ociPort : fmt.Sprintf(%d/%s, port.Port, port.Protocol.Network()) container.Config.ExposedPorts[ociPort] struct{}{} container.ImageRef return container, nil }从中可以提炼出三个实现事实去重语义若已存在“相同端口号 相同协议”的端口则用新值替换旧端口避免重复否则追加到container.Ports列表OCI EXPOSE 写入端口会以port/protocol的形式如8080/tcp写入container.Config.ExposedPorts这正是后续镜像发布时写入 OCIEXPOSE字段的数据源镜像失效重置修改暴露端口后container.ImageRef被清空确保缓存命中的镜像引用不会与新的 EXPOSE 配置冲突。与之配套的是withoutExposedPort(port, protocol)core/schema/container.go#L4539-L4562、core/container.go#L6868用于移除之前暴露的端口以及exposedPortscore/schema/container.go#L913-L915用于检索容器当前暴露的全部端口——值得注意的是exposedPorts的文档说明它包含镜像本身已暴露的端口即使未通过 Dagger 显式添加。六、实战示例TypeScript 与 Go 客户端调用6.1 TypeScript本类型的主战场withExposedPort在 TypeScript 生成客户端中的完整签名sdk/typescript/src/api/client.gen.ts#L5288-L5302withExposedPort ( port: number, opts?: ContainerWithExposedPortOpts, ): Container { const metadata { protocol: { is_enum: true, value_to_name: NetworkProtocolValueToName }, } const ctx this._ctx.select(withExposedPort, { port, ...opts, __metadata: metadata, }) return new Container(ctx) }典型用法暴露 8080 端口TCP 协议附带描述并跳过健康检查import { Client, NetworkProtocol } from dagger.io/dagger const client new Client() const ctr client .container() .from(nginx:alpine) .withExposedPort(8080, { protocol: NetworkProtocol.Tcp, description: payment API endpoint, experimentalSkipHealthcheck: true, }) await ctr.publish(registry.example.com/payment-api:latest) // 发布后的镜像 OCI 配置中将包含 EXPOSE 8080/tcp6.2 Go 客户端集成测试中的真实用法仓库集成测试 core/integration/container_test.go 中大量使用了对应选项例如WithExposedPort(5000, dagger.ContainerWithExposedPortOpts{Protocol: dagger.NetworkProtocolTcp})见 core/integration/container_test.go#L4025 等多处以及不带选项的默认调用WithExposedPort(5000)见 core/integration/container_test.go#L5013。这些测试同时验证了暴露端口后容器作为服务启动时的健康检查行为、端口去重语义以及镜像发布时 EXPOSE 元数据的正确性——dockerfile_test.go、services_test.go、localcache_test.go等测试文件也引用了相关机制可从 core/integration 目录继续追踪。Go 客户端中的对应类型dagger.ContainerWithExposedPortOpts可在生成的 dagger.gen.go 中找到结构与 TypeScript 版本一一对应。七、总结与最佳实践围绕ContainerWithExposedPortOpts可以归纳出如下使用要点关注点结论依据默认协议不传protocol时按 TCP 处理core/schema/container.go#L4509重复暴露相同端口 相同协议会被替换而非追加core/container.go#L6841-L6854健康检查服务模式下默认执行健康检查experimentalSkipHealthcheck: true可跳过core/schema/container.go#L903、core/schema/container.go#L4511OCI EXPOSE暴露端口会以port/protocol写入镜像 EXPOSE 配置core/container.go#L6860-L6861反向操作使用withoutExposedPort(port, protocol)取消暴露core/schema/container.go#L906-L911查询使用exposedPorts读取全部暴露端口含镜像自带core/schema/container.go#L913-L915实践建议当容器会被service()/asService()包装并以服务方式运行且暴露的端口没有就绪探针时考虑开启experimentalSkipHealthcheck当端口仅用于发布镜像的 EXPOSE 元数据时保持默认即可。由于该选项带experimental前缀建议在升级 Dagger 版本后通过 CHANGELOG.md 确认其语义是否发生变化。更多 TypeScript SDK 的生成客户端参考可继续翻阅 client.gen 参考目录。【免费下载链接】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），仅供参考 Dagger TypeScript SDK 中 ContainerWithExposedPortOpts 详解：用 `withExposedPort` 声明容器端口、协议与健康检查
Dagger TypeScript SDK 中 ContainerWithExposedPortOpts 详解用withExposedPort声明容器端口、协议与健康检查【免费下载链接】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导读ContainerWithExposedPortOpts是 Dagger TypeScript SDK 中Container.withExposedPort(port, opts?)方法的可选参数对象类型用于在构建 Dagger 容器时声明对外暴露的端口及其网络协议、描述信息和健康检查行为。本文基于 Dagger 仓库 v0.19 版本文档与核心源码完整讲解该类型的三个可选属性protocol、description、experimentalSkipHealthcheck的语义、默认值、底层实现原理并结合仓库中的 Schema 定义、核心实现与集成测试给出可运行的实战示例帮助你正确使用 Dagger 暴露端口以驱动服务健康检查与镜像 EXPOSE 元数据。一、类型别名速览ContainerWithExposedPortOpts 是什么ContainerWithExposedPortOpts在 Dagger TypeScript SDK 的生成客户端中是一个对象类型别名Type Alias全部三个属性都是可选的ContainerWithExposedPortOptsobject属性类型必填说明description?string可选端口描述示例payment API endpointexperimentalSkipHealthcheck?boolean可选作为服务运行时跳过健康检查protocol?NetworkProtocol可选网络协议示例tcp该类型对应的官方参考文档位于 ContainerWithExposedPortOpts.md它是withExposedPortGraphQL API 在 TypeScript 客户端中的类型投影定义由代码生成器自动产出。在生成的 TypeScript SDK 源码中其定义位于 sdk/typescript/src/api/client.gen.ts#L721-L736export type ContainerWithExposedPortOpts { /** * Network protocol. Example: tcp */ protocol?: NetworkProtocol /** * Port description. Example: payment API endpoint */ description?: string /** * Skip the health check when run as a service. */ experimentalSkipHealthcheck?: boolean }protocol字段引用自NetworkProtocol枚举见 NetworkProtocol.md因此写代码时可以通过NetworkProtocol.Tcp这样的枚举成员获得编译期类型校验。二、使用场景withExposedPort与 DockerfileEXPOSE的异同ContainerWithExposedPortOpts是Container.withExposedPort(port, opts?)的第二个参数。该方法的作用是暴露一个网络端口其 GraphQL Schema 文档明确说明见 core/schema/container.go#L894-L904Expose a network port. Like EXPOSE in Dockerfile (but with healthcheck support). Exposed ports serve two purposes:For health checks and introspection, when running servicesFor setting the EXPOSE OCI field when publishing the container翻译过来即暴露的端口有两大用途服务健康检查与自省introspection当容器作为 Dagger Service 运行时Dagger 引擎使用暴露的端口对服务进行健康检查和信息探测写入镜像 OCI 元数据当容器被发布publish为镜像时暴露的端口会写入镜像配置的EXPOSE字段与 Dockerfile 中EXPOSE指令的效果一致。这也是withExposedPort与普通 DockerfileEXPOSE的关键差异多了一层健康检查支持——ContainerWithExposedPortOpts.experimentalSkipHealthcheck正是为这一能力服务的详见下文第四部分。Schema 中四个参数的定义与本文类型一一对应// core/schema/container.go#L900-L903 dagql.Arg(port).Doc(Port number to expose. Example: 8080), dagql.Arg(protocol).Doc(Network protocol. Example: tcp), dagql.Arg(description).Doc(Port description. Example: payment API endpoint), dagql.Arg(experimentalSkipHealthcheck).Doc(Skip the health check when run as a service.),三、属性详解protocol、description 的语义与默认值3.1protocol?:NetworkProtocol指定端口的网络协议示例值为tcp。该字段映射到核心层的core.NetworkProtocol枚举并在解析参数时带有默认值TCP。这一点可以从核心 Schema 的参数结构体得到证实core/schema/container.go#L4507-L4512type containerWithExposedPortArgs struct { Port int Protocol core.NetworkProtocol default:TCP Description *string ExperimentalSkipHealthcheck bool default:false }也就是说如果不传protocolDagger 默认按 TCP 协议处理protocol也可选udp等NetworkProtocol枚举中定义的其他取值。NetworkProtocol枚举在 TypeScript 端以值到名称的映射参与序列化withExposedPort生成代码中可以看到该枚举被标记为is_enum并通过NetworkProtocolValueToName进行转换sdk/typescript/src/api/client.gen.ts#L5292-L5294。3.2description?:string为端口附加一段人类可读的描述示例payment API endpoint。描述信息会随Port对象一并存储可用于服务自省、调试输出或生成文档是纯元数据字段不影响端口连通性。在核心实现中它被建模为core.Port结构体上的可选字段*stringport : core.Port{ Protocol: args.Protocol, Port: args.Port, Description: args.Description, ExperimentalSkipHealthcheck: args.ExperimentalSkipHealthcheck, }四、属性详解experimentalSkipHealthcheck 与服务健康检查experimentalSkipHealthcheck?: boolean的官方解释为“作为服务运行时跳过健康检查”Skip the health check when run as a service。从名称中的experimental前缀可以看出这是一个带有实验性质、面向服务Service场景的选项。Dagger 的 Service 机制会在容器作为后台服务启动时对暴露的端口执行健康检查以判断服务是否就绪当该选项为true时这一自动健康检查会被跳过。这在以下场景中很有价值端口本身并不承载可探测的健康检查端点例如纯 UDP 端口服务启动慢且无法提供就绪信号希望避免健康检查导致的误判希望完全由调用方自行控制就绪逻辑。其默认值为false见 core/schema/container.go#L4511 中default:false即默认情况下不跳过健康检查。注意该选项名为experimental表示 API 可能在后续版本演进或调整生产使用前请关注版本迁移说明相关参考CHANGELOG.md、RELEASING.md。五、源码级原理端口如何被记录进容器配置理解了参数语义后再看核心层如何落地这些选项。withExposedPort的 GraphQL 处理器位于 core/schema/container.go#L4514-L4537它会克隆当前容器不可变快照模型把参数组装成core.Port后调用ctr.WithExposedPort(port)并支持惰性执行ContainerWithExposedPortLazy见 core/container.go#L286。真正的状态变更发生在 core/container.go#L6840-L6865 的WithExposedPort实现中其行为要点如下// mutates container caller must have handled cloning or creating a new child. func (container *Container) WithExposedPort(port Port) (*Container, error) { // replace existing port to avoid duplicates gotOne : false for i, p : range container.Ports { if p.Port port.Port p.Protocol port.Protocol { container.Ports[i] port gotOne true break } } if !gotOne { container.Ports append(container.Ports, port) } if container.Config.ExposedPorts nil { container.Config.ExposedPorts map[string]struct{}{} } ociPort : fmt.Sprintf(%d/%s, port.Port, port.Protocol.Network()) container.Config.ExposedPorts[ociPort] struct{}{} container.ImageRef return container, nil }从中可以提炼出三个实现事实去重语义若已存在“相同端口号 相同协议”的端口则用新值替换旧端口避免重复否则追加到container.Ports列表OCI EXPOSE 写入端口会以port/protocol的形式如8080/tcp写入container.Config.ExposedPorts这正是后续镜像发布时写入 OCIEXPOSE字段的数据源镜像失效重置修改暴露端口后container.ImageRef被清空确保缓存命中的镜像引用不会与新的 EXPOSE 配置冲突。与之配套的是withoutExposedPort(port, protocol)core/schema/container.go#L4539-L4562、core/container.go#L6868用于移除之前暴露的端口以及exposedPortscore/schema/container.go#L913-L915用于检索容器当前暴露的全部端口——值得注意的是exposedPorts的文档说明它包含镜像本身已暴露的端口即使未通过 Dagger 显式添加。六、实战示例TypeScript 与 Go 客户端调用6.1 TypeScript本类型的主战场withExposedPort在 TypeScript 生成客户端中的完整签名sdk/typescript/src/api/client.gen.ts#L5288-L5302withExposedPort ( port: number, opts?: ContainerWithExposedPortOpts, ): Container { const metadata { protocol: { is_enum: true, value_to_name: NetworkProtocolValueToName }, } const ctx this._ctx.select(withExposedPort, { port, ...opts, __metadata: metadata, }) return new Container(ctx) }典型用法暴露 8080 端口TCP 协议附带描述并跳过健康检查import { Client, NetworkProtocol } from dagger.io/dagger const client new Client() const ctr client .container() .from(nginx:alpine) .withExposedPort(8080, { protocol: NetworkProtocol.Tcp, description: payment API endpoint, experimentalSkipHealthcheck: true, }) await ctr.publish(registry.example.com/payment-api:latest) // 发布后的镜像 OCI 配置中将包含 EXPOSE 8080/tcp6.2 Go 客户端集成测试中的真实用法仓库集成测试 core/integration/container_test.go 中大量使用了对应选项例如WithExposedPort(5000, dagger.ContainerWithExposedPortOpts{Protocol: dagger.NetworkProtocolTcp})见 core/integration/container_test.go#L4025 等多处以及不带选项的默认调用WithExposedPort(5000)见 core/integration/container_test.go#L5013。这些测试同时验证了暴露端口后容器作为服务启动时的健康检查行为、端口去重语义以及镜像发布时 EXPOSE 元数据的正确性——dockerfile_test.go、services_test.go、localcache_test.go等测试文件也引用了相关机制可从 core/integration 目录继续追踪。Go 客户端中的对应类型dagger.ContainerWithExposedPortOpts可在生成的 dagger.gen.go 中找到结构与 TypeScript 版本一一对应。七、总结与最佳实践围绕ContainerWithExposedPortOpts可以归纳出如下使用要点关注点结论依据默认协议不传protocol时按 TCP 处理core/schema/container.go#L4509重复暴露相同端口 相同协议会被替换而非追加core/container.go#L6841-L6854健康检查服务模式下默认执行健康检查experimentalSkipHealthcheck: true可跳过core/schema/container.go#L903、core/schema/container.go#L4511OCI EXPOSE暴露端口会以port/protocol写入镜像 EXPOSE 配置core/container.go#L6860-L6861反向操作使用withoutExposedPort(port, protocol)取消暴露core/schema/container.go#L906-L911查询使用exposedPorts读取全部暴露端口含镜像自带core/schema/container.go#L913-L915实践建议当容器会被service()/asService()包装并以服务方式运行且暴露的端口没有就绪探针时考虑开启experimentalSkipHealthcheck当端口仅用于发布镜像的 EXPOSE 元数据时保持默认即可。由于该选项带experimental前缀建议在升级 Dagger 版本后通过 CHANGELOG.md 确认其语义是否发生变化。更多 TypeScript SDK 的生成客户端参考可继续翻阅 client.gen 参考目录。【免费下载链接】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），仅供参考