Etherpad-Lite 连接 MySQL 数据库的正确配置方式

在部署 Etherpad-Lite 协作编辑平台时，许多用户会选择 MySQL 作为后端数据库。然而，在通过 Unix 域套接字连接 MySQL 时，官方文档中的配置方法存在错误，导致连接失败。本文将详细介绍正确的配置方法及其背后的技术原理。

常见错误配置

根据过时的文档，用户通常会尝试以下配置方式：

"dbType": "mysql",
"dbSettings": {
  "user": "etherpad",
  "port": "/run/mysqld/mysqld.sock",
  "password": "password",
  "database": "etherpad",
  "charset": "utf8mb4"
}

这种配置会导致 Etherpad-Lite 忽略套接字路径设置，转而尝试通过 TCP/IP 连接本地 3306 端口。当 MySQL 未监听 TCP 端口时，系统会抛出 ECONNREFUSED 错误。

技术背景分析

Etherpad-Lite 通过 ueberDB 抽象层与数据库交互，而 ueberDB 底层使用 mysql2 驱动。mysql2 是 Node.js 生态中维护良好的 MySQL 客户端库，相比旧版 mysql 驱动具有更好的性能和安全性。

mysql2 驱动明确区分了两种连接方式：

1. TCP/IP 连接：使用 host 和 port 参数
2. Unix 域套接字连接：使用 socketPath 参数

当指定 socketPath 时，驱动会完全忽略 host 和 port 设置，这是设计上的有意行为。

正确配置方法

要通过 Unix 域套接字连接 MySQL，应使用以下配置：

"dbType": "mysql",
"dbSettings": {
  "user": "etherpad",
  "socketPath": "/run/mysqld/mysqld.sock",
  "password": "password",
  "database": "etherpad",
  "charset": "utf8mb4"
}

关键变化是将 port 参数替换为 socketPath 参数。这种配置方式具有以下优势：

1. 安全性更高：Unix 域套接字仅限于本地通信
2. 性能更好：避免了 TCP/IP 协议栈的开销
3. 可靠性更强：不受网络配置变化影响

配置验证与排错

验证配置是否生效的方法：

1. 确认 MySQL 确实配置为使用套接字连接
2. 检查套接字文件路径是否正确
3. 确保 Etherpad-Lite 进程有访问套接字文件的权限
4. 查看启动日志中是否出现数据库连接错误

常见问题解决方案：

• 若出现 EACCES 错误，需调整套接字文件权限
• 若出现 ENOENT 错误，检查路径拼写是否正确
• 若出现认证错误，确认用户名密码是否正确

最佳实践建议

对于生产环境部署，建议：

1. 为 Etherpad-Lite 创建专用数据库用户
2. 限制该用户的权限到必要的最小范围
3. 使用 utf8mb4 字符集以支持完整 Unicode
4. 考虑定期备份数据库
5. 监控数据库连接性能

通过正确配置 Unix 域套接字连接，可以确保 Etherpad-Lite 与 MySQL 数据库建立稳定、高效的连接，为协作编辑体验提供可靠的后端支持。