Nacre

---

Nacre 是一个可自托管的知识索引，支持细粒度访问控制。 Agent 通过 MCP 访问它，应用通过 REST API 访问它。没有聊天界面， 也没有企业助手——只有它们底层的上下文层。

为什么选择 Nacre

向量搜索已不再是难题。尚未解决的是：确保查询企业索引的 Agent 只能看到请求用户获准访问的文档，并能够向审计人员证明这一点。

• 权限可继承。 工作区 → 层，read/write/admin 自上而下继承。write 不代表拥有 read 权限；admin 则同时包含这两项权限。 文档级授权和拒绝规则属于商业功能——此版本会拒绝这些规则， 并明确说明原因，而不是接受无法向下传递的规则。
• 过滤在索引内部进行。 访问过滤器在 HNSW 遍历期间应用，而不是在排序后应用， 因此 top_k 返回的是 k 个符合权限的结果，而不是剔除部分结果后的 k 个结果。
• 将 MCP 作为一等入口。 按照 2026-07-28 规范提供 Streamable HTTP， 并为开发者 Agent 提供本地 STDIO。Agent 使用服务 账户密钥进行身份验证；提供 OAuth 发现（RFC 9728），而客户端注册 属于授权服务器的职责，不归我们负责。
• 混合检索，因为 Agent 会查询标识符。 使用互惠排名融合，将密集向量与 BM25 结合；部署配置了交叉编码器时，还会进行重排序。这并非差异化卖点—— 上面那一条才是我们诚实的说法——但 Agent 搜索 SQLSTATE 23505、发票编号 或变量名时需要精确匹配，而纯密集向量索引无法可靠地返回这些结果。
• 自带模型。 通过任何兼容 OpenAI 的端点生成嵌入，并按层绑定模型。 更改现有层的模型需要重新索引；在整个过程中，搜索仍可正常响应，并且只有在 针对你提供的查询集验证召回率后，才会切换到新模型。
• 命令行客户端。 npx @nacre.work/cli 可登录、创建层、将目录遍历导入层中并执行搜索—— 快速入门中列出的四条 curl 命令，适用于你想要结果而非操作约定的场景。 文档索引失败时会以非零状态退出，因此夜间导入不会在什么都没索引的情况下报告成功。
• 始终留在你的网络内。 使用 Docker Compose，不会主动向外通信。

快速入门

git clone https://github.com/nacre-work/nacre && cd nacre
cp .env.example .env
docker compose --profile minimal up -d

完整操作指南：docs/quickstart.md。

在 Apple Silicon Mac 上，请先阅读 docs/apple-silicon.md——镜像为 arm64，整个技术栈均为原生运行， 但嵌入模型服务是唯一需要在主机上运行的组件。

目录结构

packages/api        REST API and authorization service
packages/mcp        MCP server (Streamable HTTP + STDIO)
packages/worker     indexing pipeline: parse, chunk, embed
packages/core       data model, permission resolver, shared types
packages/sdk        TypeScript SDK
packages/admin      community admin UI
services/parser     Python sidecar: bytes → {text, blocks, metadata}
docs/               specifications — normative, and ahead of the code

状态

目前还处于早期阶段，但已经可以运行。整个流程端到端可用，并且已在真实的 PostgreSQL 和 Qdrant 上手动验证：创建组织、创建层、授予某人 read 权限、摄取文档、轮询作业直到状态变为 indexed，然后搜索并取回分块；再以未获授权的身份搜索，结果为空，尽管向量仍留在索引中。REST 和通过 Streamable HTTP 与 STDIO 提供的 MCP 两种方式都可用。撤销授权后，下次请求的结果中就会移除该文档：每次搜索都会根据授权计算允许访问的集合，因此索引中没有可能过期的缓存。

搜索按组织进行速率限制，不安全的方法必须携带 Idempotency-Key，集合按游标分页；部署配置了重排器时，搜索路径上会运行重排。已删除的向量会被清理，SDK 和管理 UI 也已编写完成。

登录功能已可用：支持邮箱和密码，并使用轮换刷新令牌；如果刷新令牌被重放，会结束会话。init 会创建首位管理员，并只显示一次生成的密码。SSO 是商业模块。

访问日志可读：GET /v1/audit，按时间倒序排列，按游标分页，支持 JSON、JSONL 或 CSV 格式。org_admin 可以看到哪些文档被读取——这正是审计日志要回答的问题；而 platform_admin 可以看到管理操作，但绝不会看到这些读取记录，这是规则 2 在日志中的体现。

可以将某个层迁移到不同的嵌入模型。Qdrant 不会为已存在的集合添加命名向量，因此会替换集合，而不是修改集合：复制所有点，不计算嵌入；用一条语句切换指针；然后逐层重新嵌入。搜索始终可用，而且始终只需一次查询。切换层之前，会使用新模型对该层的参考查询集进行评分；如果迁移导致召回率下降，就会停止迁移，而不会上线。只有在你编写查询集后，这道关卡才会启用，因为其中需要由你挑选文档。

除了通过 JSON 发送文档，也可以将其作为表单上传；PDF、Office 或 OpenDocument 文件（文本、演示文稿或电子表格）、EPUB 或 RTF 会由解析器 sidecar 提取内容。两种信号必须一致——表单声明文件类型，字节内容以对应签名开头——因为声明的类型与字节内容相矛盾就意味着不一致，而仅靠嗅探会让声明的类型沦为装饰。其他任何二进制格式仍会在入口处被拒绝；没有文本层的扫描 PDF 也会被拒绝，而不会作为空内容编入索引。

令牌可以使用 Ed25519 密钥签名，而不使用共享密钥；在这种情况下，公钥会发布在 /.well-known/jwks.json，只有签发令牌的进程持有私钥。

已从干净克隆运行 docker compose --profile minimal up，并通过该环境驱动了整个流程。

尚未构建的功能由商业许可涵盖，详见 docs/licensing.md：多租户、SSO、文档级权限和拒绝规则、ID-JAG、SIEM 导出、全局管理员以及配额。

docs/ 是规范文档，其中有些部分仍领先于代码——请从 docs/authz.md 开始阅读，其他所有内容都依赖它。

不变量

六条规则。违反其中任何一条都属于安全事件，而不是 bug。 详情见 docs/authz.md。

1. 组织只能从令牌中获取，不能从其他地方获取。
2. 访问过滤必须是预过滤，绝不能是后过滤。
3. 如果无法评估权限，就拒绝访问。
4. “没有权限”和“不存在此对象”必须返回完全相同的响应。
5. 已删除的文档绝不会被返回，包括垃圾回收之前。
6. write 不代表拥有 read 权限。

许可证

全部采用 Apache 2.0 许可证。上文提到的所有内容都在此代码仓库中，并会一直留在这里。

租户管理（停用、移交、配额）、基于 OIDC 的 SSO 和 SCIM 组同步、签发文档级授权和拒绝规则、EMA、SIEM 转发、全局管理员、备份、强制要求第二重验证，以及经过筛选的目录管理，都是商业模块。它们位于单独的私有代码仓库中，采用单独的许可证，且不会随本项目分发——关于两者的界限以及决定界限的那个问题，请参阅 docs/licensing.md。

当此构建遇到其中任一功能时，会明确拒绝：对于 deny 规则或文档范围的授权，它会返回 400 并说明原因，而不是接受请求后悄然不予执行。

Nacre 名称和标志是商标；请参阅 TRADEMARK.md。

支持本项目

这里没有托管版、席位数量限制，也没有任何按量计费，因此使用开源部分不会带来任何收入——这正是我们的初衷，也正因如此，我们值得说明是谁在为它买单。商业模块承担了这部分成本，并面向需要它们的组织；在笔记本电脑上运行本项目的开发者绝不会是被要求付费的人。

如果它为你省下了一周时间，可以点击此代码仓库顶部的「赞助」按钮来表达支持。此代码仓库没有任何内容需要通过赞助解锁，今后也不会有。