Halo 零基础搭建教程 – 搭建你的现代化个人博客

一、Halo 是什么

Halo 是一个现代化的开源个人博客系统，基于 Java 开发。它的定位是替代 WordPress，提供更简洁、更现代的博客体验。

Halo 的核心特点：

• 界面美观：自带一套漂亮的默认主题，也支持第三方主题市场，一键切换。
• Markdown 编辑器：内置所见即所得的 Markdown 编辑器，支持实时预览。
• 插件系统：丰富的插件生态，可以扩展评论、搜索、图床对接等功能。
• 多用户支持：一个博客可以有多个作者。
• 附件管理：上传的图片、文件集中管理，可对接阿里云 OSS、腾讯云 COS 等云存储。
• Docker 部署：官方提供 Docker 镜像，一条命令就能跑起来。
• 完全开源免费：GitHub 仓库：https://github.com/halo-dev/halo

二、你需要准备什么

准备项	说明
一台云服务器	推荐 1 核 2G 以上。阿里云/腾讯云/华为云均可
一个域名（可选）	没有域名可以用服务器 IP 访问
基本的终端操作能力	会复制粘贴命令即可

三、部署方式一：Docker 部署（最推荐）

Docker 是最简单的部署方式。不需要安装 Java、不需要配置环境，一条命令搞定。

3.1 连接到你的云服务器

Windows 用户：使用 FinalShell 或 Xshell 连接服务器。
Mac 用户：打开终端，输入 ssh root@你的服务器IP。

如果你还没有安装 Docker，先安装：

# 安装 Docker（Ubuntu/Debian）
curl -fsSL https://get.docker.com | bash

# 启动 Docker 并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 验证安装
docker --version

3.2 创建目录结构

mkdir -p ~/.halo2

3.3 使用 Docker Compose 部署（推荐）

先安装 Docker Compose：

# 安装 Docker Compose 插件
sudo apt install -y docker-compose-plugin

# 验证
docker compose version

创建 docker-compose.yml 文件：

cd ~
cat > docker-compose.yml << 'EOF'
version: "3"

services:
  halo:
    image: halohub/halo:2.19
    container_name: halo
    restart: unless-stopped
    ports:
      - "8090:8090"
    volumes:
      - ~/.halo2:/root/.halo2
    environment:
      - HALO_EXTERNAL_URL=http://你的域名或IP:8090
      - HALO_SECURITY_INITIALIZER_SUPERADMINUSERNAME=admin
      - HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD=你的密码
    command:
      - --spring.r2dbc.url=r2dbc:pool:mysql://127.0.0.1:3306/halo
      - --spring.r2dbc.username=root
      - --spring.r2dbc.password=你的MySQL密码
      - --spring.sql.init.mode=always
      - --halo.external-url=http://你的域名或IP:8090
EOF

注意：以上配置需要外部 MySQL。如果你想快速启动（使用内置 H2 数据库），可以简化：

cd ~
cat > docker-compose.yml << 'EOF'
version: "3"

services:
  halo:
    image: halohub/halo:2.19
    container_name: halo
    restart: unless-stopped
    ports:
      - "8090:8090"
    volumes:
      - ~/.halo2:/root/.halo2
    environment:
      - HALO_EXTERNAL_URL=http://你的服务器IP:8090
      - HALO_SECURITY_INITIALIZER_SUPERADMINUSERNAME=admin
      - HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD=请设置一个复杂的密码
EOF

这个简化版本使用内置的 H2 数据库，不需要额外安装 MySQL。对于个人博客来说完全够用。

启动容器：

docker compose up -d

等待几秒钟，容器启动完成。

查看运行状态：

docker ps | grep halo

如果看到 STATUS 显示 Up，说明启动成功。

查看日志：

docker logs halo

3.4 放行端口

去云服务商控制台 → 安全组 → 入方向规则，添加：

• 协议：TCP
• 端口：8090
• 来源：0.0.0.0/0

3.5 初始化博客

1. 浏览器访问 http://你的服务器IP:8090
2. 第一次访问会进入初始化页面。
3. 按照页面提示填写：
   • 站点标题：你的博客名称（如“张三的博客”）。
   • 用户名：管理员用户名（建议用 admin）。
   • 密码：管理员密码（设置一个复杂的密码）。
   • 邮箱：你的邮箱。
4. 点击“初始化”，等待完成。
5. 初始化完成后，用刚才设置的用户名和密码登录。

登录成功，进入 Halo 的管理后台。你可以在后台写文章、换主题、安装插件。

3.6 访问前台

后台地址：http://你的IP:8090/admin
前台地址：http://你的IP:8090

你的博客已经上线了！

四、部署方式二：宝塔面板 + Docker 混合部署

如果你已经在用宝塔面板管理服务器，可以在宝塔中安装 Docker 管理器，然后用 Docker 运行 Halo。

4.1 在宝塔中安装 Docker

1. 宝塔面板 → 软件商店。
2. 搜索 Docker 管理器，点击安装。
3. 等待安装完成。

4.2 拉取并启动 Halo

1. 宝塔面板 → 终端（或直接用 FinalShell 连接服务器）。
2. 执行以下命令：

docker run -d \
  --name halo \
  --restart unless-stopped \
  -p 8090:8090 \
  -v ~/.halo2:/root/.halo2 \
  -e HALO_EXTERNAL_URL=http://你的IP:8090 \
  -e HALO_SECURITY_INITIALIZER_SUPERADMINUSERNAME=admin \
  -e HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD=你的密码 \
  halohub/halo:2.19

4.3 后续步骤

和 Docker 部署一样，放行 8090 端口，浏览器访问 http://你的IP:8090 完成初始化。

五、部署方式三：1Panel 面板部署

1Panel 是一个现代化的 Linux 服务器运维管理面板（比宝塔更轻量、界面更现代）。如果你用的是 1Panel，部署 Halo 非常简单。

5.1 安装 1Panel（如果还没装）

curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o quick_start.sh && sudo bash quick_start.sh

安装完成后，终端会显示面板地址、用户名和密码。

5.2 通过应用商店安装 Halo

1. 登录 1Panel 面板。
2. 左侧菜单 → 应用商店。
3. 搜索 Halo。
4. 点击 安装。
5. 填写参数：
   • 端口：8090
   • 管理员用户名：admin
   • 管理员密码：设置密码
6. 点击确认，等待安装完成。

1Panel 会自动完成 Docker 拉取、启动、端口放行等所有步骤。

六、绑定域名（可选）

如果你有自己的域名，可以通过 Nginx 反向代理实现用域名访问。

6.1 添加 DNS 解析

在域名服务商（阿里云/腾讯云）处，添加一条 A 记录：

• 主机记录：blog（表示 blog.yourdomain.com）或 @（表示根域名）
• 记录值：你的服务器公网 IP

6.2 配置 Nginx 反向代理

如果你用宝塔面板：

1. 宝塔面板 → 网站 → 添加站点。
2. 域名填你解析的域名（如 blog.yourdomain.com）。
3. 创建站点后，点击站点名称 → 反向代理。
4. 目标 URL 填写 http://127.0.0.1:8090。
5. 点击保存。

现在就可以用 http://blog.yourdomain.com 访问你的博客了。

如果需要 HTTPS，在宝塔面板中点击 SSL → Let’s Encrypt，一键申请免费 SSL 证书。

七、Halo 基本使用指南

7.1 写第一篇文章

1. 登录后台 → 文章 → 写文章。
2. 在编辑器中输入标题和正文。编辑器支持 Markdown 语法。
3. 设置文章分类、标签。
4. 点击 发布。

7.2 更换主题

1. 后台 → 外观 → 主题。
2. 点击 主题市场，浏览可用的免费主题。
3. 找到喜欢的主题，点击 安装。
4. 安装后点击 启用。

7.3 安装插件

1. 后台 → 插件 → 插件市场。
2. 常用的插件：评论组件（对接 GitHub/微信等评论系统）、图床插件（自动上传图片到云存储）、搜索插件（增强搜索功能）。
3. 点击安装并启用。

7.4 创建页面

除了文章，你还可以创建独立的页面——比如“关于我”、“友情链接”。

1. 后台 → 页面 → 新建页面。
2. 输入标题和内容，发布。
3. 在主题设置中，将页面添加到导航菜单。

八、常见问题

Q1：访问 8090 端口打不开

检查云服务商安全组是否放行了 8090 端口。如果用的是宝塔，还需要检查宝塔的“安全”菜单中是否放行了 8090 端口。

Q2：初始化后忘记管理员密码

如果你使用 Docker 部署，可以在启动容器时通过环境变量重新设置密码：

# 停止并删除旧容器
docker stop halo
docker rm halo

# 重新启动，指定新密码
docker run -d \
  --name halo \
  --restart unless-stopped \
  -p 8090:8090 \
  -v ~/.halo2:/root/.halo2 \
  -e HALO_SECURITY_INITIALIZER_SUPERADMINUSERNAME=admin \
  -e HALO_SECURITY_INITIALIZER_SUPERADMINPASSWORD=新密码 \
  halohub/halo:2.19

Q3：如何升级 Halo 到最新版？

# 拉取新镜像
docker pull halohub/halo:2.19

# 停止并删除旧容器（数据不会丢失，存在 ~/.halo2 中）
docker stop halo
docker rm halo

# 重新启动
docker run -d \
  --name halo \
  --restart unless-stopped \
  -p 8090:8090 \
  -v ~/.halo2:/root/.halo2 \
  halohub/halo:2.19

Q4：上传的图片存在哪里？

默认存在服务器本地（Docker 容器的 ~/.halo2 目录中）。如果想存在云端，可以在后台安装图床插件，对接阿里云 OSS 或腾讯云 COS。

九、总结

Halo 是目前最优秀的开源博客系统之一。部署流程概括为：

1. 准备服务器：安装 Docker。
2. 启动容器：一条 docker run 命令。
3. 初始化：浏览器访问，填写站点名称和管理员密码。
4. 使用：登录后台，写文章、换主题、装插件。

从零到博客上线，十分钟就能完成。如果你一直想要一个属于自己的博客，Halo 是非常好的选择。

项目地址：https://github.com/halo-dev/halo