CI/CD on HanGR的碎碎念

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，不要硬编码
失败保留证据：上传测试报告，方便排查

参考资源

Vitest + Playwright 全栈 e2e 测试实战

Wed, 23 Apr 2025 00:00:00 +0000

测试不是可选项。这篇记录 RuiToolAI 的测试体系搭建，以及踩过的 SQLite 并发锁这个大坑。

测试策略

RuiToolAI 的测试分两层：

层级	工具	覆盖范围
单元/集成测试	Vitest	工具函数、Server Actions、数据库操作
e2e 测试	Playwright	完整用户流程（注册、登录、生成图片）

原则：e2e 测试覆盖核心用户旅程，单元测试覆盖复杂业务逻辑。 不追求 100% 覆盖率，追求关键路径不出错。

Vitest 单元测试配置

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


// vitest.config.ts
import { defineConfig } from "vitest/config";
import path from "path";

export default defineConfig({
 test: {
 environment: "node",
 globals: true,
 setupFiles: ["./src/test/setup.ts"],
 },
 resolve: {
 alias: {
 "@": path.resolve(__dirname, "./src"),
 },
 },
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// src/test/setup.ts
import { beforeAll, afterAll } from "vitest";

// 全局测试前置
beforeAll(async () => {
 // 初始化测试数据库
});

afterAll(async () => {
 // 清理
});

Playwright e2e 测试配置

 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


// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
 testDir: "./e2e",
 fullyParallel: true,
 forbidOnly: !!process.env.CI,
 retries: process.env.CI ? 2 : 0,
 workers: process.env.CI ? 1 : undefined,
 reporter: "html",

 use: {
 baseURL: "http://localhost:3000",
 trace: "on-first-retry",
 },

 projects: [
 {
 name: "chromium",
 use: { ...devices["Desktop Chrome"] },
 },
 ],

 // 测试前启动开发服务器
 webServer: {
 command: "pnpm dev",
 url: "http://localhost:3000",
 reuseExistingServer: !process.env.CI,
 timeout: 120 * 1000,
 },
});

测试数据库隔离

e2e 测试不能用生产数据库，需要独立的测试数据库。

在 Cloudflare Workers 本地开发环境里，Wrangler 会自动创建本地 SQLite 文件：

1
2
3


.wrangler/state/v3/d1/
└── <database-id>/
 └── db.sqlite ← 本地测试用这个

测试前需要初始化 schema：

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


// e2e/fixtures/db.ts
import { execSync } from "child_process";

export function setupTestDb() {
 // 应用所有迁移
 execSync("pnpm db:migrate:local", { stdio: "inherit" });
}

export function cleanTestDb() {
 // 清理测试数据
 execSync(
 'wrangler d1 execute DB --local --command "DELETE FROM users WHERE email LIKE \'%test%\'"',
 { stdio: "inherit" }
 );
}

SQLite 并发锁问题及解决

这是我踩过最深的坑。

问题现象

CI 里 e2e 测试随机失败，错误信息：

1

SqliteError: database is locked

原因分析

Vitest 默认并行运行多个测试文件，每个文件在独立的 Worker 线程里执行。多个线程同时写同一个 SQLite 文件，就会出现锁冲突。

SQLite 的写锁是文件级别的，同一时刻只允许一个写操作。

解决方案

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


// vitest.e2e.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
 test: {
 // 关键：禁用文件级并行，改为串行执行
 fileParallelism: false,
 // 只用一个 Worker
 maxWorkers: 1,
 // 测试文件内部的测试用例仍然可以并行
 // （但写数据库的测试用例最好也串行）
 },
});

代价是测试速度变慢，但在 CI 里稳定性更重要。

为什么之前没问题？

本地开发时，测试文件少，并发冲突概率低。CI 里测试文件多，并发冲突必然发生。

常用测试模式

测试 Server Action

 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


// src/app/(auth)/sign-up/sign-up.actions.test.ts
import { describe, it, expect, beforeEach } from "vitest";
import { signUpAction } from "./sign-up.actions";

describe("signUpAction", () => {
 it("应该成功注册新用户", async () => {
 const result = await signUpAction({
 email: "test@example.com",
 password: "Password123!",
 });

 expect(result?.data?.success).toBe(true);
 });

 it("应该拒绝已存在的邮箱", async () => {
 // 先注册一次
 await signUpAction({
 email: "existing@example.com",
 password: "Password123!",
 });

 // 再注册同一个邮箱
 const result = await signUpAction({
 email: "existing@example.com",
 password: "Password123!",
 });

 expect(result?.serverError).toBeDefined();
 });
});

Playwright 测试登录流程

 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


// e2e/auth.spec.ts
import { test, expect } from "@playwright/test";

test.describe("认证流程", () => {
 test("用户可以注册并登录", async ({ page }) => {
 // 访问注册页
 await page.goto("/sign-up");

 // 填写表单
 await page.fill('[name="email"]', "e2e-test@example.com");
 await page.fill('[name="password"]', "TestPassword123!");

 // 提交
 await page.click('[type="submit"]');

 // 验证跳转到 dashboard
 await expect(page).toHaveURL("/dashboard");
 await expect(page.locator("h1")).toContainText("欢迎");
 });

 test("错误密码应该显示错误提示", async ({ page }) => {
 await page.goto("/sign-in");
 await page.fill('[name="email"]', "user@example.com");
 await page.fill('[name="password"]', "wrongpassword");
 await page.click('[type="submit"]');

 await expect(page.locator('[role="alert"]')).toBeVisible();
 });
});

测试需要认证的页面

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// e2e/fixtures/auth.ts
import { test as base, expect } from "@playwright/test";

// 扩展 test，自动登录
export const test = base.extend({
 page: async ({ page }, use) => {
 // 登录
 await page.goto("/sign-in");
 await page.fill('[name="email"]', process.env.TEST_USER_EMAIL!);
 await page.fill('[name="password"]', process.env.TEST_USER_PASSWORD!);
 await page.click('[type="submit"]');
 await page.waitForURL("/dashboard");

 await use(page);
 },
});

export { expect };

1
2
3
4
5
6
7


// e2e/history.spec.ts
import { test, expect } from "./fixtures/auth";

test("历史页面应该显示生成记录", async ({ page }) => {
 await page.goto("/history");
 await expect(page.locator("h1")).toContainText("生成历史");
});

使用 Page Object Model

对于复杂页面，用 Page Object Model 封装操作：

 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


// e2e/pages/image-gen.page.ts
import { Page } from "@playwright/test";

export class ImageGenPage {
 constructor(private page: Page) {}

 async goto() {
 await this.page.goto("/image-gen");
 }

 async generateImage(prompt: string) {
 await this.page.fill("textarea", prompt);
 await this.page.click('[data-testid="generate-button"]');
 }

 async waitForGeneration() {
 // 等待生成完成（最多 60 秒）
 await this.page.waitForSelector('[data-testid="generated-image"]', {
 timeout: 60000,
 });
 }

 async getGeneratedImageUrl() {
 return this.page
 .locator('[data-testid="generated-image"]')
 .getAttribute("src");
 }
}

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


// e2e/image-gen.spec.ts
import { test, expect } from "./fixtures/auth";
import { ImageGenPage } from "./pages/image-gen.page";

test("用户可以生成图片", async ({ page }) => {
 const imageGenPage = new ImageGenPage(page);
 await imageGenPage.goto();
 await imageGenPage.generateImage("a beautiful sunset over the ocean");
 await imageGenPage.waitForGeneration();

 const imageUrl = await imageGenPage.getGeneratedImageUrl();
 expect(imageUrl).toBeTruthy();
});

CI 里运行测试

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


# .github/workflows/ci.yml
- 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 test results
 uses: actions/upload-artifact@v4
 if: failure()
 with:
 name: playwright-report
 path: playwright-report/
 retention-days: 7

测试失败时上传报告，方便排查问题。

总结

全栈测试体系的关键点：

分层测试：单元测试覆盖逻辑，e2e 测试覆盖用户旅程
数据库隔离：测试用独立的本地 SQLite，不污染生产数据
串行执行：SQLite 不支持并发写，fileParallelism: false 是必须的
Page Object Model：复杂页面封装操作，测试代码更易维护
CI 上传报告：失败时保留截图和 trace，方便排查