Dagger TypeScript SDK Port 类完全指南容器端口暴露与网络协议解析【免费下载链接】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 仓库version-0.19 版本文档中的Port类 API 参考文档结合引擎端 Go 源码与集成测试系统讲解 Dagger TypeScript SDK 中Port对象的方法、字段语义、底层 OCI 端口模型以及在实际容器编排端口暴露、服务健康检查、镜像发布中的应用方式。读完本文你将能熟练使用container.exposedPorts()获取并解析端口信息理解NetworkProtocol枚举与PortID标量类型的含义并掌握withExposedPort/withoutExposedPort的完整链路。一、Port 是什么容器暴露端口的只读视图在 Dagger 的 GraphQL 类型体系中PortA port exposed by a container即容器暴露的端口是描述某个端口及其元数据的只读值对象。它并不主动暴露端口而是承载端口暴露的结果信息——当你通过Container.withExposedPort()暴露端口或读取镜像中既有的EXPOSE声明时返回的都是Port对象。从引擎端源码看Port的核心定义位于 core/net.go// Port configures a port to exposed from a container or service. type Port struct { Port int field:true doc:The port number. Protocol NetworkProtocol field:true doc:The transport layer protocol. Description *string field:true doc:The port description. ExperimentalSkipHealthcheck bool field:true doc:Skip the health check when run as a service. }四个字段与 TypeScript SDK 中Port类的五个只读方法一一对应Description与ExperimentalSkipHealthcheck为可空/可选字段分别对应两个Promise方法。也就是说Port本质上是引擎端值类型在 GraphQL 层的投影SDK 生成代码client.gen通过 dagql 的field:true标记自动生成对应的取值方法。二、类定义与构造函数仅供内部使用在 TypeScript SDK 中Port是一个继承自BaseClient的类类声明Port继承BaseClient构造函数new Port(ctx?, _id?, _description?, _experimentalSkipHealthcheck?, _port?, _protocol?)所有参数均为可选且文档明确标注Constructor is used for internal usage only, do not create object from it构造函数仅供内部使用请勿手动创建对象。这一点与 Dagger 客户端 SDK 的整体设计一致像Port、Container、Directory这类对象都由引擎查询结果反序列化而来用户不应也无法有意义地直接实例化。构造函数参数中的_id类型为PortID、_protocol类型为NetworkProtocol正是下面要介绍的两种关联类型。在实际代码中你拿到Port对象的唯一途径是调用容器的exposedPorts()方法以及引擎内部为镜像既有 EXPOSE 端口构造的Port例如const ports: Port[] await container.exposedPorts(); for (const p of ports) { const number await p.port(); const proto await p.protocol(); const desc await p.description(); const skip await p.experimentalSkipHealthcheck(); const id await p.id(); }三、五个方法逐一拆解Port类共暴露五个实例方法全部返回Promise下面结合引擎端实现说明各自的真实语义。3.1 port()端口号port(): Promisenumber返回端口号如8080。对应 core/net.go 中的Port int字段。端口号本身没有范围校验逻辑写死在Port值类型中但 GraphQL 层会要求其为整数实际使用时应遵循 1–65535 的常规端口范围。3.2 protocol()传输层协议protocol(): PromiseNetworkProtocol返回传输层协议取值为NetworkProtocol枚举NetworkProtocol.TcpTCP或NetworkProtocol.UdpUDP。对应 core/net.go 的Protocol NetworkProtocol字段。值得注意的细节在withExposedPort的 GraphQL 参数定义中protocol带有默认值TCP见 core/schema/container.gotype containerWithExposedPortArgs struct { Port int Protocol core.NetworkProtocol default:TCP Description *string ExperimentalSkipHealthcheck bool default:false }也就是说当你不指定协议时端口默认按 TCP 暴露而exposedPorts()返回的既有镜像端口则会如实反映其在 OCI 配置中的协议。3.3 description()端口描述description(): Promisestring返回端口描述对应withExposedPort的description参数例如payment API endpoint。描述信息并不存在于 OCI 规范中而是 Dagger 的扩展能力——引擎端exposedPorts的实现特意做了说明get descriptions fromContainer.Ports(not in the OCI spec)core/schema/container.go。因此通过 DaggerwithExposedPort显式暴露的端口描述会保留在引擎侧Container.Ports列表里镜像自带的 EXPOSE 端口没有描述字段description()返回空字符串。3.4 experimentalSkipHealthcheck()跳过服务健康检查experimentalSkipHealthcheck(): Promiseboolean返回是否在作为服务运行时跳过健康检查。Dagger 的withExposedPort在文档中被描述为Like EXPOSE in Dockerfile (but with healthcheck support)core/schema/container.go即暴露端口有两个目的服务健康检查与自省health checks and introspectionwhen running services设置 OCI 的 EXPOSE 字段when publishing the container。当端口同时被用作服务健康检查探针时如果该端口本身不响应健康检查例如纯 UDP 端口可设置experimentalSkipHealthcheck: true跳过。此字段是实验性的未来版本可能调整命名或语义。3.5 id()Port 的唯一标识id(): PromisePortID返回该Port对象的唯一标识符类型为PortID标量。PortID的定义见 type-aliases/PortID.mdPortIDstringobject即用于标识 Port 类型对象的标量类型。它是 Dagger 统一 ID 机制结构化标量 ID的一部分ID 在字符串表象之外携带结构化约束__PortID: never标记阻止字面量伪造可在同一引擎会话内把任意值对象序列化为可传递的 ID。不过Port本身是轻量值对象实际场景中更多直接读取其port()/protocol()ID 主要用于统一的对象引用与缓存语义。四、关联类型NetworkProtocol 枚举protocol()的返回类型NetworkProtocol定义于 enumerations/NetworkProtocol.md包含两个成员枚举成员字符串值说明NetworkProtocol.TcpTCP传输控制协议NetworkProtocol.UdpUDP用户数据报协议在引擎端该枚举由 dagql 动态注册core/net.go// NetworkProtocol is a GraphQL enum type. type NetworkProtocol string var NetworkProtocols dagql.NewEnum[NetworkProtocol]() var ( NetworkProtocolTCP NetworkProtocols.Register(TCP) NetworkProtocolUDP NetworkProtocols.Register(UDP) )在 Go SDK 中对应dagger.NetworkProtocolTcp/dagger.NetworkProtocolUdpPython SDK 中对应dagger.NetworkProtocol.TCP/dagger.NetworkProtocol.UDPTypeScript SDK 中即为本文的NetworkProtocol.Tcp/NetworkProtocol.Udp。五、底层原理从 OCI 端口规范到 Port 对象理解Port的语义绕不开 OCI 镜像规范中的端口表达方式。OCI 配置中的ExposedPorts是map[string]struct{}键的格式为port/protocol例如8080/tcp、53/udp。引擎端exposedPorts()的实现core/schema/container.go做了两件事把 Dagger 显式暴露的端口Container.Ports携带描述与健康检查信息按%d/%s格式fmt.Sprintf(%d/%s, p.Port, p.Protocol.Network())映射为 OCI 键遍历 OCI 配置Config.ExposedPorts凡是没有对应 Dagger 端口的即镜像自带 EXPOSE调用NewPortFromOCI反解析成Port对象解析失败则跳过。NewPortFromOCIcore/net.go的实现func NewPortFromOCI(s string) (p Port, _ error) { port, protoStr, ok : strings.Cut(s, /) if !ok { return p, fmt.Errorf(unable to parse OCI port: missing / delimiter) } portNr, err : strconv.Atoi(port) ... proto, err : NetworkProtocols.Lookup(strings.ToUpper(protoStr)) ... p Port{ Port: portNr, Protocol: proto, } return p, nil }这解释了文档中的一个重要行为——exposedPorts的 GraphQL 文档明确写着This includes ports already exposed by the image, even if not explicitly added with daggercore/schema/container.go你拿到的端口列表是镜像声明 Dagger 显式暴露的并集。同理WithExposedPortcore/container.go在写入时做了去重与 OCI 同步若同端口、同协议已存在则替换避免重复同时写入Container.Ports列表与Container.Config.ExposedPortsOCI map清除ImageRef缓存使端口变更在后续镜像导出时生效。对应的WithoutExposedPortcore/container.go则按端口协议过滤并重建 OCI map。这两个引擎端方法与 GraphQL 层的withExposedPort/withoutExposedPort节点一一对应core/schema/container.goPort对象正是这条暴露 → 记录 → 查询链路的数据载体。六、实战在 Dagger 管道中读取与使用 Port6.1 组合使用 withExposedPort exposedPorts一个典型的端到端模式构建容器 → 暴露端口 → 读取端口信息 → 按需发布或连接服务。import { connect, NetworkProtocol } from dagger.io/dagger; connect(async (client) { const ctr client .container() .from(nginx:1.27) .withExposedPort(8080, { description: payment API endpoint, protocol: NetworkProtocol.Tcp, }); // 读取全部暴露端口含镜像自带的 80 const ports await ctr.exposedPorts(); for (const p of ports) { console.log(port${await p.port()} proto${await p.protocol()} desc${await p.description()}); } // 撤销 8080 的暴露 const ctr2 ctr.withoutExposedPort(8080, NetworkProtocol.Tcp); });6.2 配合 Service 使用健康检查experimentalSkipHealthcheck字段的典型场景是与Service组合将容器作为服务启动时Dagger 会用暴露端口做健康检查探针对于 UDP 端口或纯数据面端口设置跳过探针可避免服务被误判为不健康。这一行为在集成测试中有充分覆盖例如 core/integration/services_test.go 中同时使用NetworkProtocolUdp与 TCP 端口的服务编排用例以及 core/integration/container_test.go 中WithExposedPort(5000/5001, ...)的容器到服务调用测试。6.3 镜像发布时的 EXPOSE 语义由于withExposedPort同时写入 OCI 的ExposedPorts最终publish()/export()产出的镜像会带上相应的 EXPOSE 元数据core/container.go下游运行时如 docker run即可感知端口。这也是exposed ports serve two purposes健康检查 发布元数据的第二重用途。七、测试验证与更多资源Dagger 仓库通过多层测试锁定了Port的行为引擎层exposedPorts从 OCI map 反解析端口的逻辑core/schema/container.go集成层Dockerfile 构建后读取端口协议并断言的用例core/integration/dockerfile_test.go以及大量WithExposedPort 服务调用的用例core/integration/services_test.go、core/integration/registry_mirrors_test.go。想进一步探索可以按以下路径深入类型定义core/net.goPort值类型与 core/net.goNetworkProtocol枚举GraphQL 注册core/schema/container.gowithExposedPort/withoutExposedPort/exposedPorts节点引擎实现core/schema/container.go参数解析与 OCI 映射、core/container.go写路径关联类型文档PortID 类型别名、NetworkProtocol 枚举其他 SDK 的对应形态可参考 SDK 目录sdk/go、sdk/python、sdk/typescript中的生成客户端代码。小结Port类虽然只包含五个取值方法但它精准映射了 Dagger 引擎在容器端口暴露上的完整设计以 OCIExposedPorts为事实源以Container.Ports承载描述与健康检查等扩展元数据通过NetworkProtocol枚举区分 TCP/UDP借助PortID标量提供统一的会话内对象引用。掌握它你就能在 TypeScript 中准确读取容器端口清单并围绕端口信息构建服务发现、健康检查与镜像发布逻辑。【免费下载链接】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 Port 类完全指南：容器端口暴露与网络协议解析
Dagger TypeScript SDK Port 类完全指南容器端口暴露与网络协议解析【免费下载链接】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 仓库version-0.19 版本文档中的Port类 API 参考文档结合引擎端 Go 源码与集成测试系统讲解 Dagger TypeScript SDK 中Port对象的方法、字段语义、底层 OCI 端口模型以及在实际容器编排端口暴露、服务健康检查、镜像发布中的应用方式。读完本文你将能熟练使用container.exposedPorts()获取并解析端口信息理解NetworkProtocol枚举与PortID标量类型的含义并掌握withExposedPort/withoutExposedPort的完整链路。一、Port 是什么容器暴露端口的只读视图在 Dagger 的 GraphQL 类型体系中PortA port exposed by a container即容器暴露的端口是描述某个端口及其元数据的只读值对象。它并不主动暴露端口而是承载端口暴露的结果信息——当你通过Container.withExposedPort()暴露端口或读取镜像中既有的EXPOSE声明时返回的都是Port对象。从引擎端源码看Port的核心定义位于 core/net.go// Port configures a port to exposed from a container or service. type Port struct { Port int field:true doc:The port number. Protocol NetworkProtocol field:true doc:The transport layer protocol. Description *string field:true doc:The port description. ExperimentalSkipHealthcheck bool field:true doc:Skip the health check when run as a service. }四个字段与 TypeScript SDK 中Port类的五个只读方法一一对应Description与ExperimentalSkipHealthcheck为可空/可选字段分别对应两个Promise方法。也就是说Port本质上是引擎端值类型在 GraphQL 层的投影SDK 生成代码client.gen通过 dagql 的field:true标记自动生成对应的取值方法。二、类定义与构造函数仅供内部使用在 TypeScript SDK 中Port是一个继承自BaseClient的类类声明Port继承BaseClient构造函数new Port(ctx?, _id?, _description?, _experimentalSkipHealthcheck?, _port?, _protocol?)所有参数均为可选且文档明确标注Constructor is used for internal usage only, do not create object from it构造函数仅供内部使用请勿手动创建对象。这一点与 Dagger 客户端 SDK 的整体设计一致像Port、Container、Directory这类对象都由引擎查询结果反序列化而来用户不应也无法有意义地直接实例化。构造函数参数中的_id类型为PortID、_protocol类型为NetworkProtocol正是下面要介绍的两种关联类型。在实际代码中你拿到Port对象的唯一途径是调用容器的exposedPorts()方法以及引擎内部为镜像既有 EXPOSE 端口构造的Port例如const ports: Port[] await container.exposedPorts(); for (const p of ports) { const number await p.port(); const proto await p.protocol(); const desc await p.description(); const skip await p.experimentalSkipHealthcheck(); const id await p.id(); }三、五个方法逐一拆解Port类共暴露五个实例方法全部返回Promise下面结合引擎端实现说明各自的真实语义。3.1 port()端口号port(): Promisenumber返回端口号如8080。对应 core/net.go 中的Port int字段。端口号本身没有范围校验逻辑写死在Port值类型中但 GraphQL 层会要求其为整数实际使用时应遵循 1–65535 的常规端口范围。3.2 protocol()传输层协议protocol(): PromiseNetworkProtocol返回传输层协议取值为NetworkProtocol枚举NetworkProtocol.TcpTCP或NetworkProtocol.UdpUDP。对应 core/net.go 的Protocol NetworkProtocol字段。值得注意的细节在withExposedPort的 GraphQL 参数定义中protocol带有默认值TCP见 core/schema/container.gotype containerWithExposedPortArgs struct { Port int Protocol core.NetworkProtocol default:TCP Description *string ExperimentalSkipHealthcheck bool default:false }也就是说当你不指定协议时端口默认按 TCP 暴露而exposedPorts()返回的既有镜像端口则会如实反映其在 OCI 配置中的协议。3.3 description()端口描述description(): Promisestring返回端口描述对应withExposedPort的description参数例如payment API endpoint。描述信息并不存在于 OCI 规范中而是 Dagger 的扩展能力——引擎端exposedPorts的实现特意做了说明get descriptions fromContainer.Ports(not in the OCI spec)core/schema/container.go。因此通过 DaggerwithExposedPort显式暴露的端口描述会保留在引擎侧Container.Ports列表里镜像自带的 EXPOSE 端口没有描述字段description()返回空字符串。3.4 experimentalSkipHealthcheck()跳过服务健康检查experimentalSkipHealthcheck(): Promiseboolean返回是否在作为服务运行时跳过健康检查。Dagger 的withExposedPort在文档中被描述为Like EXPOSE in Dockerfile (but with healthcheck support)core/schema/container.go即暴露端口有两个目的服务健康检查与自省health checks and introspectionwhen running services设置 OCI 的 EXPOSE 字段when publishing the container。当端口同时被用作服务健康检查探针时如果该端口本身不响应健康检查例如纯 UDP 端口可设置experimentalSkipHealthcheck: true跳过。此字段是实验性的未来版本可能调整命名或语义。3.5 id()Port 的唯一标识id(): PromisePortID返回该Port对象的唯一标识符类型为PortID标量。PortID的定义见 type-aliases/PortID.mdPortIDstringobject即用于标识 Port 类型对象的标量类型。它是 Dagger 统一 ID 机制结构化标量 ID的一部分ID 在字符串表象之外携带结构化约束__PortID: never标记阻止字面量伪造可在同一引擎会话内把任意值对象序列化为可传递的 ID。不过Port本身是轻量值对象实际场景中更多直接读取其port()/protocol()ID 主要用于统一的对象引用与缓存语义。四、关联类型NetworkProtocol 枚举protocol()的返回类型NetworkProtocol定义于 enumerations/NetworkProtocol.md包含两个成员枚举成员字符串值说明NetworkProtocol.TcpTCP传输控制协议NetworkProtocol.UdpUDP用户数据报协议在引擎端该枚举由 dagql 动态注册core/net.go// NetworkProtocol is a GraphQL enum type. type NetworkProtocol string var NetworkProtocols dagql.NewEnum[NetworkProtocol]() var ( NetworkProtocolTCP NetworkProtocols.Register(TCP) NetworkProtocolUDP NetworkProtocols.Register(UDP) )在 Go SDK 中对应dagger.NetworkProtocolTcp/dagger.NetworkProtocolUdpPython SDK 中对应dagger.NetworkProtocol.TCP/dagger.NetworkProtocol.UDPTypeScript SDK 中即为本文的NetworkProtocol.Tcp/NetworkProtocol.Udp。五、底层原理从 OCI 端口规范到 Port 对象理解Port的语义绕不开 OCI 镜像规范中的端口表达方式。OCI 配置中的ExposedPorts是map[string]struct{}键的格式为port/protocol例如8080/tcp、53/udp。引擎端exposedPorts()的实现core/schema/container.go做了两件事把 Dagger 显式暴露的端口Container.Ports携带描述与健康检查信息按%d/%s格式fmt.Sprintf(%d/%s, p.Port, p.Protocol.Network())映射为 OCI 键遍历 OCI 配置Config.ExposedPorts凡是没有对应 Dagger 端口的即镜像自带 EXPOSE调用NewPortFromOCI反解析成Port对象解析失败则跳过。NewPortFromOCIcore/net.go的实现func NewPortFromOCI(s string) (p Port, _ error) { port, protoStr, ok : strings.Cut(s, /) if !ok { return p, fmt.Errorf(unable to parse OCI port: missing / delimiter) } portNr, err : strconv.Atoi(port) ... proto, err : NetworkProtocols.Lookup(strings.ToUpper(protoStr)) ... p Port{ Port: portNr, Protocol: proto, } return p, nil }这解释了文档中的一个重要行为——exposedPorts的 GraphQL 文档明确写着This includes ports already exposed by the image, even if not explicitly added with daggercore/schema/container.go你拿到的端口列表是镜像声明 Dagger 显式暴露的并集。同理WithExposedPortcore/container.go在写入时做了去重与 OCI 同步若同端口、同协议已存在则替换避免重复同时写入Container.Ports列表与Container.Config.ExposedPortsOCI map清除ImageRef缓存使端口变更在后续镜像导出时生效。对应的WithoutExposedPortcore/container.go则按端口协议过滤并重建 OCI map。这两个引擎端方法与 GraphQL 层的withExposedPort/withoutExposedPort节点一一对应core/schema/container.goPort对象正是这条暴露 → 记录 → 查询链路的数据载体。六、实战在 Dagger 管道中读取与使用 Port6.1 组合使用 withExposedPort exposedPorts一个典型的端到端模式构建容器 → 暴露端口 → 读取端口信息 → 按需发布或连接服务。import { connect, NetworkProtocol } from dagger.io/dagger; connect(async (client) { const ctr client .container() .from(nginx:1.27) .withExposedPort(8080, { description: payment API endpoint, protocol: NetworkProtocol.Tcp, }); // 读取全部暴露端口含镜像自带的 80 const ports await ctr.exposedPorts(); for (const p of ports) { console.log(port${await p.port()} proto${await p.protocol()} desc${await p.description()}); } // 撤销 8080 的暴露 const ctr2 ctr.withoutExposedPort(8080, NetworkProtocol.Tcp); });6.2 配合 Service 使用健康检查experimentalSkipHealthcheck字段的典型场景是与Service组合将容器作为服务启动时Dagger 会用暴露端口做健康检查探针对于 UDP 端口或纯数据面端口设置跳过探针可避免服务被误判为不健康。这一行为在集成测试中有充分覆盖例如 core/integration/services_test.go 中同时使用NetworkProtocolUdp与 TCP 端口的服务编排用例以及 core/integration/container_test.go 中WithExposedPort(5000/5001, ...)的容器到服务调用测试。6.3 镜像发布时的 EXPOSE 语义由于withExposedPort同时写入 OCI 的ExposedPorts最终publish()/export()产出的镜像会带上相应的 EXPOSE 元数据core/container.go下游运行时如 docker run即可感知端口。这也是exposed ports serve two purposes健康检查 发布元数据的第二重用途。七、测试验证与更多资源Dagger 仓库通过多层测试锁定了Port的行为引擎层exposedPorts从 OCI map 反解析端口的逻辑core/schema/container.go集成层Dockerfile 构建后读取端口协议并断言的用例core/integration/dockerfile_test.go以及大量WithExposedPort 服务调用的用例core/integration/services_test.go、core/integration/registry_mirrors_test.go。想进一步探索可以按以下路径深入类型定义core/net.goPort值类型与 core/net.goNetworkProtocol枚举GraphQL 注册core/schema/container.gowithExposedPort/withoutExposedPort/exposedPorts节点引擎实现core/schema/container.go参数解析与 OCI 映射、core/container.go写路径关联类型文档PortID 类型别名、NetworkProtocol 枚举其他 SDK 的对应形态可参考 SDK 目录sdk/go、sdk/python、sdk/typescript中的生成客户端代码。小结Port类虽然只包含五个取值方法但它精准映射了 Dagger 引擎在容器端口暴露上的完整设计以 OCIExposedPorts为事实源以Container.Ports承载描述与健康检查等扩展元数据通过NetworkProtocol枚举区分 TCP/UDP借助PortID标量提供统一的会话内对象引用。掌握它你就能在 TypeScript 中准确读取容器端口清单并围绕端口信息构建服务发现、健康检查与镜像发布逻辑。【免费下载链接】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），仅供参考