建站工具 Halo 使用 JAR 文件部署

部署 Halo 前，需确认软硬件配置符合要求，避免后续出现兼容问题。

硬件配置

服务器类型：不支持云虚拟主机，需使用云服务器或 VPS。

CPU：无特殊要求，Docker 镜像已支持多平台。

内存：建议至少 1G RAM，保证运行流畅。

磁盘：无强制容量要求，推荐 SSD 硬盘，提升运行速度。

网络：可在无公网环境使用，但部分主题依赖第三方资源，可能需要公网。

软件环境

Docker（可选）：推荐使用 Docker 部署，减少环境配置问题。

JRE（可选）：若用 Docker 镜像部署，无需安装 JRE，若用 JAR 文件部署，版本需匹配：2.21 以上版本需 JRE 21，2.20 及以下版本需 JRE 17。

数据库：支持 PostgreSQL、MySQL、MariaDB、H2。其中 H2 无需单独运行，其他需单独安装配置。生产环境不推荐 H2 数据库，可能因操作不当损坏数据文件，若必须使用，需按时备份。

Web 服务器（可选）：生产环境绑定域名时，推荐用 Nginx、Caddy 等做反向代理，注意 Halo 不支持代理到子目录（如 halo.run/blog）。

辅助工具（可选）：后续操作会用到 wget 下载文件、vim 修改配置文件，也可使用其他熟悉的工具替代。

浏览器支持

• 用户前台：取决于主题支持情况。

• 管理后台：支持常见现代浏览器，具体以 Vue 框架支持为准。

名词解释

~（符号）：代表当前系统的用户目录。

镜像：Halo 的 Docker 镜像，用于启动应用。

工作目录：Halo 运行时在用户目录下生成的 .halo2 文件夹（路径 ~/.halo2），包含 db、themes、plugins、attachments、logs、application.yaml、backups、static 等目录或文件。使用 Docker 部署需注意目录映射。

主题：包含站点页面模板的资源包，决定用户浏览到的内容和样式。

插件：扩展 Halo 功能的软件包，可独立安装、升级、卸载。

使用 JAR 文件部署 Halo

若选择 JAR 文件部署，按以下步骤操作。

1、依赖检查

确保服务器满足：

• 已安装对应版本的 Java 环境（2.21+ 用 JRE 21，2.20 及以下用 JRE 17）。

• 已安装数据库（MySQL 5.7+、MariaDB、PostgreSQL 中的任一）。

2、安装步骤

创建系统用户：不推荐用 root 用户运行，可创建名为 halo 的用户（也可自定义）：

useradd -m halo
passwd halo  # 设置密码
su - halo  # 登录 halo 账户

创建目录：

mkdir ~/app && cd ~/app  # 存放运行包

下载运行包：

wget https://dl.halo.run/release/halo-2.21.0.jar -O halo.jar

官方下载地址：download.halo.run , github.com/halo-dev/halo/releases 。

创建工作目录：

mkdir ~/.halo2 && cd ~/.halo2

创建配置文件：

vim application.yaml

复制以下内容并根据需求配置（数据库配置需对应正确格式）：

server:
port: 8090
spring:
r2dbc:
    url: r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE
    username: admin
    password: 123456
sql:
    init:
    mode: always
    platform: h2
halo:
work-dir: ${user.home}/.halo2
external-url: http://localhost:8090
attachment:
    resource-mappings:
    - pathPattern: /upload/**
        locations:
        - migrate-from-1.x

数据库需提前创建，如 MySQL 可执行 create database halo character set utf8mb4 collate utf8mb4_bin;。

3、测试运行

cd ~/app && java -Dfile.encoding=UTF-8 -jar halo.jar --spring.config.additional-location=optional:file:$HOME/.halo2/

无异常日志时，访问 http://ip:端口号 可进入初始化页面。测试完成后按 CTRL + C 停止进程。

4、作为服务运行

• 退出 halo 账户，登录 root 账户（若已是 root 可跳过）：

exit

• 创建服务文件：

vim /etc/systemd/system/halo.service

复制以下内容并配置 JAR_PATH（运行包绝对路径）和 USER（运行用户）：

[Unit]
Description=Halo Service
Documentation=https://docs.halo.run
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=USER
ExecStart=/usr/bin/java -Dfile.encoding=UTF-8 -server -Xms256m -Xmx256m -jar JAR_PATH --spring.config.additional-location=optional:file:/home/halo/.halo2/
ExecStop=/bin/kill -s QUIT $MAINPID
Restart=always
StandOutput=syslog
StandError=inherit

[Install]
WantedBy=multi-user.target

• 重新加载并启动服务：

systemctl daemon-reload
systemctl start halo
systemctl enable halo  # 设置开机启动

• 查看日志：

journalctl -n 20 -u halo

5、版本升级

• 备份数据（推荐）。 • 停止服务：

service halo stop

• 下载新版本覆盖旧文件：

wget https://dl.halo.run/release/halo-2.21.0.jar -O /home/halo/app/halo.jar

• 启动服务：

service halo start

6、反向代理配置

Nginx：

upstream halo {
server 127.0.0.1:8090;
}
server {
listen 80;
listen [::]:80;
server_name www.yourdomain.com;
client_max_body_size 1024m;
location / {
    proxy_pass http://halo;
    proxy_set_header HOST $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}

Caddy 2：

www.yourdomain.com
encode gzip
reverse_proxy 127.0.0.1:8090