法德政府联合推出的开源文档协作编辑器，支持实时协作、子页面层级、数据自托管，基于 Django 与 React 构建，是 Notion 或 Outline 的替代品。

Docs：开源、协作、数据自主——一场来自政府的知识管理革命

如果你关注 Hacker News，最近被 1952 分热度推上首页的 Docs 项目你一定不陌生。这不是又一个写着 "open source Notion alternative" 的仓库——它的背后是法国政府和德国政府的联合推动，目标是创造一个真正属于公共部门与开放社区的知识协作工具。

在深入代码和功能之前，先回答一个核心问题：在 Notion、Outline、AppFlowy、AFFiNE 等众多选择中，Docs 凭什么值得你投入时间去了解？答案可能在于它的出身、架构选择与协作哲学。

项目定位：一个政府级别的开源文本编辑器

Docs 是 La Suite（法国公共部门数字工具套件）的一部分，由法国政府数字部门 DINUM（Direction interministérielle du numérique）与德国政府 ZenDiS（Zentrum für Digitale Souveränität）联合主导。目前正在纳入荷兰政府作为新合作伙伴。

官方定位：Docs 是一个 Web 原生、面向实时协作的开源文本编辑器，提供清晰结构化的文档与子文档管理，并保证用户对数据的完全所有权。

从技术上来说，它的核心产物是一个类似 Notion 的现代文档工具，区别在于——你可以把它完整部署在自己的服务器上，数据完全自主可控，且没有任何厂商锁定。

核心功能拆解：不止于编辑器

1. 写作体验：富文本与 Markdown 的双重支持

Docs 的编辑器底层构建在 ProseMirror 之上，外层使用 BlockNote.js 提供块结构。这意味着它同时支持富文本与 Markdown 输入，并且提供斜杠命令（slash command）与块系统来组织内容。

具体写作特性包括：

• 富文本与 Markdown 双模式编辑
• 斜杠命令快速插入不同区块（标题、列表、引用、代码块等）
• 美观的格式化输出
• 离线编辑支持
• 可选的 AI 写作助手（重写、摘要、翻译、纠错）

关于离线编辑：Docs 使用 Yjs 作为 CRDT（无冲突复制数据类型），这是目前实时协作领域最成熟的开源方案之一。即使网络断开，你依然可以继续编辑文档，待网络恢复后 Yjs 会负责合并冲突。

2. 实时协作：不只是同时编辑

协作功能看起来是标配，但 Docs 在细节上有自己的思考：

• 实时光标（Live cursors）：你能看到协作伙伴的光标在哪个位置、正在输入什么。这种存在感（presence）对于远程团队尤其重要。
• 评论与分享：支持段落级评论，并可设置粒度化的访问控制。
• 细粒度权限管理：支持不同用户对文档的不同操作权限（查看、评论、编辑、管理）。

与 Google Docs 的实时协作不同，Docs 并不要求你信任谷歌的云基础设施。你可以自托管整套服务，后端提供 Django REST Framework 的 API，前端是 Next.js。这种技术栈选择使得它非常适合集成到已有的政府或企业 IT 生态中。

3. 知识管理：子页面与层级结构

这是 Docs 区别于 Google Docs 的重要方面——它不是单一文档编辑器，而是一个知识库管理系统。

• 子页面（Subpages） 与层级结构（Hierarchy）允许你将文档组织成真实的知识树。这类似于 Notion 的页面嵌套，但不依赖数据库，而是通过父子关系的文档对象来实现。
• 全文搜索覆盖所有文档内容。

这意味着，无论你是维护一个团队知识库、产品文档还是个人笔记，Docs 都能将分散的文档组织成一个可导航、可搜索的整体结构，而不是一堆孤立的 Markdown 文件或 Google Docs 链接。

4. 演示模式：超出文档本身

Docs 内置了一个演示文稿功能，它并不像 PowerPoint 或 Google Slides 那样基于独立的演示文稿文件，而是在文档内容中通过分隔符 --- 来定义幻灯片边界。

你可以：

• 使用键盘导航进行演示
• 从任意一个文档块开始演示（不限于文档开头）
• 生成演示链接（可以发送给其他人直接观看）
• 导出 PDF

这实际上是让知识文档本身变成演示素材——你无需在笔记和演示文稿之间不断拷贝粘贴。

5. 导入与导出：尊重互操作性

Docs 支持导入 .docx 和 .md 格式，导出 .docx、.odt（开放文档格式）和 .pdf。这背后是政府对开放标准和互操作性的重视——确保文档不会被锁死在某一个平台里。

---

深入技术细节：架构与依赖

从仓库结构可以看到，Docs 使用了一套现代且成熟的技术栈：

• 后端：Django REST Framework（Python），负责 API、认证、权限与持久化。
• 前端：Next.js（React），负责 UI 与编辑器交互。
• 编辑器内核：ProseMirror（一个灵活、可扩展的富文本编辑器框架）
• 块编辑器：BlockNote.js（开源块编辑器组件库）
• 实时协作：Yjs（CRDT 实现）与 HocusPocus（Yjs 的 WebSocket 服务端）

这个栈的优势在于：

1. Django 提供成熟稳健的后端基础设施（用户认证、ORM、权限、Admin 界面）
2. Yjs + HocusPocus 让实时协作不必放在 Electron shell 或专有云服务上，而是可以完全掌控
3. BlockNote.js + ProseMirror提供了比普通 contenteditable 更可靠、可编程的文档编辑体验

特别值得提的是，Docs 团队是 BlockNote.js 和 Yjs 的赞助商之一——这说明他们不仅仅是使用这些库，而是在支持开源生态的发展。

Docker 与部署

如果你想要快速体验或部署 Docs，官方提供了完善 Docker Compose 和 Kubernetes 支持，还附带了 PaaS（如 Scalingo 等）部署配置。系统还支持通过 Nix 或 YunoHost 等社区方法安装。

本地开发环境下，Docs 使用 Minio 作为 S3 兼容的对象存储服务来实现文件存储。在生产环境中，你可以替换为任意 S3 兼容服务（AWS S3、Ceph、Minio 等皆可）。

bash

克隆后快速开始

make bootstrap FLUSH_ARGS='--no-input' # 构建容器、安装依赖、执行迁移
make run # 启动服务

访问 https://localhost:3000

开发环境默认（仅限开发用途）账号密码都是 impress。开发环境还提供 Django Admin 界面（默认运行于端口 8071）用于管理用户和数据。

对于前端开发者来说，可以不使用 Docker 容器，直接在宿主机运行 frontend-development 模式以获得更快的热更新速度。

---

AI 功能：双重架构的取舍

Docs 中的 AI 特性是一个有意思的话题。它明确区分了两种版本：

V1：选中即替换（Select & Replace）

• 你选中一段文本，然后输入指令（如"重写这段文字让它更像正式公文"或"将这段话翻译为法文"），AI 模型会返回替换文本
• 优势：交互简单、流程明确，不需要理解复杂对话状态

V2：AI 工具栏与 AI 光标（Beta）

• 基于 BlockNote 的 AI 集成功能
• 候选展示是**流式（streaming）**的，你可以在生成过程中看到字符逐个出现
• 支持在工具栏中接受、拒绝、迭代调整生成结果
• AI 光标的概念很有趣：AI 不是在一个独立的对话窗口中操作，而是像一位协作者一样直接在你的文档中移动光标并输出内容，让生成过程更加透明且有上下文感

模型无关性与网关无关性是 Docs AI 功能的重要设计原则：你只需要提供一个 API Key 和 URL，就可以接入任意兼容 OpenAI 或同类接口的模型提供商，也可以自建网关（如 vLLM、LiteLLM 等）。

鉴于 Docs 面向政府机构，这种设计尤为重要——政府不能将敏感文档发送到美国商业公司的云端 AI 服务中。通过自托管 LLM（例如使用 Mistral 或 Llama 的独立部署），Docs 可以在内网环境中提供完整的 AI 辅助能力，同时不泄露任何数据。

---

互操作性：服务端 API 与 Meet 集成

Docs 提供了两种 API：

1. Resource Server API：供前端或其他客户端调用的持久化 REST API
2. Server-to-Server API：允许其他服务安全地向 Docs 推送数据

官方给出了一个很棒的实际案例：如果你在运行 Meet（自托管的视频会议服务），通过简单的环境变量配置（DJANGO_SERVER_TO_SERVER_API_TOKENS），你可以将会议的自动转录文本推送到 Docs 中，并为发起请求的用户自动分配访问权限。

这个实例体现了一个核心理念——Docs 不只是孤立的知识库，它应该成为集成生态的一环，服务端 API 让它可以轻松与内部工具（会议记录、客服工单、政务流程系统等）连接在一起。

---

开源许可证：MIT 选择背后的策略

Docs 使用 MIT 许可证，这是一个非常宽松的开源许可证。有趣的是，在这个决定背后有明确的策略动机：

"我们的许可证选择是邀请私营部门参与者使用、销售并为项目做出贡献。"

政府创建的软件为何要让私有企业使用？因为政府的核心目标是推动这项技术的普及和可持续——如果一家商业软件公司能够基于 Docs 提供付费托管服务（SaaS），那不是竞争，而是生态扩展。一旦有更多开发者参与贡献，项目长期维护和发展就有了更多可能性。

然而，这里有一个重要复杂之处：并不是所有依赖都是 MIT 兼容的。官方警告中指出，一些高级功能（例如导出 PDF）依赖于 Blocknote 的 XL 包，这些包是 GPL 许可的，与 MIT 不兼容。因此，如果你想完全避免 GPL 代码，需要添加构建参数：

bash
PUBLISH_AS_MIT=true

这会构建一个不包含非 MIT 特性的 Docs 镜像。从法律角度讲，这个设置非常贴心——它允许政府和私营企业在不被 GPL 污染的情况下使用该软件。

---

社区、路线图与治理

Docs 目前 GitHub 仓库拥有 16.8k stars 和 625 forks，这是一个相当健康的增长态势，项目保持着活跃的社区热度。目前共有 2,332 个提交，仓库结构完整而有纪律（包括 CONTRIBUTING.md、SECURITY.md、CODE_OF_CONDUCT.md、CHANGELOG.md、publiccode.yml 及安全审计报告 secu-audit.md）。

官方提供三种交流渠道：

• Matrix（开源聊天室）用于实时讨论
• GitHub Issues 用于 Bug 报告与功能建议
• 公共路线图用于查看项目未来计划与优先级

翻译系统采用 Crowdin 平台，这是很好的国际化策略。考虑到政府背景，支持多语言是产品刚需，评论区中有多个语言（至少法文、德文、中文等）的社区讨论。

---

深度审视：Docs 与 Notion、Outline 的对比

与 Notion 的比较

Notion 是目前最流行的全能型笔记与知识库工具，它拥有极佳的用户体验和很高的定制能力（数据库、模板、API）。但正因为其业务模式是专有 SaaS，Notion 存在几个无法回避的问题：

1. 数据安全：你的所有笔记文本都存储在 Notion 云上，虽然在传输与静态加密层面有保护，但 Notion 的数据模型是封闭的，你无法将自己的数据迁移到另一个系统而确保格式不失真。
2. 价格：个人免费版有块数和文件大小限制，团队使用昂贵。
3. 架构：Notion 是纯粹的单体 SaaS，没有自托管选项，也没有私有化可能性。

Docs 选择了完全相反的道路：数据完全属于你，自托管选项，服务端 API 可以集成任何内部系统。当然，Notion 的成熟度（插件生态、第三方应用丰富度、数据库功能）超过 Docs 目前的版本，但如果你需要的是治理性强、数据可控的知识库，那么 Docs 在架构上更贴近这一目标。

与 Outline 的比较

Outline 是目前常被视为开源 Notion 替代品的最先进项目。两者相比：

• 架构上：Outline 使用 React 前端 + Node.js 后端；Docs 使用 Django + React（Next.js）
• 编辑模型中：Outline 早期历史偏传统博客与文档处理，Docs 以实时协作 CRDT（Yjs）为核心进行设计，实时体验更加原生
• 治理上：Docs 有着双政府背景，治理机制以及安全、合规路径具有更高的公信力和延续性——在中国，这意味着它更容易通过国内政府或国有企业的安全审查
• 权限模型：Docs 的细粒度权限控制架构上更适合复杂组织架构，而 Outline 以空间为单位的权限简单得多

不过需要承认：如果只看代码成熟度和社区生态，Outline 起步更早，文档与部署指导可能更为成熟。但 Docs 的增量迭代速度极快，且有着政府级的资源投入，可以预期未来表现会持续提升。

安全与治理：值得关注的结构特征

考虑到数据安全，Docs 提供了几个关键设计特征：

1. 数据可迁移：因为是自托管，你可以随时从 Postgres 数据库导出裸数据，配合 S3 对象存储中的媒体文件，完全迁移到别的系统无需供应商同意。
2. 部署可控：可用 Docker Compose 或 Kubernetes 在完全隔离的网络环境中部署，不依赖任何外部网络通信。
3. 审计与社区验证：公开的安全审计报告与活跃的安全响应渠道（SECURITY.md）可以在将 Docs 部署在关键基础设施前对齐你的安全要求。
4. AI 数据与 Gateway 的隔离性：你控制 AI 工具发送数据的模型连接和令牌，这从根本解决了使用公共 AI 服务时数据泄露的痛点。

---

如何开始使用 Docs？

0 成本体验：直接点击官方实时 Demo 链接，浏览一个活的 Demo 文档，无需任何安装：https://docs.la-suite.eu/

部署自己的实例：

• 克隆仓库到服务器
• 配置环境变量（参照 env.d/ 目录）
• 使用 Docker Compose 或 K8s 部署

社区也维护有 Nix 与 YunoHost 的自动部署方式，其中 YunoHost 方法让任何非技术人员也可以像安装手机App一样在低配 VPS（例如 2GB 内存）上完成部署。

---

未来展望与潜在挑战

虽然 Docs 在架构和理念上都相当引人注目，它依然面临显著挑战：

1. 成熟生态的竞争：Notion 的品牌效应和便捷性使很多人甚至不会考虑开源自托管方案。
2. BlockNote 依赖的不确定性：ProseMirror 虽本身稳定，但 BlockNote.js 较年轻，其发展节奏与路线图不完全受 Docs 团队控制。GPL 包混用问题在团队向更多功能扩展时可能变得难以规避。
3. 采用范围的局限：可以预期，Docs 的主要用户群体会集中在欧洲公共部门、开源社区、亚洲与大洋洲政府数字基建。对于普通个人用户来说，Docs 的部署和维护成本高于“注册即用”的 SaaS 方案，他们更可能选择在不期待最低总拥有成本的场景下使用。

然而，这依然是迄今为止最值得关注的一个“政府主办开源软件”项目，因为它做对了几件关键的事情：

• 用主流开源组件构建坚实技术基础
• 通过务实挑选的 MIT 许可证吸引企业开发者参与
• 以各国政府牵头为安全性和长期维护奠定公信力
• 将 AI 功能、演示模式和实时协作开箱即用做到足够完善

写在最后

Docs 不仅仅是一个“替代品”，其价值主张更接近于：当技术主权与数字自主被当成设计原则时，一款现代协作编辑器应该长什么样。它会成为越来越多对于数据主权敏感的机构——政府机关、国企、研究机构、隐私导向的初创团队的首选之一。

它的背后是“政府以实际行动支持开源”的范式转移，值得我们持续关注它的演进。

原文链接：https://github.com/suitenumerique/docs