AI 管理的 Hugo 博客与自动化部署计划
上一篇《本博客的框架与部署》记录了本站的技术栈与部署方式。 本文从另一个角度补充记录：AI 助手在本站扮演了什么角色，以及已落地的 Git 同步自动化部署——既是备忘，也是给未来的自己看的工作记录。
AI 在本站搭建中做了什么
本站从零搭建到最后上线，大部分机械而繁琐的工作由 AI 助手完成，人工只负责做决策和写内容：
| 阶段 | AI 承担的工作 |
|---|---|
| 架构决策 | 对比 Ghost / Hugo / Hexo，确定 Hugo + PaperMod + Nginx + Cloudflare 方案 |
| 环境搭建 | 安装 Hugo v0.165 (extended)、初始化 git 仓库、拉取 PaperMod submodule |
| 主题配置 | hugo.toml 全部参数：菜单、RSS、SEO（Open Graph / Twitter Cards / Schema）、暗色模式 |
| 数学公式 | 配置 goldmark passthrough 扩展保护 $...$，KaTeX 资源本地化到 static/katex/ |
| 代码高亮 | 配置 Chroma（github-dark 主题） |
| 部署 | Nginx 站点配置（HTTP→HTTPS 301、缓存头、404 页）、Cloudflare Full (strict) |
| 内容创作 | 生成文章模板、测试文章、本文档类的说明文章 |
| 文档化 | docs/latex-guide.md 写作规范、README、部署脚本 deploy.sh |
AI 是怎么"测试"博客的
搭建过程中最花时间的是验证。AI 的验证方式是真实浏览器访问，而不是只靠构建成功：
curl检查全部页面返回 200- 浏览器实测：KaTeX 公式渲染 0 错误、代码高亮正常、TOC 自动生成、暗色/亮色切换
- 375px 移动端视口检查：公式/代码/表格不撑破页面
调试中踩过的坑
多行公式被 setext heading 破坏
Hugo 的 goldmark 会把"独立的 = 行"误判为 setext 二级标题。因此多行 $$...$$ 中若出现单独一行的 =，公式会被拆坏。
$$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$$
这种单行写法没问题；多行公式请用 \begin{aligned}（&= 与 \\ 换行），这是数学博客的主力格式，实测完全正常。规范已写入 docs/latex-guide.md。
localhost:1313 打不开
开发服务器跑在 VPS 上，监听 127.0.0.1:1313。从 Mac 浏览器访问 localhost:1313 时，localhost 指向的是 Mac 自己——Mac 上并没有 hugo server，于是报 ERR_CONNECTION_REFUSED。
这不是服务器挂了，而是网络拓扑问题。两种解决办法：
- SSH 隧道（本地预览用，安全）：
ssh -N -L 1313:127.0.0.1:1313 root@<VPS-IP>
# 然后浏览器访问 http://localhost:1313
- 直接看生产站（已发布内容用）：
https://meilingxiangmoyu.uk/posts/fft-eigenvalue/
不要把 hugo server 直接绑到 0.0.0.0 暴露公网——开发服务器无鉴权且会展示 draft: true 的文章，防火墙也不该为此开 1313 端口。
dev server 会把草稿写进 public/
Hugo v0.165 的 hugo server 默认把渲染结果写到磁盘（public/）。配合 -D 启动时，draft: true 的文章也会被写进 public/，而 Nginx 直接指向 public/——意味着草稿会被直接发布上线，同时 dev server 还会与部署流程争抢写 public/。
修复：dev server 用 --renderToMemory 只做内存渲染，public/ 只归部署流程写：
hugo server -D --renderToMemory --port 1313 --bind 127.0.0.1
Git 同步自动化部署（已落地）
架构
写作 → 同步 → 上线的完整链路已经跑通：
Mac (Typora 写作)
↓ git add / commit / push
GitHub (BWmagician/MeilingXiangMoyu)
↓ VPS cron 每 2 分钟 git pull（deploy key，只读）
/var/www/meilingxiangmoyu
↓ 有更新才重建（sync.sh）
public/ → Nginx → Cloudflare → https://meilingxiangmoyu.uk
方案对比（当时的选择过程）
| 方案 | 实时性 | 复杂度 | 安全/暴露面 |
|---|---|---|---|
| GitHub Actions | 秒级 | 高（需在 VPS 放 Runner 或 SSH 回连） | 需给 CI 开放 SSH 入口 |
| Webhook | 秒级 | 中（需一个公网接收端点 + secret 校验） | 多一个对外端点 |
cron 轮询 git pull | 1~5 分钟 | 低 | 零新增暴露面 |
个人博客最终选了 cron 轮询：每 2 分钟检查一次远程更新，命中才执行重建。简单、可靠、无新增攻击面，几秒的延迟对博客完全无感。若以后需要"push 即上线"的实时体验，再升级为 webhook。
落地过程
- VPS 生成 SSH deploy key（
ed25519），添加到 GitHub 仓库 Deploy Keys（只读） - 配置
~/.ssh/config让github.com走这把专用密钥 git remote add origin [email protected]:BWmagician/MeilingXiangMoyu.git- 一次性种子推送：
git push -u origin master（当前 84 个文件全量上传） - 编写增量同步脚本
sync.sh：git pull --ff-only→ 对比 HEAD → 有变化才hugo --gc --minify+nginx -s reload；无变化静默退出 - cron 注册：每 2 分钟执行一次
sync.sh - 端到端验证：本机改文章 → push → 手动跑一次
sync.sh→ 确认远端 HEAD 变化触发重建 → 生产站验证内容更新
写作工作流（当前生效）
hugo new content posts/my-post/index.md # 建文章
# Typora 打开 content/posts/ 写作，图片放同目录（Page Bundle）
hugo server -D # 本地预览
git add . && git commit -m "..." && git push # 发布
# VPS 每 2 分钟自动同步 → 构建 → 上线 ✓
结语
AI 负责繁琐的搭建、配置、测试与文档化，人负责内容与决策——这是本站当前的维护模式。
自动化部署落地后，发布一篇新文章只需一次 git push，从"手动运维"彻底走向"内容创作"。