Halo 2.x 博客部署与工作流集成指南

1. 架构与环境概述

• 宿主机环境：Ubuntu / Debian (阿里云 ECS 等云服务器)
• 核心服务：Halo 2.x (Java) 运行于本地 8090 端口
• 网关与反向代理：Nginx
• 安全与证书：Let's Encrypt (Certbot) 自动化 SSL 证书
• 内容管理终端：Obsidian (配合 Halo 社区插件)
• 网络拓扑：公网 IP 直连 (剥离了内网穿透架构)

2. 标准部署流程 (Deployment Pipeline)

2.1 基础环境与网络准备

1. 云防火墙配置：登录云服务商控制台（如阿里云），进入实例安全组，添加入方向规则，放行以下端口：

   • 80 (HTTP)
   • 443 (HTTPS)

2. 域名解析：在域名服务商处，添加一条 A 记录，将目标域名（如 blog.domain.com）指向云服务器的公网 IP。

2.2 启动 Halo 2.x 服务端

确保 Halo 服务已在服务器后端正常启动，并监听本地的 8090 端口。

• 注：通过 systemctl status halo.service 检查服务运行状态。确认运行后，此时可通过 http://服务器IP:8090/console 访问初始化界面。

2.3 配置 Nginx 反向代理 (关键环节)

1. 安装 Nginx：sudo apt install nginx -y

2. 开启全局下划线 Header 支持。编辑 sudo nano /etc/nginx/nginx.conf，在 http {} 块内确认存在：

   Nginx

   underscores_in_headers on;
   

3. 创建站点配置文件：sudo nano /etc/nginx/conf.d/halo.conf，填入以下标准配置（已包含大文件与 Token 转发优化）：

   Nginx

   server {
       listen 80;
       server_name blog.你的域名.top;
   
       # 允许最大 100MB 的附件上传 (防止 413 错误)
       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;
   
           # 显式透传 Authorization 头 (防止 Obsidian API 鉴权 401 错误)
           proxy_set_header Authorization $http_authorization;
           proxy_pass_header Authorization;
       }
   }
   

4. 测试并重载：sudo nginx -t && sudo systemctl reload nginx

2.4 部署 HTTPS 免费证书 (Certbot)

1. 安装 Certbot 及其 Nginx 插件：

   Bash

   sudo apt update
   sudo apt install certbot python3-certbot-nginx -y
   

2. 执行一键申请与自动配置：

   Bash

   sudo certbot --nginx -d blog.你的域名.top
   

3. 按照提示输入邮箱，并在重定向选项中选择 2 (Redirect)，强制 HTTP 跳转 HTTPS。

2.5 集成 Obsidian 自动化发布

1. 获取鉴权令牌 (Token)：

   • 登录 Halo 后台 (https://.../console)。
   • 在“插件”市场启用/安装 Personal Access Token (个人令牌)。
   • 进入“用户 -> 个人中心 -> 令牌”，生成一个包含所有权限 (Superuser) 的新令牌。
   • 复制弹窗中以 pat_ 开头的长字符串。

2. 配置 Obsidian 客户端：

   • 在 Obsidian 社区插件中安装并启用 Halo。
   • 进入插件设置，填入站点地址：https://blog.你的域名.top（注意末尾无斜杠）。
   • 粘贴令牌字符串，点击验证，显示绿色成功提示即可。

3. 核心避坑指南与故障排除 (Troubleshooting)

在实际部署中，极易遇到以下 5 类异常阻断，对应特征及修复方案如下：

3.1 Nginx API 鉴权失败 (Obsidian 连接报错)

• 故障表现：Obsidian 插件配置无误但提示“连接失败”。Nginx access.log 报 401 Unauthorized 或 400 Bad Request。

• 具体成因：Nginx 默认丢弃非标准 HTTP Header，导致发往 Halo 的 Authorization 令牌丢失。此外，用户填写的站点地址末尾若多加了 /，会引发路径拼接双斜杠（//apis/...）导致 400 错误。

• 解决方案：

  1. 检查 halo.conf 中是否包含 proxy_set_header Authorization $http_authorization;（见 2.3 节）。
  2. 确保 Obsidian 站点配置中，URL 末尾没有 /。

3.2 大文件上传中断 (413 Request Entity Too Large)

• 故障表现：在后台上传图片/视频或安装主题时，直接弹窗 413 错误。
• 具体成因：Nginx 默认的 client_max_body_size 限制为 1MB，安全策略物理拦截了大文件 POST 请求。
• 解决方案：在 Nginx 配置的 server 块中添加 client_max_body_size 100M;，并 reload Nginx。

3.3 自动化 SSL 部署报错 (Python 依赖冲突)

• 故障表现：运行 certbot 抛出 ImportError: cannot import name 'appengine' from 'urllib3.contrib'。

• 具体成因：宿主机系统中其他的 Python 工具通过 pip 全局升级了 urllib3 到 2.x 版本，破坏了系统源 Certbot 依赖的 <2.0 旧版环境。

• 解决方案：执行环境降级：

  Bash

  sudo pip install "urllib3<2.0"
  sudo pip install --upgrade requests requests-toolbelt
  

  修复后重新执行 certbot --nginx。

3.4 域名解析与本地代理劫持 (网站无法访问)

• 故障表现 1 (DNS)：通过域名访问显示 503 错误（如 Sakura Frp 残留界面），但 IP 访问正常。

  • 修复：修改域名商 A 记录至公网 IP，执行 ipconfig /flushdns 清理本地缓存。

• 故障表现 2 (代理软件)：开启电脑代理（如 Clash）后网页失联，插件报错。

  • 修复：在代理软件的预处理脚本或 Bypass（绕过）列表中，强制为博客域名和服务器 IP 添加 DIRECT（直连）规则。

3.5 令牌插件隐蔽性问题

• 故障表现：在 Halo 用户中心找不到生成令牌的入口。
• 具体成因：Halo 2.x 采用插件化架构，默认情况下“个人令牌”功能未显式激活。
• 解决方案：必须前往“插件管理”界面手动启用该插件，重启后选项卡才会出现在用户个人中心页的顶部。

4. 部署后收尾与验证标准

基础设施搭建完毕后，务必执行以下验证动作形成闭环：

1. 系统协议更新：进入 Halo 仪表盘 -> 设置 -> 常规，将“外部访问地址”由 http 更新为 https。
2. 发布流穿透测试：在 Obsidian 中新建一篇测试 Markdown，按下快捷键（如 Ctrl+P 调出 Halo: Publish），检查能否成功发布至线上，并确认侧边栏无报错。
3. 附件流测试：在 Obsidian 或网页后台上传一张超过 2MB 的高清图片，确认不触发 413 报错。