RepoKnow · 知仓

A self-hosted, model-free knowledge base for GitHub and GitLab repositories.

源码 · 反馈问题 · MCP 接入

把 Git 仓库变成可检索、可追溯的知识库。通过浏览器或 MCP 搜索文档、阅读代码、查询符号和直接调用线索。CPU 即可运行，无模型、无向量服务、无需 GPU 或 AI API Key。

基于 Git 固定快照、Tree-sitter 和 SQLite FTS5，采用 MIT 许可。当前为 0.2.0 早期版本。

功能

• 仓库导入：支持公开和有权限访问的私有 GitHub、GitLab、自建 GitLab 仓库，使用 HTTP(S) 克隆地址。

• 批量导入：分页发现 GitLab 组 / 子组、GitHub 组织（含 Enterprise）的可见仓库，逐仓库索引；已有分支跳过，无默认分支等情况说明原因。

• 成员准入：默认关闭公开注册；管理员创建、启用或停用普通成员，停用会撤销该成员的登录会话和只读 Key。

• 凭证复用：Token 按登录账号和平台域名加密保存，同域名仓库自动复用。

• 文档与源码：Markdown、源码行号、模块目录、路径筛选和固定 commit 的来源链接。

• 符号与调用线索：解析 Python、Go、JavaScript、TypeScript / TSX、Java；其他支持的文本格式仍可全文检索。

• 跨仓库检索：搜索文档、代码和符号，支持中文单字、完整短语优先，以及路径前缀 / 文件语言筛选；返回 commit、文件路径、行号和原仓库链接。

• 只读 MCP：AI 客户端可查询知识库，服务端不调用模型。

• 个人 MCP Key：每个成员可为不同客户端创建命名 Key，并单独撤销；完整 Key 仅创建时显示一次。

• 知识库设置：所有者可修改名称、在私有和团队共享之间切换，无需重新导入。

• 同步与隔离：同 commit 复用索引，新索引事务发布，失败保留旧版本；私有知识库仅所有者可读。

flowchart LR
  Git[GitHub / GitLab] --> Snapshot[只读 Git 快照]
  Snapshot --> Parse[文档提取 / Tree-sitter]
  Parse --> DB[SQLite / FTS5]
  DB --> Web[Web 知识库]
  DB --> MCP[只读 MCP]

Related MCP server: Kivgraph

快速开始

需要 Linux 或 macOS、Python 3.10+、Git 和 uv。Windows 可使用 Linux 容器或 WSL，本机进程管理依赖 POSIX。

克隆并启动：

git clone https://github.com/gdpu11/repoknow.git
cd repoknow
uv sync --locked
python3 scripts/manage.py start

打开 http://localhost:8090。首次启动随机生成管理员密码和只读 MCP Key，保存在 .data/admin.json，文件权限为 600。使用其中的 username、password 登录。

每次新安装都有自己的随机凭证；源码不携带预置密码、已导入仓库或预登录会话。

python3 scripts/manage.py status
python3 scripts/manage.py stop

停止服务会保留索引和凭证。可选导入两个公开示例：

.venv/bin/python scripts/demo.py

示例来自 go-chi/chi 和 GitLab Python 示例。只读取仓库，不执行其代码或安装其依赖。

账号与升级

默认关闭公开注册。管理员登录后，打开侧栏 团队成员 创建普通账户或停用 / 启用成员。停用立即撤销其登录会话和只读 Key；重新启用后需要重新登录，原 Key 不会恢复。仓库、索引和凭证保留，共享知识库仍按原可见性开放。管理员账号不能停用。

如确需公开自助注册，在启动进程环境中设置 REPOKNOW_ALLOW_REGISTRATION=1（Docker 在 compose.yaml 的 environment 中设置），然后重启；自助注册始终创建普通成员。

成员登录后可在侧栏 MCP 接入 创建自己的只读 Key，不需要接触服务器数据目录或借用管理员 Key。每个账号最多保留 20 个 Key，默认长期有效；不再使用的客户端应单独撤销，停用成员则撤销其全部 Key。

从 0.1.x 升级前，停止进程并备份整个数据目录；更新源码、执行 uv sync --locked 后重新启动。首次迁移将原启动时创建的首个账号设为管理员，其他账号保留为普通成员；原密码、MCP Key、平台凭证和索引保留。升级后公开注册默认关闭。不要删除或重新生成 admin.json、credentials.key 或数据库。

升级不会替换已有 MCP Key，仅补充用于列表和撤销的元数据。初始 Key 也可在界面撤销；撤销后 admin.json 中的旧值失效，重启不会恢复它。

Docker

需要 Docker Engine 和 Docker Compose v2。也可以直接用 Docker CLI 构建和运行镜像。

docker compose up -d --build
docker compose exec repoknow cat /data/admin.json

默认仅绑定 127.0.0.1:8090，使用独立的 repoknow-data 命名卷。不要和本机进程同时占用同一端口，也不要让两个实例访问同一数据库目录。

导入私有仓库、GitLab 组和 GitHub 组织

1. 打开侧栏 平台凭证，填 Git 平台域名，例如 https://gitlab.example.com、Git 账号和只读 Token。

2. 选择 导入仓库 / 组 / 组织，填写地址；默认复用同域名的平台凭证。

3. 等待后台索引完成，进入知识库浏览或检索。

GitLab 权限：单仓库克隆使用 read_repository；组发现加克隆使用 read_api 和 read_repository。Token 需要有目标组/仓库的访问权限，参见 GitLab 官方权限说明。Deploy Token 仅用于单仓库克隆，不用于组 API 发现。

GitHub 建议使用限定目标组织和仓库的 Fine-grained PAT，赋予 Metadata 读取和 Contents 读取权限；组织策略可能要求管理员批准或 SSO 授权。公开组织可匿名预览，受 GitHub API 限流影响。参见 组织仓库 API 与权限。GitHub Enterprise 在平台凭证中选择 GitHub，使用该实例的 Token，组织发现通过同域名 /api/v3 API。

• 分支留空时检测默认分支。组导入默认包含子组，排除其他组共享进来的项目。

• 完整发现成功后才写入任务，发现失败不留下部分导入；每个仓库独立索引，一个失败不影响其他任务。

• 重复导入只补充新仓库，不覆盖已有配置或刷新已有索引；已有仓库通过 同步更新 刷新。

• 平台凭证更新后，引用它的仓库在下次同步时使用新 Token；更新时留空保留原值，界面不回显旧值。

• 也可展开 仅为此仓库填写凭证。仓库页的 更新凭证 仅作用于该仓库，并取消其平台凭证引用。

组和组织不包括个人用户主页。界面可先“仅查看发现结果”，确认后再导入；当前不定时发现新增仓库，需再次发起批量导入。

导入后，所有者可在仓库页的 知识库设置 修改名称和可见性。“共享”允许全部启用的登录成员通过网页或各自的 MCP Key 读取；改回“仅自己可见”后，其他成员的新查询会失去访问权限，已读取或保存的内容无法收回。已有索引、分支、平台凭证和同步任务保持不变。

通过命令或 AI 代理导入

先在界面配置平台凭证，再使用本地管理命令：

.venv/bin/python scripts/import_source.py https://gitlab.example.com/engineering/api.git --wait
.venv/bin/python scripts/import_source.py https://gitlab.example.com/engineering --kind group --wait
.venv/bin/python scripts/import_source.py https://github.com/example-org --kind organization --wait

命令使用 .data/admin.json 登录本机管理 API，默认按域名复用凭证，不接受 Token 命令行参数。--connection 可指定已有凭证名称或 ID；--branch 指定单仓库分支；--no-subgroups 关闭递归子组。

默认返回创建结果；--wait 等待索引并报告逐仓库结果，默认 600 秒，--timeout 可调整。等待超时不取消后台任务。多级子组和仓库无法只凭 URL 区分，组导入请明确使用 --kind group。github.com 单层主页默认识别为组织；GitHub Enterprise 组织请使用 --kind organization。

代理可在用户授权后执行此命令，实现“导入这个仓库 / 这个组 / 这个组织”的对话操作；RepoKnow 本身不内置语言模型。

MCP 接入

端点：http://127.0.0.1:8090/mcp，使用 Streamable HTTP 的 JSON 响应模式。客户端发送：

Authorization: Bearer <read_only_api_key>

推荐登录自己的账号，在侧栏 MCP 接入 为客户端创建 Key。完整 Key 仅创建成功时显示一次，数据库只保存其哈希；丢失后请撤销并重新创建。首次安装的管理员 Key 仍保存在本机 .data/admin.json，不要将其分发给成员。

MCP Key 用于访问当前账号有权读取的知识库，与后台拉代码的 GitLab / GitHub Token 分开。不要将真实值提交到版本控制。

MCP 不提供导入、同步、Token 管理或代码修改。管理操作使用界面或登录认证的管理 API。源码查询严格校验 commit，版本不匹配会报错，不替换成新版本的同一行。

推荐先查询概览、浏览目录，再按 path 获取文件符号大纲。目录和符号分页均返回 next_offset；后续请求带上上一页 commit_id 作为 commit，同步导致版本变化时会明确报错。目录只包含成功索引的文件，不代表原仓库完整文件树。依赖概览支持 package.json、requirements*.txt、go.mod、PEP 621 / Poetry / uv 风格的 pyproject.toml 和 Cargo.toml，仅提取清单，不安装或解析远端依赖。

已有索引需要手动点一次 同步更新 才能启用新增的中文单字索引，即使远端 commit 相同也会重建一次。之后相同 commit 仍复用索引；本次升级不会自动批量同步你的仓库。

Codex 配置示例见 MCP 接入说明。源码包只提供占位配置，不会自动修改客户端的全局配置。

数据、安全与限制

• 数据默认在 .data/，数据库为 repoknow.sqlite3；REPOKNOW_DATA_DIR 可指定其他位置，REPOKNOW_PORT 可调整本机管理脚本端口。

• 导入和示例命令默认连接 http://127.0.0.1:8090；调整端口后，用 REPOKNOW_URL 指定对应的本机地址。

• Token 使用 AES-256-GCM 加密并绑定仓库/平台凭证 ID，密钥在 credentials.key。备份数据库时必须同时备份密钥；Git 缓存一并保存便于恢复。备份仍应按私有资料保护。

• Git 只读抓取到 bare 缓存，不 checkout、不执行仓库代码、依赖安装、构建、Git hook 或子模块递归。

• 批量发现 API 和管理命令不跟随重定向；平台凭证仅用于相同协议和域名。HTTPS 校验保持开启，内部 CA 需要正确安装到信任环境。

• .env*、常见私钥、生成产物、二进制和明显密钥模式会过滤，但过滤不等于完整 DLP。被授权索引的业务资料仍会保存在本机数据库中。

• 默认单文件 512 KiB、单仓库 2 万合格文件 / 64 MiB 文本、单次组 / 组织发现 5000 仓库；超过总预算会明确失败，不静默发布残缺索引。

• 只保留当前成功的索引快照。调用线索不覆盖动态分派、运行时或跨服务调用链。

• 当前为单实例、单工作器。“共享”表示所有启用的登录账号可读，管理员身份不额外获得他人私有知识库的读取权限。尚无 SSO、部门或角色级授权；对外部署前应落实 HTTPS、边界访问控制和备份，见 安全说明。

• 支持关键词证据检索和结构化概览，不生成架构长文、自然语言答案、OCR 或向量检索。

开发与验证

uv sync --locked
.venv/bin/python -m unittest discover -s tests -v
node --check app/static/app.js
python3 scripts/prepare_release.py --check

测试使用临时数据和临时私有 Git HTTP 服务，不需要真实 Token。参见 贡献指南、验证说明 和 源码包准备说明。

app/                  Web、MCP、Git 抓取、扫描、索引与权限
app/static/           无构建步骤、无 CDN 的中文前端
scripts/              本机管理、导入、示例和安全导出
tests/                权限、索引、私有认证和导出回归测试
docs/                 MCP、验证和发布流程说明
release-manifest.json  公开源码白名单

运行依赖及其上游许可证见 第三方依赖说明。导入的第三方仓库内容不属于本项目源码许可范围，不随源码包分发。