Halo 2.x 博客搭建与主题定制指南

我的博客从 WordPress 迁到 Halo 已经一年多了。选 Halo 的原因很简单：国产开源、界面清爽、主题生态成熟、 Docker 部署一条命令。

为什么从 WordPress 迁到 Halo

之前 WordPress 跑了两年，问题是：

1. 插件灾难 — 每次更新都担心某个插件不兼容，主题也是

2. Docker 化困难 — WordPress 的官方镜像不太适合多服务架构

3. 主题太重 — 加载慢，查个主题跟逛淘宝似的

Halo 2.x 出来后果断迁移。Docker 拉取镜像，改改配置，启动就是完整的博客系统。后台管理、编辑器、主题系统都比 WP 轻量太多。

快速部署（Docker Compose）

version: "3.8"
services:
halo:
image: halohub/halo:2.23
container_name: halo
restart: unless-stopped
ports:
- "8090:8090"
volumes:
- ./halo-data:/root/.halo2
environment:
- TZ=Asia/Shanghai
- HALO_SECURITY_INITIALIZER_USERNAME=admin
- HALO_SECURITY_INITIALIZER_PASSWORD=你的强密码
networks:
- app

networks:
app:
driver: bridge

第一次启动会初始化管理员账号。访问 http://IP:8090 按提示配置就行。

生产环境配置

我只用一条命令 docker run 是不够的。下面是我的完整生产配置要点：

数据库分离

不要用 Halo 内置的 H2 数据库，数据大了会挂。我用的是独立的 MySQL：

services:
halo:
# ...
environment:
- SPRING_DATASOURCE_DRIVER_CLASS_NAME=com.mysql.cj.jdbc.Driver
- SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/halo_nccsbr?characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
- SPRING_DATASOURCE_USERNAME=halo_user
- SPRING_DATASOURCE_PASSWORD=halo_password
depends_on:
- mysql
networks:
- app

mysql:
image: mysql:8.0
container_name: halo-mysql
restart: unless-stopped
volumes:
- ./mysql-data:/var/lib/mysql
environment:
- MYSQL_ROOT_PASSWORD=root密码
- MYSQL_DATABASE=halo_nccsbr
- MYSQL_USER=halo_user
- MYSQL_PASSWORD=halo_password
networks:
- app

域名 + HTTPS

用 OpenResty 反代，配置 HTTPS：

server {
listen 443 ssl http2;
server_name soulwrite.xyz;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
    
location / {
proxy_pass http://halo:8090;
# ... 其他反代头
}
}

主题定制（ZhihaiHub）

我用的主题是 ZhihaiHub，直接在后台主题市场搜"ZhihaiHub"安装。

自定义 CSS

后台 → 外观 → 主题设置 → 自定义 CSS，加几句：

/* 暗色主题适配 */
@media (prefers-color-scheme: dark) {
body {
background: #1a1a1a;
color: #e0e0e0;
}
}

/* 代码块样式 */
pre {
background: #2d2d2d;
border-radius: 8px;
padding: 16px;
}

/* 标题 hover 效果 */
h1:hover, h2:hover, h3:hover {
color: #3b82f6;
}

SEO 设置

主题设置 → SEO，打开：

- 启用itemap

- 自动推送百度

- Open Graph

插件推荐

我用这几个插件：

1. 搜索 — Halo 自带全文搜索，够用

2. 评论 — 内置评论系统，支持 Markdown

3. 备份 — 定时备份数据库和上传文件

4. ExChat — 接入 ChatGPT 浮动客服（可选）

备份策略

我的备份脚本：

#!/bin/bash
DATE=$(date +%F)
备份数据库
docker exec halo-mysql mysqldump -u halo_user -phalo_password halo_nccsbr > backup-$DATE.sql
压缩
tar czf halo-backup-$DATE.tar.gz backup-$DATE.sql ./halo-data/uploads
上传云端
rclone copy halo-backup-$DATE.tar.gz remote:backup/

每天凌晨 3 点跑一次。

踩坑记录

坑 1：上传文件 413

博客传大图片时报 413 Request Entity Too Large。OpenResty 默认限制了请求体大小。

解决：

client_max_body_size 50M;

坑 2：内存占用越来越高

Halo 跑久了内存从 300MB 涨到 1GB+。查了一下是 JVM 堆内存没限制。

environment:
- JAVA_OPTS=-Xms256m -Xmx512m -XX:+UseG1GC

坑 3：主题更新后样式丢失

每次主题更新，自定义 CSS 会清空。一定要把 CSS 内容备份到单独文件，更新后手动复制回去。

总结

Halo 2.x 适合：

- 想快速搭建博客的技术人

- 喜欢 Docker 部署的运维党

- 想要简洁后台的内容创作者

复杂度和 WordPress 相比不是一个级别。我现在维护成本基本为零，偶尔更新下主题就行。

彼方の旅人

Nginx/OpenResty 博客搭建与主题定制