ProjectAGiPrompt/33-富文本中心/1-docmost-部署方案.md

一、整体架构设计

Docmost 自托管时的典型组件：

• Docmost 应用容器（Node.js 服务，监听 3000 端口）。 ayushchugh
• PostgreSQL 数据库（存页面正文、用户、权限等元数据）。 github
• Redis（会话、缓存）。 senate
• 文件存储：
  • 默认 STORAGE_DRIVER=local，附件写入容器中的 /app/data/storage 目录，对应挂载卷或主机目录。 docmost
  • 可切换为 S3 兼容对象存储或 Azure Blob（配置 STORAGE_DRIVER=s3/azure 及相关环境变量）。 docmost
• Nginx / Caddy 等反向代理：负责域名、TLS、HTTP→HTTPS 跳转。可选，用于对外暴露统一端口和证书管理。 ayushchugh

Docmost 官方明确推荐使用 Docker 部署，自托管场景（包括 On‑Prem / Air‑gapped）都支持。 docmost

---

二、中国大陆环境的前置准备

1. 服务器与系统

   • 建议：Linux（如 Ubuntu / Debian / CentOS Stream），公网或内网 IP 均可。
   • 资源建议：至少 2 vCPU + 2GB RAM 起（社区实践与通用建议），更高并发可上 4GB+。 cloudcuddler

2. 安装 Docker & Docker Compose 插件

   • 按 Docmost 官方安装指南在 Linux 上安装 Docker 与 docker compose 插件。 docmost

3. 镜像拉取加速（大陆环境）

   • 如直接拉取 docmost/docmost、postgres:16-alpine、redis:7.2-alpine 等镜像较慢，可配置 Docker Hub 加速器（阿里云、腾讯云、DaoCloud 等）或自建 registry 缓存。
   • 这一部分和 Docmost 无关，是通用 Docker 最佳实践，你应该很熟，就不展开了。

---

三、Docker Compose 参考方案（本地存储）

下面是一个精简、适合大陆自建的 docker-compose.yml 思路（结构参考官方与社区示例，变量名称与路径沿用官方）： senate

version: "3.9"

services:
  docmost:
    image: docmost/docmost:latest
    depends_on:
      - db
      - redis
    environment:
      APP_URL: "https://docmost.example.com"        # 对外访问域名或内网 URL
      APP_SECRET: "自己生成 >=32 位随机字符串"
      DATABASE_URL: "postgresql://docmost:强密码@db:5432/docmost?schema=public"
      REDIS_URL: "redis://redis:6379"
      STORAGE_DRIVER: "local"                       # 默认 local，本地磁盘存附件 [web:51]
      FILE_UPLOAD_SIZE_LIMIT: "50mb"               # 单文件上传上限，默认 50MB [web:58][web:55]
      FILE_IMPORT_SIZE_LIMIT: "100mb"              # 导入上限，默认 100MB [web:58]
      # 邮件可选：邀请/重置密码需要
      MAIL_DRIVER: "smtp"
      SMTP_HOST: "smtp.example.com"
      SMTP_PORT: "587"
      SMTP_USERNAME: "noreply@example.com"
      SMTP_PASSWORD: "邮件密码或 App Password"
      MAIL_FROM_ADDRESS: "noreply@example.com"
      MAIL_FROM_NAME: "Docmost"
    volumes:
      - ./data/storage:/app/data/storage           # 附件/上传文件目录 [web:46][web:51][web:52]
    ports:
      - "3000:3000"
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: docmost
      POSTGRES_USER: docmost
      POSTGRES_PASSWORD: "强密码"
    volumes:
      - ./data/db:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7.2-alpine
    volumes:
      - ./data/redis:/data
    restart: unless-stopped

要点说明：

• APP_SECRET 必须至少 32 字符，否则启动会报错（官方文档有说明）。 github
• STORAGE_DRIVER=local 时，所有上传附件都写入 /app/data/storage，挂载为宿主机的 ./data/storage。 senate
• 页面正文和元数据存 PostgreSQL；docmost_data 卷中的是上传文件。 github

启动：

docker compose up -d

然后访问 http(s)://服务器IP:3000 进行初始化配置。 docmost

---

四、反向代理与 HTTPS（生产环境）

建议在宿主机再跑一个 Nginx / Caddy：

• Nginx 监听 80/443，对外暴露 docmost.example.com。
• location / 反向代理到 http://127.0.0.1:3000。
• 用 acme.sh / Certbot 从 Let’s Encrypt 或其他 CA 签证书即可。 ayushchugh

Docmost 官方与社区教程都建议通过反向代理统一处理 HTTPS，这样 Docmost 容器只关心 HTTP。 docmost

---

五、附件存储策略与空间规划

1. Docmost 如何存储附件

• 正文内容：存储在 PostgreSQL 中（页内容在 DB，方便版本、查询）。 github
• 附件 / 上传文件：
  • 如果 STORAGE_DRIVER=local，则在容器内 /app/data/storage，映射到宿主卷（上面的 ./data/storage）。 docmost
  • 如果 STORAGE_DRIVER=s3，则通过环境变量配置 S3 兼容对象存储：AWS_S3_ACCESS_KEY_ID、AWS_S3_SECRET_ACCESS_KEY、AWS_S3_REGION、AWS_S3_BUCKET、AWS_S3_ENDPOINT 等。 docmost

Docmost 官方文档说明支持 local / S3 兼容 / Azure Blob 三种驱动，S3 兼容意味着可以用 MinIO 等实现自建对象存储。 docmost

2. 上传大小与限制

• 默认单文件上传上限：FILE_UPLOAD_SIZE_LIMIT=50mb。 railway
• 默认导入大小上限：FILE_IMPORT_SIZE_LIMIT=100mb。 docmost
• 可以根据实际需要在 docker-compose.yml 中调大或调小，但要同步考虑带宽和磁盘容量。 railway

3. 磁盘空间估算方法（附件）

Docmost 不会“自动清理”附件，附件存储空间基本就是：

总附件占用 ≈ 用户数 × 每人每日平均上传量 × 保留天数

根据你实际业务场景估：

• 小团队（10 人）：
  • 假设每人每天平均 10MB 附件（几张截图/小文档），保留 3 年：
  • 10 × 10MB × 365 × 3 ≈ 1.1TB → 建议至少预留 1.5TB。
• 中团队（50 人）：
  • 假设每人每天平均 20MB，保留 3 年：50 × 20MB × 365 × 3 ≈ 10.9TB，建议本地用 NAS/对象存储。
• 大团队：更建议直接上对象存储（MinIO / S3 兼容），Docmost 本机只放少量缓存。

同时：

• PostgreSQL 部分（正文 + 元数据）体积通常远小于附件，除非你大量粘贴图片到正文（但附件仍走 storage）。 github
• 建议本地磁盘为附件目录再多预留 20–30% headroom 做碎片与增长缓冲。

4. 是否选择对象存储（中国大陆场景）

• 若服务器本地磁盘空间充足（例如 IDC/NAS 上有数 TB），用 local 最简单，备份时一起打包。
• 若有独立对象存储系统（自建 MinIO 或厂商提供的 S3 兼容服务），可切换 STORAGE_DRIVER=s3，由对象存储承载附件，Docmost 主机只负责计算与元数据。 docmost

---

六、备份与恢复建议

1. 数据库备份（关键）

   • 使用 pg_dump 定期备份 Docmost 数据库：
   • 在宿主机执行类似：

     docker exec -t <db_container_name> \
       pg_dump -U docmost -d docmost > backup/docmost_$(date +%F).sql
     

   • 这是社区推荐做法，可配合 cron 实现每天备份。 github

2. 附件存储备份

   • STORAGE_DRIVER=local 时，只需备份挂载目录 ./data/storage（或实际挂载的路径）；
   • STORAGE_DRIVER=s3 时，依赖对象存储自身的冗余与版本管理策略即可。 github

3. 恢复流程简单理解

   • 新环境：先用 Docker 启动空 Docmost + Postgres；
   • 恢复 DB：psql 导入 pg_dump 备份；
   • 恢复附件：把 ./data/storage 或对象存储 bucket 中的数据恢复即可，Docmost 会按数据库中的记录关联附件。 docmost