Cloudflare on HanGR的碎碎念

Vinext：用 Vite 替代 Next.js 构建

Sat, 21 Mar 2026 00:00:00 +0000

为什么要迁移到 Vinext

RuiToolAI 最初是用标准 Next.js 开发的。但部署到 Cloudflare Workers 时遇到了一个根本问题：Next.js 需要 Node.js 运行时，Workers 基于 V8 引擎，它们不兼容。

当时只有一个选择：

OpenNext + SST：用 OpenNext 把 Next.js 编译成 Workers 兼容代码

但是，现在有了新的选择：Vinext

Vinext 是什么

2026年2月24日，Cloudflare 正式发布了 Vinext。这也是我们从 OpenNext 迁移过来的直接契机——官方工具出来了，没理由继续用绕弯子的方案。

Vinext 是 Cloudflare 的一个实验性项目，核心思路是：用 Vite 实现 Next.js 的公开 API 接口。

它保留了 Next.js 的 App Router、React Server Components、Server Actions、Route Handlers 等核心功能，但底层构建换成了 Vite。

1
2
3
4
5
6
7
8


# 开发 — 和 Next.js 一样的体验
pnpm dev

# 构建
pnpm build

# 部署
pnpm deploy

选择 Vinext，因为：

Cloudflare 官方维护，长期支持更有保障
Vite 构建速度更快
对 Workers 的原生支持更好

迁移过程

1. 安装 Vinext

1

pnpm add vinext

2. 替换 package.json 里的脚本

1
2
3
4
5
6
7
8


{
 "scripts": {
 "dev": "vinext dev",
 "build": "vinext build",
 "start": "vinext start",
 "deploy": "vinext deploy"
 }
}

3. 创建 worker-entrypoint.ts

Vinext 需要这个文件作为 Workers 的入口：

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


import { getCloudflareContext } from "./src/utils/cloudflare-context";
import { createHandler } from "vinext";

const handler = await createHandler({
 getCloudflareContext,
 // 配置 KV 缓存
 cache: {
 handler: new KVCacheHandler(env.NEXT_INC_CACHE_KV, {
 appPrefix: "ruitoolai",
 }),
 },
});

export default {
 fetch: handler.fetch,
 scheduled: async (event, env, ctx) => {
 ctx.waitUntil(cleanupExpiredImageRecords(env));
 },
};

4. 运行兼容性检查

1

pnpm run check:vinext

这个命令会扫描项目，找出不兼容的代码。比如：

使用了 Node.js 原生模块（fs, net, crypto 等）
使用了 Workers 不支持的 API

5. 修复兼容性问题

主要修复了三类问题：

a) 替换 crypto 模块

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 之前
import crypto from "crypto";
const hash = crypto.createHash("sha256").update(data).digest("hex");

// 之后
const encoder = new TextEncoder();
const data = encoder.encode(input);
const hashBuffer = await crypto.subtle.digest("SHA-256", data);
const hash = Array.from(new Uint8Array(hashBuffer))
 .map(b => b.toString(16).padStart(2, "0"))
 .join("");

b) 替换文件系统操作

Workers 没有 fs 模块，文件操作改为 R2：

1
2
3
4
5
6
7
8


// 之前：本地文件
import fs from "fs";
const buffer = fs.readFileSync("./template.html");

// 之后：R2 存储
const { env } = await getCloudflareContext();
const object = await env.USER_UPLOADS_BUCKET.get("template.html");
const buffer = await object.arrayBuffer();

c) 处理 Edge Runtime 差异

一些中间件和库需要适配 Edge Runtime：

1
2
3
4
5
6


// vite.config.ts
export default defineConfig({
 ssr: {
 noExternal: ["@some-edge-incompatible-lib"],
 },
});

遇到的坑和解决方案

坑 1：`waitUntil` 里的 setTimeout 不生效

Workers 的 setTimeout 不会真正 sleep，导致后台轮询任务瞬间跑完。

解决方案： 改用前端轮询 Server Action。

坑 2：某些 npm 包在构建时报错

部分包在 Vite 构建时报 dynamic require 相关的错误。

解决方案： 在 vite.config.ts 中配置 ssr.noExternal 或 optimizeDeps.exclude。

坑 3：热更新偶尔失效

Vinext 的 dev server 热更新偶尔不生效，需要手动刷新。

解决方案： 这是已知问题，社区正在修复。临时方案是 pnpm dev --force。

性能对比

指标	Next.js + OpenNext	Vinext
开发启动	8-15s	3-5s
构建时间	45-60s	20-30s
热更新	200-500ms	100-300ms
生产包大小	2.5MB	1.8MB
冷启动	500ms	300ms

总结

Vinext 目前还处于实验阶段，但对于 RuiToolAI 这种项目来说，它已经足够稳定。迁移带来的好处是：

构建速度提升 50%
包体积减少 30%
与 Cloudflare Workers 的原生集成

如果你也在用 Next.js + Cloudflare Workers，Vinext 值得一试。但建议先在测试环境跑通完整流程，确认兼容性后再上生产。

参考资源

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

参考资源

Cloudflare Cron 定时任务实战

Wed, 31 Jul 2024 00:00:00 +0000

使用场景

RuiToolAI 的图片生成记录有 7 天有效期，R2 文件会自动删除，但 DB 里的记录不会自动清理。如果不清理，DB 会越来越大，而且历史页面会显示大量"已过期"的空白卡片。

解决方案：用 Cloudflare Cron Triggers 每天定时清理过期记录。

配置 Cron Trigger

在 wrangler.jsonc 中添加：

1
2
3
4
5


{
 "triggers": {
 "crons": ["0 3 * * *"]
 }
}

Cron 表达式格式：分时日月周

表达式	含义
`0 3 * * *`	每天 UTC 凌晨 3 点
`0 /6 * *`	每 6 小时
`0 0 * * 0`	每周日 UTC 0 点
`/5 * * *`	每 5 分钟

实现 scheduled 处理器

在 worker-entrypoint.ts 中添加 scheduled 方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


export default {
 ...worker,
 async scheduled(
 _event: ScheduledEvent,
 env: Env,
 ctx: ExecutionContext
 ): Promise<void> {
 ctx.waitUntil(cleanupExpiredImageRecords(env));
 },
};

注意：这里用 ctx.waitUntil 是正确的，因为 scheduled 处理器本身就是异步的，不像 HTTP 请求有 CPU 时间限制。

自动清理过期图片记录

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


async function cleanupExpiredImageRecords(env: Env): Promise<void> {
 const { drizzle } = await import("drizzle-orm/d1");
 const schema = await import("./src/db/schema");
 const { generatedImageTable, IMAGE_GEN_STATUS } = schema;
 const { lt, eq, and } = await import("drizzle-orm");

 // 直接用 env.NEXT_TAG_CACHE_D1，不用 getDB()
 // 因为 scheduled 处理器里没有 cloudflare:workers 的全局 env
 const db = drizzle(env.NEXT_TAG_CACHE_D1, { schema });
 const now = new Date();

 const result = await db
 .delete(generatedImageTable)
 .where(
 and(
 eq(generatedImageTable.status, IMAGE_GEN_STATUS.COMPLETED),
 lt(generatedImageTable.expiresAt, now),
 ),
 )
 .returning({ id: generatedImageTable.id });

 console.log(`[cron] Cleaned up ${result.length} expired image records.`);
}

为什么不用 getDB()？

getDB() 内部用了 cloudflare:workers 的 env，这个 env 是通过 Cloudflare 的全局上下文注入的，只在 HTTP 请求处理中可用。scheduled 处理器里需要直接用参数传入的 env。

R2 生命周期规则配合

R2 的生命周期规则负责删除文件，Cron 负责清理 DB 记录，两者配合：

R2 设置（Cloudflare Dashboard）：

1
2
3
4


对象生命周期规则
 规则名称：Delete user uploads after 7 days
 前缀：users/
 操作：7 天后删除对象

时间线：

1
2
3


Day 0：用户生成图片 → 存 R2 → DB 记录 expiresAt = Day 7
Day 7：R2 自动删除文件
Day 7 凌晨 3 点：Cron 清理 DB 中 expiresAt < now 的记录

这样 DB 和 R2 都保持干净。

本地调试

先 build 再用 wrangler dev：

1
2
3
4
5
6
7
8
9


# 方法一：部署到 Cloudflare 后在 Dashboard 手动触发
# Workers → 你的 Worker → Triggers → Cron Triggers → Run

# 方法二：本地 wrangler dev（需要先 build）
pnpm build
npx wrangler dev --port 8787

# 然后触发
curl "http://localhost:8787/__scheduled?cron=0+3+*+*+*"

推荐方法一，更简单，而且可以看到真实的 D1 数据。

总结

Cloudflare Cron Triggers 的使用要点：

在 wrangler.jsonc 的 triggers.crons 中配置 Cron 表达式
在 worker-entrypoint.ts 中实现 scheduled 方法
scheduled 处理器里用参数传入的 env，不用全局 env
配合 R2 生命周期规则，实现文件和 DB 记录的双重清理

参考资源

Serverless 架构下的多数据库选型

Thu, 11 Apr 2024 00:00:00 +0000

为什么需要三种数据库

RuiToolAI 是一个全栈 SaaS 平台，数据需求多种多样：

用户数据、订单、积分流水：需要结构化查询、关联查询
Session、API 缓存、页面缓存：需要极快读写、支持过期时间
用户上传的文件、AI 生成的图片：需要存储大文件、支持 CDN 分发

如果用单一数据库，比如全用 D1，反过来 Session 和缓存会拖慢关系型查询；全用 KV，用户订单这种结构化数据没法做关联查询。

所以选择了 D1 + KV + R2 的组合。

D1：关系型数据库

Cloudflare D1 是基于 SQLite 的 Serverless 关系型数据库，兼容 SQLite 语法。

在 RuiToolAI 中的使用

D1 存储所有结构化数据：

1
2
3
4
5
6
7


user # 用户表
session # Session 表（已迁移到 KV）
credit_transaction # 积分流水表
generated_image # 图片生成记录表
cms_entry # CMS 内容表
cms_navigation_node # CMS 导航表
cms_media # CMS 媒体表

集成方式

使用 Drizzle ORM 操作 D1：

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


import { drizzle } from "drizzle-orm/d1";
import { getDB } from "@/db";

const db = getDB();

// 查询
const user = await db.query.userTable.findFirst({
 where: eq(userTable.email, email),
});

// 插入
await db.insert(userTable).values({
 id: `usr_${createId()}`,
 email,
 passwordHash,
 role: "user",
});

局限性

不支持事务：D1 不支持多语句事务，处理退款时要补偿式设计
单文件限制：数据库文件最大 2GB（付费版 10GB）
并发限制：写入并发有限，高并发场景需要设计重试

KV：键值存储

Cloudflare KV 是分布式的键值存储，最终一致性模型，全球秒级同步。

在 RuiToolAI 中的使用

KV 主要用在两个场景：

1. Session 存储

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 存储 Session
await env.NEXT_TAG_CACHE_KV.put(
 `session:${sessionId}`,
 JSON.stringify(sessionData),
 { expirationTtl: 7 * 24 * 60 * 60 } // 7 天过期
);

// 读取 Session
const raw = await env.NEXT_TAG_CACHE_KV.get(`session:${sessionId}`);
const session = raw ? JSON.parse(raw) : null;

2. Vinext 页面缓存

1
2
3
4


// worker-entrypoint.ts
new KVCacheHandler(env.NEXT_INC_CACHE_KV, {
 appPrefix: VINEXT_CACHE_PREFIX
})

Vinext 框架自动用 KV 做 ISR 缓存，每个页面请求都会先查 KV 是否有缓存。

特点

极快读取：全球边缘节点，毫秒级
最终一致性：写入后最多 60 秒同步到全球
免费额度：每天 10 万次读取，1GB 存储

R2：对象存储

Cloudflare R2 是 S3 兼容的对象存储，最大特点是不收出口流量费。

在 RuiToolAI 中的使用

R2 存储所有用户生成的文件：

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


// 存储 AI 生成的图片
await env.USER_UPLOADS_BUCKET.put(r2Key, imageBuffer, {
 httpMetadata: {
 contentType: "image/png",
 contentDisposition: `attachment; filename="${filename}"`,
 },
 customMetadata: {
 prompt: prompt.slice(0, 500),
 generatedBy: userId,
 expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
 },
});

// 读取文件
const object = await env.USER_UPLOADS_BUCKET.get(r2Key);
const buffer = await object.arrayBuffer();

// 删除文件
await env.USER_UPLOADS_BUCKET.delete(r2Key);

生命周期规则

R2 支持自动清理过期文件。在 RuiToolAI 中，设置了 7 天生命周期规则，配合 Cron 定时任务清理 DB 记录：

1
2


R2 规则：uploads/ 前缀，7 天后自动删除
Cron 任务：每天凌晨 3 点，删除 DB 中 expiresAt < now 的记录

选型对比表

特性	D1	KV	R2
数据类型	关系型（SQLite）	键值对	文件/对象
读取速度	快（毫秒级）	极快（毫秒级）	取决于文件大小
一致性	强一致	最终一致	强一致
查询能力	SQL 完整支持	仅 key 查询	前缀/列表
关联查询	支持	不支持	不支持
最大大小	2GB/10GB	1GB（免费）	无限
出口流量费	无	无	无（核心优势）
适合场景	用户数据、订单	缓存、Session	文件存储

实际使用场景

场景一：用户注册

1

用户提交 → D1 INSERT user → KV PUT session → 返回

场景二：AI 图片生成

1

用户提交 → D1 UPDATE credits → D1 INSERT task → Model API → R2 PUT image → D1 UPDATE status

场景三：页面加载

1

用户访问 → KV GET 缓存 → 命中返回 / 未命中 → DB 查询 → 渲染

总结

多数据库不是越多越好，关键是根据数据的访问模式选型：

需要关联查询 → D1
需要极快读写 + 过期 → KV
需要存储大文件 + 免流量 → R2

Cloudflare 的这三件套覆盖了 SaaS 产品 90% 的数据需求，而且全部按量付费，非常适合独立开发者。

参考资源

为什么选择 Cloudflare Workers 而不是传统 VPS

Tue, 26 Mar 2024 00:00:00 +0000

背景

在开发 RuiToolAI 这个全栈 SaaS 项目时，面临一个核心问题：部署在哪里？

传统方案是买一台 VPS（如阿里云、AWS EC2），装 Docker，跑 Node.js 服务。但作为一个独立开发者，我不希望把时间花在运维上。于是我调研了 Cloudflare Workers 这个 Serverless 方案，最终决定把整个项目跑在它上面。

这篇文章就来聊聊为什么做出这个选择，以及实际使用中的经验和教训。

方案对比

传统 VPS 方案

架构：

1

用户 → Nginx → Node.js 服务 → 数据库

优点：

成熟稳定，生态丰富
无运行时限制，可以跑长时间任务
完全控制服务器环境

缺点：

需要自己管理服务器（安全补丁、系统更新、证书续期）
需要自己配置负载均衡和扩容
单地域部署，国内访问国外 VPS 延迟高，反之亦然
费用固定，即使没流量也要付月费

Cloudflare Workers 方案

架构：

1

用户 → Cloudflare 全球边缘节点 → Workers → D1/KV/R2

优点：

全球 330+ 边缘节点，就近响应
零运维，不用管服务器
按量付费，没流量不花钱
D1、KV、R2 原生集成，不需要额外配置连接

缺点：

CPU 时间限制（免费版 10ms，付费版 30s）
不支持 WebSocket 长连接
生态相对较新，部分 npm 包不兼容

Cloudflare Workers 的优势

1. 全球边缘部署，零冷启动

Workers 部署在 Cloudflare 的全球边缘网络上，用户请求会被路由到最近的节点处理。我测试过从国内访问部署在 Workers 上的 RuiToolAI，响应时间在 100-200ms 左右，而同样的应用部署在美西 VPS 上，延迟在 300-500ms。

2. 原生集成 D1/KV/R2

这一点非常重要。传统方案里，你需要：

配置数据库连接字符串
处理连接池
管理文件存储（如 S3 SDK）

而在 Workers 里，这些都是原生 binding：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


const { env } = await getCloudflareContext();

// D1 数据库
const db = getDB();

// KV 缓存
await env.NEXT_INC_CACHE_KV.put(key, value);

// R2 文件存储
await env.USER_UPLOADS_BUCKET.put(key, buffer);

3. GitHub Actions 自动化部署

推送代码到 GitHub → 自动 lint → typecheck → e2e 测试 → 构建 → 部署到 Workers → 执行 D1 迁移。整个过程全自动，不需要手动操作服务器。

成本分析

以 RuiToolAI 为例，目前的使用情况：

服务	免费额度	当前用量	费用
Workers	10 万请求/天	~5000/天	免费
D1	5GB 存储 + 500 万读/天	<1%	免费
KV	1GB 存储 + 10 万读/天	~50%	免费
R2	10GB 存储	<1GB	免费

对比传统 VPS：

最低配置 VPS：$5-10/月
Cloudflare Workers：$0/月（当前用量），流量增长后 $5/月起步

踩过的坑

1. CPU 时间限制导致异步任务失败

最开始我用 waitUntil 在后台轮询 AI 生成结果，但 Workers 的 setTimeout 不会真正 sleep，导致轮询瞬间跑完。

解决方案： 改用前端轮询 Server Action。每次轮询是一个独立请求，不受 30 秒限制。

2. D1 不支持事务

SQLite 在 D1 上不支持多语句事务，这在处理积分退款时很麻烦。

解决方案： 补偿式设计。先扣积分，失败时插入退款记录补充余额。

3. 某些 npm 包不兼容

Workers 不支持 Node.js 原生模块（如 fs、net、crypto 的部分 API）。需要用 Web Crypto API 替代，或者找 Workers 兼容的替代包。

总结

场景	推荐方案
SaaS 产品、API 服务、静态网站	Cloudflare Workers
长时间任务（视频处理、模型训练）	传统 VPS
需要 WebSocket 长连接	传统 VPS
低预算、低流量项目	Cloudflare Workers

对于 RuiToolAI 这种 SaaS 产品，Workers 是完美的选择。零运维、按量付费、全球低延迟，让独立开发者可以专注于产品本身。

Cloudflare on HanGR的碎碎念

Vinext：用 Vite 替代 Next.js 构建

为什么要迁移到 Vinext

Vinext 是什么

迁移过程

1. 安装 Vinext

2. 替换 package.json 里的脚本

3. 创建 worker-entrypoint.ts

4. 运行兼容性检查

5. 修复兼容性问题

遇到的坑和解决方案

坑 1：waitUntil 里的 setTimeout 不生效

坑 2：某些 npm 包在构建时报错

坑 3：热更新偶尔失效

性能对比

总结

参考资源

GitHub Actions 全自动 CI/CD 流水线

流水线设计

基础 CI 配置

Cloudflare Workers 自动部署

Secrets 管理

生成 Cloudflare API Token

e2e 测试集成

数据库迁移自动化

部署通知

完整流水线示例

常见问题排查

问题 1：pnpm install 很慢

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

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

问题 4：e2e 测试超时

总结

参考资源

Cloudflare Cron 定时任务实战

使用场景

配置 Cron Trigger

实现 scheduled 处理器

自动清理过期图片记录

R2 生命周期规则配合

本地调试

总结

参考资源

Serverless 架构下的多数据库选型

为什么需要三种数据库

D1：关系型数据库

在 RuiToolAI 中的使用

集成方式

局限性

KV：键值存储

在 RuiToolAI 中的使用

特点

R2：对象存储

在 RuiToolAI 中的使用

生命周期规则

选型对比表

实际使用场景

场景一：用户注册

场景二：AI 图片生成

场景三：页面加载

总结

参考资源

为什么选择 Cloudflare Workers 而不是传统 VPS

背景

方案对比

传统 VPS 方案

Cloudflare Workers 方案

Cloudflare Workers 的优势

1. 全球边缘部署，零冷启动

2. 原生集成 D1/KV/R2

3. GitHub Actions 自动化部署

成本分析

踩过的坑

1. CPU 时间限制导致异步任务失败

2. D1 不支持事务

3. 某些 npm 包不兼容

总结

参考资源

坑 1：`waitUntil` 里的 setTimeout 不生效