mirror of
https://github.com/halo-dev/docs.git
synced 2025-10-21 02:04:01 +00:00
docs: update documentation for Halo 2.18 (#407)
Signed-off-by: Ryan Wang <i@ryanc.cc>
This commit is contained in:
Ryan Wang
84
versioned_docs/version-2.19/developer-guide/core/build.md
Normal file
84
versioned_docs/version-2.19/developer-guide/core/build.md
Normal file
@@ -0,0 +1,84 @@
|
||||
---
|
||||
title: 构建
|
||||
description: 构建为可执行 JAR 和 Docker 镜像的文档
|
||||
---
|
||||
|
||||
:::info
|
||||
在此之前，我们推荐你先阅读[《准备工作》](./prepare)，检查本地环境是否满足要求。
|
||||
:::
|
||||
|
||||
一般情况下，为了保证版本一致性和可维护性，我们并不推荐自行构建和二次开发。
|
||||
|
||||
## 克隆项目
|
||||
|
||||
如果你已经 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
|
||||
|
||||
# 切换到特定的分支或标签，请替换 ${branch_name}
|
||||
git checkout ${branch_name}
|
||||
```
|
||||
|
||||
## 构建 Fat Jar
|
||||
|
||||
构建之前需要修改 `gradle.properties` 中的 `version` 属性（推荐遵循 [SemVer 规范](https://semver.org/)），例如：`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 文件部署](../../getting-started/install/jar-file.md)。
|
||||
|
||||
## 构建 Docker 镜像
|
||||
|
||||
在此之前，请确认已经构建好了 Fat Jar。
|
||||
|
||||
```bash
|
||||
cd path/to/halo
|
||||
```
|
||||
|
||||
```bash
|
||||
# 请替换 ${tag_name}
|
||||
docker build -t halo-dev/halo:${tag_name} .
|
||||
```
|
||||
|
||||
```bash
|
||||
# 插件构建完成的版本
|
||||
docker images | grep halo
|
||||
```
|
||||
|
||||
最终部署文档可参考：[使用 Docker Compose 部署](../../getting-started/install/docker-compose.md)。
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: 代码风格
|
||||
description: 代码风格的相关配置说明
|
||||
---
|
||||
|
||||
Halo 添加了 checkstyle 插件，来保证每位提交者代码的风格保持一致，减少无效代码的修改。本篇文章主要讲解如何在 IDEA 中添加 CheckStyle 插件，并引入项目所提供的 checkstyle.xml 配置。
|
||||
|
||||
## 安装 CheckStyle-IDEA
|
||||
|
||||
- 进入 IDEA 插件市场。
|
||||
- 搜索 CheckStyle-IDEA，点击安装即可。
|
||||
|
||||
## 配置 CheckStyle
|
||||
|
||||
- 进入 CheckStyle 配置（File | Settings | Tools | Checkstyle）。
|
||||
- 选择 Checkstyle 版本：9.3（以文件 `application/build.gradle` 中指定的版本为准）。
|
||||
- 在配置文件中点击添加按钮，配置描述可随便填写（推荐 Halo Checks），选择 ./config/checkstyle/checkstyle.xml，点击下一步和完成。
|
||||
- 勾选刚刚创建的配置文件。
|
||||
|
||||
## 配置 Editor
|
||||
|
||||
- 进入编辑器配置（File | Settings | Editor | Code Style）
|
||||
|
||||
- 导入 checkstyle.xm 配置：
|
||||
|
||||
|
||||
|
||||
- 选择 `./config/checkstyle/checkstyle.xml` 配置文件，点击确定即可。
|
||||
|
||||
至此，有关代码风格检查工具和格式化配置已经完成。
|
||||
25
versioned_docs/version-2.19/developer-guide/core/prepare.md
Normal file
25
versioned_docs/version-2.19/developer-guide/core/prepare.md
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: 准备工作
|
||||
description: 开发环境的准备工作
|
||||
---
|
||||
|
||||
## 环境要求
|
||||
|
||||
- [OpenJDK 17 LTS](https://github.com/openjdk/jdk)
|
||||
- [Node.js 20 LTS](https://nodejs.org)
|
||||
- [pnpm 9](https://pnpm.io/)
|
||||
- [IntelliJ IDEA](https://www.jetbrains.com/idea/)
|
||||
- [Git](https://git-scm.com/)
|
||||
- [Docker](https://www.docker.com/)（可选）
|
||||
|
||||
## 名词解释
|
||||
|
||||
### 工作目录
|
||||
|
||||
指 Halo 所依赖的工作目录，在 Halo 运行的时候会在系统当前用户目录下产生一个 halo-next 的文件夹，绝对路径为 ~/halo-next。里面通常包含下列目录或文件：
|
||||
|
||||
1. `db`：存放 H2 Database 的物理文件，如果你使用其他数据库，那么不会存在这个目录。
|
||||
2. `themes`：里面包含用户所安装的主题。
|
||||
2. `plugins`：里面包含用户所安装的插件。
|
||||
5. `attachments`：附件目录。
|
||||
4. `logs`：运行日志目录。
|
||||
122
versioned_docs/version-2.19/developer-guide/core/run.md
Normal file
122
versioned_docs/version-2.19/developer-guide/core/run.md
Normal file
@@ -0,0 +1,122 @@
|
||||
---
|
||||
title: 开发环境运行
|
||||
description: 开发环境运行的指南
|
||||
---
|
||||
|
||||
:::info
|
||||
在此之前，我们推荐你先阅读[《准备工作》](./prepare)，检查本地环境是否满足要求。
|
||||
:::
|
||||
|
||||
## 项目结构说明
|
||||
|
||||
目前如果需要完整的运行 Halo，总共需要三个部分：
|
||||
|
||||
1. Halo 主项目（[halo-dev/halo](https://github.com/halo-dev/halo)）
|
||||
2. UI，包括 Console 控制台和 UC 个人中心（托管在 Halo 主项目）
|
||||
3. 主题（Halo 主项目内已包含默认主题）
|
||||
|
||||
:::info 说明
|
||||
从 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/
|
||||
```
|
||||
|
||||
:::info 提示
|
||||
请不要直接使用 UI 的运行端口（3000 / 4000）访问，会因为跨域问题导致无法正常登录，建议按照后续的步骤以 dev 的配置文件运行 Halo，在 dev 的配置文件中，我们默认代理了 UI 页面的访问地址，所以后续访问 UI 页面使用 `http://localhost:8090/console` 和 `http://localhost:8090/uc` 访问即可，代理的相关配置：
|
||||
|
||||
```yaml
|
||||
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](http://localhost:8090)
|
||||
2. Console 控制台：[http://localhost:8090/console](http://localhost:8090/console)
|
||||
3. UC 个人中心：[http://localhost:8090/uc](http://localhost:8090/uc)
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: 系统结构
|
||||
description: Halo 项目的构成
|
||||
---
|
||||
|
||||
[Halo](https://github.com/halo-dev/halo) 博客系统分为以下四个部分：
|
||||
|
||||
| 项目名称 | 简介 |
|
||||
| :------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |
|
||||
| [halo](https://github.com/halo-dev/halo) | 提供整个系统的服务，采用 [Spring Boot](https://spring.io/) 开发 |
|
||||
| [halo-admin](https://github.com/halo-dev/halo-admin) | 负责后台管理的渲染，采用 [Vue](https://vuejs.org/) 开发，已集成在 Halo 运行包内，无需独立部署。 |
|
||||
| [halo-comment](https://github.com/halo-dev/halo-comment) | 评论插件，采用 [Vue](https://vuejs.org/) 开发，在主题中运行方式引入构建好的 `JavaScript` 文件即可 |
|
||||
| [halo-theme-\*](https://github.com/halo-dev) | 主题项目集，采用 [FreeMarker](https://freemarker.apache.org/) 模板引擎编写，需要包含一些特殊的配置才能够被 halo 所使用 |
|
||||
|
||||
## 自定义配置
|
||||
|
||||
> 为什么要提前讲自定义配置呢？是因为在这里让大家了解到 `Halo` 的`配置方式`，以及`配置优先级`，不至于未来运行项目的时候不知道如何优雅地修改配置。
|
||||
|
||||
`Halo` 配置目录优先级如下（从上到下优先级越来越小，上层的配置将会覆盖下层）:
|
||||
|
||||
- `Halo` 自定义配置
|
||||
- file:~/.halo/
|
||||
- file:~/.halo-dev/
|
||||
- `Spring Boot` 默认配置
|
||||
- file:./config/
|
||||
- file:./
|
||||
- classpath:/config/
|
||||
- classpath:/
|
||||
|
||||
> 参考: [Application Property Files](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html#boot-features-external-config-application-property-files)
|
||||
|
||||
在开发的时候，希望大家能够在 `~/halo-dev/application.yml` 中进行添加自定义配置。当然后面也会讲到如何用`运行参数` 和 `VM options` 进行控制配置，届时可根据具体情况进行选择。
|
||||
|
||||
:::warning
|
||||
开发的时候，我们不建议直接更改`项目源码`中的所包含的`配置文件`，包括 `application.yml`、`application-dev.yml`、`application-test.yml` 和 `application-user.yml`。
|
||||
:::
|
||||
Reference in New Issue
Block a user