chezmoi Keeper 模板函数详解在模板中安全获取 Keeper 密钥数据【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址: https://gitcode.com/gh_mirrors/ch/chezmoikeeper、keeperDataFields与keeperFindPassword是 chezmoi 内置的三组 Keeper 模板函数它们通过调用 Keeper 官方 Commander CLI 将密码库中的结构化数据注入点文件模板。读完本文你将掌握这三个函数各自的适用场景、底层命令调用方式、keeper.command与keeper.args配置项的作用以及如何配合--skip-secrets构建安全、可复现的多机点文件管理流程。一、Keeper 函数概览chezmoi 通过 Keeper 的 Commander CLI命令名为keeper把密码库能力暴露为模板函数。所有以keeper开头的函数统称为Keeper 函数它们的工作方式一致在渲染模板时调用 Keeper CLI将其标准输出解析后提供给模板使用。从源码看三个函数统一注册在 internal/cmd/config.go 的模板函数表中keeper: c.keeperTemplateFunc, keeperDataFields: c.keeperDataFieldsTemplateFunc, keeperFindPassword: c.keeperFindPasswordTemplateFunc,这意味着在任意 chezmoi 模板*.tmpl文件、chezmoi.toml.tmpl、脚本模板等中都可以直接使用它们。Keeper 函数家族包含三个成员函数参数返回值底层命令keeperuid解析为 JSON 的 mapkeeper get --formatjson uidkeeperDataFieldsuid按字段类型索引的 mapkeeper get --formatjson uidkeeperFindPasswordquery字符串密码keeper find-password query其中query可以是记录的 UID也可以是路径。keeper与keeperDataFields接受 UIDkeeperFindPassword更灵活UID 和路径都可以。二、keeperuid获取完整 JSON 结构化数据keeper函数返回通过 Commander CLI 从 Keeper 获取的结构化数据。uid会被原样传给keeper get --formatjson输出结果按 JSON 解析后返回。在 internal/cmd/keepertemplatefuncs.go 中的实现如下func (c *Config) keeperTemplateFunc(record string) map[string]any { chezmoi.SkipTemplateIf(c.skipSecrets) output : mustValue(c.keeperOutput([]string{get, --formatjson, record})) var result map[string]any must(json.Unmarshal(output, result)) return result }执行过程分为三步若启用了--skip-secrets直接跳过模板渲染调用keeper get --formatjson uid获取 JSON 输出将输出json.Unmarshal为map[string]any返回。因此模板中可以通过keeper $UID拿到记录的完整 JSON再按 Key 逐层取值。典型用法取自官方文档title {{ (keeper $UID).data.title }}keeper get的 JSON 顶层包含data、record_uid、type等字段其中data下又有title、fields、custom等子结构可逐层访问。例如获取记录的创建时间、类型等元数据recordType {{ (keeper $UID).type }}三、keeperDataFieldsuid按字段类型索引的便捷封装keeperDataFields是keeper的便捷变体它同样执行keeper get --formatjson uid但只抽取 JSON 中.data.fields数组并将其按字段的type重新索引为 map。这样就不必在模板里手工遍历fields数组。实现位于 internal/cmd/keepertemplatefuncs.govar data struct { Data struct { Fields []struct { Type string json:type Value any json:value } json:fields } json:data } must(json.Unmarshal(output, data)) result : make(map[string]any) for _, field : range data.Data.Fields { result[field.Type] field.Value } return result注意字段的value在 Keeper 的 JSON 中本身是数组如登录名、密码等字段可能有多个值因此取值时通常需要用index取第一个元素。官方文档给出的示例url {{ (keeperDataFields $UID).url }} login {{ index (keeperDataFields $UID).login 0 }} password {{ index (keeperDataFields $UID).password 0 }}url字段直接可用因为多数记录只有一个 URLlogin、password字段是数组必须用index ... 0取首个元素。Keeper 记录常见的字段type有login、password、url、oneTimeCode等均可按此方式索引。四、keeperFindPasswordquery直接取密码keeperFindPassword返回keeper find-password query命令的输出query可以是 UID 或路径非常适合只想取一个密码、不想处理 JSON 结构的场景。实现位于 internal/cmd/keepertemplatefuncs.go与keeper的关键差异是输出会经过bytes.TrimSpace去除首尾空白保证模板中不会混入多余换行func (c *Config) keeperFindPasswordTemplateFunc(record string) string { chezmoi.SkipTemplateIf(c.skipSecrets) output : mustValue(c.keeperOutput([]string{find-password, record})) return string(bytes.TrimSpace(output)) }用户指南中的示例展示了 UID 与路径两种查询方式examplePasswordFromPath {{ keeperFindPassword $PATH }} examplePasswordFromUid {{ keeperFindPassword $UID }}在真实点文件中可以把密码直接渲染进需要密钥的配置文件。例如生成一个包含 API 密钥的~/.config/myapp/configapi_key {{ keeperFindPassword MyApp/API Key }}五、底层命令执行与结果缓存三个函数最终都汇聚到keeperOutputinternal/cmd/keepertemplatefuncs.go该函数是理解 Keeper 集成原理的关键func (c *Config) keeperOutput(args []string) ([]byte, error) { key : strings.Join(args, \x00) if data, ok : c.Keeper.outputCache[key]; ok { return data, nil } name : c.Keeper.Command args append(args, c.Keeper.Args...) cmd : exec.Command(name, args...) cmd.Stdin os.Stdin cmd.Stderr os.Stderr output, err : chezmoilog.LogCmdOutput(c.logger, cmd) ... c.Keeper.outputCache[key] output return output, nil }几个值得注意的实现细节参数合并顺序函数自带的参数如get --formatjson uid在前配置的keeper.args追加在后按参数缓存以\x00连接参数作为缓存 Key同一个模板渲染过程中重复的 Keeper 查询只会执行一次 CLI降低延迟与对 Keeper 服务的压力标准输入/输出透传cmd.Stdin与cmd.Stderr直接透传因此需要交互式解锁 Keeper 会话时如输入主密码可正常交互错误信息也会原样展示错误包装CLI 失败时会通过newCmdOutputError包装模板渲染随之失败避免静默使用错误数据。六、配置项keeper.command与keeper.argsKeeper 集成允许通过 chezmoi 配置文件定制 CLI 命令本身。默认配置定义在 internal/cmd/config.goKeeper: keeperConfig{ Command: keeper, },两个配置项的完整定义见 variables.md.yaml配置项类型默认值说明keeper.commandstringkeeperKeeper CLI 命令keeper.args[]string空追加给 Keeper CLI 的额外参数在~/.config/chezmoi/chezmoi.toml中为 CLI 附加配置文件的示例官方文档原例[keeper] args [--config, /path/to/config.json]如果keeper命令不在PATH中或需要指定绝对路径可以设置command[keeper] command /usr/local/bin/keeper在其他配置格式YAML / JSON中写法同理keeper: command: keeper args: - --config - /path/to/config.json七、安全实践配合--skip-secrets使用Keeper 函数与所有敏感数据函数一样遵守 chezmoi 的--skip-secrets机制。在三个函数的实现开头都调用了chezmoi.SkipTemplateIf(c.skipSecrets)该标志在 internal/cmd/config.go 注册persistentFlags.BoolVar(c.skipSecrets, skip-secrets, c.skipSecrets, Skip all templates containing secrets)这意味着执行chezmoi apply --skip-secrets时任何包含 Keeper 函数的模板会被整体跳过不会触发对 Keeper CLI 的调用也不会在日志或输出中暴露密码。这在你只想知道哪些文件会变化配合--dry-run、--diff或在不具备 Keeper 会话的环境如 CI中预览变更时非常有用。使用时还需注意前置条件需要先按 Commander CLI 文档创建持久化登录会话persistent login session否则首次调用会触发交互式登录。八、实操示例一份完整的.tmpl用法综合以上内容一个典型的 Keeper 驱动的点文件模板如dot_config/myapp/config.tmpl可以是# 由 chezmoi 模板生成不要直接编辑 app_title {{ (keeper ABCD-EFGH-IJKL-MNOP).data.title }} username {{ index (keeperDataFields ABCD-EFGH-IJKL-MNOP).login 0 }} password {{ keeperFindPassword MyApp/API Key }} endpoint {{ (keeperDataFields ABCD-EFGH-IJKL-MNOP).url }}对应使用流程在 Keeper 中创建记录记下其 UID或使用路径按 Commander CLI 文档建立持久化登录会话编写包含上述模板函数的.tmpl源文件并chezmoi add执行chezmoi apply完成渲染落盘需要预览而不触碰密钥时使用chezmoi diff --skip-secrets。相关文档与源码位置Keeper 函数参考keeper-functions/index.mdkeeper函数keeper-functions/keeper.mdkeeperDataFields函数keeper-functions/keeperDataFields.mdkeeperFindPassword函数keeper-functions/keeperFindPassword.md用户指南password-managers/keeper.md源码实现internal/cmd/keepertemplatefuncs.go【免费下载链接】chezmoiManage your dotfiles across multiple diverse machines, securely.项目地址: https://gitcode.com/gh_mirrors/ch/chezmoi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考