diff --git a/.vscode/settings.json b/.vscode/settings.json index f0d31a08..ad67b6c8 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,6 +1,6 @@ { "[markdown]": { - "editor.defaultFormatter": "DavidAnson.vscode-markdownlint" + "editor.defaultFormatter": "yzhang.markdown-all-in-one" }, "i18n-ally.localesPaths": [ "i18n" diff --git a/docs/getting-started/install/config.md b/docs/getting-started/install/config.md new file mode 100644 index 00000000..46cd00f6 --- /dev/null +++ b/docs/getting-started/install/config.md @@ -0,0 +1,130 @@ +--- +title: 配置说明 +description: Halo 的运行配置说明文档 +--- + +在前面的部署文档中,为了保证部署流程的简洁,只说明了运行所必须的配置,但除了运行之外,Halo 还提供了不少其他的配置以及我们所使用的 Web 框架的配置,这个文档我们将详细介绍 Halo 的完整配置。 + +## 配置方式 + +Halo 支持通过多种方式进行配置,目前 [Docker Compose 部署文档](./docker-compose.md) 的示例是通过运行参数配置,[JAR 文件部署方式](./jar-file.md) 是通过配置文件进行配置。 + +### 通过运行参数 + +通常我们在使用 Docker Compose 部署的时候推荐使用这种方式进行配置,配置方式为在 Docker Compose 配置文件的 `command` 添加对应的配置条目即可,比如: + +```yaml {5-10} +services: + halo: + image: registry.fit2cloud.com/halo/halo:2.20 + ... + command: + - --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo + - --spring.r2dbc.username=halo + - --spring.r2dbc.password=openpostgresql + - --spring.sql.init.platform=postgresql + - --halo.external-url=http://localhost:8090/ +``` + +### 通过配置文件 + +通常我们在使用 JAR 文件部署的时候更推荐使用这种方式进行配置,配置文件名称为 `application.yaml`,并且需要在运行的时候通过 `--spring.config.additional-location` 参数指定配置文件存放的目录,运行示例: + +```bash +java -jar halo.jar --spring.config.additional-location=optional:file:$HOME/.halo2/ +``` + +配置示例: + +```yaml title="~/.halo2/application.yaml" +spring: + r2dbc: + url: r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE + username: admin + password: 123456 + sql: + init: + mode: always + platform: h2 +``` + +:::info +完整的 JAR 文件部署文档可查阅:[使用 JAR 文件部署](./jar-file.md) +::: + +当然,使用 Docker Compose 部署同样支持通过这种方式配置,只需要将 `application.yaml` 放在工作目录的挂载目录即可,示例: + +```bash +❯ tree +. +├── docker-compose.yaml +└── halo2 + └── application.yaml + +2 directories, 2 files +``` + +其中,`docker-compose.yaml` 的 Halo 服务的 `volumes` 应该包含 `./halo2:/root/.halo2`。 + +## 配置列表 + +### Halo 独有配置 + +通常用于生产环境的配置: + +| 配置路径 | 说明 | 生产环境默认值 | +| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | +| `halo.work-dir` | Halo [工作目录](../prepare.md#工作目录),通常不建议修改 | `${user.home}/.halo2` | +| `halo.external-url` | 网站的实际访问地址,如:`https://www.halo.run` | `http://localhost:8090` | +| `halo.use-absolute-permalink` | 永久链接是否生成为绝对地址,设置为 `true` 时,请确保正确配置了 `halo.external-url` | `false` | +| `halo.security.frame-options.disabled` | 是否禁止网站通过 iframe 嵌入 | `false` | +| `halo.security.frame-options.mode` | iframe 嵌入模式,默认为同源,可设置的值为 `DENY`、`SAMEORIGIN` | `SAMEORIGIN` | +| `halo.security.referrer-options.policy` | Referrer-Policy 是一个 HTTP 头部字段,用于控制浏览器在发送请求时如何处理 Referer 信息,可设置的值请参考 [https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Referrer-Policy](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Referrer-Policy) | `strict-origin-when-cross-origin` | +| `halo.security.remember-me.token-validity` | 保持登录会话的有效期,默认为 14 天(14d) | `14d` | +| `halo.security.basic-auth.disabled` | 是否禁用 API 的 Basic Auth 认证 | `true` | +| `halo.security.two-factor-auth.disabled` | 是否禁用系统全局的两步验证 | `false` | +| `halo.attachment.resource-mappings[0].pathPattern` | 附件资源代理匹配规则,这个设置通常适用于从其他平台迁移的场景 | `/upload/**` | +| `halo.attachment.resource-mappings[0].locations` | 附件资源代理目录,只能放置在[工作目录](../prepare.md#工作目录)的 `attachments` 目录 | `migrate-from-1.x` | + +通常用于开发环境的配置: + +| 配置路径 | 说明 | 默认值 | +| ----------------------------- | --------------------------- | ------ | +| `halo.console.proxy.endpoint` | 开发环境的 Console 代理地址 | -- | +| `halo.console.proxy.enabled` | 是否启用 Console 代理地址 | -- | +| `halo.uc.proxy.endpoint` | 开发环境的 UC 代理地址 | -- | +| `halo.uc.proxy.enabled` | 是否启用 UC 代理地址 | -- | +| `halo.plugin.runtime-mode` | 插件的运行模式 | -- | + +### Web 框架本身的配置 + +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 常用的配置: + +Web 服务相关: + +| 配置路径 | 说明 | 默认值 | +| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `server.port` | Web 服务端口 | `8090` | +| `server.compression.enabled` | 是否开启 gzip 压缩 | `true` | +| `spring.web.resources.cache.cachecontrol.max-age` | 设置静态资源的缓存存储的最大周期,超过这个时间缓存被认为过期 | `365d` | +| `spring.web.resources.cache.cachecontrol.no-cache` | 设置静态资源响应头的 `Cache-Control` 为 `no-cache`,在发布缓存副本之前,强制要求缓存把请求提交给原始服务器进行验证(协商缓存验证) | `false` | +| `spring.web.resources.cache.cachecontrol.use-last-modified` | 是否为静态资源添加 Last-Modified 响应头,Last-Modified 表示服务器上资源的最后修改时间。当浏览器第一次请求资源时,服务器会在响应头中包含这个字段 | `true` | +| `spring.thymeleaf.cache` | 是否开启模版引擎缓存 | `true` | + +数据库相关: + +| 配置路径 | 说明 | 默认值 | +| -------------------------- | ----------------------------------------------------------- | ------ | +| `spring.r2dbc.url` | 数据库连接地址,详细可查阅下方的 `数据库配置` | -- | +| `spring.r2dbc.username` | 数据库用户名 | -- | +| `spring.r2dbc.password` | 数据库密码 | -- | +| `spring.sql.init.platform` | 数据库平台名称,支持 `postgresql`、`mysql`、`mariadb`、`h2` | -- | + +数据库配置: + +| 链接方式 | 链接地址格式 | `spring.sql.init.platform` | +| ----------- | ---------------------------------------------------------------------------------- | -------------------------- | +| PostgreSQL | `r2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}` | postgresql | +| MySQL | `r2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}` | mysql | +| MariaDB | `r2dbc:pool:mariadb://{HOST}:{PORT}/{DATABASE}` | mariadb | +| H2 Database | `r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE` | h2 | diff --git a/docs/getting-started/install/docker-compose.md b/docs/getting-started/install/docker-compose.md index 45a42607..930322cd 100644 --- a/docs/getting-started/install/docker-compose.md +++ b/docs/getting-started/install/docker-compose.md @@ -221,6 +221,10 @@ import DockerRegistryList from "./slots/_docker-registry-list.md" + :::info + 为了保持部署流程的简洁,此文档仅提供了必要的配置示例,完整的配置选项列表可查阅:[配置说明](./config.md) + ::: + 3. 启动 Halo 服务 ```bash diff --git a/docs/getting-started/install/docker.md b/docs/getting-started/install/docker.md index 729f2d02..b07157ae 100644 --- a/docs/getting-started/install/docker.md +++ b/docs/getting-started/install/docker.md @@ -48,6 +48,10 @@ import DockerRegistryList from "./slots/_docker-registry-list.md" + :::info + 为了保持部署流程的简洁,此文档仅提供了必要的配置示例,完整的配置选项列表可查阅:[配置说明](./config.md) + ::: + 2. 用浏览器访问 `/console` 即可进入 Halo 管理页面,首次启动会进入初始化页面。 :::tip diff --git a/docs/getting-started/install/jar-file.md b/docs/getting-started/install/jar-file.md index 5fea801a..a1f7dd95 100644 --- a/docs/getting-started/install/jar-file.md +++ b/docs/getting-started/install/jar-file.md @@ -136,6 +136,10 @@ title: 使用 JAR 文件部署 不推荐在生产环境使用默认的 H2 数据库,这可能因为操作不当导致数据文件损坏。如果因为某些原因(如内存不足以运行独立数据库)必须要使用,建议按时[备份数据](../../user-guide/backup.md)。 ::: + :::info + 为了保持部署流程的简洁,此文档仅提供了必要的配置示例,完整的配置选项列表可查阅:[配置说明](./config.md) + ::: + 配置完成之后,保存即可。 6. 测试运行 Halo diff --git a/docs/getting-started/install/offline.md b/docs/getting-started/install/offline.md index 7eff5176..0ce8f145 100644 --- a/docs/getting-started/install/offline.md +++ b/docs/getting-started/install/offline.md @@ -1,6 +1,6 @@ --- -title: 离线环境部署 -description: 离线环境部署 +title: 使用离线包部署 +description: 使用离线包在离线环境部署 --- import DockerArgs from "./slots/_docker-args.md" diff --git a/docs/getting-started/install/podman.md b/docs/getting-started/install/podman.md index 0a745c66..52458fe3 100644 --- a/docs/getting-started/install/podman.md +++ b/docs/getting-started/install/podman.md @@ -74,6 +74,10 @@ Podman 采用无守护进程的包容性架构,因此可以更安全、更简 + :::info + 为了保持部署流程的简洁,此文档仅提供了必要的配置示例,完整的配置选项列表可查阅:[配置说明](./config.md) + ::: + 2. 用浏览器访问 `/console` 即可进入 Halo 管理页面,首次启动会进入初始化页面。 :::tip diff --git a/sidebars.js b/sidebars.js index deef327a..65db1a95 100644 --- a/sidebars.js +++ b/sidebars.js @@ -39,6 +39,7 @@ module.exports = { "getting-started/install/podman", "getting-started/install/jar-file", "getting-started/install/offline", + "getting-started/install/config", { type: "category", label: "云平台", diff --git a/versioned_docs/version-2.20/getting-started/install/config.md b/versioned_docs/version-2.20/getting-started/install/config.md new file mode 100644 index 00000000..46cd00f6 --- /dev/null +++ b/versioned_docs/version-2.20/getting-started/install/config.md @@ -0,0 +1,130 @@ +--- +title: 配置说明 +description: Halo 的运行配置说明文档 +--- + +在前面的部署文档中,为了保证部署流程的简洁,只说明了运行所必须的配置,但除了运行之外,Halo 还提供了不少其他的配置以及我们所使用的 Web 框架的配置,这个文档我们将详细介绍 Halo 的完整配置。 + +## 配置方式 + +Halo 支持通过多种方式进行配置,目前 [Docker Compose 部署文档](./docker-compose.md) 的示例是通过运行参数配置,[JAR 文件部署方式](./jar-file.md) 是通过配置文件进行配置。 + +### 通过运行参数 + +通常我们在使用 Docker Compose 部署的时候推荐使用这种方式进行配置,配置方式为在 Docker Compose 配置文件的 `command` 添加对应的配置条目即可,比如: + +```yaml {5-10} +services: + halo: + image: registry.fit2cloud.com/halo/halo:2.20 + ... + command: + - --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo + - --spring.r2dbc.username=halo + - --spring.r2dbc.password=openpostgresql + - --spring.sql.init.platform=postgresql + - --halo.external-url=http://localhost:8090/ +``` + +### 通过配置文件 + +通常我们在使用 JAR 文件部署的时候更推荐使用这种方式进行配置,配置文件名称为 `application.yaml`,并且需要在运行的时候通过 `--spring.config.additional-location` 参数指定配置文件存放的目录,运行示例: + +```bash +java -jar halo.jar --spring.config.additional-location=optional:file:$HOME/.halo2/ +``` + +配置示例: + +```yaml title="~/.halo2/application.yaml" +spring: + r2dbc: + url: r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE + username: admin + password: 123456 + sql: + init: + mode: always + platform: h2 +``` + +:::info +完整的 JAR 文件部署文档可查阅:[使用 JAR 文件部署](./jar-file.md) +::: + +当然,使用 Docker Compose 部署同样支持通过这种方式配置,只需要将 `application.yaml` 放在工作目录的挂载目录即可,示例: + +```bash +❯ tree +. +├── docker-compose.yaml +└── halo2 + └── application.yaml + +2 directories, 2 files +``` + +其中,`docker-compose.yaml` 的 Halo 服务的 `volumes` 应该包含 `./halo2:/root/.halo2`。 + +## 配置列表 + +### Halo 独有配置 + +通常用于生产环境的配置: + +| 配置路径 | 说明 | 生产环境默认值 | +| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | +| `halo.work-dir` | Halo [工作目录](../prepare.md#工作目录),通常不建议修改 | `${user.home}/.halo2` | +| `halo.external-url` | 网站的实际访问地址,如:`https://www.halo.run` | `http://localhost:8090` | +| `halo.use-absolute-permalink` | 永久链接是否生成为绝对地址,设置为 `true` 时,请确保正确配置了 `halo.external-url` | `false` | +| `halo.security.frame-options.disabled` | 是否禁止网站通过 iframe 嵌入 | `false` | +| `halo.security.frame-options.mode` | iframe 嵌入模式,默认为同源,可设置的值为 `DENY`、`SAMEORIGIN` | `SAMEORIGIN` | +| `halo.security.referrer-options.policy` | Referrer-Policy 是一个 HTTP 头部字段,用于控制浏览器在发送请求时如何处理 Referer 信息,可设置的值请参考 [https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Referrer-Policy](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Referrer-Policy) | `strict-origin-when-cross-origin` | +| `halo.security.remember-me.token-validity` | 保持登录会话的有效期,默认为 14 天(14d) | `14d` | +| `halo.security.basic-auth.disabled` | 是否禁用 API 的 Basic Auth 认证 | `true` | +| `halo.security.two-factor-auth.disabled` | 是否禁用系统全局的两步验证 | `false` | +| `halo.attachment.resource-mappings[0].pathPattern` | 附件资源代理匹配规则,这个设置通常适用于从其他平台迁移的场景 | `/upload/**` | +| `halo.attachment.resource-mappings[0].locations` | 附件资源代理目录,只能放置在[工作目录](../prepare.md#工作目录)的 `attachments` 目录 | `migrate-from-1.x` | + +通常用于开发环境的配置: + +| 配置路径 | 说明 | 默认值 | +| ----------------------------- | --------------------------- | ------ | +| `halo.console.proxy.endpoint` | 开发环境的 Console 代理地址 | -- | +| `halo.console.proxy.enabled` | 是否启用 Console 代理地址 | -- | +| `halo.uc.proxy.endpoint` | 开发环境的 UC 代理地址 | -- | +| `halo.uc.proxy.enabled` | 是否启用 UC 代理地址 | -- | +| `halo.plugin.runtime-mode` | 插件的运行模式 | -- | + +### Web 框架本身的配置 + +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 常用的配置: + +Web 服务相关: + +| 配置路径 | 说明 | 默认值 | +| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `server.port` | Web 服务端口 | `8090` | +| `server.compression.enabled` | 是否开启 gzip 压缩 | `true` | +| `spring.web.resources.cache.cachecontrol.max-age` | 设置静态资源的缓存存储的最大周期,超过这个时间缓存被认为过期 | `365d` | +| `spring.web.resources.cache.cachecontrol.no-cache` | 设置静态资源响应头的 `Cache-Control` 为 `no-cache`,在发布缓存副本之前,强制要求缓存把请求提交给原始服务器进行验证(协商缓存验证) | `false` | +| `spring.web.resources.cache.cachecontrol.use-last-modified` | 是否为静态资源添加 Last-Modified 响应头,Last-Modified 表示服务器上资源的最后修改时间。当浏览器第一次请求资源时,服务器会在响应头中包含这个字段 | `true` | +| `spring.thymeleaf.cache` | 是否开启模版引擎缓存 | `true` | + +数据库相关: + +| 配置路径 | 说明 | 默认值 | +| -------------------------- | ----------------------------------------------------------- | ------ | +| `spring.r2dbc.url` | 数据库连接地址,详细可查阅下方的 `数据库配置` | -- | +| `spring.r2dbc.username` | 数据库用户名 | -- | +| `spring.r2dbc.password` | 数据库密码 | -- | +| `spring.sql.init.platform` | 数据库平台名称,支持 `postgresql`、`mysql`、`mariadb`、`h2` | -- | + +数据库配置: + +| 链接方式 | 链接地址格式 | `spring.sql.init.platform` | +| ----------- | ---------------------------------------------------------------------------------- | -------------------------- | +| PostgreSQL | `r2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}` | postgresql | +| MySQL | `r2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}` | mysql | +| MariaDB | `r2dbc:pool:mariadb://{HOST}:{PORT}/{DATABASE}` | mariadb | +| H2 Database | `r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE` | h2 | diff --git a/versioned_docs/version-2.20/getting-started/install/docker-compose.md b/versioned_docs/version-2.20/getting-started/install/docker-compose.md index 45a42607..930322cd 100644 --- a/versioned_docs/version-2.20/getting-started/install/docker-compose.md +++ b/versioned_docs/version-2.20/getting-started/install/docker-compose.md @@ -221,6 +221,10 @@ import DockerRegistryList from "./slots/_docker-registry-list.md" + :::info + 为了保持部署流程的简洁,此文档仅提供了必要的配置示例,完整的配置选项列表可查阅:[配置说明](./config.md) + ::: + 3. 启动 Halo 服务 ```bash diff --git a/versioned_docs/version-2.20/getting-started/install/docker.md b/versioned_docs/version-2.20/getting-started/install/docker.md index 729f2d02..b07157ae 100644 --- a/versioned_docs/version-2.20/getting-started/install/docker.md +++ b/versioned_docs/version-2.20/getting-started/install/docker.md @@ -48,6 +48,10 @@ import DockerRegistryList from "./slots/_docker-registry-list.md" + :::info + 为了保持部署流程的简洁,此文档仅提供了必要的配置示例,完整的配置选项列表可查阅:[配置说明](./config.md) + ::: + 2. 用浏览器访问 `/console` 即可进入 Halo 管理页面,首次启动会进入初始化页面。 :::tip diff --git a/versioned_docs/version-2.20/getting-started/install/jar-file.md b/versioned_docs/version-2.20/getting-started/install/jar-file.md index 5fea801a..a1f7dd95 100644 --- a/versioned_docs/version-2.20/getting-started/install/jar-file.md +++ b/versioned_docs/version-2.20/getting-started/install/jar-file.md @@ -136,6 +136,10 @@ title: 使用 JAR 文件部署 不推荐在生产环境使用默认的 H2 数据库,这可能因为操作不当导致数据文件损坏。如果因为某些原因(如内存不足以运行独立数据库)必须要使用,建议按时[备份数据](../../user-guide/backup.md)。 ::: + :::info + 为了保持部署流程的简洁,此文档仅提供了必要的配置示例,完整的配置选项列表可查阅:[配置说明](./config.md) + ::: + 配置完成之后,保存即可。 6. 测试运行 Halo diff --git a/versioned_docs/version-2.20/getting-started/install/offline.md b/versioned_docs/version-2.20/getting-started/install/offline.md index 7eff5176..0ce8f145 100644 --- a/versioned_docs/version-2.20/getting-started/install/offline.md +++ b/versioned_docs/version-2.20/getting-started/install/offline.md @@ -1,6 +1,6 @@ --- -title: 离线环境部署 -description: 离线环境部署 +title: 使用离线包部署 +description: 使用离线包在离线环境部署 --- import DockerArgs from "./slots/_docker-args.md" diff --git a/versioned_docs/version-2.20/getting-started/install/podman.md b/versioned_docs/version-2.20/getting-started/install/podman.md index 0a745c66..52458fe3 100644 --- a/versioned_docs/version-2.20/getting-started/install/podman.md +++ b/versioned_docs/version-2.20/getting-started/install/podman.md @@ -74,6 +74,10 @@ Podman 采用无守护进程的包容性架构,因此可以更安全、更简 + :::info + 为了保持部署流程的简洁,此文档仅提供了必要的配置示例,完整的配置选项列表可查阅:[配置说明](./config.md) + ::: + 2. 用浏览器访问 `/console` 即可进入 Halo 管理页面,首次启动会进入初始化页面。 :::tip diff --git a/versioned_sidebars/version-2.20-sidebars.json b/versioned_sidebars/version-2.20-sidebars.json index 3b7e3f40..ac9fa931 100644 --- a/versioned_sidebars/version-2.20-sidebars.json +++ b/versioned_sidebars/version-2.20-sidebars.json @@ -24,6 +24,7 @@ "getting-started/install/podman", "getting-started/install/jar-file", "getting-started/install/offline", + "getting-started/install/config", { "type": "category", "label": "云平台",