docs: update documentation for Halo 2.6 (#222)

为 Halo 2.6 更新文档。 /kind documentation ```release-note None ```
2025-10-22 19:04:55 +00:00 · 2023-06-01 15:43:14 +08:00
parent 4b934c0ace
commit 5d74edea8f
109 changed files with 11048 additions and 2131 deletions
--- a/versioned_docs/version-2.6/developer-guide/core/build.md
+++ b/versioned_docs/version-2.6/developer-guide/core/build.md
@@ -0,0 +1,99 @@
+---
+title: 构建
+description: 构建为可执行 JAR 和 Docker 镜像的文档
+---
+
+:::info
+在此之前，我们推荐你先阅读[《准备工作》](./prepare)，检查本地环境是否满足要求。
+:::
+
+一般情况下，为了保证版本一致性和可维护性，我们并不推荐自行构建和二次开发。但考虑到我们目前仅提供 Docker 镜像的发行版本，不再提供可执行 JAR 的发行版本，因此我们提供了构建的文档，以供用户自行构建。
+
+## 克隆项目
+
+如果你已经 fork 了相关仓库，请将以下命令中的 halo-dev 替换为你的 GitHub 用户名。
+
+```bash
+git clone https://github.com/halo-dev/halo
+
+# 或者使用 ssh 的方式 clone（推荐）
+
+git clone git@github.com:halo-dev/halo.git
+
+# 切换到最新的 tag
+
+cd halo
+
+git checkout v2.4.0
+```
+
+:::tip
+请务必按照以上要求切换到最新的 tag，而不是直接使用 main 分支构建，main 分支是我们的开发分支。此文档以 `2.6.0` 为例，查看最新的 tag 可使用 `git tag --column` 查看。
+:::
+
+:::warning
+从 2.4.0 开始，Console 项目已经合并到 Halo 主项目，所以不再需要单独克隆 Console 的项目仓库。
+
+详情可查阅：<https://github.com/halo-dev/halo/issues/3393>
+:::
+
+## 构建 Console
+
+```bash
+cd path/to/halo
+```
+
+Linux / macOS 平台：
+
+```bash
+make -C console build
+```
+
+Windows 平台：
+
+```bash
+cd console
+
+pnpm install
+
+pnpm build:packages
+
+pnpm build
+```
+
+## 构建 Fat Jar
+
+构建之前需要修改 `gradle.properties` 中的 `version` 为当前 tag 的版本号，如：`version=2.6.0`
+
+```bash
+cd path/to/halo
+```
+
+```bash
+# Windows
+./gradlew.bat clean build -x check
+
+# macOS / Linux
+./gradlew clean build -x check
+```
+
+构建完成之后，在 halo 项目下产生的 `application/build/libs/halo-2.6.0.jar` 即为构建完成的文件。
+
+## 构建 Docker 镜像
+
+在进行之前，请确保已经完成上述操作，最终需要确认在 halo 项目的 `application/build/libs/` 目录已经包含了 `halo-2.6.0.jar` 文件。
+
+```bash
+cd path/to/halo
+```
+
+```bash
+docker build -t halo-dev/halo:2.6.0 .
+```
+
+```bash
+# 插件构建完成的版本
+docker images | grep halo
+```
+
+最终部署文档可参考：[使用 Docker Compose 部署](./docker-compose)
--- a/versioned_docs/version-2.6/developer-guide/core/code-style.md
+++ b/versioned_docs/version-2.6/developer-guide/core/code-style.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 版本：8.39。
+- 在配置文件中点击添加按钮，配置描述可随便填写（推荐 Halo Checks），选择 ./config/checkstyle/checkstyle.xml，点击下一步和完成；
+- 勾选刚刚创建的配置文件。
+
+## 配置 Editor
+
+- 进入编辑器配置（File | Settings | Editor | Code Style）
+
+- 导入 checkstyle.xm 配置：
+
+![image.png](https://halo.run/upload/2020/2/image-0c7a018e73f74634a534fa3ba8806628.png)
+
+- 选择 `./config/checkstyle/checkstyle.xml` 配置文件，点击确定即可。
+
+至此，有关代码风格检查工具和格式化配置已经完成。
--- a/versioned_docs/version-2.6/developer-guide/core/prepare.md
+++ b/versioned_docs/version-2.6/developer-guide/core/prepare.md
@@ -0,0 +1,25 @@
+---
+title: 准备工作
+description: 开发环境的准备工作
+---
+
+## 环境要求
+
+- [OpenJDK 17 LTS](https://github.com/openjdk/jdk)
+- [Node.js 18 LTS](https://nodejs.org)
+- [pnpm 7](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`：运行日志目录。
--- a/versioned_docs/version-2.6/developer-guide/core/run.md
+++ b/versioned_docs/version-2.6/developer-guide/core/run.md
@@ -0,0 +1,122 @@
+---
+title: 开发环境运行
+description: 开发环境运行的指南
+---
+
+:::info
+在此之前，我们推荐你先阅读[《准备工作》](./prepare)，检查本地环境是否满足要求。
+:::
+
+## 项目结构说明
+
+目前如果需要完整的运行 Halo，总共需要三个部分：
+
+1. Halo 主项目（[halo-dev/halo](https://github.com/halo-dev/halo)）
+2. Console 控制台（托管在 Halo 主项目）
+3. 主题（Halo 主项目内已包含默认主题）
+
+:::info 说明
+当前 Halo 主项目并不会将 Console 的构建资源托管到 Git 版本控制，所以在开发环境是需要同时运行 Console 项目的。当然，在我们的最终发布版本的时候会在 CI 中自动构建 Console 到 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
+```
+
+:::warning
+从 2.4.0 开始，Console 项目已经合并到 Halo 主项目，所以不再需要单独克隆 Console 的项目仓库。
+
+详情可查阅：<https://github.com/halo-dev/halo/issues/3393>
+:::
+
+## 运行 Console
+
+```bash
+cd path/to/halo
+```
+
+Linux / macOS 平台：
+
+```bash
+make -C console dev
+```
+
+Windows 平台：
+
+```bash
+cd console
+
+pnpm install
+
+pnpm build:packages
+
+pnpm dev
+```
+
+最终控制台打印了如下信息即代表运行正常：
+
+```bash
+VITE v3.1.6  ready in 638 ms
+
+➜  Local:   http://localhost:3000/console/
+```
+
+:::info 提示
+请不要直接使用 Console 的运行端口（3000）访问，会因为跨域问题导致无法正常登录，建议按照后续的步骤以 dev 的配置文件运行 Halo，在 dev 的配置文件中，我们默认代理了 Console 的访问地址，所以后续访问 Console 使用 `http://localhost:8090/console` 访问即可，代理的相关配置：
+
+```yaml
+halo:
+  console:
+    proxy:
+      endpoint: http://localhost:3000/
+      enabled: true
+```
+
+:::
+
+## 运行 Halo
+
+1. 在 IntelliJ IDEA 中打开 Halo 项目，等待 Gradle 初始化和依赖下载完成。
+
+2. 修改 IntelliJ IDEA 的运行配置
+    1. macOS / Linux
+    将 Active Profiles 改为 `dev`，如图所示：
+    ![IntelliJ IDEA Profiles](/img/developer-run/IntelliJ-IDEA-Profiles-MacOs.png)
+    2. Windows
+    将 Active Profiles 改为 `dev,win`，如图所示：
+    ![IntelliJ IDEA Profiles](/img/developer-run/IntelliJ-IDEA-Profiles-Win.png)
+
+3. 点击 IntelliJ IDEA 的运行按钮，等待项目启动完成。
+
+4. 或者使用 Gradle 运行
+
+    ```bash
+    # macOS / Linux
+    ./gradlew bootRun --args="--spring.profiles.active=dev"
+
+    # Windows
+    gradlew.bat bootRun --args="--spring.profiles.active=dev,win"
+    ```
+
+5. 最终访问 `http://localhost:8090/console` 即可进入控制台。访问 `http://localhost:8090` 即可进入站点首页。
+
+:::info
+开发环境下，超级管理员的默认用户名为 `admin`，默认密码为 `admin`。也可通过修改 `application-dev.yaml` 配置文件进行更改：
+
+```yaml
+halo:
+  security:
+    initializer:
+      super-admin-username: admin
+      super-admin-password: admin
+```
+
+:::
--- a/versioned_docs/version-2.6/developer-guide/core/structure.md
+++ b/versioned_docs/version-2.6/developer-guide/core/structure.md
@@ -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`。
+:::