halo/docs
1
0
Fork 0
mirror of https://github.com/halo-dev/docs.git synced 2025-10-18 16:24:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update documentation for Halo 2.20 (#429)

Browse Source 
为 [Halo 2.20](https://github.com/halo-dev/halo/releases/tag/v2.20.0) 更新文档。

/kind documentation

```release-note
None
```
This commit is contained in:
Ryan Wang
2024-10-14 11:33:15 +08:00
committed by GitHub
parent f752dd74d7
commit 9876911e3a
185 changed files with 15652 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
versioned_docs/version-2.20/getting-started/first-post.md Normal file
View File

@@ -0,0 +1,32 @@
---
title: 第一篇文章
description: 安装完成后，如何写下第一篇文章。
---
<!-- markdownlint-disable MD034 -->
<video src="https://assets.halo.run/first-post.mp4" controls style={{width: '100%', borderRadius: '8px'}}/>
## 登录管理端
浏览器访问 `/console` 即可进入 Halo 管理端。
## 新建文章
Halo 安装完成后，默认初始化了一篇 `Hello Halo` 文章，接下来我们将创建并发布一篇自己的文章。
1. 在 Halo 管理端，点击仪表盘页面中的 `创建文章` 快捷入口，即可进入到文章编辑页面。
2. 在文章编辑器中，你可以尽情写下你想展现的内容。
3. 当内容编辑完成后，点击右上角的 `发布` 按钮，给文章设置一个合适的标题和别名，同时可以设置文章所属分类、标签及其他一些高级设置。
4. 确认无误后，点击弹框下方的 `发布` 按钮，我们的第一篇文章就成功发布了。
:::info
关于文章相关其他功能及文章各种设置项的说明，请参考《[用户指南-文章](../user-guide/posts.md)》章节
:::
## 查看文章
文章发布成功后，就可以在主题端查看到我们刚刚创建的文章了。
浏览器访问域名进入站点首页，站点展示的内容及样式由当前启用的主题所决定。
接下来，选一款喜欢的主题，尽情体验 Halo 吧！

78
versioned_docs/version-2.20/getting-started/install/1panel.md Normal file
View File

@@ -0,0 +1,78 @@
---
title: 使用 1Panel 部署
description: 使用 1Panel 部署
---
import DockerArgs from "./slots/_docker-args.md"
:::info
在继续操作之前，我们推荐您先阅读[《写在前面》](../prepare)，这可以快速帮助你了解 Halo。
:::
## 1Panel 简介
[1Panel](https://1panel.cn) 是一个现代化、开源的 Linux 服务器运维管理面板。
![1Panel 截图](/img/install/1panel/1panel.png)
### 功能
- **快速建站**：深度集成 WordPress 和 Halo，域名绑定、SSL 证书配置等一键搞定。
- **高效管理**：通过 Web 端轻松管理 Linux 服务器，包括应用管理、主机监控、文件管理、数据库管理、容器管理等。
- **安全可靠**：最小漏洞暴露面，提供防火墙和安全审计等功能。
- **一键备份**：支持一键备份和恢复，备份数据云端存储，永不丢失。
### 安装
关于 1Panel 的安装部署与基础功能介绍，请参考 [1Panel 官方文档](https://1panel.cn/docs/installation/online_installation/)。此处假设你已经完成了 1Panel 的安装部署，并对其功能有了基础了解。
### 安装基础软件
在安装 Halo 之前，我们需要先在 1Panel 上安装好所需的软件，包括 OpenResty 和 MySQL。在接下来的文档中，我们会默认你已经安装好了这两个软件，并不再赘述。
![OpenResty 和 MySQL](/img/install/1panel/openresty-mysql.png)
## 安装 Halo 应用
进入应用商店应用列表，选择其中的 Halo 应用进行安装。
![选择 Halo 应用](/img/install/1panel/app-store-halo.png)
在应用详情页选择最新的 Halo 版本进行安装。
![选择 Halo 版本](/img/install/1panel/install-halo.png)
参数说明：
- **名称**：要创建的 Halo 应用的名称。
- **数据库服务**：Halo 应用使用的数据库应用，支持下拉选择已安装的数据库应用，1Panel 会自动配置 Halo 使用该数据库。
- **数据库名**：Halo 应用使用的数据库名称，1Panel 会在选中的数据库中自动创建这个数据库。
- **数据库用户**：Halo 应用使用的数据库用户名，1Panel 会在选中的数据库中自动创建这个用户，并添加对应的数据库授权。
- **数据库用户密码**：Halo 应用使用的数据库用户密码，1Panel 会在选中的数据库中自动为上一步创建的用户配置该密码。
- **超级管理员用户名**：Halo 应用初始化创建的超级管理员用户名。
- **超级管理员密码**：Halo 应用初始化创建的超级管理员密码。
- **外部访问地址**：Halo 应用的最终访问地址，如果有为 Halo 规划域名，需要配置为域名格式，例如 `http://halo.example.com`。否则配置为 `http://服务器IP:PORT`，例如 `http://192.168.1.1:8090`。
- **端口**：Halo 应用的服务端口。
开始安装后页面自动跳转到已安装应用列表，等待刚刚安装的 Halo 应用变为已启动状态。
![Halo 运行状态](/img/install/1panel/halo-status.png)
此时便可以通过配置的外部访问地址来访问 Halo 了。
![访问 Halo](/img/install/1panel/halo-console.png)
## 创建网站
完成 Halo 应用的安装后，此时并不会自动创建一个网站，我们需要手动创建一个网站，然后将 Halo 应用绑定到这个网站上才能使用域名访问。
点击 1Panel 菜单的 **网站**，进入网站列表页，点击 **创建网站** 按钮。
![创建网站](/img/install/1panel/new-site.png)
1. 在已装应用中选择我们刚刚新建的 Halo 应用。
2. 正确填写主域名，需要注意的是需要提前解析好域名到服务器 IP。
最后，点击确认按钮，等待网站创建完成。
![网站列表](/img/install/1panel/site.png)

19
versioned_docs/version-2.20/getting-started/install/cloud/alibaba-cloud-computenest.md Normal file
View File

@@ -0,0 +1,19 @@
---
title: 阿里云计算巢部署
description: 使用阿里云计算巢服务部署 Halo
---
阿里云计算巢提供了软件与资源的一体化交付的完善基础能力，助力服务商、开发者的提升服务能力和降低运营成本。计算巢已经支持快速部署 Halo 社区版。
## 部署流程
1. 访问计算巢 Halo 社区版服务[部署链接](https://computenest.console.aliyun.com/service/instance/create/default?type=user&ServiceId=service-71b471d79c224520bba3)，按提示填写部署参数：
![image.png](/img/install/alibab-cloud-computenest/deploy_1.jpg)
2. 参数填写完成后可以看到对应询价明细，确认参数后点击**下一步：确认订单**。确认订单完成后同意服务协议并点击**立即创建**进入部署阶段。
3. 等待部署完成后进入服务实例管理, 在控制台找到 Halo 服务访问链接。
![image.png](/img/install/alibab-cloud-computenest/deploy_2.jpg)
4. 单击链接访问 Halo 服务。
![image.png](/img/install/alibab-cloud-computenest/halo-setup.jpg)

71
versioned_docs/version-2.20/getting-started/install/cloud/tencent-cloud-lighthouse.md Normal file
View File

@@ -0,0 +1,71 @@
---
title: 腾讯云轻量应用模板
description: 使用腾讯云轻量应用服务器的应用模板部署 Halo
---
腾讯云目前已经在轻量应用服务器的应用模板中添加了 Halo 的模板镜像，选择应用模板购买服务器之后就预装了 Halo 和 [1Panel](https://1panel.cn/)。
## 购买轻量应用服务器
购买地址：[轻量应用服务器](https://buy.cloud.tencent.com/lighthouse?blueprintType=APP_OS&blueprintOfficialId=lhbp-pjoqcja2&regionId=8&zone=ap-beijing-3&bundleId=bundle_starter_mc_med2_01&loginSet=AUTO&from=lh-console)
然后在应用模板中选择 Halo，然后选择所需地域、可用区、套餐等，点击立即购买即可。
![购买](/img/install/tencent-cloud-lighthouse/buy.png)
## 应用管理
![应用管理](/img/install/tencent-cloud-lighthouse/application.png)
服务器初始化完成之后，进入应用 **管理页面** 即可看到 Halo 和 1Panel 的相关信息。
## 访问 Halo
在 **应用管理** 页面中点击 **管理员登录地址** 即可进入 Halo 初始化页面，填写初始化信息即可完成 Halo 的安装。
![Halo 初始化](/img/install/tencent-cloud-lighthouse/halo-setup.png)
## 1Panel 管理
1. 在 **应用管理** 页面中可以看到预装的 1Panel 信息，首先需要将 1Panel 的端口开放，进入防火墙页面添加默认端口 8090 即可：
![防火墙](/img/install/tencent-cloud-lighthouse/firewall.png)
2. 登录到实例获取 1Panel 初始用户名和密码：
![1Panel 信息](/img/install/tencent-cloud-lighthouse/1panel-info.png)
3. 然后就可以通过 `http://ip:8090/tencentcloud` 进入 1Panel 的管理后台：
![1Panel 登录](/img/install/tencent-cloud-lighthouse/1panel-login.png)
![1Panel 概览](/img/install/tencent-cloud-lighthouse/1panel-overview.png)
## 查看预装应用
为了保证 Halo 的正常运行，1Panel 中预装了 Halo 所需的环境，可以在 **应用商店** 的 **已安装** 选项卡中查看：
![预装应用](/img/install/tencent-cloud-lighthouse/installed-apps.png)
关于应用商店，可查阅 [1Panel 文档](https://1panel.cn/docs/user_manual/appstore/appstore/)。
## 升级 Halo
在 **应用商店** 的 **可升级** 选项卡中检查 Halo 是否有更新，如果有新的版本，点击应用卡片的 **升级** 按钮即可。
![升级 Halo](/img/install/tencent-cloud-lighthouse/upgrade.png)
## 绑定域名
:::info
该操作要求用户有一个可用的域名，并在 DNS 服务商处添加对应的解析记录。
:::
在 **网站** 页面中，此镜像默认添加了一个关联 Halo 应用的网站，你可以点击配置按钮然后添加自己的域名。
![网站](/img/install/tencent-cloud-lighthouse/websites.png)
![添加域名](/img/install/tencent-cloud-lighthouse/domain.png)
除此之外，在绑定域名之后，还需要修改一下 Halo 的 **外部访问地址** 参数为实际的网站访问地址（如：[https://demo.halo.run](https://demo.halo.run)），否则 Halo 的部分功能或者插件可能会出现使用问题，只需要按照下图所示修改应用的参数然后点击确认即可。
![修改外部访问地址](/img/install/tencent-cloud-lighthouse/external-url.png)
关于网站管理，可查阅 [1Panel 文档](https://1panel.cn/docs/user_manual/websites/websites/)。

333
versioned_docs/version-2.20/getting-started/install/docker-compose.md Normal file
View File

@@ -0,0 +1,333 @@
---
title: 使用 Docker Compose 部署
description: 使用 Docker Compose 部署
---
```mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import DockerArgs from "./slots/_docker-args.md"
import DockerRegistryList from "./slots/_docker-registry-list.md"
```
:::info
在继续操作之前，我们推荐您先阅读[《写在前面》](../prepare.md)，这可以快速帮助你了解 Halo。
:::
## 环境搭建
- Docker 安装文档：[https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
- Docker Compose 安装文档：[https://docs.docker.com/compose/install/](https://docs.docker.com/compose/install/)
:::tip
我们推荐按照 Docker 官方文档安装 Docker 和 Docker Compose，因为部分 Linux 发行版软件仓库中的 Docker 版本可能过旧。
:::
## 创建容器组
<DockerRegistryList />
1. 在系统任意位置创建一个文件夹，此文档以 `~/halo` 为例。
```bash
mkdir ~/halo && cd ~/halo
```
:::info
注意：后续操作中，Halo 产生的所有数据都会保存在这个目录，请妥善保存。
:::
2. 创建 `docker-compose.yaml`
此文档提供几种场景的 Docker Compose 配置文件，请根据你的需要**选择一种**。
:::info
需要注意的是，此文档为了更加方便的管理配置，所有与 Halo 相关的配置都使用 Docker 容器启动参数代替，所以无需创建 application.yaml 文件。
:::
<Tabs queryString="current">
<TabItem value="halo-postgresql" label="Halo + PostgreSQL" default>
```yaml {23-29,43} title="~/halo/docker-compose.yaml"
version: "3"
services:
halo:
image: registry.fit2cloud.com/halo/halo:2.20
restart: on-failure:3
depends_on:
halodb:
condition: service_healthy
networks:
halo_network:
volumes:
- ./halo2:/root/.halo2
ports:
- "8090:8090"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"]
interval: 30s
timeout: 5s
retries: 5
start_period: 30s
command:
- --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo
- --spring.r2dbc.username=halo
# PostgreSQL 的密码，请保证与下方 POSTGRES_PASSWORD 的变量值一致。
- --spring.r2dbc.password=openpostgresql
- --spring.sql.init.platform=postgresql
# 外部访问地址，请根据实际需要修改
- --halo.external-url=http://localhost:8090/
halodb:
image: postgres:15.4
restart: on-failure:3
networks:
halo_network:
volumes:
- ./db:/var/lib/postgresql/data
healthcheck:
test: [ "CMD", "pg_isready" ]
interval: 10s
timeout: 5s
retries: 5
environment:
- POSTGRES_PASSWORD=openpostgresql
- POSTGRES_USER=halo
- POSTGRES_DB=halo
- PGUSER=halo
networks:
halo_network:
```
:::info
此示例的 PostgreSQL 数据库容器默认没有设置端口映射，如果需要在容器外部访问数据库，可以自行在 `halodb` 服务中添加端口映射，PostgreSQL 的端口为 `5432`。
:::
</TabItem>
<TabItem value="halo-mysql" label="Halo + MySQL">
```yaml {23-29,51} title="~/halo/docker-compose.yaml"
version: "3"
services:
halo:
image: registry.fit2cloud.com/halo/halo:2.20
restart: on-failure:3
depends_on:
halodb:
condition: service_healthy
networks:
halo_network:
volumes:
- ./halo2:/root/.halo2
ports:
- "8090:8090"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"]
interval: 30s
timeout: 5s
retries: 5
start_period: 30s
command:
- --spring.r2dbc.url=r2dbc:pool:mysql://halodb:3306/halo
- --spring.r2dbc.username=root
# MySQL 的密码，请保证与下方 MYSQL_ROOT_PASSWORD 的变量值一致。
- --spring.r2dbc.password=o#DwN&JSa56
- --spring.sql.init.platform=mysql
# 外部访问地址，请根据实际需要修改
- --halo.external-url=http://localhost:8090/
halodb:
image: mysql:8.1.0
restart: on-failure:3
networks:
halo_network:
command:
- --default-authentication-plugin=caching_sha2_password
- --character-set-server=utf8mb4
- --collation-server=utf8mb4_general_ci
- --explicit_defaults_for_timestamp=true
volumes:
- ./mysql:/var/lib/mysql
- ./mysqlBackup:/data/mysqlBackup
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
interval: 3s
retries: 5
start_period: 30s
environment:
# 请修改此密码，并对应修改上方 Halo 服务的 SPRING_R2DBC_PASSWORD 变量值
- MYSQL_ROOT_PASSWORD=o#DwN&JSa56
- MYSQL_DATABASE=halo
networks:
halo_network:
```
:::info
此示例的 MySQL 数据库容器默认没有设置端口映射，如果需要在容器外部访问数据库，可以自行在 `halodb` 服务中添加端口映射，MySQL 的端口为 `3306`。
:::
</TabItem>
<TabItem value="halo-h2" label="Halo + H2">
:::warning
不推荐在生产环境使用默认的 H2 数据库，这可能因为操作不当导致数据文件损坏。如果因为某些原因（如内存不足以运行独立数据库）必须要使用，建议按时[备份数据](../../user-guide/backup.md)。
:::
```yaml {19-24} title="~/halo/docker-compose.yaml"
version: "3"
services:
halo:
image: registry.fit2cloud.com/halo/halo:2.20
restart: on-failure:3
volumes:
- ./halo2:/root/.halo2
ports:
- "8090:8090"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"]
interval: 30s
timeout: 5s
retries: 5
start_period: 30s
command:
# 外部访问地址，请根据实际需要修改
- --halo.external-url=http://localhost:8090/
```
</TabItem>
<TabItem value="external-db" label="使用外部数据库">
```yaml {7,12-20} title="~/halo/docker-compose.yaml"
version: "3"
services:
halo:
image: registry.fit2cloud.com/halo/halo:2.20
restart: on-failure:3
network_mode: "host"
volumes:
- ./halo2:/root/.halo2
command:
# 修改为自己已有的 MySQL 配置
- --spring.r2dbc.url=r2dbc:pool:mysql://localhost:3306/halo
- --spring.r2dbc.username=root
- --spring.r2dbc.password=
- --spring.sql.init.platform=mysql
# 外部访问地址，请根据实际需要修改
- --halo.external-url=http://localhost:8090/
# 端口号 默认8090
- --server.port=8090
```
</TabItem>
</Tabs>
运行参数详解：
<DockerArgs />
3. 启动 Halo 服务
```bash
docker-compose up -d
```
实时查看日志：
```bash
docker-compose logs -f
```
4. 用浏览器访问 /console 即可进入 Halo 管理页面，首次启动会进入初始化页面。
:::tip
如果需要配置域名访问，建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip:端口号` 的形式无法访问，请到服务器厂商后台将运行的端口号添加到安全组，如果服务器使用了 Linux 面板，请检查此 Linux 面板是否有还有安全组配置，需要同样将端口号添加到安全组。
:::
## 更新容器组
1. 备份数据，可以参考 [备份与恢复](../../user-guide/backup.md) 进行完整备份（可选，但推荐备份）。
2. 更新 Halo 服务
修改 `docker-compose.yaml` 中配置的镜像版本。
```yaml {3}
services:
halo:
image: registry.fit2cloud.com/halo/halo:2.20
```
```bash
docker-compose up -d
```
## 反向代理
你可以在下面的反向代理软件中任选一项，我们假设你已经安装好了其中一项，并对其的基本操作有一定了解。 如果你对它们没有任何了解，可以参考我们更为详细的反向代理文档：
1. 使用 [Nginx Proxy Manager](../install/other/nginxproxymanager.md)
2. 使用 [Traefik](../install/other/traefik.md)
### Nginx
```nginx {2,7,10}
upstream halo {
server 127.0.0.1:8090;
}
server {
listen 80;
listen [::]:80;
server_name www.yourdomain.com;
client_max_body_size 1024m;
location / {
proxy_pass http://halo;
proxy_set_header HOST $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
```
### Caddy 2
```txt {1,5}
www.yourdomain.com
encode gzip
reverse_proxy 127.0.0.1:8090
```
### Traefik
更新 halo 容器组的配置
1. `networks` 中引入已存在的网络 `traefik`（此网络需要 [提前创建](../install/other/traefik.md#创建-traefik)）
2. `services.halo.networks` 中添加网络 `traefik`
3. 修改外部地址为你的域名
4. 声明路由规则、开启 TLS
```yaml {4-5,16,20,25-31}
version: "3.8"
networks:
traefik:
external: true
halo:
services:
halo:
image: registry.fit2cloud.com/halo/halo:2.20
restart: on-failure:3
volumes:
- ./halo2:/root/.halo2
networks:
- traefik
- halo
command:
# 外部访问地址，请根据实际需要修改
- --halo.external-url=https://yourdomain.com
labels:
traefik.enable: "true"
traefik.docker.network: traefik
traefik.http.routers.halo.rule: Host(`yourdomain.com`)
traefik.http.routers.halo.tls: "true"
traefik.http.routers.halo.tls.certresolver: myresolver
traefik.http.services.halo.loadbalancer.server.port: 8090
```

79
versioned_docs/version-2.20/getting-started/install/docker.md Normal file
View File

@@ -0,0 +1,79 @@
---
title: 使用 Docker 部署
description: 使用 Docker 部署
---
import DockerArgs from "./slots/_docker-args.md"
import DockerRegistryList from "./slots/_docker-registry-list.md"
:::info
在继续操作之前，我们推荐您先阅读[《写在前面》](../prepare)，这可以快速帮助你了解 Halo。
:::
:::warning
此文档仅提供使用默认 H2 数据库的 Docker 运行方式，主要用于体验和测试，在生产环境我们不推荐使用 H2 数据库，这可能因为操作不当导致数据文件损坏。如果因为某些原因（如内存不足以运行独立数据库）必须要使用，建议按时[备份数据](../../user-guide/backup.md)。
如果需要使用其他数据库部署，我们推荐使用 Docker Compose 部署：[使用 Docker Compose 部署](./docker-compose)
:::
## 环境搭建
- Docker 安装文档：[https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
:::tip
我们推荐按照 Docker 官方文档安装 Docker，因为部分 Linux 发行版软件仓库中的 Docker 版本可能过旧。
:::
## 使用 Docker 镜像
<DockerRegistryList />
1. 创建容器
```bash
docker run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 registry.fit2cloud.com/halo/halo:2.20
```
:::info
注意：此命令默认使用自带的 H2 Database 数据库。如需使用 PostgreSQL，请参考：[使用 Docker Compose 部署](./docker-compose)
:::
- **-it**：开启输入功能并连接伪终端
- **-d**：后台运行容器
- **--name**：为容器指定一个名称
- **-p**：端口映射，格式为 `主机(宿主)端口:容器端口` ，可在 `application.yaml` 配置。
- **-v**：工作目录映射。形式为：`-v 宿主机路径:/root/.halo2`，后者不能修改。
运行参数详解：
<DockerArgs />
2. 用浏览器访问 `/console` 即可进入 Halo 管理页面，首次启动会进入初始化页面。
:::tip
如果需要配置域名访问，建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip:端口号` 的形式无法访问，请到服务器厂商后台将运行的端口号添加到安全组，如果服务器使用了 Linux 面板，请检查此 Linux 面板是否有还有安全组配置，需要同样将端口号添加到安全组。
:::
## 升级版本
1. 备份数据，可以参考 [备份与恢复](../../user-guide/backup.md) 进行完整备份（可选，但推荐备份）。
2. 拉取新版本镜像
```bash
docker pull registry.fit2cloud.com/halo/halo:2.20
```
3. 停止运行中的容器
```bash
docker stop halo
docker rm halo
```
4. 更新 Halo
修改版本号后，按照最初安装的方式，重新创建容器即可。
```bash
docker run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 registry.fit2cloud.com/halo/halo:2.20
```

142
versioned_docs/version-2.20/getting-started/install/helm.md Normal file
View File

@@ -0,0 +1,142 @@
---
title: 使用 Helm 部署
description: 使用 Helm Chart 在 Kubernetes 集群中部署
---
import DockerArgs from "./slots/_docker-args.md"
:::info
在继续操作之前，我们推荐您先阅读[《写在前面》](../prepare.md)，这可以快速帮助你了解 Halo。
:::
## 先决条件
1. 拥有可用的 1.19 或更高版本的 Kubernetes 集群
2. 安装有 Helm 客户端 3.2 或更高的版本
3. 指定 StorageClass 自动创建存储卷时需要底层存储驱动支持
4. 用户对 Kubernetes 及 Helm 相关概念及如何使用有基本了解
## 快速部署
通过以下命令可以使用默认安装参数快速部署 Halo。默认参数下该 Chart 会自动部署 PostgreSQL 数据库给 Halo 使用，同时 Halo 工作目录及 PostgreSQL 数据目录通过指定 StorageClass 的方式自动创建存储卷进行持久化。
```bash
# 添加 Halo 项目的 Helm Charts 仓库
helm repo add halo https://halo-sigs.github.io/charts/
# 从 chart 仓库中更新本地可用chart的信息
helm repo update
# 使用默认参数，在当前的 Kubernetes namespace 中安装 Halo
helm install halo halo/halo
```
命令执行成功后会返回类似下文中的提示，通过提示中的命令可以获取到 NodePort 方式的 Halo 访问地址及默认的控制台管理员用户名和密码。
```text
NAME: halo
LAST DEPLOYED: Sun Jun 25 15:49:53 2023
NAMESPACE: halo
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
CHART NAME: halo
CHART VERSION: 1.1.0
APP VERSION: 2.6.1
** Please be patient while the chart is being deployed **
Your Halo site can be accessed through the following DNS name from within your cluster:
halo.halo.svc.cluster.local (port 80)
To access your Halo site from outside the cluster follow the steps below:
1. Get the Halo URL by running these commands:
export NODE_PORT=$(kubectl get --namespace halo -o jsonpath="{.spec.ports[0].nodePort}" services halo)
export NODE_IP=$(kubectl get nodes --namespace halo -o jsonpath="{.items[0].status.addresses[0].address}")
echo "Halo URL: http://$NODE_IP:$NODE_PORT/"
echo "Halo Console URL: http://$NODE_IP:$NODE_PORT/console"
2. Open a browser and access Halo using the obtained URL.
3. Login with the following credentials below to see your site:
echo Username: admin
echo Password: $(kubectl get secret --namespace halo halo -o jsonpath="{.data.halo-password}" | base64 -d)
```
:::info 参数说明
- 使用 Halo Helm Chart 仓库中 [values.yaml](https://github.com/halo-sigs/charts/blob/main/charts/halo/values.yaml) 文件中的默认参数进行安装；
- 关于 PostgreSQL 数据库的更多参数说明，请参考 [Bitnami PostgreSQL Chart](https://github.com/bitnami/charts/tree/main/bitnami/postgresql#parameters)，在原有参数格式上增加 `postgresql.` 前缀即可。
:::
## 卸载
使用命令 `helm uninstall halo` 可卸载已安装的 Halo 应用，其中 `halo` 为安装时指定的 Halo 应用名称。
:::warning
卸载应用前请确认数据库及 Halo 工作空间中的文件已进行备份或不再需要。
:::
## 使用 MySQL 数据库
当用户希望使用 MySQL 数据库而非默认的 PostgreSQL 数据库时，可以参考以下命令进行部署。
```bash
helm install halo halo/halo --set mysql.enabled=true --set postgresql.enabled=false
```
:::info 参数说明
- `mysql.enabled=true`： 自动安装 MySQL 数据库；
- `postgresql.enabled=false`： 不自动安装 PostgreSQL 数据库；
- 关于 mysql 的更多参数说明，请参考 [Bitnami MySQL Chart](https://github.com/bitnami/charts/tree/main/bitnami/mysql#parameters)，在原有参数格式上增加 `mysql.` 前缀即可。
:::
## 使用已有的数据库
当用户希望使用已有的数据库而非自动安装新数据库时，可以参考以下命令进行部署。
```bash
helm install halo halo/halo \
--set mysql.enabled=false \
--set postgresql.enabled=false \
--set externalDatabase.platform=mysql \
--set externalDatabase.host=mysql \
--set externalDatabase.port=3306 \
--set externalDatabase.user=halo \
--set externalDatabase.password=0P0gJrCyzz \
--set externalDatabase.database=halo
```
:::info 参数说明
- `mysql.enabled=true`： 不自动安装 MySQL 数据库；
- `postgresql.enabled=false`： 不自动安装 PostgreSQL 数据库；
- `externalDatabase.platform=mysql`：外部数据库类型，例如 `postgresql`、`mysql`；
- `externalDatabase.host=mysql`：外部数据库连接地址；
- `externalDatabase.port=3306`：外部数据库连接端口；
- `externalDatabase.user=halo`：外部数据库用户名；
- `externalDatabase.password=0P0gJrCyzz`：外部数据库密码；
- `externalDatabase.database=halo`：外部数据库库名；
:::
## 创建 Ingress
当用户希望通过 Ingress 将 Halo 应用暴露到 Kubernetes 集群外进行访问时，可以参考以下安装参数。
```bash
helm install halo halo/halo --set ingress.enabled=true --set ingress.hostname=demo.halo.run
```
对于已有的 Halo 应用，可以通过如下命令更新应用参数，为 Halo 应用创建 Ingress。
```bash
helm upgrade halo halo/halo --set ingress.enabled=true --set ingress.hostname=demo.halo.run
```
## 其他参数
完整参数列表请参考 Halo 项目的 [Helm Chart 仓库](https://github.com/halo-sigs/charts#parameters)。

291
versioned_docs/version-2.20/getting-started/install/jar-file.md Normal file
View File

@@ -0,0 +1,291 @@
---
title: 使用 JAR 文件部署
---
:::info
在继续操作之前，我们推荐您先阅读[《写在前面》](../prepare.md)，这可以快速帮助你了解 Halo。
:::
## 依赖检查
在开始之前，需要确保服务器已经满足以下条件：
1. [Java](https://openjdk.org) 环境，目前 Halo 最低需要 **JRE 17** 的环境。
2. 数据库（任一）
- [MySQL 5.7+](https://www.mysql.com)
- [MariaDB](https://mariadb.org)
- [PostgreSQL](https://www.postgresql.org)
由于 Linux 发行版本的差异以及包管理器的不同，此文档不会涉及到如何安装 Java 环境以及数据库，建议查阅对应依赖的官方文档进行安装。
## 安装
1. 创建新的系统用户
:::info
我们不推荐直接使用系统 root 用户来运行 Halo。如果你需要直接使用 root 用户，请跳过这一步。
:::
创建一个名为 halo 的用户（名字可以随意）
```bash
useradd -m halo
```
为 halo 用户创建密码
```bash
passwd halo
```
登录到 halo 账户
```bash
su - halo
```
2. 创建存放运行包的目录，这里以 `~/app` 为例
```bash
mkdir ~/app && cd ~/app
```
3. 下载运行包
```bash
wget https://dl.halo.run/release/halo-2.20.0.jar -O halo.jar
```
:::info
以下是官方维护的下载地址：
1. [https://download.halo.run](https://download.halo.run)
2. [https://github.com/halo-dev/halo/releases](https://github.com/halo-dev/halo/releases)
:::
4. 创建 [工作目录](../prepare#工作目录)
```bash
mkdir ~/.halo2 && cd ~/.halo2
```
5. 创建 Halo 配置文件
```bash
vim application.yaml
```
将以下内容复制到 `application.yaml` 中，根据下面的配置说明进行配置。
```yaml title="application.yaml"
server:
# 运行端口
port: 8090
spring:
# 数据库配置，支持 MySQL、MariaDB、PostgreSQL、H2 Database，具体配置方式可以参考下面的数据库配置
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
# 需要配合 r2dbc 的配置进行改动
platform: h2
halo:
caches:
page:
# 是否禁用页面缓存
disabled: true
# 工作目录位置
work-dir: ${user.home}/.halo2
# 外部访问地址
external-url: http://localhost:8090
# 附件映射配置，通常用于迁移场景
attachment:
resource-mappings:
- pathPattern: /upload/**
locations:
- migrate-from-1.x
```
数据库配置说明：
| 参数名 | 描述 |
|----------------------------|-------------------------------------------------------|
| `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 |
:::info
- HOST：数据库服务地址，如 `localhost`
- PORT：数据库服务端口，如 `3306`
- DATABASE：数据库名称，如 `halo`，需要提前创建
:::
:::warning
不推荐在生产环境使用默认的 H2 数据库，这可能因为操作不当导致数据文件损坏。如果因为某些原因（如内存不足以运行独立数据库）必须要使用，建议按时[备份数据](../../user-guide/backup.md)。
:::
配置完成之后，保存即可。
6. 测试运行 Halo
```bash
cd ~/app && java -jar halo.jar --spring.config.additional-location=optional:file:$HOME/.halo2/
```
7. 如果没有观察到异常日志，即可尝试访问 Halo
打开 `http://ip:端口号` 即可跳转到初始化页面。
:::info
如测试启动正常，请继续看[作为服务运行](#作为服务运行)部分，第 8 步仅仅作为测试。当你关闭 ssh 连接之后，服务会停止。你可使用 <kbd>CTRL</kbd>+<kbd>C</kbd> 停止运行测试进程。
:::
:::tip
如果需要配置域名访问，建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip:端口号` 的形式无法访问，请到服务器厂商后台将运行的端口号添加到安全组，如果服务器使用了 Linux 面板，请检查此 Linux 面板是否有还有安全组配置，需要同样将端口号添加到安全组。
:::
## 作为服务运行
下面将介绍如何将 Halo 作为服务运行，以实现在关闭 ssh 连接后，Halo 仍然可以正常运行。
此文档以 Systemd 为例，也可以参考：[Installing Spring Boot Applications](https://docs.spring.io/spring-boot/docs/current/reference/html/deployment.html#deployment.installing)
1. 退出 halo 账户，登录到 root 账户
> 如果当前就是 root 账户，请略过此步骤。
```bash
exit
```
2. 创建 halo.service 文件
```bash
vim /etc/systemd/system/halo.service
```
将以下内容复制到 `halo.service` 中，根据下面的配置说明进行配置。
```ini {9,10} title="/etc/systemd/system/halo.service"
[Unit]
Description=Halo Service
Documentation=https://docs.halo.run
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=USER
ExecStart=/usr/bin/java -server -Xms256m -Xmx256m -jar JAR_PATH --spring.config.additional-location=optional:file:/home/halo/.halo2/
ExecStop=/bin/kill -s QUIT $MAINPID
Restart=always
StandOutput=syslog
StandError=inherit
[Install]
WantedBy=multi-user.target
```
- **JAR_PATH**：Halo 运行包的绝对路径，例如 `/home/halo/app/halo.jar`，注意：此路径不支持 `~` 符号。
- **USER**：运行 Halo 的系统用户，如果有按照上方教程创建新的用户来运行 Halo，修改为你创建的用户名称即可。反之请删除 `User=USER`。
:::tip
请确保 `/usr/bin/java` 是正确无误的。建议将 `ExecStart` 中的命令复制出来运行一下，保证命令有效。
:::
配置完成之后，保存即可。
3. 重新加载 systemd
```bash
systemctl daemon-reload
```
4. 运行服务
```bash
systemctl start halo
```
5. 在系统启动时启动服务
```bash
systemctl enable halo
```
最后，你可以通过下面的命令查看服务日志：
```bash
journalctl -n 20 -u halo
```
## 版本升级
1. 备份数据，可以参考 [备份与恢复](../../user-guide/backup.md) 进行完整备份（可选，但推荐备份）。
2. 停止 Halo 服务
```bash
service halo stop
```
3. 下载新版本的 Halo 运行包，覆盖原有的运行包
```bash
wget https://dl.halo.run/release/halo-2.20.0.jar -O /home/halo/app/halo.jar
```
4. 启动 Halo 服务
```bash
service halo start
```
## 反向代理
你可以在下面的反向代理软件中任选一项，我们假设你已经安装好了其中一项，并对其的基本操作有一定了解。 如果你对它们没有任何了解，可以参考我们更为详细的反向代理文档：
1. 使用 [Nginx Proxy Manager](../install/other/nginxproxymanager.md)
### Nginx
```nginx {2,7,10}
upstream halo {
server 127.0.0.1:8090;
}
server {
listen 80;
listen [::]:80;
server_name www.yourdomain.com;
client_max_body_size 1024m;
location / {
proxy_pass http://halo;
proxy_set_header HOST $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
```
### Caddy 2
```txt {1,5}
www.yourdomain.com
encode gzip
reverse_proxy 127.0.0.1:8090
```

106
versioned_docs/version-2.20/getting-started/install/offline.md Normal file
View File

@@ -0,0 +1,106 @@
---
title: 离线环境部署
description: 离线环境部署
---
import DockerArgs from "./slots/_docker-args.md"
import DockerRegistryList from "./slots/_docker-registry-list.md"
:::info
在继续操作之前，我们推荐您先阅读[《写在前面》](../prepare.md)，这可以快速帮助你了解 Halo。
:::
Halo 离线安装包使用 Docker + Docker Compose 的方式部署 Halo 及其他服务，安装包中内置了 Docker 程序和容器镜像文件，可以帮助用户在无法访问互联网的服务器上，完成 Halo 的安装部署。
## 下载安装包
请自行前往[飞致云开源社区](https://community.fit2cloud.com/#/products/halo/downloads)下载 Halo 最新版本的安装包，并复制到目标机器的 /tmp 目录下。
## 安装部署
### 解压安装包
以 root 用户 ssh 登录到目标机器, 并执行如下命令：
```bash
cd /tmp
# 解压安装包（halo-offline-installer-v2.17.0-amd64.tar.gz 为示例安装包名称，操作时可根据实际安装包名称替换）
tar zxvf halo-offline-installer-v2.17.0-amd64.tar.gz
```
:::info
安装包目录说明
```text
[root@localhost halo-offline-installer-v2.17.0-amd64]# tree
.
├── docker # 离线安装 Docker 使用到的文件
│   ├── bin
│   │   ├── containerd
│   │   ├── containerd-shim-runc-v2
│   │   ├── ctr
│   │   ├── docker
│   │   ├── docker-compose
│   │   ├── dockerd
│   │   ├── docker-init
│   │   ├── docker-proxy
│   │   └── runc
│   └── service
│   └── docker.service
├── docker-compose.yaml # 包含 Halo 及数据库服务的 Docker Compose 文件
├── .env # Docker Compose 文件使用的变量声明文件，部分参数从该文件中读取
├── images # Halo 及数据库的容器镜像文件
│   ├── halo.tar.gz
│   ├── mysql.tar.gz
│   └── postgres.tar.gz
├── install.sh # 安装脚本
├── LICENSE
└── README.md
```
:::
### 执行安装脚本
```bash
# 进入安装包目录（halo-offline-installer-v2.17.0-amd64 为示例安装包目录名称，操作时可根据实际安装包名称替换）
cd halo-offline-installer-v2.17.0-amd64
# 运行安装脚本
/bin/bash install.sh
```
根据脚本给出的提示，输入安装目录、服务端口、数据库信息等相关配置信息，等待脚本执行完成。
:::info
假设采用默认安装位置 /opt/halo 完成安装，安装目录的文件结构如下：
```text
[root@meter-prototype halo]# tree
.
├── data # 数据存储目录
│   ├── db # 数据库数据存储目录，挂载至数据库容器
│   └── halo # Halo 数据存储目录，挂载至 Halo 容器
│   ├── indices
│   ├── keys
│   ├── logs
│   ├── plugins
│   └── themes
├── docker-compose.yaml # Docker Compose 文件
├── .env # Docker Compose 文件使用的变量声明文件，部分参数从该文件中读取
├── install.log # 安装脚本日志文件
├── LICENSE
└── README.md
```
安装完成后，可以直接进入 /opt/halo 目录，使用 docker-compose 命令完成后续维护操作，也可以修改 docker-compose.yaml 中的相关配置满足不同需求。
运行参数详解：
<DockerArgs />
:::
### 登录访问
用浏览器访问 /console 即可进入 Halo 管理页面，首次启动会进入初始化页面。

164
versioned_docs/version-2.20/getting-started/install/other/nginxproxymanager.md Normal file
View File

@@ -0,0 +1,164 @@
---
title: 与 Nginx Proxy Manager 配合使用
description: 使用 Nginx Proxy Manager 管理 Halo 服务的反向代理
---
## Halo 部署
参见 [使用 Docker Compose 部署](../docker-compose)
:::info
`「反向代理」` 部分不进行操作，保证 Halo 服务运行无误即可。
:::
## 简介
顾名思义，Nginx Proxy Manager 就是一个 Nginx 的代理管理器，它最大的特点是简单方便。
即使是没有 Nginx 基础的小伙伴，也能轻松地用它来完成反向代理的操作，而且因为自带面板，操作极其简单，非常适合配合 docker 搭建的应用使用。
Nginx Proxy Manager 后台还可以一键申请 SSL 证书，并且会自动续期，方便省心。
下面我们就来介绍如何用 Nginx Proxy Manger 来配合 Halo，实现反向代理和 HTTPS 访问。
## 安装 Nginx Proxy Manager
> 说明：默认你的服务器已经安装了 Docker 和 Docker Compose，如果你没有安装，可以参考：[使用 Docker Compose 部署](../docker-compose) 的环境搭建部分来进行安装。
点击下方链接进入 Nginx Proxy Manager（以下简称 NPM） 官网：[https://nginxproxymanager.com/](https://nginxproxymanager.com/)
我们可以直接选择 [快速安装](https://nginxproxymanager.com/guide/#quick-setup)。
首先，我们创建一个文件夹来存放 NPM 的 `docker-compose.yml` 文件：
```bash
mkdir -p ~/data/docker_data/nginxproxymanager # 创建一个 npm 的文件夹
cd ~/data/docker_data/nginxproxymanager # 进入该文件夹
vi docker-compose.yml
```
在英文状态的输入法下，按下 `i`，左下角出现 `--INSERT--` 后，粘贴填入下面的内容：
```yaml
version: '3'
services:
app:
image: 'jc21/nginx-proxy-manager:latest'
restart: unless-stopped
ports:
- '80:80' # 不建议修改端口
- '81:81' # 可以把冒号左边的 81 端口修改成你服务器上没有被占用的端口
- '443:443' # 不建议修改端口
volumes:
- ./data:/data # 点号表示当前文件夹，冒号左边的意思是在当前文件夹下创建一个 data 目录，用于存放数据，如果不存在的话，会自动创建
- ./letsencrypt:/etc/letsencrypt # 点号表示当前文件夹，冒号左边的意思是在当前文件夹下创建一个 letsencrypt 目录，用于存放证书，如果不存在的话，会自动创建
```
> 注意：安装了 NPM 之后，就不需要再安装 Nginx 了，否则会端口冲突（不建议修改 NPM 的 80、443 端口）。如果你的服务器安装了宝塔面板，也可以和 NPM 一起使用，只要你到软件后台把宝塔安装的 Nginx 关闭或者卸载即可。
之后，同样在英文输入法下，按一下 `esc`，然后 `:wq` 保存退出。
启动 NPM：
```bash
docker-compose up -d # -d 表示后台运行
docker compose up -d # 如果你用的是 docker-compose-plugin 的话，用这条命令
```
不出意外，此时你使用 [http://127.0.0.1:81](http://127.0.0.1:81/) 就可以访问 NPM 的网页端了。（注意把 `127.0.0.1` 替换成你实际服务器的 IP）
:::info
1. 不知道服务器 IP，可以直接在命令行输入：curl ip.sb，会显示当前服务器的 IP。
2. 遇到访问不了的情况，请再次检查在宝塔面板的防火墙和服务商的后台防火墙是否打开对应了端口。
:::
默认登录的用户名：`admin@example.com` 密码：`changeme`
第一次登录会提示更改用户名和密码，建议修改一个复杂一点的密码。
至此，我们已经完成了 Nginx Proxy Manager 的搭建，之后就可以用它给我们的 Halo 或者其他 Web 应用做反向代理了。
## 配置 Halo 的反向代理
首先我们登录网页端之后，会弹出修改用户名和密码的对话框，我们根据自己的实际来修改自己的用户名和邮箱。
![Nginx Proxy Manager 1](/img/nginx-proxy-manager/Nginx-Proxy-Manager-1.png)
保存之后，会让我们修改密码（建议用一个复杂的密码）。
![Nginx Proxy Manager 2](/img/nginx-proxy-manager/Nginx-Proxy-Manager-2.png)
接着我们就可以来给 Halo 来添加一个反向代理了。
点击 `Proxy Hosts`，
![Nginx Proxy Manager 3](/img/nginx-proxy-manager/Nginx-Proxy-Manager-3.png)
接着点击 `Add Proxy Host`，弹出如下对话框：
![Nginx Proxy Manager 4](/img/nginx-proxy-manager/Nginx-Proxy-Manager-4.png)
看起来都是英文，很复杂，但是其实很简单，我们只要用到其中的几个功能即可，这边稍微解释一下：
- `Domain Names` ：填我们 Halo 网站的域名，首先记得做好 DNS 解析，把域名绑定到我们的服务器的 IP 上
- `Scheme` ：默认 `http` 即可，除非你有自签名证书
- `Forward Hostname/IP` ：填入服务器的 IP，或者 Docker 容器内部的 IP（如果 NPM 和 Halo 搭建在同一台服务器上的话）
- `Forward Port`：填入 Halo 映射出的端口，这边默认是 `8090`
- `Cache Assets` ：缓存，可以选择打开
- `Block Common Exploits`： 阻止常见的漏洞，可以选择打开
- `Websockets Support` ：WS 支持，可以选择打开
- `Access List`： 这个是 NPM 自带的一个限制访问功能，这边我们不管，后续可以自行研究。
以下是一个样列：
![Nginx Proxy Manager 5](/img/nginx-proxy-manager/Nginx-Proxy-Manager-5.png)
因为样例的 NPM 和 Halo 搭建在同一台 VPS 上，所以这边的 IP，图中填的是 `172.17.0.1`，为 Docker 容器内部的 IP 地址，
可以通过下面的命令查询：
```bash
ip addr show docker0
```
```bash {3}
4: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default
link/ether 02:42:e4:a3:b5:b9 brd ff:ff:ff:ff:ff:ff
inet 172.17.0.1/16 brd 172.17.255.255 scope global docker0
valid_lft forever preferred_lft forever
```
这边的 IP 是 `172.17.0.1`，填入这个 IP，可以不用打开防火墙的 `8090` 端口。
当然，如果你的 NPM 和 Halo 不在同一台服务上，你需要在 IP 部分填入 **你的 Halo 所在的服务器的 IP**，并在服务商（部分服务商如腾讯、阿里）的后台打开 `8090` 端口。
## 一键申请 SSL 证书
接着我们来申请一张 SSL 证书，让我们的网站支持 `https` 访问。
![Nginx Proxy Manager 6](/img/nginx-proxy-manager/Nginx-Proxy-Manager-6.png)
![Nginx Proxy Manager 7](/img/nginx-proxy-manager/Nginx-Proxy-Manager-7.png)
如图所示，记得打开强制 SSL，其他四个的功能请自行研究，这边不多做讨论。
:::info
1. 申请证书需要你提前将域名解析到 NPM 所在的服务器的 IP 上；
2. 如果你使用的是国内的服务器，默认 `80` 和 `443` 端口是关闭的，你需要备案之后才能使用；
3. 如果你使用了 CloudFlare 的 DNS 服务，记得把小黄云关闭（即不开启 CDN）。
:::
不出意外，你将成功申请到 SSL 证书，证书会三个月自动续期。
再次点开配置，查看一下，将强制 SSL 打开。
![Nginx Proxy Manager 8](/img/nginx-proxy-manager/Nginx-Proxy-Manager-8.png)
至此，你已经成功完成了 Halo 的反向代理，快尝试使用域名访问一下看看吧！
> 同样的，举一反三，试试把你的 NPM 也用一个域名来反向代理一下吧。(小提示：你需要再解析一个域名（可以是二级域名）到 NPM 所在的服务器上，反代页面需要填的 IP 可以填 docker 容器内的 IP 也可以填服务器的 IP，端口填 `81` 即可）

117
versioned_docs/version-2.20/getting-started/install/other/traefik.md Normal file
View File

@@ -0,0 +1,117 @@
---
title: 与 Traefik 配合使用
description: 使用 Traefik 管理 Halo 服务的反向代理
---
## Halo 部署
参见 [使用 Docker Compose 部署](../docker-compose.md)
:::info
`「反向代理」` 部分不进行操作，保证 Halo 服务运行无误即可。
:::
## 简介
[Traefik](https://traefik.io/traefik/) 是一款开源的反向代理与负载均衡工具，它监听后端的变化并自动更新服务配置。
它与传统反向代理最大的区别，是支持声明式的动态路由规则，大大简化网关规则的配置。而且还有诸多实用特性，例如：健康检查、多实例负载均衡、能够实现 Let's Encrypt 证书的自动签发、验证与续期等等。
## 创建 Traefik
下面的配置中，创建了 Traefik 实例。并且做了基础的几项配置：
1. 监听了宿主机的 80、443 端口，并自动将 80 端口的请求重定向到 443 端口。[文档](https://doc.traefik.io/traefik/routing/entrypoints/)
2. 开启 Docker 服务发现，监听检测 Docker 容器声明的服务关系。[文档](https://doc.traefik.io/traefik/providers/docker/#provider-configuration)
3. 开启 Traefik Dashboard，建议使用二级域名的形式（示例：`traefik.yourdomain.com`）。[文档](https://doc.traefik.io/traefik/operations/dashboard/#dashboard-router-rule)
4. 开启证书自动生成，通过 ACME 自动管理 TLS 证书的申请、校验与续期。[文档](https://doc.traefik.io/traefik/https/acme/)
:::warning
ACME 证书 (`/acme.json`) 一定要 [持久化](https://doc.traefik.io/traefik/https/acme/#storage)，否则每次重启 Traefik 服务，都会去申请签发证书。可能会触发 Let's
Encrypt 的 [速率限制](https://letsencrypt.org/zh-cn/docs/rate-limits/)，导致签名的域名一段时间内无法签发新的证书。
:::
```yaml {19,31,35,41} showLineNumbers
version: "3.8"
networks:
traefik:
name: traefik
attachable: true
services:
traefik:
image: traefik:v2.9
container_name: traefik
networks:
- traefik
ports:
- "80:80"
- "443:443"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./acme.json:/acme.json
command: >
--api.dashboard=true
--entrypoints.web.address=:80
--entrypoints.websecure.address=:443
--entrypoints.web.http.redirections.entrypoint.to=websecure
--entrypoints.web.http.redirections.entrypoint.scheme=https
--providers.docker=true
--providers.docker.endpoint=unix:///var/run/docker.sock
--providers.docker.watch=true
--providers.docker.exposedByDefault=false
--certificatesResolvers.myresolver.acme.httpChallenge.entryPoint=web
--certificatesresolvers.myresolver.acme.email=your-mail@mail.com
labels:
traefik.enable: "true"
traefik.docker.network: traefik
traefik.http.routers.dashboard.rule: Host(`traefik.yourdomain.com`)
traefik.http.routers.dashboard.tls: "true"
traefik.http.routers.dashboard.tls.certresolver: myresolver
traefik.http.routers.dashboard.service: "api@internal"
traefik.http.routers.dashboard.middlewares: auth
# 账号密码 admin/P@88w0rd 生成 echo $(htpasswd -nb user password) | sed -e s/\\$/\\$\\$/g
traefik.http.middlewares.auth.basicauth.users: "admin:$$apr1$$q8q0qpzT$$lvzMP7VYd9EUcG/wkIsAN."
```
## 配置 Halo 的反向代理
这里以最简配置（h2 数据库）Halo 服务的 Docker 配置举例。只需做以下调整：
1. 顶层 `networks` 中添加了外部网络 `traefik`
2. `services.halo.networks` 中添加了 `traefik` 网络
3. `services.halo.labels` 中声明了 Traefik 配置
1. 路由规则为 `yourdomain.com`
2. 开启 TLS
3. 指定了服务端口为 8090
```yaml {4-5,16,20,25-31} showLineNumbers
version: "3.8"
networks:
traefik:
external: true
halo:
services:
halo:
image: registry.fit2cloud.com/halo/halo:2.20
container_name: halo
restart: on-failure:3
volumes:
- ./halo2:/root/.halo2
networks:
- traefik
- halo
command:
# 外部访问地址，请根据实际需要修改
- --halo.external-url=https://yourdomain.com
labels:
traefik.enable: "true"
traefik.docker.network: traefik
traefik.http.routers.halo.rule: Host(`yourdomain.com`)
traefik.http.routers.halo.tls: "true"
traefik.http.routers.halo.tls.certresolver: myresolver
traefik.http.services.halo.loadbalancer.server.port: 8090
```

224
versioned_docs/version-2.20/getting-started/install/podman.md Normal file
View File

@@ -0,0 +1,224 @@
---
title: 使用 Podman 部署
description: 使用 Podman 部署
---
import DockerArgs from "./slots/_docker-args.md"
import DockerRegistryList from "./slots/_docker-registry-list.md"
## 前言
:::info
在继续操作之前，我们推荐您先阅读[《写在前面》](../prepare)，这可以快速帮助你了解 Halo。
:::
:::info
什么是 Podman ?
Podman（全称 POD 管理器）是一款用于在 Linux® 系统上开发、管理和运行容器的开源工具。Podman 最初由红帽® 工程师联合开源社区一同开发，它可利用 lipod 库来管理整个容器生态系统。
Podman 采用无守护进程的包容性架构，因此可以更安全、更简单地进行容器管理，再加上 Buildah 和 Skopeo 等与之配套的工具和功能，开发人员能够按照自身需求来量身定制容器环境。
为什么选择 Podman 而不是 Docker ?
这个需要视情况而定, 如果您的主机配置不是很高, 您使用 Docker 时, 因为 Docker 自带的守护进程可能会雪上加霜, 它会大量占用您的资源。
而 Podman 采用无守护进程架构，而且容器是无根模式，您可以在占用资源极小的情况下运行镜像，并且获得很高的安全性。
而且 Podman 与 Docker 高度兼容，您不需要做特别配置即可将 Docker 容器运行在Podman 上。
[什么是 Podman?](https://www.redhat.com/zh/topics/containers/what-is-podman)
[Podman ArchWiki](https://wiki.archlinux.org/title/Podman)
[Podman 官网](https://podman.io/)
:::
:::tip
此文档提供使用默认 H2 数据库和 Postgresql 数据库的 Podman 运行示例，在生产环境我们不推荐使用 H2 数据库。
:::
## 环境搭建
- Podman 安装文档：[https://podman.io/docs/installation](https://podman.io/docs/installation)
:::tip
我们推荐您先阅读 Podman 官方文档对 Podman 有了相关了解后，再考虑通过Linux包管理系统安装 Podman 或者使用文档中指定的方式安装 。
:::
## 使用 Docker 镜像
:::tip
为什么是 Docker 镜像?
通过[前言](#前言)我们已经了解了 Podman ，其中提到 ***Podman 与 Docker 高度兼容*** ，正是因为 Podman 完全是为了替代 Docker 而诞生，所以原本的 Docker 生态中的镜像我们可以无需更改直接使用。
:::
<DockerRegistryList />
1. 创建容器
```bash
mkdir -p ~/.halo2
podman run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 registry.fit2cloud.com/halo/halo:2.20
```
:::info
注意：此命令默认使用自带的 H2 Database 数据库。如需使用 PostgreSQL，请参考：[使用 Docker Compose 部署](./docker-compose)
:::
- **-it**：开启输入功能并连接伪终端
- **-d**：后台运行容器
- **--name**：为容器指定一个名称
- **-p**：端口映射，格式为 `主机(宿主)端口:容器端口` ，可在 `application.yaml` 配置。
- **-v**：工作目录映射。形式为：`-v 宿主机路径:/root/.halo2`，后者不能修改。
运行参数详解：
<DockerArgs />
2. 用浏览器访问 `/console` 即可进入 Halo 管理页面，首次启动会进入初始化页面。
:::tip
如果需要配置域名访问，建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip:端口号` 的形式无法访问，请到服务器厂商后台将运行的端口号添加到安全组，如果服务器使用了 Linux 面板，请检查此 Linux 面板是否有还有安全组配置，需要同样将端口号添加到安全组。
:::
## 升级版本
1. 备份数据，可以参考 [备份与恢复](../../user-guide/backup.md) 进行完整备份（可选，但推荐备份）。
2. 拉取新版本镜像
```bash
podman pull registry.fit2cloud.com/halo/halo:2.20
```
3. 停止运行中的容器
```bash
podman stop halo
podman rm halo
```
4. 更新 Halo
修改版本号后，按照最初安装的方式，重新创建容器即可。
```bash
podman run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 registry.fit2cloud.com/halo/halo:2.20
```
## 使用 [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html)
:::tip
Podman 没有和 Docker 类似的管理进程，在低配置的主机上更友好。
但是使用 Podman 想要开机后自动启动，官方推荐一种和 systemd 服务类似的语法文件，即 Podman Quadlet。
:::
下面是一个使用 Podstgresql 数据库的示例:
```bash
mkdir -p /opt/podman-data/halo
mkdir -p /etc/containers/systemd
vim /etc/containers/systemd/halo.container
```
```conf
[Unit]
Description=The halo container
Wants=network-online.target
After=network-online.target
[Container]
AutoUpdate=registry
ContainerName=halo
User=60000
Group=60000
UserNS=keep-id:uid=60000,gid=60000
Environment=JVM_OPTS="-Xmx512m -Xms256m"
Environment=HALO_WORK_DIR="/.halo"
Environment=SPRING_CONFIG_LOCATION="optional:classpath:/;optional:file:/.halo/"
Environment=TZ=Asia/Shanghai
Volume=/opt/podman-data/halo:/.halo
PublishPort=127.0.0.1:8090:8090
Image=ghcr.io/halo-dev/halo:2.20
Exec=--halo.external-url=https://localhost:8090 --spring.sql.init.platform=postgresql --spring.r2dbc.url=r2dbc:pool:postgresql://127.0.0.1:5432/my-db --spring.r2dbc.username=my-user --spring.r2dbc.password=my-password
[Service]
Restart=always
RestartSec=30s
StartLimitInterval=30
TimeoutStartSec=900
TimeoutStopSec=70
[Install]
WantedBy=multi-user.target default.target
```
```bash
systemctl daemon-reload
systemctl start halo
# 只需要systemctl start halo.
# 之后重启会自动启动不需要enable服务.
```
Podman Quadlet 解析:
`[Unit]` 部分:
- Wants和After字段指定了Halo在什么服务后启动。
`[Container]` 部分:
- `AutoUpdate=registry`指定了自动拉取容器。假设后续Halo镜像支持了`latest`标签，你需要`systemctl enable --now podman-auto-update.timer`以启用容器自动更新。本文示例`ghcr.io/halo-dev/halo:2.20`，将会自动更新适用与`2.20`版本的patch，例如您创建容器时是`2.20.1`，在官方发布`2.20.2`版本时，容器会自动更新到`2.20.2`。
- `ContainerName=`指定了 systemd 将生成的服务名称。
- `User=60000 Group=60000 UserNS=keep-id:uid=60000,gid=60000` 限制容器以 id 60000 的用户运行，提高安全性。注意这个id 60000请根据你实际想要运行的用户名来修改，可通过`id user`获得你的用户的id.
- `Environment=`字段指定了容器的环境变量，其中你需要注意的是`Environment=HALO_WORK_DIR="/.halo"` `Environment=SPRING_CONFIG_LOCATION="optional:classpath:/;optional:file:/.halo/"`这两个变量中的`/.halo`路径。
- `Volume=`字段指定挂载到容器储存Halo配置文件的路径，请仔细观察`/opt/podman-data/halo:/.halo`其中的`/.halo`要与上面需要注意的环境变量路径要一致。
- `PublishPort=`和docker -p命令一致，即需要映射的端口。
- `Image=ghcr.io/halo-dev/halo` 即Docker镜像的地址，注意要完整的。比如`ghcr.io`这个路径就不能少，如果你没有配置 Podman 的 registries 文件，此路径就必不可少，建议写全。
- `Exec=` 即附加到Halo容器的 Command ，具体变量参考上方的 DockerArgs 。多个变量以空格分开。
`[Service]` 部分:
即原生systemd语法
- `Restart` 指定遇到错误后总是重启容器
- `RestartSec` 重启的间隔时间
- `StartLimitInterval` 重启的次数，超过这个次数将不再重启。
- `TimeoutStartSec` 启动容器的超时时间，建议不要修改，因为每次开机后 Podman 将自动拉取容器，这时也许耗时会很长，这些时间是算在启动时间中的。如果定义太小的时间，可能将导致 Podman 无法拉取容器镜像。
- `TimeoutStopSec` 停止容器时的超时时间，`systemctl stop halo` 假设使用这个命令，如果停止时间超过了`TimeoutStopSec`定义的时间，将会被系统Kill.
`[Install]` 部分:
此部分请查看systemd文档，不建议修改。
使用默认的 root 用户运行时无需定义 `User=60000 Group=60000 UserNS=keep-id:uid=60000,gid=60000` 与 `Environment=HALO_WORK_DIR="/.halo"` `Environment=SPRING_CONFIG_LOCATION="optional:classpath:/;optional:file:/.halo/"`，
示例:
```bash
mkdir -p /opt/podman-data/halo
mkdir -p /etc/containers/systemd
vim /etc/containers/systemd/halo.container
```
```conf
# /etc/containers/systemd/halo.container
[Unit]
Description=The halo container
Wants=network-online.target
After=network-online.target
[Container]
AutoUpdate=registry
ContainerName=halo
Volume=/opt/podman-data/halo:/root/.halo
PublishPort=127.0.0.1:8090:8090
Image=ghcr.io/halo-dev/halo:2.20
Exec=--halo.external-url=https://localhost:8090 --spring.sql.init.platform=postgresql --spring.r2dbc.url=r2dbc:pool:postgresql://127.0.0.1:5432/my-db --spring.r2dbc.username=my-user --spring.r2dbc.password=my-password
[Service]
Restart=always
RestartSec=30s
StartLimitInterval=30
TimeoutStartSec=900
TimeoutStopSec=70
[Install]
WantedBy=multi-user.target default.target
```

16
versioned_docs/version-2.20/getting-started/install/slots/_docker-args.md Normal file
View File

@@ -0,0 +1,16 @@
| 参数名 | 描述 |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spring.r2dbc.url` | 数据库连接地址，详细可查阅下方的 `数据库配置` |
| `spring.r2dbc.username` | 数据库用户名 |
| `spring.r2dbc.password` | 数据库密码 |
| `spring.sql.init.platform` | 数据库平台名称，支持 `postgresql`、`mysql`、`mariadb`、`h2` |
| `halo.external-url` | 外部访问链接，如果需要在公网访问，需要配置为实际访问地址 |
数据库配置：
| 链接方式 | 链接地址格式 | `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 |

15
versioned_docs/version-2.20/getting-started/install/slots/_docker-registry-list.md Normal file
View File

@@ -0,0 +1,15 @@
目前 Halo 官方维护的 Docker 镜像仓库，可以根据自己的需求选择合适的镜像源：
- registry.fit2cloud.com/halo/halo
- [halohub/halo](https://hub.docker.com/r/halohub/halo)
- [ghcr.io/halo-dev/halo](https://github.com/halo-dev/halo/pkgs/container/halo)
:::info 注意
目前 Halo 2 并未更新 Docker 的 latest 标签镜像，主要因为 Halo 2 不兼容 1.x 版本，防止使用者误操作。我们推荐使用固定版本的标签，比如 `2.20` 或者 `2.20.0`。
- `registry.fit2cloud.com/halo/halo:2`：表示最新的 2.x 版本，即每次发布新版本都会更新此镜像。
- `registry.fit2cloud.com/halo/halo:2.20`：表示最新的 2.20.x 版本，即每次发布 patch 版本都会同时更新此镜像。
- `registry.fit2cloud.com/halo/halo:2.20.0`：表示一个具体的版本。
后续文档以 `registry.fit2cloud.com/halo/halo:2.20` 为例。
:::

80
versioned_docs/version-2.20/getting-started/migrate-from-1.x.md Normal file
View File

@@ -0,0 +1,80 @@
---
title: 从 Halo 1.x 迁移
description: 从 Halo 1.x 迁移的完整指南和注意事项
---
因为 Halo 2.0 的底层架构变动，无法兼容 1.x 的数据，导致无法平滑升级，所以需要进行数据迁移。为此，我们提供了从 Halo 1.5 / 1.6 版本迁移的插件。在进行迁移之前，**有几点注意事项和要求，如果你目前无法满足，建议先暂缓迁移。**
- Halo 版本必须为 1.5.x 或 1.6.x。如果不满足，需要先升级到 1.5.x 或 1.6.x 版本。
- Halo 2.0 不兼容 1.x 的主题，建议在升级前先查询你正在使用的主题是否已经支持 2.0。你可以访问 [halo-sigs/awesome-halo](https://github.com/halo-sigs/awesome-halo) 或 [应用市场](https://halo.run/store/apps?type=THEME) 查阅目前支持的主题。
- Halo 2.0 目前没有内置 Markdown 编辑器，如果需要重新编辑迁移后的文章，需要额外安装 Markdown 编辑器插件。目前社区已经提供了以下插件：
- StackEdit：[https://halo.run/store/apps/app-hDXMG](https://halo.run/store/apps/app-hDXMG)
- ByteMD：[https://halo.run/store/apps/app-HTyhC](https://halo.run/store/apps/app-HTyhC)
- Halo 2.0 不再内置友情链接、日志、图库等模块，需要安装额外的插件，目前官方已提供：
- 链接管理：[https://halo.run/store/apps/app-hfbQg](https://halo.run/store/apps/app-hfbQg)
- 图库：[https://halo.run/store/apps/app-BmQJW](https://halo.run/store/apps/app-BmQJW)
- 瞬间（原日志）：[https://halo.run/store/apps/app-SnwWD](https://halo.run/store/apps/app-SnwWD)
- Halo 2.0 不再内置外部云存储的支持。需要安装额外的插件，目前官方已提供：
- S3（兼容国内主流的云存储）：[https://halo.run/store/apps/app-Qxhpp](https://halo.run/store/apps/app-Qxhpp)
- 阿里云 OSS：[https://halo.run/store/apps/app-wCJCD](https://halo.run/store/apps/app-wCJCD)
- 在迁移过程中不会保留旧版本的用户数据，迁移完成之后，关于文章等数据的关联都将改为 Halo 2.0 的新用户。
- 为了防止直接升级 2.0 导致 1.x 的数据受到破坏，我们已经将工作目录由 `~/.halo` 变更为 `~/.halo2`。
- 目前 Halo 2.0 仅提供 Docker 部署方式，没有提供可执行 JAR 包，但可以自编译，请参考 [构建](../developer-guide/core/build.md) 文档
- 可以考虑先在本地运行一个 Halo 2.0，模拟一下导入，检查导入后是否满足要求。
如果遇到了迁移过程中的问题，也可以向我们提交 Issue: [https://github.com/halo-dev/halo/issues/new/choose](https://github.com/halo-dev/halo/issues/new/choose)，以上暂不支持的功能我们也会陆续完善。
## 备份数据
在进行迁移操作之前，我们强烈建议先**完整备份所有数据**，可以参考 [备份迁移](https://v1.legacy-docs.halo.run/user-guide/backup-migration) 进行整站备份。
## 导出数据文件
在 Halo 1.5.x / 1.6.x 后台的小工具中提供了数据导出的功能，将最新的数据进行备份，然后下载即可。这个数据文件包含了数据库所有的数据，后续我们在 2.0 的导入插件中就是通过这个文件进行数据导入。
![halo-data-export.png](/img/halo-data-export.png)
## 部署 Halo 2.0
可以参考以下文档进行部署：
- [使用 Docker 部署](./install/docker.md)
- [使用 Docker Compose 部署](./install/docker-compose.md)
:::tip
可以考虑暂时保留旧版本的 Halo，等到迁移完成之后再移除。如果需要保留旧版本的 Halo，请注意在部署 Halo 2.0 的时候使用其他端口，然后在反向代理（Nginx）中修改为 Halo 2.0 的运行端口即可。
:::
## 移动附件
- 本地存储的附件，只需要将 1.x 工作目录的 `upload` 目录里面的所有文件夹移动到 2.0 工作目录下的 `attachments/migrate-from-1.x` 文件夹即可。
- 云存储的附件迁移会在迁移插件中进行。
## 安装插件
在迁移过程中，需要提前安装必要的插件：
- 站点迁移：[https://halo.run/store/apps/app-TlUBt](https://halo.run/store/apps/app-TlUBt)
- 链接管理：[https://halo.run/store/apps/app-hfbQg](https://halo.run/store/apps/app-hfbQg)
- 图库：[https://halo.run/store/apps/app-BmQJW](https://halo.run/store/apps/app-BmQJW)
- 瞬间（原日志）：[https://halo.run/store/apps/app-SnwWD](https://halo.run/store/apps/app-SnwWD)
- S3（如果需要迁移存在云存储的附件，需要安装）：[https://halo.run/store/apps/app-Qxhpp](https://halo.run/store/apps/app-Qxhpp)
## 配置存储策略
> 如果在 Halo 1.x 中未使用云存储，可以跳过此步骤。
1. 安装 S3 插件。
2. 进入附件管理页面。
3. 点击页面右上角的 **存储策略** 按钮。
4. 创建存储策略，选择 **S3 Object Storage**。
5. 填写相关配置，点击 **保存** 即可。
## 迁移
![Migrate Plugin](/img/migrate/halo2.0-migrate-plugin.png)
1. 点击左侧菜单的迁移进入迁移页面。
2. 点击 **选择文件** 按钮，选择在 Halo 1.5.x / 1.6.x 导出的数据文件（JSON 格式）。
3. 如果在 1.x 中使用了云存储，会弹出选择云存储的对话框，选择之前创建的存储策略即可。
4. 最后点击页面下方的 **执行导入** 即可。

124
versioned_docs/version-2.20/getting-started/prepare.md Normal file
View File

@@ -0,0 +1,124 @@
---
title: 写在前面
description: 在开始前，你需要了解的事项
---
## 环境要求
这里将讲述运行 Halo 所要求的一些软硬件的配置，我们建议你在运行或者部署之前先浏览一遍此页面。
### 硬件配置
:::tip
如果你要使用服务器进行部署 Halo，需要注意的是，Halo 目前不支持市面上的云虚拟主机，请使用云服务器或者 VPS。
如果你还未购买服务器，可以考虑[通过我们的推广链接购买服务器](../contribution/sponsor.md#通过我们的推广链接购买服务器)。
:::
#### CPU
无特别要求。目前我们的 [Docker 镜像](https://hub.docker.com/r/halohub/halo) 也已经支持多平台。
#### 内存
为了获得更好的体验，我们建议至少配置 1G 的 RAM。
#### 磁盘
无特别要求，理论上如果不大量在服务器上传附件，Halo 对磁盘的容量要求并不是很高。但我们推荐最好使用 SSD 硬盘的服务器，能更快的运行 Halo。
#### 网络
无特别要求，Halo 目前可以在无公网环境下使用，但部分主题由于使用了第三方资源，可能需要公网环境。
### 软件环境
Halo 理论上可以运行在任何支持 Docker 及 Java 的平台。
#### Docker（可选）
我们主要推荐使用 Docker 运行 Halo，这可以避免一些环境配置相关的问题，文档可参考：
- [使用 Docker Compose 部署](./install/docker-compose.md)
- [使用 Docker 部署](./install/docker.md)
#### JRE（可选）
如果使用 Docker 镜像部署，那么无需在服务器上安装 JRE。但目前我们也提供了 jar 文件部署的方式，文档可参考：
- [使用 JAR 文件部署](./install/jar-file.md)
:::info
当前版本（2.0）需要 JRE 17 的版本，推荐使用 OpenJDK 17。
:::
#### 数据库
Halo 目前支持以下数据库：
- PostgreSQL
- MySQL
- MariaDB
- H2
其中，H2 不需要单独运行，其他数据库需要单独安装并配置。一般情况下，推荐按照 [使用 Docker Compose 部署](./install/docker-compose.md) 文档将 Halo 和数据库容器编排在一起。
:::warning
不推荐在生产环境使用默认的 H2 数据库，这可能因为操作不当导致数据文件损坏。如果因为某些原因（如内存不足以运行独立数据库）必须要使用，建议按时[备份数据](../user-guide/backup.md)。
:::
#### Web 服务器（可选）
如果你部署在生产环境，那么你很可能需要进行域名绑定，这时候我们推荐使用诸如 [Nginx](http://nginx.org/)、[Caddy](https://caddyserver.com/) 之类的 Web 服务器进行反向代理。但需要注意的是，目前 Halo 不支持代理到子目录（如：halo.run/blog）。
#### Wget（可选）
后续的文档中，我们会使用 wget 为例，用于下载所需要的文件，所以请确保服务器已经安装好了这个软件包。当然，下载文件不限制工具，如果你对其他工具熟悉，可以忽略。
#### VIM（可选）
后续的文档中，我们会使用 vim 为例，用于修改一些必要的配置文件，所以同样请确保服务器已经安装了这个软件包。当前，修改文档也不限制工具，如果你对其他编辑软件熟悉，也可以忽略。
## 浏览器支持
1. 用户前台：视主题所支持的情况而定。
2. 管理后台（Console 和个人中心）：支持目前常见的现代浏览器，具体视 [Vue](https://vuejs.org/about/faq#what-browsers-does-vue-support) 框架的支持情况而定。
## 名词解释
这里将列出后续文档中一些和 Halo 相关的名词含义。
### ~（符号）
代表当前系统下的 [用户目录](https://zh.wikipedia.org/wiki/%E5%AE%B6%E7%9B%AE%E5%BD%95)。
### 镜像
指 Halo 构建所产生的 [Docker 镜像](https://docs.docker.com/engine/reference/commandline/images/)。用户通过该镜像启动 Halo 应用。
### 工作目录
指 Halo 所依赖的工作目录，在 Halo 运行的时候会在系统当前用户目录下产生一个 `.halo2` 的文件夹，绝对路径为 `~/.halo2`。里面通常包含下列目录或文件：
1. `db`：存放 H2 Database 的物理文件，如果你使用其他数据库，那么不会存在这个目录。
2. `themes`：里面包含用户所安装的主题。
2. `plugins`：里面包含用户所安装的插件。
5. `attachments`：附件目录。
4. `logs`：运行日志目录。
6. `application.yaml`：配置文件。
7. `backups`：备份文件目录。
8. `static`：虚拟的根文件目录，需要手动创建。
> 如果你使用的 Docker 部署，请不要忽略 `~/.halo2` 的目录映射。
### 主题
包含了各种站点页面模板的资源包。用户访问 Halo 站点浏览到的内容及样式，由 Halo 管理端所配置使用的主题所决定。
相关使用文档：[主题管理相关功能说明](../user-guide/themes.md)
### 插件
用于扩展 Halo 功能的软件包。插件独立于 Halo 核心应用，可以单独安装、升级、卸载。
相关使用文档：[插件管理相关功能说明](../user-guide/plugins.md)

18
versioned_docs/version-2.20/getting-started/setup.md Normal file
View File

@@ -0,0 +1,18 @@
---
title: 初始化
description: 首次安装的初始化指南
---
通过之前的安装文档，你已经成功安装了 Halo，在首次访问网站的时候会自动跳转到初始化页面，你需要完成这个步骤才能正常使用 Halo。
![Setup](/img/setup/setup.png)
表单项说明：
1. **站点名称**：网站的名称，将会显示在浏览器标签页上。
2. **邮箱**：初始管理员的邮箱地址。
3. **用户名**：初始管理员的用户名。
4. **密码**：初始管理员的密码。
5. **确认密码**：重复输入密码以验证是否匹配。
输入完成之后点击**初始化**按钮即可完成初始化，初始化完成之后，将会跳转到登录页面，输入刚才设置的用户名和密码即可登录。