常见问题排查：502、空白页与缓存
按“进程 → 数据库 → 反向代理 → 主题/缓存”的顺序快速定位。
排查线上问题时，先确认请求走到了哪一层，再逐层缩小范围，比反复重启服务更有效。
第一步：进程是否活着
ss -lntp | grep 23180
ps -eo pid,ppid,user,cmd | grep 'cms serve'
curl -i http://127.0.0.1:23180/health/live本地健康检查都失败时，问题在应用或数据库；本地正常而域名 502，问题在 Nginx 或上游代理。
第二步：数据库与迁移
source shared/configs/runtime.env
./current/bin/cms doctordoctor 会检查连接、迁移、目录权限、主题与插件状态。常见原因是数据库密码未注入、账号权限不足，或者迁移执行到一半被中断。
第三步：反向代理
nginx -t
tail -f /www/wwwlogs/站点.error.log
curl -I -H 'Host: cms.example.com' http://127.0.0.1/确认 proxy_pass 端口、证书路径和 Host 头。开启了 CDN 时，还要检查回源地址与回源 Host。
第四步：主题与缓存
- 页面白屏或 500：执行
cms theme validate --source shared/themes/当前主题，检查标签和资源引用。 - 改了模板但不生效：确认改的是
shared/themes而不是旧版本目录，并清理浏览器/CDN 缓存。 - 发布后列表没更新：页面缓存最多 5 分钟自然过期；多实例部署会在几秒内广播失效。
- 搜索没有结果：执行
cms search reindex重建索引，或确认后台搜索模式。
其他常见提示
| 现象 | 优先检查 |
|---|---|
invalid plugin secret key | auth.identity_hash_key 是否为 Base64 的 32 字节 |
database.password is required | runtime.env 是否使用 export 并被服务加载 |
| 管理员密码文件被拒绝 | 密码文件权限必须为 0600 |
| License Cloud 502 | 本地无法访问 Cloud 时的环境问题，不影响社区版使用 |
| 后台入口 404 | 确认 app.yaml 的 admin_path 与访问地址一致，并带末尾斜杠 |
收集信息
提交问题前，请准备：CMS 版本、部署方式、doctor 输出、相关时间段的错误日志、请求的 X-Request-Id。这些信息能显著缩短定位时间。
讨论
发表评论