## 一、整体架构设计

Docmost 自托管时的典型组件：  

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

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

***

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

1. **服务器与系统**  
   - 建议：Linux（如 Ubuntu / Debian / CentOS Stream），公网或内网 IP 均可。  
   - 资源建议：至少 2 vCPU + 2GB RAM 起（社区实践与通用建议），更高并发可上 4GB+。 [cloudcuddler](https://cloudcuddler.com/what-is-docmost-how-to-configure-it/)

2. **安装 Docker & Docker Compose 插件**  
   - 按 Docmost 官方安装指南在 Linux 上安装 Docker 与 `docker compose` 插件。 [docmost](https://docmost.com/docs/installation/)

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

***

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

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

```yaml
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](https://github.com/docmost/docs/issues/17)
- `STORAGE_DRIVER=local` 时，所有上传附件都写入 `/app/data/storage`，挂载为宿主机的 `./data/storage`。 [senate](https://senate.sh/apps/docmost)
- 页面正文和元数据存 PostgreSQL；`docmost_data` 卷中的是上传文件。 [github](https://github.com/docmost/docmost/discussions/1697)

启动：  

```bash
docker compose up -d
```

然后访问 `http(s)://服务器IP:3000` 进行初始化配置。 [docmost](https://docmost.com/docs/installation/)

***

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

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

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

Docmost 官方与社区教程都建议通过反向代理统一处理 HTTPS，这样 Docmost 容器只关心 HTTP。 [docmost](https://docmost.com/docs/installation/)

***

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

### 1. Docmost 如何存储附件

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

Docmost 官方文档说明支持 **local / S3 兼容 / Azure Blob** 三种驱动，S3 兼容意味着可以用 MinIO 等实现自建对象存储。 [docmost](https://docmost.com/docs/self-hosting/configuration)

### 2. 上传大小与限制

- 默认单文件上传上限：`FILE_UPLOAD_SIZE_LIMIT=50mb`。 [railway](https://railway.com/deploy/docmost-open-source-wiki)
- 默认导入大小上限：`FILE_IMPORT_SIZE_LIMIT=100mb`。 [docmost](https://docmost.com/docs/self-hosting/environment-variables)
- 可以根据实际需要在 `docker-compose.yml` 中调大或调小，但要同步考虑带宽和磁盘容量。 [railway](https://railway.com/deploy/docmost-open-source-wiki)

### 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](https://github.com/docmost/docmost/discussions/1697)
- 建议本地磁盘为附件目录再多预留 20–30% headroom 做碎片与增长缓冲。  

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

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

***

## 六、备份与恢复建议

1. **数据库备份（关键）**  
   - 使用 `pg_dump` 定期备份 Docmost 数据库：  
   - 在宿主机执行类似：  
     ```bash
     docker exec -t <db_container_name> \
       pg_dump -U docmost -d docmost > backup/docmost_$(date +%F).sql
     ```  
   - 这是社区推荐做法，可配合 cron 实现每天备份。 [github](https://github.com/docmost/docmost/discussions/1697)

2. **附件存储备份**  
   - `STORAGE_DRIVER=local` 时，只需备份挂载目录 `./data/storage`（或实际挂载的路径）；  
   - `STORAGE_DRIVER=s3` 时，依赖对象存储自身的冗余与版本管理策略即可。 [github](https://github.com/docmost/docmost/discussions/1697)

3. **恢复流程简单理解**  
   - 新环境：先用 Docker 启动空 Docmost + Postgres；  
   - 恢复 DB：`psql` 导入 `pg_dump` 备份；  
   - 恢复附件：把 `./data/storage` 或对象存储 bucket 中的数据恢复即可，Docmost 会按数据库中的记录关联附件。 [docmost](https://docmost.com/docs/self-hosting/configuration)