Docmost私有化部署全流程：Docker编排、Nginx代理与运维避坑

最近我把团队内部的文档系统整体换了一次，最终选定了Docmost并完成了私有化部署。折腾完这一轮，我把选型理由、部署步骤、运维经验和踩坑记录都整理在下面。如果你也在考虑自托管一个文档管理软件，或者已经决定用Docmost但卡在部署阶段，这篇文章可以直接照着抄。

先交代一下背景。我这边是十来个人的小团队，原来文档散落在腾讯文档和本地Markdown文件里，权限混乱、搜索基本靠记忆、新旧版本分不清。想找一个能私有化部署的文档平台，要求很朴素：开源、可自托管、支持实时协同编辑、有清晰的目录结构、最好带基础的权限管理。对比过Notion、Confluence、Outline等几个方案之后，最后锁定了Docmost。它是一个基于Node.js的开源协作文档平台，官方提供Docker镜像，界面观感和Notion接近，支持工作空间（Space）、页面树、实时多人编辑、评论和Markdown语法，部署门槛确实是我测过的几个方案里最低的——一个Compose文件拉三个容器起来，十分钟内就能进入初始化流程。

1. 为什么我会在自托管选型里锁定Docmost

1.1 先搞清楚它到底是什么

Docmost，简单说就是一个可以自己部署的协作式文档平台，功能上可以理解成Confluence和Notion的轻量合体。核心能力包括：多工作空间隔离、无限层级页面树、多人实时协同编辑、行内评论与讨论、Markdown编辑体验、全文检索，以及成员权限管理。最要紧的是它开源，代码在GitHub上，内部自托管没有授权费用问题，数据全程在自己手里，不用担心厂商锁定或第三方数据留存。

这里单独展开讲一下"实时协同编辑"，因为它直接决定你最后用得顺不顺手。Docmost的编辑器基于TipTap，底层是ProseMirror这套成熟的富文本框架，用类CRDT的方式做实时同步。两个人同时打开一篇文档改同一段文字，对方屏幕上会几乎无延迟地看到光标位置和改动内容，不是传统"保存后刷新才看到"的体验，和Google Docs差不多的感觉。这个能力依赖浏览器与服务器之间维持一条常驻连接，所以一旦用反向代理部署，WebSocket的转发配置就成了生死线。这一点我会在第6节专门讲坑。

1.2 和几个主流竞品对比后的取舍

我当时把候选方案拉了一张对比表，核心差异点其实很集中：

表格只是参考，最后让我定下来的其实是三个细节。一是Docmost的实时编辑流畅度，我在测试环境里拉了两个窗口同时写一份长文档，没有出现丢字、错位或光标乱跳；二是权限模型很简单明确，成员、编辑者、管理员三级角色，基本覆盖我们团队的使用场景，不用为"谁能不能看这个空间"反复折腾；三是部署复杂度的确低，不用编译源码、不用手动装Node环境，官方镜像把运行时都打包好了。反过来，如果你对插件生态有硬需求，现阶段的Docmost会让人失望，它目前就是把"文档这件事做扎实"，没有流程图组件、没有数据库表格、没有自动化流程。这类重型需求，还是踏实用Notion或者Confluence。

1.3 什么场景适合，什么场景别硬上

从我这段时间的真实使用来看，Docmost最适合的形态是：中小团队的内部知识库、项目协作文档、会议纪要沉淀、新人手册、技术方案归档。它的优势在于"快"和"轻"——打开就能写，写完就能共享，页面树一拉就能找到上下文。如果你的团队需要大量和外部客户共享文档，或者需要嵌入第三方系统做流程集成，现阶段用Docmost会比较吃力。另外它的附件功能定位是"文档辅助"，上传图片和普通文件没问题，但别指望它能替代企业网盘，也别把几百GB的资料往里塞。

2. 动手之前列好清单：服务器、域名、Docker环境

2.1 硬件与系统的最低要求

先说服务器。Docmost官方推荐配置听起来不吓人，但实际用下来我建议至少2核4G起步，硬盘根据文档量预留，一般团队20G到50G足够用很久。我把我们团队的实际表现说一下：2核4G的云服务器上，十几个人同时在线、偶尔几个人同时编辑同一篇文档，内存占用大概稳定在2.5G到3.2G之间，CPU平时都在个位数，只有全文搜索或首次打开大文档时会短暂冲高。如果只是三五个人用，2核2G也能跑，但遇到协同编辑高峰期会有明显卡顿，所以不建议太抠。

系统方面，我个人推荐Ubuntu 22.04或24.04 LTS。Docmost本身对系统没有挑剔，只要是能装Docker的Linux基本都能跑，但Ubuntu的Docker生态和文档资料最全，遇到问题搜解决方案最容易。不推荐用CentOS 7这种已经停止维护的老系统，Docker新版对老内核的兼容性早晚会让你头疼。

2.2 安装Docker和Compose插件

Docmost官方镜像依赖Docker和Docker Compose。现在Compose已经作为Docker的插件集成进来了，不再需要单独装docker-compose这个Python工具，命令统一用docker compose（中间有空格）。安装方式官方推荐用apt源，但国内服务器如果直接连官方源容易超时，我一般直接换用可用的镜像源，然后把官方源的GPG key装好，这步属于常规操作，具体命令如下：

# 安装依赖 sudo apt update sudo apt install -y ca-certificates curl # 添加Docker官方GPG key（源根据实际网络环境选择） sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 添加apt源 echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

装完验证一下：docker --version和docker compose version都能正常输出版本号就说明环境OK。这一步的坑主要在网络源上，如果apt update一直卡住或者报404，优先检查源地址是否可达，换一个可用的镜像源再试。

2.3 域名和DNS的准备工作

如果只是内网测试，服务器IP加端口直接访问就行。但正式使用我强烈建议准备一个域名，比如doc.example.com，原因有三个：一是浏览器对IP直连的Cookie、安全策略时不时会给你添乱；二是后面要上HTTPS证书，免费证书签发必须要域名；三是同事记域名比记IP加端口容易太多。先在DNS管理后台加一条A记录，把doc.example.com指向服务器的公网IP，TTL设短一点（300秒），等解析生效再继续。

2.4 部署前需要备好的几个参数

动手写Compose文件之前，先把下面这些变量准备好，省得中途手忙脚乱：

• APP_URL：最终用户访问文档站的完整地址，比如https://doc.example.com。这个变量非常关键，填错会直接导致登录跳转异常，我后面会详述。
• APP_SECRET：用于会话签名和敏感数据加密的随机密钥，至少32位。生成方法很多，我习惯用openssl rand -hex 32，生成一串64位的十六进制字符串。
• 数据库密码：Postgres的独立密码，别用太简单的，建议也用openssl rand -hex 16生成。
• 服务器公网IP和域名：上面已经准备好。
• 数据目录：我习惯在/opt/docmost下放Compose文件，数据全部交给Docker volume管理，这样备份和迁移都简单。

3. 三容器Compose编排：Postgres、Redis、Docmost一次跑通

3.1 编排文件逐段拆解

Docmost的部署架构是三个容器：应用本体 + PostgreSQL + Redis。为什么用Postgres而不是SQLite？因为文档平台是典型的并发读写场景，PostgreSQL的MVCC机制能同时支持多人读和多协作者写入，SQLite这种单文件数据库在写锁上会明显拖后腿。Redis则承担会话缓存和部分实时同步的中间状态，挂了不会丢数据，但会导致所有用户被迫重新登录和协作短暂中断。

下面是我实际在用的Compose文件，去掉了敏感信息，结构保持官方推荐版本：

services: docmost: image: docmost/docmost:latest depends_on: - db - redis environment: APP_URL: https://doc.example.com APP_SECRET: 你的随机密钥 DATABASE_URL: postgresql://docmost:你的数据库密码@db:5432/docmost REDIS_URL: redis://redis:6379 CORS_ALLOW_ORIGIN: https://doc.example.com ports: - "127.0.0.1:3000:3000" volumes: - docmost-storage:/app/data/storage restart: unless-stopped db: image: postgres:16-alpine environment: POSTGRES_DB: docmost POSTGRES_USER: docmost POSTGRES_PASSWORD: 你的数据库密码 volumes: - postgres-data:/var/lib/postgresql/data restart: unless-stopped redis: image: redis:7-alpine restart: unless-stopped volumes: - redis-data:/data volumes: docmost-storage: postgres-data: redis-data:

注意几个我在写这个文件时特别注意的细节。第一，应用端口我映射成了127.0.0.1:3000:3000，只绑本机回环地址，不让宿主机公网直接暴露3000端口。这样即使Nginx配置出了问题，外部也无法绕过反向代理直接打到应用上，多一层安全感。第二，depends_on只保证容器启动顺序，不保证依赖服务已经"可用"，所以第一次启动时如果看到Docmost容器报数据库连接失败，不用慌，它内部有重试机制，等几十秒会自己恢复。第三，restart: unless-stopped一定要写上，服务器重启后容器能自动拉起来，这是自托管服务的保命配置。

3.2 环境变量填错了会怎样

环境变量是这套部署最容易翻车的地方，我把最常见的两类错误说透。

第一类是APP_URL与真实访问地址不一致。假如你配的是http://localhost:3000，但同事们实际通过https://doc.example.com访问，就会出现"登录时明明输入对了账号密码，却一直在登录页打转"或"认证成功后跳回首页但不是当前用户状态"的症状。原因很简单：应用用它认为的"自己地址"来生成各种回调链接、Cookie作用域和CSRF校验，地址对不上，这条信任链就断了。所以务必把APP_URL写成用户最终访问的完整外网地址，包括协议头。

第二类是DATABASE_URL里的密码或数据库名和Postgres容器对不上。这种错误最直接的表现是应用容器不断重启，日志里能看到connection refused或password authentication failed。排查时先docker compose logs db确认数据库容器是否正常起起来了，再docker compose exec db psql -U docmost用同样的账号密码手动登一下，基本几秒钟就能定位。

3.3 首次启动与管理员初始化

把Compose文件保存到/opt/docmost/docker-compose.yml之后，进入目录执行：

cd /opt/docmost docker compose up -d

-d参数是后台运行。首次执行会拉取三个镜像，Postgres镜像约50MB、Redis约30MB、Docmost本体约几百MB，取决于网络速度。拉完之后可以用docker compose ps查看状态，三个服务都显示Up就说明容器层面正常。

这时打开http://服务器IP:3000，如果端口没被防火墙拦，会进入Docmost的初始化页面，第一步是创建管理员账号。这里要提醒一个我踩过的坑：在初始化页面里设置的邮箱、密码就是整个实例的超级管理员，别拿公司公共邮箱来注册，这个账号权限极大，能管理所有工作空间和所有用户，一定要用专门的管理员身份并开启二次验证。初始化完成之后进入主界面，可以顺手创建第一个工作空间（Space）。Docmost里的工作空间是"租户隔离"的单位，不同部门或不同项目组建议分开建，权限管理会清爽很多。

3.4 项目目录的整理建议

也许有人觉得目录结构是小事，但我在团队里推了一段时间后深有体会：Docmost的页面树虽然灵活，但如果不提前约定规则，半年后必然是一锅粥。我个人的建议是：工作空间按团队或大项目划分，每个工作空间内部按"部门/项目→分类→具体文档"三层组织。比如"研发部"空间下建"技术方案""会议纪要""新人文档"几个顶级分类页面，再往下放具体内容。页面树支持拖拽调整顺序和层级，这个能力帮助很大，整理工作可以随时进行。

4. Nginx反向代理与HTTPS：从裸端口到正式域名

4.1 为什么裸IP加端口不能直接用

有人觉得，反正都部署好了，直接给同事发http://IP:3000不就行了？短期应急可以，长期这么干有四个问题。第一，端口号在URL里出现，分享链接不美观也容易输错；第二，明文HTTP传输，文档内容在局域网还可能无所谓，但在公网上就是裸奔，Cookie随时可能被截获；第三，3000端口暴露在公网上，等于让扫描器直接探测你的应用，平白增加被攻击的风险；第四，谷歌等浏览器的密码管理器对非HTTPS站点限制很多，同事保存密码都不方便。所以正式使用，Nginx反向代理加HTTPS这一步省不了。

4.2 Nginx配置要点与WebSocket转发

安装Nginx很简单，Ubuntu上sudo apt install nginx即可。然后在/etc/nginx/conf.d/下新建一个docmost.conf，内容如下：

upstream docmost_backend { server 127.0.0.1:3000; keepalive 32; } server { listen 80; server_name doc.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name doc.example.com; ssl_certificate /etc/letsencrypt/live/doc.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/doc.example.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; client_max_body_size 50m; location / { proxy_pass http://docmost_backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

这配置里有两处绝对不能省。一处是proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection "upgrade";这两行，没有它们，WebSocket握手会被Nginx当成普通HTTP请求处理，导致协同编辑的实时同步完全失效。另一处是proxy_set_header X-Forwarded-Proto $scheme;，Docmost依赖这个头来判断用户当前用的协议，从而正确生成HTTPS链接和回调地址，漏掉的话即使证书配好了，应用内部某些链接还是会跳成HTTP。

验证配置没问题后执行sudo nginx -t，然后sudo systemctl reload nginx。注意，HTTP/2和WebSocket的兼容性在Nginx 1.25.1以上版本才完善，如果你的系统自带Nginx版本较老，建议直接加官方源安装新版。

4.3 申请证书与自动续期

证书我用的是Let's Encrypt免费证书，配合certbot自动续期。安装certbot后执行一次：

sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d doc.example.com

certbot会自动检测Nginx配置并完成证书签发，还会顺手改好SSL配置。之后它会在系统中注册一个定时任务，每两个月续期一次。我建议手动验证一下续期链路是否真的能跑通：sudo certbot renew --dry-run，看到Congratulations就说明自动续期没问题。这个验证值得做，因为很多人装完证书就再也不管了，某天突然发现证书过期、网站全红，比任何故障都尴尬。

4.4 备选：不用Nginx的场景怎么处理

如果团队本来就用了Caddy或Docker里跑了Traefik，同样思路配置反向代理即可。我自己在备用的内网环境里试过Caddy，它的优势是自动申请和续期证书，配置文件极短：

doc.example.com { reverse_proxy 127.0.0.1:3000 }

Caddy默认就支持WebSocket转发，基本零配置。但如果你像我一样更多使用Nginx的生态环境、需要精细控制转发规则或做多层代理，Nginx仍然是更稳妥的选择。

5. 数据安全三板斧：备份、恢复、升级全记录

5.1 要备份的其实只有两部分

很多自托管新手以为"备份整个文件夹"就行，但Docker部署下数据分布在两个地方：PostgreSQL里的结构化数据（文档内容、用户、权限、评论等），以及Docmost容器里/app/data/storage目录下的附件文件（上传的图片、文件等）。Redis里的数据只是会话和临时缓存，丢了最坏的结果是所有用户重新登录一次，不需要刻意备份。

所以我的备份策略是：数据库用pg_dump导出SQL文件，附件用tar打包volume目录，两个备份都放到独立的备份磁盘或对象存储上。下面是我每天凌晨3点跑的备份脚本核心部分：

#!/bin/bash BACKUP_DIR=/backup/docmost mkdir -p "$BACKUP_DIR/$(date +%F)" # 备份PostgreSQL docker compose exec -T db pg_dump -U docmost docmost | gzip > "$BACKUP_DIR/$(date +%F)/docmost-db.sql.gz" # 备份附件存储 docker run --rm \ -v docmost_docmost-storage:/data \ -v "$BACKUP_DIR/$(date +%F)":/backup \ alpine tar czf /backup/docmost-storage.tar.gz -C /data .

写这脚本时注意两点。docker compose exec后面必须带-T参数，否则在cron这种没有TTY的环境下会报the input device is not a TTY错误。附件备份用docker run --rm临时起一个alpine容器来打包volume，是操作Docker volume最干净的方法，比直接去/var/lib/docker/volumes里翻文件安全得多。备份完成后建议额外检查一下SQL文件大小，如果某天发现异常小，大概率是pg_dump失败了，脚本里加个文件大小判断会更好。

5.2 恢复演练

备份的价值在恢复，我没少见过"备份了三年从来没恢复过，真出事发现备份是坏的"的案例。恢复流程分两步，先恢复SQL，再恢复附件。

# 恢复SQL：先删掉容器里旧库再导入，避免冲突 docker compose exec -T db dropdb -U docmost --if-exists docmost docker compose exec -T db createdb -U docmost -O docmost docmost gunzip -c 你的备份文件.sql.gz | docker compose exec -T db psql -U docmost docmost # 恢复附件：把tar包解回volume docker run --rm \ -v docmost_docmost-storage:/data \ -v "$BACKUP_DIR":/backup \ alpine sh -c "rm -rf /data/* && tar xzf /backup/docmost-storage.tar.gz -C /data"

我强烈建议你在测试环境或者新服务器上完整演练一次恢复流程，而不是只在生产环境脑子里过一遍。我第一次做恢复演练时，就发现备份tar包因为没有包含隐藏文件而少了一部分数据。这种问题只有真实跑一遍恢复流程才能发现。

5.3 升级的正确操作顺序

Docmost迭代速度不慢，几乎每个月都有新版本。升级前务必先看官方更新的docker-compose.yml示例，确认新版本有没有调整环境变量或引入新的依赖服务。我习惯的升级顺序是：

1. 停服前先做一次完整备份（数据库加附件）。
2. 拉取新镜像并重建容器：docker compose pull && docker compose up -d。
3. 观察日志：docker compose logs -f docmost，看迁移是否正常完成。
4. 访问网站，重点验证登录、协同编辑、附件上传三条主链路。
5. 如果迁移失败或页面异常，用备份回滚：docker compose down，修改Compose文件把镜像tag改回旧版本，然后按5.2的恢复流程还原数据。

需要特别提醒的是，升级过程中Docmost会自动执行数据库迁移脚本，这个过程千万别中途Ctrl+C或者重启容器。迁移是一次性操作，强行中断很可能让数据库处于中间状态，后续再启动会非常难处理。耐心等日志里出现类似migration complete的标记再继续。

5.4 日常健康检查的几个观察点

自托管服务的日常运维不用太复杂，我固定每周看一眼这几个指标：容器状态（docker compose ps全部是Up）、磁盘剩余空间（附件会越来越大）、Postgres的慢查询和连接数（连接数打满通常是应用出问题的前兆）。另外建议在Docmost绑定的域名下配一个定时探活，比如crontab里每5分钟curl -sI https://doc.example.com检查HTTP响应码，不是200就发告警。这套极简监控足以覆盖小团队自托管的90%风险点。

6. 实测踩过的五个坑：现象、排查路径与最终解法

6.1 登录认证后一直在跳转——APP_URL不一致

现象：部署完所有步骤都正确，但同事反馈输入账号密码后页面一直在登录页和首页之间跳来跳去，或者登录成功了刷新又变回未登录状态。

排查路径：我一开始以为是Cookie配置问题，检查了Nginx的代理头，都没有异常。后来打开浏览器开发者工具，发现登录接口返回的302跳转地址指向的是http://localhost:3000，而不是https://doc.example.com，这才意识到是应用内部生成的链接基于APP_URL。

解法：把Compose文件里的APP_URL改成https://doc.example.com，重建容器，问题立刻解决。这个坑提醒我，部署前就要把最终访问地址定好，中途再改虽然不麻烦，但排查的过程很浪费时间。

6.2 文档同步断线、光标不同步——WebSocket被中间层吞了

现象：网页能正常打开，文档也能正常编辑，但两个人的光标永远互相看不见，一个人改动后另一个人要刷新页面才能看到新内容。

排查路径：这个症状非常典型，就是实时同步通道断了。我在浏览器控制台看到WebSocket连接状态一直在pending然后失败。查了Nginx访问日志，发现请求确实到达了后端，但响应明显不对。

解法：检查Nginx配置，发现我最初写配置时漏了Upgrade和Connection "upgrade"两个头。Docmost的前端通过WebSocket保持协作状态，没有这两个头，Nginx就把升级请求当普通HTTP处理，实时同步自然全废。补上后重建连接，光标恢复实时可见。

6.3 文档时间显示总是差8小时——容器时区问题

现象：文档的创建时间、更新时间全部比本地时间晚8个小时。

排查路径：Docker容器默认使用UTC时区，而国内服务器和用户所在时区是UTC+8。Postgres存储的timestamp类型不带时区信息，应用读取后按容器内时区渲染，就造成了8小时偏移。

解法：在Postgres和Docmost两个容器的环境变量里都加上TZ: Asia/Shanghai，重建后时间显示恢复正常。有人可能会说"时间是客观的，偏移一下无所谓"，但文档平台上"今天改的"和"一个星期前改的"显示错误，会直接影响协作效率，值得顺手修掉。

6.4 附件上传到一半报413——反向代理body大小限制

现象：上传小图片没问题，一旦传几MB的PDF或者大截图，页面直接提示"请求实体过大"。

排查路径：看到413状态码，第一反应就是Nginx的client_max_body_size默认值太小。Nginx默认只允许1MB的请求体，Docmost的附件上传请求超过这个阈值就直接拒绝了。

解法：在Nginx的server块里加client_max_body_size 50m;，按团队实际需求调整。改完reload配置再测试，几十MB的文件也能正常上传。这个坑很常见，几乎每个自托管应用都会遇到，建议部署时直接把这项写上，别等用户来反馈。

6.5 升级后控制台停在"running migrations"不动——数据库连接与锁

现象：执行docker compose up -d拉新镜像后，应用容器日志一直停在数据库迁移阶段，怎么等都不继续，页面也打不开。

排查路径：我先看Postgres日志，发现迁移期间数据库连接数被占满。进一步排查，发现是因为之前测试时遗留了几个旧连接session没有释放，加上迁移脚本本身需要较长的表锁，多个连接互相等待导致死锁般的状态。

解法：重启Postgres容器清掉遗留连接：docker compose restart db，然后等它起来后再重启应用容器。这次迁移顺利完成。从此我升级前都会先重启一下数据库容器确保连接干净，并且用docker compose stop docmost先把应用停掉，避免旧版本的进程还占用数据库连接时就开始迁移。

最后说点实在的

跑了大半个季度，Docmost在我这里已经从"试试看"变成了团队真正的文档中枢。每天有二三十篇文档产生，页面树越叠越厚，搜索功能帮我们省了大量翻聊天记录的时间。如果让我重新选一次，我大概率还是会选它，因为它把"私有化文档"这件事做得足够朴素可靠。

最后再分享两个小技巧收尾。第一，Docmost支持在设置里导出整站数据，我建议每个月手动导出一次存到本地，作为备份系统之外的另一道保险。第二，如果团队里有人习惯用Markdown写文档，在Docmost里可以直接粘贴Markdown段落，它多数情况下能识别的较好，不用手动修改格式。这两个功能不算起眼，但实际用起来都属于"真香"级别。希望这篇能帮你少走几个弯路。