企业官网建设流程全解析

• 存储
• 分布式文件系统
• 对象存储
• 云原生

在 CubeFS 中，元数据节点（MetaNode）以"元数据分片（meta partition）"为单位承载文件系统的目录项（Dentry）与 inode 管理。当集群出现目录项异常、文件找不到、或需要核对某个分片内的目录结构时，MetaNode 提供了一组 HTTP 调试接口，可以直接查询单个 Dentry、指定目录下的全部子项，以及整个分片内的全部目录信息。本指南以 docs-zh/source/dev-guide/admin-api/metanode/dentry.md 为骨架，结合 metanode/api_handler.go 等源码，完整讲解这三个接口的参数、调用方式与底层实现原理，帮助读者快速上手目录项级排障。

接口一览

MetaNode 的 HTTP 调试服务通过registerAPIHandler注册路由（见 metanode/api_handler.go），其中与 Dentry 相关的接口如下：

三个接口均为只读查询，不会向 Raft 提交写操作，可安全用于线上排查。下面逐一展开。

使用前提：访问入口与端口

这些接口由 MetaNode 进程内置的 HTTP 服务提供。MetaNode 启动时通过 metanode/metanode.go 依次调用startServer与registerAPIHandler，其中startServer（见 metanode/server.go）监听配置文件中listen指定的端口；若开启了bindIp，则监听localAddr:listen。

文档示例中的http://10.196.59.202:17220仅为示意地址，实际调用时需将 IP 与端口替换为待排查 MetaNode 的地址：

• IP：目标 MetaNode 的localAddr；
• port：目标 MetaNode 配置文件中的listen端口；
• 分片编号pid可通过master的元数据分片列表查询，也可用同目录下/getPartitions、/getPartitionById接口确认。

作为参考，metanode/api_handler_test.go 中的测试服务器使用http.ListenAndServe(":8220", nil)启动并注册同一组路由，说明端口是可通过配置灵活指定的。

获取单个 Dentry 信息：/getDentry

该接口根据"父目录 inode + 名称"精确查询一个目录项，等价于文件系统层面的lookup操作，返回该 Dentry 对应的 inode 与类型。

请求示例

curl -v "http://10.196.59.202:17220/getDentry?pid=100&name="aa.txt"&parentIno=1024"

参数说明

响应结构与状态码

从源码 metanode/api_handler.go 的getDentryHandler可以看出，其处理流程为：

1. 通过parseArgs解析pid、parentIno，并读取name表单值；
2. 调用getRealVerSeq解析可选参数verSeq（见下文"多版本语义"小节）；
3. 通过metadataManager.GetPartition(pid)获取分片对象；
4. 构造LookupReq{PartitionID, ParentID, Name, VerSeq, VerAll}并调用mp.Lookup(req, p)；
5. 成功时 HTTP 状态码为303 See Other，JSON 响应体结构为{"code": 303, "msg": "<结果信息>", "data": "<查询结果>"}。

其中mp.Lookup的实现位于 metanode/partition_op_dentry.go：它先构造一个仅含ParentId与Name的Dentry，按请求的VerSeq设置版本号，然后调用分片内部的getDentry（见 metanode/partition_fsmop_dentry.go），在分片的内存 B+ 树dentryTree中查找；命中后返回 inode 与类型，未命中则返回OpNotExistErr。

获取指定目录下的全部文件：/getDirectory

该接口枚举指定父目录下的全部子目录项，等价于文件系统层面的readdir操作，可用于核对某个目录下的文件是否齐全、是否存在"幽灵"目录项。

请求示例

curl -v "http://10.196.59.202:17220/getDirectory?pid=100&parentIno=1024"

参数说明

需要特别指出：原文档参数表中该参数写作ino，但请求示例与源码解析使用的实际参数名均为parentIno（parseArgs中使用pIno.ParentIno()，见 metanode/api_handler.go），请以parentIno为准。另外从当前仓库的getDirectoryHandler实现看（metanode/api_handler.go），handler 会再次读取parentIno表单值并将其赋给pid用于GetPartition定位分片，这一行为与文档表格的描述存在差异，属于当前源码中的实现细节，使用前建议结合所部署版本的源码确认参数语义。

底层实现

getDirectoryHandler构造ReadDirReq{ParentID, VerSeq}并调用mp.ReadDir（metanode/partition_op_dentry.go），最终落到metaPartition.readDir（metanode/partition_fsmop_dentry.go）：

• 以Dentry{ParentId: req.ParentID}为起点、Dentry{ParentId: req.ParentID + 1}为终点，对dentryTree执行AscendRange区间遍历；
• 对每个目录项调用getDentryByVerSeq做版本过滤，过滤掉已删除或不可见的版本；
• 将所有子项的Inode、Type、Name组装为proto.Dentry列表返回。

因为dentryTree以ParentId + Name作为排序键，同一父目录下的全部目录项在 B+ 树中是连续区间，因此该查询天然高效。

获取指定分片的全部目录信息：/getAllDentry

该接口遍历整个分片的dentryTree，输出该分片内所有目录项。当怀疑分片内目录项数据整体不一致、或需要导出某个分片的完整目录快照做对比分析时使用。

请求示例

curl -v "http://10.196.59.202:17220/getAllDentry?pid=100"

参数说明

流式输出与过滤逻辑

getAllDentriesHandler的实现见 metanode/api_handler.go，与另外两个接口不同，它采用边遍历边写响应体的流式输出方式：先写出{"code": 200, "msg": "OK", "data":[前缀，随后对dentryTree.Ascend逐个输出 JSON，最后以]}收尾，避免一次性将海量目录项载入内存。

遍历过程中对每个目录项调用getDentryFromVerList(verSeq, false)（定义于 metanode/dentry.go）：

• 若某个目录项存在多版本快照（multiSnap），则按verSeq取对应可见版本；
• 若该版本已被删除（isDeleted()返回 true）或版本不可见，则直接跳过，不输出到结果中。

因此该接口输出的数据已经过版本过滤，与当前可见的目录结构一致。

进阶：可选参数 verSeq 与 verAll 的多版本语义

CubeFS 的元数据分片支持多版本快照机制，Dentry结构体内含multiSnap版本列表（见 metanode/dentry.go），每次变更会通过addVersion保留历史版本。对应地，上述接口提供两个可选参数：

• verSeq：指定查询的快照版本号。getRealVerSeq（metanode/api_handler.go）将其解析为 uint64；当verSeq=0或缺省时，会被替换为math.MaxUint64，即查询最新版本。这在核对历史目录快照、排查多版本恢复问题时非常有用。
• verAll（仅/getDentry支持）：置为true时返回该目录项的全部版本信息，而非仅指定版本。

从源码看 Dentry 的数据结构

了解接口返回值前，先明确 Dentry 的两种形态：

对外（协议层）：proto.Dentry（见 proto/fs_proto.go）仅包含三个字段，JSON 序列化后的键名为name、ino、type：

type Dentry struct { Name string `json:"name"` Inode uint64 `json:"ino"` Type uint32 `json:"type"` }

对内（存储层）：metanode.Dentry（见 metanode/dentry.go）额外携带ParentId与版本快照multiSnap：

type Dentry struct { ParentId uint64 Inode uint64 Name string Type uint32 multiSnap *DentryMultiSnap }

Type字段区分目录与普通文件（可通过proto.IsDir判断），multiSnap中每个版本都记录VerSeq，并且用VerSeq的最高位（1 << 63）标记该版本是否被删除（isDeleted，见 metanode/dentry.go），getVerSeq取版本号时会屏蔽该标志位。理解了这一点，就能明白/getAllDentry为什么能准确跳过已删除目录项。

调试实战建议与注意事项

1. 参数名区分大小写：三个接口的参数均以小写驼峰形式出现，pid、parentIno、name、verSeq、verAll需原样拼写；name含特殊字符（引号、空格、中文）时务必先做 URL 编码。
2. 确认分片归属：pid是元数据分片 ID，不是 inode 号。查询前可通过 master 或 MetaNode 的/getPartitions接口确认目标 inode 属于哪个分片，避免 404（handler 在分片不存在时返回StatusNotFound）。
3. 按需使用 /getAllDentry：大分片目录项可能成千上万，流式输出仍会产生较大响应体，建议配合curl -o落盘分析，避免终端输出堆积。
4. 多版本场景配合 verSeq 使用：若集群启用了多版本快照，默认查询的是最新版本；需要排查历史状态时显式传入verSeq。
5. 源码与文档差异：/getDirectory文档参数表写作ino，实际请求参数与源码解析均为parentIno；同时当前版本 handler 存在将parentIno赋给pid的取值细节，线上使用前请以所部署版本源码为准核对。

参考与延伸阅读

• 接口注册与实现：metanode/api_handler.go
• Dentry 内部结构与版本管理：metanode/dentry.go
• Lookup / ReadDir 操作封装：metanode/partition_op_dentry.go
• 分片内目录遍历与版本过滤：metanode/partition_fsmop_dentry.go
• 协议层 Dentry 结构：proto/fs_proto.go
• 元数据操作码定义（OpMetaLookup、OpMetaReadDir等）：proto/packet.go

• 存储
• 分布式文件系统
• 对象存储
• 云原生