部署Halo项目问题及解决方案

1. JDK 版本兼容性问题

问题描述

Halo 不同版本对 JDK 要求不同，部署时可能因版本不匹配导致错误。

• Halo 2.21 及以上：要求 JDK 21。
• Halo 2.20 及以下：要求 JDK 17。

运行 halo.jar 时，若 Java 运行时环境（JRE）版本过低，会报错：

UnsupportedClassVersionError: run/halo/app/Application has been compiled by a more recent version of the Java Runtime (class file version 65.0), this version of the Java Runtime only recognizes class file versions up to 61.0

解决方案

• 确认 Halo 版本，安装对应 JDK 版本。
• 建议：
  • Halo 2.21+：安装 JDK 21。
  • Halo 2.20-：安装 JDK 17。

图例

2. OpenJDK 安装与环境变量配置问题

问题描述

• OpenJDK 17 可通过 apt 直接安装，而 OpenJDK 21 需添加第三方源或手动下载。
• 安装后需手动配置环境变量，否则无法正常使用。

解决方案

1. 安装 OpenJDK 21：
   • 添加第三方源（如 Oracle JDK 21 或 PPA）。
   • 下载并安装 OpenJDK 21。

2. 配置环境变量：

   # 编辑环境变量
   vim /etc/profile
   
   # 添加以下内容
   export JAVA_HOME=/usr/local/jdk21
   export PATH=$PATH:$JAVA_HOME/bin
   
   # 使配置生效
   source /etc/profile
   

3. 验证安装：

   java -version
   

图例

3. Halo 初始化无法连接 MySQL 数据库（配置文件路径问题）

问题描述

Halo 初始化时无法连接 MySQL 数据库，默认使用 H2 数据库。检查发现启动命令未指定配置文件路径。

解决方案

• 错误启动命令（未指定配置文件路径）：

  java -jar halo.jar
  

• 正确启动命令（指定配置文件路径）：

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

• 确保 $HOME/.halo2/ 目录下存在正确的 application.yml 配置文件。

图例

4. Halo 初始化无法连接 MySQL 数据库（配置文件内容问题）

问题描述

Halo 初始化时无法连接 MySQL 数据库，默认使用 H2 数据库。检查发现 application.yml 配置文件中的参数错误。

解决方案

• 编辑 $HOME/.halo2/application.yml，确保以下配置正确：

  server:
    port: 8090
  
  spring:
    r2dbc:
      url: r2dbc:mysql://192.168.0.113:3306/halo_db
      username: halo
      password: 12345678
    sql:
      init:
        mode: always
        platform: mysql
  
  halo:
    work-dir: ${user.home}/.halo2
    external-url: http://localhost:8090
    attachment:
      resource-mappings:
        - pathPattern: /upload/**
          locations:
            - migrate-from-1.x
  

• 注意：
  • 严格按照官方文档格式配置 r2dbc.url 和 sql.platform。
  • 检查 MySQL 连接参数（URL、用户名、密码），避免使用 root 用户。

图例

5. Halo systemd 服务启动失败

问题描述

使用 halo.service 启动 Halo 时，systemctl status halo.service 显示服务启动失败，主进程退出状态码为 203/EXEC，原因是服务文件中 ExecStart 的 Java 路径错误。

解决方案

1. 修改 systemd 服务文件：
   • 编辑 /etc/systemd/system/halo.service：

     [Service]
     ExecStart=/usr/local/jdk21/bin/java -jar /path/to/halo.jar --spring.config.additional-location=optional:file:$HOME/.halo2/
     

2. 重新加载并启动服务：

   sudo systemctl daemon-reload
   sudo systemctl restart halo.service
   sudo systemctl status halo.service
   

3. 验证 Java 路径：

   which java
   java -version
   

图例