Etherpad 运维实战指南:安装部署、Pad 管理与数据备份恢复全解

原创2026-09-20 21:22:072,000 阅读
文章标签:后端前端WebSocket协同办公富文本

Etherpad 运维实战指南:安装部署、Pad 管理与数据备份恢复全解

本篇技术指南基于 Etherpad 官方 FAQ 整理并深入源码验证,系统讲解 Etherpad 实例从安装、日常管理(列出/删除/管理 Pad)、数据备份恢复到修订历史压缩的完整运维链路。读者将掌握 Docker、APT、源码等多种部署方式,理解 /admin、/p/:padID、/export/:type 等 URL 路由的用途,并学会使用 HTTP API、CLI 工具与底层数据库完成 Pad 的查询、备份、修复和清理,可直接用于生产实例的日常维护。

如何安装 Etherpad?

Etherpad 提供多种受支持的安装方式,可按环境自由选择。安装完成后默认监听 9001 端口,浏览器访问 http://localhost:9001 即可开始使用。Etherpad 要求 Node.js >= 24 与 pnpm >= 12(见根目录 package.json 的 engines 字段),源码安装时务必满足该版本约束。

Docker 方式(最快捷)

官方镜像同时发布到 Docker Hub(etherpad/etherpad)与 GitHub Container Registry(ghcr.io/ether/etherpad),两个仓库使用完全一致的 tag:

docker pull etherpad/etherpad
docker run -p 9001:9001 etherpad/etherpad

Docker 方式的高级用法——构建个性化镜像、在镜像内启用插件、配置办公格式(DOCX/PDF 等)导入导出——参见 Docker 部署章节。值得注意:容器内的 settings.json 实际上是包含 ${VAR:default} 占位符的模板,环境变量替换只发生在加载时(仅内存生效,不会改写磁盘文件),这是通过 docker exec 查看文件时看到占位符的原因。

一键安装脚本(macOS / Linux / WSL)

curl -fsSL https://raw.githubusercontent.com/ether/etherpad/master/bin/installer.sh | sh

Windows(PowerShell):

irm https://raw.githubusercontent.com/ether/etherpad/master/bin/installer.ps1 | iex

该脚本会克隆 Etherpad 源码、安装依赖并构建前端。如需安装完成后立即启动,可设置环境变量 ETHERPAD_RUN=1。

APT 仓库(Debian / Ubuntu)

Etherpad 发布带签名的 APT 仓库(stable 通道)。导入签名密钥、添加仓库并安装:

curl -fsSL https://etherpad.org/key.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/etherpad.gpg

echo "deb [signed-by=/usr/share/keyrings/etherpad.gpg] https://etherpad.org/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/etherpad.list

sudo apt-get update
sudo apt-get install etherpad

该仓库提供 amd64 与 arm64 两种架构的构建产物。由于 Etherpad 依赖 Node.js >= 24,在较旧的发行版上可能需要额外引入 NodeSource 的 APT 仓库来满足依赖。仓库中还附带 systemd 服务单元与安装/卸载钩子脚本(见 packaging/,如 packaging/systemd/etherpad.service),安装后可通过 systemd 管理守护进程。

从源码安装

git clone -b master https://github.com/ether/etherpad
cd etherpad
pnpm i
pnpm run build:etherpad
pnpm run prod

然后打开 http://localhost:9001。其中 pnpm run build:etherpad 会依次构建 admin 管理端与 ui 界面(见根 package.json 的 build:etherpad 脚本),pnpm run prod 以生产模式启动服务。

Etherpad 提供哪些 URL 路径?

Etherpad 的路由分为管理后台、Pad 编辑器与导出接口三类,官方文档给出了如下速查表:

路径 说明
/admin 管理仪表盘(需要管理员登录)。
/admin/plugins 在 Web 界面中安装、更新与移除插件。
/admin/settings 在 Web 界面中编辑 settings.json。
/p/:padID 打开(或创建)指定 padID 的 Pad,例如 /p/foo。
/p/:padID/timeslider 打开 Pad 的历史时间轴视图。追加 #N 可跳转到指定修订,例如 /p/foo/timeslider#5。
/p/:padID/export/:type 以指定格式导出 Pad,例如 /p/foo/export/html。追加 ?revs=N 可导出指定修订。

支持的导出类型

  • 原生格式(无需额外依赖): txt、html、etherpad、docx、pdf。其中 DOCX/PDF 导出由项目内置的纯 JS 进程内转换器实现,开箱即用(详见 Docker 章节 的 office-format 说明)。
  • 经由 LibreOffice: odt、doc、rtf——这些格式要求 settings.json 中的 soffice 设置指向 LibreOffice 可执行文件。Docker 环境下可用 INSTALL_SOFFICE 构建变量安装 LibreOffice,并设置 soffice 为 /usr/bin/soffice。

etherpad 格式是唯一能够完整保留 Pad 全部修订历史并可重新导入的格式,是迁移与归档单个 Pad 的首选。

如何列出所有 Pad?

官方推荐的方案是通过 HTTP API 的 listAllPads 方法,配合 jq 解析:

ETHERPAD_HOST='https://pad.example.com'
ETHERPAD_API_KEY='...'      # Etherpad 根目录下的 APIKEY.txt 文件内容
ETHERPAD_API_VERSION='...'  # 参见 https://pad.example.com/api 返回的 currentVersion

curl -s "${ETHERPAD_HOST}/api/${ETHERPAD_API_VERSION}/listAllPads?apikey=${ETHERPAD_API_KEY}" \
  | jq -r '.data.padIDs[]'

其中 APIKEY.txt 在 Etherpad 首次启动时自动生成于项目根目录,是所有 HTTP API 调用的身份凭证。

如果需要带管理操作的交互式列表,可安装 ep_adminpads2 插件并访问 /admin/pads。

作为最后手段,可以直连数据库查询。具体查询语句取决于所配置的后端;Pad 记录使用 pad:<padID> 与 pad:<padID>:revs:<n> 形式的键。以 SQLite 为例:

sqlite3 ./var/sqlite.db "select key from store where key like 'pad:%'" \
  | grep -Eo '^pad:[^:]+' \
  | sed -e 's/pad://' \
  | sort -u

注意: 应优先使用 API 或管理插件,而非直接操作 SQL——数据表结构属于实现细节,可能随版本变化(从 src/node/db/ 的存储层代码可见 ueberdb2 抽象了多种后端,键结构由上层决定)。

如何删除与管理 Pad?

通过 HTTP API

使用 deletePad 方法:

curl -s "${ETHERPAD_HOST}/api/${ETHERPAD_API_VERSION}/deletePad?apikey=${ETHERPAD_API_KEY}&padID=foo"

API 还提供 copyPad、movePad、getRevisionsCount 等方法,完整清单参见 HTTP API 章节。

通过 Web 界面

安装 ep_adminpads2 插件后,可在 /admin/pads 中搜索、查看与删除 Pad。

通过 CLI 工具

Etherpad 的 bin/ 目录提供了一整套运维 CLI(TypeScript 脚本,统一通过 pnpm filter 调用,见 bin/package.json):

pnpm run --filter bin deletePad <padID>

从源码看,bin/deletePad.ts 的实现会读取 settings.json 中的 ip/port 与根目录 APIKEY.txt,先请求 /api/ 获取当前 API 版本,再 POST 到 /api/<version>/deletePad 完成删除。这类工具需要 Etherpad 处于运行状态,因为它走的是 HTTP API。

如何备份与恢复 Pad?

备份整个实例

所有 Pad 数据都存放在配置的数据库中。请使用适合后端的方式备份:MySQL/MariaDB 用 mysqldump,PostgreSQL 用 pg_dump,基于文件的 dirty/rusty 引擎则需在 Etherpad 停止时复制 var/*.db 文件。对生产实例而言,定期自动化的数据库转储是规范的备份方案。

如需更换数据库后端,可参考 CLI 章节 的 migrateDB 工具(pnpm run --filter bin migrateDB --file1 source.json --file2 target.json,需在实例停止时运行),或使用 migrateDirtyDBtoRealDB 将 var/dirty.db 一次性迁入真实数据库。

备份单个 Pad

在 Pad 的 URL 后追加 /export/<type> 即可通过 HTTP 导出。纯文本、HTML 与可往返的 etherpad 格式最适合备份:

curl -o mypad.txt   https://pad.example.com/p/foo/export/txt
curl -o mypad.html  https://pad.example.com/p/foo/export/html
curl -o mypad.etherpad https://pad.example.com/p/foo/export/etherpad

etherpad 导出保留 Pad 的完整历史且可重新导入,是迁移或归档单个 Pad 的最佳选择。

恢复或查看旧修订

Pad 经历过的每个状态都存储在数据库中,因此无需单独备份即可找回早期修订:

  • 打开 /p/:padID/timeslider 浏览历史,找到所需修订号;
  • 用 ?revs=N 查询参数直接导出指定修订,例如 https://pad.example.com/p/foo/export/html?revs=1000。

修复损坏的 Pad

如果 Pad 数据损坏,可使用 CLI 修复工具(checkPad、repairPad、rebuildPad),完整用法见 CLI 章节:

工具 用途 运行前提
pnpm run --filter bin checkPad <padID> 检查单个 Pad 修订是否损坏 实例停止
pnpm run --filter bin checkAllPads 检查实例上所有 Pad 实例停止
pnpm run --filter bin repairPad <padID> 提取全部数据、删除并重新插入以修复 实例停止
pnpm run --filter bin rebuildPad <padID> <rev> [newPadID] 在已知良好修订处重建为新的 Pad(默认 <padID>-rebuilt) 实例停止

checkPad/checkAllPads 只报告损坏、不修改任何数据;repairPad 与 rebuildPad 会写入。执行任何写操作前务必先备份数据库。

如何限制历史或修剪修订?

Etherpad 会保留每个 Pad 的完整修订历史,因此数据库会随时间持续增长。若要回收空间,可使用 Pad 压缩 CLI 工具,它们会折叠或修剪一个 Pad、所有 Pad、或仅过期 Pad 的修订历史:

# 折叠某个 Pad 的全部历史
pnpm run --filter bin compactPad <padID>

# 仅保留某个 Pad 的最后 50 个修订
pnpm run --filter bin compactPad <padID> --keep 50

# 压缩实例上的所有 Pad
pnpm run --filter bin compactAllPads

# 仅压缩 90 天内未被编辑的 Pad,保留最后 50 个修订
pnpm run --filter bin compactStalePads --older-than 90 --keep 50

这三个工具都要求 settings.json 中设置 cleanup.enabled = true(模板默认值为 cleanup: { "enabled": false, "keepRevisions": 5 },见 settings.json.template),并且都是破坏性操作——历史会被折叠或修剪。操作前务必先通过 Pad 的 /export/etherpad 路由导出任何不能丢失的内容。同一原语也可通过 HTTP API 的 compactPad 方法在线触发,详见 CLI 章节 与 HTTP API 章节。

压缩工具的源码级原理

从源码看,这套工具的调用链与设计颇具工程细节,值得运维人员了解:

  • CLI 是 API 的薄封装:bin/compactPad.ts、bin/compactAllPads.ts 与 bin/compactStalePads.ts 均通过 HTTP API 驱动运行中的 Etherpad:compactPad 先调用 getRevisionsCount 打印压缩前的修订数(pre-flight),压缩后再读取一次并展示"压缩前 → 压缩后"的修订数量对比。compactAllPads 组合 listAllPads → getRevisionsCount → compactPad,逐 Pad 容错,单个失败不中断整个批次,退出码反映是否有失败;还支持 --dry-run 只列出 Pad 与修订数而不写入。

  • compactStalePads 的冷热隔离:bin/compactStalePads.ts 组合 listAllPads → getLastEdited → compactPad,按最后编辑时间过滤。它对"热 Pad"特别谨慎:第一遍筛选后,在真正压缩前会再次检查每个 Pad 的最后编辑时间,缩小选择与压缩之间的 TOCTOU 窗口——若 Pad 在批量运行期间重新变为活跃,则跳过而非压缩,避免误伤正在被用户使用的 Pad。

  • 底层清理原语:src/node/utils/Cleanup.ts 实现了 deleteAllRevisions(通过"复制无历史 Pad → 回拷 → 删除临时 Pad"完成全历史折叠)与 deleteRevisions/rebuildHistory(保留最近 N 个修订)。rebuildHistory 的实现顺序刻意设计为:先写重建后的历史,再移动 head 指向新历史,最后删除孤儿修订——若中途失败,Pad 只会浪费空间而不会出现历史空洞或头部错乱;压缩前还会调用 pad.check() 校验,并检测缺失修订(findMissingRevisions),发现缺失时拒绝清理(参见源码中关于 issue #8134 的注释)。同时它会将正在编辑该 Pad 的会话踢出(kickSessionsFromPad),并正确平移 savedRevisions 中的修订号。

  • --keep N 参数语义:不指定时折叠全部历史;指定时保留最后 N 个修订。--older-than 仅 compactStalePads 支持且为必填项。

compactStalePads 适合对长期运行的实例做周期性巡检——用户仍在 timeslider 中浏览的活跃 Pad 保持不动,只重写冷数据尾部,是回收数据库空间的推荐日常手段。

附:运维 CLI 工具速查

除上述工具外,bin/ 目录还包含数据库迁移(migrateDB、migrateDirtyDBtoRealDB、importSqlFile)、会话管理(deleteAllGroupSessions、createUserSession)与插件管理(plugins、checkPlugin、stalePlugins)等工具,统一通过 pnpm run --filter bin <script> [args] 调用。这些脚本是 TypeScript 文件、没有编译产物,必须经由 tsx 加载器运行,直接 node 执行不会成功。完整清单与"运行中/停止时"使用约束见 CLI 章节。

登录后查看全文
etherpad