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

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

---

目录

1. 什么是 GitHub Actions
2. 核心概念
3. ishwe 的 CI/CD 架构
4. 从零开始配置
5. 踩坑记录与解决方案
6. GitHub Actions 常见问题解答
7. 经验总结

---

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 功能：

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

---

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

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

1. 打开 GitHub 仓库页面（如 https://github.com/Pronting/eisenhower）
2. 点击 Settings（顶部标签栏最右边）
3. 左侧菜单找到 Secrets and variables → 点击 Actions
4. 点击 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 设置工作流权限

1. Settings → Actions → General
2. 往下滚到 Workflow permissions
3. 选择 Read and write permissions
4. 点 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 查看部署状态

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

从推送代码到部署完成，通常需要 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 就会：

1. 读取 on 字段，确定触发条件
2. 当条件满足时（如 push to master），自动创建一个 Workflow Run
3. 分配一个 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 }} 是怎么工作的？

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

安全限制：

• 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: 工作流运行失败了怎么办？

1. 打开 GitHub 仓库 → Actions 标签
2. 点击失败的 Workflow Run（红色叉图标）
3. 点击具体的 Job
4. 展开失败的 Step，查看日志
5. 根据错误信息修复代码或配置
6. 再次 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

成功。

---