Halo 开发者指南——项目运行、构建

准备工作

环境要求

名词解释

工作目录

指 Halo 所依赖的工作目录,在 Halo 运行的时候会在系统当前用户目录下产生一个 halo-next 的文件夹,绝对路径为 ~/halo-next。里面通常包含下列目录或文件:

  1. db:存放 H2 Database 的物理文件,如果你使用其他数据库,那么不会存在这个目录。
  2. themes:里面包含用户所安装的主题。
  3. plugins:里面包含用户所安装的插件。
  4. attachments:附件目录。
  5. logs:运行日志目录。

开发环境运行

项目结构说明

目前如果需要完整的运行 Halo,总共需要三个部分:

  1. Halo 主项目(halo-dev/halo
  2. UI,包括 Console 控制台和 UC 个人中心(托管在 Halo 主项目)
  3. 主题(Halo 主项目内已包含默认主题)

说明

从 Halo 2.11 开始,Halo 项目的 ui​ 目录同时包含了 Console(管理控制台)和 UC(个人中心),以下统称为 UI。

当前 Halo 主项目并不会将 UI 的构建资源托管到 Git 版本控制,所以在开发环境是需要同时运行 UI 项目的。当然,在我们的最终发布版本的时候会在 CI 中自动构建 UI 到 Halo 主项目。

克隆项目

如果你已经 Fork 了相关仓库,请将以下命令中的 halo-dev​ 替换为你的 GitHub 用户名。

bash 复制代码
git clone https://github.com/halo-dev/halo

# 或者使用 ssh 的方式 clone(推荐)
# git clone git@github.com:halo-dev/halo.git

# 或者使用 GitHub CLI 克隆(推荐)
# gh repo clone halo-dev/halo 

# 或者使用 GitHub CLI Fork(推荐)
# gh repo fork halo-dev/halo

运行 UI 服务

bash 复制代码
cd path/to/halo/ui
pnpm install
pnpm build:packages
pnpm dev

最终控制台打印了如下信息即代表运行正常:

bash 复制代码
VITE v4.2.3  ready in 638 ms

# Console 控制台服务
➜  Local:   http://localhost:3000/console/

# UC 个人中心服务
➜  Local:   http://localhost:4000/uc/

请不要直接使用 UI 的运行端口(3000 / 4000)访问,会因为跨域问题导致无法正常登录,建议按照后续的步骤以 dev 的配置文件运行 Halo,在 dev 的配置文件中,我们默认代理了 UI 页面的访问地址,所以后续访问 UI 页面使用 http://localhost:8090/console​ 和 http://localhost:8090/uc​ 访问即可,代理的相关配置:

yml 复制代码
halo:
  console:
    proxy:
      endpoint: http://localhost:3000/
      enabled: true
  uc:
    proxy:
      endpoint: http://localhost:4000/
      enabled: true

运行 Halo

  1. 在 IntelliJ IDEA 中打开 Halo 项目,等待 Gradle 初始化和依赖下载完成。

  2. 下载预设插件(可选)

    bash 复制代码
    # Windows
    ./gradlew.bat downloadPluginPresets
    
    # macOS / Linux
    ./gradlew downloadPluginPresets
  3. 修改 IntelliJ IDEA 的运行配置

    • Windows
      将 Active Profiles 改为 dev,win,如图所示:
    • macOS / Linux
      将 Active Profiles 改为 dev,如图所示:
  4. 点击 IntelliJ IDEA 的运行按钮,等待项目启动完成。

  5. 或者使用 Gradle 运行

    bash 复制代码
    # macOS / Linux
    ./gradlew bootRun --args="--spring.profiles.active=dev"
    
    # Windows
    gradlew.bat bootRun --args="--spring.profiles.active=dev,win"
  6. 最终提供以下访问地址:

    1. 网站首页:http://localhost:8090
    2. Console 控制台:http://localhost:8090/console
    3. UC 个人中心:http://localhost:8090/uc

构建

一般情况下,为了保证版本一致性和可维护性,我们并不推荐自行构建和二次开发。

构建 Docker 镜像

一般情况下,为了保证版本一致性和可维护性,我们并不推荐自行构建和二次开发。

克隆项目

如果你已经 Fork 了相关仓库,请将以下命令中的 halo-dev​ 替换为你的 GitHub 用户名。

bash 复制代码
git clone https://github.com/halo-dev/halo

# 或者使用 ssh 的方式 clone(推荐)
# git clone git@github.com:halo-dev/halo.git

# 或者使用 GitHub CLI 克隆(推荐)
# gh repo clone halo-dev/halo 

# 或者使用 GitHub CLI Fork(推荐)
# gh repo fork halo-dev/halo

cd halo

# 切换到特定的分支或标签,请替换 <span class="katex--inline"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>b</mi><mi>r</mi><mi>a</mi><mi>n</mi><mi>c</mi><msub><mi>h</mi><mi>n</mi></msub><mi>a</mi><mi>m</mi><mi>e</mi></mrow><mi>g</mi><mi>i</mi><mi>t</mi><mi>c</mi><mi>h</mi><mi>e</mi><mi>c</mi><mi>k</mi><mi>o</mi><mi>u</mi><mi>t</mi></mrow><annotation encoding="application/x-tex">{branch_name}
git checkout </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"><span class="mord"><span class="mord mathnormal">b</span><span class="mord mathnormal" style="margin-right:0.02778em;">r</span><span class="mord mathnormal">an</span><span class="mord mathnormal">c</span><span class="mord"><span class="mord mathnormal">h</span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:0.1514em;"><span style="top:-2.55em;margin-left:0em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"><span class="sizing reset-size6 size3 mtight"><span class="mord mathnormal mtight">n</span></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.15em;"><span></span></span></span></span></span><span class="mord mathnormal">am</span><span class="mord mathnormal">e</span></span><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="mord mathnormal">i</span><span class="mord mathnormal">t</span><span class="mord mathnormal">c</span><span class="mord mathnormal">h</span><span class="mord mathnormal">ec</span><span class="mord mathnormal" style="margin-right:0.03148em;">k</span><span class="mord mathnormal">o</span><span class="mord mathnormal">u</span><span class="mord mathnormal">t</span></span></span></span></span>{branch_name}
</span></span></span>

构建 Fat Jar

构建之前需要修改 gradle.properties​ 中的 version​ 属性(推荐遵循 SemVer 规范),例如:version=2.19.0

bash 复制代码
cd path/to/halo

下载预设插件(可选):

bash 复制代码
# Windows
./gradlew.bat downloadPluginPresets

# macOS / Linux
./gradlew downloadPluginPresets

构建:

bash 复制代码
# Windows
./gradlew.bat clean build -x check

# macOS / Linux
./gradlew clean build -x check

构建完成之后,在 Halo 项目下产生的 application/build/libs/halo-${version}.jar​ 即为构建完成的文件。

最终部署文档可参考:使用 JAR 文件部署

构建 Docker 镜像

在此之前,请确认已经构建好了 Fat Jar。

bash 复制代码
cd path/to/halo
bash 复制代码
# 请替换 <span class="katex--inline"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>t</mi><mi>a</mi><msub><mi>g</mi><mi>n</mi></msub><mi>a</mi><mi>m</mi><mi>e</mi></mrow><mi>d</mi><mi>o</mi><mi>c</mi><mi>k</mi><mi>e</mi><mi>r</mi><mi>b</mi><mi>u</mi><mi>i</mi><mi>l</mi><mi>d</mi><mo>−</mo><mi>t</mi><mi>h</mi><mi>a</mi><mi>l</mi><mi>o</mi><mo>−</mo><mi>d</mi><mi>e</mi><mi>v</mi><mi mathvariant="normal">/</mi><mi>h</mi><mi>a</mi><mi>l</mi><mi>o</mi><mo>:</mo></mrow><annotation encoding="application/x-tex">{tag_name}
docker build -t halo-dev/halo:</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"><span class="mord"><span class="mord mathnormal">t</span><span class="mord mathnormal">a</span><span class="mord"><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:0.1514em;"><span style="top:-2.55em;margin-left:-0.0359em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"><span class="sizing reset-size6 size3 mtight"><span class="mord mathnormal mtight">n</span></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.15em;"><span></span></span></span></span></span><span class="mord mathnormal">am</span><span class="mord mathnormal">e</span></span><span class="mord mathnormal">d</span><span class="mord mathnormal">oc</span><span class="mord mathnormal" style="margin-right:0.03148em;">k</span><span class="mord mathnormal" style="margin-right:0.02778em;">er</span><span class="mord mathnormal">b</span><span class="mord mathnormal">u</span><span class="mord mathnormal">i</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">d</span><span class="mspace" style="margin-right:0.2222em;"><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="base"><span class="strut" style="height:0.7778em;vertical-align:-0.0833em;"><span class="mord mathnormal">t</span><span class="mord mathnormal">ha</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">o</span><span class="mspace" style="margin-right:0.2222em;"><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"><span class="mord mathnormal">d</span><span class="mord mathnormal">e</span><span class="mord mathnormal" style="margin-right:0.03588em;">v</span><span class="mord">/</span><span class="mord mathnormal">ha</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">o</span><span class="mspace" style="margin-right:0.2778em;"><span class="mrel">:</span></span></span></span></span>{tag_name} .
</span></span></span></span></span></span></span></span></span></span>
bash 复制代码
# 插件构建完成的版本
docker images | grep halo

最终部署文档可参考:使用 Docker Compose 部署

在此之前,请确认已经构建好了 Fat Jar。

powershell 复制代码
cd path/to/halo
powershell 复制代码
# 请替换 <span class="katex--inline"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>t</mi><mi>a</mi><msub><mi>g</mi><mi>n</mi></msub><mi>a</mi><mi>m</mi><mi>e</mi></mrow><mi>d</mi><mi>o</mi><mi>c</mi><mi>k</mi><mi>e</mi><mi>r</mi><mi>b</mi><mi>u</mi><mi>i</mi><mi>l</mi><mi>d</mi><mo>−</mo><mi>t</mi><mi>h</mi><mi>a</mi><mi>l</mi><mi>o</mi><mo>−</mo><mi>d</mi><mi>e</mi><mi>v</mi><mi mathvariant="normal">/</mi><mi>h</mi><mi>a</mi><mi>l</mi><mi>o</mi><mo>:</mo></mrow><annotation encoding="application/x-tex">{tag_name}
docker build -t halo-dev/halo:</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"><span class="mord"><span class="mord mathnormal">t</span><span class="mord mathnormal">a</span><span class="mord"><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:0.1514em;"><span style="top:-2.55em;margin-left:-0.0359em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"><span class="sizing reset-size6 size3 mtight"><span class="mord mathnormal mtight">n</span></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.15em;"><span></span></span></span></span></span><span class="mord mathnormal">am</span><span class="mord mathnormal">e</span></span><span class="mord mathnormal">d</span><span class="mord mathnormal">oc</span><span class="mord mathnormal" style="margin-right:0.03148em;">k</span><span class="mord mathnormal" style="margin-right:0.02778em;">er</span><span class="mord mathnormal">b</span><span class="mord mathnormal">u</span><span class="mord mathnormal">i</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">d</span><span class="mspace" style="margin-right:0.2222em;"><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="base"><span class="strut" style="height:0.7778em;vertical-align:-0.0833em;"><span class="mord mathnormal">t</span><span class="mord mathnormal">ha</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">o</span><span class="mspace" style="margin-right:0.2222em;"><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"><span class="mord mathnormal">d</span><span class="mord mathnormal">e</span><span class="mord mathnormal" style="margin-right:0.03588em;">v</span><span class="mord">/</span><span class="mord mathnormal">ha</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">o</span><span class="mspace" style="margin-right:0.2778em;"><span class="mrel">:</span></span></span></span></span>{tag_name} .
</span></span></span></span></span></span></span></span></span></span>
powershell 复制代码
# 插件构建完成的版本
docker images | grep halo

最终部署文档可参考:使用 Docker Compose 部署


原文链接:https://docs.halo.run/category/系统开发

相关推荐
川石课堂软件测试38 分钟前
性能测试|docker容器下搭建JMeter+Grafana+Influxdb监控可视化平台
运维·javascript·深度学习·jmeter·docker·容器·grafana
stewie61 小时前
在IDEA中使用Git
java·git
追风林8 小时前
mac 本地docker-mysql主从复制部署
mysql·macos·docker
前端青山8 小时前
Node.js-增强 API 安全性和性能优化
开发语言·前端·javascript·性能优化·前端框架·node.js
晓理紫10 小时前
使用git lfs向huggingface提交较大的数据或者权重
git
城南vision10 小时前
Docker学习—Docker核心概念总结
java·学习·docker
wclass-zhengge10 小时前
Docker篇(Docker Compose)
运维·docker·容器
GDAL11 小时前
npm入门教程1:npm简介
前端·npm·node.js
我不是程序猿儿11 小时前
【GIT】sourceTree的“当前分支“,“合并分支“与“检出分支的区别
git
梦魇梦狸º13 小时前
腾讯轻量云服务器docker拉取不到镜像的问题:拉取超时
docker·容器·github