GitHub Actions 在小型网站的最佳实践

GitHub Actions 实践指南：从零到部署 ishwe

基于 eshwe 项目的真实部署经历，记录从零配置 CI/CD 的完整过程，包括原理讲解、踩坑记录和解决方案。

1. 什么是 GitHub Actions

GitHub Actions 是 GitHub 内置的 CI/CD 平台。简单来说：

你 push 代码 → GitHub 自动帮你执行预定义的命令

对于 ishwe 项目，流程是：

git push origin master
        ↓
GitHub 检测到代码变更
        ↓
自动 SSH 到你的服务器
        ↓
执行 git pull + docker compose up -d --build
        ↓
服务器上的容器自动更新

你不需要手动 SSH 到服务器，不需要手动执行任何部署命令。 推送代码 = 部署。

2. 核心概念

2.1 Workflow（工作流）

工作流就是一个 YAML 文件，放在 .github/workflows/ 目录下。GitHub 会自动读取并执行。

.github/
  workflows/
    deploy.yml    ← 这就是工作流

ishwe 的工作流文件：.github/workflows/deploy.yml

2.2 Trigger（触发器）

工作流什么时候执行？由 on 字段定义：

on:
  push:
    branches: [master]        # 推送到 master 分支时触发
    paths:                     # 只有这些路径下的文件变更才触发
      - "backend/**"
      - "frontend/**"
      - "docker-compose.yml"

为什么用 paths 过滤？ 如果你只改了 README.md，没必要重新部署。只有前后端代码或 Docker 配置变了才触发部署。

2.3 Job（任务）

一个工作流可以包含多个 Job，默认并行执行。每个 Job 运行在一个独立的虚拟机上（称为 Runner）。

jobs:
  deploy:           # Job 名称
    runs-on: ubuntu-latest   # 使用 Ubuntu 虚拟机
    steps:                   # 该 Job 包含的步骤
      - name: Deploy
        run: echo "deploying..."

2.4 Step（步骤）

每个 Job 由多个 Step 组成，按顺序执行。

steps:
  - name: 第一步
    run: echo "step 1"
  - name: 第二步
    run: echo "step 2"      # 第一步完成后才执行

2.5 Action（动作）

Action 是可复用的步骤，别人写好的，你直接用。格式是 用户名/仓库名@版本。

steps:
  - uses: actions/checkout@v4          # 官方的，拉取代码
  - uses: appleboy/ssh-action@v1       # 第三方的，SSH 执行命令

2.6 Secrets（密钥）

敏感信息（密码、API Key）不能写在 YAML 里（仓库是公开的）。GitHub 提供了 Secrets 功能：

在仓库 Settings → Secrets and variables → Actions 中添加
在 YAML 中通过 ${{ secrets.名称 }} 引用
日志中会自动显示为 ***

3. ishwe 的 CI/CD 架构

最终方案

┌─────────────────────────────────────────────────────┐
│                    GitHub 仓库                       │
│                                                     │
│   代码变更 → push to master → 触发 deploy.yml        │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│              GitHub Actions Runner                   │
│              (GitHub 提供的虚拟机)                    │
│                                                     │
│   1. SSH 连接到你的服务器                             │
│   2. 执行部署命令                                    │
└──────────────────────┬──────────────────────────────┘
                       │ SSH
                       ▼
┌─────────────────────────────────────────────────────┐
│              你的服务器 (xxx.xx.xxx.xx)               │
│                                                     │
│   git fetch origin master                           │
│   git reset --hard FETCH_HEAD                       │
│   docker compose up -d --build --force-recreate     │
│                                                     │
│   ┌─────────┐  ┌─────────┐  ┌──────────────┐      │
│   │ backend │  │frontend │  │  OpenResty   │      │
│   │ :8000   │  │ :3000   │  │  (Nginx)     │      │
│   └─────────┘  └─────────┘  │  :8080       │      │
│                              └──────────────┘      │
└─────────────────────────────────────────────────────┘

为什么不需要单独构建镜像？

你可能会问：CI/CD 不是应该先构建镜像再推送到镜像仓库吗？

这是两种不同的部署模式：

模式	流程	适用场景
镜像仓库模式	CI 构建镜像 → 推送到 GHCR/Docker Hub → 服务器拉取	大型项目、多服务器、需要版本管理
源码构建模式	服务器 git pull → docker compose build → 重启	小型项目、单服务器、简单直接

ishwe 用的是源码构建模式。GitHub Actions 的 Runner 只是一个"遥控器"，通过 SSH 在你的服务器上执行命令。真正的构建发生在你的服务器上。

完整的 deploy.yml

name: Build & Deploy

on:
  push:
    branches: [master]
    paths:
      - "backend/**"
      - "frontend/**"
      - "docker-compose.yml"
      - ".github/workflows/deploy.yml"

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to server
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          password: ${{ secrets.SERVER_PASSWORD }}
          script: |
            cd /home/ubuntu/ishwe
            git config --global http.version HTTP/1.1
            git fetch origin master
            git reset --hard FETCH_HEAD
            sudo docker compose up -d --build --force-recreate
            sudo docker image prune -f

逐行解释：

on:
  push:
    branches: [master]    # 只在推送到 master 时触发
    paths:                 # 只在这些文件变更时触发
      - "backend/**"       # backend 目录下的任何文件
      - "frontend/**"      # frontend 目录下的任何文件
      - "docker-compose.yml"
      - ".github/workflows/deploy.yml"

steps:
  - uses: appleboy/ssh-action@v1    # 使用 SSH 执行远程命令的 Action
    with:
      host: ${{ secrets.SERVER_HOST }}       # 从 Secrets 读取服务器 IP
      username: ${{ secrets.SERVER_USER }}   # SSH 用户名
      password: ${{ secrets.SERVER_PASSWORD }} # SSH 密码

script: |
  cd /home/ubuntu/ishwe           # 进入项目目录
  git config --global http.version HTTP/1.1  # 修复 TLS 问题
  git fetch origin master         # 拉取最新代码
  git reset --hard FETCH_HEAD     # 强制同步到最新版本
  sudo docker compose up -d --build --force-recreate  # 重建并启动
  sudo docker image prune -f      # 清理旧镜像释放磁盘

4. 从零开始配置

4.1 准备工作

你需要：

一个 GitHub 仓库（ishwe 代码已推送）
一台 Linux 服务器（已安装 Docker）
服务器上已 clone 了仓库

4.2 配置 GitHub Secrets

这是最关键的一步。 在浏览器中操作：

打开 GitHub 仓库页面（如 https://github.com/Pronting/eisenhower）
点击 Settings（顶部标签栏最右边）
左侧菜单找到 Secrets and variables → 点击 Actions
点击 New repository secret，逐个添加：

Name	Value	说明
`SERVER_HOST`	`xxx.xx.xxx.xx`	你的服务器 IP
`SERVER_USER`	`ubuntu`	SSH 用户名
`SERVER_PASSWORD`	`你的密码`	SSH 密码

每添加一个点 Add secret。添加完成后，这些值会被加密存储，YAML 中通过 ${{ secrets.SERVER_HOST }} 引用。

4.3 设置工作流权限

Settings → Actions → General
往下滚到 Workflow permissions
选择 Read and write permissions
点 Save

这一步允许 GitHub Actions 对仓库进行写操作。如果以后需要推送构建产物到仓库（如 GHCR 镜像），需要这个权限。

4.4 创建工作流文件

在项目根目录创建：

.github/
  workflows/
    deploy.yml

写入上面的完整 YAML 内容。

4.5 提交并推送

git add .github/workflows/deploy.yml
git commit -m "ci: 添加 GitHub Actions 自动部署"
git push origin master

4.6 查看部署状态

打开 GitHub 仓库页面
点击顶部 Actions 标签
你会看到一个正在运行的工作流（黄色圆圈 = 运行中）
点进去可以看实时日志
绿色勾 = 成功，红色叉 = 失败

从推送代码到部署完成，通常需要 2-5 分钟（主要是 docker compose build 中 pip install 耗时）。

5. 踩坑记录与解决方案

以下是我们在部署 ishwe 过程中遇到的所有问题，按出现顺序记录。

5.1 SSH 权限不足

现象：

permission denied while trying to connect to the Docker daemon socket
at unix:///var/run/docker.sock

原因： SSH 登录的用户（ubuntu）没有 Docker 权限。Docker daemon 的 socket 文件只有 root 和 docker 组用户才能访问。

解决： 在 docker compose 命令前加 sudo。

# 错误
docker compose up -d --build

# 正确
sudo docker compose up -d --build

永久解决（可选）： 在服务器上执行 sudo usermod -aG docker $USER，然后重新登录。

5.2 git pull 失败 — TLS 协议错误

现象：

fatal: unable to access 'https://github.com/Pronting/eisenhower.git/':
GnuTLS recv error (-110): The TLS connection was non-properly terminated.

原因： 服务器的 git 使用 HTTP/2 协议与 GitHub 通信，某些网络环境下 HTTP/2 不稳定（尤其在国内服务器）。

解决： 在 git pull 或 git fetch 前设置 git 使用 HTTP/1.1。

script: |
  git config --global http.version HTTP/1.1   # 加这一行
  git fetch origin master

注意： git config --global 修改的是 ~/.gitconfig 文件，对当前用户永久生效。但通过 SSH 非交互式执行时，某些环境下配置可能不持久。建议每次都设置一次。

5.3 git pull 冲突

现象：

error: Your local changes to the following files would be overwritten by merge

原因： 服务器上有一些本地修改（比如手动改过 docker-compose.yml），导致 git pull 失败。

解决： 使用 git fetch + git reset --hard 替代 git pull。

# 不推荐：可能冲突
git pull origin master

# 推荐：强制同步，不会冲突
git fetch origin master
git reset --hard FETCH_HEAD

区别：

git pull = git fetch + git merge，merge 可能冲突
git fetch + git reset --hard = 直接覆盖本地代码，不会冲突

注意： git reset --hard 会丢弃服务器上的所有本地修改。确保服务器上没有需要保留的改动。

5.4 pip 依赖版本冲突

现象：

ERROR: Cannot install pydantic==2.5.2 because these package versions
have conflicting dependencies.

langchain 1.2.15 depends on pydantic>=2.7.4
pydantic-settings 2.1.0 depends on pydantic>=2.3.0

原因： requirements.txt 用 == 锁定了旧版本，但 langchain 的新版本需要更高版本的 pydantic。

这是最常见的 Python 项目依赖问题。 根本原因是 requirements.txt 中的版本组合本身就有内在冲突，只是之前构建的 Docker 镜像缓存了旧依赖，没暴露出来。

解决： 将 == 改为 >=，让 pip 自动解析兼容版本。

# 错误：锁定旧版本
pydantic==2.5.2
pydantic-settings==2.1.0
langchain==1.2.15

# 正确：允许升级
pydantic>=2.7.4
pydantic-settings>=2.10.1
langchain>=1.2.15

如何找到正确的版本？ 查看服务器上正在运行的容器里实际安装的版本：

docker exec <容器名> pip list | grep <包名>

5.5 pip 下载超时/失败 — 国内网络问题

现象：

ERROR: Could not find a version that satisfies the requirement
websockets>=10.4 (from versions: none)

原因： 服务器在国内，访问 PyPI（Python 包仓库）不稳定，某些包下载超时或被墙。

解决： 在 Dockerfile 中配置国内镜像源。

FROM python:3.12-slim

WORKDIR /app
# 添加这两行：配置阿里云 pip 镜像
RUN pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ && \
    pip config set global.trusted-host mirrors.aliyun.com
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

注意： 这个配置必须写在 Dockerfile 里，不能只在宿主机上配置。因为 docker build 运行在容器内部，宿主机的 pip 配置对容器不生效。

常用的国内 pip 镜像：

镜像	地址
阿里云	https://mirrors.aliyun.com/pypi/simple/
清华	https://pypi.tuna.tsinghua.edu.cn/simple
腾讯	https://mirrors.cloud.tencent.com/pypi/simple

5.6 前端构建失败 — 模块找不到

现象：

Module not found: Can't resolve '@/components/Header'
Module not found: Can't resolve '@/i18n/LanguageContext'

原因： .dockerignore 文件排除了 tsconfig.json。Next.js 的 @/ 路径别名是在 tsconfig.json 中定义的：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

没有这个文件，webpack 就不知道 @/ 映射到哪里。

解决： 从 .dockerignore 中移除 tsconfig.json。

# 错误：排除了构建必需的文件
node_modules
.next
tsconfig.json        # ← 这行要删掉

# 正确：只排除真正不需要的文件
node_modules
.next
.env.local
.env*.local

教训： .dockerignore 要谨慎配置。排除文件前，先想想 Docker 构建时是否需要它。构建时需要的文件（如 tsconfig.json、package.json）绝不能排除。

5.7 容器时区不对 — 定时任务偏差 8 小时

现象： 用户设置 09:00 推送邮件，实际 17:00 才收到。偏差正好 8 小时。

原因： Docker 容器默认使用 UTC 时区，而用户在中国（UTC+8）。

服务器宿主机: Asia/Shanghai (UTC+8)  → datetime.now() = 09:00
Docker 容器:  UTC (UTC+0)            → datetime.now() = 01:00

代码中 datetime.now() 返回的是容器本地时间。容器以为 01:00 是凌晨，等到 UTC 09:00（北京时间 17:00）才触发推送。

解决： 在 docker-compose.yml 中设置容器时区。

services:
  backend:
    environment:
      - TZ=Asia/Shanghai    # 添加这一行

验证：

# 查看容器时间
docker exec <容器名> date

# 对比宿主机时间
date

两者应该一致。

注意： TZ 环境变量只对支持它的程序有效。Python 的 datetime.now() 会读取 TZ，所以对 ishwe 有效。

5.8 docker compose 配置变更不生效

现象： 修改了 docker-compose.yml（比如添加了 TZ=Asia/Shanghai），但 docker compose up -d 后容器没有重建。

原因： docker compose up -d 只在镜像变化或容器配置有实质变化时才重建。某些情况下它检测不到变化。

解决： 使用 --force-recreate 强制重建。

# 可能不重建
docker compose up -d

# 强制重建
docker compose up -d --force-recreate

在 CI/CD 中，建议始终使用 --force-recreate，确保配置变更一定会生效。

5.9 git ref 锁文件残留

现象：

error: cannot lock ref 'refs/remotes/origin/master': is at fe49777
but expected 785718a

原因： 之前的 git 操作异常中断，留下了锁文件。

解决：

rm -f .git/refs/remotes/origin/master.lock
git fetch origin master
git reset --hard FETCH_HEAD

5.10 `script_stop` 参数不支持

现象：

Warning: Unexpected input(s) 'script_stop'

原因： appleboy/ssh-action@v1 不支持 script_stop 参数（这是 v3 才有的）。

解决： 删除这个参数，或升级 Action 版本。

# 错误
- uses: appleboy/ssh-action@v1
  with:
    script_stop: true    # ← 不支持

# 正确：删除 script_stop
- uses: appleboy/ssh-action@v1
  with:
    script: |
      ...

6. GitHub Actions 常见问题解答

Q: 创建 `.github/workflows/xxx.yml` 就能自动 CI/CD？

是的。 GitHub 会自动扫描仓库中的 .github/workflows/ 目录。只要 YAML 文件语法正确，GitHub 就会：

读取 on 字段，确定触发条件
当条件满足时（如 push to master），自动创建一个 Workflow Run
分配一个 Runner（虚拟机），执行 YAML 中定义的步骤

你不需要在 GitHub 网页上做任何额外配置。 创建文件 + push = 生效。

Q: 为什么有了 docker-compose.yml 就能自动构建？

不是 docker-compose.yml 触发的自动构建。 是 GitHub Actions 触发的。

docker-compose.yml 只是一个配置文件，告诉 Docker "怎么组合多个容器"。它本身不会自动执行任何东西。

真正的流程是：

GitHub Actions (触发)
    → SSH 到服务器 (执行)
        → docker compose up -d --build (docker-compose.yml 生效)

docker-compose.yml 中的 build: ./backend 指令告诉 Docker："从 ./backend/Dockerfile 构建镜像"。docker compose up -d --build 会读取这个配置并执行构建。

Q: `paths` 过滤是怎么工作的？

on:
  push:
    paths:
      - "backend/**"
      - "frontend/**"

backend/** 是 glob 模式，匹配 backend/ 目录下的所有文件（递归）。

backend/app/main.py → 匹配 ✅ → 触发工作流
frontend/src/page.tsx → 匹配 ✅ → 触发工作流
README.md → 不匹配 ❌ → 不触发

注意： paths 是 OR 关系。只要任一路径匹配，就触发。

Q: `${{ secrets.XXX }}` 是怎么工作的？

你在 GitHub 网页上添加 Secret，值被加密存储
工作流运行时，GitHub 自动解密并注入环境变量
YAML 中的 ${{ secrets.XXX }} 被替换为实际值
日志中显示为 ***，不会泄露

安全限制：

Fork 的仓库无法访问原仓库的 Secrets
Pull Request 中修改的 workflow 无法访问 Secrets（防止恶意代码窃取）

Q: Runner 是什么？

Runner 就是 GitHub 提供的虚拟机，用来执行你的工作流。

GitHub-hosted Runner： GitHub 提供，runs-on: ubuntu-latest 就是用这个
Self-hosted Runner： 你自己的机器，需要额外配置

ishwe 用的是 GitHub-hosted Runner。它是一个干净的 Ubuntu 虚拟机，每次运行完就销毁。

Q: 工作流运行失败了怎么办？

打开 GitHub 仓库 → Actions 标签
点击失败的 Workflow Run（红色叉图标）
点击具体的 Job
展开失败的 Step，查看日志
根据错误信息修复代码或配置
再次 push 触发新的运行

Q: 怎么手动触发工作流？

在 YAML 中添加 workflow_dispatch：

on:
  push:
    branches: [master]
  workflow_dispatch:    # 添加这一行

然后在 GitHub 仓库 → Actions 页面，选择该工作流，点击 "Run workflow"。

7. 经验总结

7.1 Docker 相关

经验	说明
始终设置 `TZ` 环境变量	避免时区问题，尤其定时任务相关
`.dockerignore` 要仔细检查	构建需要的文件绝不能排除
国内服务器配 pip/npm 镜像	写在 Dockerfile 里，不是宿主机
用 `>=` 而非 `==` 锁定依赖	避免版本冲突，但要测试兼容性
`--force-recreate` 确保配置生效	`docker compose up -d` 可能不重建

7.2 Git 相关

经验	说明
用 `fetch + reset --hard` 替代 `pull`	避免冲突，适合 CI/CD 场景
每次设置 `http.version HTTP/1.1`	防止国内服务器 TLS 错误
不要在服务器上手动改代码	改了也会被 `reset --hard` 覆盖

7.3 GitHub Actions 相关

经验	说明
密钥用 Secrets 存储	绝不写在 YAML 或代码里
`paths` 过滤减少无意义部署	只在相关文件变更时触发
Action 版本要看清楚	v1 和 v3 参数可能不同
日志是最好的调试工具	失败了看 Actions 日志

7.4 ishwe 项目的特殊经验

经验	说明
服务器上要有 `.env` 文件	包含 JWT_SECRET、API Key 等
`docker-compose.yml` 的 `env_file` 引用 `.env`	密钥通过环境变量传入容器
1Panel OpenResty 做反向代理	8080 → 3000 (前端)，/api → 8000 (后端)
`deploy_ssh.py` 不要提交到 Git	含明文密码，已加入 `.gitignore`

附录：ishwe deploy.yml 完整演进历史

第一版：基础版

script: |
  cd /home/ubuntu/ishwe
  git pull origin master
  docker compose up -d --build

失败原因： SSH 用户没有 Docker 权限，git pull TLS 错误

第二版：加 sudo

script: |
  cd /home/ubuntu/ishwe
  git pull origin master
  sudo docker compose up -d --build

失败原因： git pull 仍然 TLS 错误

第三版：加 HTTP/1.1

script: |
  cd /home/ubuntu/ishwe
  git config --global http.version HTTP/1.1
  git pull origin master
  sudo docker compose up -d --build

失败原因： git pull 冲突（服务器有本地修改）

第四版：用 fetch + reset

script: |
  cd /home/ubuntu/ishwe
  git config --global http.version HTTP/1.1
  git fetch origin master
  git reset --hard FETCH_HEAD
  sudo docker compose up -d --build

失败原因： pip 依赖冲突（pydantic 版本问题）

第五版：修复依赖 + 镜像源

（同时修改了 requirements.txt 和 Dockerfile）

失败原因： 前端 .dockerignore 排除了 tsconfig.json

第六版：修复 .dockerignore

失败原因： docker compose 没有重建容器（配置变更不生效）

第七版（最终版）：加 --force-recreate

script: |
  cd /home/ubuntu/ishwe
  git config --global http.version HTTP/1.1
  git fetch origin master
  git reset --hard FETCH_HEAD
  sudo docker compose up -d --build --force-recreate
  sudo docker image prune -f

成功。

posted @ 2026-05-18 21:33 叫授_pront 阅读(28) 评论(0) 收藏举报

刷新页面返回顶部

pronting

GitHub Actions 在小型网站的最佳实践

GitHub Actions 实践指南：从零到部署 ishwe

目录

1. 什么是 GitHub Actions

2. 核心概念

2.1 Workflow（工作流）

2.2 Trigger（触发器）

2.3 Job（任务）

2.4 Step（步骤）

2.5 Action（动作）

2.6 Secrets（密钥）

3. ishwe 的 CI/CD 架构

最终方案

为什么不需要单独构建镜像？

完整的 deploy.yml

4. 从零开始配置

4.1 准备工作

4.2 配置 GitHub Secrets

4.3 设置工作流权限

4.4 创建工作流文件

4.5 提交并推送

4.6 查看部署状态

5. 踩坑记录与解决方案

5.1 SSH 权限不足

5.2 git pull 失败 — TLS 协议错误

5.3 git pull 冲突

5.4 pip 依赖版本冲突

5.5 pip 下载超时/失败 — 国内网络问题

5.6 前端构建失败 — 模块找不到

5.7 容器时区不对 — 定时任务偏差 8 小时

5.8 docker compose 配置变更不生效

5.9 git ref 锁文件残留

5.10 script_stop 参数不支持

6. GitHub Actions 常见问题解答

Q: 创建 .github/workflows/xxx.yml 就能自动 CI/CD？

Q: 为什么有了 docker-compose.yml 就能自动构建？

Q: paths 过滤是怎么工作的？

Q: ${{ secrets.XXX }} 是怎么工作的？

Q: Runner 是什么？

Q: 工作流运行失败了怎么办？

Q: 怎么手动触发工作流？

7. 经验总结

7.1 Docker 相关

7.2 Git 相关

7.3 GitHub Actions 相关

7.4 ishwe 项目的特殊经验

附录：ishwe deploy.yml 完整演进历史

第一版：基础版

第二版：加 sudo

第三版：加 HTTP/1.1

第四版：用 fetch + reset

第五版：修复依赖 + 镜像源

第六版：修复 .dockerignore

第七版（最终版）：加 --force-recreate

公告

5.10 `script_stop` 参数不支持

Q: 创建 `.github/workflows/xxx.yml` 就能自动 CI/CD？

Q: `paths` 过滤是怎么工作的？

Q: `${{ secrets.XXX }}` 是怎么工作的？