Dagger TypeScript SDK HostServiceOpts 完全指南host.service 端口转发与上游主机配置【免费下载链接】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 SDKdagger.io/daggerAPI 参考中的HostServiceOpts类型别名展开讲解如何在Host.service()调用中通过host选项指定流量转发的上游主机地址并结合仓库源码剖析其底层实现原理。读完本文你将掌握HostServiceOpts、PortForward、NetworkProtocol的完整配置方法理解localhost默认值与Socket构建逻辑并能在实际管线中正确编写宿主机网络端口转发代码。一、HostServiceOpts 是什么类型定义速览HostServiceOpts是 Dagger TypeScript SDK 生成客户端 APIapi/client.gen中的对象类型别名仅包含一个可选属性用于配置通过宿主机Host转发流量时的上游地址。其定义位于 sdk/typescript/src/api/client.gen.tsexport type HostServiceOpts { /** * Upstream host to forward traffic to. */ host?: string }对应 TypeScript API 参考文档 中给出的属性说明如下属性类型必填说明host?string可选要转发流量的上游主机地址Upstream host该类型不做任何额外约束是Host.service()方法可选参数opts的类型。它的唯一职责就是把“转发目标的主机名/主机地址”以字符串形式传递给引擎。二、使用场景Host.service() 宿主机端口转发HostServiceOpts并不独立存在它总是作为Host类的service()方法参数出现。在 Host 类参考文档 中service()的定义是Creates a service that forwards traffic to a specified address via the host.其 TypeScript 方法签名位于 sdk/typescript/src/api/client.gen.tsservice (ports: PortForward[], opts?: HostServiceOpts): Service { const ctx this._ctx.select(service, { ports, ...opts }) return new Service(ctx) }方法参数ports: PortForward[]要通过宿主机网络暴露的端口映射列表。若某个映射的frontend未指定或为0则默认与backend相同空端口集合是无效的引擎会返回错误。opts?: HostServiceOpts转发选项其中host即上游主机地址。典型应用场景包括Dagger 容器需要访问运行在宿主机上或宿主机可达的局域网/远端的服务例如本机数据库、开发服务器、测试桩mock server等此时通过Host.service()创建以宿主网络为媒介的Service再将其asService()挂载到其他容器。三、搭配使用的 PortForward 与 NetworkProtocolHostServiceOpts只负责上游主机而端口映射细节由PortForward承担。其定义见 sdk/typescript/src/api/client.gen.ts以及 PortForward 类型参考文档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 }属性类型必填说明backendnumber是流量到达的目的端口frontend?number可选暴露给客户端的前端端口未指定时选择默认值在Host.service语义下与 backend 相同protocol?NetworkProtocol可选传输层协议protocol的类型为枚举NetworkProtocol见 sdk/typescript/src/api/client.gen.ts取值只有两个export enum NetworkProtocol { Tcp TCP, Udp UDP, }因此HostServiceOptsPortForward共同构成一次完整的转发描述到达哪个主机host、监听哪个端口frontend、转发到哪个端口backend、使用什么协议protocol。四、实战示例在 TypeScript 管线中配置 host 选项下面给出可直接套用的 TypeScript 示例。默认情况下不传host引擎会使用localhost需要转发到其他主机时显式传入host。4.1 使用默认上游主机localhostimport { connect } from dagger.io/dagger connect(async (client) { // 通过宿主机 localhost:5432 访问 PostgreSQL const db client.host().service( [{ backend: 5432, frontend: 5432, protocol: TCP }] // 未传 optshost 默认 localhost ) // 将宿主机服务挂载到应用容器 const app client .container() .from(node:22-alpine) .withServiceBinding(db, db) .withExec([node, app.js]) await app.stdout() })4.2 显式指定上游主机import { connect, NetworkProtocol } from dagger.io/dagger connect(async (client) { // 将流量转发到局域网内另一台主机的 6379 端口 const redis client.host().service( [ { backend: 6379, frontend: 6379, protocol: NetworkProtocol.Tcp, }, ], { host: redis.internal.example } // HostServiceOpts.host ) const svc await client .container() .from(redis:7) .withServiceBinding(redis, redis) .sync() })4.3 UDP 端口转发host选项与协议无关UDP 场景只需在PortForward中指定protocol: NetworkProtocol.Udpconst dns client.host().service( [ { backend: 53, frontend: 5353, protocol: NetworkProtocol.Udp }, ], { host: dns.server.local } )五、底层实现原理从 opts.host 到 HostSockets理解HostServiceOpts.host的最可靠方式是阅读引擎侧 GraphQL 实现。core/schema/host.go 中定义了对应的参数结构与处理逻辑type hostServiceArgs struct { Host string default:localhost Ports []dagql.InputObject[core.PortForward] } func (s *hostSchema) service(ctx context.Context, parent dagql.ObjectResult[*core.Host], args hostServiceArgs) (inst dagql.ObjectResult[*core.Service], err error) { srv, err : core.CurrentDagqlServer(ctx) if err ! nil { return inst, fmt.Errorf(failed to get current dagql server: %w, err) } if len(args.Ports) 0 { return inst, errors.New(no ports specified) } clientMetadata, err : engine.ClientMetadataFromContext(ctx) if err ! nil { return inst, fmt.Errorf(failed to get client metadata: %w, err) } ports : collectInputsSlice(args.Ports) socks : make([]*core.Socket, 0, len(ports)) for _, port : range ports { sock : core.Socket{ Kind: core.SocketKindHostIP, URLVal: (url.URL{Scheme: port.Protocol.Network(), Host: fmt.Sprintf(%s:%d, args.Host, port.Backend)}).String(), PortForwardVal: port, SourceClientID: clientMetadata.ClientID, } socks append(socks, sock) } svc : core.Service{ HostSockets: socks, } return dagql.NewObjectResultForCurrentCall(ctx, srv, svc) }从这段实现可以归纳出几个关键事实host有默认值localhosthostServiceArgs中Host string \default:localhost表明即使 TypeScript 侧不传HostServiceOpts引擎也会回退到localhost这与 API 文档中host? 的可选语义完全一致。空端口列表直接报错if len(args.Ports) 0 { return ..., errors.New(no ports specified) }印证了Host.service()文档中“An empty set of ports is not valid; an error will be returned.”的行为。每个端口被转换为一个Socket端口映射被构造成core.SocketKind为SocketKindHostIPURL 形式为protocol://host:backend例如tcp://localhost:5432。可见HostServiceOpts.host最终直接影响生成的 Socket URL 主机段。SourceClientID记录来源客户端从engine.ClientMetadataFromContext获取的客户端 ID 被写入每个 Socket用于标识该转发属于哪个客户端会话。返回的Service由HostSockets聚合多个端口映射最终汇入同一个core.Service的HostSockets字段供后续withServiceBinding、up等操作消费。这一链路说明host选项并非只是 SDK 层的字符串透传而是切实参与了引擎侧 Socket 地址的组装因此错误的host值会导致连接失败而非静默忽略。六、注意事项与最佳实践结合文档与源码使用HostServiceOpts时应注意以下几点host只在需要时传默认localhost已覆盖“访问宿主机本机服务”这一最常见需求仅当目标服务位于其他主机时才需显式传入主机名或 IP。不要传空端口数组ports为空会触发引擎侧no ports specified错误与frontend缺省自动回退backend的行为不同空数组没有任何回退逻辑。frontend缺省语义在Host.service中frontend未指定或为0时默认等于backend这与Host.tunnel随机端口的缺省行为不同两者不要混淆——Host.service用于将宿主机网络上的既有服务暴露给 Dagger 管线Host.tunnel则反向把管线内Service暴露到宿主机。协议要匹配真实服务NetworkProtocol只有Tcp与Udp两个取值转发 UDP 服务如 DNS、部分游戏服务器时必须显式指定Udp。只读仓库说明本文所述配置均基于当前仓库 sdk/typescript/src/api/client.gen.ts 与 core/schema/host.go 的实现可直接用于本地安装的 Dagger 0.19 版本 SDK 项目无需修改仓库自身。七、参考资料HostServiceOpts 类型参考文档本文主体来源。Host 类参考文档service()、tunnel()、unixSocket()等方法总览。PortForward 类型参考文档端口映射三要素。TypeScript SDK 生成客户端源码HostServiceOpts、PortForward、NetworkProtocol与Host.service的类型级实现。Host schema 核心实现hostServiceArgs默认值与HostSockets组装逻辑。【免费下载链接】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），仅供参考