Hexo 博客部署排障清单：从重复 Front Matter 到 CI/CD 发布稳定性

Hexo 博客自动部署真正难的不是第一次上线，而是长期运营中的稳定发布。文章越来越多、主题不断调整、产品页和服务页加入后，任何一个小问题都可能导致页面 404、sitemap 缺失、样式不生效或 Jenkins 构建失败。

这篇文章把原来的部署笔记整理成一份排障清单，重点关注 Hexo + Jenkins + Docker + Nginx / FRP 场景下最常见的问题。

1. 内容文件问题

1.1 重复 Front Matter

Hexo 文章必须只有一段 Front Matter：

---
title: 文章标题
date: 2026-04-01 09:00:00
categories:
  - DevOps / CI-CD
tags:
  - Hexo
---

如果文章中出现两段 --- 包起来的元数据，Hexo 可能把第二段当正文，也可能导致渲染异常。内容审计时应重点扫描：

是否存在双 Front Matter；
title、date、categories 是否重复；
permalink 是否和其他文章冲突；
draft: true 是否误留在线上文章。

1.2 permalink 冲突

两篇文章使用同一个 permalink 会造成覆盖或访问异常。建议：

对历史文章保留原 permalink，避免 SEO 链接失效；
新文章使用稳定规则，例如 posts/YYYY-MM-DD/hash.html；
内容迁移时保留旧链接，必要时做 301 重定向。

1.3 分类和标签混乱

分类过多会稀释 SEO 权重。博客商业化后，应把分类收敛到有限集合，例如：

AI Agent
AI Coding
Claude Code
MCP
OpenClaw
DevOps / CI-CD
架构设计
工具效率

标签可以更细，但分类不宜无限扩张。

2. 子模块问题

如果博客采用“总仓库 + 内容仓库 + 主题仓库”结构，最常见的问题是内容或主题 MR 已合并，但 site 仓库子模块指针没更新。

排查命令：

1
2
3

git submodule status
git ls-tree HEAD source
git ls-tree HEAD themes

如果线上没有新文章或导航样式没变化，优先检查：

内容仓库 main 是否包含目标 commit；
主题仓库 main 是否包含目标 commit；
site 仓库是否更新 source / themes 指针；
Jenkins 是否拉取了最新子模块。

3. Jenkins 构建问题

3.1 依赖安装失败

常见原因：

Node 版本不一致；
npm 源不可用；
lock 文件和 package.json 不匹配；
Jenkins 节点磁盘不足。

建议在 Jenkins 日志中明确输出：

node -v
npm -v
df -h
npm ci

3.2 Hexo generate 失败

重点检查：

Front Matter YAML 格式；
Markdown 表格是否损坏；
图片链接是否包含非法字符；
主题模板是否引用不存在的字段；
文章文件名是否存在特殊空格或编码问题。

3.3 构建成功但页面缺失

这类问题通常发生在：

permalink 配置不符合预期；
page 文件目录不正确；
文章 draft 状态错误；
主题 layout 没有覆盖该页面类型。

建议构建后检查 public/：

test -f public/index.html
test -f public/sitemap.xml
test -d public/services
test -d public/products/pr-reviewer

4. Docker 部署问题

4.1 容器启动失败

排查：

1
2
3

docker ps -a
docker logs --tail 100 blog-container
docker inspect blog-container

重点看端口冲突、Nginx 配置错误、镜像不存在、卷挂载路径错误。

4.2 `<none>:<none>` 镜像堆积

重复构建 latest 或相同 tag 时，旧镜像会变成 dangling image。建议部署后清理：

1	docker image prune -f --filter "dangling=true" --filter "until=24h"

不要在共享服务器上随意执行 docker system prune -a，避免误删其他项目镜像。

5. Nginx / FRP 访问问题

如果公网访问链路是：

1	公网域名 -> 公网 Nginx -> FRP / WireGuard -> 内网 Nginx -> Docker 容器

排障时要分层 curl：

1
2
3

curl -I http://localhost:8080/
curl -I http://内网-nginx/
curl -I https://blog.example.com/

不要只看公网 502，要定位是哪一层断了：容器、内网 Nginx、FRP 通道、公网入口还是 DNS / 证书。

6. 发布后 SEO 检查

每次较大内容变更后，建议检查：

首页 title / description 是否正确；
sitemap 是否更新；
服务页、产品页、专题页是否 200；
文章标题是否包含核心关键词；
是否出现重复文章或重复 permalink；
旧文章是否仍能访问。

命令示例：

1
2
3

curl -I https://blog.sharezone.cn/
curl -I https://blog.sharezone.cn/sitemap.xml
curl -I https://blog.sharezone.cn/services/

7. 架构师点评

博客部署排障本质上是一个小型生产系统排障。内容、构建、镜像、容器、Nginx、网络、SEO，每一层都可能出问题。把排障清单固化到 Jenkins 和文档中，比靠经验临时处理更可靠。

对于正在做 AI Agent / AI Coding 商业化的技术博客，发布链路就是获客链路的一部分。页面 404、导航错误、sitemap 缺失，都会直接影响转化。

8. 企业落地建议

建议把博客部署排障沉淀成三类资产：

CI 检查脚本：自动发现 Front Matter、冲突标记、关键页面缺失；
运行时检查脚本：验证线上关键路径和 SEO 标签；
运维手册：记录 Docker、Nginx、FRP、Jenkins 常见问题。

需要把博客、知识库或产品文档站升级成稳定的内容发布平台，可以查看企业 AI Agent / AI Coding 落地咨询。