docs: docs: update documentation for Halo 2.5 (#212)

为 Halo 2.5 更新文档。 /kind documentation ```release-note None ```
2026-05-07 01:01:45 +08:00 · 2023-04-28 11:50:17 +08:00
parent 38b006eea3
commit bc5fe02283
108 changed files with 9218 additions and 69 deletions
@@ -0,0 +1,102 @@
+---
+title: 附件
+description: 附件管理相关功能说明
+---
+
+## 存储策略
+
+为了能够更加灵活地管理附件的存储位置，Halo 提供了存储策略的概念。
+
+Halo 中支持多种类型的存储策略，你可以通过安装插件的方式对支持的存储策略类型进行扩展。一个存储策略包含了存储提供者，具体存储位置等使用该类型存储所必要的各种信息。
+
+你可以点击附件页面右上角的 `存储策略` 按钮对存储策略进行管理。
+
+![存储策略](/img/user-guide/attachments/attachment-policy.png)
+
+### 新建存储策略
+
+点击存储策略列表右上方的 `+` 添加按钮即可新建一个存储策略。
+
+![添加存储策略](/img/user-guide/attachments/attachment-policy-add.png)
+
+添加时首先需要选择一种存储策略类型，系统内置的存储策略为本地存储，图中的 `Aliyun OSS` 阿里云的 OSS 对象存储由[该插件](https://github.com/halo-sigs/plugin-alioss)提供。
+
+![添加本地存储策略](/img/user-guide/attachments/attachment-policy-add-local.png)
+添加一个本地存储时，你需要输入名称及存储位置信息。其中的存储位置决定了使用该存储策略的附件，在服务器上的实际存储路径，路径规则为 `{Halo 工作目录}/attachments/{存储位置}`，其中的 Halo 工作目录由安装时指定的参数决定，默认为 `~/.halo2`。
+:::info
+默认的 Docker 部署方式，实际存储位置由挂载到 Halo 容器工作目录的服务器目录所决定。
+:::
+
+### 删除存储策略
+
+点击存储策略列表指定存储所在行后方的 `···` 更多操作按钮即可对该存储策略进行编辑或删除。
+
+![存储策略操作](/img/user-guide/attachments/attachment-policy-operate.png)
+:::info
+为了保护附件安全避免用户误操作，当存储策略下存在附件时，该存储策略不允许删除。如果确定要删除某个存储策略及该存储策略中的所有附件，可以先按照存储策略对附件进行筛选，先批量删除存储策略下的所有附件，再删除存储策略。
+:::
+
+## 附件分组
+
+通过附件分组功能可以方便地将同一类型、同一用途的附件划分到一个分组中，方便后续附件的管理和插件。
+
+附件所使用的存储策略决定了附件的实际存储位置和 URL 规则，而附件分组功能仅是逻辑上的归类划分，不会影响附件的存储位置及 URL。
+
+### 新建分组
+
+点击附件列表上方的 `添加分组` 按钮即可新建一个分组。
+
+![添加分组](/img/user-guide/attachments/attachment-group-add.png)
+
+### 删除分组
+
+点击附件列表上方指定分组上的 `···` 更多按钮，可以对分组进行重命名或删除操作。
+
+Halo 目前提供了两种分组删除策略：
+
+1. **删除并将附件移动至未分组**：分组被删将被删除，分组下的附件移动到未分组中；
+2. **删除并同时删除附件**：先删除下的所有附件后，再删除该分组。
+:::warning
+当使用 `删除并同时删除附件` 方式时，分组下的所有附件会被同时删除且不可恢复、无法找回，请谨慎进行该操作。
+:::
+
+## 上传附件
+
+点击附件列表右上方的 `上传` 按钮即可上传新的附件到 Halo。
+:::info
+附件会被上传到当前选中的分组中，如果选择的是 `全部` 附件，则附件会被默认上传到 `未分组` 中。
+:::
+
+![上传附件](/img/user-guide/attachments/attachment-upload.png)
+
+上传附件时你需要先选择一个存储策略，后续上传的附件将会存储在选中的存储策略中。
+
+你可以点击 `浏览` 或 `我的设备` 图标唤起本地文件管理器进行文件选择，也可以直接将文件拖拽到待上传文件区域中。
+
+![上传多个附件](/img/user-guide/attachments/attachment-upload-multiple.png)
+
+如上图所示，你可以同时添加多个文件一次性完成多个附件的上传。
+
+## 查看附件
+
+点击附件列表中的某一个附件即可查看该附件的详细信息。
+:::info
+对于存储策略类型为本地存储的附件，详细信息中的的原始链接生成规则为 `/upload/{存储策略存储路径}/{文件名称}`。
+:::
+
+## 删除附件
+
+附件页面提供两种浏览模式，列表模式和平铺模式。
+
+在平铺模式下，你可以点击附件缩略图右上角的 `√` 图标选中若干个附件，通过上方的批量操作按钮删除选中的附件。
+![批量操作附件](/img/user-guide/attachments/attachment-batch-operate.png)
+
+在列表模式下，你可以点击指定附件所在行后方的 `···` 更多按钮，对附件进行删除操作。
+
+:::warning
+附件删除后不可恢复、无法找回，请谨慎进行该操作。
+:::
+
+## 移动附件所在分组
+
+与批量删除操作类似，你可以选中多个附件后在上方的批量操作按钮中选择 `移动` 操作，将所选附件移动到指定的分组中。
@@ -0,0 +1,38 @@
+---
+title: 备份迁移
+description: 关于备份和迁移的最佳实践
+---
+
+:::info
+在开始之前，我们推荐你先阅读 [《写在前面》](/getting-started/prepare) 的名词解释部分。
+:::
+
+## 备份
+
+### 数据备份
+
+目前 Halo 在后台的小工具中提供了数据导出的功能，此功能的作用为导出数据库的所有数据，格式为 `JSON`。通常可以作为切换数据库类型的时候使用。需要注意的是，此备份仅仅为备份数据，不包含其他诸如主题、附件等资料。如下图：
+
+![halo-data-export.png](/img/halo-data-export.png)
+
+点击右下角的备份按钮即可导出所有数据，之后点击备份文件的标题即可下载。
+
+### 整站备份
+
+通过 [《写在前面》](/getting-started/prepare) 的名词解释部分我们可以知道，Halo 的所有数据都是存放在当前用户目录的工作目录（.halo）下的（使用 MySQL 数据库除外，你还需要导出 MySQL 数据）。**所以我们备份整站的数据仅需备份这个目录即可**，不管你使用何种方式。不过，为了操作方便，我们也在后台的小工具中提供了备份整站数据的功能，和上面所说的数据备份一致，点击备份按钮即可打包工作目录文件夹。如下图：
+
+![halo-workspace-export.png](/img/halo-workspace-export.png)
+
+## 迁移
+
+### 导入数据
+
+此功能为导入上面所说的数据备份产生的数据文件（JSON 格式），并非整站备份的工作目录文件。需要注意的是，此功能仅在站点初始化的时候支持。如下图：
+
+![halo-data-import.png](/img/halo-data-import.png)
+
+上传文件之后，点击导入即可。
+
+### 整站迁移
+
+此操作通常用于迁移服务器，基于上面 **整站备份** 所说，Halo 的所有数据都是存放于当前用户目录的工作目录（.halo）下的。当然，这仅限于使用 **H2 Database** 的情况下，如果你使用的 MySQL，那么还需要手动导出 MySQL 数据。所以，我们迁移服务器仅仅需要将工作目录的备份文件上传到新服务器的用户目录下解压，然后按照 [《安装指南》](/getting-started/install/linux) 重新安装即可。MySQL 用户还需要做的就是手动导出 MySQL 数据，并在新服务器上导入。
@@ -0,0 +1,72 @@
+---
+title: 基础说明
+description: Halo 中的基本概念说明
+---
+Halo 作为一款好用又强大的开源建站工具，配合上不同的模板与插件，可以很好地帮助你构建你心中的理想站点。它可以是你公司的官方网站，可以是你的个人博客，也可以是团队共享的知识库，甚至可以是一个论坛、一个商城。
+
+为了更好地发挥出 Halo 的价值，这里有一些基本概念需要你进行了解。
+
+## 控制台
+
+控制台是一个 Halo 站点的后台管理系统，只有具有权限的登录用户才可以正常使用控制台功能。你可以在控制台中管理站点中的文章、页面、附件等各种内容，调整站点使用的主题或各种设置。
+
+:::info
+控制台默认地址为 `$HALO_EXTERNAL_URL/console/`。忘记密码请参考[常见问题中的忘记密码章节](../user-guide/faq.md#忘记密码怎么办)进行处理。
+:::
+
+### 界面说明
+
+![控制台界面说明](/img/user-guide/common/控制台界面说明.png)
+
+1. **全局搜索框**：点击或通过快捷键 `Ctrl+K` 可以呼出全局搜索框，输入关键字可以在所有文章、页面、附件、用户及设置项等所有内容中进行全局搜索；
+2. **侧边导航栏**：对控制台提供的功能进行导航，点击导航栏条目会在页面右侧显示对应功能页面。安装某些插件可能会扩展导航栏条目；
+3. **用户信息展示及操作**：展示当前登录用户的头像、名称及角色等信息，`···` 中提供更多用户相关操作；
+4. **功能页面标题**： 当前所在的功能页面标题；
+5. **功能页面操作区域**：当前所在功能页面提供的功能操作按钮；
+6. **功能页面主体**： 当前所在功能页面的主体显示区域，显示内容及形式视具体页面功能而定。
+
+## 文章
+
+文章是 Halo 中的核心概念之一。一篇文章主要由纯文本的文章标题和富文本的文章内容构成，除此之外你还可以为文章设置所属分类、添加标签、设置封面图等。
+
+在不同的站点类型不同的应用场景中，文章的实际含义也会有所区别，它可以代表一则公司新闻、一篇博客或者产品文档中的某一章节。
+
+## 页面
+
+Halo 中存在两种类型的页面，`功能页面` 和 `自定义页面`。
+
+### 功能页面
+
+功能页面通常由各个插件提供，页面功能及在控制台呈现的内容由具体提供该页面的插件决定。
+
+### 自定义页面
+
+自定义页面与文章类似，同样包含页面标题和富文本形式的页面内容。与文章不同的是自定义页面无法设置所属分类和标签信息，一般用于站点中单一展示功能的页面，例如常见的站点关于页面、联系我们页面等。
+
+## 分类
+
+通过分类可以更好的组织管理文章。分类之间存在层级关系，一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。
+
+## 标签
+
+标签可以用于为文章添加特定标记，与分类不同的是标签之间没有层级关系。一篇文章也可以同时添加多个标签。
+
+## 附件
+
+由用户上传的，供文章、主题设置等各个地方引用的文件。多用于文章配图、主题配图、用户头像等场景。
+
+## 主题
+
+包含了各种站点页面模板的资源包。用户访问 Halo 站点浏览到的内容及样式，由 Halo 管理端所配置使用的主题所决定。
+
+:::info
+当前 Halo 支持的主题可在[Awesome Halo](https://github.com/halo-sigs/awesome-halo)仓库查看。
+:::
+
+## 插件
+
+用于扩展 Halo 功能的软件包。插件独立于 Halo 核心应用，可以单独安装、升级、卸载。
+
+:::info
+当前 Halo 支持的插件可在[Awesome Halo](https://github.com/halo-sigs/awesome-halo)仓库查看。
+:::
@@ -0,0 +1,172 @@
+---
+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代码`的。
@@ -0,0 +1,155 @@
+---
+title: 常见问题
+description: 使用上的常见问题
+---
+
+### Halo 是什么？
+
+**Halo** [ˈheɪloʊ]，是一款好用又强大的[开源建站工具](https://github.com/halo-dev/halo)，配合上不同的模板与插件，可以很好地帮助你构建你心中的理想站点。它可以是你公司的官方网站，可以是你的个人博客，也可以是团队共享的知识库，甚至可以是一个论坛、一个商城。
+
+### 忘记密码怎么办？
+
+如果安装时没有指定 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD` 环境变量，系统会随机一个初始化密码，可以通过下面的命令进行查看。
+
+```bash
+docker logs halo | grep 'Generated random password:' | tail -1
+```
+
+如果你已经修改过初始化密码后忘记了密码，假设系统中还有可用的具有用户管理权限的其他用户，可以通过该用户参考[修改用户密码](./users#修改用户密码)部分，修改指定用户的密码。没有可用的具有用户管理权限的管理员用户时，目前需要通过删除数据库记录的方式，触发管理员用户的初始化任务进行密码重置。
+
+假设 Halo 使用容器方式运行，容器名称为 `halo`，具体操作如下。
+
+1. 停止 Halo 服务
+
+  ```bash
+  docker stop halo
+  ```
+
+2. 连接 Halo 使用的数据库，删除 admin 用户记录
+
+  以容器化部署的 PostgreSQL 为例，假设容器名称为 `halo_db`。
+
+  ```bash
+  # 进入 psql 命令行
+  docker exec -it halo_db psql halo
+
+  # 执行下面的 SQL 删除 admin 用户记录
+  delete from extensions where name like '/registry/users/admin';
+  ```
+
+  :::info
+  其他类型的数据库处理方式类似，先通过命令行或数据库连接工具连接到数据库后，再执行上面的 `delete` SQL 语句。
+  :::
+
+3. 重新启动 Halo 服务
+
+  ```bash
+  docker start halo
+  ```
+
+4. 登录 Halo 控制台
+
+  如果部署时通过 `HALO_SECURITY_INITIALIZER_SUPERADMINUSERNAME` 和 `HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD` 环境变量指定了初始化用户名和密码，使用该用户名密码登录控制台。
+  
+  如果未指定该配置，则默认用户名为 `admin`，默认密码将打印在 Halo 容器日志中，可以通过如下命令查看。
+
+  ```bash
+  docker logs halo | grep 'Generated random password:' | tail -1
+  ```
+
+### 为什么百度无法搜索到我的站点？
+
+这是一个暂时无法解答的问题。所涉及到的问题过多，受影响因素可能有域名、服务器 IP 位置、建站时间、网站结构、内容等等。建议了解一下 SEO 相关知识对网站进行优化，目前我们在程序方面做的优化有：
+
+- 支持 sitemap 站点地图：可访问 `/sitemap.xml` 或 `/sitemap.html`
+- 全站绝对路径
+- 页面静态化
+- 支持自定义文章关键字和描述
+- 支持自定义站点关键字以及站点描述
+
+### 附件上传提示 `413 Request Entity Too Large` 如何解决？
+
+这可能是由于 Nginx 的上传大小限制所导致的。可以在 Nginx 的配置文件下的 server 节点加入 `client_max_body_size 1024m;` 即可解决，如果 1024m 还不够，请自行断定，详细配置参考如下：
+
+```nginx {4}
+server {
+    listen       80;
+    server_name  localhost;
+    client_max_body_size 1024m;
+}
+```
+
+### 网站加载速度慢，是什么问题导致的？
+
+导致网站加载速度慢的原因有很多，建议打开浏览器的 Developer Tools 查看具体是哪个请求时间过长，然后进行针对性的优化。这里提供一些可能的原因：
+
+1. 服务器带宽过小，很多厂商提供的最低带宽一般是 1M。
+2. 服务器地区过远，这个需要自行取舍。
+3. 网站上的图片过多或者体积过大，可以尝试压缩图片，或者参考 [优雅的让 Halo 支持 webp 图片输出](https://halo.run/archives/halo-and-webp.html) 的教程配置一个 Webp 图片的服务。
+4. 部分主题的静态资源可能是由公共 CDN 提供的，当这个 CDN 不稳定的时候可能会导致加载变慢。
+
+一些提升网站加载速度的建议：
+
+1. 尽量不要选择 1M 带宽的服务器，可以根据自己的预算适当提升带宽。一般 3M 以上即可。
+2. 尽量购买网络质量较好的服务器，或者较近区域的服务器。
+3. 如果一定需要放大量的图片，建议先无损压缩一下再使用。
+4. 如上所说，可以自行搭建一个 Webp 图片转换的服务，参考 [优雅的让 Halo 支持 webp 图片输出](https://halo.run/archives/halo-and-webp.html)。
+5. 如果网站的静态资源加载慢是由三方 CDN 导致的，可以自行修改主题。
+6. 可以使用全站 CDN 加速的方案。
+
+### 如何在一台服务器上部署多个站点？
+
+参考 [写在前面/工作目录](../getting-started/prepare.md#工作目录) 我们可以知道，工作目录对于 Halo 主程序来说是固定的。如果我们需要部署多个站点，我们提供以下两种方式以供参考：
+
+1. 创建多个 Linux 账户，并在每个账户上运行一个独立的 Halo。因为工作目录是基于账户的，所以每个账户都有自己的工作目录。但是有一点需要注意，就是需要修改每一个 Halo 的运行端口，参考：[配置参考/端口](../getting-started/config#%E7%AB%AF%E5%8F%A3)
+2. 使用 Docker 创建多个容器，因为使用 Docker 可以将内部的工作目录映射到宿主机的任何目录，可以参考以下创建容器的方式：
+
+    ```bash
+    # 第一个 Halo 容器
+    docker run \
+      -it -d \
+      --name halo-1 \
+      -p 8090:8090 \
+      -v ~/.halo2.1:/root/.halo2 \
+      -e HALO_EXTERNAL_URL=http://localhost:8090/ \
+      -e HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD=P@88w0rd \
+      halohub/halo:2.5
+
+    # 第二个 Halo 容器
+    docker run \
+      -it -d \
+      --name halo-2 \
+      -p 8090:8090 \
+      -v ~/.halo2.2:/root/.halo2 \
+      -e HALO_EXTERNAL_URL=http://localhost:8090/ \
+      -e HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD=P@88w0rd \
+      halohub/halo:2.5
+    ```
+
+更多 Docker 相关的教程请参考：[使用 Docker 部署 Halo](../getting-started/install/docker.md)
+
+### 如何查看运行日志？
+
+使用 docker logs 命令进行查看。
+
+```bash
+# '-f' 滚动更新日志
+# '-n 200' 从倒数第200行开始查看
+# 更多帮助可以查看 'docker logs --help'
+docker logs -f halo_next -n 200
+```
+
+### 前台样式丢失，如何解决？
+
+前台样式不正常或者丢失有很多种问题的可能，最快捷定位问题的方式就是打开浏览器控制台查看具体请求的错误，以下列出了部分导致出现该问题的常见原因：
+
+1. 后台设置的 `博客地址` 与实际访问地址不一致。也可能是开启了 https 之后，无法正常加载 http 资源，将 `博客地址` 改为 https 协议即可。
+2. Nginx 配置了静态资源缓存，但没有设置 `proxy_pass`，参考如下：
+
+    ```nginx
+    location ~ .*\.(gif|jpg|jpeg|png|bmp|swf|flv|mp4|ico)$ {
+        proxy_pass http://halo;
+        expires 30d;
+        access_log off;
+    }
+    ```
@@ -0,0 +1,454 @@
+---
+title: Markdown 语法
+description: Halo 编辑器中所支持的 Markdown 语法说明
+---
+
+## 写在前面
+
+从 1.5.0 版本开始，Halo 默认保存编辑器渲染的 html 文档。使用的 Markdown 渲染库为 [markdown-it](https://github.com/markdown-it/markdown-it)，我们也对此进行了封装：[@halo-dev/markdown-renderer](https://github.com/halo-dev/js-sdk/tree/master/packages/markdown-renderer)。后续我们会在任何需要渲染 Markdown 的地方都使用此库，保证 Markdown 渲染结果一致。
+
+## 基础语法
+
+markdown-it 使用了 [CommonMark spec](https://spec.commonmark.org) 规范，基础语法请参考 [CommonMark spec](https://spec.commonmark.org)。
+
+## 自动链接（Auto Link）
+
+支持自动将一个链接格式的文本转换为 a 标签链接。
+
+语法规则：
+
+```plain
+https://halo.run
+```
+
+渲染结果：
+
+```html
+<a href="https://halo.run">https://halo.run</a>
+```
+
+预览：
+
+<https://halo.run>
+
+## 代码块（Code Block）
+
+语法规则：
+
+````markdown {1}
+```language
+内容
+```
+````
+
+示例：
+
+````markdown {1}
+```java
+public static void main(String[] args){
+    System.out.println("Hello World!");
+}
+```
+````
+
+````markdown {1}
+```javascript
+console.log("Hello World!")
+```
+````
+
+:::info
+注意：代码高亮需要主题添加插件支持，不同的主题可能有实现差异。
+:::
+
+## 缩写（abbr）
+
+语法规则：
+
+```markdown
+*[HTML]: Hyper Text Markup Language
+*[W3C]:  World Wide Web Consortium 
+The HTML specification
+is maintained by the W3C.
+```
+
+渲染结果：
+
+```html
+<p>
+    The
+    <abbr title="Hyper Text Markup Language">
+        HTML
+    </abbr>
+    specification
+    <br />
+    is maintained by the
+    <abbr title="World Wide Web Consortium">
+        W3C
+    </abbr>
+    .
+</p>
+```
+
+## Attrs
+
+此语法支持将 `id` `class` `target` 添加到渲染后的 HTML 标签上。
+
+示例：
+
+```markdown
+# Halo {#halo}
+```
+
+```markdown
+> Hello Halo {.info}
+```
+
+```markdown
+[https://halo.run](https://halo.run) {target="_blank"}
+```
+
+渲染结果：
+
+```html
+<h1 id="halo" tabindex="-1">Halo</h1>
+```
+
+```html
+<blockquote class="info"> <p>Hello Halo</p> </blockquote>
+```
+
+```html
+<a href="https://halo.run" target="_blank">https://halo.run</a>
+```
+
+## Emoji
+
+支持将 Emoji 的文字形式转化为图片形式。
+
+示例：
+
+```markdown
+:100:
+```
+
+渲染结果：
+
+```html
+💯
+```
+
+## 脚注（Footnote）
+
+语法规则：
+
+```markdown
+[^脚注名]
+[^脚注名]: 脚注内容
+```
+
+示例：
+
+```html
+驿外[^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>
+```
+
+## 下划线（ins）
+
+示例：
+
+```markdown
++inserted++
+```
+
+渲染结果：
+
+```html
+<ins>inserted</ins>
+```
+
+预览：
+
+<ins>inserted</ins>
+
+## 标记（mark）
+
+示例：
+
+```markdown
+==marked==
+```
+
+渲染结果：
+
+```html
+<mark>marked</mark>
+```
+
+预览：
+
+<mark>marked</mark>
+
+## 下标（sub）
+
+示例：
+
+```markdown
+H~2~0
+```
+
+渲染结果：
+
+```html
+H<sub>2</sub>0
+```
+
+预览：
+
+H<sub>2</sub>0
+
+## 上标（sup）
+
+示例：
+
+```markdown
+29^th^
+```
+
+渲染结果：
+
+```html
+29<sup>th</sup>
+```
+
+预览：
+
+29<sup>th</sup>
+
+## 目录（TOC）
+
+此语法支持根据标题生成文档目录。
+
+示例：
+
+```markdown
+[toc]
+
+# Heading
+
+## Sub heading 1
+Some nice text
+
+## Sub heading 2
+Some even nicer text
+```
+
+渲染结果：
+
+```html
+<p>
+    <div class="table-of-contents">
+        <ul>
+            <li>
+                <a href="#heading">
+                    Heading
+                </a>
+                <ul>
+                    <li>
+                        <a href="#sub-heading-1">
+                            Sub heading 1
+                        </a>
+                    </li>
+                    <li>
+                        <a href="#sub-heading-2">
+                            Sub heading 2
+                        </a>
+                    </li>
+                </ul>
+            </li>
+        </ul>
+    </div>
+</p>
+<h1 id="heading" tabindex="-1">
+    Heading
+</h1>
+<h2 id="sub-heading-1" tabindex="-1">
+    Sub heading 1
+</h2>
+<p>
+    Some nice text
+</p>
+<h2 id="sub-heading-2" tabindex="-1">
+    Sub heading 2
+</h2>
+<p>
+    Some even nicer text
+</p>
+```
+
+## 任务列表（Task Lists）
+
+示例：
+
+```markdown
+- [x] Apple
+- [ ] Banana
+```
+
+渲染结果：
+
+```html
+<ul class="contains-task-list">
+    <li class="task-list-item">
+        <input class="task-list-item-checkbox" checked="" disabled="" type="checkbox">
+        Apple
+    </li>
+    <li class="task-list-item">
+        <input class="task-list-item-checkbox" disabled="" type="checkbox">
+        Banana
+    </li>
+</ul>
+```
+
+预览：
+
+- [x] Apple
+- [ ] Banana
+
+## 数学公式（Katex）
+
+我们使用了 Katex 作为数学公式渲染的插件，因为从 1.5.0 开始，我们将直接保存编辑器渲染的内容，在保存的时候就已经保存了渲染好的 Katex 结构。所以在前台无需引入 Katex 插件来进行渲染，但目前仍需要引入 Katex 的样式文件，如果主题没有支持，可以在系统设置的 `自定义内容页 head：` 中加入以下代码：
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/katex@0.12.0/dist/katex.min.css" />
+```
+
+### 行内公式
+
+示例：
+
+```markdown
+$\sqrt{3x-1}+(1+x)^2$
+```
+
+预览：
+
+Example：$\sqrt{3x-1}+(1+x)^2$
+
+### 块级公式
+
+示例：
+
+```markdown
+$$\begin{array}{c}
+
+\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &
+= \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\
+
+\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\
+
+\nabla \cdot \vec{\mathbf{B}} & = 0
+
+\end{array}$$
+```
+
+预览：
+
+$$\begin{array}{c}
+
+\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &
+= \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\
+
+\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\
+
+\nabla \cdot \vec{\mathbf{B}} & = 0
+
+\end{array}$$
+
+## 图表（Mermaid）
+
+从 Halo 1.5.0 开始，编辑器支持渲染 Mermaid 图表为 svg 内容，并直接保存渲染后的内容，所以无需在前台引入 Mermaid 插件进行渲染。
+
+示例：
+
+````markdown
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+````
+
+````markdown
+```mermaid
+sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->>John: Hello John, how are you?
+    loop Healthcheck
+        John->>John: Fight against hypochondria
+    end
+    Note right of John: Rational thoughts <br/>prevail!
+    John-->>Alice: Great!
+    John->>Bob: How about you?
+    Bob-->>John: Jolly good!
+```
+````
+
+预览：
+
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+
+```mermaid
+sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->>John: Hello John, how are you?
+    loop Healthcheck
+        John->>John: Fight against hypochondria
+    end
+    Note right of John: Rational thoughts <br/>prevail!
+    John-->>Alice: Great!
+    John->>Bob: How about you?
+    Bob-->>John: Jolly good!
+```
+
+## 短连接
+
+参考 [1.4.17/Markdown 语法](../../versioned_docs/version-1.4/user-guide/markdown.md#短连接)。目前已经在 1.5.x 移除，建议直接使用官方提供的嵌入代码。
@@ -0,0 +1,41 @@
+---
+title: 页面
+description: 页面管理相关功能说明
+---
+
+Halo 中存在两种类型的页面，`功能页面` 和 `自定义页面`。
+
+### 功能页面
+
+功能页面通常由各个插件提供，页面功能及在控制台呈现的内容由具体提供该页面的插件决定。
+
+例如[链接插件](https://github.com/halo-sigs/plugin-links)便实现了一个站点链接管理功能，用户可以通过该插件更加方便地管理与站点相关的友情链接。安装该插件后，在功能页面会出现列表会出现如下条目。
+
+![链接功能页面](/img/user-guide/pages/page-links.png)
+
+点击这个条目即可进入到链接插件提供的配置管理页面。
+
+![链接功能页面](/img/user-guide/pages/page-links-edit.png)
+
+你可以在这个页面中管理链接分组和链接条目。链接信息维护完成后，通过 `$HALO_EXTERNAL_URL/links/` 便可访问到对应的页面。
+
+:::info
+对于 `links` 页面的访问需要主题端支持，即安装使用的主题需要有对应的 `links.html` 模板，且在模板中正确处理链接插件提供的数据。
+:::
+
+### 自定义页面
+
+自定义页面与文章类似，同样包含页面标题和富文本形式的页面内容。与文章不同的是自定义页面无法设置所属分类和标签信息，一般用于站点中单一展示功能的页面，例如常见的站点关于页面、联系我们页面等。
+
+自定义页面的访问链接为 `$HALO_EXTERNAL_URL/{slug}/` 其中 `slug` 为自定义页面的别名。
+
+对于如下的关于页面，便可以通过 `$HALO_EXTERNAL_URL/page/` 地址进行访问。
+![链接功能页面](/img/user-guide/pages/page-about.png)
+
+:::info
+自定义页面默认使用主题端的 `page.html` 模板进行渲染，如果主题中提供了针对自定义页面的其他模板，用户可以通过修改自定义页面高级设置中的自定义模板设置进行使用。
+:::
+
+#### 自定义页面操作
+
+对于自定义页面的新建、设置、发布及删除等操作，与文章操作基本一致，具体操作请参考[《用户指南-文章》](./posts.md)章节，此处不再赘述。
@@ -0,0 +1,52 @@
+---
+title: 插件
+description: 插件管理相关功能说明
+---
+
+插件时用于扩展 Halo 功能的软件包。插件独立于 Halo 核心应用，可以单独安装、升级、卸载。
+
+:::info
+当前 Halo 支持的插件可在[Awesome Halo](https://github.com/halo-sigs/awesome-halo)仓库查看。
+:::
+
+本文档仅对插件的基本管理功能进行说明，关于插件的详细使用说明请参考对应插件的文档。
+
+## 安装插件
+
+点击插件页面右上角的 `安装` 按钮，在弹出的文件上传对话框中上传插件文件即可完成插件安装。
+
+![安装插件](/img/user-guide/plugins/plugin-install.png)
+
+插件安装成功后，便会出现在已安装主题列表中。你可以点击某个插件进入到插件详情页面。
+
+## 插件设置
+
+点击插件列表中的某个插件进入插件详情页面。与主题设置类似，插件详情页面默认显示出了当前插件的详细信息，在详细信息标签页后方的标签页，即为插件提供的相关设置。不同的插件提供的设置项各不相同，设置项的详细说明请参考对应插件的文档。
+
+![插件设置](/img/user-guide/plugins/plugin-setting.png)
+
+以 Unsplash 插件为例，该提供仅在基本设置组中提供了 `Access Key` 一项配置，用于调用 Unsplash 接口。
+
+:::info
+你可以点击插件列表指定插件所在行后方的 `···` 更多操作按钮，选择其中的 `重置` 选项将插件提供的设置项恢复为默认值。
+:::
+
+## 启用/禁用插件
+
+点击插件列表或插件详情页中的启用/禁用开关，即可切换插件的启用禁用状态。
+
+![插件启用/禁用](/img/user-guide/plugins/plugin-switch.png)
+
+## 升级插件
+
+点击插件列表指定插件所在行后方的 `···` 更多操作按钮，选择其中的 `升级` 选项即可上传新的插件文件对当前插件进行升级。
+
+## 卸载插件
+
+点击插件列表指定插件所在行后方的 `···` 更多操作按钮，选择其中的 `卸载` 选项即可对当前插件进行卸载。
+![卸载插件](/img/user-guide/plugins/plugin-uninstall.png)
+
+:::info
+目前提供了 `卸载` 及 `卸载并删除配置` 两种卸载方式。
+仅卸载插件时插件的配置信息会进行保留，当重新安装插件后还可以使用之前已保存的配置。
+:::
@@ -0,0 +1,150 @@
+---
+title: 文章
+description: 文章管理相关功能说明
+---
+## 新建文章
+
+目前你可以通过以下两种方式新建一篇文章：
+
+1. 点击仪表盘快捷访问组件中的创建文章
+:::info
+仪表盘中需要存在快捷访问组件（默认存在）。关于仪表盘组件配置，请参考《用户指南-仪表盘》章节。
+:::
+2. 通过左侧导航栏进入文章页面，点击右上角的新建按钮
+
+进入到如下页面后，你就可以开始编辑自己的文章内容了：
+
+![文章编辑界面说明](/img/user-guide/posts/post-edit.png)
+
+在文章编辑器中输入你想展现的内容，你可以通过编辑器上方的工具栏调整指定内容的格式或者插入图片、音视频等各类附件。编辑器还提供了各种快捷指令，通过输入 `/` 字符便可以快速选择常用的输入类型，不需要操作鼠标便可以轻松完成文章排版。
+
+:::info
+编辑器详细使用说明请参考[《用户指南-编辑器》](./posts.md)。
+
+如果安装并启用了额外的编辑器插件，可以点击右上角切换使用不同的编辑器。以下文档内容均使用默认编辑器进行说明。
+:::
+
+在页面右侧你可以看到文章的大纲结构及字词数等详细信息。一切满意之后，你可以选择暂存这篇文章的草稿或直接将文章进行发布。
+
+:::info
+点击保存按钮将只保存文章内容的修改，不会将新修改的内容进行发布。对于未发布的文章内容，只有授权用户可以在控制台进行查看，不会出现在站点内容中；
+
+点击发布按钮将直接发布修改后的内容。对于已发布的文章，默认可以通过站点地址进行公开访问，用户可以在文章高级设置中修改可见性。
+:::
+
+## 文章设置
+
+当你想修改一篇文章的标题、所属分类等信息时，你可以通过以下方式进行操作：
+
+1. 点击文章列表指定文章所在行的 `···` 更多操作按钮，选择设置；
+2. 在文章列表点击指定文章的标题进入文章编辑页面，点击页面右上角的设置按钮。
+
+![文章编辑界面说明](/img/user-guide/posts/post-setting.png)
+
+### 设置说明
+
+- **标题**：用于在主题端显示的文章标题；
+- **别名**：多用于文章 URL 路径定位，一般不会出现在页面中；
+- **分类目录**：文章所属分类，方便用户区分文章类型进行针对性浏览，一篇文章可以属于多个分类；
+- **标签**：文章添加的标签，方便用户更进一步标识文章信息，一篇文章可以添加多个标签；
+- **自动生成摘要**：文章摘要是对文章内容的概括性描述；
+  - **是**： 系统根据文章内容，自动生成一段摘要文本；
+  - **否**： 用户自行输入文章摘要文本。
+- **允许评论**：是否允许用户在主题端浏览文章时对该文章发起评论；
+- **是否置顶**：文章是否排序在文章列表的最顶部；
+- **可见性**：访问站点主题端时，哪些人可以看到这篇文章；
+  - **公开**：所有用户均可看到这篇文章，包括未登录用户；
+  - **私有**：仅文章作者可以看到这篇文章。
+- **发表时间**：手动指定文章的发表时间，未指定时以实际发布时间为准；
+- **自定义模板**：主题端使用哪一个文章模板进行页面渲染；
+- **封面图**：用户在主题端显示的文章封面图，需要主题支持该功能；
+- **元数据**：供主题、插件使用的额外数据信息。例如 Halo 官网主题仓库中的主题，便可以使用该功能为主题类型的文章增加一条名为下载地址的元数据，提供对应主题的下载链接。
+
+## 发布及取消发布
+
+对于已发布的文章，默认可以通过站点地址进行公开访问，用户可以在文章高级设置中修改可见性。
+
+你可以在上文介绍的文章设置对话框中，修改文章的发布状态。
+
+在文章设置对话框中，若文章当前处于已发布状态，下方会显示取消发布按钮；若文章处于未发布状态，下方怎会显示发布按钮。
+
+## 删除文章
+
+当你不再需要一篇文章时，你可以通过以下方式删除该文章：
+
+1. 点击文章列表指定文章所在行的 `···` 更多操作按钮，选择删除；
+2. 勾选文章列表中的全选/多选框，选中一篇或多篇文章进行批量删除。
+
+文章删除后会进入回收站中，点击右上角的回收站按钮进入回收站。在回收站中，你可以永久删除或恢复指定的文章。
+
+:::warning
+文章永久删除后将从数据库删除该记录，后续无法再恢复找回。
+:::
+
+## 文章分类管理
+
+通过分类可以更好的组织管理文章。分类之间存在层级关系，一个父分类下可包含多个子分类。一篇文章可以同时属于多个分类。
+
+在文章管理页面，点击页面右上角的 `分类` 按钮即可进入分类管理页面。
+
+### 新建文章分类
+
+点击分类管理页面右上角的 `新建` 按钮即可新建一个分类。
+
+![文章分类编辑界面说明](/img/user-guide/posts/category-create.png)
+
+#### 设置说明
+
+- **名称**：用于在主题端显示的分类名称；
+- **别名**：用于分类 URL 路径定位。默认路径规则为 `$HALO_EXTERNAL_URL/categories/{slug}`，其中 `slug` 为分类别名，访问该地址即可浏览该分类下的所有文章。分类页路由前缀可[在设置中修改](./settings#主题路由设置)；
+- **自定义模板**：主题端使用哪一个文章分类模板进行页面渲染；
+- **封面图**：用户在主题端显示的文章分类封面图，需要主题支持该功能；
+- **描述**：关于改文章分类的更多描述信息；
+- **元数据**：供主题、插件使用的额外数据信息。例如部分主题期望使用不同的颜色对分类进行区分，便可以使用该功能为分类增加颜色相关的元数据。
+
+### 调整分类层级
+
+分类之间存在层级关系，一个父分类下可包含多个子分类。
+
+你可以按住分类前的图标，通过拖拽来调整分类间的层级关系和顺序。
+
+![移动文章分类](/img/user-guide/posts/category-move.gif)
+
+### 修改删除分类
+
+点击指定分类所在行后方的 `···` 更多操作按钮，可以对文章分类进行修改或删除。
+:::warning
+文章分类删除后，对应文章的关联将被解除，且该操作不可恢复，请谨慎进行该操作。
+:::
+
+## 文章标签管理
+
+标签可以用于为文章添加特定标记，与分类不同的是标签之间没有层级关系。一篇文章也可以同时添加多个标签。
+
+### 新建文章标签
+
+点击分类管理页面右上角的 `新建` 按钮即可新建一个分类。
+
+![标签编辑界面说明](/img/user-guide/posts/tag-create.png)
+
+#### 设置说明
+
+- **名称**：用于在主题端显示的标签名称；
+- **别名**：用于标签 URL 路径定位。默认路径规则为 `$HALO_EXTERNAL_URL/tags/{slug}`，其中 `slug` 为标签别名，访问该地址即可浏览具有该标签的所有文章。标签页路由前缀可[在设置中修改](./settings#主题路由设置)；
+- **颜色**：用于在控制台及主题端显示的标签颜色，主题端显示颜色需要主题支持该功能；
+- **封面图**：用户在主题端显示的标签封面图，需要主题支持该功能；
+- **元数据**：供主题、插件使用的额外数据信息。
+
+### 修改删除标签
+
+标签页面提供两种浏览模式，列表模式和平铺模式。点击右上方红框区域对应模式的切换按钮即可进行切换。
+
+![标签浏览](/img/user-guide/posts/tag-list.png)
+
+在列表模式下，点击指定标签所在行后方的 `···` 更多操作按钮，可以对文章标签进行修改或删除。
+
+在平铺模式下，直接点击对应的标签，即可对文章标签进行修改。
+
+:::warning
+文章标签删除后，对应文章的关联将被解除，且该操作不可恢复，请谨慎进行该操作。
+:::
@@ -0,0 +1,72 @@
+---
+title: 站点设置
+description: 站点设置相关功能说明
+---
+
+## 基本设置
+
+Halo 提供了以下站点基本信息设置：
+
+- **站点标题**
+- **站点副标题**
+- **站点 Logo 图片**
+- **站点 Favion 图片**
+
+在控制台设置完成后，主题端可以通过特定的表达式获取到这些信息并且在对应的位置进行展示。具体是否读取使用这些配置、在哪些位置显示这些信息由使用的不同主题而决定。
+
+以 Halo 2.0 的[默认主题 Earth](https://github.com/halo-dev/theme-earth) 为例，这些设置信息将在如下位置进行展示。
+
+![默认主题基本设置说明](/img/user-guide/settings/setting-basic.png)
+
+## 文章设置
+
+针对主题端的文章展示，Halo 提供了以下设置项：
+
+- **文章列表显示条数**
+- **归档页文章显示条数**
+- **分类页文章显示条数**
+- **标签页文章显示条数**
+
+## SEO设置
+
+针对站点的 SEO（搜索引擎优化）需求，Halo 提供了以下设置项：
+
+- **屏蔽搜索引擎**：配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name="robots" content="noindex" />`；
+- **站点关键词**：格式为以`,`分隔的关键词列表，配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name="keywords"> content="{用户的配置关键词}" />`；
+- **站点描述**：配置后会在所有页面 HTML 源码的 head 部分添加 `<meta name=""> content="{用户的配置描述}" />`。
+
+## 评论设置
+
+针对站点的评论功能，Halo 提供了以下设置项：
+
+- **启用评论**：全局评论功能开关配置，修改后影响所有文章、页面的评论功能；
+- **新评论审核**：新增的评论是否需要在控制台进行审核，审核通过后其他访问者才能看到该条评论；
+- **仅允许注册用户评论**：开启后只有登录用户才能添加评论，关闭后匿名（未登录）访问者也可以添加评论。
+
+## 主题路由设置
+
+针对访问站点各种类型页面的 URL 生成规则，Halo 提供了以下主题路由设置项：
+
+- **分类页路由前缀**：定位到指定文章分类页面的 URL 规则前缀，默认为 `/categories/{文章分类别名}`，修改后为 `/{用户定义的分类页路由前缀/{文章分类别名}`；
+- **标签页路由前缀**：定位到指定文章标签页面的 URL 规则前缀，默认为 `/tags/{文章标签别名}`，修改后为 `/{用户定义的标签页路由前缀/{文章标签别名}`；
+- **归档页路由前缀**：定位到文章归档页面的 URL 规则前缀，默认为 `/archives/{年}/{月}` 等路径，修改后为 `/{用户定义的归档页路由前缀/{年}/{月}` 等；
+- **文章详情页访问规则**：定位到具体文章详情页面的 URL 规则前缀，默认为 `/archives/{文章别名}` ，用户可从以下路径规则进行选择：
+  - `/archives/{slug}`
+  - `/archives/{name}`
+  - `/?p={name}`
+  - `/?p={slug}`
+  - `/?p={slug}`
+  - `/{year}/{slug}`
+  - `/{year}/{month}/{slug}`
+  - `/{year}/{month}/{day}/{slug}`
+:::info 变量说明
+    - `slug`：文章别名；
+    - `name`：文章 `metadata.name` 字段值；
+    - `year`：四位数格式的文章发布年份；
+    - `month`：两位数格式的文章发布月份：
+    - `day`：两位数格式的文章发布日。
+:::
+
+## 代码注入
+
+你可以使用代码注入功能，在特定类型的页面中注入额外的代码。你可以通过该功能覆盖或补充部分主题 CSS 样式，或者引入额外的 JavaScript 脚本扩展主题端功能。
@@ -0,0 +1,80 @@
+---
+title: 主题
+description: 主题管理相关功能说明
+---
+
+主题包含了各种站点页面模板的资源包。用户访问 Halo 站点浏览到的内容及样式，由 Halo 管理端所配置使用的主题所决定。
+:::info
+当前 Halo 支持的主题可在[Awesome Halo](https://github.com/halo-sigs/awesome-halo)仓库查看。
+:::
+
+## 安装主题
+
+点击主题页面右上方的 `主题管理` 按钮即可弹出主题管理对话框。
+
+目前 Halo 提供了两种主题安装方式：
+
+1. 通过控制台上传安装
+2. 将主题文件夹拷贝到服务器上的 `{Halo 工作目录}/themes/` 目录下等待 Halo 自动扫描
+
+针对第一种安装方式，你可以点击主题管理对话框下方的 `安装主题` 按钮，在弹出的文件上传对话框中上传主题压缩包。
+
+![安装主题](/img/user-guide/themes/theme-install.png)
+
+主题安装成功后，便会出现在已安装主题列表中。
+
+针对第二种方式，你需要手动将解压后的主题文件夹拷贝到服务器上的指定目录下，如果主题校验通过，你便可以在主题列表的 `未安装` 标签页中看到该主题。
+
+之后点击主题所在行后方的 `安装` 按钮，即可完成该主题的安装。
+
+![后台安装主题](/img/user-guide/themes/theme-install-alt.png)
+
+## 切换主题
+
+同样点击主题页面右上方的 `主题管理` 按钮弹出主题管理对话框。
+
+在弹框中点击选中要切换的目标主题，此时页面返回到主题详情页，点击右上角的 `启用` 按钮即可将当前主题切换为实际使用的主题。
+:::info
+仅选中主题不点击右上角的 `启用` 按钮时，不会影响当前实际使用的主题。
+:::
+
+你也可以在已安装主题列表中，通过后方 ··· 的更多操作中的启用选项直接启用指定的主题。
+
+## 修改主题设置
+
+主题页面默认显示出了当前主题的详细信息，在详细信息标签页后方的标签页，即为主题提供的相关设置。不同的主题提供的设置项各不相同，设置项的详细说明请参考对应主题的文档。
+
+![主题设置](/img/user-guide/themes/theme-setting.png)
+
+以 Halo 的默认主题 Earth 为例，该主题提供了布局、样式、侧边栏、页脚及备案设置共五组配置项。
+
+:::info
+你可以点击主题列表指定主题所在行后方的 `···` 更多操作按钮，选择其中的 `重置` 选项将主题提供的设置项恢复为默认值。
+:::
+
+## 预览主题
+
+通过预览功能，你可以在不更改当前启用主题的情况下查看不同主题的效果。点击主题详情页面右上角的 `预览` 按钮预览当前主题，或者进入已安装主题列表，通过后方 `···` 的更多操作中的预览选项预览指定的主题。
+
+![主题设置](/img/user-guide/themes/theme-preview.png)
+
+在主题预览页面你可以切换不同分辨率的设备，模拟主题在不同终端下的显示效果。也可以通过右上角的功能菜单切换预览的主题，或者调整当前主题的设置，查看不同设置下主题所展现的区别。
+
+## 升级主题
+
+点击主题详情页右上角的 `···` 更多操作按钮，选择其中的 `升级` 选项即可上传新的主题包对当前主题进行升级更新。
+
+## 重载主题配置
+
+如果当前主题提供的设置项发生变化，可以通过 `···` 更多操作中的 `重载主题配置` 选项对主题配置项进行更新。
+
+## 卸载主题
+
+进入已安装主题列表，点击指定主题所在行后方的 `···` 更多操作按钮，选择其中的 `卸载` 选项即可对当前主题进行卸载。
+
+![卸载主题](/img/user-guide/themes/theme-uninstall.png)
+
+:::info
+目前提供了 `卸载` 及 `卸载并删除配置` 两种卸载方式。
+仅卸载主题时主题的配置信息会进行保留，当重新安装主题后还可以使用之前已保存的配置。
+:::
@@ -0,0 +1,95 @@
+---
+title: 用户与权限
+description: 用户管理、权限配置相关功能说明
+---
+
+## 概览
+
+Halo 2.0 版本采用了基于角色的权限控制（RBAC）体系。不同于之前 1.x 版本的单用户设计，现在你可以创建多个用户并且通过赋予不同用户不同角色的方式，为他们分配不同的权限。
+
+Halo 中的权限控制体系示例:
+
+![权限控制体系示例](/img/user-guide/user-permission.png)
+
+## 用户
+
+点击左侧导航栏的 `用户` 条目进入用户管理页面。
+
+### 创建用户
+
+在用户管理页面，点击右上角的 `添加用户` 按钮即可弹出新建用户对话框。
+
+![创建用户](/img/user-guide/users/user-setting.png)
+
+目前支持配置的用户属性有：
+
+- **用户名**：用户登录 Halo 控制台使用的用户名，不可与已有的用户名重复；
+- **显示名称**：用于显示文章作者等用户信息时使用的，更友好的用户名称；
+- **密码**
+- **电子邮箱**
+- **手机号**
+- **头像**
+- **描述**
+- **元数据**：供主题、插件使用的额外数据信息。例如部分主题期望展示作者的学历、工作单位等信息，便可以使用该功能为用户增加相关的元数据。
+
+### 其他操作
+
+点击用户列表中的 `···` 更多操作按钮，可以对指定用户进行修改资料、修改密码等其他更多操作。
+
+![用户列表其他操作](/img/user-guide/users/user-operate.png)
+
+#### 修改用户资料
+
+你可以修改除用户名以外的所有资料，具有用户管理相关权限的用户，也可对其他用户的资料进行修改。
+
+#### 修改用户密码
+
+对于已有的用户，你可以在 `···` 更多操作中修改指定用户的登录密码。
+
+#### 分配角色
+
+对于已有的用户，你可以在 `···` 更多操作中为该用户分配角色，分配角色后该用户具有角色所对应的权限。
+
+:::info
+修改用户分配的角色会影响用户所拥有的权限，可能影响用户使用。
+:::
+
+#### 删除用户
+
+对于已有的用户，你可以在 `···` 更多操作中删除该用户。
+
+:::warning
+删除用户后，该用户之前创建的文章、页面等内容的作者信息将会丢失，可能影响站点内容浏览。此操作不可恢复。
+:::
+
+## 角色
+
+如下图所示，在用户管理页面，点击右上角红色区域的 `角色管理` 按钮，即可进入到角色管理页面。
+
+![角色管理](/img/user-guide/users/role-management.png)
+
+### 创建角色
+
+Halo 提供了全新创建和基于已有角色创建两种角色创建方式。
+
+#### 全新创建
+
+点击角色管理页面右上角的 `新建角色` 按钮即可弹出新建角色对话框，通过这种方式创建的角色默认未勾选任何权限，你需要在对话框中点击切换到权限标签页，为该角色勾选需要的权限。
+
+#### 基于已有角色创建
+
+当系统中已经存在一些基础角色时，你可以点击某个角色所在行中的 `···` 更多操作按钮，选择 `基于此角色创建` 来创建一个新的角色。通过这种方式创建的角色默认继承了原有角色的权限，但你同样可以对新角色的权限进行进一步调整。
+
+![基于已有角色创建角色](/img/user-guide/users/role-fork.png)
+
+### 修改角色信息
+
+对于已有的角色，你可以在 `···` 更多操作中修改指定角色的名称和该角色所拥有的权限。
+
+### 其他操作
+
+对于已有的角色，你可以在 `···` 更多操作中删除指定角色。
+
+:::warning
+删除角色后，分配了该角色的用户会丧失对应的权限，影响用户使用。此操作不可恢复。
+:::