mirror of
https://github.com/halo-dev/docs.git
synced 2025-10-18 08:14:42 +00:00
feat: support create versioning docs (#16)
This commit is contained in:
@@ -61,6 +61,17 @@ const darkCodeTheme = require("prism-react-renderer/themes/palenight");
|
||||
href: "https://bbs.halo.run",
|
||||
label: "论坛",
|
||||
},
|
||||
{
|
||||
type: 'docsVersionDropdown',
|
||||
position: 'right',
|
||||
dropdownActiveClassDisabled: true,
|
||||
dropdownItemsAfter: [
|
||||
{
|
||||
to: '/versions',
|
||||
label: 'All versions',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
href: "https://github.com/halo-dev/halo",
|
||||
label: "GitHub",
|
||||
|
6
pnpm-lock.yaml
generated
6
pnpm-lock.yaml
generated
@@ -3281,7 +3281,7 @@ packages:
|
||||
peerDependencies:
|
||||
react: '*'
|
||||
dependencies:
|
||||
'@types/react': 17.0.34
|
||||
'@types/react': 17.0.37
|
||||
prop-types: 15.7.2
|
||||
react: 17.0.2
|
||||
dev: false
|
||||
@@ -4041,8 +4041,8 @@ packages:
|
||||
resolution: {integrity: sha512-L28j2FcJfSZOnL1WBjDYp2vUHCeIFlyYI/53EwD/rKUBQ7MtUUfbQWiyKJGpcnv4/WgrhWsFKrcPstcAt/J0tQ==}
|
||||
dev: false
|
||||
|
||||
/@types/react/17.0.34:
|
||||
resolution: {integrity: sha512-46FEGrMjc2+8XhHXILr+3+/sTe3OfzSPU9YGKILLrUYbQ1CLQC9Daqo1KzENGXAWwrFwiY0l4ZbF20gRvgpWTg==}
|
||||
/@types/react/17.0.37:
|
||||
resolution: {integrity: sha512-2FS1oTqBGcH/s0E+CjrCCR9+JMpsu9b69RTFO+40ua43ZqP5MmQ4iUde/dMjWR909KxZwmOQIFq6AV6NjEG5xg==}
|
||||
dependencies:
|
||||
'@types/prop-types': 15.7.4
|
||||
'@types/scheduler': 0.16.2
|
||||
|
104
src/pages/versions.tsx
Normal file
104
src/pages/versions.tsx
Normal file
@@ -0,0 +1,104 @@
|
||||
import React from 'react';
|
||||
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
|
||||
import Link from '@docusaurus/Link';
|
||||
import Layout from '@theme/Layout';
|
||||
|
||||
import {useVersions, useLatestVersion} from '@theme/hooks/useDocs';
|
||||
|
||||
function Version(): JSX.Element {
|
||||
const {
|
||||
siteConfig: {organizationName, projectName},
|
||||
} = useDocusaurusContext();
|
||||
const versions = useVersions();
|
||||
const latestVersion = useLatestVersion();
|
||||
const currentVersion = versions.find(
|
||||
(version) => version.name === 'current',
|
||||
)!;
|
||||
const pastVersions = versions.filter(
|
||||
(version) => version !== latestVersion && version.name !== 'current',
|
||||
);
|
||||
const repoUrl = `https://github.com/${organizationName}/${projectName}`;
|
||||
|
||||
return (
|
||||
<Layout
|
||||
title="Versions"
|
||||
description="Docusaurus 2 Versions page listing all documented site versions">
|
||||
<main className="container margin-vert--lg">
|
||||
<h1>Halo documentation versions</h1>
|
||||
|
||||
{latestVersion && (
|
||||
<div className="margin-bottom--lg">
|
||||
<h3 id="next">Current version (Stable)</h3>
|
||||
<p>
|
||||
Here you can find the documentation for current released version.
|
||||
</p>
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>{latestVersion.label}</th>
|
||||
<td>
|
||||
<Link to={latestVersion.path}>Documentation</Link>
|
||||
</td>
|
||||
<td>
|
||||
<a href={`${repoUrl}/releases/tag/v${latestVersion.name}`}>
|
||||
Release Notes
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{currentVersion !== latestVersion && (
|
||||
<div className="margin-bottom--lg">
|
||||
<h3 id="latest">Next version (Unreleased)</h3>
|
||||
<p>
|
||||
Here you can find the documentation for work-in-process unreleased
|
||||
version.
|
||||
</p>
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>{currentVersion.label}</th>
|
||||
<td>
|
||||
<Link to={currentVersion.path}>Documentation</Link>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
)}
|
||||
|
||||
{(pastVersions.length > 0) && (
|
||||
<div className="margin-bottom--lg">
|
||||
<h3 id="archive">Past versions (Not maintained anymore)</h3>
|
||||
<p>
|
||||
Here you can find documentation for previous versions of
|
||||
Docusaurus.
|
||||
</p>
|
||||
<table>
|
||||
<tbody>
|
||||
{pastVersions.map((version) => (
|
||||
<tr key={version.name}>
|
||||
<th>{version.label}</th>
|
||||
<td>
|
||||
<Link to={version.path}>Documentation</Link>
|
||||
</td>
|
||||
<td>
|
||||
<a href={`${repoUrl}/releases/tag/v${version.name}`}>
|
||||
Release Notes
|
||||
</a>
|
||||
</td>
|
||||
</tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
)}
|
||||
</main>
|
||||
</Layout>
|
||||
);
|
||||
}
|
||||
|
||||
export default Version;
|
16
versioned_docs/version-1.4.15/about.md
Normal file
16
versioned_docs/version-1.4.15/about.md
Normal file
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: 关于文档
|
||||
description: 关于本文档站点的一些说明
|
||||
---
|
||||
|
||||
:::note
|
||||
此文档使用 [Docusaurus](https://docusaurus.io/) 搭建,感谢 [Docusaurus](https://github.com/facebook/docusaurus) 社区所做的贡献。
|
||||
:::
|
||||
|
||||
## 参与贡献
|
||||
|
||||
:::tip
|
||||
如果你发现文档中有不正确或者需要添加的内容,非常欢迎参与到文档编辑当中。
|
||||
:::
|
||||
|
||||
当前文档的仓库地址为 [halo-dev/docs](https://github.com/halo-dev/docs) ,所以你可以 fork 此仓库,修改之后提交 `Pull request` 等待我们合并即可。
|
28
versioned_docs/version-1.4.15/contribution/issue.md
Normal file
28
versioned_docs/version-1.4.15/contribution/issue.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: 问题反馈
|
||||
description: 问题反馈渠道及指南
|
||||
---
|
||||
|
||||
:::info
|
||||
如果您在使用过程中遇到了什么问题,您可以通过下面的方式反馈,但请尽量按照要求提出反馈。
|
||||
:::
|
||||
|
||||
## GitHub Issues
|
||||
|
||||
链接:https://github.com/halo-dev/halo/issues
|
||||
|
||||
如果你在使用过程中,遇到了一些 bug 或者需要添加某些新特性,请尽量在 GitHub Issues 进行反馈,这非常有助于我们跟踪解决此问题,您也可以很方便的接收到处理状态。
|
||||
|
||||
建议步骤:
|
||||
|
||||
1. 在 [Issues 列表](https://github.com/halo-dev/halo/issues) 搜索相关问题,看看是否有其他人已经提到了此问题。
|
||||
2. 如果当前还没有人遇到您类似的问题,那么请点击右上角的 `New issue` 按钮创建新的 issue。
|
||||
3. 选择正确的反馈类型。
|
||||
4. 请尽可能详细的按照模板填写内容。
|
||||
5. 点击 `Submit new issue` 提交 issue。
|
||||
|
||||
## Halo 官方社区
|
||||
|
||||
链接:https://bbs.halo.run
|
||||
|
||||
此平台主要目的用于与其他 Halo 用户进行交流。但如果您对 GitHub 不是很熟悉或者没有账号,您也可以在此平台进行反馈。
|
58
versioned_docs/version-1.4.15/contribution/pr.md
Normal file
58
versioned_docs/version-1.4.15/contribution/pr.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: 代码贡献
|
||||
description: 代码贡献指南
|
||||
---
|
||||
|
||||
> 欢迎你参与 Halo 的开发,下面是参与代码贡献的指南,以供参考。
|
||||
|
||||
### 代码贡献步骤
|
||||
|
||||
#### 0. 提交 issue
|
||||
|
||||
任何新功能或者功能改进建议都先提交 issue 讨论一下再进行开发,bug 修复可以直接提交 pull request。
|
||||
|
||||
#### 1. Fork 此仓库
|
||||
|
||||
点击右上角的 `fork` 按钮即可。
|
||||
|
||||
#### 2. Clone 仓库到本地
|
||||
|
||||
```bash
|
||||
git clone https://github.com/{YOUR_USERNAME}/halo
|
||||
|
||||
git submodule init
|
||||
|
||||
git submodule update
|
||||
```
|
||||
|
||||
#### 3. 创建新的开发分支
|
||||
|
||||
```bash
|
||||
git checkout -b {BRANCH_NAME}
|
||||
```
|
||||
|
||||
#### 4. 提交代码
|
||||
|
||||
```bash
|
||||
git push origin {BRANCH_NAME}
|
||||
```
|
||||
|
||||
#### 5. 提交 pull request
|
||||
|
||||
回到自己的仓库页面,选择 `New pull request` 按钮,创建 `Pull request` 到原仓库的 `master` 分支。
|
||||
|
||||
然后等待我们 Review 即可,如有 `Change Request`,再本地修改之后再次提交即可。
|
||||
|
||||
#### 6. 更新主仓库代码到自己的仓库
|
||||
|
||||
```bash
|
||||
git remote add upstream git@github.com:halo-dev/halo.git
|
||||
|
||||
git pull upstream master
|
||||
|
||||
git push
|
||||
```
|
||||
|
||||
### 开发规范
|
||||
|
||||
请参考 [代码风格](/developer-guide/core/code-style),请确保所有代码格式化之后再提交。
|
31
versioned_docs/version-1.4.15/contribution/sponsor.md
Normal file
31
versioned_docs/version-1.4.15/contribution/sponsor.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: 赞助我们
|
||||
description: 如果 Halo 对您有帮助,不妨赞助我们
|
||||
---
|
||||
|
||||
## 为什么需要赞助
|
||||
|
||||
我们花费了大量的精力来维护这个软件,并且也提供了不少资金来维护服务器,域名等。因此我们需要赞助来节省部分开发成本。你的赞助不仅仅会被我们用来支付一些开发成本(比如服务器,OSS,域名等),还会让我们有更多的信心和精力投入到这个开源项目的开发中。从而让项目保持更加健康的成长以及迭代。
|
||||
|
||||
## 赞助形式
|
||||
|
||||
:::info
|
||||
您可以通过任何形式对我们赞助,不限于资金。
|
||||
:::
|
||||
|
||||
### 资金赞助
|
||||
|
||||
| 支付宝 | 微信 |
|
||||
| ------ | ---- |
|
||||
| <img alt="ali-pay.png" src="/img/ali-pay.png" style={{width: '150px'}}/> | <img alt="wechat-pay.png" src="/img/wechat-pay.png" style={{width: '150px'}}/> |
|
||||
|
||||
### 通过我们的推广链接购买服务器
|
||||
|
||||
如果您当前还没有购买服务器,可以考虑通过以下链接购买,这会为我们带来一部分收益。此外,如果您已经通过下面的链接购买了服务器,可以[联系我们](mailto:hi@halo.run)帮您免费部署 Halo。
|
||||
|
||||
- 阿里云:[https://promotion.aliyun.com/ntms/yunparter/invite.html?userCode=3t6v5x0v](https://promotion.aliyun.com/ntms/yunparter/invite.html?userCode=3t6v5x0v)
|
||||
- 阿里云双十一新用户:[https://www.aliyun.com/minisite/goods?taskPkg=1111ydsrwb&pkgSid=12305&userCode=3t6v5x0v](https://www.aliyun.com/minisite/goods?taskPkg=1111ydsrwb&pkgSid=12305&userCode=3t6v5x0v)
|
||||
- 腾讯云:[https://curl.qcloud.com/ewTUJQec](https://curl.qcloud.com/ewTUJQec)
|
||||
- 腾讯云双十一新用户:[https://cloud.tencent.com/act/pre-2021double11?spread_hash_key=f7cce5fd94766a553072b1642977ea7a](https://cloud.tencent.com/act/pre-2021double11?spread_hash_key=f7cce5fd94766a553072b1642977ea7a)
|
||||
- Vultr:[https://www.vultr.com/?ref=7278289](https://www.vultr.com/?ref=7278289)
|
||||
|
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: 代码风格
|
||||
description: 代码风格的相关配置说明
|
||||
---
|
||||
|
||||
Halo 添加了 checkstyle 插件,来保证每位提交者代码的风格保持一致,减少无效代码的修改。本篇文章主要讲解如何在 IDEA 中添加 CheckStyle 插件,并引入项目所提供的 checkstyle.xml 配置。
|
||||
|
||||
## 安装 CheckStyle-IDEA
|
||||
|
||||
- 进入 IDEA 插件市场。
|
||||
- 搜索 CheckStyle-IDEA,点击安装即可。
|
||||
|
||||
## 配置 CheckStyle
|
||||
|
||||
- 进入 CheckStyle 配置(File | Settings | Other Settings | Checkstyle)。
|
||||
- 在配置文件中点击添加按钮,配置描述可随便填写(建议 Halo Checks),选择 ./config/checkstyle/checkstyle.xml,点击下一步和完成;
|
||||
- 勾选刚刚创建的配置文件。
|
||||
|
||||
## 配置 Editor
|
||||
|
||||
- 进入编辑器配置(File | Settings | Editor | Code Style)
|
||||
|
||||
- 导入 checkstyle.xm 配置:
|
||||
|
||||

|
||||
|
||||
- 选择 `./config/checkstyle/checkstyle.xml` 配置文件,点击确定即可。
|
||||
|
||||
至此,有关代码风格检查工具和格式化配置已经完成。
|
137
versioned_docs/version-1.4.15/developer-guide/core/prepare.md
Normal file
137
versioned_docs/version-1.4.15/developer-guide/core/prepare.md
Normal file
@@ -0,0 +1,137 @@
|
||||
---
|
||||
title: 相关说明
|
||||
description: 开发环境的一些说明
|
||||
---
|
||||
|
||||
## 所需要的环境
|
||||
|
||||
1. IDE:[IntelliJ IDEA](https://www.jetbrains.com/idea/download/) 或者 [STS](https://spring.io/tools)(Spring Tools Suite)
|
||||
2. 工具:[Gradle](https://gradle.org/),[Lombok](https://projectlombok.org/) 插件
|
||||
3. JDK:`11+`
|
||||
|
||||
> 推荐 IntelliJ IDEA 社区版(开源免费)https://github.com/JetBrains/intellij-community
|
||||
|
||||
`Halo` 项目使用了 `Lombok`,运行 `Halo` 之前请检查 `IDE` 是否已经安装好了 `Lombok` 插件。
|
||||
|
||||
如果使用的 `IDE` 是 `IntelliJ IDEA`,请在设置中启用 `Build, Execution, Deployment/Annotation Processors` 的 `Enable annotation processing`。
|
||||
|
||||
如果仍然因为 `Lombok` 报错,请更新 `IntelliJ IDEA` 至最新版。
|
||||
|
||||
## 克隆项目(Optional)
|
||||
|
||||
如果你已经 `fork` 了 [`Halo`](https://github.com/halo-dev/halo),请将以下命令中的 `halo-dev` 替换为你的 `Github 用户名`。
|
||||
|
||||
```bash
|
||||
git clone --recursive https://github.com/halo-dev/halo
|
||||
|
||||
// 如果你在 Github 上已经添加了你的 ssh key,请使用以下命令进行 clone:
|
||||
git clone --recursive git@github.com:halo-dev/halo.git
|
||||
```
|
||||
|
||||
这里推荐使用第二种方式进行克隆,这样每次提交代码的时候,就不会提示登录 `Github` 了。
|
||||
|
||||
## 导入项目
|
||||
|
||||
导入项目的时候请选择 `Gradle 项目`进行导入。
|
||||
|
||||
> `IntelliJ IDEA` 在导入项目的时候请勾选 `auto import`,推荐使用 `gradle wrapper`。
|
||||
|
||||
## 运行方式
|
||||
|
||||
`Halo` 运行方式总体来讲有以下两种:
|
||||
|
||||
### 直接运行 `Application` 主类(配合 IDE 运行)
|
||||
|
||||
如果需要指定配置,请在 `Run/Debug Configuration` 内进行设置 `VM options`(这里推荐采用上文的[自定义配置](#%E8%87%AA%E5%AE%9A%E4%B9%89%E9%85%8D%E7%BD%AE)),例如:
|
||||
|
||||
```ini
|
||||
-Dspring.profiles.active=dev
|
||||
-Dhalo.auth-enabled=false
|
||||
-Dhalo.production-env=false
|
||||
```
|
||||
|
||||
### 采用 `gradle bootRun task` 运行(不需要 IDE)
|
||||
|
||||
在项目根目录下运行以下命令:
|
||||
|
||||
```bash
|
||||
# 类 Unix 用户
|
||||
./gradlew bootRun
|
||||
|
||||
# Windows 用户
|
||||
./gradlew.bat bootRun
|
||||
```
|
||||
|
||||
如果需要手动指定配置,可添加 `--args` 参数(这里推荐采用上文的[自定义配置](#%E8%87%AA%E5%AE%9A%E4%B9%89%E9%85%8D%E7%BD%AE)),例如:
|
||||
|
||||
```bash
|
||||
# 类 Unix 用户
|
||||
./gradlew bootRun --args="--spring.profiles.active=dev --server.port=2333"
|
||||
|
||||
# Windows 用户
|
||||
./gradlew.bat bootRun --args="--spring.profiles.active=dev --server.port=2333"
|
||||
```
|
||||
|
||||
如果一切正常且没有额外指定配置,则可根据控制台的输出链接进行访问 `Halo`:
|
||||
|
||||
```java
|
||||
2019-06-06 16:20:52.285 INFO 1330 --- [ restartedMain] run.halo.app.listener.StartedListener : Halo started at http://127.0.0.1:8090
|
||||
2019-06-06 16:20:52.285 INFO 1330 --- [ restartedMain] run.halo.app.listener.StartedListener : Halo admin started at http://127.0.0.1:8090/admin
|
||||
2019-06-06 16:20:52.285 DEBUG 1330 --- [ restartedMain] run.halo.app.listener.StartedListener : Halo doc was enable at http://127.0.0.1:8090/swagger-ui.html # 仅在开发环境才会输出
|
||||
```
|
||||
|
||||
首次运行的时候,会跳转到博客安装页面,请大家耐心填写完毕,最后正式进入`开发之旅`。
|
||||
|
||||
这里推荐一个配置:
|
||||
|
||||
| key | value |
|
||||
| :----- | :------------ |
|
||||
| 用户名 | test |
|
||||
| 昵称 | test |
|
||||
| 邮箱 | test@test.com |
|
||||
| 密码 | opentest |
|
||||
|
||||
---
|
||||
|
||||
## 高级配置
|
||||
|
||||
### 调整启动参数(VMoptions)
|
||||
|
||||
运行命令中添加 `VM options`,例如:
|
||||
|
||||
```ini
|
||||
-Dspring.profiles.active=dev
|
||||
```
|
||||
|
||||
### 调整启动参数(args)
|
||||
|
||||
运行命令中添加参数,例如:
|
||||
|
||||
```ini
|
||||
--spring.profiles.active=dev
|
||||
```
|
||||
|
||||
`IDE` 一般都会提供一个 `Run/Debug 配置`,可以添加 `VM options` 和 `参数`。以上示例可以直接应用在以`命令运行`方式上。
|
||||
|
||||
### 启用自动构建(Build project automatically)
|
||||
|
||||
在开发环境下,修改代码之后,每次都需要重启应用,是一个非常耗时的操作。
|
||||
|
||||
有一个专门解决这个问题的工具,那就是 [JRebel](https://jrebel.com/),但是它的费用实在是太昂贵,作为普通的开发者很难承受这笔费用(但**不推荐**使用破解版)。
|
||||
|
||||
于是 `Halo` 最后采用了 `Spring Boot` 官方推荐的 [Developer Tools](https://docs.spring.io/spring-boot/docs/current/reference/html/using-boot-devtools.html)。
|
||||
|
||||
这里以 `IntelliJ IDEA` 为例。
|
||||
|
||||
1. 进入 `Settings` (Preferences on macOS)。
|
||||
2. 打开 `Build, Execution, Deployment > Compiler`. 启用 `Build project automatically`。
|
||||
3. 点击 `应用`。
|
||||
4. 按 `Ctrl+Shift+A` (Cmd+Shift+A on macOS)快捷键,然后搜索 `Registry`。打开之后找到 `compiler.automake.allow.when.app.running`,并启用它 (IntelliJ IDEA 15 and newer)。
|
||||
|
||||
> 来源于 <https://zeroturnaround.com/software/jrebel/quickstart/intellij/enable-automatic-compilation-in-intellij-idea/>
|
||||
|
||||
Developer Tools 原理
|
||||
|
||||
在保存代码的时候,`IDE` 会自动为我们编译代码,`Developer Tools` 检测到代码的 `class 文件`(只能检测 `classpath` 下的 `class 文件`)的变更,会自动重启项目。注意,这里的重启速度会有质的提升,具体原因是 `Spring Boot` 提供的 `restart 技术`提供了两个 `classloaders`:`base classloader` 和 `restart classloader`。当项目重启的时候 `restart classloader` 将会被抛弃,并重启创建一个,这比 `code starts`(冷启动)快很多。当然,肯定是比不上 `JRebel` 采用的 `Reload 技术`。
|
||||
|
||||
更多细节请查阅: [Automatic Restart](https://docs.spring.io/spring-boot/docs/current/reference/html/using-boot-devtools.html#using-boot-devtools-restart)
|
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: 系统结构
|
||||
description: Halo 项目的构成
|
||||
---
|
||||
|
||||
[Halo](https://github.com/halo-dev/halo) 博客系统分为以下四个部分:
|
||||
|
||||
| 项目名称 | 简介 |
|
||||
| :------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |
|
||||
| [halo](https://github.com/halo-dev/halo) | 提供整个系统的服务,采用 [Spring Boot](https://spring.io/) 开发 |
|
||||
| [halo-admin](https://github.com/halo-dev/halo-admin) | 负责后台管理的渲染,采用 [Vue](https://vuejs.org/) 开发,已集成在 Halo 运行包内,无需独立部署。 |
|
||||
| [halo-comment](https://github.com/halo-dev/halo-comment) | 评论插件,采用 [Vue](https://vuejs.org/) 开发,在主题中运行方式引入构建好的 `Javascript` 文件即可 |
|
||||
| [halo-theme-\*](https://github.com/halo-dev) | 主题项目集,采用 [Freemarker](https://freemarker.apache.org/) 模板引擎编写,需要包含一些特殊的配置才能够被 halo 所使用 |
|
||||
|
||||
## 自定义配置
|
||||
|
||||
> 为什么要提前讲自定义配置呢?是因为在这里让大家了解到 `Halo` 的`配置方式`,以及`配置优先级`,不至于未来运行项目的时候不知道如何优雅地修改配置。
|
||||
|
||||
`Halo` 配置目录优先级如下(从上到下优先级越来越小,上层的配置将会覆盖下层):
|
||||
|
||||
- `Halo` 自定义配置
|
||||
- file:~/.halo/
|
||||
- file:~/.halo-dev/
|
||||
- `Spring Boot` 默认配置
|
||||
- file:./config/
|
||||
- file:./
|
||||
- classpath:/config/
|
||||
- classpath:/
|
||||
|
||||
> 参考: [Application Property Files](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html#boot-features-external-config-application-property-files)
|
||||
|
||||
在开发的时候,希望大家能够在 `~/halo-dev/application.yml` 中进行添加自定义配置。当然后面也会讲到如何用`运行参数` 和 `VM options` 进行控制配置,届时可根据具体情况进行选择。
|
||||
|
||||
|
||||
<article class="message is-warning">
|
||||
<div class="message-body">
|
||||
|
||||
开发的时候,我们不建议直接更改`项目源码`中的所包含的`配置文件`,包括 `application.yml`、`application-dev.yml`、`application-test.yml` 和 `application-user.yml`。
|
||||
|
||||
</div>
|
||||
</article>
|
@@ -0,0 +1,261 @@
|
||||
---
|
||||
title: 配置文件
|
||||
description: 主题配置文件的说明
|
||||
---
|
||||
|
||||
> Halo 的主题模块使用 yaml 来对主题进行配置,`theme.yaml` 里面主要描述主题的名称,开发者的信息,开源地址等等。`settings.yaml` 包含了主题所有的配置选项,需要注意的是,这些选项仅仅是用于构建配置表单,并不起到对主题的配置作用。
|
||||
|
||||
## theme.yaml
|
||||
|
||||
```yaml
|
||||
id: 主题id,唯一,不能与其他主题一样。我们建议设置为 `作者名_主题名称`
|
||||
name: 主题名称
|
||||
author:
|
||||
name: 作者名称
|
||||
website: 作者网址
|
||||
description: 主题描述
|
||||
logo: 主题 Logo 地址
|
||||
website: 主题地址,可填写为 git 仓库地址
|
||||
repo: 主题 git 仓库地址,如有填写,后台可在线更新
|
||||
version: 版本号
|
||||
require: 最低支持的 Halo 版本,如:1.3.0,那么如果用户的版本为 1.3.0 以下,则无法安装
|
||||
|
||||
postMetaField: 文章自定义 meta 变量
|
||||
- meta_key
|
||||
|
||||
sheetMetaField:
|
||||
- meta_key 页面自定义 meta 变量
|
||||
```
|
||||
|
||||
示例:
|
||||
|
||||
```yaml
|
||||
id: caicai_anatole
|
||||
name: Anatole
|
||||
author:
|
||||
name: Caicai
|
||||
website: https://www.caicai.me
|
||||
description: A other Halo theme
|
||||
logo: https://avatars1.githubusercontent.com/u/1811819?s=460&v=4
|
||||
website: https://github.com/halo-dev/halo-theme-anatole
|
||||
repo: https://github.com/halo-dev/halo-theme-anatole
|
||||
version: 1.0.0
|
||||
require: 1.3.0
|
||||
postMetaField:
|
||||
- music_url # 假设在文章页面需要播放背景音乐,用户可以自己填写音乐地址。
|
||||
- download_url # 假设在文章页有一个下载按钮,那么用户也可以自己填写加载地址。
|
||||
|
||||
sheetMetaField:
|
||||
- music_url
|
||||
- download_url
|
||||
```
|
||||
|
||||
### 自定义 meta
|
||||
|
||||
这个为 1.2.0 引入的功能,用户可以在文章设置中设置自定义 meta,我们在 `theme.yaml` 中填写的 `postMetaField` 和 `sheetMetaField` 为预设项,当用户激活当前主题之后,在文章设置中即可看到预先设置好的项,然后填写对应的值即可。
|
||||
|
||||
关于这个 meta 变量如何调用的问题,会在后面的模板变量中阐述。
|
||||
|
||||
## settings.yaml
|
||||
|
||||
```yaml
|
||||
# Tab 节点
|
||||
group1:
|
||||
label: 第一个 Tab 名称
|
||||
# 表单项
|
||||
items:
|
||||
# 省略
|
||||
group2:
|
||||
label: 第二个 Tab 名称
|
||||
# 表单项
|
||||
items:
|
||||
# 省略
|
||||
```
|
||||
|
||||
## settings.yaml#items
|
||||
|
||||
> settings.yaml 的 items 下即为所有表单元素,所支持的表单元素如下
|
||||
|
||||
```yaml
|
||||
items:
|
||||
|
||||
# 普通文本框
|
||||
item1:
|
||||
name: item1 // 设置项的 name 值,在页面可通过 ${settings.item1!} 获取值。
|
||||
label: item1 // 表单项的 label
|
||||
type: text // 表单项类型:普通文本框
|
||||
placeholder: '' // 表单项的 placeholder,一般给用户提示
|
||||
default: '' // 表单项的默认值
|
||||
description: '' // 描述,一般用于说明该设置的具体用途
|
||||
|
||||
# 颜色选择框
|
||||
item1:
|
||||
name: item1 // 设置项的 name 值,在页面可通过 ${settings.item1!} 获取值。
|
||||
label: item1 // 表单项的 label
|
||||
type: color // 表单项类型:颜色选择框
|
||||
placeholder: '' // 表单项的 placeholder,一般给用户提示
|
||||
default: '' // 表单项的默认值
|
||||
description: '' // 描述,一般用于说明该设置的具体用途
|
||||
|
||||
# 附件选择框
|
||||
item1:
|
||||
name: item1 // 设置项的 name 值,在页面可通过 ${settings.item1!} 获取值。
|
||||
label: item1 // 表单项的 label
|
||||
type: attachment // 表单项类型:颜色选择框
|
||||
placeholder: '' // 表单项的 placeholder,一般给用户提示
|
||||
default: '' // 表单项的默认值
|
||||
description: '' // 描述,一般用于说明该设置的具体用途
|
||||
|
||||
# 多行文本框
|
||||
item2: // 设置项的 name 值,在页面可通过 ${settings.item2!} 获取值。
|
||||
name: item2
|
||||
label: item2 // 同上
|
||||
type: textarea // 表单项类型:多行文本框
|
||||
placeholder: '' // 同上
|
||||
default: '' // 同上
|
||||
description: '' // 描述,一般用于说明该设置的具体用途
|
||||
|
||||
# 单选框
|
||||
item3:
|
||||
name: item3 // 同上
|
||||
label: item3_label // 同上
|
||||
type: radio // 表单项类型:单选框
|
||||
data-type: bool // 数据类型:bool,string,long,double
|
||||
default: value1 // 同上
|
||||
description: '' // 描述,一般用于说明该设置的具体用途
|
||||
options: // 选项
|
||||
- value: value1 // 值
|
||||
label: label1 // 说明
|
||||
- value: value2
|
||||
label: label2
|
||||
|
||||
# 下拉框
|
||||
item4:
|
||||
name: item4 // 同上
|
||||
label: item4 // 同上
|
||||
type: select // 表单项类型:下拉框
|
||||
data-type: bool // 数据类型:bool,string,long,double
|
||||
default: value1 // 同上
|
||||
description: '' // 描述,一般用于说明该设置的具体用途
|
||||
options: // 选项
|
||||
- value: value1 // 值
|
||||
label: label1 // 说明
|
||||
- value: value2
|
||||
label: label2
|
||||
```
|
||||
|
||||
### 一个例子
|
||||
|
||||
假设我们的配置文件如下:
|
||||
|
||||
```yaml
|
||||
general:
|
||||
label: 基础设置
|
||||
items:
|
||||
index_title:
|
||||
name: index_title
|
||||
label: 首页标题
|
||||
type: text
|
||||
description: '注意:将覆盖博客标题'
|
||||
background_cover:
|
||||
name: background_cover
|
||||
label: 首页背景图
|
||||
type: attachment
|
||||
default: '/casper/assets/images/blog-cover.jpg'
|
||||
description: '设置首页的背景图,你可以点击右边的选择按钮选择图片。'
|
||||
background_color:
|
||||
name: background_color
|
||||
label: 首页背景颜色
|
||||
type: color
|
||||
default: '#fff'
|
||||
music_enabled:
|
||||
name: music_enabled
|
||||
label: 背景音乐
|
||||
type: radio
|
||||
data-type: bool
|
||||
default: false
|
||||
description: '是否开启背景音乐,默认为 false'
|
||||
options:
|
||||
- value: true
|
||||
label: 开启
|
||||
- value: false
|
||||
label: 关闭
|
||||
code_pretty:
|
||||
name: code_pretty
|
||||
label: 文章代码高亮主题
|
||||
type: select
|
||||
default: Default
|
||||
options:
|
||||
- value: Default
|
||||
label: Default
|
||||
- value: Coy
|
||||
label: Coy
|
||||
- value: Dark
|
||||
label: Dark
|
||||
- value: Okaidia
|
||||
label: Okaidia
|
||||
- value: Solarized Light
|
||||
label: Solarized Light
|
||||
- value: Tomorrow Night
|
||||
label: Tomorrow Night
|
||||
- value: Twilight
|
||||
label: Twilight
|
||||
```
|
||||
|
||||
页面取值:
|
||||
|
||||
```html
|
||||
// 获取首页标题
|
||||
|
||||
<#if settings.index_title?? && settings.index_title != ''>
|
||||
<h1>${settings.index_title!}</h1>
|
||||
</#if>
|
||||
```
|
||||
|
||||
```html
|
||||
// 获取背景图片
|
||||
|
||||
<#if settings.background_cover?? && settings.background_cover != ''>
|
||||
<img src="${settings.background_cover!}">
|
||||
</#if>
|
||||
```
|
||||
|
||||
```html
|
||||
// 获取背景颜色
|
||||
|
||||
<style>
|
||||
body{
|
||||
<#if settings.background_color?? && settings.background_color != ''>
|
||||
background-color: ${settings.background_color!}
|
||||
<#else>
|
||||
background-color: #fff
|
||||
</#if>
|
||||
}
|
||||
</style>
|
||||
|
||||
或者
|
||||
|
||||
<style>
|
||||
body{
|
||||
background-color: ${settings.background_color!'#fff'}
|
||||
}
|
||||
</style>
|
||||
|
||||
```
|
||||
|
||||
```html
|
||||
// 判断是否开启背景音乐
|
||||
|
||||
<#if settings.music_enabled!false>
|
||||
do something...
|
||||
</#if>
|
||||
```
|
||||
|
||||
```html
|
||||
// 获取代码高亮主题
|
||||
|
||||
<link rel="stylesheet" type="text/css" href="${theme_base!}/assets/prism/css/prism-${settings.code_pretty!'Default'}.css" />
|
||||
<script type="text/javascript" src="${theme_base!}/assets/prism/js/prism.js"></script>
|
||||
```
|
||||
|
||||
更多实例可参考:<https://github.com/halo-dev/halo-theme-material/blob/master/settings.yaml>。
|
@@ -0,0 +1,263 @@
|
||||
---
|
||||
title: 全局变量
|
||||
description: 系统提供的一些全局变量
|
||||
---
|
||||
|
||||
## 博客地址
|
||||
|
||||
```
|
||||
${blog_url!}
|
||||
```
|
||||
|
||||
此变量与后台博客设置中的 `博客地址` 相对应。
|
||||
|
||||
|
||||
## 网站根路径
|
||||
|
||||
```
|
||||
${context!}
|
||||
```
|
||||
|
||||
需要注意的是,此变量和 `blog_url` 不同的是,这个变量有两种值,一种为相对路径形式,一种为绝对路径形式。
|
||||
|
||||
那么,当在后台博客设置中将 `全局绝对路径` 的选项打开时,`context` 变量值为 `${blog_url}/`,关闭时,`context` 的变量值为 `/`。
|
||||
|
||||
假设,我设置的 `博客地址` 为 `https://halo.run`,那么:
|
||||
|
||||
- 全局绝对路径为开启的状态下:https://halo.run/
|
||||
- 全局绝对路径为关闭的状态下:/
|
||||
|
||||
## 主题资源根路径
|
||||
|
||||
```
|
||||
${theme_base!}
|
||||
```
|
||||
|
||||
假设你的主题在 `~/halo-dev/templates/themes/anatole` 这个目录,那么 `theme_base` 为 `https://yourdomain/themes/anatole`
|
||||
|
||||
举个例子,你当前开发的主题为 `anatole`,当你要获取主题下 `css/style.css` 这个文件的路径,那么:
|
||||
|
||||
```
|
||||
${theme_base!}/css/style.css
|
||||
```
|
||||
|
||||
## 主题信息
|
||||
|
||||
主题名称:
|
||||
|
||||
```
|
||||
${theme.name!}
|
||||
```
|
||||
|
||||
主题 git 仓库地址:
|
||||
|
||||
```
|
||||
${theme.repo!}
|
||||
```
|
||||
|
||||
主题版本号:
|
||||
|
||||
```
|
||||
${theme.version!}
|
||||
```
|
||||
|
||||
## 博客标题
|
||||
|
||||
```
|
||||
${blog_title!}
|
||||
```
|
||||
|
||||
此变量与后台博客设置中的 `博客标题` 相对应。
|
||||
|
||||
## 博客 Logo
|
||||
|
||||
```
|
||||
${blog_logo!}
|
||||
```
|
||||
|
||||
此变量与后台博客设置中的 `Logo` 相对应。
|
||||
|
||||
## Halo 版本
|
||||
|
||||
```
|
||||
${version!}
|
||||
```
|
||||
|
||||
当前 Halo 的版本,如:1.3.0
|
||||
|
||||
## 博主信息
|
||||
|
||||
昵称:
|
||||
|
||||
```
|
||||
${user.nickname!}
|
||||
```
|
||||
|
||||
邮箱地址:
|
||||
|
||||
```
|
||||
${user.email!}
|
||||
```
|
||||
|
||||
描述:
|
||||
|
||||
```
|
||||
${user.description!}
|
||||
```
|
||||
|
||||
头像地址:
|
||||
|
||||
```
|
||||
${user.avatar!}
|
||||
```
|
||||
|
||||
上次登录时间:
|
||||
|
||||
```
|
||||
${user.expireTime!}
|
||||
```
|
||||
|
||||
## SEO 关键词
|
||||
|
||||
```
|
||||
${meta_keywords!}
|
||||
```
|
||||
|
||||
需要注意的是,虽然这个变量在任何页面都可以使用,但是其值可能在不同的页面是不一样的。会根据用户的设置,生成对应的值。
|
||||
|
||||
假设在文章页面:
|
||||
|
||||
- 如果用户为文章设置了标签,而没有设置 `自定义关键词`,系统会自动将标签设置为页面关键词。
|
||||
- 如果用户设置了 `自定义关键词`,那么则会取用户设置的值。
|
||||
|
||||
## SEO 描述
|
||||
|
||||
```
|
||||
${meta_description!}
|
||||
```
|
||||
|
||||
需要注意的是,虽然这个变量在任何页面都可以使用,但是其值可能在不同的页面是不一样的。会根据用户的设置,生成对应的值。
|
||||
|
||||
|
||||
## RSS 2.0 订阅地址
|
||||
|
||||
```
|
||||
${rss_url!}
|
||||
```
|
||||
|
||||
如:`https://yourdomain/rss.xml`
|
||||
|
||||
## Atom 格式的订阅地址
|
||||
|
||||
```
|
||||
${atom_url!}
|
||||
```
|
||||
|
||||
如:`https://yourdomain/atom.xml`
|
||||
|
||||
## Xml 格式的网站地图地址
|
||||
|
||||
```
|
||||
${sitemap_xml_url!}
|
||||
```
|
||||
|
||||
如:`https://yourdomain/sitemap.xml`
|
||||
|
||||
## HTML 格式的网站地图地址
|
||||
|
||||
```
|
||||
${sitemap_html_url!}
|
||||
```
|
||||
|
||||
如:`https://yourdomain/sitemap.html`
|
||||
|
||||
## 友情链接页面地址
|
||||
|
||||
```
|
||||
${links_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**:`https://yourdomain.com/{links_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**:`/{links_prefix}`
|
||||
|
||||
`{links_prefix}` 是用户可设定的值,用户可以在后台修改 `友情链接` 的前缀,默认为 `links`。
|
||||
|
||||
## 图库页面地址
|
||||
|
||||
```
|
||||
${photos_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**:`https://yourdomain.com/{photos_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**:`/{photos_prefix}`
|
||||
|
||||
`{photos_prefix}` 是用户可设定的值,用户可以在后台修改 `图库页面` 的前缀,默认为 `photos`。
|
||||
|
||||
## 日志页面地址
|
||||
|
||||
```
|
||||
${journals_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**:`https://yourdomain.com/{journals_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**:`/{journals_prefix}`
|
||||
|
||||
`{journals_prefix}` 是用户可设定的值,用户可以在后台修改 `日志页面` 的前缀,默认为 `journals`。
|
||||
|
||||
## 文章归档页面地址
|
||||
|
||||
```
|
||||
${archives_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**:`https://yourdomain.com/{archives_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**:`/{archives_prefix}`
|
||||
|
||||
`{archives_prefix}` 是用户可设定的值,用户可以在后台修改 `归档` 的前缀,默认为 `archives`。
|
||||
|
||||
## 分类列表页面地址
|
||||
|
||||
```
|
||||
${categories_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**:`https://yourdomain.com/{categories_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**:`/{categories_prefix}`
|
||||
|
||||
`{categories_prefix}` 是用户可设定的值,用户可以在后台修改 `分类` 的前缀,默认为 `categories`。
|
||||
|
||||
## 标签列表页面地址
|
||||
|
||||
```
|
||||
${tags_url!}
|
||||
```
|
||||
|
||||
- **全局绝对路径为开启的状态下**:`https://yourdomain.com/{tags_prefix}`
|
||||
- **全局绝对路径为关闭的状态下**:`/{tags_prefix}`
|
||||
|
||||
`{tags_prefix}` 是用户可设定的值,用户可以在后台修改 `标签` 的前缀,默认为 `tags`。
|
||||
|
||||
## 页面判断
|
||||
|
||||
判断当前页面是否是特定的页面。
|
||||
|
||||
- **is_index**:首页
|
||||
- **is_post**:文章页
|
||||
- **is_sheet**:自定义页面
|
||||
- **is_archives**:归档页面
|
||||
- **is_categories**:分类列表页面
|
||||
- **is_category**:单个分类页面
|
||||
- **is_tags**:标签列表页面
|
||||
- **is_tag**:单个标签页面
|
||||
- **is_search**:搜索结果页面
|
||||
- **is_journals**:日志页面
|
||||
- **is_photos**:图库页面
|
||||
- **is_links**:友情链接页面
|
||||
|
||||
用法:
|
||||
|
||||
```html
|
||||
<#if is_index??>
|
||||
当前页面是首页
|
||||
</#if>
|
||||
```
|
1354
versioned_docs/version-1.4.15/developer-guide/theme/page-variable.md
Normal file
1354
versioned_docs/version-1.4.15/developer-guide/theme/page-variable.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: 准备工作
|
||||
description: 主题开发的环境搭建
|
||||
---
|
||||
|
||||
:::info
|
||||
Halo 的模板引擎为 Freemarker,建议在开发 Halo 的主题之前,先阅读一遍 Freemarker 的相关文档:<https://freemarker.apache.org>。
|
||||
:::
|
||||
|
||||
## 搭建开发环境
|
||||
|
||||
> 假设你已经在本地电脑配置好了 Java 开发环境。
|
||||
|
||||
Halo 的运行可参考上述 [系统开发](/developer-guide/core/prepare),或者直接下载打包好的程序启动,如下步骤:
|
||||
|
||||
1. 从 [Github release](https://github.com/halo-dev/halo/releases) 或者 [https://dl.halo.run](https://dl.halo.run) 下载最新的运行包。
|
||||
2. 在终端中执行 `java -jar halo.jar --spring.profiles.active=dev`
|
||||
|
||||
启动完成之后,在电脑的用户目录即可看到 `halo-dev` 文件夹。
|
||||
|
||||
## 新建主题
|
||||
|
||||
1. 在 `~/halo-dev/templates/themes` 下新建一个文件夹,该文件夹就是你所新建的主题目录。
|
||||
2. 使用你熟悉的编辑器打开你所新建的主题目录,这里我们推荐使用 [Visual Studio Code](https://code.visualstudio.com),并安装 [Freemarker](https://marketplace.visualstudio.com/items?itemName=dcortes92.FreeMarker) 扩展。
|
||||
|
||||
:::info
|
||||
我们同样为 Halo 主题开发了一个 `Visual Studio Code` Snippets 扩展,以简化一些操作,但目前处于 beta 状态,有需要的可以试试 [Halo theme develop Snippets](https://marketplace.visualstudio.com/items?itemName=halo-dev.halo-theme-dev-snippets-for-vs-code)。
|
||||
:::
|
||||
|
||||
## 开发约定
|
||||
|
||||
- 主题目录下必须存在 `theme.yaml(主题描述文件)`,`settings.yaml(主题配置文件)`,相关格式在后面会详细讲解。
|
||||
- 如果要开源到 Github 我们建议将仓库名设置为 `halo-theme-主题名`,并设置仓库的 `topic` 为 `halo` 和 `halo-theme`,这样可以方便使用者搜索。
|
||||
- 所有模板文件的后缀为 `.ftl`。
|
||||
- 主题目录需要以 `screenshot.png` 命名的预览图片,以供后台展示。
|
||||
|
||||
## 开发样板
|
||||
|
||||
> 为了让开发者更快速的上手主题的开发,我们提供了一个简单的开发样板以供参考。
|
||||
|
||||
仓库地址:<https://github.com/halo-dev/halo-theme-quick-starter>
|
||||
|
||||
## 目录结构
|
||||
|
||||
> 为了让开发更加规范,我们推荐使用以下的目录结构。
|
||||
|
||||
```
|
||||
├── module // 公共模板目录
|
||||
│ ├── comment.ftl // 比如:评论模板
|
||||
│ ├── layout.ftl // 比如:布局模板
|
||||
├── source // 静态资源目录
|
||||
│ ├── css // 样式目录
|
||||
│ ├── images // 图片目录
|
||||
│ ├── js // JS 脚本目录
|
||||
│ └── plugins // 前端库目录
|
||||
├── index.ftl // 首页
|
||||
├── post.ftl // 文章页
|
||||
├── post_xxx.ftl // 自定义文章模板,如:post_diary.ftl。可在后台发布文章时选择。
|
||||
├── sheet.ftl // 自定义页面
|
||||
├── sheet_xxx.ftl // 自定义模板,如:sheet_search.ftl、sheet_author.ftl。可在后台发布页面时选择。
|
||||
├── archives.ftl // 归档页
|
||||
├── categories.ftl // 分类目录页
|
||||
├── category.ftl // 单个分类的所属文章页
|
||||
├── tags.ftl // 标签页面
|
||||
├── tag.ftl // 单个标签的所属文章页
|
||||
├── search.ftl // 搜索结果页
|
||||
├── links.ftl // 内置页面:友情链接
|
||||
├── photos.ftl // 内置页面:图库
|
||||
├── journals.ftl // 内置页面:日志
|
||||
├── 404.ftl // 404 页
|
||||
├── 500.ftl // 500 页
|
||||
├── README.md // README,一般用于主题介绍或说明
|
||||
├── screenshot.png // 主题预览图
|
||||
├── settings.yaml // 主题选项配置文件
|
||||
└── theme.yaml // 主题描述文件
|
||||
```
|
@@ -0,0 +1,95 @@
|
||||
---
|
||||
title: 公共宏模板
|
||||
description: 系统提供的一些宏模板
|
||||
---
|
||||
|
||||
> 为了减少重复代码,我们将某些常见的全局变量封装成了一个公共模板,我们只需要引入该模板,然后调用其中的宏模板即可。
|
||||
|
||||
## 公共 head 模板
|
||||
|
||||
> 需要注意的是,为了保证系统功能的完整性,我们强制要求在每个页面的 `<head>` 标签下必须包含此模板。
|
||||
|
||||
```html
|
||||
<@global.head />
|
||||
```
|
||||
|
||||
等同于:
|
||||
|
||||
```html
|
||||
<#if options.seo_spider_disabled!false>
|
||||
<meta name="robots" content="none">
|
||||
</#if>
|
||||
<meta name="generator" content="Halo ${version!}"/>
|
||||
<@global.favicon />
|
||||
<@global.custom_head />
|
||||
<@global.custom_content_head />
|
||||
```
|
||||
|
||||
## 公共底部
|
||||
|
||||
> 需要注意的是,为了保证系统功能的完整性,我们强制要求在每个页面的尾部必须包含此模板。
|
||||
|
||||
|
||||
```html
|
||||
<@global.footer />
|
||||
```
|
||||
|
||||
|
||||
等同于:
|
||||
|
||||
```html
|
||||
<@global.statistics />
|
||||
<@global.footer_info />
|
||||
````
|
||||
|
||||
## 相对时间
|
||||
|
||||
```html
|
||||
<@global.timeline datetime="时间" />
|
||||
|
||||
// 输出
|
||||
x 年前/x 个月前/x 天前/昨天/x 小时前/x 分钟前/x 秒前/刚刚
|
||||
```
|
||||
|
||||
|
||||
## 评论模块
|
||||
|
||||
```html
|
||||
<@global.comment target= type="" />
|
||||
```
|
||||
|
||||
等同于:
|
||||
|
||||
```html
|
||||
<#if !post.disallowComment!false>
|
||||
<script src="//cdn.jsdelivr.net/npm/vue@2.6.10/dist/vue.min.js"></script>
|
||||
<script src="${options.comment_internal_plugin_js!'//cdn.jsdelivr.net/npm/halo-comment@latest/dist/halo-comment.min.js'"></script>
|
||||
<halo-comment id="${post.id}" type="${type}"/>
|
||||
</#if>
|
||||
```
|
||||
|
||||
参数说明:
|
||||
|
||||
- target:post / sheet / journal 对象
|
||||
- type:评论类型,可为:post / sheet / journal
|
||||
|
||||
|
||||
例子:
|
||||
|
||||
在文章页面(post.ftl or post_xxx.ftl):
|
||||
|
||||
```
|
||||
<@global.comment target=post type="post" />
|
||||
```
|
||||
|
||||
在自定义页面(sheet.ftl or post_sheet.ftl):
|
||||
|
||||
```
|
||||
<@global.comment target=sheet type="sheet" />
|
||||
```
|
||||
|
||||
在日志页面(journals.ftl):
|
||||
|
||||
```
|
||||
<@global.comment target=journal type="journal" />
|
||||
```
|
2645
versioned_docs/version-1.4.15/developer-guide/theme/template-tag.md
Normal file
2645
versioned_docs/version-1.4.15/developer-guide/theme/template-tag.md
Normal file
File diff suppressed because it is too large
Load Diff
195
versioned_docs/version-1.4.15/getting-started/config.md
Normal file
195
versioned_docs/version-1.4.15/getting-started/config.md
Normal file
@@ -0,0 +1,195 @@
|
||||
---
|
||||
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` 使用配置文件中的即可。
|
||||
|
||||
#### 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
|
||||
cache: memory
|
||||
```
|
||||
|
||||
目前支持两种策略:
|
||||
- `memory` 将数据缓存至内存,重启服务缓存将清空。
|
||||
- `level` 将数据缓存至本地,重启服务不会清空缓存。
|
||||
|
||||
### 压缩
|
||||
启用压缩对于减少带宽和加快页面加载非常有用,在**未使用** `Nginx` 或 `Caddy` 等反向代理服务器时(反向代理服务器通常是默认开启 Gzip 的),可以考虑开启系统自带的Gzip 功能。
|
||||
|
||||
```yaml
|
||||
server:
|
||||
# Response data gzip.
|
||||
compression:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
## 示例配置文件
|
||||
|
||||
:::info
|
||||
建议根据使用的数据库类型查看。
|
||||
:::
|
||||
|
||||
### H2 Database
|
||||
|
||||
```yaml
|
||||
server:
|
||||
port: 8090
|
||||
|
||||
# Response data gzip.
|
||||
compression:
|
||||
enabled: false
|
||||
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
|
||||
cache: memory
|
||||
```
|
||||
|
||||
### MySQL
|
||||
|
||||
```yaml
|
||||
server:
|
||||
port: 8090
|
||||
|
||||
# Response data gzip.
|
||||
compression:
|
||||
enabled: false
|
||||
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
|
||||
cache: memory
|
||||
```
|
||||
|
||||
官方的完整示例配置文件可以在 [https://dl.halo.run/config/](https://dl.halo.run/config/) 下找到。
|
25
versioned_docs/version-1.4.15/getting-started/downloads.md
Normal file
25
versioned_docs/version-1.4.15/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://dl.halo.run](https://dl.halo.run)
|
||||
|
||||
此镜像源由 [Nova Kwok](https://nova.moe/) 提供并维护。
|
||||
|
||||
## 三方镜像源
|
||||
|
||||
- [https://halo.cary.tech](https://halo.cary.tech)
|
||||
|
||||
此镜像源由 [新逸Cary](https://blog.xinac.cn) 提供并维护。
|
101
versioned_docs/version-1.4.15/getting-started/install/docker.md
Normal file
101
versioned_docs/version-1.4.15/getting-started/install/docker.md
Normal file
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: 使用 Docker 部署 Halo
|
||||
description: 使用 Docker 部署
|
||||
---
|
||||
|
||||
:::info
|
||||
在继续操作之前,我们推荐您先阅读[《写在前面》](/getting-started/prepare),这可以快速帮助你了解 Halo。
|
||||
:::
|
||||
|
||||
## 使用 Docker 镜像
|
||||
Halo 在 Docker Hub 上发布的镜像为 [halohub/halo](https://hub.docker.com/r/halohub/halo)
|
||||
|
||||
1. 创建[工作目录](/getting-started/prepare#工作目录)
|
||||
```bash
|
||||
mkdir ~/.halo && cd ~/.halo
|
||||
```
|
||||
|
||||
2. 下载示例配置文件到[工作目录](/getting-started/prepare#工作目录)
|
||||
```bash
|
||||
wget https://dl.halo.run/config/application-template.yaml -O ./application.yaml
|
||||
```
|
||||
|
||||
3. 编辑配置文件,配置数据库或者端口等,如需配置请参考[参考配置](/getting-started/config)
|
||||
```bash
|
||||
vim application.yaml
|
||||
```
|
||||
|
||||
4. 拉取最新的 Halo 镜像
|
||||
```bash
|
||||
docker pull halohub/halo:1.4.15
|
||||
```
|
||||
|
||||
:::info
|
||||
查看最新版本镜像:https://hub.docker.com/r/halohub/halo ,我们推荐使用具体版本号的镜像,但也提供了 `latest` 标签的镜像,它始终是最新的。
|
||||
:::
|
||||
|
||||
5. 创建容器
|
||||
```bash
|
||||
docker run -it -d --name halo -p 8090:8090 -v ~/.halo:/root/.halo --restart=unless-stopped halohub/halo:1.4.15
|
||||
```
|
||||
- **-it:** 开启输入功能并连接伪终端
|
||||
- **-d:** 后台运行容器
|
||||
- **--name:** 为容器指定一个名称
|
||||
- **-p:** 端口映射,格式为 `主机(宿主)端口:容器端口` ,可在 `application.yaml` 配置。
|
||||
- **-v:** 工作目录映射。形式为:-v 宿主机路径:/root/.halo,后者不能修改。
|
||||
- **--restart:** 建议设置为 `unless-stopped`,在 Docker 启动的时候自动启动 Halo 容器。
|
||||
|
||||
6. 打开 `http://ip:端口号` 即可看到安装引导界面。
|
||||
|
||||
:::tip
|
||||
如果需要配置域名访问,建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip:端口号` 的形式无法访问,请到服务器厂商后台将运行的端口号添加到安全组,如果服务器使用了 Linux 面板,请检查此 Linux 面板是否有还有安全组配置,需要同样将端口号添加到安全组。
|
||||
:::
|
||||
|
||||
## 反向代理
|
||||
|
||||
你可以在下面的反向代理软件中任选一项,我们假设你已经安装好了其中一项,并对其的基本操作有一定了解。如果你对 Nginx 不熟悉,我们推荐使用 [OneinStack](/getting-started/install/other/oneinstack) 来管理 Nginx。
|
||||
|
||||
### Nginx
|
||||
|
||||
```nginx
|
||||
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 1.x
|
||||
|
||||
```
|
||||
https://www.yourdomain.com {
|
||||
gzip
|
||||
tls your@email.com
|
||||
proxy / localhost:8090 {
|
||||
transparent
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Caddy 2.x
|
||||
|
||||
```
|
||||
www.yourdomain.com
|
||||
|
||||
encode gzip
|
||||
|
||||
reverse_proxy 127.0.0.1:8090
|
||||
```
|
||||
|
||||
以上配置都可以在 https://github.com/halo-dev/halo-common 找到。
|
253
versioned_docs/version-1.4.15/getting-started/install/linux.md
Normal file
253
versioned_docs/version-1.4.15/getting-started/install/linux.md
Normal file
@@ -0,0 +1,253 @@
|
||||
---
|
||||
title: 在 Linux 环境部署
|
||||
description: 在Linux上快速安装Halo
|
||||
---
|
||||
|
||||
:::info
|
||||
在继续操作之前,我们推荐您先阅读[《写在前面》](/getting-started/prepare),这可以快速帮助你了解 Halo。
|
||||
:::
|
||||
|
||||
## 依赖检查
|
||||
目前运行 Halo 的最低依赖要求为 JRE 11,请务必确保在进行下面操作之前已经正确安装了 JRE。
|
||||
|
||||
目前介绍两种 Linux 发行版的安装方式,均为 OpenJRE,不推荐 Oracle 版本。
|
||||
|
||||
### CentOS <i class="mdi mdi-centos"></i>
|
||||
|
||||
```bash
|
||||
sudo yum install java-11-openjdk -y
|
||||
```
|
||||
|
||||
检查版本:
|
||||
|
||||
```bash
|
||||
java -version
|
||||
```
|
||||
|
||||
如果输出以下类似内容即代表成功
|
||||
|
||||
```bash
|
||||
openjdk version "11.0.10" 2021-01-19 LTS
|
||||
OpenJDK Runtime Environment 18.9 (build 11.0.10+9-LTS)
|
||||
OpenJDK 64-Bit Server VM 18.9 (build 11.0.10+9-LTS, mixed mode, sharing)
|
||||
```
|
||||
|
||||
### Ubuntu <i class="mdi mdi-ubuntu"></i>
|
||||
|
||||
```bash
|
||||
sudo apt-get install openjdk-11-jre -y
|
||||
```
|
||||
|
||||
检查版本:
|
||||
|
||||
```bash
|
||||
java -version
|
||||
```
|
||||
|
||||
如果输出以下类似内容即代表成功
|
||||
|
||||
```bash
|
||||
openjdk version "11.0.10" 2021-01-19
|
||||
OpenJDK Runtime Environment (build 11.0.10+9-Ubuntu-0ubuntu1.20.04)
|
||||
OpenJDK 64-Bit Server VM (build 11.0.10+9-Ubuntu-0ubuntu1.20.04, mixed mode)
|
||||
```
|
||||
|
||||
## 安装
|
||||
|
||||
1. 创建新的系统用户
|
||||
|
||||
:::info
|
||||
我们不推荐直接使用系统 root 用户来运行 Halo。如果您需要直接使用 root 用户,请跳过这一步。
|
||||
:::
|
||||
|
||||
创建一个名为 halo 的用户(名字可以随意)
|
||||
```bash
|
||||
useradd -m halo
|
||||
```
|
||||
|
||||
给予 sudo 权限
|
||||
```bash
|
||||
usermod -aG wheel halo
|
||||
```
|
||||
|
||||
为 halo 用户创建密码
|
||||
```bash
|
||||
passwd halo
|
||||
```
|
||||
|
||||
登录到 halo 账户
|
||||
```bash
|
||||
su - halo
|
||||
```
|
||||
|
||||
2. 创建存放 [运行包](/getting-started/prepare#运行包) 的目录,这里以 `~/app` 为例
|
||||
|
||||
```
|
||||
mkdir ~/app && cd ~/app
|
||||
```
|
||||
|
||||
3. 下载运行包
|
||||
```bash
|
||||
wget https://dl.halo.run/release/halo-1.4.15.jar -O halo.jar
|
||||
```
|
||||
|
||||
:::info
|
||||
如果下载速度不理想,可以 [在这里](/getting-started/downloads) 选择其他下载地址。
|
||||
:::
|
||||
|
||||
4. 创建 [工作目录](/getting-started/prepare#工作目录)
|
||||
|
||||
```bash
|
||||
mkdir ~/.halo && cd ~/.halo
|
||||
```
|
||||
|
||||
5. 下载示例配置文件到 [工作目录](/getting-started/prepare#工作目录)
|
||||
```bash
|
||||
wget https://dl.halo.run/config/application-template.yaml -O ./application.yaml
|
||||
```
|
||||
|
||||
6. 编辑配置文件,配置数据库或者端口等,如需配置请参考 [参考配置](/getting-started/config)
|
||||
```bash
|
||||
vim application.yaml
|
||||
```
|
||||
|
||||
7. 测试运行 Halo
|
||||
```bash
|
||||
cd ~/app && java -jar halo.jar
|
||||
```
|
||||
|
||||
8. 如看到类似以下日志输出,则代表启动成功。
|
||||
```bash
|
||||
run.halo.app.listener.StartedListener : Halo started at http://127.0.0.1:8090
|
||||
run.halo.app.listener.StartedListener : Halo admin started at http://127.0.0.1:8090/admin
|
||||
run.halo.app.listener.StartedListener : Halo has started successfully!
|
||||
```
|
||||
打开 `http://ip: 端口号` 即可看到安装引导界面。
|
||||
|
||||
:::info
|
||||
如测试启动正常,请继续看`作为服务运行`部分,第 8 步仅仅作为测试。当你关闭 ssh 连接之后,服务会停止。你可使用 <kbd>CTRL</kbd>+<kbd>C</kbd> 停止运行测试进程。
|
||||
:::
|
||||
|
||||
:::tip
|
||||
如果需要配置域名访问,建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip: 端口号` 的形式无法访问,请到服务器厂商后台将运行的端口号添加到安全组,如果服务器使用了 Linux 面板,请检查此 Linux 面板是否有还有安全组配置,需要同样将端口号添加到安全组。
|
||||
:::
|
||||
|
||||
## 作为服务运行
|
||||
|
||||
1. 退出 halo 账户,登录到 root 账户
|
||||
|
||||
> 如果当前就是 root 账户,请略过此步骤。
|
||||
|
||||
```bash
|
||||
exit
|
||||
```
|
||||
|
||||
2. 下载 Halo 官方的 halo.service 模板
|
||||
```bash
|
||||
wget https://dl.halo.run/config/halo.service -O /etc/systemd/system/halo.service
|
||||
```
|
||||
|
||||
3. 修改 halo.service
|
||||
```bash
|
||||
vim /etc/systemd/system/halo.service
|
||||
```
|
||||
|
||||
4. 修改配置
|
||||
- **YOUR_JAR_PATH**:Halo 运行包的绝对路径,例如 `/home/halo/app/halo.jar`,注意:此路径不支持 `~` 符号。
|
||||
- **USER**:运行 Halo 的系统用户,如果有按照上方教程创建新的用户来运行 Halo,修改为你创建的用户名称即可。反之请删除 `User=USER`。
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Halo Service
|
||||
Documentation=https://halo.run
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=USER
|
||||
ExecStart=/usr/bin/java -server -Xms256m -Xmx256m -jar YOUR_JAR_PATH
|
||||
ExecStop=/bin/kill -s QUIT $MAINPID
|
||||
Restart=always
|
||||
StandOutput=syslog
|
||||
|
||||
StandError=inherit
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
:::tip
|
||||
请确保 `/usr/bin/java` 是正确无误的。建议将 `ExecStart` 中的命令复制出来运行一下,保证命令有效。
|
||||
:::
|
||||
|
||||
5. 重新加载 systemd
|
||||
```bash
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
6. 运行服务
|
||||
```bash
|
||||
systemctl start halo
|
||||
```
|
||||
|
||||
7. 在系统启动时启动服务
|
||||
```bash
|
||||
systemctl enable halo
|
||||
```
|
||||
|
||||
您可以查看服务日志检查启动状态
|
||||
```bash
|
||||
journalctl -n 20 -u halo
|
||||
```
|
||||
|
||||
## 反向代理
|
||||
|
||||
你可以在下面的反向代理软件中任选一项,我们假设你已经安装好了其中一项,并对其基本操作有一定了解。如果你对 Nginx 不熟悉,我们推荐使用 [OneinStack](/getting-started/install/other/oneinstack) 来管理 Nginx。
|
||||
|
||||
### Nginx
|
||||
|
||||
```nginx
|
||||
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;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
注意:Nginx 默认的 `client_max_body_size` 配置大小为 1m,可能会导致你在 Halo 后台上传文件被 Nginx 限制,所以此示例配置文件加上了 `client_max_body_size 1024m;` 这行配置。当然,1024m 可根据你的需要自行修改。
|
||||
|
||||
### Caddy 1.x
|
||||
|
||||
```
|
||||
https://www.yourdomain.com {
|
||||
gzip
|
||||
tls your@email.com
|
||||
proxy / localhost:8090 {
|
||||
transparent
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Caddy 2.x
|
||||
|
||||
```
|
||||
www.yourdomain.com
|
||||
|
||||
encode gzip
|
||||
|
||||
reverse_proxy 127.0.0.1:8090
|
||||
```
|
||||
|
||||
以上配置都可以在 https://github.com/halo-dev/halo-common 找到。
|
@@ -0,0 +1,149 @@
|
||||
---
|
||||
title: 与宝塔面板配合使用
|
||||
description: 与宝塔面板配合使用的指南
|
||||
---
|
||||
|
||||
## 声明
|
||||
|
||||
1. 本组织与宝塔面板官方无任何合作和利益关系。
|
||||
2. 您在使用期间如果有宝塔面板所带来的问题,均与我们无关。
|
||||
3. 开始之前,我们默认认为您已经安装好了宝塔面板,以及熟悉宝塔面板的使用。
|
||||
4. 建议使用宝塔面板最新版本,截止到撰写指南的时刻,宝塔面板的版本为 `7.4.7`。
|
||||
|
||||
## Halo 部署
|
||||
|
||||
参见 [在 Linux 环境部署](/getting-started/install/linux)
|
||||
|
||||
:::info
|
||||
`「作为服务运行」` 部分可以不进行操作,只需测试启动无误即可,后面将使用宝塔面板软件包中的 `Supervisor` 托管 Halo 进程。
|
||||
:::
|
||||
|
||||
## 宝塔面板所需软件包下载
|
||||
|
||||
需要在宝塔面板的软件商店安装的软件包有:
|
||||
|
||||
1. Nginx
|
||||
2. Supervisor
|
||||
|
||||
## 使用 Supervisor 托管 Halo 进程
|
||||
|
||||
打开 Supervisor 管理器的设置,点击 `添加守护进程` 按钮。
|
||||
|
||||
需要填写的表单信息如下:
|
||||
|
||||
- **名称**:随意
|
||||
- **启动用户**:如果您按照 [在 Linux 环境部署](/getting-started/install/linux) 创建了用于运行 Halo 的用户,则选择您创建的用户即可。否则选择默认的 root。
|
||||
- **运行目录**:运行包的存放目录,按照实际情况填写,需要保证你所选的目录包含运行包。
|
||||
- **启动命令**:`java -server -Xms256m -Xmx256m -jar halo.jar`
|
||||
|
||||
填写完成之后点击 `确定` 按钮即可。
|
||||
|
||||
## 添加站点并配置 Nginx
|
||||
|
||||
1. 点击左侧的 `网站` 菜单项,点击 `添加站点` 按钮。
|
||||
|
||||
需要填写的表单信息如下:
|
||||
|
||||
- **域名**:填写您已经解析到当前服务器公网 IP 的域名。
|
||||
- **PHP版本**:纯静态
|
||||
|
||||
填写完成之后点击 `提交` 按钮即可。
|
||||
|
||||
2. 设置 SSL
|
||||
|
||||
:::info
|
||||
在配置反向代理之前,我们推荐先设置好 SSL 证书。
|
||||
:::
|
||||
|
||||
- 可选择 `宝塔 SSL` 或者 `Let's Encrypt` 进行证书申请。
|
||||
- 需要开启右上角的 `强制 HTTPS`。
|
||||
|
||||
3. 修改配置文件
|
||||
|
||||
在根节点添加:
|
||||
|
||||
```nginx
|
||||
upstream halo {
|
||||
server 127.0.0.1:8090;
|
||||
}
|
||||
```
|
||||
|
||||
> 其中的 8090 为 Halo 的运行端口,请按需修改。
|
||||
|
||||
在 server 节点添加:
|
||||
|
||||
```nginx
|
||||
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;
|
||||
}
|
||||
```
|
||||
|
||||
修改 server 节点中的 `location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$` 节点:
|
||||
|
||||
```nginx
|
||||
location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$
|
||||
{
|
||||
proxy_pass http://halo;
|
||||
expires 30d;
|
||||
error_log /dev/null;
|
||||
access_log off;
|
||||
}
|
||||
```
|
||||
|
||||
修改 server 节点中的 `location ~ .*\.(js|css)?$` 节点:
|
||||
|
||||
```nginx
|
||||
location ~ .*\.(js|css)?$
|
||||
{
|
||||
proxy_pass http://halo;
|
||||
expires 12h;
|
||||
error_log /dev/null;
|
||||
access_log off;
|
||||
}
|
||||
```
|
||||
|
||||
完整配置文件示例(仅包含关键部分):
|
||||
|
||||
```nginx
|
||||
upstream halo {
|
||||
server 127.0.0.1:8090;
|
||||
}
|
||||
server
|
||||
{
|
||||
...
|
||||
|
||||
location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$
|
||||
{
|
||||
proxy_pass http://halo;
|
||||
expires 30d;
|
||||
error_log /dev/null;
|
||||
access_log off;
|
||||
}
|
||||
|
||||
location ~ .*\.(js|css)?$
|
||||
{
|
||||
proxy_pass http://halo;
|
||||
expires 12h;
|
||||
error_log /dev/null;
|
||||
access_log off;
|
||||
}
|
||||
|
||||
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;
|
||||
}
|
||||
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
随后点击保存即可。如果配置不生效,请重载 Nginx 或者 重启 Nginx。
|
||||
|
||||
最后,访问域名即可进行 Halo 的初始化。
|
@@ -0,0 +1,274 @@
|
||||
---
|
||||
title: 与 OneinStack 配合使用
|
||||
description: 使用 OneinStack 的 vhost 脚本创建 Halo 站点的 Nginx 配置文件
|
||||
---
|
||||
|
||||
## Halo 部署
|
||||
|
||||
参见 [在 Linux 环境部署](/getting-started/install/linux)
|
||||
|
||||
:::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
|
||||
upstream halo {
|
||||
server 127.0.0.1:8090;
|
||||
}
|
||||
```
|
||||
|
||||
4. 在 `server` 节点添加如下配置
|
||||
|
||||
```nginx
|
||||
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
|
||||
location ~ .*\.(gif|jpg|jpeg|png|bmp|swf|flv|mp4|ico)$ {
|
||||
proxy_pass http://halo;
|
||||
expires 30d;
|
||||
access_log off;
|
||||
}
|
||||
```
|
||||
|
||||
6. 修改 `location ~ .*\.(js|css)?$` 节点
|
||||
|
||||
```nginx
|
||||
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
|
||||
location ^~ /.well-known/acme-challenge/ {
|
||||
default_type "text/plain";
|
||||
allow all;
|
||||
root /data/wwwroot/demo.halo.run/;
|
||||
}
|
||||
```
|
||||
|
||||
至此,配置修改完毕,保存即可。最终你的配置文件可能如下面配置一样:
|
||||
|
||||
```nginx
|
||||
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
|
||||
```
|
||||
|
||||
如果输出如下提示则代表配置有效:
|
||||
|
||||
```
|
||||
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 配置:
|
||||
|
||||
```
|
||||
nginx -s reload
|
||||
```
|
||||
|
||||
至此,整个教程完毕,现在你可以访问域名检查是否已经配置成功。
|
@@ -0,0 +1,80 @@
|
||||
---
|
||||
title: 腾讯云 CloudBase
|
||||
description: 使用腾讯云 CloudBase 一键部署
|
||||
---
|
||||
|
||||
## 声明
|
||||
|
||||
1. 本组织与腾讯云官方无任何合作和利益关系。
|
||||
2. 您在使用期间如果有腾讯云所带来的问题,均与我们无关。
|
||||
3. 开始之前,我们默认认为您已经了解过 [腾讯云云开发](https://cloud.tencent.com/product/tcb)。
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. 系统使用内置的 H2 Database,暂不支持使用 MySQL。
|
||||
1. 工作目录保存在腾讯云提供的 CFS 上,在使用此方式创建应用的时候会要求创建 CFS。
|
||||
1. 目前使用该方式部署,不支持修改 [配置文件](/getting-started/config)。
|
||||
1. 费用相关请参考 https://cloud.tencent.com/document/product/876/18864
|
||||
|
||||
## 进入云开发页面
|
||||
|
||||
点击下方按钮即可进入到腾讯云云开发 CloudBase 创建应用界面,此按钮可在云开发页面自动选择 Halo 的配置模板。
|
||||
|
||||
[](https://console.cloud.tencent.com/tcb/env/index?action=CreateAndDeployCloudBaseProject&appUrl=https%3A%2F%2Fgithub.com%2Fhalo-dev%2Ftencent-cloudbase-halo&branch=master)
|
||||
|
||||
## 配置并部署
|
||||
|
||||
**填写环境名称**,这里建议把 `开启免费额度` 打开,然后点击下一步。
|
||||
|
||||

|
||||
|
||||
**应用配置**,需要注意:这里需要开通 CFS,用于存储 Halo 的工作目录。
|
||||
|
||||

|
||||
|
||||
**提交授权**,点击 `授权并开通`。
|
||||
|
||||

|
||||
|
||||
**创建环境中**,完成之后,点击 `环境` 下面的卡片,即可进入详细配置页面。
|
||||
|
||||

|
||||
|
||||
**构建应用中**,这里可能会等待较长时间。
|
||||
|
||||

|
||||
|
||||
**构建应用完成**,需要注意的是,构建完成之后可能还需要等待一小段时间才能正常访问,这个期间是在等待 Halo 应用启动完毕。点击 `访问` 按钮即可进入 Halo 初始化页面。
|
||||
|
||||

|
||||
|
||||
**Halo 初始化页面**
|
||||
|
||||

|
||||
|
||||
**CFS 管理页面**:[https://console.cloud.tencent.com/cfs/fs](https://console.cloud.tencent.com/cfs/fs)
|
||||
|
||||

|
||||
|
||||
## 更新 Halo
|
||||
|
||||
> 当 Halo 有新版本更新的时候,你可以采用下面的方式进行版本升级。
|
||||
|
||||
### 删除旧版本
|
||||
|
||||
前往 [云托管](https://console.cloud.tencent.com/tcb/service) 页面,点击服务名称进入版本列表,然后删除当前使用的版本。
|
||||
|
||||

|
||||
|
||||
### 重新部署
|
||||
|
||||
回到 [我的应用](https://console.cloud.tencent.com/tcb/apps/index) 页面,点击 `部署` 按钮并确定。
|
||||
|
||||

|
||||
|
||||
## 相关链接
|
||||
|
||||
- [Halo 配置文件仓库](https://github.com/halo-dev/tencent-cloudbase-halo)
|
||||
- [腾讯云 CloudBase](https://console.cloud.tencent.com/tcb/env/index)
|
||||
- [云开发使用指南](https://cloud.tencent.com/document/product/876)
|
||||
|
@@ -0,0 +1,13 @@
|
||||
---
|
||||
title: 三方指南
|
||||
---
|
||||
|
||||
:::tip
|
||||
此类指南或教程均来自第三方或者网友提供,我们不能一直保证其具有有效性,请参考的时候仔细甄别。另外,如果您有写类似的教程,也可以[联系我们](mailto:hi@halo.run)放在下方。
|
||||
:::
|
||||
|
||||
- [Halo 博客安装教程,一款优秀的 Java 开源博客系统](https://www.cnblogs.com/bronya0/p/14198512.html)
|
||||
- [如何用服务器优雅地搭建一个博客—Hello,Halo!](https://www.bilibili.com/video/BV1JN411Q7Na/)
|
||||
- [Halo+云服务器+Nginx反向代理实现个人博客搭建](https://yusart.xyz/archives/halo%E4%B8%AA%E4%BA%BA%E5%8D%9A%E5%AE%A2%E6%90%AD%E5%BB%BA)
|
||||
- [如何在 Windows 下搭建 Halo](https://ykanade.cn/archives/如何在windows下搭建halo)
|
||||
- [Halo 博客建站记录](https://catchersun.cn/archives/halo%E5%8D%9A%E5%AE%A2%E5%BB%BA%E7%AB%99%E8%AE%B0%E5%BD%95)
|
@@ -0,0 +1,72 @@
|
||||
---
|
||||
title: 在 Windows 服务器上部署
|
||||
---
|
||||
|
||||
:::info
|
||||
在继续操作之前,我们推荐您先阅读[《写在前面》](/getting-started/prepare),这可以快速帮助你了解 Halo。
|
||||
:::
|
||||
|
||||
# 系统要求
|
||||
目前运行 Halo 的最低依赖要求为 JRE 11,而 Java9 之后将不再提供 32 位系统的环境,因此请确保您的服务器属于 64 位 CPU。
|
||||
|
||||
# 依赖检查
|
||||
如下将介绍在 Windows 下安装 OpenJRE 11 的方式。如果您的服务器已经安装过 OpenJRE 11,则可以直接跳过本节。
|
||||
|
||||
1. 使用浏览器前往 https://developers.redhat.com/content-gateway/file/java-11-openjdk-jre-11.0.10.9-1.windows.redhat.x86_64.msi 下载 OpenJRE 11 的可执行程序。
|
||||
|
||||
2. 下载时会提示登录“红帽”,任意注册账号登录即可。登录完成之后会自动下载 JRE。
|
||||
|
||||
3. 双击 MSI 安装程序,安装 JRE 至服务器,注意到安装程序第三步时,勾选 `JAVA_HOME Variable`,其余直接 `next` 即可
|
||||
|
||||

|
||||
|
||||
4. 安装完成之后, 使用 <kbd>Win</kbd>+<kbd>R</kbd> 打开运行窗口并输入 `CMD` 后,回车打开 CMD 窗口。之后键入 `java -version`。显示如下所示内容即代表安装成功。
|
||||
```
|
||||
openjdk version "11.0.10" 2021-01-19 LTS
|
||||
OpenJDK Runtime Environment 18.9 (build 11.0.10+9-LTS)
|
||||
OpenJDK 64-Bit Server VM 18.9 (build 11.0.10+9-LTS, mixed mode)
|
||||
```
|
||||
|
||||

|
||||
|
||||
# 安装 Halo
|
||||
1. 下载运行包
|
||||
|
||||
使用浏览器前往 https://dl.halo.run/release/halo-1.4.6.jar 下载最新版本 Halo 运行包,**并保存至桌面**。修改 Jar 包名称为 `halo.jar`
|
||||
|
||||
:::info
|
||||
如果下载速度不理想,可以[在这里](/getting-started/downloads)选择其他下载地址。
|
||||
:::
|
||||
|
||||
2. 下载示例配置文件
|
||||
|
||||
使用浏览器前往 https://dl.halo.run/config/application-template.yaml 下载示例配置文件,**并保存至桌面**。修改示例配置文件名字为 `application.yaml`。
|
||||
|
||||
:::tip
|
||||
IE 浏览器下,配置文件可能会以文本的形式直接打开,因此推荐使用其他浏览器或下载器下载。
|
||||
:::
|
||||
|
||||
3. 使用记事本编辑配置文件,配置数据库或者端口等,如需配置请参考[参考配置](/getting-started/config)
|
||||
|
||||
4. 测试运行 Halo
|
||||
|
||||
使用 <kbd>Win</kbd>+<kbd>R</kbd> 打开运行窗口并输入 `CMD` 后,回车打开 CMD 窗口,并键入如下命令。
|
||||
```
|
||||
cd Desktop && java -jar halo.jar
|
||||
```
|
||||
|
||||
5. 如看到类似以下日志输出,则代表启动成功。
|
||||
```bash
|
||||
run.halo.app.listener.StartedListener : Halo started at http://127.0.0.1:8090
|
||||
run.halo.app.listener.StartedListener : Halo admin started at http://127.0.0.1:8090/admin
|
||||
run.halo.app.listener.StartedListener : Halo has started successfully!
|
||||
```
|
||||
浏览器打开 `http://ip:端口号` 即可看到安装引导界面。
|
||||
|
||||
:::info
|
||||
如测试启动正常,请继续看`作为服务运行`部分,第 4 ~ 5 步仅仅作为测试。当你关闭 CMD 窗口之后,服务会停止。你可使用 <kbd>CTRL</kbd>+<kbd>C</kbd> 停止运行测试进程。
|
||||
:::
|
||||
|
||||
:::tip
|
||||
如果需要配置域名访问,建议先配置好反向代理以及域名解析再进行初始化。如果通过 `http://ip:端口号` 的形式无法访问,请到服务器厂商后台将运行的端口号添加到安全组,如果服务器使用了 Linux 面板,请检查此 Linux 面板是否有还有安全组配置,需要同样将端口号添加到安全组。
|
||||
:::
|
107
versioned_docs/version-1.4.15/getting-started/prepare.md
Normal file
107
versioned_docs/version-1.4.15/getting-started/prepare.md
Normal file
@@ -0,0 +1,107 @@
|
||||
---
|
||||
title: 写在前面
|
||||
description: 在开始前,您需要了解的事项
|
||||
---
|
||||
|
||||
## 环境要求
|
||||
|
||||
这里将讲述运行 Halo 所要求的一些软硬件的配置,我们建议您在运行或者部署之前先浏览一遍此页面。
|
||||
|
||||
### 硬件配置
|
||||
|
||||
:::tip
|
||||
如果您要使用服务器进行部署 Halo,您需要注意的是,Halo 目前不支持市面上的云虚拟主机,请使用云服务器或者 VPS。
|
||||
:::
|
||||
|
||||
#### CPU
|
||||
|
||||
无特别要求。目前我们的 [Docker 镜像](https://hub.docker.com/r/halohub/halo) 也已经支持多平台。
|
||||
|
||||
#### 内存
|
||||
|
||||
为了获得更好的体验,我们建议至少配置 1G 的 RAM。
|
||||
|
||||
#### 磁盘
|
||||
|
||||
无特别要求,理论上如果不大量在服务器上传附件,Halo 对磁盘的容量要求并不是很高。但我们推荐最好使用 SSD 硬盘的服务器,能更快的运行 Halo。
|
||||
|
||||
#### 网络
|
||||
|
||||
Halo 目前必须在外网畅通的情况下使用,否则会导致页面异常。
|
||||
|
||||
### 软件环境
|
||||
|
||||
Halo 理论上可以运行在任何支持 Java 的平台。
|
||||
|
||||
#### JRE(Java Runtime Environment)
|
||||
|
||||
必须在运行环境安装好 JRE,这是运行 Halo 所要求的的最低软件环境要求。如果您使用 Docker 运行 Halo,可忽略此要求。
|
||||
|
||||
:::info
|
||||
从 1.4.3 起,版本要求为 11 以上的版本。1.4.3 以下需要 1.8 以上的版本。
|
||||
:::
|
||||
|
||||
#### MySQL(可选)
|
||||
|
||||
这并不是 Halo 必须依赖的,Halo 默认使用自带的 `H2 Database`,无需单独安装。如果 `H2 Database` 不能满足你的要求,您需要在系统内安装并运行好 MySQL。
|
||||
|
||||
具体要求:
|
||||
|
||||
1. 版本:5.7 +
|
||||
2. 字符集(Character Set):`utf8mb4`
|
||||
3. 排序规则(Collate):`utf8mb4_bin`
|
||||
4. 存储引擎:`InnoDB`
|
||||
|
||||
综上,建议创建数据库采用下面的命令:
|
||||
|
||||
```bash
|
||||
create database halodb character set utf8mb4 collate utf8mb4_bin;
|
||||
```
|
||||
|
||||
#### Web 服务器(可选)
|
||||
|
||||
如果您部署在生产环境,那么你很可能需要进行域名绑定,这时候我们推荐使用诸如 [Nginx](http://nginx.org/)、[Caddy](https://caddyserver.com/) 之类的 Web 服务器进行反向代理。
|
||||
|
||||
#### Wget(可选)
|
||||
|
||||
后续的文档中,我们会使用 wget 为例,用于下载所需要的文件,所以请确保服务器已经安装好了这个软件包。当然,下载文件不限制工具,如果你对其他工具熟悉,可以忽略。
|
||||
|
||||
#### Vim(可选)
|
||||
|
||||
后续的文档中,我们会使用 vim 为例,用于修改一些必要的配置文件,所以同样请确保服务器已经安装了这个软件包。当前,修改文档也不限制工具,如果你对其他编辑软件熟悉,也可以忽略。
|
||||
|
||||
### 服务器推荐
|
||||
|
||||
如果您当前还没有购买服务器,可以考虑通过以下链接购买,这会为我们带来一部分收益。此外,如果您已经通过下面的链接购买了服务器,可以 [联系我们](mailto:hi@halo.run) 帮你免费部署 Halo。
|
||||
|
||||
- 阿里云:[https://promotion.aliyun.com/ntms/yunparter/invite.html?userCode=3t6v5x0v](https://promotion.aliyun.com/ntms/yunparter/invite.html?userCode=3t6v5x0v)
|
||||
- 阿里云双十一新用户:[https://www.aliyun.com/minisite/goods?taskPkg=1111ydsrwb&pkgSid=12305&userCode=3t6v5x0v](https://www.aliyun.com/minisite/goods?taskPkg=1111ydsrwb&pkgSid=12305&userCode=3t6v5x0v)
|
||||
- 腾讯云:[https://curl.qcloud.com/ewTUJQec](https://curl.qcloud.com/ewTUJQec)
|
||||
- 腾讯云双十一新用户:[https://cloud.tencent.com/act/pre-2021double11?spread_hash_key=f7cce5fd94766a553072b1642977ea7a](https://cloud.tencent.com/act/pre-2021double11?spread_hash_key=f7cce5fd94766a553072b1642977ea7a)
|
||||
- Vultr:[https://www.vultr.com/?ref=7278289](https://www.vultr.com/?ref=7278289)
|
||||
|
||||
## 浏览器支持
|
||||
|
||||
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 构建所产生的 Jar 包,后缀为 `.jar`。可能与其他网站应用有所区别的是,Halo 仅仅只有这一个文件。而且所有数据统一保存在下面所说的 `工作目录`。
|
||||
|
||||
### 工作目录
|
||||
指 Halo 所依赖的工作目录,在 Halo 运行的时候会在系统当前用户目录下产生一个 `.halo` 的文件夹,绝对路径为 `~/.halo`。由于这个工作目录是固定的,所以上面所说的 `运行包`不限制所存放的位置,里面通常包含下列目录或文件:
|
||||
|
||||
1. `db`:存放 H2 Database 的物理文件,如果您使用 MySQL 数据库,那么不会存在这个目录。
|
||||
2. `templates/themes`:里面包含用户所下载的主题。
|
||||
3. `static`:相当于网站的根目录。
|
||||
4. `logs`:运行日志目录。
|
||||
4. `upload`:附件目录。
|
||||
5. `application.yaml`:配置文件。
|
109
versioned_docs/version-1.4.15/getting-started/upgrade.md
Normal file
109
versioned_docs/version-1.4.15/getting-started/upgrade.md
Normal file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: 版本升级
|
||||
description: 版本升级指南
|
||||
---
|
||||
|
||||
选择你部署的平台:
|
||||
|
||||
## Linux <i class="mdi mdi-ubuntu"></i>
|
||||
|
||||
> 我们假设您存放运行包的路径为 `~/app`,运行包的文件名为 `halo.jar`,如有不同,下列命令请按需修改。
|
||||
|
||||
---
|
||||
|
||||
:::tip
|
||||
从 1.4.3 开始,Halo 最低支持的 JRE 版本为 11,在升级前,请务必先升级 JRE。
|
||||
:::
|
||||
|
||||
:::info
|
||||
如果当前您不方便升级到 11,我们推荐使用 [Docker](/getting-started/install/docker) 运行新版 Halo,从 Jar 包的方式迁移到 Docker 运行非常方便,按照[指南](/getting-started/install/docker)在创建容器的时候将容器内的 `/root/.halo` 目录映射到当前 Halo 的工作目录即可。
|
||||
:::
|
||||
|
||||
1. 停止正在运行的服务
|
||||
|
||||
```bash
|
||||
service halo stop
|
||||
```
|
||||
|
||||
2. 备份数据以及旧的运行包(重要)
|
||||
|
||||
```bash
|
||||
cp -r ~/.halo ~/.halo.1.4.14
|
||||
```
|
||||
|
||||
```bash
|
||||
cd ~/app && mv halo.jar halo.jar.1.4.14
|
||||
```
|
||||
|
||||
3. 下载最新版本的运行包
|
||||
|
||||
```bash
|
||||
cd ~/app && wget https://dl.halo.run/release/halo-1.4.15.jar -O halo.jar
|
||||
```
|
||||
|
||||
:::info
|
||||
如果下载速度不理想,可以[在这里](/getting-started/downloads)选择其他下载地址。
|
||||
:::
|
||||
|
||||
4. 启动测试
|
||||
|
||||
```bash
|
||||
java -jar halo.jar
|
||||
```
|
||||
|
||||
:::info
|
||||
如测试启动正常,请继续下一步。使用 <kbd>CTRL</kbd>+<kbd>C</kbd> 停止运行测试进程。
|
||||
:::
|
||||
|
||||
5. 重启服务
|
||||
|
||||
```
|
||||
service halo start
|
||||
```
|
||||
|
||||
|
||||
## Docker <i class="mdi mdi-docker"></i>
|
||||
|
||||
> 我们假设您的容器是按照 [使用 Docker 部署 Halo](/getting-started/install/docker) 中的命令构建的。如有不同,请根据实际情况修改。
|
||||
|
||||
1. 停止并删除当前运行中的容器
|
||||
|
||||
```bash
|
||||
docker stop halo
|
||||
```
|
||||
|
||||
```bash
|
||||
docker rm -f halo
|
||||
```
|
||||
|
||||
:::info
|
||||
你的容器名称不一定为 `halo`,在执行前可以先执行 `docker ps -a` 查看一下。
|
||||
:::
|
||||
|
||||
2. 备份数据(重要)
|
||||
|
||||
```bash
|
||||
cp -r ~/.halo ~/.halo.1.4.14
|
||||
```
|
||||
|
||||
3. 拉取最新的 Halo 镜像
|
||||
|
||||
```bash
|
||||
docker pull halohub/halo:1.4.15
|
||||
```
|
||||
|
||||
:::info
|
||||
查看最新版本镜像:https://hub.docker.com/r/halohub/halo ,我们推荐使用具体版本号的镜像,但也提供了 `latest` 标签的镜像,它始终是最新的。
|
||||
:::
|
||||
|
||||
4. 创建容器
|
||||
|
||||
```bash
|
||||
docker run -it -d --name halo -p 8090:8090 -v ~/.halo:/root/.halo --restart=unless-stopped halohub/halo:1.4.15
|
||||
```
|
||||
- **-it:** 开启输入功能并连接伪终端
|
||||
- **-d:** 后台运行容器
|
||||
- **--name:** 为容器指定一个名称
|
||||
- **-p:** 端口映射,格式为 `主机(宿主)端口:容器端口` ,可在 `application.yaml` 配置。
|
||||
- **-v:** 工作目录映射。形式为:-v 宿主机路径:/root/.halo,后者不能修改。
|
||||
- **--restart:** 建议设置为 `unless-stopped`,在 Docker 启动的时候自动启动 Halo 容器。
|
89
versioned_docs/version-1.4.15/intro.md
Normal file
89
versioned_docs/version-1.4.15/intro.md
Normal file
@@ -0,0 +1,89 @@
|
||||
---
|
||||
id: intro
|
||||
sidebar_label: 简介
|
||||
title: ''
|
||||
sidebar_position: 1
|
||||
hide_title: true
|
||||
slug: /
|
||||
---
|
||||
|
||||
<p align="center">
|
||||
<a href="https://halo.run" target="_blank" rel="noopener noreferrer">
|
||||
<img width="100" src="https://halo.run/logo" alt="Halo logo" />
|
||||
</a>
|
||||
</p>
|
||||
|
||||
> Halo 是一款现代化的个人独立博客系统,给习惯写博客的同学多一个选择。
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/halo-dev/halo/releases"><img alt="GitHub release" src="https://img.shields.io/github/release/halo-dev/halo.svg?style=flat-square" /></a>
|
||||
<a href="https://github.com/halo-dev/halo/releases"><img alt="GitHub All Releases" src="https://img.shields.io/github/downloads/halo-dev/halo/total.svg?style=flat-square" /></a>
|
||||
<a href="https://hub.docker.com/r/halohub/halo"><img alt="Docker pulls" src="https://img.shields.io/docker/pulls/halohub/halo?style=flat-square" /></a>
|
||||
<a href="https://github.com/halo-dev/halo/commits"><img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/halo-dev/halo.svg?style=flat-square" /></a>
|
||||
<a href="https://github.com/halo-dev/halo/actions"><img alt="GitHub Workflow Status" src="https://img.shields.io/github/workflow/status/halo-dev/halo/Halo%20CI?style=flat-square" /></a>
|
||||
</p>
|
||||
|
||||
------------------------------
|
||||
|
||||
## 简介
|
||||
|
||||
**Halo** `[ˈheɪloʊ]`,一个优秀的开源博客发布应用,值得一试。
|
||||
|
||||
[官网](https://halo.run) | [文档](https://docs.halo.run) | [社区](https://bbs.halo.run) | [Gitee](https://gitee.com/halo-dev) | [Telegram 频道](https://t.me/halo_dev)
|
||||
|
||||
## 快速开始
|
||||
|
||||
### Fat Jar
|
||||
|
||||
下载最新的 Halo 运行包:
|
||||
|
||||
```bash
|
||||
curl -L https://github.com/halo-dev/halo/releases/download/v1.4.15/halo-1.4.15.jar --output halo.jar
|
||||
```
|
||||
|
||||
其他地址:<https://docs.halo.run/getting-started/downloads>
|
||||
|
||||
```bash
|
||||
java -jar halo.jar
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
docker run -it -d --name halo -p 8090:8090 -v ~/.halo:/root/.halo --restart=always halohub/halo
|
||||
```
|
||||
|
||||
详细部署文档请查阅:<https://docs.halo.run/getting-started/install/linux>
|
||||
|
||||
## 生态
|
||||
|
||||
| 项目 | 状态 | 描述 |
|
||||
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
|
||||
| [halo-admin](https://github.com/halo-dev/halo-admin) | <a href="https://www.npmjs.com/package/halo-admin"><img alt="npm release" src="https://img.shields.io/npm/v/halo-admin?style=flat-square"/></a> | Web 管理端 UI,已内置在主应用 |
|
||||
| [halo-comment](https://github.com/halo-dev/halo-comment) | <a href="https://www.npmjs.com/package/halo-comment"><img alt="npm release" src="https://img.shields.io/npm/v/halo-comment?style=flat-square"/></a> | 独立评论组件,可以非常方便的集成到主题中 |
|
||||
| [halo-comment-normal](https://github.com/halo-dev/halo-comment-normal) | <a href="https://www.npmjs.com/package/halo-comment-normal"><img alt="npm release" src="https://img.shields.io/npm/v/halo-comment-normal?style=flat-square"/></a> | 另外一款评论组件 |
|
||||
| [halo-mobile-app](https://github.com/halo-dev/halo-mobile-app) | 已停止维护 | 移动端管理 APP |
|
||||
| [tencent-cloudbase-halo](https://github.com/halo-dev/tencent-cloudbase-halo) | 无 | 腾讯云 CloudBase 一键部署配置 |
|
||||
| [halo-theme-*](https://github.com/topics/halo-theme) | 无 | GitHub 上开源的 Halo 主题集合 |
|
||||
|
||||
## 许可证
|
||||
|
||||
[](https://github.com/halo-dev/halo/blob/master/LICENSE)
|
||||
|
||||
Halo 使用 GPL-v3.0 协议开源,请遵守开源协议。
|
||||
|
||||
## 贡献
|
||||
|
||||
参考 [CONTRIBUTING](https://github.com/halo-dev/halo/blob/master/CONTRIBUTING.md)。
|
||||
|
||||
<a href="https://github.com/halo-dev/halo/graphs/contributors"><img src="https://opencollective.com/halo/contributors.svg?width=890&button=false" /></a>
|
||||
|
||||
## 状态
|
||||
|
||||

|
||||
|
||||
## 赞助我们
|
||||
|
||||
> 如果 Halo 对您有帮助,不妨赞助我们
|
||||
|
||||
<https://docs.halo.run/contribution/sponsor>
|
38
versioned_docs/version-1.4.15/user-guide/backup-migration.md
Normal file
38
versioned_docs/version-1.4.15/user-guide/backup-migration.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: 备份迁移
|
||||
description: 关于备份和迁移的最佳实践
|
||||
---
|
||||
|
||||
:::info
|
||||
在开始之前,我们推荐你先阅读 [《写在前面》](/getting-started/prepare) 的名词解释部分。
|
||||
:::
|
||||
|
||||
## 备份
|
||||
|
||||
### 数据备份
|
||||
|
||||
目前 Halo 在后台的小工具中提供了数据导出的功能,此功能的作用为导出数据库的所有数据,格式为 `JSON`。通常可以作为切换数据库类型的时候使用。需要注意的是,此备份仅仅为备份数据,不包含其他诸如主题、附件等资料。如下图:
|
||||
|
||||

|
||||
|
||||
点击右下角的备份按钮即可导出所有数据,之后点击备份文件的标题即可下载。
|
||||
|
||||
### 整站备份
|
||||
|
||||
通过 [《写在前面》](/getting-started/prepare) 的名词解释部分我们可以知道,Halo 的所有数据都是存放在当前用户目录的工作目录(.halo)下的(使用 MySQL 数据库除外,你还需要导出 MySQL 数据)。**所以我们备份整站的数据仅需备份这个目录即可**,不管你使用何种方式。不过,为了操作方便,我们也在后台的小工具中提供了备份整站数据的功能,和上面所说的数据备份一致,点击备份按钮即可打包工作目录文件夹。如下图:
|
||||
|
||||

|
||||
|
||||
## 迁移
|
||||
|
||||
### 导入数据
|
||||
|
||||
此功能为导入上面所说的数据备份产生的数据文件(JSON 格式),并非整站备份的工作目录文件。需要注意的是,此功能仅在站点初始化的时候支持。如下图:
|
||||
|
||||

|
||||
|
||||
上传文件之后,点击导入即可。
|
||||
|
||||
### 整站迁移
|
||||
|
||||
此操作通常用于迁移服务器,基于上面 **整站备份** 所说,Halo 的所有数据都是存放于当前用户目录的工作目录(.halo)下的。当然,这仅限于使用 **H2 Database** 的情况下,如果你使用的 MySQL,那么还需要手动导出 MySQL 数据。所以,我们迁移服务器仅仅需要需要将工作目录的备份文件上传到新服务器的用户目录下解压,然后按照 [《安装指南》](/getting-started/install/linux) 重新安装即可。MySQL 用户还需要做的就是手动导出 MySQL 数据,并在新服务器上导入。
|
173
versioned_docs/version-1.4.15/user-guide/config.md
Normal file
173
versioned_docs/version-1.4.15/user-guide/config.md
Normal file
@@ -0,0 +1,173 @@
|
||||
---
|
||||
title: 功能配置
|
||||
description: 系统功能的相关配置说明
|
||||
---
|
||||
|
||||
## 修改博客地址
|
||||
|
||||
很多人在部署完成之后都会惊奇的发现,博客前台居然没有样式?究其原因就是无法获取到静态资源,那么为什么获取不到呢?那就是你的博客地址没有设置正确。
|
||||
|
||||
第一步:
|
||||
|
||||
登录到后台之后,进入 博客设置 -> 常规设置。
|
||||
|
||||
第二步:
|
||||
|
||||
修改你的博客地址:
|
||||
|
||||
- 如果你没有进行域名解析或者没有配置反向代理,那么博客地址一般为 `http://ip:端口`。
|
||||
|
||||
- 如果你进行了域名解析且配置了反向代理,但是没有配置 SSL 证书,那么博客地址一般为 `http://域名`。
|
||||
|
||||
- 如果你进行了域名解析、配置了反向代理、也配置了 SSL 证书,那么博客地址一般为 `https://域名`。
|
||||
|
||||
说了这么多,就是希望你别把 `http://` 或者 `https://` 搞混了。
|
||||
|
||||
另外,需要注意的是,地址尾部不需要 `/`。
|
||||
|
||||
## 注册 Gravatar
|
||||
|
||||
很多人反映评论中自己的头像不显示,其实评论部分调用的头像并不是在个人资料中设置的那个,而是 `Gravatar`。所以这一点怪我,从 Halo 发布至今我都没有说明这个事情。
|
||||
|
||||
至于什么是 `Gravatar`,引用 `Gravatar` 官方的说明:`全球公认的头像`。这可不是在吹牛,因为只要接入了 Gravatar 的网站,你在网站上使用在 Gravatar 注册的邮箱之后,都会显示你设置的头像,而不需要额外设置。比较出名的网站有 `Github`,`Gitlab`,`V2ex` 等。所以点击 https://cn.gravatar.com/ 注册一个吧。
|
||||
|
||||
## 设置用户头像/Logo/Favicon
|
||||
|
||||
### 头像
|
||||
|
||||
第一步:
|
||||
|
||||
登录到后台之后,进入 用户 -> 个人资料。
|
||||
|
||||
第二步:
|
||||
|
||||
点击左侧头像即可选择本地附件中的图片。另外,也支持设置为 `Gravatar` 头像。点击 `使用 Gravatar` 即可。当然,前提是你注册了 `Gravatar` 才行。
|
||||
|
||||
### Logo/Favicon
|
||||
|
||||
第一步:
|
||||
|
||||
登录到后台之后,进入 系统 -> 博客设置。
|
||||
|
||||
第二步:
|
||||
|
||||
在常规设置中找到 Logo/Favicon 输入框,点击输入框后面的按钮即可调用附件库选择图片。
|
||||
|
||||
## SEO 设置
|
||||
|
||||
先说说程序本身对 SEO 做的优化:
|
||||
|
||||
- 支持 sitemap 站点地图:可访问 /sitemap.xml 或 /sitemap.html
|
||||
- 全站绝对路径
|
||||
- 页面静态化
|
||||
- 支持伪静态(1.3.0+)
|
||||
|
||||
需要自己设置的有:
|
||||
|
||||
第一步:
|
||||
|
||||
登录到后台之后,进入 系统 -> 博客设置 -> SEO 设置。
|
||||
|
||||
第二步:
|
||||
|
||||
填写你需要的一些关键词和博客描述,这部分可能需要你了解一定的 SEO 优化技巧。
|
||||
|
||||
> 另外,文章和自定义页面都可以自行设置关键词和描述(文章设置的高级设置中)。当然,你也可以不设置,系统为自动取你设置的文章标签为关键词,描述会自动取文章的部分内容。
|
||||
|
||||
Q&A
|
||||
|
||||
Q:我刚发布的文章,为啥百度搜索不到呢?
|
||||
|
||||
A:这是一件非常正常的事情,建议注册百度的站长工具,手动或者自动提交链接。
|
||||
|
||||
## SMTP 服务
|
||||
|
||||
SMTP 服务,简称发信服务,顾名思义就是用来发邮件的。那么,为什么要设置这个呢?有两个用途:
|
||||
|
||||
1. 评论通知,收到评论之后发信通知博主,评论者被回复之后发信通知被评论者。
|
||||
|
||||
2. 找回密码。
|
||||
|
||||
第一步:
|
||||
|
||||
登录到后台之后,进入 系统 -> 博客设置 -> SMTP 设置。
|
||||
|
||||
第二步:
|
||||
|
||||
勾选 `是否启用`,并配置相关信息:
|
||||
|
||||
1. SMTP 地址,到邮箱服务商查询。举两个例子:QQ 邮箱(smtp.qq.com),163 邮箱(smtp.163.com)
|
||||
|
||||
2. 发送协议:一般不修改,具体可到邮箱服务商查询。
|
||||
|
||||
3. SSL 端口:一般不修改,具体可到邮箱服务商查询。
|
||||
|
||||
4. 邮箱账号:你的账号。
|
||||
|
||||
5. 邮箱密码:你的密码。
|
||||
|
||||
6. 发件人:随意。
|
||||
|
||||
第三步:
|
||||
|
||||
点击发送测试,填上你可以接收到的邮箱,并填写测试内容,最后点击发送。不出意外就可以发送成功,失败了就检查下配置吧。
|
||||
|
||||
Q&A:
|
||||
|
||||
Q:发送失败
|
||||
|
||||
A:先检查配置是否有误,如不知道哪里错误,请查看日志。点击左上角 `Halo Dashboard`即可进入开发者选项,点击 `实时日志` 即可看到最近的日志。
|
||||
|
||||
Q:日志说我授权出错,但是我密码明明是对的啊!
|
||||
|
||||
A:部分邮箱所谓的密码并不是你的登陆密码,需要去邮箱服务商生成 `授权码`。这个才是你需要填写的。
|
||||
|
||||
## 设置统计代码
|
||||
|
||||
第一步:
|
||||
|
||||
登录到后台之后,进入 系统 -> 博客设置 -> 其他设置。
|
||||
|
||||
第二步:
|
||||
|
||||
将 `网站统计平台` 提供给你的一串代码填写到 `统计代码` 即可。
|
||||
|
||||
Q&A:
|
||||
|
||||
Q:什么是网站统计平台?
|
||||
|
||||
A:诸如百度统计,CNZZ,Google Analytics。可以非常详细的统计你网站的访问情况。
|
||||
|
||||
## 找一个合适自己的主题
|
||||
|
||||
当你搭建好博客之后,如果你不喜欢默认的主题,那么你可以去 [https://halo.run/themes/](https://halo.run/themes/) 选择你喜欢的主题。在这里主要讲一些注意事项。
|
||||
|
||||
### 如何安装?
|
||||
|
||||
登录到后台之后,进入 外观 -> 主题,在后下角有一个按钮,点击之后选择 `安装主题`。系统提供的两种安装方式。
|
||||
|
||||
1. 第一种,远程拉取。你只需要把主题的 Github 地址复制进去点击下载即可。
|
||||
2. 第二种,本地上传,你需要将主题安装包(releases)下载到本地,然后选择 `本地上传` 点击选择你下载好的主题即可。
|
||||
|
||||
> 一般情况下,推荐第二种,第一种一般安装的为开发版本,建议谨慎使用。
|
||||
|
||||
### 设置主题
|
||||
|
||||
> 可能有一部分人不太清楚,一般情况下,每个主题都是有单独的设置选项的。
|
||||
|
||||
点击主题下方的设置按钮即可进入主题设置。另外主题设置还有一种预览模式,可以实时查看主题设置变更后的效果。当你设置当前激活主题的时候,在页面右下角有一个 `预览模式` 的按钮,点击即可进入预览模式。
|
||||
|
||||
## 设置备案信息
|
||||
由于后台博客设置并没有提供设置备案信息的选项,所以有很多人不知道该怎么添加备案信息,这里简单说明一下。
|
||||
|
||||
|
||||
第一步:
|
||||
|
||||
登录到后台之后,进入 系统 -> 博客设置 -> 常规设置。
|
||||
|
||||
这时候你应该可以看到一个`页脚信息`的选项,而且有提示 `支持 HTML 格式的文本`。所以我们把备案信息放在这里即可。
|
||||
|
||||
|
||||
第二步:
|
||||
|
||||
将整理好的备案信息填写到页脚信息即可,如果没记错的话,公安联网备案是有提供`网站公安机关备案号`和`备案编号HTML代码`的。
|
6
versioned_docs/version-1.4.15/user-guide/faq.md
Normal file
6
versioned_docs/version-1.4.15/user-guide/faq.md
Normal file
@@ -0,0 +1,6 @@
|
||||
---
|
||||
title: 常见问题
|
||||
---
|
||||
|
||||
# Header
|
||||
Your content here
|
205
versioned_docs/version-1.4.15/user-guide/markdown.md
Normal file
205
versioned_docs/version-1.4.15/user-guide/markdown.md
Normal file
@@ -0,0 +1,205 @@
|
||||
---
|
||||
title: Markdown 语法
|
||||
description: Halo 编辑器中所支持的 Markdown 语法说明
|
||||
---
|
||||
|
||||
## 基础语法
|
||||
|
||||
Halo 使用的 `Markdown` 解析器为 [flexmark-java](https://github.com/vsch/flexmark-java),基于 [CommonMark (spec 0.28)](https://spec.commonmark.org/0.28/) 标准开发,语法参考:[https://spec.commonmark.org/0.28/](https://spec.commonmark.org/0.28/)。
|
||||
|
||||
## 代码块
|
||||
|
||||
```language
|
||||
代码块
|
||||
```
|
||||
|
||||
其中,language 为必填,如果不填写,很可能主题的代码高亮插件无法识别代码的语言,导致样式异常。举几个例子:
|
||||
|
||||
```java
|
||||
public static void main(String[] args){
|
||||
System.out.println("Hello World!");
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
console.log("Hello World!")
|
||||
```
|
||||
|
||||
## TOC
|
||||
|
||||
在文章的最前面加上 `[TOC]` 即可。
|
||||
|
||||
## 自动链接
|
||||
|
||||
支持自动将一个链接解析为可点击的格式,如下:
|
||||
|
||||
````markdown
|
||||
https://halo.run
|
||||
````
|
||||
|
||||
将被解析为:
|
||||
|
||||
```html
|
||||
<a href="https://halo.run">https://halo.run</a>
|
||||
```
|
||||
|
||||
## Emoji
|
||||
|
||||
支持将 Emoji 的文字形式转化为图片形式,如下:
|
||||
|
||||
```markdown
|
||||
:100:
|
||||
```
|
||||
|
||||
将被解析为:
|
||||
|
||||
```html
|
||||
💯
|
||||
```
|
||||
|
||||
更多 Emoji 表情可访问:[https://emoji.svend.cc](https://emoji.svend.cc)
|
||||
|
||||
## 数学公式
|
||||
|
||||
行内公式:
|
||||
|
||||
```markdown
|
||||
$a \ne 0$
|
||||
```
|
||||
|
||||
段落公式:
|
||||
|
||||
```markdown
|
||||
$$
|
||||
x = {-b \pm \sqrt{b^2-4ac} \over 2a}.
|
||||
$$
|
||||
```
|
||||
|
||||
> 需要注意的是,并不是每一款主题都支持显示数学公式,你可以先到你使用的主题设置中查看是否支持,如不支持,请看下面的解决方案。
|
||||
|
||||
首先,登陆到后台,进入 `系统 -> 博客设置 -> 其他设置`。将下面的代码复制到 `自定义内容页面 head`。
|
||||
|
||||
```html
|
||||
<script src="//cdn.jsdelivr.net/npm/mathjax@2.7.5/unpacked/MathJax.js?config=TeX-MML-AM_CHTML" defer></script>
|
||||
<script>
|
||||
document.addEventListener('DOMContentLoaded', function () {
|
||||
MathJax.Hub.Config({
|
||||
'HTML-CSS': {
|
||||
matchFontHeight: false
|
||||
},
|
||||
SVG: {
|
||||
matchFontHeight: false
|
||||
},
|
||||
CommonHTML: {
|
||||
matchFontHeight: false
|
||||
},
|
||||
tex2jax: {
|
||||
inlineMath: [
|
||||
['$','$'],
|
||||
['\\(','\\)']
|
||||
],
|
||||
displayMath: [["$$", "$$"], ["\\[", "\\]"]]
|
||||
}
|
||||
});
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
## 图表
|
||||
|
||||
饼图:
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
pie title NETFLIX
|
||||
"Time spent looking for movie" : 90
|
||||
"Time spent watching it" : 10
|
||||
```
|
||||
````
|
||||
|
||||
更多用法查看:[https://mermaidjs.github.io/#/](https://mermaidjs.github.io/#/)
|
||||
|
||||
> 需要注意的是,并不是每一款主题都支持显示图表,你可以先到你使用的主题设置中查看是否支持,如不支持,请看下面的解决方案。
|
||||
|
||||
首先,登陆到后台,进入 `系统 -> 博客设置 -> 其他设置`。将下面的代码复制到 `自定义内容页面 head`。
|
||||
|
||||
```html
|
||||
<script src="https://cdn.jsdelivr.net/npm/mermaid@8.4.4/dist/mermaid.min.js"></script>
|
||||
```
|
||||
|
||||
## 短连接
|
||||
|
||||
:::tip
|
||||
这属于实验性特性,也许我们将在未来的版本移除这个特性。
|
||||
:::
|
||||
|
||||
Halo 内置一些短连接以更好地支持一些 HTML 语法,但是编辑器目前并不能解析,只能发布之后才可以看到效果,如下:
|
||||
|
||||
### 网易云音乐
|
||||
|
||||
#### 语法
|
||||
|
||||
```markdown
|
||||
[music:id]
|
||||
```
|
||||
|
||||
#### 示例
|
||||
|
||||
```markdown
|
||||
[music:32507038]
|
||||
```
|
||||
|
||||
#### 解析结果
|
||||
|
||||
```html
|
||||
<iframe frameborder="no" border="0" marginwidth="0" marginheight="0" width=330 height=86 src="//music.163.com/outchain/player?type=2&id=32507038&auto=1&height=66"></iframe>
|
||||
```
|
||||
|
||||
### 哔哩哔哩动画
|
||||
|
||||
#### 语法
|
||||
|
||||
```markdown
|
||||
[bilibili:aid,width,height]
|
||||
```
|
||||
|
||||
#### 示例
|
||||
|
||||
```markdown
|
||||
[bilibili:65898131,256,256]
|
||||
```
|
||||
|
||||
#### 解析结果
|
||||
|
||||
```html
|
||||
<iframe height="256" width="256" src="//player.bilibili.com/player.html?aid=65898131" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>
|
||||
```
|
||||
|
||||
## 脚注
|
||||
|
||||
#### 语法
|
||||
|
||||
```markdown
|
||||
[^脚注名]
|
||||
[^脚注名]: 脚注内容
|
||||
```
|
||||
|
||||
#### 示例
|
||||
|
||||
```markdown
|
||||
驿外[^1]断桥边,寂寞开无主。已是黄昏独自愁,更着风和雨
|
||||
[^1]: 驿(yì)外:指荒僻、冷清之地。驿,驿站。
|
||||
```
|
||||
|
||||
#### 解析结果
|
||||
|
||||
```html
|
||||
<p>驿外<sup class="footnote-ref"><a href="#fn1" id="fnref1">[1]</a></sup>断桥边,寂寞开无主。已是黄昏独自愁,更着风和雨</p>
|
||||
<hr class="footnotes-sep">
|
||||
<section class="footnotes">
|
||||
<ol class="footnotes-list">
|
||||
<li id="fn1" class="footnote-item"><p>驿(yì)外:指荒僻、冷清之地。驿,驿站。 <a href="#fnref1" class="footnote-backref">↩︎</a></p>
|
||||
</li>
|
||||
</ol>
|
||||
</section>
|
||||
```
|
89
versioned_sidebars/version-1.4.15-sidebars.json
Normal file
89
versioned_sidebars/version-1.4.15-sidebars.json
Normal file
@@ -0,0 +1,89 @@
|
||||
{
|
||||
"tutorialSidebar": [
|
||||
"intro",
|
||||
{
|
||||
"type": "category",
|
||||
"label": "入门",
|
||||
"collapsed": false,
|
||||
"items": [
|
||||
"getting-started/prepare",
|
||||
{
|
||||
"type": "category",
|
||||
"label": "安装指南",
|
||||
"items": [
|
||||
"getting-started/install/linux",
|
||||
"getting-started/install/docker",
|
||||
{
|
||||
"type": "category",
|
||||
"label": "其他指南",
|
||||
"items": [
|
||||
"getting-started/install/other/bt-panel",
|
||||
"getting-started/install/other/oneinstack",
|
||||
"getting-started/install/other/tencent-cloudbase",
|
||||
{
|
||||
"type": "link",
|
||||
"label": "腾讯云开发者实验室",
|
||||
"href": "https://cloud.tencent.com/developer/labs/lab/10523"
|
||||
}
|
||||
]
|
||||
},
|
||||
"getting-started/install/third-party"
|
||||
]
|
||||
},
|
||||
"getting-started/config",
|
||||
"getting-started/upgrade",
|
||||
"getting-started/downloads"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
"label": "用户指南",
|
||||
"items": [
|
||||
"user-guide/backup-migration",
|
||||
"user-guide/markdown"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
"label": "开发者指南",
|
||||
"items": [
|
||||
{
|
||||
"type": "category",
|
||||
"label": "系统开发",
|
||||
"items": [
|
||||
"developer-guide/core/structure",
|
||||
"developer-guide/core/prepare",
|
||||
"developer-guide/core/code-style"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
"label": "主题开发",
|
||||
"items": [
|
||||
"developer-guide/theme/prepare",
|
||||
"developer-guide/theme/config-files",
|
||||
"developer-guide/theme/global-variable",
|
||||
"developer-guide/theme/public-template-tag",
|
||||
"developer-guide/theme/page-variable",
|
||||
"developer-guide/theme/template-tag"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "link",
|
||||
"label": "REST API",
|
||||
"href": "https://api.halo.run"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
"label": "参与贡献",
|
||||
"items": [
|
||||
"contribution/issue",
|
||||
"contribution/pr",
|
||||
"contribution/sponsor"
|
||||
]
|
||||
},
|
||||
"about"
|
||||
]
|
||||
}
|
3
versions.json
Normal file
3
versions.json
Normal file
@@ -0,0 +1,3 @@
|
||||
[
|
||||
"1.4.15"
|
||||
]
|
Reference in New Issue
Block a user