Etherpad 部署教程：多人在线编辑同一份文档

开会时几个人轮流补文字，事后再合并文件，容易漏掉修改。Etherpad 可以让多人在同一份文本上实时编辑，适合会议记录、临时方案和共同整理的工作说明。它保留文档修订，但团队的账号、访问方式和长期备份仍要另外安排。

这篇教程使用 PostgreSQL 持久保存文档，启用内置认证。第一阶段只做一个小团队的私人入口，不把可猜到地址的文档当作天然私密的文件。

把文档放进 PostgreSQL

准备 Linux VPS、Docker Engine、Compose、可用域名，以及安装在宿主机的 Caddy。初始化时先通过 SSH 隧道访问。

多人共同编辑时，客户端到 VPS 的连接会影响实时协作，数据库则保存文档与修订。准备新的协作实例，可以查看雨云云服务器，优惠码 KuZhuJi。按成员所在位置选择区域，为应用和 PostgreSQL 留出资源；现有 VPS 也能先做小团队试用，确认代理和断线重连正常后再迁入长期文档。

mkdir -p ~/apps/etherpad
cd ~/apps/etherpad
umask 077
docker pull etherpad/etherpad:latest
printf 'ETHERPAD_IMAGE=%s\n' "$(docker image inspect --format '{{index .RepoDigests 0}}' etherpad/etherpad:latest)" > .env
printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 32)" >> .env
printf 'ADMIN_PASSWORD=%s\n' "$(openssl rand -hex 32)" >> .env
printf 'USER_PASSWORD=%s\n' "$(openssl rand -hex 32)" >> .env

确认镜像摘要和三个不同密码已写入 .env，这个文件只留给部署账号读取。保存为 compose.yml：

services:
  db:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: etherpad
      POSTGRES_USER: etherpad
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?请生成数据库密码}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U etherpad -d etherpad"]
      interval: 10s
      timeout: 5s
      retries: 10
  pad:
    image: ${ETHERPAD_IMAGE:?请固定镜像摘要}
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:3017:9001"
    environment:
      NODE_ENV: production
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_NAME: etherpad
      DB_USER: etherpad
      DB_PASS: ${POSTGRES_PASSWORD}
      ADMIN_PASSWORD: ${ADMIN_PASSWORD:?请设置管理员密码}
      USER_PASSWORD: ${USER_PASSWORD:?请设置协作账号密码}
      REQUIRE_AUTHENTICATION: "true"
      TRUST_PROXY: "true"
      DEFAULT_PAD_TEXT: "在此记录会议主题、日期和行动项。"
    volumes:
      - plugins:/opt/etherpad-lite/src/plugin_packages
      - etherpad-var:/opt/etherpad-lite/var
volumes:
  plugins:
  etherpad-var:

数据库没有发布公网端口。TRUST_PROXY 配合本机上游的可信反向代理使用，不应把可直接公网访问的应用端口一起开放。

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

电脑上建立隧道后访问 http://localhost:3017：

ssh -N -L 3017:127.0.0.1:3017 user@VPS_IP

普通协作使用内置 user 账号及 USER_PASSWORD。admin 账号与其密码用于管理，别把它交给所有参与者。

两个浏览器检查实时编辑与重连

新建一份不含敏感资料的测试文档，在两个独立浏览器会话中用普通账号打开相同地址。分别输入不同的句子，观察两边是否收到更新，再查看修订记录。

让其中一个浏览器短暂断网，恢复网络后检查文档是否重新连接、另一边的修改是否出现。浏览器中填写的显示名和颜色方便辨认编辑位置，不等于经过验证的个人身份；共用一个登录账号时，不能把它当作每位成员独立的权限或审计体系。

需要给不同成员设置独立访问范围时，应按团队要求选择认证和授权方案，并对照对应插件文档测试。先把一个普通私人入口维护好，比一开始安装很多插件更容易发现协作中的真实需求。

反向代理要让实时连接一直通

宿主机 Caddy 的例子：

pad.example.com {
    reverse_proxy 127.0.0.1:3017
}

替换域名，确认 DNS、80 和 443 端口满足证书条件，验证配置后再重载。Caddy 的 reverse_proxy 可以处理 WebSocket 升级；若经过其他代理层，还要检查这些层是否支持长连接，是否存在过短的超时。

上线后重新做双浏览器编辑测试。页面能加载但修改不同步，先看应用日志、浏览器连接状态与代理配置。再用未登录窗口直接打开文档地址，确认它要求认证。长而随机的 pad 地址不能代替登录要求。

配置在 Compose 中，备份留下数据库与扩展状态

尽量通过 Compose 环境变量管理本例的配置。管理页面中对容器内部 settings.json 的修改可能随重建消失；如果以后需要持久编辑该文件，按官方方式挂载已有的设置文件，并验证其可写权限。

核心文档和修订保存在数据库，可在停止写入后导出：

mkdir -p backups
umask 077
docker compose stop pad
docker compose exec -T db pg_dump -U etherpad -d etherpad -Fc > "backups/etherpad-$(date +%Y%m%d-%H%M%S).dump"
docker compose start pad

另行保存 Compose、.env、镜像摘要；装过插件时，还要保留插件清单及插件使用的卷、配置和数据。数据库归档恢复到隔离实例后，用旧镜像检查文档正文、修订、登录和双浏览器同步，再安排正式升级。

插件与应用应按兼容关系升级，PostgreSQL 主版本迁移则单独处理。仅下载一份最终文本导出可以保留内容，但无法完整替代修订和服务器状态的备份。

部署参数见 Etherpad 官方 Docker 文档，认证与代理选项可对照 Docker 设置模板。