Hugo 自动化部署方案2：服务器编译

Hugo 自动化部署方案2：服务器编译

#

本文将深入探讨如何利用云服务器上的 1Panel 管理面板，结合 Git 与 Webhook 技术，为 Hugo 静态博客搭建一套专业、高效的自动化部署（CI/CD）流水线。我们将摒弃手动上传或提交构建产物（public 目录）的传统模式，转向更为先进和可靠的“服务器端构建”方案，实现真正意义上的 git push 即部署。

一、 引言：为何要自动化？

#

对于每一位 Hugo 博主而言，将本地撰写的 Markdown 文章发布到线上服务器，是创作流程的最后一环。传统的 hugo 构建后，通过 FTP 或 SCP 手动上传 public 文件夹的方式，不仅效率低下、过程繁琐，更容易因人工疏忽导致文件遗漏或版本错乱。

现代化的开发工作流追求的是持续集成与持续部署 (CI/CD)。其核心理念在于将代码的集成、测试、构建和部署等环节自动化，以提升效率、降低风险。本文将要实现的，正是这一理念在个人博客部署场景下的一个完美实践。

核心思想： 我们将 Git 仓库（如 GitHub）作为我们网站源代码（Source Code）的唯一真实来源 (Single Source of Truth)。我们的云服务器则扮演“自动化工厂”的角色，在接收到更新通知后，自动拉取最新的源代码，并在服务器本地环境中进行“编译打包”（hugo 构建），最终将成品无缝发布。

技术栈:

• 本地环境: 任意操作系统（Windows/macOS/Linux）
• 版本控制: Git & GitHub (或 Gitee/GitLab 等)
• 静态网站生成器: Hugo
• 服务器环境: 装有 1Panel 面板的 Linux 云服务器

通过本指南，您将告别手动部署的“石器时代”，步入优雅高效的自动化“现代文明”。

二、 Phase 1：规范化您的 Git 仓库

#

在开始之前，我们需要确保您的 Hugo 项目仓库处于一个干净、专业的状态。此阶段所有操作均在您的本地电脑上完成。

步骤 1.1：配置 .gitignore（至关重要）

#

.gitignore 文件用于告知 Git 哪些文件或目录不应被纳入版本控制。在“服务器端构建”模型中，我们绝不应该追踪由机器生成的 public 和 resources 目录。

1. 在您 Hugo 项目的根目录，找到或创建 .gitignore 文件。

2. 确保其内容如下，如果不是，请用以下内容覆盖：

   Code snippet

   # Hugo 生成的部署文件和缓存，必须忽略
   /public/
   /resources/
   hugo_stats.json
   
   # 常见操作系统的临时文件
   .DS_Store
   Thumbs.db
   

步骤 1.2：从 Git 历史中移除已追踪的产物目录

#

如果您之前的仓库追踪了 public 或 resources 目录，我们需要将它们从 Git 的追踪记录中移除。

1. 在项目根目录打开终端，执行以下命令：

   Bash

   # 分别移除 public 和 resources 目录的追踪记录
   # --cached 参数确保只删除追踪记录，不删除您本地的文件夹
   git rm -r --cached public
   git rm -r --cached resources
   

   如果某个目录之前未被追踪，执行命令时会提示错误，直接忽略即可。

2. 提交这次清理操作：

   Bash

   git commit -m "chore: Stop tracking generated directories (public, resources)"
   git push origin main
   

三、 Phase 2：配置云服务器环境

#

此阶段，我们需要登录云服务器，为其赋予自动构建您网站的能力。

步骤 2.1：安装必要的软件

#

您的服务器需要安装 Git 和 Hugo。

Bash

# 以 Debian/Ubuntu 系统为例
sudo apt update
sudo apt install -y git

# 安装 Hugo (推荐从 GitHub Releases 安装最新的 extended 版本)
# 1. 访问 https://github.com/gohugoio/hugo/releases 找到最新的 .deb 包链接
# 2. 复制链接地址，并在服务器上执行
wget [您复制的 .deb 文件链接]
sudo dpkg -i [下载的 .deb 文件名]

# 3. 验证安装成功
hugo version

步骤 2.2：创建服务器专属的 SSH 部署密钥

#

为了让服务器能安全、免密地从您的私有 GitHub 仓库拉取代码，我们将使用 SSH 密钥认证。

1. 在服务器终端执行，生成一对新的 SSH 密钥。ed25519 是目前推荐的高安全性算法。

   Bash

   ssh-keygen -t ed25519 -C "hugo_deploy_key_for_antwen.com"
   

2. 过程中会提问三次，请连续按三次回车，使用默认设置且不添加密码。

3. 查看并复制生成的公钥（.pub 文件）。

   Bash

   cat ~/.ssh/id_ed25519.pub
   

   请完整复制输出的、以 ssh-ed25519 开头的全部内容。

步骤 2.3：在 GitHub 中添加部署密钥 (Deploy Key)

#

1. 在浏览器中，进入您博客的 GitHub 仓库页面，导航至 Settings > Deploy Keys。
2. 点击 Add deploy key。
   • Title: 填写一个便于识别的名称，如 1Panel Production Server。
   • Key: 粘贴您刚刚从服务器复制的公钥。
   • Allow write access: 请勿勾选。我们遵循最小权限原则，服务器只需读取代码。
3. 点击 Add key 保存。

步骤 2.4：克隆项目源代码至服务器

#

现在，服务器已经有权限拉取代码了。我们将项目克隆到一个统一的源代码存放目录。

1. 在 GitHub 仓库页面，点击绿色 <> Code 按钮，选择 SSH 标签页，复制 SSH 格式的 URL。

2. 在服务器终端中执行：

   Bash

   # 创建一个用于存放所有网站源码的父目录
   sudo mkdir -p /opt/hugo_source
   
   # 克隆您的项目
   git clone [您复制的SSH格式URL] /opt/hugo_source/your_project_name
   

   例如: git clone git@github.com:dinghyv/myhugo.git /opt/hugo_source/antwen-blog

四、 Phase 3：配置 1Panel 自动化工作流

#

这是整个流程的核心，我们将利用 1Panel 的功能，将所有环节串联起来。

步骤 3.1：在 1Panel 中创建静态网站

#

1. 登录 1Panel，进入 “网站” > “创建网站”，选择 “静态网站”。
2. 主域名: 填写您的域名，如 www.antwen.com。
3. 网站目录: 1Panel 会为您生成一个固定的网站根目录。请务必记下这个路径，例如 /opt/1panel/apps/openresty/openresty/www/sites/www.antwen.com/index。
4. 保存网站。

步骤 3.2：编写服务器端部署脚本 (deploy.sh)

#

此脚本是自动化部署的“大脑”，定义了服务器在收到通知后需要执行的所有操作。

1. 进入您在服务器上克隆的项目源码目录：

   Bash

   cd /opt/hugo_source/your_project_name
   nano deploy.sh
   

2. 将以下脚本内容完整粘贴进去。请务必根据您的实际情况，修改 SOURCE_DIR 和 DEST_DIR 两个变量的值！

   Bash

   #!/bin/bash
   
   # --- 请根据您的实际情况修改以下变量 ---
   # 您的项目源代码在服务器上的存放路径
   SOURCE_DIR="/opt/hugo_source/antwen-blog"
   # 1Panel 为您网站指定的、不可更改的根目录
   DEST_DIR="/opt/1panel/apps/openresty/openresty/www/sites/www.antwen.com/index"
   # --- 修改结束 ---
   
   echo "============================================================"
   echo " executing deployment script for Antwen Blog"
   echo " Stated at: $(date '+%Y-%m-%d %H:%M:%S')"
   echo "============================================================"
   
   # 进入源代码目录，如果失败则退出
   cd $SOURCE_DIR || exit
   
   # 1. 从 Git 仓库拉取最新的源代码
   echo ">>> Step 1: Pulling latest source code from GitHub..."
   git reset --hard
   git pull origin main
   
   # 2. 初始化并更新主题（Git Submodule）
   # 即使您不使用子模块，执行此命令也无害，这是一个好习惯
   echo ">>> Step 2: Initializing theme submodule (if any)..."
   git submodule update --init --recursive
   
   # 3. 在服务器上执行 Hugo 构建命令
   # 这是整个流程的核心：从最新的源码，构建出最终的网站文件
   # -d 参数指定输出目录为 1Panel 的网站根目录
   # --gc 会执行垃圾回收，清理缓存，优化性能
   # --minify 会压缩 HTML/CSS/JS 文件，提升网站加载速度
   echo ">>> Step 3: Building site with Hugo on the server..."
   hugo --gc --minify -d "$DEST_DIR"
   
   echo "------------------------------------------------------------"
   echo " Hugo deployment successful!"
   echo "============================================================"
   

3. 保存并退出编辑器 (Ctrl+X, Y, Enter)。

4. 为脚本赋予可执行权限：

   Bash

   chmod +x deploy.sh
   

步骤 3.3：创建 Webhook 触发器

#

我们将巧妙地利用 1Panel 的“计划任务”功能，来接收 GitHub 发送的 Webhook 通知。

1. 进入 1Panel 的 “计划任务” > “创建计划任务”。
2. 任务名称: 起一个清晰的名字，如 Webhook: Deploy Hugo Blog。
3. 执行周期: 选择“手动执行”，我们不依赖它的定时功能。
4. 脚本内容: 填写您部署脚本的绝对路径，例如 /bin/bash /opt/hugo_source/antwen-blog/deploy.sh。
5. 保存任务。
6. 在计划任务列表中找到刚创建的任务，点击右侧的 “…” 更多操作，选择 “Webhook”，复制弹出的 URL。

步骤 3.4：关联 GitHub 与 1Panel

#

1. 回到您的 GitHub 仓库页面，进入 Settings > Webhooks > Add webhook。
2. Payload URL: 粘贴您从 1Panel 复制的 Webhook URL。
3. Content type: 选择 application/json。
4. 点击 Add webhook 保存。

至此，您的自动化部署流水线已完全建成！

五、 Phase 4：域名配置与优化

#

最后一步，确保所有用户都能正确访问您的网站。

1. 目标： 确定一个首选域名（推荐 www.antwen.com），并将不带 www 的 antwen.com 通过 301 永久重定向跳转过去。

2. Hugo baseURL: 确保您本地 hugo.toml 文件中的 baseURL 设置为您的首选域名，并以 / 结尾。

   Ini, TOML

   baseURL = "https://www.antwen.com/"
   

3. 1Panel 重定向配置:

   • 进入 www.antwen.com 网站的设置页面，在“域名绑定”中确保两个域名都已添加。
   • 在“重定向”中创建新规则：
     • 源域名: antwen.com
     • 重定向类型: 301
     • 目标 URL: https://www.antwen.com$request_uri (此变量能保证内页也被正确跳转)
   • 保存并启用规则。

六、 结论：新工作流

#

现在，您发布文章的流程已极致简化：

1. 在本地撰写和修改您的 Markdown 文章和源代码。
2. （可选）使用 hugo server 在本地实时预览。
3. 完成修改后，直接执行 git push 将源代码推送到 GitHub。