Etherpad-lite v2.0 升级指南：系统服务配置与常见问题解决

前言

Etherpad-lite 是一款优秀的开源协作编辑器，其 v2.0 版本带来了许多重大改进，包括从 npm 迁移到 pnpm 包管理器、TypeScript 支持等。然而，这些变化也给系统管理员带来了新的挑战，特别是在系统服务配置和升级过程中。

升级准备

在升级到 v2.0 版本前，建议做好以下准备工作：

1. 备份现有 settings.json 文件和 APIKEY.txt
2. 确保数据库已备份（特别是如果使用文件系统存储）
3. 准备升级 Node.js 到 v21 版本（v2.0 对 Node.js 版本要求较高）

系统服务配置

v2.0 版本的系统服务文件需要做相应调整，以下是推荐的 systemd 服务配置：

[Unit]
Description=Etherpad-lite, the collaborative editor.
After=syslog.target network.target

[Service]
Type=simple
User=etherpad
Group=etherpad
WorkingDirectory=/opt/etherpad
Environment=NODE_ENV=production
ExecStart=pnpm run prod
Restart=always

[Install]
WantedBy=multi-user.target

关键变化点：

• 使用 pnpm 作为包管理器
• 直接调用 pnpm run prod 命令启动
• 指定工作目录为 Etherpad 安装路径

常见问题解决

JSON 配置文件错误

升级过程中常见的 JSON 解析错误通常由以下原因引起：

1. 注释未正确移除（虽然 JSON5 支持注释，但某些解析器可能不兼容）
2. 缺少闭合括号
3. 格式错误的 skinVariants 配置

建议使用支持 JSON5 的校验工具检查配置文件。

依赖管理问题

v2.0 使用 pnpm 作为包管理器，可能遇到以下问题：

1. 依赖安装不完整：

   • 删除所有 node_modules 目录
   • 执行 pnpm install 重新安装

2. 权限问题：

   • 确保 etherpad 用户对安装目录有完全访问权限
   • 避免使用 root 用户运行 Etherpad

Node.js 版本兼容性

虽然文档说明支持 Node.js 18.18.2+，但实际运行中发现：

• Node.js 20 可能无法正确处理 TypeScript 文件
• 推荐使用 Node.js 21 以获得最佳兼容性

管理员登录问题

v2.0 版本中，管理员登录界面有所变化，若无法登录：

1. 确认 showSettingsInAdminPage 设置为 true
2. 检查用户配置格式是否正确
3. 确保密码字段未被意外修改

最佳实践

1. 测试环境先行：在生产环境升级前，先在测试环境验证
2. 版本控制：使用 git 管理 Etherpad 代码，便于回滚
3. 监控日志：配置日志轮转，定期检查错误日志
4. 依赖管理：理解 pnpm 的工作区概念，避免直接修改根目录的 package.json

总结

Etherpad-lite v2.0 带来了现代化的技术栈升级，虽然初期配置可能遇到挑战，但遵循本文指南可以顺利完成升级。随着项目的持续发展，预计未来版本会进一步改善 Node.js 版本兼容性等问题。对于生产环境，建议密切关注官方更新，及时应用稳定版本。