Hugo + GitHub Actions：从本地 Markdown 到线上站点的全自动流水线

Tue, 13 May 2025 15:30:00 +0800

0. 背景与架构演进：为什么我们需要流水线？

Hugo 的运行机制

Hugo 是一个基于 Go 语言的静态网站生成器（Static Site Generator）。它的核心工作流是将我们编写的 Markdown 源文件，结合站点配置和主题模板，在编译阶段直接渲染成纯静态的 HTML、CSS 和 JS 文件（输出到 public/ 目录）。由于是纯静态站点，线上的服务器不需要运行任何数据库或动态后端（如 PHP/Node.js），只需要一个 Web 服务器来托管这些文件即可对外提供访问。这种架构带来了极高的访问速度和安全性。

自动化构建的必然性

正因为 Hugo 所有的页面都是预先生成的，如果采用手动发布，我们每次更新文章就会陷入一个繁琐的循环：本地写 Markdown -> 本地运行 hugo 构建出 public 目录 -> 手动打包或通过 scp/rsync 把文件传到服务器。这三步里有两步是枯燥的机械劳动，不仅容易出错（比如忘了构建就上传），而且如果更换电脑写作，还得重新配置 Hugo 环境。因此，搭建一条自动化的 CI/CD 流水线，把编译和部署工作交给云端，是大幅提升博客写作体验的必选项。我们最终期望的体验是：只管写 Markdown，推代码即自动部署。

为什么这样设计部署架构？

基于上述诉求，我们设计了当前的流水线架构：

构建层（GitHub Actions）：文章源码天然需要使用 Git 进行版本控制并托管在 GitHub 上。GitHub Actions 提供了与代码仓库深度绑定的免费 CI/CD 环境。它可以监听 git push 事件，自动在云端运行容器，拉取子模块（主题）并执行 hugo build。这样无论我们在哪里写代码，只要能 push，云端就能帮我们完成构建。
传输层（rsync）：在云端构建完成后，我们使用 rsync 经由 SSH 将生成的静态文件增量同步到阿里云 ECS。rsync 非常轻量高效，配合 --delete 参数能够确保服务器上的文件状态与最新编译结果完全一致（自动删除已移除的文件），不需要在服务器端部署任何复杂的 Agent。
网关与服务层（从 Nginx 到 Pingap）：静态文件传到服务器的指定目录后，需要对外暴露。本站点早期用 Nginx 直接托管静态文件，后来迁移到 Pingap 统一入口。为了让 Hugo 生成的目录页、文章页和标签页都保持稳定的 index.html 行为，当前采用 darkhttpd 在本机监听静态目录，Pingap 负责 HTTPS、SNI、HTTP 跳转和反代。无论入口网关怎么演进，“云端编译静态文件并推送到服务器目录” 始终是整套发布流程的核心。

1. 最终部署架构图

本地写 Markdown ──git push──→ GitHub ──Actions──→ Hugo build ──rsync──→ ECS /var/www/hugo-site/
↑
SSH deploy key

GitHub：源码仓库 + CI 触发器 + 版本历史
GitHub Actions：Ubuntu runner 上跑 hugo build，然后 rsync
阿里云 ECS：实际跑服务的地方，darkhttpd 承载静态文件，Pingap 对外反代

2. 准备：仓库初始化

假设你已经有一个空仓库克隆到本地：

从 Nginx 迁移到 Pingap：一次接近零停机的实战记录

Tue, 13 May 2025 15:00:00 +0800

0. 背景与动机：为什么要替换掉 Nginx？

在过去很长一段时间里，本站点的静态文件托管（Hugo）以及动态服务反代（SillyTavern）一直由 Nginx 承担。Nginx 久经考验、极其稳定，堪称业界标杆。但随着系统架构的演进和统一网关管理的考量，我们开始寻求更现代化的反向代理方案，并最终将目光投向了 Pingap。

为什么选择 Pingap？

现代化的底层基石：Pingap 基于 Cloudflare 开源的 Pingora 框架构建，采用 Rust 编写。Pingora 在 Cloudflare 内部已经受了万亿级请求的考验。得益于 Rust 的内存安全特性，它从根本上规避了传统 C/C++ 网关常见的内存越界和崩溃风险。
更直观的配置模型：Nginx 的配置语法虽然强大，但指令的上下文和隐式执行顺序往往让人头疼。Pingap 采用了基于 TOML 的声明式配置，将 Server、Location、Upstream 和 Plugin 彻底解耦，配置的心智模型更加清晰，更利于后期的维护与扩展。
原生的高级特性支持：Pingap 对 HTTP/1.x、HTTP/2、WebSocket、gRPC-web、证书动态加载和插件化网关能力支持更直接。需要注意的是，HTTP/3/QUIC 这类能力应以当前官方 release 和文档为准，迁移生产入口时不要默认假设已经完整可用。

本次实战的核心目标：先在隔离端口上把新代理跑起来并完整验证，再用一次原子切换无缝替换 Nginx，全程保留 Nginx 配置以便出现问题时能够秒级回滚。

通过这种“先验证后切换”的安全策略，我们最终实测的切换中断窗口仅为 174 ms，线上流量几乎无感。

2026-05-17 复核：我重新 SSH 到服务器核对了一遍真实状态。当前服务器仍运行 pingap 0.13.2，pingap.service 使用 daemon 模式，Hugo 静态文件由 darkhttpd 承载。本文以下配置以服务器现状为准；新装环境可以再按最新 release 调整。

1. 起点：现状盘点

服务器：阿里云 ECS（Alibaba Cloud Linux 3 / RHEL 兼容），跑 Nginx 1.20.1，承载两个站点：

教程 on Cloudside