Skip to content

Commit 61776d2

Browse files
ruibabyruibaby
committed
docs: add Halo configuration documentation
Signed-off-by: Ryan Wang <[email protected]>
1 parent 32c8947 commit 61776d2

File tree

5 files changed

+135
-5
lines changed

5 files changed

+135
-5
lines changed

‎.vscode/settings.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"[markdown]": {
3-
"editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
3+
"editor.defaultFormatter": "yzhang.markdown-all-in-one"
44
},
55
"i18n-ally.localesPaths": [
66
"i18n"

‎docs/getting-started/install/config.md

+129
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
title: 配置说明
3+
---
4+
5+
在前面的部署文档中，为了保证部署流程的简洁，只说明了运行所必须的配置，但除了运行之外，Halo 还提供了不少其他的配置以及我们所使用的 Web 框架的配置，这个文档我们将详细介绍 Halo 的完整配置。
6+
7+
## 配置方式
8+
9+
Halo 支持通过多种方式进行配置，目前 [Docker Compose 部署文档](./docker-compose.md) 的示例是通过运行参数配置，[JAR 文件部署方式](./jar-file.md) 是通过配置文件进行配置。
10+
11+
### 通过运行参数
12+
13+
通常我们在使用 Docker Compose 部署的时候推荐使用这种方式进行配置，配置方式为在 Docker Compose 配置文件的 `command` 添加对应的配置条目即可，比如：
14+
15+
```yaml {5-10}
16+
services:
17+
halo:
18+
image: registry.fit2cloud.com/halo/halo:2.20
19+
...
20+
command:
21+
- --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo
22+
- --spring.r2dbc.username=halo
23+
- --spring.r2dbc.password=openpostgresql
24+
- --spring.sql.init.platform=postgresql
25+
- --halo.external-url=http://localhost:8090/
26+
```
27+
28+
### 通过配置文件
29+
30+
通常我们在使用 JAR 文件部署的时候更推荐使用这种方式进行配置，配置文件名称为 `application.yaml`，并且需要在运行的时候通过 `--spring.config.additional-location` 参数指定配置文件存放的目录，运行示例：
31+
32+
```bash
33+
java -jar halo.jar --spring.config.additional-location=optional:file:$HOME/.halo2/
34+
```
35+
36+
配置示例：
37+
38+
```yaml title="~/.halo2/application.yaml"
39+
spring:
40+
r2dbc:
41+
url: r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE
42+
username: admin
43+
password: 123456
44+
sql:
45+
init:
46+
mode: always
47+
platform: h2
48+
```
49+
50+
:::info
51+
完整的 JAR 文件部署文档可查阅：[使用 JAR 文件部署](./jar-file.md)
52+
:::
53+
54+
当然，使用 Docker Compose 部署同样支持通过这种方式配置，只需要将 `application.yaml` 放在工作目录的挂载目录即可，示例：
55+
56+
```bash
57+
❯ tree
58+
.
59+
├── docker-compose.yaml
60+
└── halo2
61+
└── application.yaml
62+
63+
2 directories, 2 files
64+
```
65+
66+
其中，`docker-compose.yaml` 的 Halo 服务的 `volumes` 应该包含 `./halo2:/root/.halo2`。
67+
68+
## 配置列表
69+
70+
### Halo 独有配置
71+
72+
通常用于生产环境的配置：
73+
74+
| 配置路径 | 说明 | 生产环境默认值 |
75+
| -------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------- |
76+
| `halo.work-dir` | Halo [工作目录](../prepare.md#工作目录)，通常不建议修改 | `${user.home}/.halo2` |
77+
| `halo.external-url` | 网站的实际访问地址，如：`https://www.halo.run` | `http://localhost:8090` |
78+
| `halo.use-absolute-permalink` | 永久链接是否生成为绝对地址，设置为 `true` 时，请确保正确配置了 `halo.external-url` | `false` |
79+
| `halo.security.frame-options.disabled` | 是否允许网站通过 iframe 嵌入 | `false` |
80+
| `halo.security.frame-options.mode` | iframe 嵌入模式，默认为同源 | `SAMEORIGIN` |
81+
| `halo.security.referrer-options.policy` | | `strict-origin-when-cross-origin` |
82+
| `halo.security.remember-me.token-validity` | 保持登录回话的有效期，默认为 14 天（14d） | `14d` |
83+
| `halo.security.basic-auth.disabled` | 是否开启 API 的 Basic Auth 认证 | `true` |
84+
| `halo.security.two-factor-auth.disabled` | 禁用系统全局的两步验证 | `false` |
85+
| `halo.attachment.resource-mappings[0].pathPattern` | | |
86+
| `halo.attachment.resource-mappings[0].locations` | | |
87+
88+
通常用于开发环境的配置：
89+
90+
| 配置路径 | 说明 | 默认值 |
91+
| ----------------------------- | --------------------------- | ------ |
92+
| `halo.console.proxy.endpoint` | 开发环境的 Console 代理地址 | -- |
93+
| `halo.console.proxy.enabled` | 是否启用 Console 代理地址 | -- |
94+
| `halo.uc.proxy.endpoint` | 开发环境的 UC 代理地址 | -- |
95+
| `halo.uc.proxy.enabled` | 是否启用 UC 代理地址 | -- |
96+
| `halo.plugin.runtime-mode` | 插件的运行模式 | -- |
97+
98+
### Web 框架本身的配置
99+
100+
Halo 使用了 [Spring Boot](https://docs.spring.io/spring-boot/) 和 [Spring WebFlux](https://docs.spring.io/spring-framework/reference/web/webflux.html)，完整的配置可查阅：[Common Application Properties](https://docs.spring.io/spring-boot/appendix/application-properties/index.html#appendix.application-properties.core)，以下将列出关于 Halo 常用的配置：
101+
102+
Web 服务相关：
103+
104+
| 配置路径 | 说明 | 默认值 |
105+
| ----------------------------------------------------------- | ------------------ | ------- |
106+
| `server.port` | Web 服务端口 | `8090` |
107+
| `server.compression.enabled` | 是否开启 gzip 压缩 | `true` |
108+
| `spring.web.resources.cache.cachecontrol.max-age` | | `365d` |
109+
| `spring.web.resources.cache.cachecontrol.no-cache` | | `false` |
110+
| `spring.web.resources.cache.cachecontrol.use-last-modified` | | `true` |
111+
| `spring.thymeleaf.cache` | | `true` |
112+
113+
数据库相关：
114+
115+
| 配置路径 | 说明 | 默认值 |
116+
| -------------------------- | ----------------------------------------------------------- | ------ |
117+
| `spring.r2dbc.url` | 数据库连接地址，详细可查阅下方的 `数据库配置` | -- |
118+
| `spring.r2dbc.username` | 数据库用户名 | -- |
119+
| `spring.r2dbc.password` | 数据库密码 | -- |
120+
| `spring.sql.init.platform` | 数据库平台名称，支持 `postgresql`、`mysql`、`mariadb`、`h2` | -- |
121+
122+
数据库配置：
123+
124+
| 链接方式 | 链接地址格式 | `spring.sql.init.platform` |
125+
| ----------- | ---------------------------------------------------------------------------------- | -------------------------- |
126+
| PostgreSQL | `r2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}` | postgresql |
127+
| MySQL | `r2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}` | mysql |
128+
| MariaDB | `r2dbc:pool:mariadb://{HOST}:{PORT}/{DATABASE}` | mariadb |
129+
| H2 Database | `r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE` |

‎docs/getting-started/install/offline.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: 离线环境部署
3-
description: 离线环境部署
2+
title: 使用离线包部署
3+
description: 使用离线包在离线环境部署
44
---
55

66
import DockerArgs from "./slots/_docker-args.md"

‎sidebars.js

+1
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ module.exports = {
3939
"getting-started/install/podman",
4040
"getting-started/install/jar-file",
4141
"getting-started/install/offline",
42+
"getting-started/install/config",
4243
{
4344
type: "category",
4445
label: "云平台",

‎versioned_docs/version-2.20/getting-started/install/offline.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: 离线环境部署
3-
description: 离线环境部署
2+
title: 使用离线包部署
3+
description: 使用离线包在离线环境部署
44
---
55

66
import DockerArgs from "./slots/_docker-args.md"

0 commit comments

Comments
 (0)