部署指南

部署方式概览

方式说明适用场景
GitHub Actions自动化 CI/CD本项目使用
GitHub PagesGitHub 托管免费托管
GitLab PagesGitLab 托管私有仓库
一键部署hexo-deployer传统方式
手动部署rsync/scp自有服务器

本项目部署架构

1
2
3
4
5
6
7
8
9
本地开发 → git push master → GitHub Actions 触发
                                    ↓
                              npm install
                                    ↓
                              npx hexo generate
                                    ↓
                              SSH Deploy 到服务器
                                    ↓
                              https://dhongli.cloud

GitHub Actions 配置

工作流文件

文件位置：.github/workflows/deploy.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
name: Deploy Hexo

on:
  push:
    branches:
      - master

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install Dependencies
        run: npm install

      - name: Generate Static Files
        run: npx hexo generate

      - name: Deploy to Server
        uses: easingthemes/ssh-deploy@v5.0.3
        with:
          SSH_PRIVATE_KEY: ${{ secrets.SERVER_SSH_KEY }}
          SOURCE: "public/"
          TARGET: "/var/www/hexo"
          REMOTE_HOST: "dhongli.cloud"
          REMOTE_USER: "root"
          ARGS: "-rltgoDzvO --delete"

配置说明

参数说明
on.push.branches触发条件：push 到 master 分支
node-versionNode.js 版本（推荐 22）
SOURCE要部署的目录（hexo generate 生成的 public/）
TARGET服务器目标路径
REMOTE_HOST服务器地址
ARGSrsync 参数，--delete 会删除目标目录中不存在的文件

GitHub Secrets 配置

需要配置的 Secrets

Secret 名称说明获取方式
SERVER_SSH_KEY服务器 SSH 私钥ssh-keygen 生成

生成 SSH 密钥

1
2
3
4
5
6
7
8
# 生成密钥对
ssh-keygen -t ed25519 -C "github-actions"

# 查看私钥（用于 GitHub Secret）
cat ~/.ssh/id_ed25519

# 查看公钥（用于服务器）
cat ~/.ssh/id_ed25519.pub

配置服务器

1
2
3
4
5
6
7
# 在服务器上创建 .ssh 目录
mkdir -p ~/.ssh
chmod 700 ~/.ssh

# 添加公钥到 authorized_keys
echo "公钥内容" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

添加 GitHub Secret

  1. 进入 GitHub 仓库
  2. 点击 Settings → Secrets and variables → Actions
  3. 点击 New repository secret
  4. 名称填写：SERVER_SSH_KEY
  5. 值填写：私钥内容（包括 BEGIN 和 END 行）

GitHub Pages 部署

配置文件

1
2
3
4
5
6
# _config.yml
deploy:
  type: git
  repo: https://github.com/username/username.github.io.git
  branch: main
  message: "Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }}"

安装部署插件

1
npm install hexo-deployer-git --save

部署命令

1
hexo clean && hexo deploy

配置 GitHub Pages

  1. 进入仓库 Settings → Pages
  2. Source 选择 main 分支
  3. 目录选择 / (root)
  4. 保存后等待部署完成

服务器部署

Nginx 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
server {
    listen 80;
    server_name dhongli.cloud;
    root /var/www/hexo;
    index index.html;

    # 首页
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存
    location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css application/json application/javascript text/xml;
}

HTTPS 配置

使用 Let’s Encrypt 免费证书：

1
2
3
4
5
6
7
8
# 安装 certbot
apt install certbot python3-certbot-nginx

# 自动配置 SSL
certbot --nginx -d dhongli.cloud

# 自动续期（certbot 会自动配置 cron）
certbot renew --dry-run

文件权限

1
2
3
# 设置正确的权限
chown -R www-data:www-data /var/www/hexo
chmod -R 755 /var/www/hexo

一键部署

部署到 Heroku

1
2
3
# _config.yml
deploy:
  type: heroku

部署到 Vercel

  1. 连接 GitHub 仓库
  2. 框架选择 Other
  3. Build Command: npx hexo generate
  4. Output Directory: public

部署到 Netlify

  1. 连接 GitHub 仓库
  2. Build Command: npx hexo generate
  3. Publish Directory: public

部署验证

检查构建日志

在 GitHub 仓库 → Actions 标签查看构建状态

检查网站

访问网站确认更新生效

常见问题排查

问题可能原因解决方案
构建失败Node.js 版本不兼容使用 Node.js 22
部署失败SSH 密钥配置错误检查 GitHub Secret
样式丢失CDN 问题检查 CDN 配置
图片不显示路径错误检查图片路径
缓存问题浏览器缓存强制刷新 (Ctrl+F5)

性能优化

构建优化

1
2
3
4
# _config.yml
ignore:
  - source/**/*.psd
  - source/**/*.ai

缓存策略

1
2
3
4
5
6
7
8
9
10
11
# 静态资源长期缓存
location ~* \.(css|js)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# HTML 不缓存
location ~* \.html$ {
    expires -1;
    add_header Cache-Control "no-cache, no-store, must-revalidate";
}

CDN 配置

1
2
3
4
5
# _config.butterfly.yml
CDN:
  internal_provider: local
  third_party_provider: jsdelivr
  version: true

回滚部署

如果部署后发现问题：

1
2
3
4
5
6
7
8
9
10
# 查看最近的提交
git log --oneline -10

# 回滚到指定版本
git revert <commit-hash>
git push origin master

# 或者强制回滚（谨慎使用）
git reset --hard <commit-hash>
git push origin master --force

下一步