【Halo 迁移后后台转圈 + 前台 Template index was not found 完整解决流程】
适用场景：
- Halo 从一台 VPS 迁移到另一台
- 后台登录一直转圈
- 前台访问显示：
Template index was not found.- 插件/主题提示版本过低
一、问题本质分析（必须先理解）
出现这组症状，本质通常是三类问题叠加：
| 现象 | 真正原因 |
|---|---|
| 后台登录一直转圈 | Halo 运行时报错（依赖缺失 / 版本问题） |
| 前台 Template index was not found | 当前启用主题不存在 |
| 主题安装失败 | Halo 主程序版本过低 |
二、第一步：确认容器是否正常
进入 Halo 目录：
cd ~/data/docker_data/halo
查看日志：
docker logs --tail=120 halo
如果看到类似错误：
NoClassDefFoundError: org/bouncycastle/crypto/params/Argon2Parameters$Builder
说明：
当前 Halo 镜像存在依赖问题（旧版本问题）
三、升级 Halo（核心步骤）
⚠️ 不要纠结，直接升级到 2.22.x 以上版本。
3.1 修改 docker-compose.yml
把：
image: halohub/halo:2.20.18
改成：
image: halohub/halo:2.22
你可以直接执行：
sed -i 's#image: halohub/halo:2\.20.*#image: halohub/halo:2.22#g' docker-compose.yml
3.2 拉取新镜像 + 强制重建
docker compose pull halo
docker compose up -d --force-recreate
查看版本：
docker logs --tail=20 halo
确认出现：
Version: 2.22.x
3.3 验证服务是否正常
curl -I http://127.0.0.1:8090/
返回：
HTTP/1.1 404 Not Found
说明：
Halo 服务正常，只是首页模板不存在
四、后台登录验证
浏览器访问：
https://你的域名/login
如果可以正常登录：
✔ 登录链路已修复
✘ 如果仍转圈 → F12 看 Network 状态码
五、解决 Template index was not found
本质原因：
当前主题不存在（themes 目录为空）
服务器验证：
ls -lah ~/data/docker_data/halo/halo_app_data/themes
如果显示：
No such file or directory
说明主题文件确实没了。
5.1 正确处理方式
进入后台：
后台 → 主题 → 安装主题 → 启用
刷新前台即可恢复。
六、插件版本不兼容问题
如果日志出现：
requires >=2.22.0
说明：
插件版本高于当前 Halo 版本
解决方式：
升级 Halo（见第三步）
七、external-url 必须正确（避免缓存和跳转问题）
在 docker-compose.yml 中确认：
- --halo.external-url=https://你的域名/
注意：
- 必须是最终访问域名
- 建议统一 https
- 建议保留结尾
/
修改后重启：
docker compose up -d --force-recreate
八、完整恢复判断标准
当以下条件全部满足时，说明系统彻底恢复：
✔ docker logs 无异常
✔ 后台可登录
✔ 前台不再报 Template 错误
✔ 主题可正常安装
✔ 插件版本不再提示系统版本过低
九、下次再遇到相同问题的最短处理流程
直接执行：
① docker logs 看是否版本问题
② 升级到 image: halohub/halo:2.22
③ docker compose up -d --force-recreate
④ 后台重新安装主题
不要再去：
- 乱改数据库
- 乱恢复备份
- 乱删除 mysql
- 怀疑反向代理
90% 的情况都是版本 + 主题问题。
十、架构反思（避免再次踩坑）
这次事故的真正原因是：
- 使用了较旧 Halo 版本（2.20.x）
- 插件/主题要求更高版本
- 迁移时主题文件未保留
- 没第一时间看日志
十一、最终建议的稳定版本配置（推荐）
docker-compose.yml 建议长期使用：
image: halohub/halo:2.22
而不是固定死某个小版本。
十二、核心认知总结
- 登录转圈 ≠ 反向代理问题
- Template index 错误 ≠ 数据丢失
- 404 ≠ 服务没启动
- 日志是第一诊断工具
评论区