Plausible社区版部署中账号注册失败问题分析与解决

问题现象

在部署Plausible社区版分析服务时，用户遇到了账号注册功能失效的问题。具体表现为服务能够正常启动并访问注册页面，但在填写完注册表单点击"创建账号"按钮后，系统没有任何响应，前端界面卡住不动。

根本原因分析

通过日志排查发现，该问题主要由两个关键因素导致：

1. WebSocket连接未正确配置：Plausible的前后端交互依赖于WebSocket协议，而初始的Nginx配置中缺少对WebSocket的支持。

2. 数据库初始化问题：从日志中可以看到ClickHouse数据库(plausible_events_db)初始化时出现了错误，提示数据库不存在，这可能影响部分功能的正常运行。

解决方案

WebSocket配置修复

对于使用Nginx作为反向代理的用户，需要在Nginx配置中添加以下WebSocket支持配置：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;

这些配置确保了WebSocket连接能够正常建立和维持。

数据库初始化确认

确保在docker-compose文件中，Plausible服务有正确的启动顺序依赖：

command: sh -c "sleep 10 && /entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh run"
depends_on:
  - plausible_db
  - plausible_events_db

这段配置确保了数据库服务先启动，并给予足够时间初始化后，Plausible应用才会启动并执行数据库迁移。

完整配置建议

对于本地开发环境，推荐使用以下配置组合：

1. 环境变量配置(plausible-conf.env)：

BASE_URL="http://localhost:8000"
SECRET_KEY_BASE="your_secret_key"
TOTP_VAULT_KEY="your_totp_key"
DISABLE_REGISTRATION=false

2. 服务端口映射：

ports:
  - 8000:8000

3. Caddy配置(如使用)：

labels:
  virtual.host: "localhost"
  virtual.port: "8000"
  virtual.tls-email: "your_email"

验证方法

成功配置后，用户应该能够：

1. 直接访问服务端口(如8000)看到注册页面
2. 填写注册表单后能够正常提交并创建账号
3. 浏览器开发者工具中不再显示WebSocket连接错误

总结

Plausible社区版的部署过程中，账号注册功能失效通常与WebSocket配置或数据库初始化问题相关。通过正确配置反向代理的WebSocket支持和确保数据库服务正确初始化，可以解决大多数注册功能异常的问题。对于本地开发环境，直接暴露服务端口并禁用注册限制是最简单的验证方式。