前言

作为一名 Go 后端工程师，我一直想搭建一个极简、高效且易维护的个人博客。经过调研和实践，我选择了 Hugo + GitHub Actions + 1panel 这套方案。本文记录了完整的部署过程和踩过的坑。

为什么选择这个方案？

  • Hugo：Go 编写的静态站点生成器，编译速度极快，对 Go 开发者友好
  • GitHub Actions：免费的 CI/CD，自动化构建和部署
  • 1panel：服务器管理面板，SSL 证书自动续签，运维省心
  • 成本：除了服务器费用，其他全部免费

架构说明

Mac 本地写作
    ↓
Git Push 到 GitHub
    ↓
GitHub Actions 自动构建
    ↓
Rsync 同步到服务器
    ↓
1panel/Nginx 提供服务

核心优势：

  • 本地只需要写 Markdown，push 后自动部署
  • 服务器只运行 Nginx，资源占用低
  • 版本控制天然支持，可随时回滚

准备工作

1. 环境要求

  • Mac（或 Linux）开发机
  • 一台服务器（已安装 1panel）
  • 已备案的域名
  • GitHub 账号

2. 安装 Hugo

brew install hugo
hugo version  # 验证安装

详细步骤

第一步：创建 Hugo 站点

# 创建站点
cd ~/
hugo new site myblog
cd myblog

# 初始化 Git
git init
git branch -M main

# 安装主题（以 PaperMod 为例）
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

第二步：配置 Hugo

编辑 hugo.toml：

baseURL = "https://你的域名.com"
languageCode = "zh-cn"
title = "你的博客名"
theme = "PaperMod"

[params]
  defaultTheme = "auto"
  ShowReadingTime = true
  ShowCodeCopyButtons = true
  ShowBreadCrumbs = true

[params.homeInfoParams]
  Title = "欢迎来到我的博客"
  Content = "这里是我的技术笔记"

[[menu.main]]
  identifier = "posts"
  name = "文章"
  url = "/posts/"
  weight = 10

[[menu.main]]
  identifier = "tags"
  name = "标签"
  url = "/tags/"
  weight = 20

第三步：写第一篇文章

# 创建目录
mkdir -p content/posts

# 创建文章
cat > content/posts/hello-world.md << 'EOF'
---
title: "Hello World"
date: 2025-01-25
draft: false
tags: ["随笔"]
---

这是我的第一篇博客文章。

## 关于我

我是一名 Go 后端工程师。
EOF

第四步：本地测试

hugo server -D
# 浏览器访问 http://localhost:1313

第五步：配置服务器

5.1 在 1panel 中创建网站

  • 登录 1panel 面板
  • 进入"网站" → “创建网站”
  • 域名：blog.你的域名.com
  • 类型：静态网站
  • 开启 HTTPS，申请 SSL 证书

记录下部署路径，例如：

/opt/1panel/www/sites/blog.你的域名.com/index

5.2 配置 SSH 密钥

在 Mac 上生成 RSA 密钥（兼容性最好）：

ssh-keygen -t rsa -b 4096 -f ~/.ssh/blog_deploy_key -N "" -C "blog-deploy" -m PEM

将公钥添加到服务器：

ssh-copy-id -i ~/.ssh/blog_deploy_key.pub -p 22 root@你的服务器IP

测试连接：

ssh -i ~/.ssh/blog_deploy_key -p 22 root@你的服务器IP "echo '连接成功'"

第六步：配置 GitHub Actions

6.1 转换密钥为 base64

重要：为了避免密钥格式兼容性问题，需要转换为 base64：

base64 -i ~/.ssh/blog_deploy_key | tr -d '\n' > /tmp/deploy_key_base64.txt
cat /tmp/deploy_key_base64.txt
# 复制输出的内容

6.2 创建 GitHub 仓库

在 GitHub 上创建新仓库（可以是私有的）。

6.3 配置 GitHub Secrets

进入仓库的 Settings → Secrets and variables → Actions，添加三个 secrets：

  • SERVER_SSH_KEY：粘贴 base64 编码后的密钥
  • REMOTE_HOST：服务器 IP 地址
  • REMOTE_PORT：SSH 端口（通常是 22）

6.4 创建部署配置

创建文件 .github/workflows/deploy.yml：

name: Deploy to Server

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Setup SSH Key
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.SERVER_SSH_KEY }}" | base64 -d > ~/.ssh/deploy_key
          chmod 600 ~/.ssh/deploy_key
          ssh-keyscan -p ${{ secrets.REMOTE_PORT }} ${{ secrets.REMOTE_HOST }} >> ~/.ssh/known_hosts

      - name: Deploy to Server
        run: rsync -avz --delete -e "ssh -i ~/.ssh/deploy_key -p ${{ secrets.REMOTE_PORT }}" public/ root@${{ secrets.REMOTE_HOST }}:/opt/1panel/www/sites/blog.你的域名.com/index/

注意：记得把最后一行的路径改成你的实际路径。

6.5 创建 .gitignore

cat > .gitignore << 'EOF'
# Hugo
/public/
/resources/_gen/
/.hugo_build.lock

# macOS
.DS_Store

# IDE
.vscode/
.idea/
EOF

第七步：推送到 GitHub

git add .
git commit -m "Initial commit: Hugo blog setup"

# 添加远程仓库（替换为你的仓库地址）
git remote add origin git@github.com:你的用户名/myblog.git

# 推送
git push -u origin main

推送成功后，GitHub Actions 会自动触发，大约 30 秒后部署完成。

第八步：验证部署

访问 https://blog.你的域名.com，应该能看到你的博客了！

常见问题

1. SSH 密钥格式错误

错误信息：

Load key "/home/runner/.ssh/deploy_key": error in libcrypto

解决方案：

  • 确保使用 RSA 格式密钥（-t rsa）
  • 指定 PEM 格式（-m PEM）
  • 转换为 base64 编码后再放入 GitHub Secrets

2. rsync 连接失败

检查项：

  • SSH 公钥是否正确添加到服务器
  • 服务器 IP 和端口是否正确
  • 部署路径是否存在且有写权限

3. 博客样式丢失

原因： baseURL 配置错误

解决： 确保 hugo.toml 中的 baseURL 与实际域名一致。

日常使用流程

部署完成后，日常写作非常简单：

# 1. 创建新文章
cd ~/myblog
hugo new posts/my-new-post.md

# 2. 编辑文章（用 VS Code、Typora 等）
# 记得把 draft: true 改为 draft: false

# 3. 本地预览（可选）
hugo server -D

# 4. 发布
git add .
git commit -m "New post: 文章标题"
git push

# 等待 30 秒，自动部署完成

总结

这套方案的优点：

  • 简单：本地只需要 Git 和 Hugo
  • 自动化：push 即发布，无需手动操作
  • 省钱：除了服务器，其他全免费
  • 可靠：1panel 自动续签证书，GitHub Actions 稳定可靠
  • 可扩展：轻松添加评论、统计等功能

经过实践，整个部署过程大约 30 分钟，后续维护成本几乎为零。对于想要专注于内容创作的技术博客来说，这是一个非常理想的解决方案。

参考资源