Etherpad 运维实战指南:安装部署、Pad 管理与数据备份恢复全解
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 章节。