许多朋友在挑选个人博客或独立站程序时都会经历过纠结：静态博客（如 Hugo、Hexo）虽然省资源，但每次写文都要本地编译、git push，想换个样式还得去改前端配置，折腾久了很容易消磨掉写作的热情；而 WordPress 这类老牌工具又略显臃肿厚重。如果你既想专注于沉浸写作，又希望拥有现代化后台、丰富精美的主题与即插即用的插件市场，那么 Halo 绝对是目前自托管博客中最值得推荐的优选方案。作为成熟的国产开源建站系统，它不仅原生支持富文本和 Markdown 双编辑流，生态拓展也极其省心，非常适合想认真记录内容又不想花太多精力死磕代码的朋友。

本文基于官方最新发布的 Halo v2.27.2 进行全流程实装验证。Halo 2.x 采用前后端分离架构，默认监听 8090 端口，自带开箱即用的内置数据库，不需要额外启动 MySQL 或 PostgreSQL 容器即可跑起来。不过需要留意的是，由于底层基于 Java 运行时，容器启动时会有一段类加载与初始化过程，首次冷启动大约需要一分钟左右。只要跟着本文的部署步骤，几分钟内你就能拥有一个属于自己的现代化独立博客站点。

成品长这样

部署完成后，你的博客前台默认会套用官方精选的现代响应式主题。排版优雅清晰，无论是长篇技术博文还是日常随笔短评，在电脑端和手机端都能获得极佳的阅读质感：

Halo 博客前台首页默认主题
图 1：Halo 博客前台首页默认主题效果

通过专属后台入口即可进入功能完备的仪表盘。在这里，文章分类、标签管理、附件存储库、第三方评论系统以及一键安装的主题与插件生态尽在掌握，日常打理极其直观清爽：

Halo 控制台仪表盘
图 2：Halo 后台控制台仪表盘，系统资源与文章数据一目了然

准备工作

在正式开始敲命令前，请先对照检查你的云服务器与运行环境是否就绪：

  • Linux 服务器与硬件建议：推荐使用 Ubuntu 22.04 / 24.04 或 Debian 12 系统。Halo 运行时需要装载 Java 虚拟机，强烈建议服务器配备 至少 1GB 可用内存（如果服务器本身跑了其他程序，2GB 内存会更加充裕流畅），并预先配置好基础的 Swap 虚拟内存以防 OOM。
  • Docker 与 Docker Compose：确保宿主机上已装好 Docker Engine 以及 Compose 插件。
  • 防火墙与安全组：前往云厂商控制台放行 TCP 8090 端口入站规则，如果服务器开启了 ufw 或 firewalld，也请同步放行该端口。
  • 站点基础信息：提前想好你的博客站点标题以及一个常用的管理员邮箱地址，后续在初始化安装向导中会直接用到。

第一步：Docker Compose 部署

我们采用 Docker Compose 方式进行容器编排，这样升级维护和后续整机迁移都会非常清晰独立。

  1. 创建项目目录并切换进入

    在服务器中规划一个专属目录（例如家目录下的 halo），用于存放配置文件和持久化挂载文件：

    BASH
    mkdir -p ~/halo && cd ~/halo

  2. 编写 docker-compose.yml 配置文件

    在当前目录下创建编排文件：

    BASH
    nano docker-compose.yml

    将以下经实测验证的配置完整复制粘贴到文件中：

    BASH
    services:
  halo:
    image: halohub/halo:2.27.2
    container_name: halo
    restart: unless-stopped
    ports:
      - "8090:8090"
    volumes:
      - ./halo2:/root/.halo2

  3. 启动容器并查看初始化进度

    保存并退出编辑器后，执行后台拉起命令：

    BASH
    docker compose up -d

    启动后可以通过实时日志查看后台初始化进度：

    BASH
    docker compose logs -f

    当日志中输出 Halo started! 或出现 Netty 启动在 8090 端口并打印出初始化引导链接时，说明核心应用已就绪。此时按下 Ctrl + C 退出日志跟踪即可。

关于工作目录与数据持久化：

配置中映射出来的 ./halo2:/root/.halo2 是整个 Halo 的核心命脉。Halo 的所有业务数据——包括内置的 H2 关系型数据库、主题包、扩展插件、本地上传的所有附件静态资源以及系统运行日志，通通存放在容器内的 /root/.halo2 路径下。只要宿主机上的 ./halo2 目录完好，即使升级版本、删掉容器重新拉起，全部文章和配置都不会丢失。建议定期将 halo2 整个目录打包备份。

冷启动等待提醒：

Halo 2.x 底层为 Spring 框架技术栈，容器拉起后并不是秒开，通常需要 40 秒到 1 分钟左右的冷启动与初始化加载时间。如果在执行 docker compose up -d 后立即通过浏览器打开 http://服务器IP:8090 遇到连接被拒绝或白屏，请稍等片刻，多刷新两次即可进入安装引导页。

第二步：系统初始化向导

容器启动成功后，先别急着在浏览器里连环刷新。Halo 基于 Java 开发，首次加载内置框架与初始化配置通常需要 40 到 60 秒的缓冲时间。等上约一分钟后，在浏览器地址栏输入 http://你的服务器IP:8090/console 访问后台管理入口。

系统如果检测到尚未进行过初始配置，会自动从控制台路径重定向跳转到「系统初始化向导」页面。向导界面十分简洁，按照提示依次完成核心信息的设定：

  • 选择语言：默认选中「简体中文」，根据个人习惯确认即可。
  • 外部访问地址：这一项非常关键，Halo 很多静态文件引用、RSS 订阅源以及后续页面跳转都会以这个 URL 为基础拼接。如果你现阶段只是内网测试或裸 IP 访问，直接确认当前显示的 http://你的服务器IP:8090 即可；若你已经解析好了域名并配置了 Nginx 反向代理，强烈建议直接填入你的完整生产域名（例如 https://blog.yourdomain.com），避免后续再去系统配置里到处修改。
  • 站点标题：填入你的博客名称，比如「我的个人技术随笔」，之后在后台的「系统设置」里随时可以修改。
  • 管理员账号与电子邮箱：设置你日常登录后台的用户名，并填入一个真实可用的常用邮箱，该邮箱主要用于接收系统通知与找回管理员密码。
  • 登录密码：为了后台安全，务必输入一个复杂度达标的管理员密码。

确认各项信息准确无误后，点击下方的「初始化」按钮，Halo 会在后台写入基础数据并生成初始表结构。

Halo 系统初始化向导
图 3：Halo 系统初始化向导界面，包含语言、外部访问地址及管理员基础信息配置

初始化过程通常在数秒内即可搞定。初始化完成后，页面会自动跳转到统一的控制台登录页面。

Halo 登录页
图 4：Halo 控制台登录界面，输入刚才创建的管理员账号与密码即可进入仪表盘

此时在表单中填入刚配置好的管理员用户名与密码，点击登录，就能直接进入 Halo 2 的管理控制台仪表盘了。在这里你能俯瞰整个站点的文章概况、流量监控以及丰富的主题插件生态。

第三步：确认前台与第一篇文章

后台登录通了，接下来让我们去验证面向读者的前台页面是否正常运作。

在浏览器新标签页中直接打开博客的首页地址 http://你的服务器IP:8090（或你配置的域名）。Halo 初始化后会自动预装一套默认的现代博客主题，并且非常贴心地生成了一篇标题为「Hello Halo」的示例文章。只要看到前台能够完整展示页面骨架、样式没有崩塌错位、示例文章能正常点进去阅读，就说明你的 Halo 博客环境已经全部调通可用了。

确认前台没问题后，回到控制台管理页面（/console），在左侧导航菜单中点击「文章」进入列表管理：

  • 你可以点击默认的「Hello Halo」文章进入编辑界面，亲自体验一下 Halo 顺滑的富文本/Markdown 编辑体验，熟悉顶部排版工具与附件插入逻辑。
  • 熟悉之后，你可以直接在文章操作项里将其移入回收站或彻底删除，保持博客的整洁。
  • 接着点击右上角的「新建文章」按钮，敲入属于你的第一篇正式博文，选定分类、打好标签，点击「发布」。再回到博客前台刷新一眼，属于你自己的独立内容空间就正式落地了！

踩坑实录

很多新手初次部署 Halo 容易在几个细节上踩坑，这里整理了三条最典型的疑难解答：

1. 访问 /setup 报错 404？初始化入口早已变更
网上许多基于老旧 Halo 1.x 版本的教程会指引你访问 http://服务器IP:8090/setup 进行初始化。但在 Halo 2.x 架构重构后，该独立入口已完全废弃，直接访问必然返回 404 页面。现在的官方初始化入口是 /console，系统内部带有导航守卫，未初始化时会自动跳往向导界面；如果访问 /console 没有跳初始化而是直接显示登录框，说明你的工作目录已有历史数据，系统早已完成过初始化。

2. 冷启动阶段网页无响应？别盲目重启，先查健康状态
Halo 属于基于 Spring Boot 的 Java Web 应用，容器从启动到完成所有类加载、内嵌运行时启动需要大约 40 至 60 秒的冷启动耗时。不少用户敲完启动命令就连续刷新网页，看到浏览器报「连接已重置」或无响应就慌张地去执行 docker restart，反而让服务陷入反复冷启动的死循环。请耐心等待一分钟左右，或者在服务器使用 curl 或浏览器直接请求 http://服务器IP:8090/actuator/health。只要接口返回 {"status":"UP"}，就说明各服务组件就绪，此时再访问网页绝对秒开。

3. 默认 H2 数据库仅供尝鲜，生产运行请警惕红字告警
进入向导初始化页面时，你会注意到页面上有一行显眼的红字风险提示：当前使用的是内置的 H2 数据库模式。H2 是嵌入式单文件数据库，优势是零额外依赖开箱即用，特别适合初学者试用体验；但它的并发写入能力、大文件抗损性能较弱，一旦长期沉淀大量附件与文章，可能会增加数据库文件损坏的风险。如果是打算长期稳定运营的生产博客，建议后续参考官方手册改用独立的 PostgreSQL 或 MySQL 容器协同运行；若继续使用 H2，请一定养成高频备份工作目录的好习惯，防患于未然。

升级与备份

博客上线之后，长期的平稳运维全靠「安全升级」与「数据备份」两条腿走路。

如何平滑升级 Halo
由于所有的业务数据、插件、主题均挂载在宿主机的持久化目录（例如 ~/.halo2）中，容器本身完全是无状态的，升级极为轻量：

  1. 编辑你的部署脚本或 docker-compose.yaml 文件，将镜像标签由旧版本修改为新版本号（例如从 halohub/halo:2.18 改为 halohub/halo:2.19）。
  2. 在当前目录执行 docker compose pull 拉取最新的官方镜像包。
  3. 随后执行 docker compose up -d，Docker 会自动停掉旧容器并用新镜像重建启动。
  4. 等待约一分钟冷启动完成，刷新管理控制台，在系统关于信息中确认版本号更新成功即可。

两套完备的数据备份方案
文章数据是博主最核心的数字资产，建议双重备份搭配使用：

  • 控制台一键全量备份（日常首选）：Halo 后台原生集成了备份机制。登录控制台后，导航至「系统」->「备份与恢复」，点击右上角的「新建备份」。系统会自动将当前所有的文章文本、附件资源、安装的插件主题及配置数据库整合打包为一个压缩文件。生成完成后将其下载到本地电脑或同步到云盘冷藏，即便误删文章也能快速原样还原。
  • 停服物理归档（重大跨版本或服务器迁移必备）：对于使用默认 H2 数据库的环境，数据库文件就位于挂载目录的 db/ 路径下。在对底层操作系统大升级、更换云服务器或跨大版本升级前，最稳妥的做法是先彻底停机避免写入损坏：执行 docker compose down 停止容器，接着在宿主机执行 tar -czvf halo2-backup-$(date +%F).tar.gz ~/.halo2 把整个挂载工作目录打成压缩包异地保存。打包完毕后再 docker compose up -d 重新拉起博客，万无一失。