Halo CMS开源建站，前后端分离个人站点

知识分享

2026-09-12 09:00

17 阅读

Halo CMS 是一款基于 Java 的开源建站工具，采用前后端分离架构，适合搭建个人博客或轻量内容站点。
本文面向零基础用户，用 Docker 方式在 Linux 服务器上完成部署，并配置 Nginx 反向代理和 HTTPS，最后验证站点可正常访问。

部署前需要准备什么

你需要一台能运行 Docker 的 Linux 服务器（1 核 2G 内存起步即可），一个已解析到服务器 IP 的域名，以及基本的 SSH 操作能力。
如果还没装 Docker，先执行官方脚本安装：

curl -fsSL https://get.docker.com | bash -s docker
systemctl enable docker && systemctl start docker
docker --version

看到版本号输出说明 Docker 就绪。
接着创建 Halo 的工作目录，所有数据都会保存在这里：

mkdir -p /opt/halo && cd /opt/halo

用 Docker Compose 启动 Halo 服务

Halo 官方推荐用 Docker Compose 管理容器。
在 /opt/halo 下新建 docker-compose.yml，内容如下：

version: "3"
services:
  halo:
    image: halohub/halo:2.20
    container_name: halo
    restart: unless-stopped
    ports:
      - "8090:8090"
    volumes:
      - ./halo2:/root/.halo2
    environment:
      - SPRING_R2DBC_URL=r2dbc:pool:mysql://127.0.0.1:3306/halo
      - SPRING_R2DBC_USERNAME=halo
      - SPRING_R2DBC_PASSWORD=你的数据库密码

注意镜像版本号建议以官方文档最新稳定版为准，不要照抄旧版本。
如果你不想用外部 MySQL，可以先去掉环境变量部分，Halo 会使用内置 H2 数据库，适合个人低流量站点。

保存后启动容器：

docker compose up -d
docker logs -f halo

当日志出现 Started HaloApplication 字样，说明服务已启动。
此时用 curl http://127.0.0.1:8090 应能返回页面内容。

配置 Nginx 反向代理并启用 HTTPS

Halo 默认监听 8090 端口，直接暴露不安全。
用 Nginx 做反向代理，同时申请 Let's Encrypt 证书。
先安装 Nginx 和 Certbot：

apt install nginx certbot python3-certbot-nginx -y

新建站点配置文件 /etc/nginx/conf.d/halo.conf：

server {
    listen 80;
    server_name 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;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

把 your-domain.com 换成你的真实域名，然后测试并重载：

nginx -t && systemctl reload nginx

接着申请证书并自动配置 HTTPS：

certbot --nginx -d your-domain.com

Certbot 会自动修改 Nginx 配置，完成后访问 https://your-domain.com 应能看到 Halo 初始化页面。

初始化站点与后台设置

首次访问域名会进入 Halo 安装向导，按提示设置管理员账号、站点名称和数据库信息（如果用了外部 MySQL）。
提交后进入后台，路径通常是 https://your-domain.com/console。

后台需要检查几个关键项：

站点地址：在“设置-基本设置”中确认站点 URL 填写的是 https:// 开头的完整域名，否则文章链接和静态资源可能加载失败。
主题：Halo 默认自带主题，可在“外观-主题”中切换或上传第三方主题包。
附件存储：如果文章要传图片，建议在“附件”中配置本地存储路径或对接对象存储。

完成这些后，发布一篇测试文章，前台能正常打开且图片显示正常，就算部署成功。

容易踩坑的地方

容器启动后立刻退出：多半是数据库连接失败。
先确认 MySQL 已启动、账号密码正确，且 Halo 容器能访问到数据库地址。
如果 MySQL 在宿主机上，用 127.0.0.1 可能不通，改用宿主机内网 IP 或 Docker 网络别名。

后台登录后跳回登录页：通常是 Nginx 没有正确传递 X-Forwarded-Proto 头，导致 Halo 认为你在用 HTTP 访问 HTTPS 站点。
检查上面 Nginx 配置中该头是否缺失。

上传图片失败：检查挂载目录权限，/opt/halo/halo2 需要对容器内用户可写。
可以临时执行 chmod -R 755 /opt/halo/halo2 验证，但生产环境建议保持最小权限。

升级后页面白屏：先备份 halo2 目录和数据库，再拉取新镜像重启。
Halo 大版本升级有时需要执行数据库迁移，具体以官方升级文档为准。

验证部署是否真正可用

完成配置后，按下面清单逐项确认：

浏览器访问 https://your-domain.com，地址栏显示锁图标，页面正常渲染。
登录后台发布一篇文章，前台点击标题能打开详情页，URL 是 https:// 开头。
在文章中插入一张图片，保存后前台刷新，图片能正常显示。
重启服务器，等待一分钟后再次访问，站点自动恢复（验证 restart: unless-stopped 生效）。

如果这四项都通过，说明你的 Halo CMS 前后端分离个人站点已经稳定运行。
后续换主题、绑多个域名或迁移服务器时，只需备份 halo2 目录和数据库，在新环境按同样步骤恢复即可。
遇到异常时，优先查看 docker logs halo 的输出定位问题。

DiscuzX站点被CC攻击防护

MCMS Java开源CMS部署，可视化建站操作