沃以的小站

Appearance

服务器部署配置指南 ​

使用 GitHub Actions 自动化部署到自己的 Linux Ubuntu 服务器，支持零停机、原子切换和自动清理

📋 前置要求 ​

  • Linux Ubuntu 服务器（推荐 18.04 LTS 或更新版本）
  • 能够通过 SSH 连接到服务器
  • 本地已安装 Git 和 SSH 工具

当前配置状态 ​

本项目已配置以下环境：

  • 服务器地址: www.woyioii.cn

  • 服务器用户: ubuntu

  • 部署目录: /var/www/blog

  • Web 服务器: Nginx 1.24.0

  • 部署方式: GitHub Actions + SCP/SSH + 原子软链接切换

  • 线上目录结构:

    bash
    /var/www/blog/
├── dist.20251124_100000/     # 自动部署的版本（带时间戳）
├── dist.20251123_235231/
└── current → dist.20251124_100000  # 软链接，Nginx 实际读取入口

🔧 配置步骤 ​

第一步：生成 SSH 密钥 ​

在本地生成 SSH 密钥对：

bash
# 在 Windows PowerShell 或 Linux/Mac 终端中运行
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N ""

查看生成的公钥：

bash
# 显示公钥内容
cat ~/.ssh/id_rsa.pub
# 或在 PowerShell 中
Get-Content $HOME\.ssh\id_rsa.pub

第二步：将公钥添加到服务器 ​

SSH 连接到服务器并添加公钥：

bash
# 1. 连接到服务器
ssh ubuntu@www.woyioii.cn

# 2. 在服务器上创建目录并添加公钥
mkdir -p ~/.ssh
echo "你的公钥内容" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
chmod 700 ~/.ssh

# 3. 退出服务器
exit

第三步：在 GitHub 仓库中配置 Secrets ​

  1. 进入 GitHub 仓库
  2. 点击 Settings → Secrets and variables → Actions
  3. 点击 New repository secret 按钮，添加以下 5 个 Secret：
Secret 名称说明已配置值
SERVER_HOST服务器域名www.woyioii.cn
SERVER_USERSSH 登录用户ubuntu
SERVER_SSH_KEYSSH 私钥内容已配置
SERVER_PORTSSH 端口22
SERVER_DEPLOY_PATH部署目录/var/www/blog

重要提示：

  • SERVER_SSH_KEY 是私钥，请保密！不要在任何地方公开分享
  • 确保私钥内容完整，包括 -----BEGIN OPENSSH PRIVATE KEY----- 和 -----END OPENSSH PRIVATE KEY----- 行

第四步：配置服务器部署目录 ​

创建部署目录并设置权限：

bash
# 创建部署目录
sudo mkdir -p /var/www/blog
sudo chown -R ubuntu:ubuntu /var/www/blog
sudo chmod -R 755 /var/www/blog

第五步：安装和配置 Nginx ​

安装 Nginx：

bash
# 更新包管理器
sudo apt-get update

# 安装 Nginx
sudo apt-get install -y nginx

创建 Nginx 虚拟主机配置：

bash
# 创建配置文件
sudo nano /etc/nginx/sites-available/blog

添加以下配置内容（注意 root 路径）：

nginx
server {
    listen 80;
    server_name www.woyioii.cn woyioii.cn;
    root /var/www/blog/current/dist;   # ← 关键：指向 current/dist
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

启用配置并重新加载 Nginx：

bash
# 创建软链接到 sites-enabled
sudo ln -sf /etc/nginx/sites-available/blog /etc/nginx/sites-enabled/blog

# 禁用默认配置（可选）
sudo rm -f /etc/nginx/sites-enabled/default

# 验证配置
sudo nginx -t

# 重新加载 Nginx
sudo systemctl reload nginx

# 检查 Nginx 状态
sudo systemctl is-active nginx

工作流说明 ​

GitHub Actions 部署工作流文件 ​

部署工作流位于 .github/workflows/deploy-server.yml，包含以下逻辑：

构建阶段（build）：

  • 检出代码
  • 安装 Node.js 20.x
  • 安装 pnpm
  • 安装项目依赖
  • 构建项目（pnpm build）
  • 上传 ./docs/.vitepress/dist 为 artifact

部署阶段（deploy）：

  • 下载构建产物到 ./dist
  • 通过 scp-action 上传到服务器的临时目录：/var/www/blog/dist_new
  • 通过 ssh-action 执行原子切换脚本：
    1. 将 dist_new 重命名为 dist.YYYYMMDD_HHMMSS
    2. 更新软链接 current → dist.新时间戳
    3. 自动清理旧版本（保留最近 3 个）

关键优势：

  • ✅ 零停机部署：软链接切换是原子操作，Nginx 无感知
  • ✅ 自动回滚：旧版本仍存在于磁盘，可手动切换链接回退
  • ✅ 自动清理：避免磁盘被旧构建占满

触发条件：

  • 推送到 master 分支时自动触发
  • 支持通过 GitHub 网页手动触发（workflow_dispatch）

目录结构示例（部署后） ​

bash
/var/www/blog/
├── dist.20251124_100000/
│   └── ...（你的博客静态文件）
├── dist.20251123_235231/
│   └── ...
├── current → dist.20251124_100000   # ← Nginx 读取此链接
└── ...（旧版本自动保留）

工作流流程图 ​

graph TD
    A["🖥️ 本地代码<br/>git push"] --> B["⚙️ GitHub Actions<br/>deploy-server.yml"]

    B --> C["🔨 Build 阶段"]
    B --> D["📤 Deploy 阶段"]

    C --> C1["Checkout 代码"]
    C --> C2["Node.js 20.x"]
    C --> C3["安装 pnpm"]
    C --> C4["安装依赖"]
    C --> C5["构建项目"]
    C --> C6["上传产物"]

    D --> D1["下载构建产物"]
    D --> D2["SCP 上传到 dist_new"]
    D --> D3["SSH 执行原子切换"]
    D3 --> D3a["重命名 dist_new → dist.时间戳"]
    D3 --> D3b["更新 current 软链接"]
    D3 --> D3c["清理旧版本"]

    C6 --> E["🐧 Ubuntu 服务器<br/>www.woyioii.cn"]
    D3 --> E

    E --> F["📁 /var/www/blog/current/dist"]
    F --> G["🌐 Nginx<br/>http://www.woyioii.cn"]

    style A fill:#e1f5ff
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#f3e5f5
    style E fill:#e8f5e9
    style G fill:#c8e6c9

验证部署是否成功 ​

  1. 查看服务器目录：

    bash
    ls -l /var/www/blog/current/dist

  2. 访问网站：https://www.woyioii.cn

  3. 检查 Actions 日志是否绿色通过

相关文档: CICD配置 | 分支策略

上次更新于: