给 Halo 博客换颗心脏:从 H2 迁到 PostgreSQL 的完整实战手册
用 Docker 起一个 Halo 博客只需五分钟,这也是它最诱人的地方。但很多人没注意的是:默认配置下,Halo 用的是 H2——一个内嵌在 Java 进程里的单文件数据库。跑一两个月没毛病,某天你可能会撞上这样的灵异事件:发布文章接口明明返回 200,文章却在几分钟后从列表里消失;翻容器日志,一串 MVStoreException: Writing to file failed 和 database has been closed [90098]。这不是灵异,是 H2 的数据库文件在历次异常断电、进程被杀、磁盘写抖动中受了内伤,之后每次大写入触发文件整理失败,库自我关闭、回滚提交。
Halo 官方对此的态度相当直白。安装文档里原话是:「不推荐在生产环境使用默认的 H2 数据库,这可能因为操作不当导致数据文件损坏」;官方博客在快速上手教程里也提醒 H2「不适合作为生产唯一存储,正式环境请换用 PostgreSQL 等并做好备份」。今天这篇就把换库手术一次讲透:不借助第三方工具,只用 Halo 自己的能力,把数据从 H2 平移到 PostgreSQL。
一、先想清楚:为什么 PostgreSQL 是「根治」而不是「续命」
H2 的问题出在存储机制上:整个库就是 halo2/db/halo.mv.db 这一个文件,写入靠追加、靠定期压缩整理(compaction)维持健康。它假设「进程优雅退出、磁盘诚实落盘」,可现实里的 VPS 快照、宿主机抖动、docker kill 都不惯着它——文件一旦带伤,轻则变慢,重则自锁回滚,docker restart 有时能救(H2 关库时会重写压缩文件),有时救不了。
PostgreSQL 是独立的数据库进程,数据落盘走 WAL(Write-Ahead Log,预写日志):任何改动先按顺序写日志再改数据页,崩溃后能精确恢复到已提交的事务边界。这套机制在数据库界锤炼了二十多年,是「服务器上跑关键数据」的标准答案。对 Halo 来说换库还有个顺手的收益:评论多、文章多之后的查询并发不再排队,备份还能用 pg_dump 做冷备,不再依赖单个文件的命运。
Halo 社区从很早就在 GitHub 上呼吁官方提供全站跨库迁移能力(issue #4059 就是代表)。从 Halo 2.8 起,Console 内置的「备份与恢复」把这件事官方化了——官方文档明确写着:恢复不限制部署方式,也不限制数据库,新站点的部署方式和数据库类型可以和备份的站点不同。这句话就是我们整个迁移方案的地基。
二、动刀前的两条保命底线
换心脏手术最忌讳的是「旧心脏先扔了」。动手前做两件事:
- 底线一:Console 里做一次全站备份。控制台左侧菜单「备份」→ 右上角「创建备份」。注意备份是后台异步执行的,点完别急着关页面,等状态变成「备份完成」。这个备份文件(zip 包)包含文章、页面、评论、附件、主题、插件、用户等完整数据,是等下灌进新库的「血包」。
- 底线二:把 Halo 工作目录整个复制一份。如果你是 Docker 部署,就是挂载到
/root/.halo2的那个宿主机目录(常见叫halo2)。停掉容器后整目录打包:
# 在宿主机执行:停容器 → 打包数据目录(路径按你的实际挂载调整)
docker stop halo
tar -czf halo2-h2-$(date +%Y%m%d).tar.gz ~/halo2/
# 打包完可以先把容器再启起来,旧站继续跑,不影响观察期
docker start halo有这两条在手,手术失败也随时能把旧库原样请回来。
三、起一套连着 PostgreSQL 的新 Halo
下面这份 docker-compose.yaml 按 Halo 官方文档的推荐结构整理(官方示例为 PostgreSQL 15.4 + healthcheck 编排),照抄后改三个地方就能用:数据库密码、外部访问地址、镜像版本保持你现有的一致(宝塔应用商店默认编排的就是社区版;官方文档示例用的是 Pro 版镜像,配置机制完全相同)。
services:
halo:
image: 你的现有镜像:版本 # 与旧站一致,避免引入变量
restart: on-failure:3
depends_on:
halodb:
condition: service_healthy
networks:
- halo_network
volumes:
- ./halo2:/root/.halo2 # 新库时代的工作目录,注意别挂旧目录
ports:
- "8090:8090" # 建议先换个临时端口,如 8091,等验证完再切
environment:
- JVM_OPTS=-Xmx256m -Xms256m # 1G 内存小机可降到 192m
command:
# ↓ 三行是重点:数据源从 H2 换成 PostgreSQL
- --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo
- --spring.r2dbc.username=halo
- --spring.r2dbc.password=改成你的强密码
- --spring.sql.init.platform=postgresql # 告诉 Halo 用 PG 方言建表
- --halo.external-url=https://你的域名/
halodb:
image: postgres:15.4
restart: on-failure:3
networks:
- halo_network
volumes:
- ./db:/var/lib/postgresql/data
healthcheck:
test: ["CMD", "pg_isready"]
interval: 10s
timeout: 5s
retries: 5
environment:
- POSTGRES_PASSWORD=改成你的强密码 # 与上面 r2dbc.password 一致
- POSTGRES_USER=halo
- POSTGRES_DB=halo
- PGUSER=halo # healthcheck 探活用
networks:
halo_network:三个容易踩的点提前说:
spring.r2dbc.url用的是 R2DBC 协议串(r2dbc:pool:postgresql://…),不是 JDBC 的jdbc:postgresql://…,抄网上老教程容易抄串。spring.sql.init.platform=postgresql不能省——它决定 Halo 首次启动时用哪套 SQL 方言初始化表结构,漏了它新库就是空壳。- 密码两处必须一致(PG 容器的
POSTGRES_PASSWORD与 Halo 的r2dbc.password),不一致的报错很隐晦,够你查一下午。
宝塔面板用户的捷径:不用命令行,左侧「Docker」→「容器编排」→ 新建项目,把上面这份贴进自定义模板即可;官方的宝塔部署文档本身就是这么教的。起栈之后先访问临时端口完成初始化向导——这一步建的临时管理员账号之后会被备份数据覆盖,随意填,别心疼。
四、灌数据:一次「恢复」完成跨库迁移
新实例空库跑起来后,进新站 Console,同样是左侧「备份」菜单,切到「恢复」选项卡。Halo 提供三种恢复方式,按备份文件在哪选一个:
- 上传备份文件:文件在本地电脑上,直接上传,适合几百 MB 以内的包;
- 远程恢复:备份文件在某个可公网访问的 URL 上,让新站自己去拉;
- 从备份文件恢复:文件已在服务器上——官方推荐把备份 zip 放进 Halo 工作目录的
backups/子目录,恢复页会自动扫描出来。大文件走这条路,最稳。
从旧站下载备份包的姿势:旧 Console 的「备份」页里,已完成的备份条目有下载入口,把 zip 拉到本地或直接传到新服务器都行。
点开始恢复后,页面会持续输出进度——期间千万别手贱刷新(官方文档特别提醒恢复耗时可能较长)。恢复的语义是「冲突数据被备份内容覆盖,已有数据不清理」,所以临时管理员账号会被备份里的原账号顶掉。跑完会弹窗提示重启 Halo,点确定;没设置自动重启的话,去服务器手动 docker restart 一下新容器。回来重新登录——用的就是旧站原来的账号密码,文章、评论、主题、附件、插件全部归位。
五、验收:五分钟过完这张清单
换库手术的验收标准要具体,别凭「感觉好了」就收工:
1. 文章数量 Console 文章列表总数 == 旧站数量
2. 最新一篇 打开发布时间最近的文章,正文/头图/评论齐全
3. 附件抽查 任挑 3 张老文章配图,右键能打开、状态 200
4. 主题与插件 外观无变化,常用插件启用状态与旧站一致
5. 发布演练 手发(或定时任务发)一篇草稿再发布,确认落库全绿之后做最后一步「切血管」:把 Nginx / 宝塔网站的反代目标从旧端口改到新栈端口,域名和 SSL 证书都不用动。观察一两天没问题,旧容器和 halo2-h2-*.tar.gz 那个包再留两周,然后才考虑退休它们——回滚窗口期内,旧的 H2 随时能上岗。
六、小内存 VPS 的两个实诚提醒
- 内存预算:PostgreSQL 15 常驻大约 150~250 MB(默认
shared_buffers就有 128 MB),加上 Halo JVM 的 256 MB,1G 内存的机器会紧。可以在 PG 容器的 command 里加-c shared_buffers=64MB -c max_connections=30压一压,个人博客完全够用;Halo 那边JVM_OPTS降到 192m 也是安全的。 - 以后还会换机器吗:迁到 PG 之后,下次搬家就是标准的
pg_dump+pg_restore(或直接docker run --volumes-from拷数据卷),Halo 官方的跨库恢复也依然是备选项。从「单文件数据库的幸存者」变成「正经数据库的运维者」,折腾半径完全不同了。
写在最后
这次迁移的技术含量其实不高——真正的门槛是心理上的:「现在还能跑,等真坏了再说」。但数据问题的规律恰恰是:能跑的时候做什么都便宜,坏了之后每一步都贵。Console 里点一次「创建备份」,十几分钟把 compose 贴上,恢复一次,验收五分钟——一个下午换掉博客最大的单点隐患,这笔账怎么算都划算。如果你的 Halo 还在默认 H2 上裸奔,这篇就是给你按下的那个开始键。
参考来源:Halo 官方文档(docs.halo.run「使用 Docker Compose 部署」「备份与恢复」「使用宝塔面板部署」三页)、Halo 官网教程《如何在本地快速体验 Halo》、Halo 社区论坛(bbs.halo.run)H2 性能与数据迁移相关讨论、GitHub halo-dev/halo issue #4059。
以上内容为 GLM 5.3 Agent 整合定时发布。

