GitHub Actions 全自动 CI/CD 流水线

Wed, 18 Jun 2025 00:00:00 +0000

每次 push 自动跑测试、自动部署到 Cloudflare Workers。这篇记录 RuiToolAI 的 CI/CD 搭建过程。

流水线设计

RuiToolAI 的 CI/CD 分两个阶段：

1
2
3
4
5
6
7


Push to main
 ↓
[CI] Lint + TypeCheck + Unit Tests
 ↓ 通过
[CD] Build + e2e Tests + Deploy to Cloudflare Workers
 ↓ 通过
生产环境更新

PR 只跑 CI，不部署。合并到 main 才触发部署。

基础 CI 配置

 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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


# .github/workflows/ci.yml
name: CI

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

jobs:
 lint-and-typecheck:
 name: Lint & TypeCheck
 runs-on: ubuntu-latest

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

 - name: Setup pnpm
 uses: pnpm/action-setup@v4
 with:
 version: 9

 - name: Setup Node.js
 uses: actions/setup-node@v4
 with:
 node-version: "20"
 cache: "pnpm"

 - name: Install dependencies
 run: pnpm install --frozen-lockfile

 - name: Lint
 run: pnpm run lint

 - name: TypeCheck
 run: pnpm run typecheck

 unit-tests:
 name: Unit Tests
 runs-on: ubuntu-latest
 needs: lint-and-typecheck

 steps:
 - uses: actions/checkout@v4
 - uses: pnpm/action-setup@v4
 with:
 version: 9
 - uses: actions/setup-node@v4
 with:
 node-version: "20"
 cache: "pnpm"
 - run: pnpm install --frozen-lockfile
 - run: pnpm run test

Cloudflare Workers 自动部署

 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
35
36
37
38
39
40
41
42
43


# .github/workflows/deploy.yml
name: Deploy

on:
 push:
 branches: [main]

jobs:
 deploy:
 name: Deploy to Cloudflare Workers
 runs-on: ubuntu-latest
 # 只在 CI 通过后部署
 needs: [lint-and-typecheck, unit-tests]

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

 - name: Setup pnpm
 uses: pnpm/action-setup@v4
 with:
 version: 9

 - name: Setup Node.js
 uses: actions/setup-node@v4
 with:
 node-version: "20"
 cache: "pnpm"

 - name: Install dependencies
 run: pnpm install --frozen-lockfile

 - name: Build
 run: pnpm run build
 env:
 # 构建时需要的环境变量
 NODE_ENV: production

 - name: Deploy to Cloudflare Workers
 run: pnpm run deploy
 env:
 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Secrets 管理

GitHub Actions 里的 Secrets 分两种：

Repository Secrets：只有这个仓库能用
Environment Secrets：绑定到特定环境（production/staging），可以设置审批流程

在 GitHub 仓库 → Settings → Secrets and variables → Actions 里配置。

RuiToolAI 需要的 Secrets：

1
2
3
4


CLOUDFLARE_API_TOKEN # Cloudflare API Token（Workers 部署权限）
CLOUDFLARE_ACCOUNT_ID # Cloudflare 账户 ID
TEST_USER_EMAIL # e2e 测试用的测试账号
TEST_USER_PASSWORD # e2e 测试用的测试密码

生成 Cloudflare API Token

登录 Cloudflare Dashboard
My Profile → API Tokens → Create Token
选择 “Edit Cloudflare Workers” 模板
复制 Token，粘贴到 GitHub Secrets

注意：Token 只显示一次，要立即保存。

e2e 测试集成

e2e 测试需要启动完整的应用，比较耗时，放在单独的 job 里：

 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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


# .github/workflows/e2e.yml
name: E2E Tests

on:
 push:
 branches: [main]

jobs:
 e2e:
 name: End-to-End Tests
 runs-on: ubuntu-latest
 timeout-minutes: 30

 steps:
 - uses: actions/checkout@v4

 - uses: pnpm/action-setup@v4
 with:
 version: 9

 - uses: actions/setup-node@v4
 with:
 node-version: "20"
 cache: "pnpm"

 - run: pnpm install --frozen-lockfile

 # 安装 Playwright 浏览器
 - name: Install Playwright Browsers
 run: pnpm exec playwright install --with-deps chromium

 # 初始化本地测试数据库
 - name: Setup test database
 run: pnpm db:migrate:local

 # 运行 e2e 测试
 - name: Run e2e tests
 run: pnpm test:e2e
 env:
 TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
 TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}

 # 失败时上传报告
 - name: Upload Playwright Report
 uses: actions/upload-artifact@v4
 if: failure()
 with:
 name: playwright-report
 path: playwright-report/
 retention-days: 7

数据库迁移自动化

部署前需要先跑数据库迁移，确保 schema 是最新的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


- name: Run database migrations
 run: pnpm db:migrate:remote
 env:
 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

- name: Deploy to Cloudflare Workers
 run: pnpm run deploy
 env:
 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

package.json 里的迁移命令：

1
2
3
4
5
6


{
 "scripts": {
 "db:migrate:local": "wrangler d1 migrations apply DB --local",
 "db:migrate:remote": "wrangler d1 migrations apply DB --remote"
 }
}

部署通知

部署成功或失败时发通知，方便及时知道状态：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


- name: Notify on success
 if: success()
 run: |
 curl -X POST ${{ secrets.SLACK_WEBHOOK_URL }} \
 -H 'Content-type: application/json' \
 -d '{"text": "✅ RuiToolAI 部署成功！"}'

- name: Notify on failure
 if: failure()
 run: |
 curl -X POST ${{ secrets.SLACK_WEBHOOK_URL }} \
 -H 'Content-type: application/json' \
 -d '{"text": "❌ RuiToolAI 部署失败，请检查 GitHub Actions 日志。"}'

完整流水线示例

把所有 job 整合到一个文件里，用 needs 控制依赖关系：

 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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88


# .github/workflows/main.yml
name: CI/CD

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

jobs:
 # 1. 代码质量检查（所有 push 和 PR 都跑）
 quality:
 name: Lint & TypeCheck
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - uses: pnpm/action-setup@v4
 with: { version: 9 }
 - uses: actions/setup-node@v4
 with: { node-version: "20", cache: "pnpm" }
 - run: pnpm install --frozen-lockfile
 - run: pnpm run lint
 - run: pnpm run typecheck

 # 2. 单元测试
 test:
 name: Unit Tests
 runs-on: ubuntu-latest
 needs: quality
 steps:
 - uses: actions/checkout@v4
 - uses: pnpm/action-setup@v4
 with: { version: 9 }
 - uses: actions/setup-node@v4
 with: { node-version: "20", cache: "pnpm" }
 - run: pnpm install --frozen-lockfile
 - run: pnpm run test

 # 3. e2e 测试（只在 main 分支跑）
 e2e:
 name: E2E Tests
 runs-on: ubuntu-latest
 needs: test
 if: github.ref == 'refs/heads/main'
 steps:
 - uses: actions/checkout@v4
 - uses: pnpm/action-setup@v4
 with: { version: 9 }
 - uses: actions/setup-node@v4
 with: { node-version: "20", cache: "pnpm" }
 - run: pnpm install --frozen-lockfile
 - run: pnpm exec playwright install --with-deps chromium
 - run: pnpm db:migrate:local
 - run: pnpm test:e2e
 env:
 TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
 TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
 - uses: actions/upload-artifact@v4
 if: failure()
 with:
 name: playwright-report
 path: playwright-report/
 retention-days: 7

 # 4. 部署（只在 main 分支，所有测试通过后）
 deploy:
 name: Deploy
 runs-on: ubuntu-latest
 needs: [test, e2e]
 if: github.ref == 'refs/heads/main'
 steps:
 - uses: actions/checkout@v4
 - uses: pnpm/action-setup@v4
 with: { version: 9 }
 - uses: actions/setup-node@v4
 with: { node-version: "20", cache: "pnpm" }
 - run: pnpm install --frozen-lockfile
 - run: pnpm run build
 - name: Run DB migrations
 run: pnpm db:migrate:remote
 env:
 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
 - name: Deploy to Workers
 run: pnpm run deploy
 env:
 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

常见问题排查

问题 1：pnpm install 很慢

加缓存：

1
2
3
4


- uses: actions/setup-node@v4
 with:
 node-version: "20"
 cache: "pnpm" # 这行很重要

问题 2：Playwright 浏览器每次都重新下载

1
2
3
4
5
6
7
8


- name: Cache Playwright browsers
 uses: actions/cache@v4
 with:
 path: ~/.cache/ms-playwright
 key: playwright-${{ runner.os }}-${{ hashFiles('**/package.json') }}

- name: Install Playwright Browsers
 run: pnpm exec playwright install --with-deps chromium

问题 3：部署失败但没有详细错误信息

1
2
3
4
5
6


- name: Deploy
 run: pnpm run deploy
 env:
 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 # 加上 --verbose 看详细日志
 # 或者检查 wrangler 版本是否兼容

问题 4：e2e 测试超时

1
2
3


jobs:
 e2e:
 timeout-minutes: 30 # 增加超时时间

总结

CI/CD 流水线的核心原则：

快速反馈：Lint 和 TypeCheck 最快，先跑；e2e 最慢，最后跑
依赖关系：用 needs 控制 job 顺序，测试通过才部署
分支策略：PR 只跑 CI，main 分支才部署
Secrets 安全：敏感信息放 GitHub Secrets，不要硬编码
失败保留证据：上传测试报告，方便排查

GitHubActions on HanGR的碎碎念