使用 JAR 文件部署

先阅读《写在前面》

在继续操作之前，我们推荐您先阅读《写在前面》，这可以快速帮助你了解 Halo。

依赖检查

在开始之前，需要确保服务器已经满足以下条件：

Java 环境，版本要求：
- 2.21 以上版本：JRE 21
- 2.20 及以下版本：JRE 17
数据库（任一）

由于 Linux 发行版本的差异以及包管理器的不同，此文档不会涉及到如何安装 Java 环境以及数据库，建议查阅对应依赖的官方文档进行安装。

安装

创建新的系统用户

不建议使用 root 用户运行

我们不推荐直接使用系统 root 用户来运行 Halo。如果你需要直接使用 root 用户，请跳过这一步。

创建一个名为 halo 的用户（名字可以随意）

useradd -m halo

为 halo 用户创建密码

passwd halo

登录到 halo 账户

su - halo

创建存放运行包的目录

这里以 ~/app 为例

mkdir ~/app && cd ~/app

下载运行包

选择对应版本的 JAR 文件

Halo 主要区分为社区版和付费版，这两个版本使用不同的 JAR 文件，以下是 JAR 文件下载地址：

后续文档将使用 halo-pro-<version>.jar 为例，如果需要使用社区版，将 halo-pro 改为 halo 即可。

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

创建工作目录

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

创建 Halo 配置文件

vim application.yaml

将以下内容复制到 application.yaml 中，根据下面的配置说明进行配置。

application.yaml

server:
  # 运行端口
  port: 8090
spring:
  # 数据库配置，支持 MySQL、MariaDB、PostgreSQL、H2 Database，具体配置方式可以参考下面的数据库配置
  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
      # 需要配合 r2dbc 的配置进行改动
      platform: h2
halo:
  # 工作目录位置
  work-dir: ${user.home}/.halo2
  # 外部访问地址
  external-url: http://localhost:8090
  # 附件映射配置，通常用于迁移场景
  attachment:
    resource-mappings:
      - pathPattern: /upload/**
        locations:
          - migrate-from-1.x

数据库配置说明：

参数名	描述
`spring.r2dbc.url`	数据库连接地址，详细可查阅下方的 `配置对应关系`
`spring.r2dbc.username`	数据库用户名
`spring.r2dbc.password`	数据库密码
`spring.sql.init.platform`	数据库平台名称，支持 `postgresql`、`mysql`、`mariadb`、`h2`

配置对应关系：

链接方式	链接地址格式	`spring.sql.init.platform`
PostgreSQL（推荐）	`r2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}`	postgresql
MySQL	`r2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}`	mysql
MariaDB	`r2dbc:pool:mariadb://{HOST}:{PORT}/{DATABASE}`	mariadb
H2 Database	`r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE`	h2

数据库连接参数

HOST：数据库服务地址，如 localhost
PORT：数据库服务端口，如 3306
DATABASE：数据库名称，如 halo，需要提前创建，以 MySQL 为例：
```
create database halo character set utf8mb4 collate utf8mb4_bin;
```

不建议在生产环境使用 H2

不推荐在生产环境使用默认的 H2 数据库，这可能因为操作不当导致数据文件损坏。如果因为某些原因（如内存不足以运行独立数据库）必须要使用，建议按时备份数据。

查看完整配置

为了保持部署流程的简洁，此文档仅提供了必要的配置示例，完整的配置选项列表可查阅：配置说明

配置完成之后，保存即可。

测试运行 Halo

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

自定义工作目录

如果指定了其他工作目录，请将 $HOME/.halo2/ 替换为相应的绝对路径，并确保路径末尾带有 /。

测试访问

如果没有观察到异常日志，即可尝试访问 Halo

打开 http://ip:端口号 即可跳转到初始化页面。

测试运行不会持续

如测试启动正常，请继续看作为服务运行部分，第 8 步仅仅作为测试。当你关闭 ssh 连接之后，服务会停止。你可使用 CTRL+C 停止运行测试进程。

初始化前配置访问地址

如果需要配置域名访问，建议先配置好反向代理以及域名解析再进行初始化。如果通过 http://ip:端口号 的形式无法访问，请到服务器厂商后台将运行的端口号添加到安全组，如果服务器使用了 Linux 面板，请检查此 Linux 面板是否有还有安全组配置，需要同样将端口号添加到安全组。

激活许可证

可以参考许可证激活进行激活，社区版无需此步骤。

作为服务运行

下面将介绍如何将 Halo 作为服务运行，以实现在关闭 ssh 连接后，Halo 仍然可以正常运行。

此文档以 Systemd 为例，也可以参考：Installing Spring Boot Applications

切换账户

退出 halo 账户，登录到 root 账户

如果当前就是 root 账户，请略过此步骤。

exit

创建 halo.service 文件

vim /etc/systemd/system/halo.service

将以下内容复制到 halo.service 中，根据下面的配置说明进行配置。

/etc/systemd/system/halo.service

[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
StandardOutput=syslog
StandardError=inherit

[Install]
WantedBy=multi-user.target

JAR_PATH：Halo 运行包的绝对路径，例如 /home/halo/app/halo.jar，注意：此路径不支持 ~ 符号。
USER：运行 Halo 的系统用户，如果有按照上方教程创建新的用户来运行 Halo，修改为你创建的用户名称即可。反之请删除 User=USER。

确认 Java 路径与启动命令

请确保 /usr/bin/java 是正确无误的。建议将 ExecStart 中的命令复制出来运行一下，保证命令有效。如果指定了其他工作目录，请像上面一样改动。

配置完成之后，保存即可。

重新加载 systemd

systemctl daemon-reload

运行服务

systemctl start halo

在系统启动时启动服务

systemctl enable halo

最后，你可以通过下面的命令查看服务日志：

journalctl -n 20 -u halo

版本升级

备份数据

可以参考备份与恢复进行完整备份（可选，但推荐备份）。

停止 Halo 服务

service halo stop

下载新版本

下载新版本的 Halo 运行包，覆盖原有的运行包

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

Halo 运行包下载地址

以下是官方维护的下载地址：

启动 Halo 服务

service halo start

反向代理

你可以在下面的反向代理软件中任选一项，我们假设你已经安装好了其中一项，并对其的基本操作有一定了解。如果你对它们没有任何了解，可以参考我们更为详细的反向代理文档：

使用 Nginx Proxy Manager

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

使用 JAR 文件部署#

#依赖检查

#安装

#创建新的系统用户

#创建存放运行包的目录

#下载运行包

#创建 工作目录

#创建 Halo 配置文件

#测试运行 Halo

#测试访问

#激活许可证

#作为服务运行

#切换账户

#创建 halo.service 文件

#重新加载 systemd

#运行服务

#在系统启动时启动服务

#版本升级

#备份数据

#停止 Halo 服务

#下载新版本

#启动 Halo 服务

#反向代理

#Nginx

#Caddy 2