常见错误与解决

无法启动服务

Error: JWT_SECRET is required

• 原因：JWT 签名密钥未设置，这是启动服务的必填项。
• 解决：在环境变量中添加 JWT_SECRET，设置一个随机字符串即可。

Error: SNOWFLAKE_WORKER_ID is required

• 原因：Snowflake 工作节点 ID 未设置。
• 解决：在环境变量中添加 SNOWFLAKE_WORKER_ID=1（单实例部署填 1 即可）。

Connection refused to postgres:5432

• 原因：PostgreSQL 服务未启动，或连接配置错误。
• 解决：
  1. 确认 PostgreSQL 容器或服务已正常运行；
  2. 检查 PG_HOST、PG_PORT、PG_USER、PG_PASSWORD 是否正确；
  3. Docker 部署时，注意容器之间的网络是否互通。

无法访问后台

502 Bad Gateway

• 原因：反向代理（Nginx/Caddy）配置错误，无法正确代理到后端服务。
• 解决：检查反向代理配置中的 upstream 地址和端口，确认后端服务端口是否为 2333（或你自定义的 PORT）。

证书错误

• 原因：HTTPS/SSL 证书配置有问题，或使用了自签名证书但客户端不信任。
• 解决：检查证书是否过期，确认 Nginx/Caddy 的 SSL 配置正确，必要时重新申请证书。

功能异常

搜索不工作

• 原因：Algolia 配置缺失或错误，索引未建立。
• 解决：
  1. 进入后台检查 Algolia 的 IndexName、AppID、ApiKey 是否填写正确；
  2. 确认 Algolia 控制台中索引已创建且有数据；
  3. 保存配置后等待片刻，让系统自动同步索引。

第三方登录失败

• 原因：OAuth 应用的回调地址（Callback URL）与后台配置不一致。
• 解决：
  1. 在 GitHub/Google 控制台核对 Authorization callback URL；
  2. 在 Mix Space 后台复制正确的回调地址并填入 OAuth 应用；
  3. 确认 ALLOWED_ORIGINS 中包含了你的前端域名。

数据相关

备份文件无法下载

• 原因：备份目录权限不足，或备份路径配置错误。
• 解决：检查备份目录的读写权限，确认运行服务的用户有权访问该目录。

回滚后数据丢失

• 原因：回滚时使用了错误的备份文件，或备份文件本身已损坏。
• 解决：
  1. 确认使用的是正确的备份文件（注意时间戳）；
  2. 回滚前务必先对当前数据做一次备份；
  3. 若备份文件损坏，尝试使用更早的备份。