MongoDB不能存储Git对象（blob/commit），因其16MB BSON限制易超限，且缺乏Git必需的SHA内容寻址、DAG结构、delta压缩及reflog等原生机制；强行存储将导致Git CLI操作失效、查询性能暴跌、WAL与复制集压力过大。
直接说结论：MongoDB 本身不替代 Git，但可以模拟 GitHub 的仓库元数据结构；真正存储 Git 对象（blob/tree/commit）必须用 Git 本地仓库或专用对象存储服务，MongoDB 只适合存 repos、branches、pullRequests 这类高查询频次、带权限和关系的元数据。
为什么不能把 Git 对象（blob/commit）直接塞进 MongoDB 文档？
MongoDB 的 BSON 文档有 16MB 上限，而单个大型二进制 blob（如压缩包、视频、大图片）很容易超限；更重要的是，Git 对象依赖 SHA-1/SHA-256 内容寻址与 DAG 结构，MongoDB 没有原生支持对象哈希校验、delta 压缩、reflog 回溯等机制。强行用 Buffer 存 commit.raw 或用嵌套文档存 tree 结构，会导致：
- 无法用标准 Git CLI 操作这些“伪对象”
- diff、blame、rebase 等操作全部失效
- 索引无法覆盖任意层级 path（如
"tree.entries.0.children.3.path"），查询性能断崖下跌 - WAL 日志和复制集对频繁小更新（如每次
git add）压力过大
repos 集合该存什么？字段设计怎么避坑？
参考 GitHub API v3 的 /repos/{owner}/{repo} 响应体，repos 集合只存可索引、可聚合、需权限控制的元信息：
OpenClaw 技能 — 给定一个 GitHub 仓库 URL，自动解析出 owner/repo 名称，发现其中的 YAML/properties 配置文件及其配对的中文字段说明；在 `workspace/{repo}/` 目录下按同步日期（格式为 `YYYY-MM-DD`）创建时间戳子目录；写入 `.openclaw-config-state.json` 状态文件。每次用户提问前，先比对远程仓库当前 ref（如 `main` 或 `master`）的最新提交 SHA 与本地状态文件中记录的 SHA：
-
name和full_name必须建唯一复合索引：{ "owner": 1, "name": 1 }，防止同名仓库冲突 -
default_branch类型用 string（不是 ObjectId），因为分支名是动态字符串，不是固定集合引用 -
git_url字段存形如"git@github.com:user/repo.git"的地址，别存 HTTP URL——它不用于 clone，只作展示和跳转 -
size字段单位是 KB，定期从真实 Git 仓库调用git count-objects -vH更新，不要靠 MongoDB 自己累加 - 避免在文档里嵌入
topics数组超过 20 项——数组过大影响索引效率，改用单独repo_topics集合 + 多对多关联
如何关联分支、提交、PR 而不破坏 Git 语义？
核心原则：MongoDB 只存指针，不动 Git 对象本身。例如：
-
branches集合每条文档含repo_id: ObjectId、name: "main"、commit_sha: "a1b2c3..."，其中commit_sha是字符串，不是 ObjectId；查询某分支最新提交时，用这个 SHA 去调用本地git --git-dir=/path/to/repo/.git show a1b2c3... -
pullRequests集合中head和base字段各含{ repo_id, ref, sha }三元组，确保跨仓库 PR（fork 场景）也能准确定位 - 所有时间字段统一用
Date类型，别用字符串存"2026-05-11T11:29:00Z"——否则无法用$dateToString聚合，也建不了 TTL 索引自动清理过期 PR
权限字段怎么设计才不被绕过？
GitHub 的权限模型是“用户 → 组织角色 → 仓库角色 → 分支保护规则”四层嵌套，MongoDB 里不能靠一个 permissions 字符串糊弄。正确做法是分三层存：
-
repo_access集合：记录user_id、repo_id、role: "admin" | "write" | "read"，查用户对某仓库权限时走这个集合 -
branch_protection集合：每条对应一个分支，含repo_id、branch_name、required_status_checks、enforce_admins等布尔/数组字段 - 关键动作（如 push、merge）必须由应用层先查这两张表，再调用真实 Git 命令；绝不能让客户端传来的
user_role直接决定是否允许git push
最容易被忽略的是：所有涉及权限的查询必须加 .hint({ user_id: 1, repo_id: 1 })，否则在百万级仓库量下，全表扫描会让鉴权延迟飙升到秒级。
