• 部署方式：1Panel 应用商店 Docker Compose 部署 Halo Pro

• 原版本：halohub/halo-pro:2.20.21

• 最终升级到：halohub/halo-pro:2.24.2

• 数据库：外置 mysql:8.4.5 容器

• 端口：8090

二、关键路径（重点记住）

1. Halo 实际部署目录

plaintext

/opt/1panel/apps/halo/halo

2. 核心文件都在这里

• 配置编排文件：docker-compose.yml

• 数据挂载目录：./data 对应容器内 /root/.halo2（所有文章、主题、配置、数据库文件都存在这里）

• 面板应用模板目录：

plaintext

/opt/1panel/resource/apps/remote/halo/

三、需要修改的文档 & 作用

只改一个文件：docker-compose.yml

路径：/opt/1panel/apps/halo/halo/docker-compose.yml

需要修改的地方：

yaml

image: halohub/halo-pro:2.20.21

把版本号改成你要升级的版本，例如：

yaml

image: halohub/halo-pro:2.24.2

其余所有配置不用动：端口、数据库关联、数据挂载、健康检查、网络都保持原样。

挂载关键配置（不用改）：

yaml

volumes:
  - ./data:/root/.halo2

作用：升级不丢数据、不丢文章、不丢主题配置。

四、本次完整升级操作步骤（按你实际执行顺序整理）

1. 进入 Halo 部署目录

bash

运行

cd /opt/1panel/apps/halo/halo

2. 编辑 docker-compose.yml 换版本号

bash

运行

nano docker-compose.yml

找到 image: 那一行，把旧版本改成新版本，保存退出。

3. 拉取新版镜像（一开始超时失败）

bash

运行

docker compose pull

报错：镜像仓库超时，直接用下一步强制重建启动。

4. 重新创建容器并后台启动

bash

运行

docker compose up -d

自动拉取新镜像、停止旧容器、启动新版本容器。

5. 查看升级运行状态

bash

运行

docker ps

观察状态：

• health: starting 正在启动初始化

• 变成 healthy 代表启动正常、服务就绪

五、数据存放说明（不用额外迁移）

• 本地目录：/opt/1panel/apps/halo/halo/data

• 映射容器：/root/.halo2

只要不删这个 data 文件夹，随便升级版本，文章、主题、设置全部保留。

六、升级后后续必做步骤

1. 浏览器访问：你的IP:8090，进入后台

2. 首次升级会自动执行数据库结构迁移，等待 1~3 分钟即可

3. 检查：

   • 文章是否都在

   • 主题样式是否正常

   • 后台插件是否正常

4. 若插件兼容报错：后台插件里禁用再重新安装对应版本即可

七、常用后续维护命令（收藏备用）

bash

运行

# 查看容器运行状态
docker ps

# 查看 halo 日志（排查启动报错）
docker logs 1Panel-halo-P7YU

# 停止 halo
docker compose down

# 重启 halo
docker compose restart

八、总结关键点

1. 不用找 jar 包、不用装环境，全程改 docker-compose.yml 版本号 即可；

2. 数据都在 ./data 目录，升级零丢失；

3. 操作固定套路：进目录→改镜像版本→docker compose up -d→看状态变 healthy 就完事。

以后再升级，直接照着这套流程走就行