定期备份是保障网站数据安全的基本措施。Halo 支持多种自动备份方式，本文将介绍两种常用方案：通过增强备份插件实现站内定时备份与远程同步，以及通过 1Panel 的计划任务功能备份网站数据。

方式一：通过增强备份插件

增强备份插件是 Halo 专业版 / 商城版专享的高级功能，支持配置定时自动备份和远程同步，适合需要可靠自动化备份方案的用户。

注意：目前 Halo 备份暂不支持备份商城功能的数据。如果你使用了 Halo 的商城功能，推荐参考下方方式二，使用 1Panel 计划任务对网站数据进行完整备份。

前提条件

• 已安装并激活增强备份插件（需 Halo 专业版或商城版）
• 如需开启远程同步，需提前安装 S3 插件 并创建好对应的存储策略。需要注意的是，出于数据安全考虑，不要将此存储策略的存储桶设置为公开访问。

配置定时任务

安装插件后，进入 Halo 控制台备份页面，点击定时任务选项卡，按以下说明完成配置：

1. 是否启用：开启总开关；
2. 计划：选择备份频率，支持每月、每周、每天、每小时；
3. 时区：选择与服务器时区一致的选项；
4. 备份设置：
   • 备份过期时间：设置备份文件的有效期，支持 d（天）、h（小时）、m（分）为单位；
   • 成功记录保留份数：保留最近 N 份成功备份记录，较旧的记录会自动删除；
   • 失败记录保留份数：保留最近 N 份失败备份记录，较旧的记录会自动删除；
5. 配置完成后点击保存。

所有自动创建的备份都会以 cron-backup- 开头，方便与手动备份区分。

配置远程同步（可选）

如果希望将备份文件同步到远程对象存储，可在同一配置页面开启启用远程同步：

1. 附件存储策略：选择一个已创建的远程且私有的存储策略（推荐通过 S3 插件配置）；

   出于安全考虑，此处不会列出本地类型的存储策略。创建存储策略的方法可参考：附件存储策略文档

2. 附件分组：可为备份文件单独创建一个附件分组，便于管理；

3. 成功 / 失败记录保留份数：分别配置同步记录的保留数量。

配置保存后，可在同步任务选项卡中查看所有同步记录及状态。

最后，如果你需要恢复备份，可以参考：备份与恢复

方式二：通过 1Panel 自动备份

如果你的服务器使用了 1Panel 面板，可以直接利用其内置的计划任务功能，定期备份 Halo 所在网站的全部数据，包括数据库和站点文件。

第一步：配置备份账号（可选）

默认情况下，备份文件会保存在当前服务器的本地磁盘。如果希望将备份数据同步到云存储，需要先添加备份账号。

1. 进入 1Panel 控制台，点击左侧菜单面板设置；
2. 切换到备份账号选项卡；
3. 点击添加备份账号，选择对应的存储类型，填写认证信息后确认。

目前支持的存储类型包括：阿里云 OSS、腾讯云 COS、亚马逊 S3、微软 OneDrive、谷歌云盘、阿里云盘、MINIO、WebDAV、SFTP、七牛云 Kodo、又拍云对象存储等。

具体配置文档可参考：备份账号

如果不配置备份账号，备份文件将保存在服务器本地磁盘，请确保磁盘有足够的剩余空间。

第二步：创建备份网站计划任务

1. 进入 1Panel 控制台，点击左侧菜单计划任务；
2. 点击创建计划任务，任务类型选择备份网站；

3. 按以下说明填写配置：
   • 执行周期：选择备份执行的时间，支持同时配置多个执行周期；
   • 备份网站：选择 Halo 所在的网站，也可以选择备份所有网站；
   • 备份账号：选择上一步配置的备份账号，若未配置则默认备份到当前服务器磁盘；
   • 压缩密码：为备份压缩包设置保护密码（可选）；
   • 保留份数：默认保留 7 份，可根据磁盘空间情况调整；
   • 排除规则：可排除不需要备份的文件，例如日志文件或临时目录；
4. 配置完成后点击确认，计划任务即生效。

任务执行完成后，可在计划任务列表点击对应任务查看执行报告，确认备份是否成功，并可直接下载备份文件。

1Panel 如何恢复网站备份可查阅：导入备份

Halo CLI 是一个用于管理 Halo 实例的命令行工具，覆盖文章、单页、评论、通知、附件、插件、主题、备份等操作。

除了命令行本身，它还附带了一套 Skills——这是专门为 AI Agent 设计的上下文文件，告诉 Agent 这个 CLI 有哪些命令、如何使用，Agent 读取 Skills 之后就能直接操作你的 Halo 站点，不需要你手动解释每一步怎么做。

准备工作

安装 CLI

npm install -g @halo-dev/cli  # 要求 Node.js >= 22

登录 Halo 站点

在 Halo 后台「个人中心 - 个人令牌」生成一个 Token，然后在终端执行：

halo auth login \
  --profile myblog \
  --url https://your-halo-site.com \
  --auth-type bearer \
  --token <your-token>

安装 Skills

npx skills add halo-dev/cli -g

操作前先备份

如果你不完全放心让 Agent 修改网站内容，可以在操作之前，完整备份网站：

halo backup create --wait

开始使用

打开任意支持 Skills 的 AI 客户端或 Agent 工具，比如 Claude Code、Codex、OpenClaw、QClaw 等，加载 Skills 后直接用自然语言描述任务即可。

场景一：SEO 检查并修复最近的文章

提示词：

帮我用 Halo CLI 检查最近发布的 10 篇文章的 SEO 情况：
标题是否清晰、摘要是否存在且合适、标签和分类是否合理。
找出有问题的文章，直接帮我修复。

此示例使用 QClaw

场景二：优化某篇文章

提示词：

帮我用 Halo CLI 优化 my-slow-post 这篇文章：
分析标题、内容、摘要、标签是否有改进空间，给出建议后直接执行。

此示例使用 Copilot CLI

场景三：审核并回复评论

提示词：

用 Halo CLI 查看所有待审核的评论，广告或无意义的直接删掉，
有实质性问题的通过并回复。

此示例使用 QClaw

场景四：更新「关于我们」页面

提示词：

用 Halo CLI 把「关于我们」单页里的联系邮箱改为 hi@example.com，
工作地址新增一个重庆，改完发布。

此示例使用 Copilot CLI

场景五：检查并升级插件

提示词：

使用 Halo CLI 帮我看看当前 Halo 站点有哪些插件可以升级，告诉我每个插件当前版本和最新版本内容
确认之后再升级。

Agent 会先列出所有可升级的插件及版本差异，等你确认后再执行升级。

此示例使用 Copilot CLI

总结

上面这几个场景只是起点。Halo CLI 覆盖了主题、附件、备份等更多操作，配合 Skills 之后，Agent 同样能理解和执行这些命令。日常运营中遇到什么重复性的事，都可以试着直接告诉 Agent，让它想办法用 CLI 完成。

如果有想支持但还没有的功能，或者用下来遇到了问题，欢迎到 halo-dev/cli 提 Issue，我们持续在完善。

Halo 是一款强大易用的开源建站工具，它让你无需太多的技术知识就可以快速搭建一个商城、企业网站或者内容管理系统。具备可插拔架构、主题套用、富文本编辑器等多重特性，支持用户根据自己的喜好选择不同类型的插件及主题模板来定制化自己的站点功能及外观。让内容创作和发布更加便捷生动。

截至目前（2026 年 Q1 季度），Halo 已经在 Docker Hub 获得了超过 340 万次下载，GitHub Star 数突破 38 k，并拥有一百多名社区贡献者。

2026 年 04 月 16 日，强大易用的开源建站工具 Halo 正式发布 2.24 版本。

亮点更新

Halo 商城小程序

在 Halo 2.24 中，Halo 商城支持以微信小程序作为销售终端。相较于 Web 端，小程序在国内拥有更高的用户渗透率，更适合承载移动端购物场景。

查看小程序源码及文档：lxware-dev/halo-shop-miniprogram

更多关于小程序的介绍可以访问：https://www.lxware.cn/archives/mini-program

创建个人令牌支持直接选择角色

在 Halo 2.24 中，创建个人令牌支持直接选择当前已有的角色，简化了创建个人令牌的权限选择步骤。

比如，你想通过 Halo CLI 管理网站的所有文章，但不想授予过多权限，那么可以在创建个人令牌的时候直接选择 文章管理员。

完整更新日志

• 付费版：https://releases.halo.run/releases/halo-pro/v2.24.0

• 社区版：https://releases.halo.run/releases/halo/v2.24.0

本文介绍如何在本地环境快速启动一个 Halo 实例，便于你在本机体验或者测试 Halo 的功能。

下面给出两种常见做法：使用 java -jar 运行官方构建的 JAR，或使用 docker run 拉起单容器。二者都默认使用内置 H2 数据库，不必单独安装 MySQL 或 PostgreSQL；数据会落在本机用户目录下的工作文件夹中（后文会说明具体路径）。

如果你想购买服务器在生产环境部署，请参考：安装指南

方式一：使用 java -jar

安装 JDK

后端基于 Java 21 构建，推荐使用 Eclipse Temurin 发行版。

• macOS / Linux

  # 推荐使用 SDKMAN 管理 JDK 版本，如已安装可略过
  curl -s "https://get.sdkman.io" | bash
  
  # 安装 JDK 21
  sdk install java 21-tem

• Windows

  前往 https://adoptium.net 下载 JDK 21 安装包，按向导安装即可。

启动

1. 从 GitHub Releases 或 download.halo.run 下载最新的 halo-*.jar，放到任意目录（下文假设文件名为 halo.jar）。

2. 在该目录执行：

   macOS / Linux

   java -jar halo.jar

   Windows（在 PowerShell 或 CMD 中）

   java -jar halo.jar

3. 启动成功后，在浏览器打开 http://localhost:8090，按向导完成初始化。

4. 结束体验时，在运行 java 的终端中按 Ctrl+C 停止进程。

数据存放位置：未自定义配置时，Halo 会将工作目录（含内置 H2 数据库、附件等）放在当前用户主目录下的 .halo2，即 macOS / Linux 为 ~/.halo2，Windows 为 %USERPROFILE%\.halo2。

提示：H2 为嵌入式文件数据库，不适合作为生产唯一存储；正式环境请换用 PostgreSQL 等并做好 备份。需要自定义端口、外部访问地址或数据库时，可参考 使用 JAR 文件部署。

方式二：使用 docker run

安装 Docker

• macOS：推荐安装 OrbStack（轻量、启动快）或 Docker Desktop

• Windows：推荐安装 Docker Desktop

• Linux：参考 Docker 官方安装文档

安装完成后请确保 Docker 守护进程已运行。

启动

1. 执行：

   # 社区版
   docker run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 halohub/halo:2
   
   # 专业版 / 商城版
   docker run -it -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 halohub/halo-pro:2

   若拉取 Docker Hub 较慢，可将镜像名替换为 registry.fit2cloud.com/halo/halo:2 或 registry.fit2cloud.com/halo/halo-pro:2 。

2. 浏览器访问 http://localhost:8090 完成初始化。

3. 不再使用时停止并删除容器：

   docker stop halo
   docker rm halo

数据存放位置：与 JAR 方式一致，通过 -v ~/.halo2:/root/.halo2 将容器内工作目录映射到本机 ~/.halo2（Windows 请将 ~/.halo2 换为 %USERPROFILE%\.halo2 对应的实际路径）。

两种方式怎么选

两种方式若都使用默认挂载路径，数据目录都会落在 ~/.halo2（Windows 为 %USERPROFILE%\.halo2），请勿在同一目录被两个进程同时占用：若先用 JAR 跑过，再改用 Docker，请先停掉 JAR 进程，或给 Docker 换一个挂载路径。

适合哪些场景？

在开始之前，请先确认这个方案是否适合你。它主要面向以下两类用户：

1. 自研自用：主题由你自己开发并用于自己的网站，希望在每次推送代码后，主题能自动构建并更新到线上站点，省去手动上传的步骤。

2. 开发测试：主题计划分享给他人使用，但需要在自己的站点上持续验证最新构建产物的效果。

如果你只是使用他人开发的主题，通过控制台的应用市场一键更新即可，不需要本文介绍的方案。

准备工作

• 主题代码已托管在 GitHub 仓库

• 主题具备完整的构建流程（例如使用 pnpm build 输出 dist/*.zip）

• Halo 站点可以通过公网访问，并已生成 API Token

推荐在主题的 package.json 的 build 脚本中引入 @halo-dev/theme-package-cli，自动构建一个 zip 包，并输出到 dist 目录，示例：

{
  "scripts": {
    "build": "vite build && npx @halo-dev/theme-package-cli"
  }
}

生成 API Token：

在 Halo 控制台进入个人中心 → 个人令牌，创建一个新的 Token，包含 主题管理 权限，并将其保存到 GitHub 仓库的 Settings → Secrets and variables → Actions 中，变量名设置为 HALO_TOKEN。

注意：此操作需要升级到 Halo 2.24，否则 主题管理 权限可能无法调用升级主题的接口。

工作流说明

整个 CI/CD 流程分为以下几步：

1. 推送代码到 main 分支

2. GitHub Actions 自动触发，检出代码

3. 使用短 commit SHA 更新 theme.yaml 中的版本号，便于追踪每次构建

4. 安装依赖并执行构建，输出主题 zip 包

5. 将构建产物上传为 Artifact 归档备份

6. 安装 Halo CLI，使用 Bearer Token 完成登录认证

7. 调用 halo theme upgrade 将新构建的主题包推送到 Halo 站点

GitHub Actions 配置

在仓库根目录创建 .github/workflows/deploy.yml 文件，内容如下：

name: Deploy theme

on:
  push:
    branches:
      - main
    paths:
      - "**"
      - "!**.md"

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup pnpm
        uses: pnpm/action-setup@v5
        with:
          run_install: false

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: "24"
          cache: "pnpm"

      # 更新主题版本号，便于在控制台中识别当前运行的具体版本
      - name: Update theme version
        run: |
          SHORT_SHA="${GITHUB_SHA::7}"
          sed -i "s/^  version: .*/  version: 0.0.0-${SHORT_SHA}/" theme.yaml
          grep '^  version:' theme.yaml

      - name: Install dependencies
        run: pnpm install

      - name: Build distribution
        run: pnpm build

      - name: Upload artifact
        uses: actions/upload-artifact@v7
        with:
          # 替换为你的主题名称（metadata.name）
          name: theme-foo
          path: dist/*.zip
          retention-days: 7

      - name: Install Halo CLI
        run: npm install -g @halo-dev/cli

      - name: Upgrade theme via Halo CLI
        env:
          HALO_CLI_CONFIG_DIR: ${{ runner.temp }}/halo-cli
          HALO_TOKEN: ${{ secrets.HALO_TOKEN }}
          # 替换为你的主题名称（metadata.name）
          THEME_NAME: theme-foo
          # 替换为你的 Halo 站点地址
          HALO_URL: https://www.halo.run
        run: |
          THEME_ZIP="$(echo dist/*.zip)"

          if [ ! -f "$THEME_ZIP" ]; then
            echo "Theme zip file not found in dist/"
            exit 1
          fi

          halo auth login \
            --profile ci \
            --url "$HALO_URL" \
            --auth-type bearer \
            --token "$HALO_TOKEN"

          halo theme upgrade "$THEME_NAME" \
            --profile ci \
            --file "$THEME_ZIP"

需要注意的是，此 Workflow 配置并不是固定的，这篇文章也只是提供一个思路，你可以根据自身需求进行调整，比如改为只有在创建新的 tag 时才部署。

需要根据实际情况修改的配置

注意事项

• HALO_TOKEN 是敏感信息，务必通过 GitHub Secrets 传入，不要硬编码在工作流文件中

• 工作流中使用了 HALO_CLI_CONFIG_DIR 将 CLI 的配置目录隔离到 runner 临时目录，避免影响其他环境

• 每次部署都会用 commit SHA 更新版本号，方便在控制台中识别当前运行的具体版本

• 如果主题尚未安装到 Halo，需要先手动安装一次，后续再通过此工作流进行升级

页面静态缓存是面向 Halo 2 的插件，在服务端对已渲染的页面做静态缓存，减少重复计算与数据库访问，从而缩短未登录访客打开前台页面的时间。

它适合以文章、页面展示为主、访客大多未登录的博客或官网；与 CDN、图片压缩等手段可以叠加使用。若你还需要从整体上排查慢加载，可参考 网站加载速度慢，是什么问题导致的？。

效果对比

启用前

启用后

安装与启用

1. 在控制台打开应用市场，搜索 页面静态缓存，或打开应用详情页：页面静态缓存；

2. 安装后启用插件即可，无需额外配置也会按默认策略开始工作。

默认缓存策略

在默认设置下，行为如下：

1. 仅未登录访客访问前台页面时会生成缓存，已登录用户访问时不会写入缓存，也不会命中已有缓存。

2. 插件会监听文章内容变更并自动刷新相关缓存，如果站点上其他类型内容更新后需要立刻对所有访客生效，需要你在变更后手动清理缓存（见下文）。

「总是缓存」选项说明

在插件设置中可以开启 总是缓存。开启后：

• 已登录与未登录用户访问时都会使用已有缓存；

• 但只有未登录访问时才会创建或更新缓存。

因此，若主题在页面 HTML 里直接渲染了「当前登录用户的昵称、头像」等数据，不建议开启该选项，否则用户登录后可能仍看到旧页面。

若业务上必须开启，建议把与用户相关的展示改为前端通过 API 异步加载，保证首屏 HTML 可被安全缓存。

手动清理缓存

当站点做了非文章类的更新、或需要立刻让全体访客看到最新前台效果时，可以手动刷新缓存：

在控制台 仪表盘 的快捷访问中，添加 刷新页面缓存 入口。

需要时点击 刷新页面缓存，即可清空当前页面缓存，后续访问会重新生成。

使用上的注意点

• 页面缓存减轻的是应用层渲染与读库压力，不能替代带宽、CDN、图片体积等优化。

• 默认策略下，已登录用户始终走实时渲染，适合需要区分访客与管理员体验的场景。

• 若站点强依赖实时数据，应评估是否启用、以及是否配合「总是缓存」与异步数据加载。

配合 CDN 使用

此插件也可以配合 CDN 使用，利用 CDN 的节点缓存，可以让访客访问就近的节点，以获得更快的访问速度。与 CDN 配合使用通常无需额外配置，默认情况下，此插件会为已缓存的页面添加 max-age=3, s-maxage=120, must-revalidate 的响应头，CDN 会自动缓存这些页面，但需要注意的是：

1. 一定要在 CDN 中配置缓存策略为 遵循源站；

2. 在 Halo 侧清理缓存不会及时清理掉 CDN 的节点缓存，如果需要及时清理，需要在 CDN 侧手动清理。

有关 Halo 配置 CDN 的教程可参考：

• 腾讯云 EdgeOne 接入 Halo 配置指南

• 又拍云 CDN 接入 Halo 配置指南

• 七牛云 DCDN 接入 Halo 配置指南

• 阿里云 ESA 接入 Halo 配置指南

什么是阿里云 ESA？

阿里云边缘安全加速 ESA是阿里云推出的全新一代边缘网络加速平台，整合了传统 CDN 的内容分发、DCDN 的全站加速，以及 DDoS 防护、WAF、Bot 管理、边缘计算等安全能力。相比前代产品，ESA 在全球节点覆盖、智能路由、安全原生防护和边缘 Serverless 能力上都有全面提升。

如果你此前使用的是阿里云 CDN 或 DCDN，阿里云官方已推荐将业务迁移至 ESA。ESA 与 DCDN、CDN 为相互独立的系统，你可以直接在 ESA 上重新部署站点并切换 DNS 解析生效，无需复杂的迁移操作。

CDN、DCDN 与 ESA 的区别

特别注意：请不要为 Halo 配置阿里云的 CDN 产品。传统 CDN 不支持 Halo 在使用的 DELETE 和 PATCH 等请求方式，会导致后台管理、文章保存、评论删除等操作失败。因此 Halo 站点至少需要使用支持动态加速的 DCDN 或 ESA。

对于 Halo 站点来说，接入阿里云 ESA 的主要收益是：

• 静态资源（图片、CSS、JS）由全球 3200+ 边缘节点就近响应，显著减少加载时间

• 动态请求通过 Anycast 智能路由和协议优化回源，降低访问延迟

• 原生集成 DDoS 和 WAF 防护，无需单独采购安全产品

• 源站真实 IP 被隐藏，降低被直接攻击的风险

• HTTPS 请求数不额外计费，更适合全站 HTTPS 的站点

准备工作

在开始之前，请确认以下条件已满足：

• Halo 站点正常运行：站点可以通过公网 IP 或已有域名正常访问

• 域名已完成 ICP 备案：在中国大陆节点加速要求域名已备案

• 已有阿里云账号并完成实名认证

添加站点并接入域名

1. 登录 ESA 控制台

访问 阿里云 ESA 控制台，首次使用需要开通服务。开通后点击添加站点。

2. 输入站点域名

填写你的 Halo 站点主域名（例如 example.com），点击下一步。

推荐输入主域名，然后在 DNS → 记录 中为需要加速的子域添加记录并开启代理加速。

3. 选择套餐

根据流量规模和功能需求选择合适的套餐：

• 基础版：适合个人博客或小型站点，按流量计费

• 标准版/高级版：适合中小型商业站点，包含更多安全规则和边缘计算额度

• 企业版：大型站点定制方案

选择后勾选服务协议，点击下一步完成站点创建。

4. 验证域名归属权

按照页面上的提示，在域名 DNS 服务商添加对应解析即可，配置完成之后，点击下方的 点击验证 按钮以测试是否配置正确。

5. 在 DNS 记录中添加加速域名

在 ESA 中，需要走边缘加速的具体子域名是在站点的 DNS → 记录 里添加的，而不是在单独的「域名管理」里新建一条站点外域名列表项。

1. 进入该站点左侧菜单 DNS → 记录，点击 添加记录。

2. 选择记录类型（常见为 A/AAAA 指向源站 IP，或由控制台引导选择 CNAME 等），填写主机记录（子域名前缀，如 www 或 demo）。

3. 打开 代理加速（代理状态为开启），这样该记录对应的访问流量才会经过 ESA 边缘网络；若关闭代理，则仅为普通 DNS 解析，不会获得加速与安全能力。

4. 填写记录值 / 源站（如服务器公网 IP 或源站域名）、回源协议建议选协议跟随；Halo 若未反代，回源端口一般为 8090，若前面已有 Nginx 反代到标准端口则按 80/443 填写。回源 Host 默认与请求 Host 一致即可，若有特殊回源需求可在 回源规则 中调整。

5. 向导中可能要求选择业务类型（如「网站页面」）、是否使用规则模板（缓存、压缩等）；对 Halo 可参考后文「边缘缓存规则」做一致或更细的调整。

6. 保存后，若使用 CNAME 接入，控制台会提示在域名解析服务商处添加 CNAME，把该子域名指向 ESA 给出的记录值；解析生效后访客才会真正从边缘访问。

配置 HTTPS

在站点左侧打开 SSL/TLS → 边缘证书，进入 证书管理 区域，为已在 DNS → 记录 中接入代理加速的域名配置证书：

1. 点击 申请免费证书：按向导选择主机名（需与已添加的加速子域名一致），由平台自动签发与续期（例如 Let's Encrypt 免费证书），适合大多数 Halo 站点。

2. 或点击 上传自定义证书：自行上传证书与私钥；需在到期前手动更新并重新上传。

证书与主机名绑定并生效后，该域名即可通过 HTTPS 访问。

证书配置完成后，前往 Halo 控制台将外部访问地址更新为 https:// 开头的地址（路径：控制台 → 概览 → 外部访问地址），否则页面中的静态资源链接可能仍生成 HTTP 地址，导致混合内容警告。

针对 Halo 的推荐配置

站点接入完成后，建议在 ESA 控制台中按以下说明调整配置，以获得更好的加速效果并确保 Halo 功能正常。

边缘缓存规则

进入 规则 → 缓存规则 页面，选择系统自动为我们创建的规则项，将 边缘缓存过期时间 选择为 优先遵循源站缓存策略（如果存在），否则不缓存。

将 查询字符串 选择为 全部保留

速度优化

在 速度和网络 → 优化 中可酌情开启：

• Gzip 压缩 / Brotli 压缩：自动压缩文本类资源，减少传输体积

• HTTP/2 和 HTTP/3 (QUIC)：提升现代浏览器的访问性能

验证是否生效

配置完成后，可以通过以下方式验证 ESA 是否正常工作：

1. 打开浏览器开发者工具，访问你的站点，在 Network 面板中查看静态资源的响应头；

2. 如果响应头中出现 x-site-cache-status 或 server: ESA 等阿里云特征头，说明资源已由边缘节点响应；

3. 使用 DNS Checker 验证域名解析是否已指向 ESA 节点。

配合页面缓存插件

在大多数情况下，CDN 对于静态资源通常有比较好的效果，但页面请求通常不会进行缓存，如果你期望对 Halo 的页面也在节点缓存，可以考虑配合静态页面缓存插件使用，详见：使用页面缓存插件优化 Halo 网站速度

在本地开发 Halo 插件时，需要让 Halo 以开发模式加载你的插件项目。建议先用官方脚手架生成工程，再任选下面两种运行方式之一。

使用脚手架创建插件项目

官方提供 create-halo-plugin 脚手架，可在本机快速生成带 Gradle、前端构建与 DevTools 集成的插件模板。

前提条件

• 已安装 Node.js（建议 LTS）与 pnpm

创建步骤

在终端执行：

pnpm create halo-plugin

按交互提示填写即可，常见字段含义如下：

• Plugin name：插件标识，只能包含小写字母、数字和连字符

• Domain：用于 Java 包名与 group 的包域，例如 com.example

• Author name：作者展示名

• Choose UI build tool：控制台前端构建工具，可选 Rsbuild 或 Vite

命令结束后会生成一个独立目录，使用编辑器打开该目录即可开始开发。

方式一：使用 Halo Gradle 插件（推荐）

通过上述脚手架创建的项目已集成 DevTools。在插件项目根目录执行 haloServer 任务时，Gradle 会拉起一个用于插件开发的 Halo 容器，并把当前工程作为插件挂载进去。

前提条件

• 已安装 Docker（并保证 Docker 守护进程正在运行）

  • macOS：推荐安装 OrbStack（轻量、启动快）或 Docker Desktop

  • Windows：推荐安装 Docker Desktop

  • Linux：参考 Docker 官方安装文档

• 已安装 JDK 21

  • macOS / Linux

    # 推荐使用 SDKMAN 管理 JDK 版本，如已安装可略过
    curl -s "https://get.sdkman.io" | bash
    
    # 安装 JDK 21
    sdk install java 21-tem

  • Windows

    前往 https://adoptium.net 下载 JDK 21 安装包，按向导安装即可。

步骤

在插件项目根目录执行：

 # macOS / Linux
 ./gradlew haloServer

 # Windows
 ./gradlew.bat haloServer

首次拉取镜像可能需要一些时间。启动成功后，控制台会打印默认访问地址与账号密码，例如：

 Halo 初始化成功，访问：http://localhost:8090/console
 用户名：admin
 密码：admin

浏览器打开控制台，在插件列表中应能看到当前插件已加载；修改代码后按 DevTools 文档说明进行热更新或重新构建即可。

该方式不需要在本机单独克隆、编译 Halo 主仓库，环境一致性好，适合绝大多数插件开发场景。

方式二：本地运行 Halo 源码并指定插件目录

当本机无法使用 Docker，或你需要同时调试 Halo 核心与插件行为时，可以在本地从源码启动 Halo，并通过配置把插件目录固定为开发路径。

前提条件

• 已按 Halo 开发环境运行 在本机成功运行 Halo 源码工程

• 已有一个可用的插件项目（通常由脚手架创建），且能通过 ./gradlew build 正常产出插件包

步骤

在插件项目中先完成一次构建：

 # macOS / Linux
 ./gradlew build

 # Windows
 ./gradlew.bat build

在 Halo 工程 application/src/main/resources 下创建或编辑 application-local.yaml，增加插件开发模式与固定路径（路径改为你的插件项目根目录的绝对路径）：

 halo:
   plugin:
     runtime-mode: development
     fixed-plugin-path:
       - /path/to/your-plugin-project

Windows 示例：

halo:
  plugin:
    runtime-mode: development
    fixed-plugin-path:
      - C:\path\to\your-plugin-project

在 Halo 仓库根目录启动（与官方文档中的 profile 保持一致）：

# macOS / Linux
./gradlew bootRun --args="--spring.profiles.active=dev,local"

# Windows
gradlew.bat bootRun --args="--spring.profiles.active=dev,win,local"

访问 http://localhost:8090/console，确认插件已出现在插件列表中且功能正常。

如何选择

更多关于 Halo 插件开发的文档可查阅：Halo 文档 - 插件开发

什么是七牛云全站加速（DCDN）？

七牛云 DCDN 是七牛云提供的一体化动态内容加速产品，覆盖国内外众多节点，支持静态加速、动态加速、HTTPS、缓存刷新等功能。相比传统 CDN 只能加速静态资源，DCDN 通过智能路由和私有协议优化，对动态请求（如页面动态内容）也有明显的加速效果，更适合 Halo 这类动静态内容混合的站点。

对于 Halo 站点来说，接入七牛云 DCDN 的主要收益是：

• 静态资源由就近节点直接响应，减少加载时间

• 动态请求通过优化链路回源，降低全球访问延迟

• 回源流量减少，降低源站带宽压力

• 源站真实 IP 被隐藏，降低被直接攻击的风险

准备工作

在开始之前，请确认以下条件已满足：

• Halo 站点正常运行：站点可以通过公网 IP 或已有域名正常访问

• 域名已完成 ICP 备案：在中国大陆节点加速要求域名已备案

• 已有七牛云账号并完成实名认证

添加加速域名

登录 七牛云控制台，进入全站加速 → 域名管理，点击添加域名

填写基本信息：

• 加速域名：填写需要加速的域名，例如 www.example.com

• 通信协议：先选择 HTTP，待域名创建完成后再到 HTTPS 配置中开启

• 覆盖范围：根据访客分布选择，国内用户为主选择中国大陆（域名需已备案）

• IP 协议：选择 IPv4/IPv6

填写源站配置：

• 源站配置：选择 IP 地址，填写服务器的公网 IP

• 回源 HOST：选择加速域名

• 回源协议：选择遵循请求协议

在缓存配置部分：

• 开启静态缓存规则，点击使用推荐配置，系统会自动填充常见静态资源的缓存规则，例如图片缓存 1 天、视频文件缓存 7 天等

• 缓存参数：选择保留所有参数

点击创建，页面会跳转到域名详情，提示需要完成域名所有权验证。

域名所有权验证

创建域名后，七牛云会要求验证域名归属权，以防止恶意接入他人域名。验证方式为 DNS 解析验证：

1. 在弹出的域名所有权验证面板中，可以看到需要添加的 TXT 记录：

   记录类型	主机记录	记录值
   TXT	verification	verify_xxxxxxxxxx

2. 前往你的 DNS 服务商，添加上述 TXT 记录；

3. 记录添加完成后，回到七牛云控制台，点击点击验证完成验证；

4. 验证通过后，再根据提示配置 CNAME 记录以正式启用 CDN 服务。

配置 CNAME

1. 域名创建后，在域名详情页的基本信息中可以找到系统分配的 CNAME 地址；

2. 前往你的 DNS 服务商，为加速域名添加一条 CNAME 记录，记录值填入上述 CNAME 地址；

3. 等待 DNS 解析生效（通常几分钟内完成）。

申请 SSL 证书

如果你还没有 SSL 证书，可以在七牛云证书服务中申请免费证书：

1. 进入 七牛云证书管理，点击购买证书；

2. 证书品牌选择 TrustAsia，证书种类选择 DV 免费域名型，费用为 ¥0.00，点击核对信息并支付；

3. 在补全信息页面中填写：

   • 域名：填写需要申请证书的加速域名

   • 证书备注名：可与域名保持一致，方便识别

   • 域名所有权验证方式：选择 DNS 验证

   • 加密算法：选择 RSA

4. 按照页面提示，在 DNS 服务商添加指定的 TXT 记录完成域名验证，证书签发后即可使用。

配置 HTTPS

1. 在域名详情页找到 HTTPS 配置，点击修改，打开配置面板；

2. 开启 HTTPS，在已有证书标签下选择之前申请的免费证书；

   如未提前申请，可点击页面中的七牛云证书服务链接，前往申请后再回来绑定。

3. 根据需要开启以下选项：

   • 强制 HTTPS：开启后所有 HTTP 请求将自动跳转到 HTTPS

   • HTTP/2 访问：开启可提升 HTTPS 下的访问性能

4. 点击确定保存配置；

5. 证书配置完成后，同步在 Halo 控制台将外部访问地址更新为 https:// 开头（路径：控制台 → 概览 → 外部访问地址）。

验证是否生效

配置完成后，可以通过以下方式验证：

1. 打开浏览器开发者工具，访问你的站点，在 Network 面板中查看静态资源的响应头；

2. 如果响应头中出现 x-dsa-trace-id 或 server: volc-dcdn，说明资源已由边缘节点响应；

3. 使用 DNS Checker 验证域名解析是否已指向 CDN 节点。

配合页面缓存插件

在大多数情况下，CDN 对于静态资源通常有比较好的效果，但页面请求通常不会进行缓存，如果你期望对 Halo 的页面也在节点缓存，可以考虑配合静态页面缓存插件使用，详见：使用页面缓存插件优化 Halo 网站速度

Halo 提供了两种方式批量更新已安装的主题和插件，无需逐个手动操作。

方式一：通过应用市场插件

安装最新版本的应用市场插件后，控制台中会新增应用市场模块，其中包含更新应用页面。

1. 在控制台菜单中点击应用市场，进入更新应用页面；

2. 页面会列出所有当前有可用更新的主题和插件；

3. 可以逐个点击更新，也可以点击页面右上角的全部更新按钮，一键完成所有更新。

这种方式操作直观，适合日常维护使用。

方式二：通过 Halo CLI

Halo CLI 支持通过命令行批量升级主题和插件，适合熟悉命令行操作或需要在脚本中自动化更新的场景。

升级所有插件：

halo plugin upgrade --all

升级所有主题：

halo theme upgrade --all

如果只需要升级某个特定的主题或插件，也可以指定名称：

halo plugin upgrade <plugin-name>
halo theme upgrade <theme-name>

关于 Halo CLI 的安装和配置，请参考 Halo CLI 文档。

什么是又拍云 CDN？

又拍云 是一家以 CDN 为核心业务的云服务商，提供静态加速、动态加速、全站加速、图片处理等服务。又拍云价格相对实惠，提供流量包计费方式，对于中小型站点较为友好。

对于 Halo 站点来说，接入又拍云 CDN 的主要收益是：

• 静态资源由就近节点直接响应，减少加载时间

• 回源流量减少，降低源站带宽压力

• 源站真实 IP 被隐藏，降低被直接攻击的风险

准备工作

在开始之前，请确认以下条件已满足：

• Halo 站点正常运行：站点可以通过公网 IP 或已有域名正常访问

• 域名已完成 ICP 备案：在中国大陆节点加速要求域名已备案

• 已有又拍云账号并完成实名认证

创建服务并绑定域名

登录 又拍云控制台，进入 CDN 加速 → 服务管理，点击创建服务

填写服务名称和加速域名后，如果该域名尚未在又拍云验证过归属权，页面会提示需要先完成 DNS 验证：

• 前往你的 DNS 服务商，添加一条 TXT 记录：

  • 主机记录：upyun-verify

  • 记录类型：TXT

  • 记录值：页面上显示的验证值

• 添加完成后，点击验证，通过后即可继续创建服务。

继续填写以下配置：

• 应用场景：选择全站加速（兼顾动静态内容）

• 源站设置：

  • 回源协议：选择 HTTP 或 HTTPS

  • 线路配置：填写服务器公网 IP 地址和端口号，如果你服务器没有配置 Nginx 反向代理，可以直接填写 Halo 服务的端口号，如果已经配置过 Nginx 反向代理和 SSL 证书，那么可以选择协议跟随

点击确定创建，系统会为该服务分配一个 CNAME 地址：

前往你的 DNS 服务商，为加速域名添加一条 CNAME 记录，记录值为上一步分配的 CNAME 地址，等待解析生效。

配置 HTTPS

进入功能配置，切换到 HTTPS 标签

你可以选择 添加自有证书 或者去证书管理页面申请免费证书，如需申请免费证书，可在 证书管理 中申请 Let's Encrypt 免费证书，申请完成后回到此处绑定。

开启强制 HTTPS，将所有 HTTP 请求重定向到 HTTPS

证书配置完成后，同步更新 Halo 控制台的外部访问地址为 https:// 开头（路径：控制台 → 概览 → 外部访问地址）。

针对 Halo 的推荐配置

参数跟随

进入 功能配置 → 缓存控制 页面：

将参数跟随设置为全程跟随。Halo 的部分请求（API、附件下载等）依赖 URL 中 ? 后的查询参数，全程跟随可以确保这些参数完整传递到源站，避免请求异常。

重定向跟随

进入 功能配置 → 性能优化 页面：

保持关闭状态。Halo 自身会处理必要的跳转逻辑，如果 CDN 节点在回源时自动跟随重定向，可能会导致跳转行为异常，建议不要开启。

验证是否生效

配置完成后，可以通过以下方式验证：

1. 打开浏览器开发者工具，访问你的站点，在 Network 面板中查看静态资源的响应头；

2. 如果响应头中出现 x-request-id 或 server: marco/3.2 等又拍云特征头，说明资源已由边缘节点响应；

3. 使用 DNS Checker 验证域名解析是否已指向 CDN 节点。

配合页面缓存插件

在大多数情况下，CDN 对于静态资源通常有比较好的效果，但页面请求通常不会进行缓存，如果你期望对 Halo 的页面也在节点缓存，可以考虑配合静态页面缓存插件使用，详见：使用页面缓存插件优化 Halo 网站速度

什么是腾讯云 EdgeOne？

腾讯云 EdgeOne（边缘安全加速平台 EO）是腾讯云推出的一体化边缘安全加速平台，将 CDN 加速、DDoS 防护、WAF、Bot 管理、边缘函数等能力集成在同一平台中，无需多个产品叠加使用。

对于 Halo 站点来说，接入 EdgeOne 的主要收益是：

• 静态资源（图片、CSS、JS）由就近的边缘节点直接响应，减少加载时间

• 回源流量减少，降低源站带宽压力

• 源站真实 IP 被隐藏，降低源站遭受直接攻击的风险

• 无需单独采购 DDoS 防护和 WAF，安全与加速一体化

准备工作

在开始之前，请确认以下条件已满足：

• Halo 站点正常运行：站点可以通过公网 IP 或已有域名正常访问

• 域名已完成 ICP 备案：接入中国大陆节点要求域名在工信部完成备案，若只接入海外节点则不要求

• 已有腾讯云账号并完成实名认证

在 EdgeOne 添加站点并接入

1. 登录 EdgeOne 控制台

访问 边缘安全加速平台 EO 控制台，首次使用时会进入场景选择页面，点击添加站点。

2. 填写站点域名

输入你的 Halo 站点的主域名（例如 example.com），点击开始接入。

3. 选择套餐

根据你的流量规模和功能需求选择合适的套餐。个人博客或小型站点可以从个人版开始，按需升级。选择后勾选服务协议，点击下一步。

4. 选择加速区域和接入模式

加速区域

根据你的访客主要分布地区选择对应的加速区域。

接入模式

• 如果你的域名和 DNS 服务都在腾讯云，推荐使用 NS 接入：EdgeOne 可以直接读取现有 DNS 记录并一键导入，后续新增域名、开启加速也最为方便；

• 如果域名托管在其他服务商（如阿里云、Cloudflare 等），推荐使用 CNAME 接入：保留原有 DNS 服务商，只需在每个加速域名下添加一条 CNAME 记录指向 EdgeOne 分配的地址即可。

5. 添加加速域名

站点创建完成后，进入 域名服务 → 域名管理，点击添加域名，按以下说明填写配置：

域名配置

• 加速域名：填写子域名部分，例如填写 www 即对应 www.example.com

回源配置

• 源站配置：选择 IP/域名，填写你的服务器公网 IP 地址

• 回源协议：选择协议跟随，EdgeOne 会根据访客请求协议自动选择回源方式

• 回源端口：Halo 默认为 8090，如果已通过 Nginx 反代到标准端口，HTTP 填 80，HTTPS 填 443

• 回源 HOST 头：选择使用加速域名

推荐模版

选择不使用模版，后续我们会在"针对 Halo 的推荐配置"章节中手动配置各项参数。

填写完成后点击下一步，EdgeOne 会展示需要在你的 DNS 服务商处添加的 CNAME 记录：

• 主机记录：你填写的子域名，例如 www

• 记录类型：CNAME

• 记录值：EdgeOne 分配的 CNAME 地址

前往你的域名解析服务商，按照上述信息添加 CNAME 记录后，点击完成即可。解析生效后，访客流量将自动经由 EdgeOne 节点加速。

6. 配置 HTTPS

EdgeOne 支持为加速域名自动申请和部署免费 HTTPS 证书，无需手动操作。

进入 域名服务 → 域名管理，在域名列表中找到对应域名，点击 HTTPS 配置 列下的配置按钮：

1. 配置方式选择申请免费证书（推荐），验证方式选择自动验证；

2. 点击保存，EdgeOne 会自动申请证书并完成部署，证书到期前会自动续期。

注意：申请证书前需要确保域名的 CNAME 解析已生效，否则验证无法通过。证书申请期间，域名的 HTTPS 访问可能短暂不可用。

如果你已有自己的 SSL 证书，可以选择使用 SSL 托管证书，上传后绑定即可。

证书配置完成后，还需要在 Halo 控制台将外部访问地址更新为 https:// 开头的地址（路径：控制台 → 概览 → 外部访问地址），否则页面中的静态资源链接仍会生成 HTTP 地址，导致混合内容警告。

最终，当域名列表中的状态为 已部署 时，就可以尝试通过域名访问网站了，如果能正常访问，那么代表配置成功。

针对 Halo 的推荐配置

站点接入完成后，建议在 加速与安全 → 站点加速 中按以下说明调整配置，以获得更好的加速效果并确保 Halo 功能正常。

节点缓存 TTL

设置为遵循源站 Cache-Control，Halo 会为各个请求设置合理的 Cache-Control，通常无需自行设置。此外，如果请求没有 Cache-Control 头，推荐设置为不缓存。

浏览器缓存 TTL

设置为遵循源站 Cache-Control。Halo 会为静态资源设置合理的缓存头，EdgeOne 遵循这些设置可以避免缓存策略冲突。

查询字符串

设置为全部保留。Halo 的部分请求（如附件下载、API 请求）依赖 URL 中的查询参数，全部保留可以避免因参数被丢弃导致请求异常。

强制 HTTPS

开启后，所有 HTTP 请求会被自动重定向到 HTTPS。建议在 HTTPS 证书配置完成后开启，重定向方式选择 302 即可。

客户端 IP 头部

开启后，EdgeOne 会将访客的真实 IP 通过请求头传递给源站。头部名称设置为 X-Real-IP，这样 Halo 才能正确记录访客的真实 IP 地址，而不是 EdgeOne 节点的 IP。

图片处理（可选）

EdgeOne 提供两个图片优化功能，可在 多媒体服务 → 图片处理 中开启：

• 图片瘦身优化：自动压缩图片体积，默认质量为 75%，几乎不影响视觉效果，可有效提升图片加载速度

• 智能格式压缩：自动将图片转换为 WebP 或 AVIF 格式，体积更小，浏览器会按支持情况自动适配

这两项功能均为按量付费，按图片处理次数计费（0.1 元/千次），图片流量较大的站点建议先评估成本再决定是否开启。详细计费说明可参考媒体处理费用。

验证是否生效

配置完成后，可以通过以下方式验证 CDN 是否正常工作：

1. 打开浏览器开发者工具，访问你的站点，在 Network 面板中查看静态资源的响应头；

2. 如果看到类似 server: TencentEdgeOne 或 eo-cache-status: HIT 的响应头，说明资源已由 EdgeOne 代理；

3. 也可以使用 DNS Checker 验证域名解析是否已指向 EdgeOne 节点。

配合页面缓存插件

在大多数情况下，CDN 对于静态资源通常有比较好的效果，但页面请求通常不会进行缓存，如果你期望对 Halo 的页面也在节点缓存，可以考虑配合静态页面缓存插件使用，详见：使用页面缓存插件优化 Halo 网站速度

如何定位问题

在开始排查之前，建议先打开浏览器的开发者工具（按 F12 或右键 → 检查），切换到 Network 标签页，刷新页面后查看各请求的耗时情况。重点关注：

• 哪个请求耗时最长？

• 是 HTML 文档本身加载慢，还是图片、JS、CSS 等静态资源加载慢？

• 是所有资源都慢，还是个别资源特别慢？

根据慢在哪里，再对照下方的可能原因进行针对性排查。

可能的原因与解决办法

服务器带宽不足

这是最常见的原因之一。许多云服务商的入门套餐带宽只有 1Mbps，在这种配置下，一张未经压缩的高清图片就可能占满带宽，导致整个页面加载缓慢。

表现：页面所有资源加载都慢，Network 面板中请求队列很长。

解决办法：

• 升级服务器带宽，一般 3Mbps 以上即可满足日常网站需求；

• 如果暂时无法升级，通过 CDN 加速来缓解带宽压力（见下方"使用 CDN 加速"部分）。

服务器地理位置距离访客太远

服务器地区与访客所在地越远，网络延迟越高，页面首字节时间（TTFB）越长。

表现：Network 面板中 HTML 文档的等待时间（Waiting）较长，但下载时间正常。

解决办法：

• 更换到离目标访客更近的机房；

• 如果访客分布在多个地区，可以考虑使用 CDN 将静态资源分发到各地节点。

图片体积过大

图片通常是页面体积最大的部分，未经优化的图片会显著拖慢加载速度。

表现：Network 面板中图片请求耗时长、传输体积大（单张几百 KB 甚至几 MB）。

解决办法：

• 上传图片前先进行无损压缩，推荐使用 Squoosh 或 TinyPNG；

• 配置 WebP 图片转换服务，WebP 格式相比 JPG/PNG 体积更小、质量相当，可参考 优雅的让 Halo 支持 webp 图片输出；

• 尽量避免在文章中直接粘贴未压缩的原始截图。

主题引用了不稳定的第三方 CDN

部分主题的 CSS、JS 或字体文件托管在公共 CDN（如 jsDelivr、cdnjs、Google Fonts 等），当这些 CDN 在某些网络环境下访问缓慢或不稳定时，整个页面的渲染会被阻塞。

表现：Network 面板中某个来自第三方域名的资源（如 fonts.googleapis.com、cdn.jsdelivr.net）长时间挂起。

解决办法：

• 将该资源下载到本地，托管在自己的服务器上；

• 换用在国内访问更稳定的 CDN 节点；

• 如果是字体文件导致的，可以考虑改用系统字体或自托管字体。

未启用 Nginx Gzip 压缩

如果未启用 Gzip 压缩，HTML、CSS、JS 等文本资源会以原始大小传输，增加传输时间。

表现：Network 面板中文本资源的传输体积与原始大小相近，没有明显的压缩比。

解决办法：在 Nginx 配置中启用 Gzip：

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml image/svg+xml;
gzip_min_length 1024;

未配置浏览器缓存

静态资源（图片、CSS、JS）如果没有设置合理的缓存头，用户每次访问都需要重新下载，造成不必要的重复请求。

表现：反复访问同一页面时，Network 面板中静态资源仍然是 200 状态而非 304 或 from cache。

解决办法：在 Nginx 中为静态资源设置缓存：

location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff2)$ {
    expires 30d;
    add_header Cache-Control "public, no-transform";
}

服务器资源不足（CPU / 内存）

当服务器 CPU 或内存使用率长期处于高位时，Halo 的响应速度也会受到影响，尤其是在并发请求较多的情况下。

表现：TTFB 偏高，服务器日志中出现请求超时或响应慢的记录。

解决办法：

• 通过 top 或 htop 查看服务器资源占用情况；

• 适当调整 Halo 的 JVM 参数（-Xmx / -Xms），避免内存设置过低或过高；

• 如果资源持续紧张，考虑升级服务器配置。

DNS 解析速度慢

DNS 解析是浏览器访问网站的第一步，如果 DNS 服务商响应慢，也会影响整体加载体验。

表现：Network 面板中请求的 DNS Lookup 阶段耗时较长。

解决办法：

• 更换响应速度更快的 DNS 服务商（如 DNSPod、阿里云 DNS）；

• 启用 DNS 预解析，在页面 <head> 中添加 <link rel="dns-prefetch" href="//your-cdn-domain.com">。

插件或主题引入了过多的 JS / CSS

每个启用的插件都可能向页面注入额外的 JS 和 CSS 文件，插件数量越多，页面需要加载的资源也越多。部分插件即使功能用不上，只要处于启用状态就会在前台页面加载相关资源，拖慢整体速度。

表现：Network 面板中出现大量来自 /plugins/ 路径的资源请求，或页面总请求数明显偏多。

解决办法：

• 不需要的插件及时关闭或卸载，而不是仅仅停用功能；

• 检查已启用的插件是否都在实际使用，按需保留；

• 主题自身引入的 JS / CSS 较多时，可以联系主题作者或自行优化，去除不必要的依赖。

使用 CDN 加速

如果以上单项优化仍无法满足需求，可以考虑接入全站 CDN 加速。CDN 会将静态资源缓存到各地节点，访客就近获取资源，从根本上解决因服务器地区或带宽不足导致的加载问题。

国内常见的 CDN 服务商有阿里云 CDN、腾讯云 CDN、又拍云等，配置时通常需要将域名的 CNAME 指向 CDN 提供的接入地址，具体可参考各服务商的接入文档。

• 腾讯云 EdgeOne 接入 Halo 配置指南

• 又拍云 CDN 接入 Halo 配置指南

• 七牛云 DCDN 接入 Halo 配置指南

• 阿里云 ESA 接入 Halo 配置指南

概览

Halo 支持通过内容助手插件将 Word 文档（.doc、.docx）直接导入为文章，导入时会自动提取文档内容并将文档中的图片上传到 Halo 附件，适合从 Word 迁移内容或批量发布已有文档的场景。

安装内容助手插件

前往应用市场安装内容助手插件，安装方式可参考插件安装文档。

导入 Word 文档

1. 登录 Halo 控制台，进入 工具 → 文章导入；

2. 选择 Word（.docx） 导入 选项卡；

3. 上传一个或多个 Word 文件（支持批量选择）；

4. 确认后，插件会自动将每个文档转换为一篇文章，文档中引用的图片会同步上传到 Halo 附件并替换为对应的链接。

注意事项

• 导入时会尽量保留 Word 文档的格式，但部分复杂排版（如多栏布局、艺术字等）可能无法完整还原，建议导入后检查一遍内容；

• 文档中嵌入的图片会自动上传，但通过链接引用的外部图片不会被处理；

• 如果需要导入 Markdown 文件，同样可以在 工具 → 文章导入 中切换格式进行操作。

随着 Halo 站点内容越来越丰富，许多站长会面临一个问题：博客列表页适合展示时效性内容，但对于产品文档、使用教程、常见问题等结构化知识内容来说，用普通博客列表来组织显得太扁平，用户很难快速找到自己需要的内容。

本文介绍如何利用 Halo 的自定义分类模板机制，在不依赖任何额外插件的情况下，为主题添加一套完整的知识库页面，包括知识库入口和子分类文章列表。

实现原理

Halo 支持在 theme.yaml 中为分类（category）注册额外的渲染模板，称为 自定义分类模板。用户在后台管理某个分类时，可以从下拉菜单中选择使用哪套模板来渲染该分类页面。

知识库的层级结构正好与分类树对应：

知识库根分类（使用 category_knowledge_base_root 模板）
├── 入门指南（使用 category_knowledge_base 模板）
│   ├── 文章 A
│   └── 文章 B
└── 进阶使用（使用 category_knowledge_base 模板）
    ├── 文章 C
    └── 文章 D

第一步：在 theme.yaml 注册模板

在 theme.yaml 的 spec.customTemplates 下注册模板：

spec:
  customTemplates:
    post:
      - name: 知识库
        description: 知识库文章页
        file: post_knowledge_base.html
    category:
      - name: 知识库入口
        description: 知识库入口页，展示所有子分类及文章预览
        file: category_knowledge_base_root.html
      - name: 知识库
        description: 知识库子分类，展示该分类下的文章列表
        file: category_knowledge_base.html

修改完 theme.yaml 后，需要在后台 主题 → 重载主题配置 才能生效。之后在分类设置中就能看到这些模板选项。

第二步：知识库入口页

模板名称：category_knowledge_base_root.html

入口页负责展示整个知识库的全貌：标题、描述、搜索入口，以及所有子分类的卡片网格。

核心 API

• categoryFinder.getByNames(category.spec.children) — 根据父分类的 children 字段获取子分类列表

• postFinder.listByCategory(1, 5, subCat.metadata.name) — 获取每个子分类的前 5 篇文章

<!-- Hero 区域：展示知识库标题、描述和搜索入口 -->
<section class="hero">
  <h1 th:text="${category.spec.displayName}"></h1>
  <p
    th:text="${category.spec.description ?: '快速查找所需内容，轻松解决每一个问题。'}"
  ></p>

  <!-- 搜索按钮（需安装 PluginSearchWidget） -->
  <button
    th:if="${pluginFinder.available('PluginSearchWidget')}"
    onclick="javascript: SearchWidget.open();"
    type="button"
  >
    搜索文章...
  </button>
</section>

<!-- 子分类宫格 -->
<section class="kb-grid-section">
  <th:block
    th:with="subCategories = ${categoryFinder.getByNames(category.spec.children)}"
  >
    <div class="kb-grid">
      <th:block th:each="subCat : ${subCategories}">
        <div
          th:with="subPosts = ${postFinder.listByCategory(1, 5, subCat.metadata.name)}"
          class="kb-card"
        >
          <!-- 卡片头部：图标 + 名称 + 文章数 -->
          <a th:href="@{${subCat.status.permalink}}" class="kb-card-header">
            <img
              th:unless="${#strings.isEmpty(subCat.spec.cover)}"
              th:src="${subCat.spec.cover}"
            />
            <h2 th:text="${subCat.spec.displayName}"></h2>
            <span th:text="|${subCat.postCount} 篇文章|"></span>
          </a>
          <!-- 文章预览列表 -->
          <ul class="kb-article-list">
            <li th:each="post : ${subPosts.items}">
              <a
                th:href="@{${post.status.permalink}}"
                th:text="${post.spec.title}"
              ></a>
            </li>
            <li th:if="${subPosts.total > 5}">
              <a
                th:href="@{${subCat.status.permalink}}"
                th:text="|查看全部 ${subPosts.total} 篇 →|"
              ></a>
            </li>
          </ul>
        </div>
      </th:block>
    </div>
  </th:block>
</section>

有两处值得注意：搜索按钮通过 pluginFinder.available('PluginSearchWidget') 判断是否安装了搜索插件，安装了才渲染，点击后调用 SearchWidget.open() 打开全站搜索弹窗；子分类的图标直接使用了 category.spec.cover，可以在后台为每个子分类上传一张图标图片。

第三步：子分类文章列表页

模板名称：category_knowledge_base.html

该模板使用分类模板的标准变量 category（当前分类信息）和 posts（分页文章列表），展示当前子分类下的所有文章。

面包屑导航

利用 categoryFinder.getBreadcrumbs(category.metadata.name) 自动生成完整路径，无需手动维护层级关系：

<nav
  th:with="breadcrumbs = ${categoryFinder.getBreadcrumbs(category.metadata.name)}"
>
  <ol>
    <li><a href="/">首页</a></li>
    <li th:each="bc, stats : ${breadcrumbs}">
      <a
        th:unless="${stats.last}"
        th:href="@{${bc.status.permalink}}"
        th:text="${bc.spec.displayName}"
      ></a>
      <span
        th:if="${stats.last}"
        th:text="${bc.spec.displayName}"
        aria-current="page"
      ></span>
    </li>
  </ol>
</nav>

文章列表

文章列表不显示封面，只展示标题和发布日期，保持知识库的专注感：

<ul class="post-list">
  <li th:each="post : ${posts.items}">
    <a th:href="@{${post.status.permalink}}" th:text="${post.spec.title}"></a>
    <time th:text="${#dates.format(post.spec.publishTime, 'yyyy-MM-dd')}"></time>
  </li>
</ul>

<nav th:if="${posts.hasPrevious() || posts.hasNext()}">
  <a
    th:href="@{${posts.prevUrl}}"
    th:classappend="${!posts.hasPrevious() ? 'disabled' : ''}"
    rel="prev"
    >
    上一页
  </a>
  <span th:text="|${posts.page} / ${posts.totalPages}|"></span>
  <a
    th:href="@{${posts.nextUrl}}"
    th:classappend="${!posts.hasNext() ? 'disabled' : ''}"
    rel="next"
    >
  下一页
  </a>
</nav>

第四步：知识库文章页

模板名称：post_knowledge_base.html

这一步并非必须。如果你希望知识库的文章和其他文章样式不同（比如去掉封面图、简化作者信息、侧边栏只保留目录），可以单独新建一个文章模板 post_knowledge_base.html。

文章模板同样可以使用 categoryFinder.getBreadcrumbs 来生成面包屑，只需从文章的第一个分类开始反查路径：

<th:block
  th:unless="${#lists.isEmpty(post.categories)}"
  th:with="breadcrumbs = ${categoryFinder.getBreadcrumbs(post.categories[0].metadata.name)}"
>
  <!-- 面包屑结构同上 -->
</th:block>

在 Halo 后台配置

完成模板开发后，在 Halo 后台按以下步骤配置：

新建知识库根分类：自定义模板选择「知识库入口」，如果你为知识库的文章单独新建了文章模板，还可以在此处设置自定义文章模板为「知识库」。另外建议勾选在列表中隐藏，勾选之后该分类下的文章将不会出现在博客归档、首页文章列表等公共列表中，相当于把知识库内容从博客流中独立出来。

新建子分类：在根分类下新建若干子分类（如「入门指南」「常见问题」），自定义模板选择「知识库」。日后发布文章时只需勾选对应子分类即可自动归入知识库体系。

总结

整套知识库功能完全基于 Halo 现有机制实现，无需额外插件：

这种「模板即功能」的思路在 Halo 主题开发中非常实用，同样可以用来做产品发布页、案例展示页等差异化内容区域。

什么是 Rybbit？

Rybbit 是一款开源的现代化网站分析工具，定位为 Google Analytics 的隐私友好替代方案。除了基础的页面浏览量、访客数、来源渠道等统计之外，Rybbit 还提供了会话回放、漏斗分析、用户旅程、留存分析、错误追踪等进阶功能，数据展示更加直观，适合对流量分析有较高要求的站点。

相比 Google Analytics，Rybbit 有以下几个优势：

• 隐私友好：不使用 Cookie，不收集个人身份信息，符合 GDPR 等隐私法规

• 开源可自托管：数据完全掌握在自己手中

• 功能丰富：会话回放、漏斗、用户旅程、留存分析等进阶功能开箱即用

• 实时仪表盘：实时查看当前在线访客和页面浏览情况

• 界面现代：交互体验比 GA4 更加直观

查看在线演示

部署 Rybbit

方式一：使用 Rybbit Cloud

如果不想自行维护服务器，可以直接使用 Rybbit Cloud。Rybbit Cloud 提供 7 天免费试用，之后需要按需订阅，可以根据实际的月页面浏览量和功能需求选择合适的套餐。

注册账号后即可直接使用，无需任何部署操作。

方式二：自托管

使用一键安装脚本（推荐新服务器）

如果你打算为 Rybbit 单独准备一台服务器，推荐使用官方提供的一键安装脚本。该脚本会自动配置好 Docker 容器、Caddy 反向代理和 HTTPS 证书，无需手动操作。

前提条件

• 一台至少 2GB 内存的服务器（推荐 Ubuntu 24 LTS）

• 一个已解析到该服务器 IP 的域名或子域名（HTTPS 是必须的，否则浏览器会拦截追踪脚本）

安装步骤

1. 安装 Docker Engine，参考 Docker 官方文档

2. 克隆 Rybbit 仓库

    git clone https://github.com/rybbit-io/rybbit.git
    cd rybbit

3. 赋予脚本执行权限

    chmod +x *.sh

4. 运行安装脚本，将 your.domain.name 替换为你的域名

    ./setup.sh your.domain.name

   脚本会自动生成配置、启动容器，并由 Caddy 自动申请 SSL 证书，首次运行需要几分钟时间。

5. 等待 DNS 解析生效后，访问 https://your.domain.name/signup 创建管理员账号即可开始使用。

使用已有的反向代理服务器

如果你的服务器上已经运行了 Nginx 等反向代理，可以在启动 Rybbit 时跳过内置的 Caddy，自行配置反向代理。

启动 Rybbit（禁用内置 Web 服务器）

./setup.sh your.domain.name --no-webserver

此命令会暴露两个端口：

• 3001：后端 API 服务

• 3002：前端客户端

Nginx 配置示例

server {
    listen 80;
    server_name your.domain.name;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your.domain.name;

    ssl_certificate /etc/letsencrypt/live/your.domain.name/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your.domain.name/privkey.pem;

    location /api/ {
        proxy_pass http://localhost:3001;
        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;
    }

    location / {
        proxy_pass http://localhost:3002;
        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;
    }
}

在 Rybbit 中创建监控网站

登录 Rybbit 控制台，首次访问会先注册，然后提示新增一个网站和组织：

创建完成之后，页面会提供一段类似于下面形式的代码：

<script
    src="https://<your-domain>/api/script.js"
    data-site-id="078bd4c1f97d"
    defer
></script>

复制这段代码，接下来将其配置到 Halo 中。

在 Halo 中配置追踪代码

登录 Halo 控制台，进入 设置 → 代码注入，将复制的追踪代码粘贴到 页脚代码 输入框中：

保存后，访问你的站点任意页面，回到 Rybbit 控制台即可看到实时数据。

参考：

1. https://rybbit.com/zh/docs/self-hosting

2. https://rybbit.com/zh/docs/self-hosting-guides/custom-nginx

什么是 Umami？

Umami 是一款开源的网站访问统计工具，可以收集页面浏览量、访客数、来源渠道、设备信息、地理位置等数据，帮助你了解站点的真实流量情况。

相比 Google Analytics，Umami 有以下几个优势：

• 隐私友好：不使用 Cookie，不收集个人身份信息，符合 GDPR 等隐私法规

• 轻量：追踪脚本体积极小，对页面加载速度几乎没有影响

• 开源可自托管：数据完全掌握在自己手中，不依赖第三方服务

• 界面简洁：数据展示直观，核心指标一目了然

部署 Umami

方式一：使用 Umami Cloud

如果不想自行维护服务器，可以直接使用 Umami Cloud。Umami Cloud 提供免费套餐，支持最多 3 个网站和每月 10 万次页面浏览，对于个人博客或小型站点通常已经足够。

注册账号后即可直接使用，无需任何部署操作。

方式二：使用 Docker Compose 自托管

如果希望将数据托管在自己的服务器上，可以使用 Docker Compose 部署 Umami。

前提条件：服务器已安装 Docker 和 Docker Compose。

1. 创建工作目录

    mkdir ~/umami && cd ~/umami

2. 创建 docker-compose.yaml

   # 来源于 https://github.com/umami-software/umami/blob/master/docker-compose.yml
   services:
     umami:
       image: ghcr.io/umami-software/umami:latest
       ports:
         - "3000:3000"
       environment:
         DATABASE_URL: postgresql://umami:umami@db:5432/umami
         APP_SECRET: replace-me-with-a-random-string
       depends_on:
         db:
           condition: service_healthy
       init: true
       restart: always
       healthcheck:
         test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
         interval: 5s
         timeout: 5s
         retries: 5
     db:
       image: postgres:15-alpine
       environment:
         POSTGRES_DB: umami
         POSTGRES_USER: umami
         POSTGRES_PASSWORD: umami
       volumes:
         - umami-db-data:/var/lib/postgresql/data
       restart: always
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
         interval: 5s
         timeout: 5s
         retries: 5
   volumes:
     umami-db-data:

   注意：请将 APP_SECRET 替换为一个随机字符串，可以使用 openssl rand -hex 32 生成。

3. 启动服务

    docker compose up -d

   启动后，Umami 默认运行在 http://服务器IP:3000。默认登录账号为 admin，密码为 umami，请登录后立即修改密码。

4. 配置 Nginx 反向代理

   如果需要通过域名访问，可以配置 Nginx 反向代理：

   配置好域名解析和 HTTPS 证书后，即可通过域名访问 Umami 控制台。

方式三：通过 1Panel 安装

如果你的服务器使用了 1Panel 面板，可以在 应用商店 中搜索 Umami 并按照引导一键安装，无需手动编写配置文件，1Panel 会自动完成数据库和容器的初始化。

在 Umami 中创建监控网站

登录 Umami 控制台，进入 设置 → 网站，点击 添加网站：

填写网站名称和域名，保存后点击页面右上角的 编辑 按钮，进入编辑页面之后可以看到一段 跟踪代码，复制这段代码，接下来将其配置到 Halo 中。

在 Halo 中配置追踪代码

登录 Halo 控制台，进入 设置 → 代码注入，将复制的追踪代码粘贴到 全局 head 标签 输入框中：

保存后，访问你的站点任意页面，回到 Umami 控制台即可看到实时数据。

配置完成后，Umami 会开始记录你的站点访问数据，包括页面浏览量、访客数、访问来源、设备类型等，你可以在 Umami 控制台的仪表盘中查看完整的统计报告。

概览

Halo 默认使用富文本编辑器，但提供了多种途径让你以 Markdown 的方式撰写和发布内容。无论你是偶尔需要插入一段 Markdown 片段，还是希望将整个写作流程留在本地编辑器中，都可以找到合适的方案。

方式一：安装 Markdown 编辑器插件

应用市场提供了多款 Markdown 编辑器插件，安装后可以在控制台直接使用 Markdown 编辑器撰写和发布文章，体验与本地 Markdown 编辑器类似。

前往应用市场浏览所有 Markdown 相关插件：应用市场 - Markdown 插件

方式二：在默认编辑器中插入 Markdown 块

如果你大部分时候使用富文本编辑器，只是偶尔需要用 Markdown 语法写某一段内容，可以安装 Markdown / HTML 内容块插件。

安装后，在默认编辑器中可以插入一个独立的 Markdown 块，该块内支持完整的 Markdown 语法，与富文本内容混排。适合以下场景：

• 在富文本文章中插入代码示例或技术说明

• 临时使用 Markdown 语法，无需切换整个编辑器

• 保留部分已有富文本内容，同时用 Markdown 补充新段落

在应用市场搜索 Markdown 内容块 即可安装。

方式三：通过内容助手批量导入 Markdown 文件

内容助手插件支持将本地的 Markdown 文件（包括 .md 文件关联的图片资源）批量导入到 Halo，适合从其他平台迁移内容，或者有大量本地 Markdown 文章需要一次性上传的场景。

使用方式

1. 在应用市场安装内容助手插件；

2. 进入 控制台 → 工具，找到文章导入功能；

3. 上传本地的 Markdown 文件，插件会自动处理文件中引用的图片资源。

方式四：VSCode 插件

vscode-extension-halo 是 Halo 官方维护的 VSCode 扩展，让你可以直接在 VSCode 中将 Markdown 文件发布到 Halo，无需打开浏览器。

主要功能

• 将当前 Markdown 文件一键发布到 Halo

• 自动将文件中引用的本地图片上传到 Halo 附件

• 支持从 Halo 将文章拉取到本地进行编辑

• 支持设置文章的分类和标签

安装方式

在 VSCode 扩展市场搜索 Halo 并安装，然后通过命令面板执行 Halo Setup 配置站点信息即可。

方式五：Obsidian 插件

obsidian-halo 是 Halo 官方维护的 Obsidian 社区插件，适合将 Obsidian 作为主要写作工具的用户，可以直接将笔记发布到 Halo，不打断本地写作流。

主要功能

• 将当前笔记发布到 Halo

• 支持配置多个 Halo 站点，并设置默认站点

• 支持从 Halo 将文章同步回 Obsidian

• 通过命令面板操作，无需离开 Obsidian

安装方式

在 Obsidian 社区插件中搜索 Halo 并安装，然后在插件设置中填写站点地址和 Personal Access Token 即可。

方式六：Halo CLI

Halo CLI 是 Halo 官方提供的命令行工具，支持通过 halo post import-markdown 命令将本地 Markdown 文件导入到 Halo，适合有自动化需求或习惯在终端工作的用户。

安装

npm install -g @halo-dev/cli

登录

halo auth login \
  --profile default \
  --url https://your-halo-site.com \
  --auth-type bearer \
  --token <your-token>

导入 Markdown 文件

halo post import-markdown ./article.md

CLI 还支持文章列表查看、草稿管理、插件和主题操作等功能，可通过 halo --help 查看完整命令列表。

如何选择

为什么考虑升级到付费版？

相比社区版，付费版在内容管理的基础上提供了一系列进阶能力：

• 全站私有化：整个站点需登录才能访问，适合企业内部知识库、付费社区或不对外公开的内容站点

• AI 插件：AI 辅助生成文章、RAG 智能问答，让访客可以直接与你的站点内容对话

• 付费阅读插件：对部分内容设置付费门槛，支持将内容变现

• SEO 优化插件：更完整的搜索引擎优化工具，提升站点在搜索结果中的排名

• 手机号注册登录：支持短信验证码登录，降低用户注册门槛，提升账号安全性

• 品牌信息自定义：替换控制台中的 Halo 默认 Logo 及品牌标识，适合对外交付或多品牌运营场景

• 在线商城（商城版）：品牌官网 + CMS + 线上店铺一体化，支持微信支付、支付宝、Stripe

如果你对版本功能还有疑问，可以先查阅版本区别说明，或访问官方版本对比页面。

概览

确认要升级后，切换过程本身非常简单——你的所有数据、配置和数据库连接信息均无需改动，只需将运行的镜像或 JAR 包替换为付费版对应的版本并重启，随后按需激活许可证即可。

这与 GitLab CE/EE 的升级方式类似：底层数据完全兼容，切换本身只是替换运行文件。

切换前建议先备份数据，可参考备份与恢复。

Docker Compose 部署

只需将 docker-compose.yaml 中的镜像从社区版改为付费版镜像，其余配置保持不变。

修改镜像地址

services:
  halo:
    image: registry.fit2cloud.com/halo/halo:2.23 # [!code --]
    image: registry.fit2cloud.com/halo/halo-pro:2.23  # 改为此镜像 [!code ++]

镜像对应关系如下：

将镜像地址替换为付费版对应地址，版本号保持一致即可。如果服务器拉取 Docker Hub 速度缓慢，可以使用国内镜像库地址。

重启服务

docker compose pull
docker compose up -d

Docker 部署

停止并删除原有容器，用付费版镜像重新创建，挂载目录和端口映射保持不变。

停止并删除旧容器

docker stop halo
docker rm halo

拉取付费版镜像

# Docker Hub
docker pull halohub/halo-pro:2.23

# 国内镜像库（拉取缓慢时使用）
docker pull registry.fit2cloud.com/halo/halo-pro:2.23

重新创建容器

将原启动命令中的镜像地址替换为付费版镜像，其他参数完全不变。以下以常见配置为例：

docker run -it -d \
  --name halo \
  -p 8090:8090 \
  -v ~/.halo2:/root/.halo2 \
  -e JVM_OPTS="-Xmx256m -Xms256m" \
  registry.fit2cloud.com/halo/halo-pro:2.23

JAR 部署

JAR 部署方式下，社区版和付费版对应不同的 JAR 文件：

停止正在运行的 Halo 服务

service halo stop

下载付费版 JAR 包，覆盖原文件

wget https://dl.halo.run/release/halo-pro-2.23.0.jar -O ~/app/halo.jar

启动服务

service halo start

工作目录（~/.halo2）、配置文件（application.yaml）以及 systemd service 文件均无需任何修改。

激活许可证

切换到付费版镜像后，Halo 会正常启动，此时功能与社区版相同。如需解锁专业版或商城版的专属功能，需要购买并激活对应的许可证。

• 购买许可证：https://www.lxware.cn/halo

• 激活方式：参考许可证激活

如果暂时不需要付费版专属功能，无需激活，站点可以继续正常使用。

Halo（发音：[ˈheɪloʊ]）是一款强大易用的开源建站工具。无论你想搭建个人博客、知识库，还是企业官网、在线商城，Halo 都能帮你一站式完成。

核心定位

Halo 的目标很简单：让任何人都能低门槛地拥有一个属于自己的网站，同时给开发者足够的灵活性去自定义和扩展。

它诞生于开源社区，遵循 GPL-v3.0 协议，源代码完全公开，任何人都可以免费使用、修改和部署。

五分钟上手

如果你本地有 Docker 环境，一行命令即可启动：

docker run -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 halohub/halo:2

不想折腾本地环境？官方提供了一个在线 Demo，后台地址是 /console，用账号 demo / P@ssw0rd123.. 即可登录体验完整功能。

生产环境推荐按照安装指南进行部署。

三个版本，满足不同需求

Halo 目前提供三个版本，适合不同规模和场景的用户：

社区版：面向个人开发者和技术爱好者。零成本搭建博客、作品集、技术文档站，可以使用超过 100 款免费主题和插件。

专业版：在社区版基础上增加了 10+ 高价值功能，包括：移动端 APP、AI 智能建站、手机号验证登录、全站私有化部署，以及付费主题和插件市场（SEO 优化、付费阅读、AI 助手等）。

商业版：面向有电商需求的用户，集成了完整的在线商城能力：商品管理、订单处理、支付对接（微信支付、支付宝），实现品牌官网 + CMS + 线上店铺的一体化落地。

丰富的生态

Halo 拥有活跃的主题和插件生态，可以在官方应用市场浏览所有适配 Halo 2.x 的资源，也可以去 awesome-halo 仓库发现社区贡献的优质内容。

总结

如果你在寻找一个自托管、可扩展、开源免费的建站工具，Halo 值得一试。它的上手门槛极低（一行 Docker 命令），但能力上限却足够高，从个人博客到商业电商，都在它的覆盖范围之内。

• 官网：www.halo.run

• 文档：docs.halo.run

• 社区：bbs.halo.run