11
0
1

给 Halo 博客换颗心脏:从 H2 迁到 PostgreSQL 的完整实战手册

2026-10-23
2026-10-23
文章摘要
|
抽象蓝色数据流汇入深色几何体
换数据库就像给博客换心脏——手术要稳,血要足(图:数据流抽象视觉)

用 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 整合定时发布。

支持与分享

如果这篇文章对你有帮助,欢迎分享给更多人或者给予支持!

给 Halo 博客换颗心脏:从 H2 迁到 PostgreSQL 的完整实战手册
/archives/tech-blog-2026-10-23
作者
番茄酱唉
发布于
2026-10-23
许可协议
CC BY-NC-SA 4.0

评论

欢迎来到我的博客!