搭建 Halo 现代博客系统完整教程（Docker 部署）

Halo 是一款基于 Java（Spring Boot）的现代开源博客/CMS 系统，界面美观，支持插件扩展，自带完善的后台管理。Halo 2.x 推荐使用 Docker 部署，配置简单，升级方便。本文以搬瓦工 VPS（Debian/Ubuntu）为例，演示从安装 Docker 到 Halo 上线的完整流程。

本文要点

安装 Docker 与 Docker Compose
用 Docker Compose 一键启动 Halo
配置 Nginx 反向代理
申请 Let's Encrypt SSL 证书
完成 Halo 初始化与基本设置

环境要求

组件	要求	说明
内存	≥ 512MB	Java 程序，推荐 1GB+
磁盘	≥ 5GB	含系统与数据存储
Docker	20.10+	推荐最新版
端口	8090（可自定义）	Halo 默认监听端口

Java 内存占用

Halo 基于 JVM 运行，启动后内存占用约 300–500MB。若 VPS 内存低于 512MB，建议先设置 Swap 空间（推荐 1GB），避免进程被系统强制终止。

安装 Docker

# Debian/Ubuntu 一键安装 Docker
curl -fsSL https://get.docker.com | bash
systemctl enable --now docker
# 验证
docker --version
docker compose version

创建 Halo 工作目录与配置文件

mkdir -p /opt/halo

创建 /opt/halo/docker-compose.yml：

version: "3"

services:
  halo:
    image: halohub/halo:2.20
    container_name: halo
    restart: on-failure:3
    network_mode: "host"
    volumes:
      - /root/.halo2:/root/.halo2
    environment:
      - SPRING_SQL_INIT_PLATFORM=h2
      - HALO_WORK_DIR=/root/.halo2
      - HALO_EXTERNAL_URL=https://your-domain.com
      - HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD=初始密码

数据库选择

上面配置使用 H2 嵌入式数据库，适合个人博客。如需更高并发，可将 SPRING_SQL_INIT_PLATFORM 改为 postgresql 并在 compose 文件中添加 PostgreSQL 服务。

启动 Halo

cd /opt/halo
docker compose up -d
# 查看启动日志
docker compose logs -f halo

等待日志出现 Started HaloApp in X seconds 表示启动成功。此时 Halo 监听在 :8090 端口。

安装并配置 Nginx 反向代理

apt install -y nginx

创建 /etc/nginx/sites-available/halo：

server {
    listen 80;
    server_name your-domain.com www.your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

ln -s /etc/nginx/sites-available/halo /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

申请 SSL 证书

apt install -y certbot python3-certbot-nginx
certbot --nginx -d your-domain.com -d www.your-domain.com

Certbot 会自动修改 Nginx 配置，添加 SSL 证书并设置 HTTPS 重定向。

Halo 初始化设置

在浏览器访问 https://your-domain.com/console，使用 docker-compose.yml 中设置的超管密码登录，完成以下初始化：

设置站点名称、描述、Logo
进入插件页面，安装内置插件（搜索、评论、图片库等）
进入主题页面，从主题市场选择并安装喜欢的主题
进入 设置 → 基本设置，配置站点 URL 为你的 HTTPS 域名

常用管理命令

# 查看运行状态
docker compose -f /opt/halo/docker-compose.yml ps

# 更新 Halo 到最新版
docker compose -f /opt/halo/docker-compose.yml pull
docker compose -f /opt/halo/docker-compose.yml up -d

# 备份数据
tar czf halo_backup_$(date +%Y%m%d).tar.gz /root/.halo2

数据目录说明

Halo 的所有数据（数据库、上传文件、主题、插件）都存储在 /root/.halo2 目录中。定期备份此目录即可保全所有网站数据。

小结

Docker Compose 部署 Halo 简单快捷，升级只需 pull 新镜像
Nginx 反向代理 + Certbot SSL 是标准的生产配置
所有数据集中在 /root/.halo2，备份简单
Halo 内置插件和主题市场，功能扩展方便

常见问题

Halo 和 WordPress 相比有什么优劣？

Halo 界面更现代，后台体验更好，原生支持中文；WordPress 插件/主题生态更庞大。Halo 适合个人博客和内容站，WordPress 适合需要大量插件功能的商业网站。

如何升级 Halo 版本？

修改 docker-compose.yml 中的镜像版本号（如 halohub/halo:2.21），然后执行 docker compose pull && docker compose up -d 即可，数据不会丢失。

Halo 访问后台 404 怎么办？

确认 Halo 容器正在运行（docker compose ps），并检查 Nginx 反向代理配置是否正确指向 8090 端口，以及 proxy_set_header 是否完整。

可以在一台服务器上同时运行 Halo 和 WordPress 吗？

可以。使用 Nginx 不同的 server_name 配置分别代理两个应用，将它们分配在不同端口互不干扰。