mirror of
https://github.com/halo-dev/docs.git
synced 2025-10-21 10:17:34 +00:00
docs: update documentation for Halo 2.3 (#196)
为 Halo 2.3 更新文档。 /kind documentation ```release-note None ```
This commit is contained in:
Ryan Wang
238
versioned_docs/version-2.3/getting-started/config.md
Normal file
238
versioned_docs/version-2.3/getting-started/config.md
Normal file
@@ -0,0 +1,238 @@
|
||||
---
|
||||
title: 配置参考
|
||||
description: Halo 配置文件的详细介绍及参考
|
||||
---
|
||||
|
||||
Halo 的配置文件名为 `application.yaml`，其必须位于[工作目录](/getting-started/prepare#工作目录) `~/.halo` 下。 Halo 会读取该目录下的配置文件进行加载。
|
||||
|
||||
:::info
|
||||
如果您是单独下载的官方配置文件，则必须将文件名 application-template.yaml 重命名为 application.yaml
|
||||
:::
|
||||
|
||||
如下将详细列出配置文件 `application.yaml` 中所有的配置项。
|
||||
|
||||
## 基础配置
|
||||
|
||||
基础配置中的配置设置一般来说是**必要的**，且必须在 application.yaml 里进行定义。
|
||||
|
||||
### 端口
|
||||
|
||||
用于指定 HTTP 服务器监听的端口，Halo 默认设置为 `8090`。
|
||||
|
||||
```yaml
|
||||
server:
|
||||
port: 8090
|
||||
```
|
||||
|
||||
请注意，如果您选择设置端口为 `80`，则需要确保您的 80 端口未被占用，通常**不建议**直接设置为 80 端口。
|
||||
|
||||
### 数据库
|
||||
|
||||
Halo 目前支持 `H2` 及 `MySQL` 数据库。
|
||||
|
||||
:::tip
|
||||
得益于我们使用的 ORM 框架，Halo 在首次启动的时候会自动根据实体类创建表结构，无需通过 SQL 脚本自行创建，也不会提供所谓的 SQL 脚本。所以，此步骤仅需配置好数据库连接地址和用户名密码即可。注意，H2 无需手动创建数据库，MySQL 需要。
|
||||
:::
|
||||
|
||||
#### H2
|
||||
|
||||
:::info
|
||||
推荐使用 **H2**，较其他数据库来说更为方便。
|
||||
:::
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
datasource:
|
||||
driver-class-name: org.h2.Driver
|
||||
url: jdbc:h2:file:~/.halo/db/halo
|
||||
username: admin
|
||||
password: 123456
|
||||
h2:
|
||||
console:
|
||||
settings:
|
||||
web-allow-others: false
|
||||
path: /h2-console
|
||||
enabled: false
|
||||
```
|
||||
|
||||
**注意事项**：
|
||||
|
||||
- `url` 为默认的数据本地存储地址，请勿修改。
|
||||
- 默认的数据库账户和密码为 `admin` 和 `123456`，建议将其修改，并妥善保存（此用户名和密码在 Halo 第一次启动的时候将自动创建。并且不支持首次启动后，通过修改配置文件中的账户或者密码，如果修改，再次启动将提示用户名或者密码错误。）。
|
||||
- 线上环境中，`h2` 的配置使用默认即可。如果需要手动修改一些数据，可将 `web-allow-others` 和 `enabled` 设为 `true` 来开启 h2 控制台，访问路径为 `ip:端口/h2-console`。`JDBC URL`，`username`，`password` 使用配置文件中的即可。
|
||||
|
||||
:::warning
|
||||
特别注意：在开启 `h2-console` 并完成所需操作之后，一定要再次关闭 `h2-console` 并重启，不要长时间将 `h2-console` 处于开启状态，这可能会有隐性的安全风险。
|
||||
:::
|
||||
|
||||
#### MySQL
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
datasource:
|
||||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||||
url: jdbc:mysql://127.0.0.1:3306/halodb?characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
|
||||
username: root
|
||||
password: 123456
|
||||
```
|
||||
|
||||
**要求**：
|
||||
|
||||
1. 版本：5.7 +
|
||||
2. 字符集（Character Set）：`utf8mb4`
|
||||
3. 排序规则（Collate）：`utf8mb4_bin`
|
||||
4. 存储引擎：`InnoDB`
|
||||
|
||||
综上，建议创建数据库采用下面的命令：
|
||||
|
||||
```bash
|
||||
create database halodb character set utf8mb4 collate utf8mb4_bin;
|
||||
```
|
||||
|
||||
**注意事项**：
|
||||
|
||||
- `username` 及 `password` 需要修改为您的 MySQL 数据库账号和密码。
|
||||
- 默认时区为 `Asia/Shanghai`，如果与您所在时区不一致，则可以修改为您所在的时区。
|
||||
|
||||
## 高级配置
|
||||
|
||||
高级配置中的配置设置是可选的，如果不需要，可以略过。
|
||||
|
||||
### 后台路径
|
||||
|
||||
Halo 支持自定义后台管理的**根路径**。
|
||||
|
||||
```yaml
|
||||
halo:
|
||||
# Your admin client path is https://your-domain/{admin-path}
|
||||
admin-path: admin
|
||||
```
|
||||
|
||||
注意：仅为改动后台管理的根路径，因此前后不带 `/`。
|
||||
|
||||
### 缓存
|
||||
|
||||
某些情况下，需要用户根据需求来设置缓存数据的保存方式，例如将缓存数据持久化保存在本地。
|
||||
|
||||
```yaml
|
||||
halo:
|
||||
# memory or level or redis
|
||||
cache: memory
|
||||
```
|
||||
|
||||
目前支持三种策略：
|
||||
|
||||
- `memory` 将数据缓存至内存，重启服务缓存将清空。
|
||||
- `level` 将数据缓存至本地，重启服务不会清空缓存。
|
||||
- `redis` 将数据缓存至 Redis，重启服务不会清空缓存，如需分布式部署 Halo，请选用此种缓存方式。
|
||||
|
||||
**注意事项**：
|
||||
|
||||
- 如果选用 Redis 缓存方式，请在配置文件加入 Redis 相关配置，完整的配置示例如下：
|
||||
|
||||
```yaml
|
||||
server:
|
||||
port: 8090
|
||||
|
||||
# Response data gzip.
|
||||
compression:
|
||||
enabled: true
|
||||
|
||||
spring:
|
||||
datasource:
|
||||
# MySQL database configuration.
|
||||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||||
url: jdbc:mysql://127.0.0.1:3306/halodb?characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
|
||||
username: root
|
||||
password: 123456
|
||||
redis:
|
||||
# Redis cache configuration.
|
||||
port: 6379
|
||||
database: 0
|
||||
host: 127.0.0.1
|
||||
password: 123456
|
||||
|
||||
halo:
|
||||
# Your admin client path is https://your-domain/{admin-path}
|
||||
admin-path: admin
|
||||
|
||||
# memory or level or redis
|
||||
cache: redis
|
||||
```
|
||||
|
||||
### 压缩
|
||||
|
||||
启用压缩对于减少带宽和加快页面加载非常有用，在**未使用** `Nginx` 或 `Caddy` 等反向代理服务器时（反向代理服务器通常是默认开启 Gzip 的），可以考虑开启系统自带的 Gzip 功能。
|
||||
|
||||
```yaml
|
||||
server:
|
||||
# Response data gzip.
|
||||
compression:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
## 示例配置文件
|
||||
|
||||
:::info
|
||||
建议根据使用的数据库类型查看。
|
||||
:::
|
||||
|
||||
### H2 Database
|
||||
|
||||
```yaml
|
||||
server:
|
||||
port: 8090
|
||||
|
||||
# Response data gzip.
|
||||
compression:
|
||||
enabled: true
|
||||
spring:
|
||||
datasource:
|
||||
# H2 database configuration.
|
||||
driver-class-name: org.h2.Driver
|
||||
url: jdbc:h2:file:~/.halo/db/halo
|
||||
username: admin
|
||||
password: 123456
|
||||
|
||||
# H2 database console configuration.
|
||||
h2:
|
||||
console:
|
||||
settings:
|
||||
web-allow-others: false
|
||||
path: /h2-console
|
||||
enabled: false
|
||||
|
||||
halo:
|
||||
# Your admin client path is https://your-domain/{admin-path}
|
||||
admin-path: admin
|
||||
|
||||
# memory or level or redis
|
||||
cache: memory
|
||||
```
|
||||
|
||||
### MySQL
|
||||
|
||||
```yaml
|
||||
server:
|
||||
port: 8090
|
||||
|
||||
# Response data gzip.
|
||||
compression:
|
||||
enabled: true
|
||||
spring:
|
||||
datasource:
|
||||
# MySQL database configuration.
|
||||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||||
url: jdbc:mysql://127.0.0.1:3306/halodb?characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
|
||||
username: root
|
||||
password: 123456
|
||||
|
||||
halo:
|
||||
# Your admin client path is https://your-domain/{admin-path}
|
||||
admin-path: admin
|
||||
|
||||
# memory or level or redis
|
||||
cache: memory
|
||||
```
|
||||
|
||||
官方的完整示例配置文件可以在 [https://dl.halo.run/config/](https://dl.halo.run/config/) 下找到。
|
||||
25
versioned_docs/version-2.3/getting-started/downloads.md
Normal file
25
versioned_docs/version-2.3/getting-started/downloads.md
Normal file
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: 资源下载
|
||||
description: 目前所有与 Halo 相关的下载地址
|
||||
---
|
||||
|
||||
## GitHub
|
||||
|
||||
:::note
|
||||
如果您的服务器在海外，推荐从 GitHub 下载。
|
||||
:::
|
||||
|
||||
- [运行包](https://github.com/halo-dev/halo/releases)
|
||||
- [配置文件](https://github.com/halo-dev/halo-common)
|
||||
|
||||
## 官方镜像源
|
||||
|
||||
- [https://download.halo.run](https://download.halo.run)
|
||||
|
||||
此镜像源由 [Nova Kwok](https://nova.moe/) 提供并维护。
|
||||
|
||||
## 三方镜像源
|
||||
|
||||
- [https://halo.cary.tech](https://halo.cary.tech)
|
||||
|
||||
此镜像源由 [新逸Cary](https://blog.xinac.cn) 提供并维护。
|
||||
38
versioned_docs/version-2.3/getting-started/first-post.md
Normal file
38
versioned_docs/version-2.3/getting-started/first-post.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: 第一篇文章
|
||||
description: 安装完成后，如何写下第一篇文章。
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 登录管理端
|
||||
|
||||
浏览器访问 `$HALO_EXTERNAL_URL/console/`（外部访问链接）即可进入 Halo 管理端。默认的管理员用户名为 `admin`，登录密码为安装时设置的 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD`，文档中的默认值为 `P@88w0rd`。
|
||||
|
||||
:::info
|
||||
如果你在安装时没有设置 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD` 变量或忘记了设置的密码，可以参考[常见问题中的忘记密码章节](../user-guide/faq.md#忘记密码怎么办)进行处理。
|
||||
:::
|
||||
|
||||
## 新建文章
|
||||
|
||||
Halo 安装完成后，默认初始化了一篇 `Hello Halo` 文章，接下来我们将创建并发布一篇自己的文章。
|
||||
|
||||
在 Halo 管理端，点击仪表盘页面中的 `创建文章` 快捷入口，即可进入到文章编辑页面。
|
||||
|
||||
在文章编辑器中，你可以尽情写下你想展现的内容。
|
||||
|
||||
当内容编辑完成后，点击右上角的 `发布` 按钮，给文章设置一个合适的标题和别名，同时可以设置文章所属分类、标签及其他一些高级设置。
|
||||
|
||||
确认无误后，点击弹框下方的 `发布` 按钮，我们的第一篇文章就成功发布了。
|
||||
|
||||
:::info
|
||||
关于文章相关其他功能及文章各种设置项的说明，请参考《[用户指南-文章](../user-guide/posts.md)》章节
|
||||
:::
|
||||
|
||||
## 查看文章
|
||||
|
||||
文章发布成功后，就可以在主题端查看到我们刚刚创建的文章了。
|
||||
|
||||
浏览器访问 `$HALO_EXTERNAL_URL` 进入站点首页，站点展示的内容及样式由当前启用的主题所决定。
|
||||
|
||||
接下来，选一款喜欢的主题，尽情体验 Halo 吧！
|
||||
@@ -0,0 +1,346 @@
|
||||
---
|
||||
title: 使用 Docker Compose 部署
|
||||
description: 使用 Docker Compose 部署
|
||||
---
|
||||
|
||||
import DockerArgs from "./slots/docker-args.md"
|
||||
|
||||
:::info
|
||||
在继续操作之前，我们推荐您先阅读[《写在前面》](../prepare.md)，这可以快速帮助你了解 Halo。
|
||||
:::
|
||||
|
||||
## 环境搭建
|
||||
|
||||
- Docker 安装文档：<https://docs.docker.com/engine/install/>
|
||||
- Docker Compose 安装文档：<https://docs.docker.com/compose/install/>
|
||||
|
||||
:::tip
|
||||
我们推荐按照 Docker 官方文档安装 Docker 和 Docker Compose，因为部分 Linux 发行版软件仓库中的 Docker 版本可能过旧。
|
||||
:::
|
||||
|
||||
## 创建容器组
|
||||
|
||||
可用的 Halo 2.3.0 的 Docker 镜像：
|
||||
|
||||
- [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 版本，防止使用者误操作。我们推荐使用固定版本的标签，比如 `halohub/halo:2.3.0`。
|
||||
:::
|
||||
|
||||
1. 在系统任意位置创建一个文件夹，此文档以 `~/halo` 为例。
|
||||
|
||||
```bash
|
||||
mkdir ~/halo && cd ~/halo
|
||||
```
|
||||
|
||||
:::info
|
||||
注意：后续操作中，Halo 产生的所有数据都会保存在这个目录，请妥善保存。
|
||||
:::
|
||||
|
||||
2. 创建 `docker-compose.yaml`
|
||||
|
||||
此文档提供两种场景的 Docker Compose 配置文件，请根据你的需要**选择一种**。
|
||||
|
||||
:::info
|
||||
需要注意的是，此文档为了更加方便的管理配置，所有与 Halo 相关的配置都使用 Docker 环境变量代替，所以无需创建 application.yaml 文件。
|
||||
:::
|
||||
|
||||
1. 创建 Halo + PostgreSQL 的实例：
|
||||
|
||||
```yaml {24-34,51} title="~/halo/docker-compose.yaml"
|
||||
version: "3"
|
||||
|
||||
services:
|
||||
halo:
|
||||
image: halohub/halo:2.3.0
|
||||
container_name: halo
|
||||
restart: on-failure:3
|
||||
depends_on:
|
||||
halodb:
|
||||
condition: service_healthy
|
||||
networks:
|
||||
halo_network:
|
||||
volumes:
|
||||
- ./:/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/
|
||||
# 初始化的超级管理员用户名
|
||||
- --halo.security.initializer.superadminusername=admin
|
||||
# 初始化的超级管理员密码
|
||||
- --halo.security.initializer.superadminpassword=P@88w0rd
|
||||
halodb:
|
||||
image: postgres:latest
|
||||
container_name: halodb
|
||||
restart: on-failure:3
|
||||
networks:
|
||||
halo_network:
|
||||
volumes:
|
||||
- ./db:/var/lib/postgresql/data
|
||||
ports:
|
||||
- "5432:5432"
|
||||
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:
|
||||
```
|
||||
|
||||
2. 创建 Halo + MySQL 的实例：
|
||||
|
||||
```yaml {24-34,59} title="~/halo/docker-compose.yaml"
|
||||
version: "3"
|
||||
|
||||
services:
|
||||
halo:
|
||||
image: halohub/halo:2.3.0
|
||||
container_name: halo
|
||||
restart: on-failure:3
|
||||
depends_on:
|
||||
halodb:
|
||||
condition: service_healthy
|
||||
networks:
|
||||
halo_network:
|
||||
volumes:
|
||||
- ./:/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/
|
||||
# 初始化的超级管理员用户名
|
||||
- --halo.security.initializer.superadminusername=admin
|
||||
# 初始化的超级管理员密码
|
||||
- --halo.security.initializer.superadminpassword=P@88w0rd
|
||||
|
||||
halodb:
|
||||
image: mysql:8.0.31
|
||||
container_name: halodb
|
||||
restart: on-failure:3
|
||||
networks:
|
||||
halo_network:
|
||||
command:
|
||||
- --default-authentication-plugin=mysql_native_password
|
||||
- --character-set-server=utf8mb4
|
||||
- --collation-server=utf8mb4_general_ci
|
||||
- --explicit_defaults_for_timestamp=true
|
||||
volumes:
|
||||
- ./mysql:/var/lib/mysql
|
||||
- ./mysqlBackup:/data/mysqlBackup
|
||||
ports:
|
||||
- "3306:3306"
|
||||
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:
|
||||
```
|
||||
|
||||
3. 仅创建 Halo 实例（使用默认的 H2 数据库，**不推荐用于生产环境，建议体验和测试的时候使用**）：
|
||||
|
||||
```yaml {19-24} title="~/halo/docker-compose.yaml"
|
||||
version: "3"
|
||||
|
||||
services:
|
||||
halo:
|
||||
image: halohub/halo:2.3.0
|
||||
container_name: halo
|
||||
restart: on-failure:3
|
||||
volumes:
|
||||
- ./:/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/
|
||||
# 初始化的超级管理员用户名
|
||||
- --halo.security.initializer.superadminusername=admin
|
||||
# 初始化的超级管理员密码
|
||||
- --halo.security.initializer.superadminpassword=P@88w0rd
|
||||
```
|
||||
|
||||
参数详解：
|
||||
|
||||
<DockerArgs />
|
||||
|
||||
3. 启动 Halo 服务
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
实时查看日志：
|
||||
|
||||
```bash
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
4. 用浏览器访问 `$HALO_EXTERNAL_URL/console/`（外部访问链接）即可进入 Halo 管理端。管理员用户名为 `admin`，登录密码为上方设置的 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD`。
|
||||
|
||||
:::tip
|
||||
如果需要配置域名访问，建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip:端口号` 的形式无法访问，请到服务器厂商后台将运行的端口号添加到安全组，如果服务器使用了 Linux 面板，请检查此 Linux 面板是否有还有安全组配置，需要同样将端口号添加到安全组。
|
||||
:::
|
||||
|
||||
## 更新容器组
|
||||
|
||||
1. 停止运行中的容器组
|
||||
|
||||
```bash
|
||||
cd ~/halo && docker-compose down
|
||||
```
|
||||
|
||||
2. 备份数据（重要）
|
||||
|
||||
```bash
|
||||
cp -r ~/halo ~/halo.archive
|
||||
```
|
||||
|
||||
> 需要注意的是，`halo.archive` 文件名不一定要根据此文档命名，这里仅仅是个示例。
|
||||
|
||||
3. 更新 Halo 服务
|
||||
|
||||
修改 `docker-compose.yaml` 中配置的镜像版本。
|
||||
|
||||
```yaml {3}
|
||||
services:
|
||||
halo:
|
||||
image: halohub/halo:2.3.0
|
||||
container_name: halo
|
||||
```
|
||||
|
||||
```bash
|
||||
docker-compose pull
|
||||
```
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## 反向代理
|
||||
|
||||
你可以在下面的反向代理软件中任选一项，我们假设你已经安装好了其中一项，并对其的基本操作有一定了解。 如果你对它们没有任何了解，可以参考我们更为详细的反向代理文档：
|
||||
|
||||
1. 使用 [OneinStack](../install/other/oneinstack.md)
|
||||
2. 使用 [Nginx Proxy Manager](../install/other/nginxproxymanager.md)
|
||||
3. 使用 [Traefik](../install/other/traefik.md)
|
||||
|
||||
### 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} showLineNumbers
|
||||
version: "3.8"
|
||||
|
||||
networks:
|
||||
traefik:
|
||||
external: true
|
||||
halo:
|
||||
|
||||
services:
|
||||
halo:
|
||||
image: halohub/halo:2.3.0
|
||||
container_name: halo
|
||||
restart: on-failure:3
|
||||
volumes:
|
||||
- ./:/root/.halo2
|
||||
networks:
|
||||
- traefik
|
||||
- halo
|
||||
command:
|
||||
# 外部访问地址，请根据实际需要修改
|
||||
- --halo.external-url=https://yourdomain.com
|
||||
# 初始化的超级管理员用户名
|
||||
- --halo.security.initializer.superadminusername=admin
|
||||
# 初始化的超级管理员密码
|
||||
- --halo.security.initializer.superadminpassword=P@88w0rd
|
||||
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
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
108
versioned_docs/version-2.3/getting-started/install/docker.md
Normal file
108
versioned_docs/version-2.3/getting-started/install/docker.md
Normal file
@@ -0,0 +1,108 @@
|
||||
---
|
||||
title: 使用 Docker 部署
|
||||
description: 使用 Docker 部署
|
||||
---
|
||||
|
||||
import DockerArgs from "./slots/docker-args.md"
|
||||
|
||||
:::info
|
||||
在继续操作之前，我们推荐您先阅读[《写在前面》](../prepare)，这可以快速帮助你了解 Halo。
|
||||
:::
|
||||
|
||||
:::tip
|
||||
此文档仅提供使用默认 H2 数据库的 Docker 运行方式，主要用于体验和测试，在生产环境我们不推荐使用 H2 数据库。
|
||||
|
||||
如果需要使用其他数据库部署，我们推荐使用 Docker Compose 部署：[使用 Docker Compose 部署](./docker-compose)
|
||||
:::
|
||||
|
||||
## 环境搭建
|
||||
|
||||
- Docker 安装文档：<https://docs.docker.com/engine/install/>
|
||||
|
||||
:::tip
|
||||
我们推荐按照 Docker 官方文档安装 Docker，因为部分 Linux 发行版软件仓库中的 Docker 版本可能过旧。
|
||||
:::
|
||||
|
||||
## 使用 Docker 镜像
|
||||
|
||||
可用的 Halo 2.3.0 的 Docker 镜像：
|
||||
|
||||
- [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 版本，防止使用者误操作。我们推荐使用固定版本的标签，比如 `halohub/halo:2.3.0`。
|
||||
:::
|
||||
|
||||
1. 创建容器
|
||||
|
||||
```bash
|
||||
docker run \
|
||||
-it -d \
|
||||
--name halo \
|
||||
-p 8090:8090 \
|
||||
-v ~/.halo2:/root/.halo2 \
|
||||
halohub/halo:2.3.0 \
|
||||
--halo.external-url=http://localhost:8090/ \
|
||||
--halo.security.initializer.superadminusername=admin \
|
||||
--halo.security.initializer.superadminpassword=P@88w0rd
|
||||
```
|
||||
|
||||
:::info
|
||||
注意：此命令默认使用自带的 H2 Database 数据库。如需使用 PostgreSQL，请参考：[使用 Docker Compose 部署](./docker-compose)
|
||||
:::
|
||||
|
||||
- **-it**：开启输入功能并连接伪终端
|
||||
- **-d**：后台运行容器
|
||||
- **--name**：为容器指定一个名称
|
||||
- **-p**：端口映射，格式为 `主机(宿主)端口:容器端口` ，可在 `application.yaml` 配置。
|
||||
- **-v**：工作目录映射。形式为：`-v 宿主机路径:/root/.halo2`，后者不能修改。
|
||||
|
||||
变量详解：
|
||||
|
||||
<DockerArgs />
|
||||
|
||||
1. 用浏览器访问 `$HALO_EXTERNAL_URL/console/`（外部访问链接）即可进入 Halo 管理端。管理员用户名为 `admin`，登录密码为上方设置的 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD`。
|
||||
|
||||
:::tip
|
||||
如果需要配置域名访问，建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip:端口号` 的形式无法访问，请到服务器厂商后台将运行的端口号添加到安全组，如果服务器使用了 Linux 面板，请检查此 Linux 面板是否有还有安全组配置，需要同样将端口号添加到安全组。
|
||||
:::
|
||||
|
||||
## 升级版本
|
||||
|
||||
1. 拉取新版本镜像
|
||||
|
||||
```bash
|
||||
docker pull halohub/halo:2.3.0
|
||||
```
|
||||
|
||||
2. 停止运行中的容器
|
||||
|
||||
```bash
|
||||
docker stop halo
|
||||
docker rm halo
|
||||
```
|
||||
|
||||
3. 备份数据（重要）
|
||||
|
||||
```bash
|
||||
cp -r ~/.halo2 ~/halo2.archive
|
||||
```
|
||||
|
||||
> 需要注意的是，`halo2.archive` 文件名不一定要根据此文档命名，这里仅仅是个示例。
|
||||
|
||||
4. 更新 Halo
|
||||
|
||||
修改版本号后，按照最初安装的方式，重新创建容器即可。
|
||||
|
||||
```bash {6}
|
||||
docker run \
|
||||
-it -d \
|
||||
--name halo \
|
||||
-p 8090:8090 \
|
||||
-v ~/.halo2:/root/.halo2 \
|
||||
halohub/halo:2.3.0 \
|
||||
--halo.external-url=http://localhost:8090/ \
|
||||
--halo.security.initializer.superadminusername=admin \
|
||||
--halo.security.initializer.superadminpassword=P@88w0rd
|
||||
```
|
||||
@@ -0,0 +1,164 @@
|
||||
---
|
||||
title: 与 Nginx Proxy Manager 配合使用
|
||||
description: 使用 Nginx Proxy Manager 管理 Halo 服务的反向代理
|
||||
---
|
||||
|
||||
### Halo 部署
|
||||
|
||||
参见 [使用 Docker Compose 部署](https://docs.halo.run/getting-started/install/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 部署](https://docs.halo.run/getting-started/install/docker-compose) 的环境搭建部分来进行安装。
|
||||
|
||||
点击下方链接进入 Nginx Proxy Manager（以下简称 NPM） 官网：<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 的反向代理
|
||||
|
||||
首先我们登陆网页端之后，会弹出修改用户名和密码的对话框，我们根据自己的实际来修改自己的用户名和邮箱。
|
||||
|
||||
|
||||
|
||||
保存之后，会让我们修改密码（建议用一个复杂的密码）。
|
||||
|
||||
|
||||
|
||||
接着我们就可以来给 Halo 来添加一个反向代理了。
|
||||
|
||||
点击 `Proxy Hosts`，
|
||||
|
||||
|
||||
|
||||
接着点击 `Add Proxy Host`，弹出如下对话框：
|
||||
|
||||
|
||||
|
||||
看起来都是英文，很复杂，但是其实很简单，我们只要用到其中的几个功能即可，这边稍微解释一下：
|
||||
|
||||
- `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 自带的一个限制访问功能，这边我们不管，后续可以自行研究。
|
||||
|
||||
以下是一个样列：
|
||||
|
||||
|
||||
|
||||
因为样例的 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` 访问。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
如图所示，记得打开强制 SSL，其他四个的功能请自行研究，这边不多做讨论。
|
||||
|
||||
:::info
|
||||
|
||||
1. 申请证书需要你提前将域名解析到 NPM 所在的服务器的 IP 上；
|
||||
2. 如果你使用的是国内的服务器，默认 `80` 和 `443` 端口是关闭的，你需要备案之后才能使用；
|
||||
3. 如果你使用了 CloudFlare 的 DNS 服务，记得把小黄云关闭（即不开启 CDN）。
|
||||
:::
|
||||
|
||||
不出意外，你将成功申请到 SSL 证书，证书会三个月自动续期。
|
||||
|
||||
再次点开配置，查看一下，将强制 SSL 打开。
|
||||
|
||||
|
||||
|
||||
至此，你已经成功完成了 Halo 的反向代理，快尝试使用域名访问一下看看吧！
|
||||
|
||||
> 同样的，举一反三，试试把你的 NPM 也用一个域名来反向代理一下吧。(小提示：你需要再解析一个域名（可以是二级域名）到 NPM 所在的服务器上，反代页面需要填的 IP 可以填 docker 容器内的 IP 也可以填服务器的 IP，端口填 `81` 即可）
|
||||
@@ -0,0 +1,274 @@
|
||||
---
|
||||
title: 与 OneinStack 配合使用
|
||||
description: 使用 OneinStack 管理 Halo 服务的反向代理
|
||||
---
|
||||
|
||||
## Halo 部署
|
||||
|
||||
参见 [使用 Docker Compose 部署](../docker-compose.md)
|
||||
|
||||
:::info
|
||||
`「反向代理」` 部分不进行操作，保证 Halo 服务运行无误即可。
|
||||
:::
|
||||
|
||||
## 通过 OneinStack 安装 Nginx
|
||||
|
||||
点击下方链接进入 OneinStack 官网，仅选择 `安装 Nginx`，其他的都可以取消选择。
|
||||
|
||||
<https://oneinstack.com/auto>
|
||||
|
||||
最后点击 `复制安装命令` 到服务器执行即可。如果你仅安装 Nginx，你的链接应该是这样：
|
||||
|
||||
```bash
|
||||
wget -c http://mirrors.linuxeye.com/oneinstack-full.tar.gz && tar xzf oneinstack-full.tar.gz && ./oneinstack/install.sh --nginx_option 1
|
||||
```
|
||||
|
||||
:::info
|
||||
这一步会经过编译安装，可能会导致安装时间很漫长，这主要取决于你服务器的性能。
|
||||
:::
|
||||
|
||||
出现下面的信息即代表安装成功：
|
||||
|
||||
```bash
|
||||
Nginx installed successfully!
|
||||
Created symlink from /etc/systemd/system/multi-user.target.wants/nginx.service to /usr/lib/systemd/system/nginx.service.
|
||||
Redirecting to /bin/systemctl start nginx.service
|
||||
####################Congratulations########################
|
||||
Total OneinStack Install Time: 5 minutes
|
||||
|
||||
Nginx install dir: /usr/local/nginx
|
||||
```
|
||||
|
||||
## 创建 vhost
|
||||
|
||||
> 即创建一个站点，你可以通过这样的方式在你的服务器创建无限个站点。接下来的目的就是创建一个站点，并反向代理到 Halo。这一步在此教程使用 `demo.halo.run` 这个域名做演示，实际情况请修改此域名。
|
||||
|
||||
1. 进入到 oneinstack 目录，执行 vhost 创建命令
|
||||
|
||||
```bash
|
||||
cd oneinstack
|
||||
```
|
||||
|
||||
```bash
|
||||
sh vhost.sh
|
||||
```
|
||||
|
||||
2. 按照提示选择或输入相关信息
|
||||
|
||||
```bash
|
||||
What Are You Doing?
|
||||
1. Use HTTP Only
|
||||
2. Use your own SSL Certificate and Key
|
||||
3. Use Let's Encrypt to Create SSL Certificate and Key
|
||||
q. Exit
|
||||
Please input the correct option:
|
||||
```
|
||||
|
||||
这一步是选择证书配置方式，如果你有自己的证书，输入 <kbd>2</kbd> 即可。如果需要使用 `Let's Encrypt` 申请证书，选择 <kbd>3</kbd> 即可。
|
||||
|
||||
```bash
|
||||
Please input domain(example: www.example.com):
|
||||
```
|
||||
|
||||
输入自己的域名即可，前提是已经提前解析好了域名。
|
||||
|
||||
```bash
|
||||
Please input the directory for the domain:demo.halo.run :
|
||||
(Default directory: /data/wwwroot/demo.halo.run):
|
||||
```
|
||||
|
||||
提示输入站点根目录，因为我们是使用 Nginx 的反向代理，所以这个目录是没有必要配置的，我们直接使用默认的即可（直接回车）。
|
||||
|
||||
```bash
|
||||
Do you want to add more domain name? [y/n]:
|
||||
```
|
||||
|
||||
是否需要添加其他域名，按照需要选择即可，如果不需要，输入 <kbd>n</kbd> 并回车确认。
|
||||
|
||||
```bash
|
||||
Do you want to add hotlink protection? [y/n]:
|
||||
```
|
||||
|
||||
是否需要做防盗链处理，按照需要选择即可。
|
||||
|
||||
```bash
|
||||
Allow Rewrite rule? [y/n]:
|
||||
```
|
||||
|
||||
路径重写配置，我们不需要，选择 <kbd>n</kbd> 回车确定即可。
|
||||
|
||||
```bash
|
||||
Allow Nginx/Tengine/OpenResty access_log? [y/n]:
|
||||
```
|
||||
|
||||
Nginx 的请求日志，建议选择 <kbd>y</kbd>。
|
||||
|
||||
这样就完成了 vhost 站点的创建，最终会输出站点的相关信息：
|
||||
|
||||
```bash
|
||||
Your domain: demo.halo.run
|
||||
Virtualhost conf: /usr/local/nginx/conf/vhost/demo.halo.run.conf
|
||||
Directory of: /data/wwwroot/demo.halo.run
|
||||
```
|
||||
|
||||
Nginx 的配置文件即 `/usr/local/nginx/conf/vhost/demo.halo.run.conf`。
|
||||
|
||||
## 修改 Nginx 配置文件
|
||||
|
||||
上方创建 vhost 的过程并没有创建反向代理的配置，所以需要我们自己修改一下配置文件。
|
||||
|
||||
1. 使用你熟悉的工具打开配置文件，此教程使用 vim。
|
||||
|
||||
```bash
|
||||
vim /usr/local/nginx/conf/vhost/demo.halo.run.conf
|
||||
```
|
||||
|
||||
2. 删除一些不必要的配置
|
||||
|
||||
```nginx
|
||||
location ~ [^/]\.php(/|$) {
|
||||
#fastcgi_pass remote_php_ip:9000;
|
||||
fastcgi_pass unix:/dev/shm/php-cgi.sock;
|
||||
fastcgi_index index.php;
|
||||
include fastcgi.conf;
|
||||
}
|
||||
```
|
||||
|
||||
此段配置是针对 php 应用的，所以可以删掉。
|
||||
|
||||
3. 添加 `upstream` 配置
|
||||
|
||||
在 `server` 的同级节点添加如下配置：
|
||||
|
||||
```nginx {2}
|
||||
upstream halo {
|
||||
server 127.0.0.1:8090;
|
||||
}
|
||||
```
|
||||
|
||||
4. 在 `server` 节点添加如下配置
|
||||
|
||||
```nginx {6}
|
||||
location / {
|
||||
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;
|
||||
proxy_pass http://halo;
|
||||
}
|
||||
```
|
||||
|
||||
5. 修改 `location ~ .*\.(gif|jpg|jpeg|png|bmp|swf|flv|mp4|ico)$` 节点
|
||||
|
||||
```nginx {2}
|
||||
location ~ .*\.(gif|jpg|jpeg|png|bmp|swf|flv|mp4|ico)$ {
|
||||
proxy_pass http://halo;
|
||||
expires 30d;
|
||||
access_log off;
|
||||
}
|
||||
```
|
||||
|
||||
6. 修改 `location ~ .*\.(js|css)?$` 节点
|
||||
|
||||
```nginx {2}
|
||||
location ~ .*\.(js|css)?$ {
|
||||
proxy_pass http://halo;
|
||||
expires 7d;
|
||||
access_log off;
|
||||
}
|
||||
```
|
||||
|
||||
如果不按照第 5，6 步操作，请求一些图片或者样式文件不会经过 Halo，所以请不要忽略此配置。
|
||||
|
||||
7. 添加 acme.sh 续签验证路由
|
||||
|
||||
OneinStack 使用的 acme.sh 管理证书，如果你在创建 vhost 的时候选择了使用 `Let's Encrypt` 申请证书，那么 OneinStack 会在系统内添加一个定时任务去自动续签证书，acme.sh 默认验证站点所有权的方式为在站点根目录生成一个文件（.well-known）来做验证，由于配置了反向代理，所以在验证的时候是无法直接访问到站点目录下的 .well-known 文件夹下的验证文件的。需要添加如下配置：
|
||||
|
||||
```nginx {4}
|
||||
location ^~ /.well-known/acme-challenge/ {
|
||||
default_type "text/plain";
|
||||
allow all;
|
||||
root /data/wwwroot/demo.halo.run/;
|
||||
}
|
||||
```
|
||||
|
||||
至此，配置修改完毕，保存即可。最终你的配置文件可能如下面配置一样：
|
||||
|
||||
```nginx {2,20,29,34,41-47,51}
|
||||
upstream halo {
|
||||
server 127.0.0.1:8090;
|
||||
}
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
listen 443 ssl http2;
|
||||
listen [::]:443 ssl http2;
|
||||
ssl_certificate /usr/local/nginx/conf/ssl/demo.halo.run.crt;
|
||||
ssl_certificate_key /usr/local/nginx/conf/ssl/demo.halo.run.key;
|
||||
ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
|
||||
ssl_ciphers TLS13-AES-256-GCM-SHA384:TLS13-CHACHA20-POLY1305-SHA256:TLS13-AES-128-GCM-SHA256:TLS13-AES-128-CCM-8-SHA256:TLS13-AES-128-CCM-SHA256:EECDH+CHACHA20:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
|
||||
ssl_prefer_server_ciphers on;
|
||||
ssl_session_timeout 10m;
|
||||
ssl_session_cache builtin:1000 shared:SSL:10m;
|
||||
ssl_buffer_size 1400;
|
||||
add_header Strict-Transport-Security max-age=15768000;
|
||||
ssl_stapling on;
|
||||
ssl_stapling_verify on;
|
||||
server_name demo.halo.run;
|
||||
access_log /data/wwwlogs/demo.halo.run_nginx.log combined;
|
||||
index index.html index.htm index.php;
|
||||
root /data/wwwroot/demo.halo.run;
|
||||
if ($ssl_protocol = "") { return 301 https://$host$request_uri; }
|
||||
include /usr/local/nginx/conf/rewrite/none.conf;
|
||||
#error_page 404 /404.html;
|
||||
#error_page 502 /502.html;
|
||||
location ~ .*\.(gif|jpg|jpeg|png|bmp|swf|flv|mp4|ico)$ {
|
||||
proxy_pass http://halo;
|
||||
expires 30d;
|
||||
access_log off;
|
||||
}
|
||||
location ~ .*\.(js|css)?$ {
|
||||
proxy_pass http://halo;
|
||||
expires 7d;
|
||||
access_log off;
|
||||
}
|
||||
location ~ /(\.user\.ini|\.ht|\.git|\.svn|\.project|LICENSE|README\.md) {
|
||||
deny all;
|
||||
}
|
||||
location / {
|
||||
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;
|
||||
proxy_pass http://halo;
|
||||
}
|
||||
location ^~ /.well-known/acme-challenge/ {
|
||||
default_type "text/plain";
|
||||
allow all;
|
||||
root /data/wwwroot/demo.halo.run/;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 重载 Nginx 使配置生效
|
||||
|
||||
验证 nginx 配置
|
||||
|
||||
```bash
|
||||
nginx -t
|
||||
```
|
||||
|
||||
如果输出如下提示则代表配置有效：
|
||||
|
||||
```bash
|
||||
nginx: the configuration file /usr/local/nginx/conf/nginx.conf syntax is ok
|
||||
nginx: configuration file /usr/local/nginx/conf/nginx.conf test is successful
|
||||
```
|
||||
|
||||
重载 Nginx 配置：
|
||||
|
||||
```bash
|
||||
nginx -s reload
|
||||
```
|
||||
|
||||
至此，整个教程完毕，现在你可以访问域名检查是否已经配置成功。
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
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/)
|
||||
|
||||
:::caution
|
||||
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: halohub/halo:2.3.0
|
||||
container_name: halo
|
||||
restart: on-failure:3
|
||||
volumes:
|
||||
- ./:/root/.halo2
|
||||
networks:
|
||||
- traefik
|
||||
- halo
|
||||
command:
|
||||
# 外部访问地址，请根据实际需要修改
|
||||
- --halo.external-url=https://yourdomain.com
|
||||
# 初始化的超级管理员用户名
|
||||
- --halo.security.initializer.superadminusername=admin
|
||||
# 初始化的超级管理员密码
|
||||
- --halo.security.initializer.superadminpassword=P@88w0rd
|
||||
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
|
||||
```
|
||||
@@ -0,0 +1,17 @@
|
||||
| 参数名 | 描述 |
|
||||
| ---------------------------------------------- | -------------------------------------------------------------------------------- |
|
||||
| `spring.r2dbc.url` | 数据库连接地址，详细可查阅下方的 `数据库配置` |
|
||||
| `spring.r2dbc.username` | 数据库用户名 |
|
||||
| `spring.r2dbc.password` | 数据库密码 |
|
||||
| `spring.sql.init.platform` | 数据库平台名称，支持 `postgresql`、`mysql`、`h2`，需要与 `SPRING_R2DBC_URL` 对应 |
|
||||
| `halo.external-url` | 外部访问链接，如果需要再公网访问，需要配置为实际访问地址 |
|
||||
| `halo.security.initializer.superadminusername` | 初始超级管理员用户名 |
|
||||
| `halo.security.initializer.superadminpassword` | 初始超级管理员密码 |
|
||||
|
||||
数据库配置：
|
||||
|
||||
| 链接方式 | 链接地址格式 | `SPRING_SQL_INIT_PLATFORM` |
|
||||
| ----------- | ---------------------------------------------------------------------------------- | -------------------------- |
|
||||
| PostgreSQL | `r2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}` | postgresql |
|
||||
| MySQL | `r2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}` | mysql |
|
||||
| H2 Database | `r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE` | h2 |
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
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) 查阅目前支持的主题。
|
||||
- Halo 2.0 目前没有内置 Markdown 编辑器，如果需要重新编辑迁移后的文章，需要额外安装 Markdown 编辑器插件。目前社区已经提供了以下插件：
|
||||
- <https://github.com/halo-sigs/plugin-bytemd>
|
||||
- <https://github.com/halo-sigs/plugin-stackedit>
|
||||
- 暂时不支持友情链接、日志、图库的数据迁移，如果你在 1.x 版本中使用了这些功能，建议先暂缓迁移。
|
||||
- Halo 2.0 不在内置外部云存储的支持。需要安装额外的插件，目前官方已提供：
|
||||
- <https://github.com/halo-sigs/plugin-alioss>
|
||||
- <https://github.com/halo-sigs/plugin-s3>
|
||||
- 关于附件，目前仅支持将本地附件代理，不支持在后台管理，也不支持迁移外部云存储的附件。如果你对外部云存储的附件有强需求，建议先暂缓迁移。
|
||||
- 在迁移过程中不会保留旧版本的用户数据，迁移完成之后，关于文章等数据的关联都将改为 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://docs.halo.run/user-guide/backup-migration) 进行整站备份。
|
||||
|
||||
## 导出数据文件
|
||||
|
||||
在 Halo 1.5.x / 1.6.x 后台的小工具中提供了数据导出的功能，将最新的数据进行备份，然后下载即可。这个数据文件包含了数据库所有的数据，后续我们在 2.0 的导入插件中就是通过这个文件进行数据导入。
|
||||
|
||||
|
||||
|
||||
## 部署 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://github.com/halo-sigs/plugin-migrate/releases> 中下载最新版本的插件 JAR 包，然后在 Halo 2.0 的插件管理中安装即可，安装完成即可在左侧菜单中看到迁移菜单。
|
||||
|
||||
|
||||
|
||||
## 迁移
|
||||
|
||||
1. 点击左侧菜单的迁移进入迁移页面。
|
||||
2. 点击 **选择文件** 按钮，选择在 Halo 1.5.x / 1.6.x 导出的数据文件（JSON 格式）。
|
||||
3. 最后点击页面下方的 **执行导入** 即可。
|
||||
98
versioned_docs/version-2.3/getting-started/prepare.md
Normal file
98
versioned_docs/version-2.3/getting-started/prepare.md
Normal file
@@ -0,0 +1,98 @@
|
||||
---
|
||||
title: 写在前面
|
||||
description: 在开始前，您需要了解的事项
|
||||
---
|
||||
|
||||
## 环境要求
|
||||
|
||||
这里将讲述运行 Halo 所要求的一些软硬件的配置，我们建议您在运行或者部署之前先浏览一遍此页面。
|
||||
|
||||
### 硬件配置
|
||||
|
||||
:::tip
|
||||
如果您要使用服务器进行部署 Halo，您需要注意的是，Halo 目前不支持市面上的云虚拟主机，请使用云服务器或者 VPS。
|
||||
:::
|
||||
|
||||
#### CPU
|
||||
|
||||
无特别要求。目前我们的 [Docker 镜像](https://hub.docker.com/r/halohub/halo) 也已经支持多平台。
|
||||
|
||||
#### 内存
|
||||
|
||||
为了获得更好的体验，我们建议至少配置 1G 的 RAM。
|
||||
|
||||
#### 磁盘
|
||||
|
||||
无特别要求，理论上如果不大量在服务器上传附件，Halo 对磁盘的容量要求并不是很高。但我们推荐最好使用 SSD 硬盘的服务器，能更快的运行 Halo。
|
||||
|
||||
#### 网络
|
||||
|
||||
Halo 目前必须在外网畅通的情况下使用，否则会导致页面异常。
|
||||
|
||||
### 软件环境
|
||||
|
||||
Halo 理论上可以运行在任何支持 Docker 及 Java 的平台。
|
||||
|
||||
#### Docker
|
||||
|
||||
必须在运行环境安装好 [Docker](https://www.docker.com/) 环境，目前 Halo 的默认安装运行方式均使用容器。
|
||||
|
||||
#### JRE（可选）
|
||||
|
||||
目前 Halo 的默认及推荐安装方式为 Docker 容器运行，使用 jar 包运行的方式需要用户自行构建 jar 包。
|
||||
|
||||
:::info
|
||||
当前版本（2.0）需要 JRE 17 的版本，推荐使用 OpenJDK 17。
|
||||
:::
|
||||
|
||||
#### PostgreSQL（可选）
|
||||
|
||||
也可以使用系统自带的 H2 Database 数据库，无需安装。但不推荐在生产环境中使用 H2 Database。
|
||||
|
||||
#### Web 服务器（可选）
|
||||
|
||||
如果您部署在生产环境，那么你很可能需要进行域名绑定，这时候我们推荐使用诸如 [Nginx](http://nginx.org/)、[Caddy](https://caddyserver.com/) 之类的 Web 服务器进行反向代理。但需要注意的是，目前 Halo 不支持代理到子目录（如：halo.run/blog）。
|
||||
|
||||
#### Wget（可选）
|
||||
|
||||
后续的文档中，我们会使用 wget 为例，用于下载所需要的文件，所以请确保服务器已经安装好了这个软件包。当然，下载文件不限制工具，如果你对其他工具熟悉，可以忽略。
|
||||
|
||||
#### VIM（可选）
|
||||
|
||||
后续的文档中，我们会使用 vim 为例，用于修改一些必要的配置文件，所以同样请确保服务器已经安装了这个软件包。当前，修改文档也不限制工具，如果你对其他编辑软件熟悉，也可以忽略。
|
||||
|
||||
## 浏览器支持
|
||||
|
||||
1. 用户前台：视主题所支持的情况而定，由于目前的评论模块使用了 [Vuejs](https://cn.vuejs.org/v2/guide/installation.html#%E5%85%BC%E5%AE%B9%E6%80%A7) 开发，所以在 [Vuejs](https://cn.vuejs.org/v2/guide/installation.html#%E5%85%BC%E5%AE%B9%E6%80%A7) 不支持的某些浏览器中无法正常显示评论区域。
|
||||
2. 管理后台：支持目前常见的现代浏览器，具体视 [Vuejs](https://cn.vuejs.org/v2/guide/installation.html#%E5%85%BC%E5%AE%B9%E6%80%A7) 框架的支持情况而定。
|
||||
|
||||
## 名词解释
|
||||
|
||||
这里将列出后续文档中一些和 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`：配置文件。
|
||||
|
||||
### 主题
|
||||
|
||||
包含了各种站点页面模板的资源包。用户访问 Halo 站点浏览到的内容及样式，由 Halo 管理端所配置使用的主题所决定。
|
||||
|
||||
### 插件
|
||||
|
||||
用于扩展 Halo 功能的软件包。插件独立于 Halo 核心应用，可以单独安装、升级、卸载。
|
||||
Reference in New Issue
Block a user