Dagger TypeScript SDK 的 Secret 类安全处理密钥引用的 API 参考与实现原理【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/daggerSecret 是 Dagger 图数据库DAG中的一个核心对象类型用于引用而非直接持有密钥值从而让容器构建、模块调用与缓存系统可以在不泄露明文的前提下安全地传递机密。本文以 Dagger 0.19 版 TypeScript SDK 的官方 API 参考文档Secret.md为骨架逐方法拆解Secret类的构造约束与四个查询方法并深入其背后的 GraphQL schema 与 Go 引擎实现帮助你在 CI/CD 流水线和自定义模块中正确地创建、传递与消费机密。一、Secret 是什么一种可安全处理的引用Dagger 中每个对象类型都由引擎侧的 GraphQL Schema 定义Secret也不例外。在核心引擎中它的类型描述与 TS SDK 中的文档字符串完全一致A reference to a secret value, which can be handled more safely than the value itself.对应实现见 core/secret.go 的TypeDescription()以及 sdk/typescript/src/api/client.gen.ts 中生成类的 JSDoc。关键点在于引用reference二字SDK 中的Secret对象并不把明文值暴露在调用方进程里而是作为一个不透明的句柄handle进入引擎的会话资源session resource系统由引擎在需要时才解析真实的密钥值。这一点从引擎端core.Secret的结构体字段可以印证// core/secret.go type Secret struct { Handle dagql.SessionResourceHandle URIVal string NameVal string PlaintextVal []byte json:- SourceClientID string }注意PlaintextVal带有json:-标签意味着明文永远不会被序列化进持久化对象或缓存。持久化时只保留Handle与Name见 core/secret.go这正是比值本身更安全的底层保障。与 GraphQL Schema 的对应关系Secret类的四个方法id()、name()、plaintext()、uri()一一对应 core/schema/secret.go 中注册在*core.Secret上的四个 GraphQL 字段。Schema 里还额外标注了两个重要约束plaintext被标记为Sensitive()并声明DoNotCache(Do not include plaintext secret in the cache.)setSecret的plaintext参数同样被标记为Sensitive()。也就是说即使你通过plaintext()读出了值引擎的 DAG 缓存中也不会写入明文避免机密通过缓存层泄漏。二、构造约束构造函数仅供内部使用new Secret(ctx?, _id?, _name?, _plaintext?, _uri?)参数ctx?: Context、_id?: SecretID、_name?: string、_plaintext?: string、_uri?: string返回Secret重写OverridesBaseClient.constructor官方文档明确写着 Constructor is used for internal usage only, do not create object from it。在生成的 TS 代码中构造函数只是把五个私有字段缓存到实例上不做任何校验或资源初始化// sdk/typescript/src/api/client.gen.ts#L14032-L14045 constructor( ctx?: Context, _id?: ID, _name?: string, _plaintext?: string, _uri?: string, ) { super(ctx) this._id _id this._name _name this._plaintext _plaintext this._uri _uri }正确的创建方式是永远通过Client的两个工厂方法之一获得Secret实例见 client.gen.tsclient.secret(uri, opts?)——按 URI 引用一个外部密钥存储secret store中的密钥client.setSecret(name, plaintext)——直接把明文字符串注册为具名密钥。这两个方法分别对应用户需求中的 GraphQL 根字段secret与setSecret其引擎端实现在 core/schema/secret.go。要点Secret实例本身是惰性的。构造函数只保存引用任何实际请求都要等调用id()/name()/plaintext()/uri()中的方法或在容器构建中被消费时才通过 GraphQL 查询执行。三、方法详解id() 与 name()id()签名id(): PromiseSecretID语义返回该Secret的唯一标识符。SecretID是一个名义类型nominal type别名其定义见 type-aliases/SecretID.mdexport type ID string { __ID: never } // 通用 ID 的模板 export type SecretID string { __SecretID: never }它本质是一个string但带有一个不可实例化的标记字段从而在编译期阻止你把普通字符串误当作SecretID传递防止 ID 与明文字符串混用。生成代码client.gen.ts中带有_id短路缓存若实例已持有 ID 则直接返回否则执行this._ctx.select(id)发起 GraphQL 查询。从引擎角度看Secret是一个内容寻址content-addressed对象。id实际上对应其会话资源句柄的内容摘要content digest详见 core/schema/secret.go 中WithContentDigest(ctx, digest.Digest(handle))的调用。name()签名name(): Promisestring语义返回该密钥的名称。引擎侧实现非常直接core/schema/secret.gofunc (s *secretSchema) name(ctx context.Context, secret dagql.ObjectResult[*core.Secret], args struct{}) (string, error) { return secret.Self().Name(ctx) }对于setSecret创建的密钥name就是你传入的用户自定义名称对于secret(uri)引用的外部密钥名称由引擎从其 URI 解析得出。名称本身不包含敏感数据因此这个字段可以放心用于日志与调试输出。四、方法详解plaintext() 与 uri()plaintext()签名plaintext(): Promisestring语义返回该密钥的明文值。这是四个方法中唯一会读出机密的方法因此在引擎端受到双重保护core/schema/secret.godagql.NodeFunc(plaintext, s.plaintext). Sensitive(). DoNotCache(Do not include plaintext secret in the cache.). Doc(The value of this secret.),Sensitive()告诉执行器与遥测系统该字段/参数属于敏感数据避免出现在日志与调用记录中DoNotCache(...)明文结果不会被写入 DAG 缓存防止机密在缓存中持久化。引擎的解析过程会通过会话资源句柄从客户端的安全存储中取回明文core/schema/secret.go。在 TS 层生成的plaintext()同样带有_plaintext短路缓存client.gen.ts。实践建议plaintext()属于逃生舱口式的 API。常规工作流中你几乎不需要调用它——正确的姿势是把Secret对象直接传给容器见下文让密钥以环境变量或文件的形式在隔离的容器内被消费而不是把明文拉回到宿主进程里。uri()签名uri(): Promisestring语义返回该密钥的来源 URI。URI 标识密钥在哪个密钥存储secret store中。引擎端解析如下core/schema/secret.gofunc (s *secretSchema) uri(ctx context.Context, secret dagql.ObjectResult[*core.Secret], args struct{}) (string, error) { return secret.Self().URI(ctx) }在创建外部密钥时client.secret(uri)会先通过secretprovider.ResolverForID(args.URI)校验 URI 是否被当前引擎支持的 resolver 识别core/schema/secret.go不认识的 URI 会直接报错。可以推断URI 的具体格式与可用 resolver 取决于运行 Dagger 引擎的主机环境所配置的密钥存储后端。五、实战如何创建 Secret 并安全地注入容器1. 用 setSecret 注入环境变量最常用的模式是把机密作为容器环境变量注入。SDK 提供了Container.withSecretVariable(name, secret)签名见 client.gen.tsimport { connect, Client } from dagger.io/dagger await connect(async (client: Client) { const secret client.setSecret(TOKEN, process.env.MY_TOKEN!) const out await client .container() .from(alpine:3.16.2) .withSecretVariable(TOKEN, secret) // 以 Secret 引用注入而非明文 .withExec([sh, -c, echo $TOKEN /out.txt]) .sync() })SDK 自带的测试用例完整演示了这一链路api.spec.ts先用setSecret(TOKEN, token)创建Secret再经withSecretVariable注入容器最后在容器内用test $TOKEN baz校验值一致。整个过程中明文只出现在你传入setSecret的那一刻之后始终以引用形式流转。2. 按 URI 引用既有密钥如果你的机密已经存在于某个受支持的密钥存储如主机环境的 secret provider中用secret(uri)引用即可const ghToken client.secret(env://GH_TOKEN) // 具体 URI 格式取决于引擎配置的存储后端 await client .container() .from(alpine:3.16.2) .withSecretVariable(GITHUB_TOKEN, ghToken) .withExec([sh, -c, test -n \$GITHUB_TOKEN\]) .sync()可选参数opts.cacheKey允许你手动指定缓存等价键见 client.gen.ts两个 URI 或明文不同但cacheKey相同的密钥在缓存查询时会被视为等价从而让原本等价的容器withExec相互命中缓存。若未指定缓存键则由密钥构造时的明文值派生而来。其底层逻辑在 core/schema/secret.go有cacheKey用SecretHandleFromCacheKey否则尝试读取明文并用SecretHandleFromPlaintext派生句柄读取失败时例如该 URI 不可达会回退到随机缓存键并打印警告。3. 将密钥作为文件挂载除了环境变量Container还提供withSecretFile之类的 API 可以把密钥内容以只读文件形式放入容器挂载方式与withSecretVariable类似返回新的Container。需要把 token 写入~/.npmrc、~/.docker/config.json、SSH key 等场景时文件形式比环境变量更可控。具体签名可以在生成 SDK 的 client.gen.ts 中搜索withSecretFile确认。六、限制与注意事项明文大小上限setSecret的明文值限制为128000 字节约 125 KB。这是 schema 层面写死的约束见 core/schema/secret.go 与 SDK 文档注释 client.gen.ts。缓存安全plaintext字段禁止缓存DoNotCache明文也不会被序列化进持久化对象。若你自行调用plaintext()拿到明文后打印到日志安全性由调用方自己负责。会话绑定从 core/schema/secret.go 可以看到创建密钥需要客户端元数据中的SessionID机密句柄与创建它的会话强绑定BindSessionResource跨会话/跨客户端不能随意传递。敏感标记setSecret的明文参数在引擎日志与调用记录中会被脱敏core/schema/secret.go 中构建消毒后调用记录时把plaintext替换为***因此在调试时不必担心明文直接进入遥测数据。七、小结Secret是 Dagger 中机密最小暴露设计的载体方法返回类型引擎字段安全属性id()PromiseSecretID内容寻址句柄的摘要不包含明文name()Promisestringname字段仅名称可用于日志plaintext()Promisestringplaintext字段Sensitive()DoNotCacheuri()Promisestringuri字段标识密钥存储来源使用口诀永远通过client.secret(uri)或client.setSecret(name, plaintext)创建绝不 new把引用交给withSecretVariable/withSecretFile让容器消费机密把plaintext()留作最后手段。相关源码入口core/schema/secret.go、core/secret.go、sdk/typescript/src/api/client.gen.ts、SDK 测试用例 sdk/typescript/src/api/test/api.spec.ts。【免费下载链接】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），仅供参考