Halo 个人博客搭建与上线保姆级教程（小白友好·零翻车版）

适合谁：完全不懂 Linux、没碰过 Docker、看到配置文件就头大的纯小白，但极其希望能拥有一个属于自己、排版高颜值、完全独立掌控的个人独立博客。

支持系统：Debian 11/12/13、Ubuntu 20.04/22.04/24.04 LTS（腾讯云、阿里云、AWS、甲骨文、搬瓦工、轻量云等主流 VPS 通用，1.6GB 内存的小机器也能丝滑飞驰）。

耗时预期：约 25 ~ 35 分钟（跟着一步一步敲，一杯咖啡的时间搞定）。

做完你将得到：一个全球 CDN 加速、自带终身免费 HTTPS 绿锁、手机电脑极速秒开、拥有现代化 Markdown 写作后台的顶级颜值个人博客！

⚠️ 全程唯一保命铁律： 教程中所有修改配置的命令都做成了「自包含防呆脚本」，绝不需要你手动打开 vim 编辑器去改文件（彻底杜绝多敲空格或退出不来的噩梦），只管稳稳复制、粘贴、按回车！

🧭 核心概念：搞懂三个“角色”（90% 新手迷路的地方）

本教程会在几个地方来回切换，每一步开头都会标明操作位置，千万别敲错地方：

📋 开始前的准备清单（缺一项都别往下走）

• [ ] 一台云服务器（VPS）：
• 拥有公网 IP（例如 123.45.67.89）和初始 root 密码；
• 推荐系统选 Debian 12 或 Ubuntu 22.04/24.04；
• [ ] 拍个“快照”（存档）：
• 🗣️ 大白话：在云服务商网页控制台点一下「创建快照」。万一中途操作翻车了，点一下「恢复快照」就能瞬间穿越回起点，新手不存档等于裸奔！
• [ ] 一个属于你的域名：
• 任何后缀都行（比如 .com、.xyz、.top），建议在 Namesilo、腾讯云、阿里云或 Cloudflare 购买；
• 本教程以二级域名 blog.example.com 演示，你可以替换为你自己的域名。

第 1 步：第一次连上服务器并做基础准备

💻 【你本地的电脑】 打开 Windows 的 PowerShell 或 Mac 的「终端」，输入连接命令（将 IP 替换为你的）：

ssh [email protected]

• 第一次连的提示：终端弹出 Are you sure you want to continue connecting (yes/no)?
  👉 敲键盘输入 yes 并按回车；
• 输密码的提示：接着出现 root@... password:
  👉 粘贴或输入你的初始 root 密码，然后直接按回车；
• ⚠️ 高频心理障碍预警：在 Linux 终端输密码时，屏幕上不会有任何星号、圆点或光标移动！ 屏幕看上去像没反应一样，这不是键盘失灵，只管稳稳敲完密码按回车即可。
• ✅ 成功标志：终端屏幕出现 root@xxx:~# 样式的绿色或白色命令提示符。

💡 从这一秒开始，这个黑色终端窗口就是 🖥️【服务器窗口】。把它放在屏幕左边。

紧接着，在 🖥️ 【服务器窗口】 粘贴以下整段命令，校准时钟并刷新环境：

# 1. 设置时区为北京时间
timedatectl set-timezone Asia/Shanghai

# 2. 刷新系统仓库并安装必备轻量小工具
export DEBIAN_FRONTEND=noninteractive
apt update && apt install -y curl wget git htop ufw

• 🗣️ 说明：升级过程屏幕会飞速刷代码，别慌，等它停下来出现命令提示符即可。

第 2 步：一键安装官方正版 Docker 环境

Halo 博客作为一个现代化的开源程序，跑在 Docker 容器里是最稳定、最干净的（完全不污染服务器底层，想删随时一键干掉）。

🖥️ 【服务器窗口】 粘贴执行官方全自动 Docker 安装脚本：

curl -fsSL https://get.docker.com | bash

安装完成后，启动 Docker 并检查版本：

systemctl enable --now docker
docker --version
docker compose version

• ✅ 成功标志：终端清晰输出类似 Docker version 27.x.x 以及 Docker Compose version v2.x.x 的字样。

第 3 步：一键创建专属目录与极简配置文件

很多老教程最坑的地方，就是让新手用 vim 逐行去建 docker-compose.yaml，新手一旦漏了个空格或者按错了键，就会卡在编辑界面动弹不得，或者报错 yaml parse error。

这里我们采用全自动防呆写入。并且采用 内置 H2 嵌入式文件数据库： * 🗣️ 大白话：很多教程教小白额外安装一个独立的 MySQL 或 PostgreSQL 容器，那两个大家伙起步就吃 800MB 内存，小机器瞬间卡死爆 OOM！而 Halo 官方原生内置的 H2 数据库是轻量文件库，零额外开销，1.6G 内存的小机器跑起来轻松自如！

🖥️ 【服务器窗口】 复制下面整段代码，粘贴并回车：

# 1. 创建 Halo 专属数据存放目录
mkdir -p /opt/halo && cd /opt/halo

# 2. 全自动生成 docker-compose.yaml 文件（彻底杜绝手动缩进错误）
cat << 'EOF' > /opt/halo/docker-compose.yaml
version: "3"

services:
  halo:
    image: halohub/halo:2.20
    container_name: halo
    restart: unless-stopped
    volumes:
      - ./:/root/.halo2
    ports:
      - "127.0.0.1:8090:8090"
    environment:
      # 限制 JVM 内存，保证小机器绝对不爆内存
      - JVM_OPTS=-Xms256m -Xmx512m
EOF

# 3. 检查文件是否生成成功
ls -lh /opt/halo/docker-compose.yaml

• ✅ 成功标志：终端输出显示 /opt/halo/docker-compose.yaml 文件存在，大小约几百字节。
• 💡 安全设计亮点：端口绑定为 127.0.0.1:8090，意味着 8090 端口只对本机内部开放，外网黑客完全扫描不到它，所有外网访问稍后统一由安全网关接入！

第 4 步：启动 Halo 博客核心容器

配置就位后，让 Docker 在后台把博客拉起。

🖥️ 【服务器窗口】 执行启动指令：

cd /opt/halo
docker compose up -d

• 🗣️ 说明：Docker 第一次会自动从云端下载 Halo 镜像，屏幕会滚动显示 Pulling... Download complete，喝口水等待 1~2 分钟。

下载完毕后，检查容器运行状态：

docker compose ps

• ✅ 成功标志：在输出的列表中，halo 容器的状态显示为 Up 或 running（如下图示例）： text NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS halo halohub/halo:2.20 "sh -c 'java ${JVM_O…" halo 10 seconds ago Up 8 seconds 127.0.0.1:8090->8090/tcp

第 5 步：去 Cloudflare 解析域名并开启“小黄云”

🗣️ 大白话：传统老教程最折磨新手的一步，就是在服务器里搞 Certbot 申请证书，遇到国内 DNS 污染、80 端口冲突或解析延迟，频繁报超时错误。现在最聪明的现代化做法是把域名托管在 Cloudflare：它不仅免费帮你抵挡黑客攻击、加速全网访问，还默认自带终身有效的 HTTPS 免费小绿锁！

💻 【你本地的浏览器】 打开 Cloudflare 控制台：

1. 进入你的域名管理页，点击左侧菜单的 「DNS」➔「记录」；
2. 点击 「添加记录」： * 类型：选择 A； * 名称：填你想用的前缀（比如 blog）； * IPv4 地址：填入你的服务器真实公网 IP（例如 123.45.67.89）； * 代理状态：保持开启（橙色小云朵 ☁️）；
3. 点击 「保存」。
4. 接着点击左侧菜单的 「SSL/TLS」： * 在加密模式里，选择 「完全 (Full)」 或 「灵活 (Flexible)」 模式。

• ✅ 成功标志：DNS 记录列表里看到 blog 指向你的 IP，且云朵显示为橙色。

第 6 步：一键配置 Nginx 安全网关与对外暴露

服务器内部的 Halo 跑在 8090 端口，现在我们要让官方标准的 Web 网关（Nginx）接管外部请求，把外界访问平滑反向代理给 Halo。

🖥️ 【服务器窗口】 先填写你的域名变量（将第 1 行换成你自己的真实域名）：

MY_DOMAIN="blog.example.com"

接着，整段粘贴执行以下自动化网关部署脚本：

# 1. 安装轻量 Nginx 网页服务
apt install -y nginx

# 2. 写入针对 Halo 特化优化的反向代理配置（带长连接保活与大文件上传放行）
cat << EOF > /etc/nginx/sites-available/halo.conf
server {
    listen 80;
    listen [::]:80;
    server_name ${MY_DOMAIN};

    # 允许上传最大 100MB 的插图与附件
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;

        # 支持 WebSocket 与实时后台通知
        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";

        # 调优超时时间，防止发布长文时断连
        proxy_connect_timeout 60s;
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }
}
EOF

# 3. 激活站点并自检语法
ln -sf /etc/nginx/sites-available/halo.conf /etc/nginx/sites-enabled/
rm -f /etc/nginx/sites-enabled/default

# 4. 语法体检与优雅重载
if nginx -t; then
    systemctl restart nginx
    echo "[✓] Nginx 自动化网关配置成功并已就绪！"
else
    echo "[✗] 语法体检未通过，请检查域名变量！"
fi

• ✅ 成功标志：最后终端打印出 [✓] Nginx 自动化网关配置成功并已就绪！，且没有任何报错。

第 7 步：去云厂商网页放行 80 / 443 端口（门禁报备）

很多新手在服务器里配得天衣无缝，但在浏览器打开网站却死活提示“连接超时”。99% 的原因就是：服务器外面的云服务商防火墙没给通行证！

💻 【你本地的浏览器】 打开购买 VPS 的云服务商后台（腾讯云/阿里云/AWS/华为云等）：

1. 进入当前服务器实例详情，找到 「安全组」 或 「防火墙」；
2. 点击 「添加入站规则」，放行两个标准网页端口： * 放行 80 端口（HTTP） * 放行 443 端口（HTTPS） * 授权源填 0.0.0.0/0（允许全网所有人访问你的博客）；
3. 保存生效。

第 8 步：打开浏览器，初始化你的神颜博客！

最激动人心的时刻到了！

💻 【你本地的浏览器】 新开一个标签页，在地址栏输入你的域名：

https://blog.example.com

屏幕上将第一次弹出漂亮的 Halo 博客初始化向导：

1. 站点名称：填入你的博客大名（例如：晚风手记 或 某某的数字花园）；
2. 站点地址：默认自动识别你的域名；
3. 管理员用户名：想一个你登录后台的专属账号（比如 admin）；
4. 管理员密码：设置一个强密码（务必牢牢记在小本本上）；
5. 管理员邮箱：填你的常用邮箱；
6. 点击 「初始化」！

• ✅ 成功标志：页面自动跳转至博客首页，界面清爽现代，地址栏显示安全小绿锁！

进入后台管理：在你的域名后面加上 /console，例如：

https://blog.example.com/console

输入刚才设置的管理员账号密码，即可跃入功能完备的现代化写作后台！🚀✨

🎁 进阶新手礼包：3 分钟换上高颜值主题

Halo 最迷人的地方就是丰富的应用市场。在后台左侧点击 「应用中心」➔「主题」，你可以一键搜索并免费安装这些全网公认的高颜值主题：

• 🌸 Hao：目前生态中最成熟、最全能的杂志风格主题，图文并茂、动效极其细腻；
• 🍃 Akari：极简清爽的文艺日系风格，排版呼吸感拉满，专门为沉浸式阅读而生；
• 💻 Geist / 极客：程序员最爱的代码与 Markdown 极致高亮主题。

点击「安装」➔「启用」，刷新你的前台首页，你的博客瞬间就会蜕变为顶级独立网站的视觉质感！

🚑 翻车急救站（新手高频卡点速查）

🎓 毕业全维度自检清单

核对以下 5 项指标，全部打钩即代表你的个人博客已完全达到生产受控标准：

• [ ] 公网 HTTPS 绿锁：浏览器直接打开 https://你的域名 能够正常展现首页，不报安全证书警告；
• [ ] 后台正常登录：访问 /console 输入密码能正常进入管理仪表盘；
• [ ] 发一篇测试文章：在后台新建文章，输入标题和 Markdown 内容，点击发布后在前台首页能立刻刷出；
• [ ] 小机器内存健康：服务器终端输入 free -h，内存消耗平稳保持在几百兆以内，无内存泄漏溢出；
• [ ] 开机自动保活：Docker 容器配置了 restart: unless-stopped，就算服务器突发重启，博客也会在开机后默默自愈上线！