尧图网页设计 
Dagger TypeScript SDK 中的 PortForward 类型服务端口转发的完整配置指南【免费下载链接】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导读PortForward是 Dagger TypeScript SDK 中用于描述「服务端口转发规则」的核心类型别名它定义了如何将容器或主机上运行的服务的流量通过隧道暴露给调用方。本文将以 Dagger 0.21 版本 TypeScript SDK 的 API 参考文档为主体结合仓库源码sdk/typescript/src/api/client.gen.ts、core/schema/service.go、core/service.go深入讲解PortForward的三个字段backend、frontend、protocol的语义、默认行为与底层实现帮助你在编写 Dagger 模块或客户端时准确配置端口转发。一、类型定义总览在 PortForward.md 中PortForward被定义为一种对象object类型的 TypeScript 类型别名type PortForward { backend: number frontend?: number protocol?: NetworkProtocol }它包含1 个必填字段backend和2 个可选字段frontend、protocol。在生成的 SDK 源码 sdk/typescript/src/api/client.gen.ts 中该类型与文档一一对应export type PortForward { /** Destination port for traffic. */ backend: number /** Port to expose to clients. If unspecified, a default will be chosen. */ frontend?: number /** Transport layer protocol to use for traffic. */ protocol?: NetworkProtocol }在 Dagger 的 GraphQL 核心 schema 中PortForward通过core.PortForward结构体存在并在服务相关 API 中以输入对象dagql.InputObject的形式被消费具体见 core/schema/service.gotype UpArgs struct { Ports []dagql.InputObject[core.PortForward] default:[] ... }二、字段详解2.1 backend必填流量目的地端口backend:numberDestination port for traffic.backend是转发规则的目标端口即流量最终要被送达的服务端口。它是唯一必填字段表示「这条转发规则要把流量送到哪个端口上」。在 Dagger 的服务模型中backend指向的是服务Service内部监听的真实端口。例如一个容器内运行着监听 8080 端口的 Web 服务那么在PortForward中backend就应设置为8080。从源码结构看backend在核心侧最终会被写入隧道的端口映射中。在 core/service.go 中服务对象保存了TunnelPorts []PortForward用于记录通过隧道暴露的端口列表而PortForward结构体中的后端端口正是隧道建立时流量转发的落点。2.2 frontend可选对外暴露端口optionalfrontend?:numberPort to expose to clients. If unspecified, a default will be chosen.frontend是暴露给客户端调用方的端口。当客户端通过隧道访问该服务时访问的就是frontend端口。该字段可省略。文档明确指出如果未指定系统将自动选择一个默认端口If unspecified, a default will be chosen。这一设计让你无需关心宿主机端口冲突问题——当多个服务同时需要转发时Dagger 会自动为每个未指定frontend的规则挑选可用的空闲端口。在 Go 核心侧core/service.go 中PortForward的 JSON 序列化字段定义为TunnelPorts []PortForward json:tunnelPorts,omitemptyfrontend端口用于客户端侧的监听而backend端口对应服务侧的监听二者构成「客户端端口 → 服务端口」的映射关系。2.3 protocol可选传输层协议optionalprotocol?:NetworkProtocolTransport layer protocol to use for traffic.protocol指定转发流量使用的传输层协议其取值来自NetworkProtocol枚举。Dagger 0.21 版本的枚举定义见 NetworkProtocol.md仅包含两个成员枚举成员取值含义TcpTCP基于 TCP 的传输层协议UdpUDP基于 UDP 的传输层协议对应地在 SDK 生成代码 sdk/typescript/src/api/client.gen.ts 中NetworkProtocol以 TypeScript 枚举形式导出并提供了NetworkProtocolValueToName/NetworkProtocolNameToValue两个工具函数用于枚举值与字符串名称之间的双向转换export enum NetworkProtocol { Tcp TCP, Udp UDP, }该字段同样可选。省略时默认使用 TCP——这一点可以从核心地址解析逻辑中得到印证在 core/schema/address.go 中当传入的协议不是 UDP 时代码显式回退到core.NetworkProtocolTCPif protocol core.NetworkProtocolUDP { protocol core.NetworkProtocolUDP } else { protocol core.NetworkProtocolTCP }这意味着不指定协议你的端口转发将按 TCP 处理只有需要传输 UDP 流量如 DNS、音视频流等场景时才需要显式传入Udp。三、PortForward 的典型使用场景PortForward最常见的消费入口是Container.up()、Service.up()以及host.service()等需要建立隧道暴露端口的 API。以 SDK 生成代码 sdk/typescript/src/api/client.gen.ts 中的主机服务方法为例其签名直接接收PortForward[]数组service (ports: PortForward[], opts?: HostServiceOpts): Service {因此一个完整的端口转发配置可以这样编写import { dag, NetworkProtocol } from dagger.io/dagger // 单条转发规则客户端访问 9000 端口流量转发到服务的 8080 端口 const forward: PortForward { backend: 8080, frontend: 9000, protocol: NetworkProtocol.Tcp, } // 也可省略 frontend 与 protocol使用自动分配的默认端口与默认 TCP 协议 const forwardWithDefaults: PortForward { backend: 8080, }在核心 schema 层PortForward作为up操作的ports参数被批量消费。查看 core/schema/service.goUpArgs中Ports的默认值为空数组[]随后在up的实现中被转换为服务隧道的实际端口参数而 core/schema/service.go 在打印隧道信息时也会读取port.Protocol.Network()再次印证protocol字段会一路传递到隧道层。四、源码中的底层流转路径为了更深入地理解PortForward可以顺着仓库源码追踪一条端口转发规则的生命周期API 入口用户在 TypeScript 端构造PortForward对象作为参数传入up/service等调用核心 schema 消费GraphQL 请求到达 core/schema/service.goUpArgs.Ports以dagql.InputObject[core.PortForward]形式被解析服务模型存储解析结果写入core.Service结构体core/service.go 中的TunnelPorts字段负责携带这批转发规则隧道建立服务启动后引擎根据TunnelPorts在客户端与容器网络之间建立隧道frontend作为客户端监听端口、backend作为容器内目标端口完成流量转发。此外core/schema/address.go 展示了从通用输入解码为core.PortForward的细节——它先通过(dagql.InputObject[core.PortForward]{}).Decoder().DecodeInput(...)将原始输入解码为端口对象再将其包装进输入对象供上层调用统一处理。五、实践要点与注意事项结合文档与源码使用PortForward时有以下几点需要留意backend必须提供这是转发规则唯一必填项缺少它 TypeScript 类型检查阶段就会报错frontend省略时端口由系统分配如果你的客户端不需要固定端口例如只是临时探测服务连通性可以放心省略frontend避免手动管理端口冲突协议默认 TCP只有 UDP 场景才需要显式设置protocol: NetworkProtocol.Udp其余情况保持默认即可批量转发PortForward通常以数组形式传入ports: PortForward[]一个服务可以同时暴露多个端口只需在数组中添加多条规则SDK 版本差异本文基于 Dagger 0.21 版本文档docs/versioned_docs/version-0.21与当前仓库源码编写其他版本的字段语义可能略有差异使用时请以对应版本的 API 参考为准。相关资源PortForward 类型别名文档NetworkProtocol 枚举文档TypeScript SDK 生成代码中的类型定义核心 schema 中 up 命令的端口参数处理核心服务模型中 TunnelPorts 的存储【免费下载链接】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 中的 PortForward 类型：服务端口转发的完整配置指南
Dagger TypeScript SDK 中的 PortForward 类型服务端口转发的完整配置指南【免费下载链接】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导读PortForward是 Dagger TypeScript SDK 中用于描述「服务端口转发规则」的核心类型别名它定义了如何将容器或主机上运行的服务的流量通过隧道暴露给调用方。本文将以 Dagger 0.21 版本 TypeScript SDK 的 API 参考文档为主体结合仓库源码sdk/typescript/src/api/client.gen.ts、core/schema/service.go、core/service.go深入讲解PortForward的三个字段backend、frontend、protocol的语义、默认行为与底层实现帮助你在编写 Dagger 模块或客户端时准确配置端口转发。一、类型定义总览在 PortForward.md 中PortForward被定义为一种对象object类型的 TypeScript 类型别名type PortForward { backend: number frontend?: number protocol?: NetworkProtocol }它包含1 个必填字段backend和2 个可选字段frontend、protocol。在生成的 SDK 源码 sdk/typescript/src/api/client.gen.ts 中该类型与文档一一对应export type PortForward { /** Destination port for traffic. */ backend: number /** Port to expose to clients. If unspecified, a default will be chosen. */ frontend?: number /** Transport layer protocol to use for traffic. */ protocol?: NetworkProtocol }在 Dagger 的 GraphQL 核心 schema 中PortForward通过core.PortForward结构体存在并在服务相关 API 中以输入对象dagql.InputObject的形式被消费具体见 core/schema/service.gotype UpArgs struct { Ports []dagql.InputObject[core.PortForward] default:[] ... }二、字段详解2.1 backend必填流量目的地端口backend:numberDestination port for traffic.backend是转发规则的目标端口即流量最终要被送达的服务端口。它是唯一必填字段表示「这条转发规则要把流量送到哪个端口上」。在 Dagger 的服务模型中backend指向的是服务Service内部监听的真实端口。例如一个容器内运行着监听 8080 端口的 Web 服务那么在PortForward中backend就应设置为8080。从源码结构看backend在核心侧最终会被写入隧道的端口映射中。在 core/service.go 中服务对象保存了TunnelPorts []PortForward用于记录通过隧道暴露的端口列表而PortForward结构体中的后端端口正是隧道建立时流量转发的落点。2.2 frontend可选对外暴露端口optionalfrontend?:numberPort to expose to clients. If unspecified, a default will be chosen.frontend是暴露给客户端调用方的端口。当客户端通过隧道访问该服务时访问的就是frontend端口。该字段可省略。文档明确指出如果未指定系统将自动选择一个默认端口If unspecified, a default will be chosen。这一设计让你无需关心宿主机端口冲突问题——当多个服务同时需要转发时Dagger 会自动为每个未指定frontend的规则挑选可用的空闲端口。在 Go 核心侧core/service.go 中PortForward的 JSON 序列化字段定义为TunnelPorts []PortForward json:tunnelPorts,omitemptyfrontend端口用于客户端侧的监听而backend端口对应服务侧的监听二者构成「客户端端口 → 服务端口」的映射关系。2.3 protocol可选传输层协议optionalprotocol?:NetworkProtocolTransport layer protocol to use for traffic.protocol指定转发流量使用的传输层协议其取值来自NetworkProtocol枚举。Dagger 0.21 版本的枚举定义见 NetworkProtocol.md仅包含两个成员枚举成员取值含义TcpTCP基于 TCP 的传输层协议UdpUDP基于 UDP 的传输层协议对应地在 SDK 生成代码 sdk/typescript/src/api/client.gen.ts 中NetworkProtocol以 TypeScript 枚举形式导出并提供了NetworkProtocolValueToName/NetworkProtocolNameToValue两个工具函数用于枚举值与字符串名称之间的双向转换export enum NetworkProtocol { Tcp TCP, Udp UDP, }该字段同样可选。省略时默认使用 TCP——这一点可以从核心地址解析逻辑中得到印证在 core/schema/address.go 中当传入的协议不是 UDP 时代码显式回退到core.NetworkProtocolTCPif protocol core.NetworkProtocolUDP { protocol core.NetworkProtocolUDP } else { protocol core.NetworkProtocolTCP }这意味着不指定协议你的端口转发将按 TCP 处理只有需要传输 UDP 流量如 DNS、音视频流等场景时才需要显式传入Udp。三、PortForward 的典型使用场景PortForward最常见的消费入口是Container.up()、Service.up()以及host.service()等需要建立隧道暴露端口的 API。以 SDK 生成代码 sdk/typescript/src/api/client.gen.ts 中的主机服务方法为例其签名直接接收PortForward[]数组service (ports: PortForward[], opts?: HostServiceOpts): Service {因此一个完整的端口转发配置可以这样编写import { dag, NetworkProtocol } from dagger.io/dagger // 单条转发规则客户端访问 9000 端口流量转发到服务的 8080 端口 const forward: PortForward { backend: 8080, frontend: 9000, protocol: NetworkProtocol.Tcp, } // 也可省略 frontend 与 protocol使用自动分配的默认端口与默认 TCP 协议 const forwardWithDefaults: PortForward { backend: 8080, }在核心 schema 层PortForward作为up操作的ports参数被批量消费。查看 core/schema/service.goUpArgs中Ports的默认值为空数组[]随后在up的实现中被转换为服务隧道的实际端口参数而 core/schema/service.go 在打印隧道信息时也会读取port.Protocol.Network()再次印证protocol字段会一路传递到隧道层。四、源码中的底层流转路径为了更深入地理解PortForward可以顺着仓库源码追踪一条端口转发规则的生命周期API 入口用户在 TypeScript 端构造PortForward对象作为参数传入up/service等调用核心 schema 消费GraphQL 请求到达 core/schema/service.goUpArgs.Ports以dagql.InputObject[core.PortForward]形式被解析服务模型存储解析结果写入core.Service结构体core/service.go 中的TunnelPorts字段负责携带这批转发规则隧道建立服务启动后引擎根据TunnelPorts在客户端与容器网络之间建立隧道frontend作为客户端监听端口、backend作为容器内目标端口完成流量转发。此外core/schema/address.go 展示了从通用输入解码为core.PortForward的细节——它先通过(dagql.InputObject[core.PortForward]{}).Decoder().DecodeInput(...)将原始输入解码为端口对象再将其包装进输入对象供上层调用统一处理。五、实践要点与注意事项结合文档与源码使用PortForward时有以下几点需要留意backend必须提供这是转发规则唯一必填项缺少它 TypeScript 类型检查阶段就会报错frontend省略时端口由系统分配如果你的客户端不需要固定端口例如只是临时探测服务连通性可以放心省略frontend避免手动管理端口冲突协议默认 TCP只有 UDP 场景才需要显式设置protocol: NetworkProtocol.Udp其余情况保持默认即可批量转发PortForward通常以数组形式传入ports: PortForward[]一个服务可以同时暴露多个端口只需在数组中添加多条规则SDK 版本差异本文基于 Dagger 0.21 版本文档docs/versioned_docs/version-0.21与当前仓库源码编写其他版本的字段语义可能略有差异使用时请以对应版本的 API 参考为准。相关资源PortForward 类型别名文档NetworkProtocol 枚举文档TypeScript SDK 生成代码中的类型定义核心 schema 中 up 命令的端口参数处理核心服务模型中 TunnelPorts 的存储【免费下载链接】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），仅供参考