用 Docker 部署 Docs 开源协作笔记平台并完成文档协作、导出与权限配置

Docs 是一个开源的协作笔记与文档管理平台，由 suitenumerique 团队开发，后端基于 Django、前端基于 React。它面向需要多人共同维护文档的团队，也适合个人整理知识：多人在同一篇文档上编辑时改动实时同步，断网时内容先存在本地、恢复网络后再上传，文档可以导出为 PDF、Word 等格式，还能把零散笔记组织成团队 Wiki。它的设计参考了 Notion 与 Outline，但完全免费、基于 MIT 许可证发布，并且需要自己部署——没有官方托管的在线版本。如果你只是想先了解这类工具的整体定位，可以看 AI分享圈 上的工具条目；下面这篇则专注于把它真正跑起来并用起来。

需要先说明一点：Docs 目前仍在持续更新，功能与配置项都可能变化，本文涉及的版本号、默认端口、默认存储方案等信息请以项目当前状态为准。另外，本地用 Docker Compose 起服务只适合试用与验证，不能直接当作生产环境使用。

准备工作

确认 Docker 与 Docker Compose 已安装

Docs 依赖 Docker 和 Docker Compose 运行，这是唯一的前置软件要求。官方建议的版本是 Docker 20.10.2 与 Docker Compose 2.32.4。先在终端里检查当前版本：

docker -v
docker compose version

如果两条命令都能正常输出版本号，说明环境已经就绪。若提示命令不存在，需要先到 Docker 官网下载并安装对应平台的版本，安装完成后再重新执行上面的检查命令。

把当前用户加入 Docker 组

默认情况下，普通用户执行 Docker 命令需要加 sudo。为了避免后续每条命令都提权，可以把当前用户加入 docker 用户组：

sudo usermod -aG docker $USER

这条命令执行后不会立即生效，需要重启电脑（或者重新登录当前会话）才会应用新的用户组。重启后可以再跑一次 docker -v，如果不加 sudo 也能输出结果，说明配置成功。

准备代码与网络条件

除了 Docker，还需要能访问代码托管平台以克隆仓库，以及足够的磁盘空间用于存放镜像、数据库与上传的文件。第一次构建会下载较多依赖，建议在网络稳定的环境下进行。Docs 的 AI 辅助功能需要联网才能使用，这一点在后面的操作步骤里还会提到。

操作步骤

第一步：克隆代码仓库

打开终端，把 Docs 的代码下载到本地，并进入项目目录：

git clone https://github.com/suitenumerique/docs.git
cd docs

克隆完成后，当前目录下就是完整的项目源码，其中包含 Docker Compose 所需的配置文件。后续所有命令都在这个 docs 目录内执行。

第二步：构建并启动服务

在项目根目录运行：

docker compose up --build

这条命令会依次完成几件事：拉取所需的基础镜像、安装项目依赖、创建数据库、启动各个服务容器。--build 参数表示强制重新构建镜像，第一次运行时耗时较长，几分钟属于正常范围。终端持续输出日志，直到显示服务启动成功即可。

如果构建过程中出现报错，先看日志里第一个报错的位置，常见原因是网络中断导致依赖下载失败，或者端口被占用。修正后重新执行同一条命令即可，Docker 会复用已经下载好的层，不会从头再来。

第三步：访问并登录

服务启动后，Docs 默认监听本地地址 http://localhost:3000。在浏览器中打开这个地址，就能看到登录界面。

如果只是试用，可以直接使用官方提供的测试账号：

• 邮箱：test.docs@yopmail.com
• 密码：I'd<3ToTestDocs

注意密码中包含单引号、小于号和数字 3，输入时容易出错，建议直接复制。这个账号仅用于本地测试环境，不要在对外可访问的部署中使用。

第四步：新建并编辑文档

登录后，点击页面上的「新建文档」按钮，Docs 会打开一个空白页面，可以直接开始输入。编辑界面提供加粗、斜体、标题等基础排版能力，不需要记忆 Markdown 语法，通过工具栏按钮即可完成格式设置。

多人同时编辑同一篇文档时，你能看到其他人的光标位置，以及他们所做的改动实时出现在页面上。这一特性不需要额外开启，只要协作者都拥有该文档的编辑权限即可。

第五步：处理离线编辑与同步

当网络中断时，Docs 会自动把改动保存到本地，编辑不会被打断。网络恢复后，点击右上角的「同步」按钮，本地积累的改动就会上传到服务器。整个过程不需要额外配置，系统会自动处理本地缓存与服务器之间的差异。

需要留意的是，离线期间其他协作者的改动不会出现在你的页面上，重新同步后才会合并。如果同一段内容在离线期间被双方修改，建议同步后先核对一遍再继续编辑。

第六步：导出文档

文档写完后，点击右上角的「导出」选项，Docs 支持三种格式：

• .pdf：适合定稿分发与打印
• .doc：适合需要继续在文字处理软件中修改的场景
• .odt：适合使用开放文档格式的办公套件

选择目标格式后点击「下载」，文件会保存到本地电脑。导出的是当前文档内容，建议在导出前确认所有协作者的改动都已同步。

第七步：使用 AI 辅助功能

Docs 内置了若干 AI 能力，包括生成文本、总结内容与翻译。使用方式是先选中一段文字，再点击工具栏上的「AI」图标，然后选择「生成」或「翻译」等操作。

例如输入「写一段介绍」，AI 会据此生成内容；选择翻译时，先指定目标语言，AI 会把选中的文字翻译成该语言。这些功能依赖网络连接，离线状态下无法使用。

第八步：设置文档权限

要控制谁能查看或修改文档，在文档页面点击「分享」按钮。Docs 提供三种权限级别：

权限	效果
只读	被邀请者可以查看内容，但不能修改
可编辑	被邀请者可以查看并直接修改内容
不可见	被邀请者无法访问该文档

输入协作者的邮箱地址，选择对应权限，点击「确认」即可完成邀请。设置生效后，只有被邀请的人才能访问这篇文档，未获授权者看不到内容。

第九步：搭建团队 Wiki

Docs 可以把多篇文档组织成 Wiki，形成团队知识库。操作路径是：点击左侧菜单的「Wiki」选项，选择「新建 Wiki」，然后把已有文档拖入其中，或者直接在 Wiki 里撰写新内容。

整理完成后，团队成员通过 Wiki 入口就能浏览整个知识库，不必再逐篇搜索文档。适合把项目规范、会议记录、常见问题这类需要长期沉淀的内容集中放置。

一个完整示例

下面把前面的步骤串成一条从零到可用的最短路径，假设你在一台已安装 Docker 的机器上，准备为一个小团队搭建内部知识库。

1. 检查环境

docker -v
docker compose version

两条命令都返回版本号后继续。若需要免 sudo，执行 sudo usermod -aG docker $USER 并重启。

2. 获取代码

git clone https://github.com/suitenumerique/docs.git
cd docs

3. 启动服务

docker compose up --build

等待终端显示服务启动成功，期间不要中断命令。

4. 登录

浏览器打开 http://localhost:3000，用测试账号 test.docs@yopmail.com / I'd<3ToTestDocs 登录。

5. 建文档并协作

点击「新建文档」，写下团队的第一篇规范文档。邀请一位同事，把权限设为「可编辑」，让对方打开同一篇文档，确认双方能看到彼此的光标与实时改动。

6. 验证离线同步

断开网络，继续在文档里补充几段内容，确认编辑没有中断。恢复网络后点击右上角「同步」，检查新增内容是否已上传到服务器。

7. 导出留档

点击右上角「导出」，选择 .pdf 并下载，确认文件内容与页面一致。

8. 组织成 Wiki

点击左侧菜单「Wiki」，选择「新建 Wiki」，把刚才的文档拖进去，再补充几篇相关文档。至此，一个可用的团队知识库雏形就完成了。

注意事项

存储服务默认使用 Minio

Docs 默认以 Minio 作为存储服务。如果希望改用其他 S3 兼容存储（例如 AWS），需要修改配置文件，具体做法参见项目中的 installation.md 文件。在修改之前，建议先确认现有部署可以正常读写文件，避免排查时混淆问题来源。

本地部署不等于生产可用

用 docker compose up --build 在本地跑起来的实例只适合测试。生产部署需要额外配置，例如启用 HTTPS。直接把本地实例暴露到公网会带来安全风险，尤其是使用默认测试账号的情况下。

AI 功能依赖网络

生成文本、总结与翻译都需要联网才能使用。在离线编辑场景下，这部分功能不可用，但普通的文档编辑与本地保存不受影响。

移动端只有网页版

Docs 目前主要是网页版，手机浏览器可以打开，但没有专门的手机 App。移动端的使用体验与桌面端存在差异，重要编辑操作建议在桌面浏览器中完成。

项目仍在演进

Docs 仍在持续更新中，功能与界面可能随版本变化。本文描述的按钮位置与操作路径以当前版本为准，升级后如有出入，以实际界面为准。价格、功能范围与配额等信息请以项目官网当前公布的内容为准。