知识与效率

Docmost:群晖部署与团队文档使用

  • 0 次阅读
  • 0 条评论
文章摘要

Docmost 是一款可自行托管的团队 Wiki 和文档协作工具。可以把部署记录、项目说明、操作手册和团队制度集中到一个工作区,再用空间和页面层级组织内容,让成员围绕同一份文档编辑和讨论。与把文件分别发给不同的人相比,协作内容、评论和历史记录集中在站点内,便于维护。 它的特点是实时协作:多人打开同一页面时可以共同编辑,配合评论和页面历史处理修改意见。页面中还可以放置代码、附件、图表和外部嵌入内容。对于 NAS 用户,可以把它作为家庭或小团队的内部知识库;如果需要向外分享,再单独设置分享范围。 部署由 Docmost 应用、PostgreSQL 数据库与 Redis 三个服务组成。应用负责页面与附件,PostgreSQL 保存业务数据,Redis 为应用提供所需的缓存或协作基础服务。备份时需要一起考虑数据库、附件和配置。

项目介绍

Docmost 是一款可自行托管的团队 Wiki 和文档协作工具。可以把部署记录、项目说明、操作手册和团队制度集中到一个工作区,再用空间和页面层级组织内容,让成员围绕同一份文档编辑和讨论。与把文件分别发给不同的人相比,协作内容、评论和历史记录集中在站点内,便于维护。

它的特点是实时协作:多人打开同一页面时可以共同编辑,配合评论和页面历史处理修改意见。页面中还可以放置代码、附件、图表和外部嵌入内容。对于 NAS 用户,可以把它作为家庭或小团队的内部知识库;如果需要向外分享,再单独设置分享范围。

部署由 Docmost 应用、PostgreSQL 数据库与 Redis 三个服务组成。应用负责页面与附件,PostgreSQL 保存业务数据,Redis 为应用提供所需的缓存或协作基础服务。备份时需要一起考虑数据库、附件和配置。

核心功能

功能 使用场景
实时协作 多个成员一起编写操作手册或项目记录,减少反复传递文档副本。
空间与页面层级 按部门、项目或家庭用途建立空间,再以页面和子页面组织资料。
成员、分组与权限 按成员职责安排空间访问范围,区分谁可以查看、谁可以编辑。
评论与页面历史 围绕内容提出修改意见,并查看页面修改记录。
图表与代码内容 使用 Draw.io、Excalidraw、Mermaid 等方式表达流程与结构,配合代码内容编写技术资料。
附件与嵌入 在文档中放置文件和外部内容,把说明与相关资料放在一起。
搜索与多语言 查找已有页面,并按个人偏好切换界面语言。

社区开源核心与企业功能分别提供许可。官方演示界面中出现的 AI 等入口,不等于自建社区版包含对应商业服务。

界面展示

Docmost 官方工作区首页

图 1:官方工作区首页,展示空间入口和最近文档;具体可用模块随版本与许可而异。

Docmost 文档编辑与评论

图 2:官方文档编辑界面,左侧组织页面,中间编辑内容,右侧展开评论讨论。

项目信息

项目 说明
类型 Docker
分类 知识与效率
项目仓库 docmost/docmost
官方入口或文档 直接访问
整理日期 2026-11-14

安装或使用条件

群晖准备支持项目功能的 Container Manager,确认 NAS 架构可使用所选镜像,且 3006 端口空闲。创建 /volume1/docker/docmost/ 作为项目目录,在其中保存 compose.yaml 与 .env。本文配置用 Docker 命名卷保存附件、数据库和 Redis 数据,数据不直接位于这个项目目录内;导出项目文件不能替代数据卷备份。

安装与使用步骤

  1. 准备项目目录,将下方 .env 和 Compose 分别保存,文件名保持准确。修改访问地址并为密钥与数据库密码分别生成随机值。
  2. 在 Container Manager 的“项目”中新建项目并选择该目录,或在终端进入项目目录执行文中的检查与启动命令。首次启动需要等待数据库和应用完成初始化。
  3. 浏览器打开 http://NAS_IP:3006,按初始化页面填写工作区与首个管理员信息。首次配置期间先限制在可信局域网中访问。
  4. 进入个人偏好设置,将界面语言切换为简体中文。创建一个测试空间,再新建页面,先写一份简单的 NAS 操作记录。
  5. 配置邀请所需邮件服务,邀请另一个测试成员。用两个账号验证共同编辑、评论与空间访问权限,再整理正式资料。

准备 .env

在 Compose 同目录设置以下变量:

环境文件由下方“群晖目录准备”命令自动生成。

下方准备命令会生成访问地址和两组独立随机值;无需手动拼接。反向代理后将 DOCMOST_URL 改为真实 HTTPS 域名。

首次使用:空间、页面与协作

  1. 切换语言:打开个人偏好设置(My preferences),选择简体中文。
  2. 创建空间:为一个具体用途新建空间,例如“NAS 运维”,再创建“服务清单”和“备份流程”等页面,按需要增加子页面。
  3. 编写内容:在页面中输入说明,插入代码块或附件。上传一张测试图片后,在刷新页面后重新打开,检查附件能否正常显示。
  4. 邀请成员:向测试成员发出邀请,设置合适的空间访问范围。用该账号验证能否查看和编辑,并尝试访问不应开放的空间。
  5. 验证协作:两个账号同时打开一个页面,分别输入一段文字,观察更新是否同步,再对内容添加评论并检查对方是否可见。
  6. 检查分享:分享前区分成员协作与对外链接。需要公开访问时,再用未登录的浏览器窗口核对实际可见内容,避免误把内部文档分享出去。

Docker Compose

按本次查到的官方完整 Compose 整理,保留 PostgreSQL 18、Redis 8 及其目录。适用于新建实例;已有旧数据库不能仅把镜像直接改为 PostgreSQL 18。示例使用 Docker 命名卷,备份时需按卷备份而非只复制项目 YAML。

群晖目录准备

在群晖 SSH 终端执行下面这一段,再将下方配置保存为 /volume1/docker/docmost/compose.yaml。也可在 Container Manager 中新建项目,选择该目录并粘贴配置。

sudo sh <<'HALO_PREPARE'
set -eu
mkdir -p /volume1/docker/docmost
cd /volume1/docker/docmost
umask 077
touch .env
NAS_ADDR=$(ip -4 route get 1.1.1.1 | sed -n "s/.* src \([^ ]*\).*/\1/p" | head -n 1)
test -n "$NAS_ADDR" || { echo "未能识别 NAS 地址,请检查默认路由"; exit 1; }
if ! grep -q "^DOCMOST_DB_PASSWORD=." .env; then
  generated_secret=$(openssl rand -hex 32)
  printf 'DOCMOST_DB_PASSWORD=%s\n' "$generated_secret" >> .env
fi
if ! grep -q "^DOCMOST_SECRET=." .env; then
  generated_secret=$(openssl rand -hex 32)
  printf 'DOCMOST_SECRET=%s\n' "$generated_secret" >> .env
fi
if ! grep -q "^DOCMOST_URL=." .env; then
  printf 'DOCMOST_URL=http://%s:3006\n' "$NAS_ADDR" >> .env
fi
chmod 600 .env
HALO_PREPARE
cd /volume1/docker/docmost

所需密码和密钥已自动生成到项目目录的 .env,已有非空值会保留。查看初始化密码可在自己的终端执行 sudo cat /volume1/docker/docmost/.env;该文件只保留在本机。

首次准备会根据 NAS 默认路由生成局域网访问地址。使用其他网卡或 HTTPS 域名时,修改项目 .env 中对应 URL 后重建服务。

配置中的命名卷由 Docker 创建并管理,不需要手动填写 UID/GID。备份时同时保存这些数据卷,不能只备份项目目录。

services:
  docmost:
    image: docmost/docmost:latest
    restart: unless-stopped
    depends_on:
      - db
      - redis
    environment:
      APP_URL: "${DOCMOST_URL}"
      APP_SECRET: "${DOCMOST_SECRET}"
      DATABASE_URL: "postgresql://docmost:${DOCMOST_DB_PASSWORD}@db:5432/docmost"
      REDIS_URL: redis://redis:6379
    ports:
      - "3006:3000"
    volumes:
      - docmost_data:/app/data/storage
  db:
    image: postgres:18
    restart: unless-stopped
    environment:
      POSTGRES_DB: docmost
      POSTGRES_USER: docmost
      POSTGRES_PASSWORD: "${DOCMOST_DB_PASSWORD}"
    volumes:
      - db_data:/var/lib/postgresql
  redis:
    image: redis:8
    restart: unless-stopped
    command: [redis-server, --appendonly, "yes", --maxmemory-policy, noeviction]
    volumes:
      - redis_data:/data
volumes:
  docmost_data:
  db_data:
  redis_data:

在项目目录保存为 compose.yaml 后,先检查配置,再启动:

docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100

配置与常见问题

  • 访问地址不对或跳转异常:确认 .env 中的 DOCMOST_URL 与实际访问入口一致。换成 HTTPS 域名后同时更新 APP_URL 对应值与反向代理配置。
  • 启动时数据库认证失败:核对应用 DATABASE_URL 与 PostgreSQL 使用相同的用户名、数据库名和密码。已有数据库卷不会因为修改环境变量就自动修改数据库内的账号密码。
  • 多人编辑不能同步:先确认访问同一页面、两个账号均有权限,再检查反向代理的长连接或 WebSocket 支持及应用日志。
  • 邀请邮件未收到:检查 SMTP 配置、发信地址、垃圾邮件和发送日志;成员邀请功能与邮件实际投递是两个检查点。
  • APP_SECRET 创建实例后保持稳定,升级时保留原值,不因为重新复制配置而每次生成一个新密钥。
  • 页面无法打开:先用 docker compose ps 检查状态,再核对宿主机端口、NAS 防火墙与应用日志。不要把容器端口随意改成另一个数字。
  • 文件无法保存:核对宿主目录是否存在、挂载方向及运行用户的读写权限。不要直接给整个存储卷开放所有权限。

更新与备份

数据库与附件需要成套备份,同时保存 .env、Compose 和应用密钥。这里的命名卷由 Docker 管理,不能把 /volume1/docker/docmost/ 目录中只有两份配置文件误认为已备份全部内容。

数据库可通过 docker compose exec -T db pg_dump -U docmost -d docmost -Fc > docmost.dump 导出到当前项目目录;导出后确认文件不是空文件,并保留错误日志。附件卷使用所用平台的卷备份方式保存。需要一致性备份时,先让用户暂停编辑并停止应用写入,再完成数据库与附件备份。

恢复演练应使用独立实例,检查页面、附件和成员数据是否一起恢复。已有 PostgreSQL 旧版本数据升级到 18 需要按数据库升级流程处理,不能仅修改镜像标签启动。

更新前保留原配置和数据备份,阅读所用版本的升级说明;确认兼容后再执行 docker compose pull 和 docker compose up -d。只回退镜像不一定能回退已经迁移过的数据库。

参考资料

配图:Docmost 官方 README 引用的界面图片;开源核心采用 AGPL-3.0,企业功能采用独立许可。