运维DevOpsIaC【免费下载链接】puppetServer automation framework and application项目地址https://gitcode.com/gh_mirrors/pu/puppet点击查看免费下载file_metadata是 Puppet Server 内置的 HTTP API 端点用于返回单个文件或多个文件的元数据校验和、属主、属组、权限模式、类型等是file资源在 agent 与 master 之间同步文件内容时的重要前置查询。本文基于 Puppet 官方 HTTP API 文档结合当前仓库的源码实现lib/puppet/file_serving/metadata.rb、lib/puppet/file_serving/fileset.rb 等深入讲解 find 与 search 两种变体的用法、全部查询参数、JSON 响应结构与底层实现原理读完即可独立调试和调用该 API。一、端点概述find 与 search 两种变体file_metadata端点返回单个文件或多个文件的精选元数据。端点存在 find查找单个对象和 search搜索多个对象两种变体search 变体在末尾多了一个s实际路径是file_metadatasGET /puppet/v3/file_metadata/:mount/path/to/file?environment:environment—— find获取单个对象的元数据GET /puppet/v3/file_metadatas/foo.txt?environmentenv—— search获取多个对象的元数据列表虽然端点和文档中统一使用file这个泛称但返回的每个对象实际可以是以下三种类型之一File普通文件Directory目录Symbolic link符号链接这一点也直接体现在响应字段type的取值上对应的 JSON Schema 将其枚举为[file, directory, link]见 api/schemas/file_metadata.json。注意以下示例中的 JSON 响应为便于阅读做了 pretty-print 美化实际响应是紧凑的单行 JSON。二、端点路径中的:mount类型端点路径包含一个:mount挂载点段决定了从哪个位置解析后续的文件路径共有五种类型mount 类型说明自定义文件服务挂载点在fileserver.conf中指定参考仓库示例 conf/fileserver.confmodules/MODULE半魔法挂载点允许访问MODULE模块的files子目录plugins高度魔法挂载点将所有模块的lib目录合并在一起用于插件同步不面向通用消费场景不能指定按模块的子路径pluginfacts高度魔法挂载点将所有模块的facts.d目录合并在一起用于外部事实external facts同步同样不面向通用消费场景不能指定按模块的子路径tasks/MODULE半魔法挂载点允许访问MODULE模块tasks子目录中的文件从源码结构看这五类挂载点在 lib/puppet/file_serving/mount/ 目录中都有对应的实现类file.rb自定义挂载、modules.rb、plugins.rb、pluginfacts.rb、tasks.rb而terminus_selector.rb负责根据请求的 mount 段选择正确的挂载处理逻辑。三、Find 变体获取单个文件的元数据3.1 HTTP 方法与响应格式支持的 HTTP 方法GET支持的响应格式application/json请求示例GET /puppet/v3/file_metadata/:mount/path/to/file?environment:environment3.2 查询参数详解find 变体支持以下可选参数links—— 取值为manage默认或followmanage返回符号链接本身的信息类型为linkdestination为链接目标follow跟随符号链接返回链接目标的元数据类型为目标的真实类型destination为nullchecksum_type—— 用于计算结果元数据校验和值的算法可选值取值说明md5默认值标准 MD5 摘要md5liteMD5 精简变体只对文件内容的前 512 字节计算用于性能优化sha256SHA-256 摘要sha256liteSHA-256 精简变体只对文件内容的前 512 字节计算mtime以修改时间作为校验和ctime以状态变更时间作为校验和none不计算校验和这些算法在 lib/puppet/util/checksums.rb 中实现例如md5_fileL195、sha256_fileL67、mtime_fileL244、ctime_fileL315、none_fileL332。md5lite与sha256lite的实现只读取文件头部 512 字节做摘要这解释了为什么目录和符号链接通常不会使用md5类算法。source_permissions—— 控制 Puppet 在管理文件时是否复制源文件的属主owner、属组group和权限模式modeignore默认值永远不应用源文件的属主、属组或模式。创建没有显式权限的新文件时其权限取决于平台行为在 POSIX 上Puppet 使用运行它的用户的 umask在 Windows 上Puppet 使用与运行用户关联的默认 DACL。usePuppet 会将源文件的属主、属组和模式应用到它管理的任何文件上。use_when_creating仅在创建文件时应用源文件的属主、属组和模式已存在的文件不会被覆盖权限。3.3 示例响应普通文件的元数据GET /puppet/v3/file_metadata/modules/example/just_a_file.txt?environmentenv HTTP/1.1 200 OK Content-Type: application/json { checksum: { type: md5, value: {md5}d0a10f45491acc8743bc5a82b228f89e }, destination: null, group: 20, links: manage, mode: 420, owner: 501, path: /etc/puppetlabs/code/modules/example/files/just_a_file.txt, relative_path: null, type: file }目录的元数据注意目录的 checksum type 是ctimeGET /puppet/v3/file_metadata/modules/example/subdirectory?environmentenv HTTP/1.1 200 OK Content-Type: application/json { checksum: { type: ctime, value: {ctime}2013-10-01 13:16:10 -0700 }, destination: null, group: 20, links: manage, mode: 493, owner: 501, path: /etc/puppetlabs/code/modules/example/files/subdirectory, relative_path: null, type: directory }符号链接的元数据linksmanage且source_permissionsignoredestination指向链接目标type为linkGET /puppet/v3/file_metadata/modules/example/link_to_file.txt?environmentenvsource_permissionsignore HTTP/1.1 200 OK Content-Type: application/json { checksum: { type: md5, value: {md5}d0a10f45491acc8743bc5a82b228f89e }, destination: /etc/puppetlabs/code/modules/example/files/just_a_file.txt, group: 20, links: manage, mode: 420, owner: 501, path: /etc/puppetlabs/code/modules/example/files/link_to_file.txt, relative_path: null, type: link }文件不存在时返回 404GET /puppet/v3/file_metadata/modules/example/does_not_exist?environmentenv HTTP/1.1 404 Not Found Not Found: Could not find file_metadata modules/example/does_not_exist四、Search 变体批量获取多个文件的元数据search 变体用于一次性获取多个文件的元数据列表路径为file_metadatas带末尾的sGET /puppet/v3/file_metadatas/foo.txt?environmentenv4.1 支持的 HTTP 方法与响应格式支持的 HTTP 方法GET支持的响应格式application/json4.2 查询参数详解search 变体除 find 的links、checksum_type、source_permissions外还支持recurse——应始终设置为yes。遗憾的是默认值是no这会导致 search 行为退化为 find 操作只返回根对象本身。从源码看lib/puppet/file_serving/fileset.rb 的Fileset#initialize中recurse falseL43只有recurse为真时continue_recursion_at?才继续向下遍历L186-L189印证了该参数的决定性作用。ignore—— 要忽略的文件或目录正则表达式可以重复传递多个。源码中Fileset#ignore接受数组L86-L89递归时通过File.fnmatch?(pattern, child)匹配并跳过被忽略的子项L150注意这里使用的是 glob 通配匹配而非正则匹配语义。4.3 示例响应基础搜索递归列出目录下所有对象的元数据GET /puppet/v3/file_metadatas/modules/example?environmentenvrecurseyes HTTP 200 OK Content-Type: application/json [ { checksum: { type: ctime, value: {ctime}2013-10-01 13:15:59 -0700 }, destination: null, group: 20, links: manage, mode: 493, owner: 501, path: /etc/puppetlabs/code/modules/example/files, relative_path: ., type: directory }, { checksum: { type: md5, value: {md5}d0a10f45491acc8743bc5a82b228f89e }, destination: null, group: 20, links: manage, mode: 420, owner: 501, path: /etc/puppetlabs/code/modules/example/files, relative_path: just_a_file.txt, type: file }, { checksum: { type: md5, value: {md5}d0a10f45491acc8743bc5a82b228f89e }, destination: /etc/puppetlabs/code/modules/example/files/just_a_file.txt, group: 20, links: manage, mode: 493, owner: 501, path: /etc/puppetlabs/code/modules/example/files, relative_path: link_to_file.txt, type: link }, { checksum: { type: ctime, value: {ctime}2013-10-01 13:15:59 -0700 }, destination: null, group: 20, links: manage, mode: 493, owner: 501, path: /etc/puppetlabs/code/modules/example/files, relative_path: subdirectory, type: directory }, { checksum: { type: md5, value: {md5}d41d8cd98f00b204e9800998ecf8427e }, destination: null, group: 20, links: manage, mode: 420, owner: 501, path: /etc/puppetlabs/code/modules/example/files, relative_path: subdirectory/another_file.txt, type: file } ]注意 search 响应与 find 响应有两个关键差异relative_path不再是null而是相对于挂载根的对象路径根对象本身是.path始终是挂载根目录的完整路径具体对象靠relative_path区分。忽略sub*且linksmanageGET /puppet/v3/file_metadatas/modules/example?environmentenvrecursetrueignoresub*linksmanage HTTP 200 OK Content-Type: application/json [ { checksum: { type: ctime, value: {ctime}2013-10-01 13:15:59 -0700 }, destination: null, group: 20, links: manage, mode: 493, owner: 501, path: /etc/puppetlabs/code/modules/example/files, relative_path: ., type: directory }, { checksum: { type: md5, value: {md5}d0a10f45491acc8743bc5a82b228f89e }, destination: null, group: 20, links: manage, mode: 420, owner: 501, path: /etc/puppetlabs/code/modules/example/files, relative_path: just_a_file.txt, type: file }, { checksum: { type: md5, value: {md5}d0a10f45491acc8743bc5a82b228f89e }, destination: /etc/puppetlabs/code/modules/example/files/just_a_file.txt, group: 20, links: manage, mode: 493, owner: 501, path: /etc/puppetlabs/code/modules/example/files, relative_path: link_to_file.txt, type: link } ]ignoresub*过滤掉了subdirectory及其子文件同时linksmanage使得link_to_file.txt保持type: link并携带destination字段。4.4linksmanage与linksfollow的行为差异下面的例子与上面完全一致唯一的区别是linksfollowGET /puppet/v3/file_metadatas/modules/example?environmentenvrecursetrueignoresub*linksfollow HTTP 200 OK Content-Type: application/json [ { checksum: { type: ctime, value: {ctime}2013-10-01 13:15:59 -0700 }, destination: null, group: 20, links: follow, mode: 493, owner: 501, path: /etc/puppetlabs/code/modules/example/files, relative_path: ., type: directory }, { checksum: { type: md5, value: {md5}d0a10f45491acc8743bc5a82b228f89e }, destination: null, group: 20, links: follow, mode: 420, owner: 501, path: /etc/puppetlabs/code/modules/example/files, relative_path: just_a_file.txt, type: file }, { checksum: { type: md5, value: {md5}d0a10f45491acc8743bc5a82b228f89e }, destination: null, group: 20, links: follow, mode: 420, owner: 501, path: /etc/puppetlabs/code/modules/example/files, relative_path: link_to_file.txt, type: file } ]与manage模式相比follow模式下的差异集中在link_to_file.txt的元数据上字段linksmanagelinksfollow所有对象的links字段managefollowdestination链接目标路径nulltypelinkfile目标的真实类型mode、owner、group链接自身的值链接目标的值源码层面lib/puppet/file_serving/fileset.rb 的links方法L91-L98会根据取值切换stat_methodmanage使用lstat不跟随链接follow使用stat跟随链接这正是上述字段差异的根源。五、响应字段与 JSON Schemafile_metadata的响应体遵循 api/schemas/file_metadata.json 定义的 JSON Schema。Schema 要求响应对象包含以下必填字段path、relative_path、links、owner、group、mode、type、destination、checksum不允许出现未定义的其他字段additionalProperties: false。各字段说明pathstring文件在服务器上的完整绝对路径relative_pathstring 或 nullsearch 场景下相对于挂载根的对象路径根为.find 场景为nulllinksenummanage或followownerstring 或 integer属主groupstring 或 integer属组modeinteger权限模式十进制数如420即八进制0644493即0755typeenumfile、directory或linkdestinationstring 或 null符号链接目标非链接为nullchecksumobject包含type和value两个必填字段type枚举为md5、sha256、ctimevalue形如{md5}d0a10f45491acc8743bc5a82b228f89e算法名花括号前缀 摘要值sourcestring可选源路径content_uristring可选puppet:///形式的 content URI。六、源码视角元数据是如何被收集的6.1 Metadata 模型与 collect 流程lib/puppet/file_serving/metadata.rb 中的Puppet::FileServing::Metadata是元数据的核心模型它继承自Puppet::FileServing::Base并indirects :file_metadata。关键实现点checksum_typeL21-L25校验算法合法性必须存在对应的#{type}_file方法否则抛出ArgumentErrorsource_permissionsL27-L31仅接受:use、:use_when_creating、:ignore三个符号值collectL101-L131执行实际统计按文件类型分支处理普通文件按checksum_type计算校验和目录强制将checksum_type切换为ctime只做时间戳校验对应示例中目录的 checksum type 总是ctime符号链接记录destination通过readlink尝试计算校验和失败则为nullFIFO 与 socketchecksum_type置为none其他类型抛出 Cannot manage files of type ... 错误mode stat.mode 0o07777L110对权限模式做掩码只保留低 12 位权限位MetaStat/WindowsStatL45-L86在source_permissionsignore时POSIX 上 owner 使用Process.euid、group 使用Process.egid、mode 使用0o644而不是源文件的真实值Windows 上则固定返回管理员 SIDS-1-5-32-544、S-1-0-0和0o644。这与参数文档中ignore的语义完全一致to_data_hashL154-L169序列化为 API 响应所需的 JSON 结构。6.2 Terminus 与 Filesetfind 与 search 的底层支撑file_metadata的 indirector terminus 定义在 lib/puppet/indirector/file_metadata/ 目录file_server.rb走 Puppet fileserver 逻辑file.rb直接读本地文件系统。lib/puppet/file_serving/terminus_helper.rb 中的path2instanceL10-L20将请求参数links、checksum_type、source_permissions注入 Metadata 实例并调用collectpath2instancesL22-L32则借助Fileset批量生成实例。lib/puppet/file_serving/fileset.rb 实现了递归遍历的核心逻辑filesL62-L84执行递归并把绝对路径剥成相对路径同时在结果前插入.表示根对应 search 响应中relative_path: .的条目默认软限制soft limit为 1000 个条目超过后发出性能告警L72-L73max_files参数可显式设置上限超过则直接抛错L70-L71perform_recursionL162-L177基于自定义的FileSetEntry结构做广度优先的层级遍历受recurse与recurselimit控制mergeL17-L27将多个 fileset 合并用于plugins、pluginfacts这类多模块合并挂载点同相对路径时靠前的 fileset 优先。6.3 校验和算法实现lib/puppet/util/checksums.rb 定义了全部可选算法L14-L15 声明的符号列表md5_file/sha256_fileL195 / L67读取整个文件计算摘要md5lite_file/sha256lite_fileL219 / L92只取文件内容前 512 字节适合大文件的快速变更检测mtime_file/ctime_fileL244 / L315以文件时间戳作为校验值none_fileL332不计算。文档中checksum_type参数的 7 个合法取值与此处的实现一一对应且校验和值统一带{algorithm}前缀如{md5}...便于下游解析。七、示例模块与实战用法以上所有示例基于如下虚构的模块目录结构/etc/puppetlabs/code/modules/example/ files/ just_a_file.txt link_to_file.txt - /etc/puppetlabs/code/modules/example/files/just_a_file.txt subdirectory/ another_file.txt实际使用场景包括agent 端文件同步agent 先通过file_metadata获取源文件校验和与本地文件比对不一致时才通过file_content端点拉取内容file_content端点文档见 api/docs/http_file_content.md目录递归变更检测配合recurseyes一次性获取整个目录树的元数据用于判断目录内是否有文件新增、删除或变更符号链接管理通过linksmanage保留链接语义或linksfollow获取目标文件真实状态权限继承控制通过source_permissions的三种取值精确控制源文件属主/属组/模式是否被复制。7.1 常见注意事项search 必须显式传recurseyes否则退化为 find 行为只返回根对象本身ignore参数可重复使用 glob 通配匹配如sub*匹配的子项及其下内容都会被跳过目录的校验和总是ctime无论请求哪种checksum_type这是源码中硬编码的行为lib/puppet/file_serving/metadata.rb L115-L117source_permissionsignore时返回的owner/group/mode并不反映源文件真实值POSIX 上为 euid/egid/0644要获取真实权限需使用use或use_when_creatingplugins与pluginfacts挂载点面向插件/外部事实同步合并了所有模块的相应目录不适合按模块指定子路径访问超大目录性能默认超过 1000 个条目的目录会产生告警建议为file资源显式设置max_files或改用其他方式管理大目录树。赞分享运维DevOpsIaC【免费下载链接】puppetServer automation framework and application项目地址https://gitcode.com/gh_mirrors/pu/puppet点击查看免费下载相关推荐Grafana Tempo HTTP API 完全指南数据接入、查询与集群运维端点详解Grafana Tempo HTTP API 完全指南数据接入、查询与集群运维端点详解 Tempo 以 HTTP 协议对外暴露了一整套 API用于推送in后端可观测性链路追踪WinFile符号链接和硬链接完全指南掌握高级文件操作技巧WinFile符号链接和硬链接完全指南掌握高级文件操作技巧 想要更高效地管理Windows文件系统吗WinFile作为经典的Windows文件管理器不仅保桌面应用Puppet 证书状态 HTTP API 深度指南/puppet-ca/v1/certificate_status 端点的查询、签发与吊销Puppet 证书状态 HTTP API 深度指南/puppet ca/v1/certificate_status 端点的查询、签发与吊销 本篇文章以 Pup运维DevOpsIaC上一篇Ollama Docker 容器如何启用 AMD GPU 的 rocm 镜像与 Vulkan 设备参数下一篇DynamicIsland自定义指南打造你的专属Mac刘海体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考