常见故障排查

服务无法启动

依次检查 MySQL、Elasticsearch 和 Redis 是否可达，再查看服务日志中的首个错误。常见原因包括数据库凭据不匹配、端口错误、迁移失败、JWT 密钥文件权限或依赖服务未健康。

不要跳过数据库迁移的 SHA256 校验。已经发布的迁移文件不得改写；新的结构变化应新增迁移文件。

首页能开，搜索没有结果

1. 检查 Elasticsearch 集群健康；
2. 在后台资源列表确认数据库内有公开且有效的资源；
3. 查看索引文档数量；
4. 必要时使用后台重建索引任务；
5. 检查过滤词、违禁词、资源状态和搜索页限制；
6. 查看系统日志和任务结果。

登录后立即退出

检查服务器时间、JWT 密钥是否被替换、用户状态与角色是否改变，以及账号的令牌版本。多台实例必须使用相同有效密钥，并保证系统时钟同步。

注册或找回密码收不到邮件

确认站长已启用相关流程并完成 SMTP 配置；查看发送日志、TLS 与端口、防火墙、发件域名和垃圾邮件目录。不要在前端显示 SMTP 密码或完整服务器错误。

后台改了配置但页面没变化

• 确认保存接口返回成功；
• 刷新公开配置请求；
• 清理浏览器、反向代理或 CDN 缓存；
• 检查是否修改了另一个部署实例；
• 对图标和静态资源检查版本参数或缓存头。

反向代理后地址或 IP 不正确

确认 SITE_URL 使用公开域名，代理传递正确的 Host、协议与客户端 IP 请求头，并将真实代理网段加入 TRUSTED_PROXIES。不要把任意公网网段设为可信代理。