GitHub Actions+Caddy实现前端项目自动化部署到公网服务器

GitHub-Actions-Caddy-自动化部署

在现代前端开发中，自动化部署已成为提高开发效率的关键环节。本文将详细介绍如何利用GitHub Actions和Caddy服务器，实现前端项目的完全自动化部署，让你的代码从推送到仓库到上线的整个过程无人值守。

我们将实现的目标是：代码推送到GitHub后，自动完成构建、部署并上线，部署目标是您自己的公网服务器。

自动化部署方案概述

在开始之前，让我们先了解一下整个自动化部署流程的架构：

这套方案的核心优势在于：

• 完全自动化 ：推送代码后无需任何人工干预
• 安全可靠 ：使用SSH密钥进行安全传输
• 自动HTTPS ：Caddy自动申请和续期SSL证书
• 高效部署 ：只传输构建后的静态资源

GitHub Actions工作流配置

首先，我们需要在项目中创建GitHub Actions工作流文件，用于定义自动化部署的各个步骤。

创建工作流文件

在项目根目录下创建.github/workflows/deploy.yml文件：

name: Deploy Frontend to Server

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Install Node and Build
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: |
          npm ci
          npm run build

      - name: Deploy to Server via SSH
        uses: appleboy/scp-action@v0.1.4
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          source: "dist/*"
          target: "/var/www/myapp"

      - name: Restart Caddy
        uses: appleboy/ssh-action@v0.1.10
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            systemctl reload caddy

配置GitHub Secrets

为了让GitHub Actions能够安全地访问服务器，我们需要配置以下Secrets：

1. 进入GitHub仓库
2. 点击Settings选项卡
3. 在左侧菜单中选择Secrets and variables > Actions
4. 点击New repository secret添加以下密钥：

Secret名称	示例值	说明
SERVER_IP	49.235.xxx.xx	服务器公网IP地址
SERVER_USER	root或ubuntu	服务器登录用户名
SSH_PRIVATE_KEY	PEM格式私钥内容	SSH登录私钥

请确保私钥具有足够权限访问服务器部署目录，并且在服务器上已配置好对应的公钥。

SSH密钥配置

生成SSH密钥对：

# 在本地生成SSH密钥对
ssh-keygen -t rsa -b 4096 -C "github-actions-deploy"

# 将公钥内容添加到服务器的authorized_keys中
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

# 设置正确的文件权限
chmod 600 ~/.ssh/authorized_keys

私钥内容（id_rsa文件内容）需要添加到GitHub Secrets的SSH_PRIVATE_KEY中。

服务器配置：Caddy安装与设置

Caddy是一款现代化的Web服务器，以其简洁的配置和自动HTTPS功能而闻名。

Caddy安装

在Ubuntu/Debian系统上安装Caddy：

# 安装必要的依赖
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https

# 添加Caddy官方GPG密钥
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo tee /etc/apt/trusted.gpg.d/caddy-stable.asc

# 添加Caddy软件源
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# 更新包列表并安装Caddy
sudo apt update
sudo apt install caddy -y

配置Caddyfile

编辑Caddy配置文件（通常位于/etc/caddy/Caddyfile）：

yourdomain.com {
    root * /var/www/myapp
    file_server
    encode gzip

    # 安全头部设置
    header X-Content-Type-Options nosniff
    header X-Frame-Options DENY
    header X-XSS-Protection "1; mode=block"

    # 临时解决跨域问题（根据需要调整）
    header Access-Control-Allow-Origin "*"
    header Access-Control-Allow-Methods "GET, POST, OPTIONS"
    header Access-Control-Allow-Headers "Content-Type, Authorization"
}

启动Caddy服务

# 启动Caddy服务
sudo systemctl start caddy

# 设置Caddy开机自启
sudo systemctl enable caddy

# 检查Caddy状态
sudo systemctl status caddy

域名解析与HTTPS配置

要让用户能够通过域名访问你的应用，需要进行域名解析配置。

域名解析设置

在你的域名服务商（腾讯云、阿里云、Cloudflare等）管理界面中添加A记录：

• 主机记录：@
• 记录类型：A
• 记录值：你的服务器IP地址（例如49.235.xxx.xx）
• TTL：默认值即可

配置完成后，等待DNS解析生效（通常需要几分钟到几小时不等），然后就可以通过域名访问你的应用了。

自动HTTPS

Caddy最大的优势之一是自动HTTPS功能：

• 当Caddy检测到有域名的站点配置时，会自动向Let’s Encrypt申请SSL证书
• 证书会自动续期，无需手动干预
• 所有HTTP请求会自动重定向到HTTPS

这意味着你不需要手动配置证书，Caddy会处理一切与SSL相关的工作。

高级配置：反向代理与跨域处理

如果你的前端应用需要与后端API交互，但受到跨域限制，可以通过Caddy的反向代理功能解决。

反向代理配置

修改Caddyfile，添加反向代理规则：

yourdomain.com {
    root * /var/www/myapp
    file_server

    # 将API请求代理到后端服务器
    reverse_proxy /api/* https://backend.example.com {
        header_up Host backend.example.com
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }

    # CORS配置
    @cors_preflight method OPTIONS
    respond @cors_preflight 204

    header Access-Control-Allow-Origin "*"
    header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
    header Access-Control-Allow-Headers "Content-Type, Authorization"
    header Access-Control-Allow-Credentials true
}

多环境部署配置

对于需要多环境部署的项目，可以扩展GitHub Actions工作流：

name: Deploy Frontend to Server

on:
  push:
    branches:
      - main
      - develop

jobs:
  determine-environment:
    runs-on: ubuntu-latest
    outputs:
      environment: ${{ steps.env.outputs.environment }}
      domain: ${{ steps.env.outputs.domain }}
    steps:
      - name: Determine environment
        id: env
        run: |
          if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
            echo "environment=production" >> $GITHUB_OUTPUT
            echo "domain=yourdomain.com" >> $GITHUB_OUTPUT
          else
            echo "environment=staging" >> $GITHUB_OUTPUT
            echo "domain=staging.yourdomain.com" >> $GITHUB_OUTPUT
          fi

  build-and-deploy:
    needs: determine-environment
    runs-on: ubuntu-latest
    environment: ${{ needs.determine-environment.outputs.environment }}
    
    steps:
      # ... 构建和部署步骤 ...

部署流程回顾与最佳实践

部署流程全回顾

第一步

本地开发完成，代码推送到GitHub仓库

第二步

GitHub Actions自动检测到代码推送，触发工作流

第三步

在GitHub Actions虚拟机中安装依赖并构建项目

第四步

通过SCP将构建产物上传到服务器指定目录

第五步

执行SSH命令重启Caddy服务，使新部署生效

第六步

用户通过HTTPS域名访问最新的应用版本

部署优化建议

1. 构建缓存 ：使用GitHub Actions的缓存功能，加速构建过程
2. 部署回滚 ：保留上一个版本的部署文件，必要时快速回滚
3. 部署通知 ：集成Slack、微信等通知，及时获取部署状态
4. 健康检查 ：添加部署后的健康检查，确保服务正常

故障排除

常见问题与解决方案

1. SSH连接失败

   • 检查SSH密钥是否正确配置
   • 确认服务器防火墙设置允许SSH连接
   • 验证GitHub Secrets中的IP和用户名是否正确

2. 构建失败

   • 检查package.json中的构建脚本是否正确
   • 确认Node.js版本与项目需求兼容
   • 查看GitHub Actions日志定位具体错误

3. Caddy服务异常

   • 检查Caddyfile语法是否正确
   • 使用systemctl status caddy查看服务状态
   • 通过journalctl -u caddy查看详细日志

4. HTTPS证书问题

   • 确认域名DNS解析已正确指向服务器
   • 检查服务器80端口是否可访问（Let’s Encrypt验证需要）
   • 验证域名所有权是否正确配置

总结

通过GitHub Actions和Caddy的组合，我们实现了：

• 完全自动化 ：推送即部署，无需人工干预
• 安全传输 ：基于SSH的安全文件传输
• 自动HTTPS ：Caddy自动申请和续期SSL证书
• 灵活扩展 ：支持多环境、多站点的部署方案

这套方案不仅适用于个人项目，也能满足中小型团队的生产环境需求。随着项目规模的增长，你还可以基于这个基础架构进一步扩展，比如集成测试、性能监控、自动化通知等功能。

持续部署是现代软件开发的重要组成部分，希望本文提供的方案能帮助你的项目实现高效、可靠的自动化部署流程。

---

持续优化部署流程，提升开发效率