cloudflare

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plan mode: If you are planning work, this entire skill is ONE plan step: "Invoke /vibes:cloudflare". Do not decompose the steps below into separate plan tasks.

计划模式：如果你正在规划工作，整个技能作为一个计划步骤：「调用 /vibes:cloudflare」。不要将以下步骤拆分为单独的计划任务。

Deploy to Cloudflare

部署到Cloudflare

Deploy your Vibes app to Cloudflare Workers with the subdomain registry.

将你的Vibes应用部署到带有子域名注册功能的Cloudflare Workers。

Prerequisites

前置条件

Cloudflare account with Workers enabled
Wrangler CLI installed (
```
npm install -g wrangler
```
)
KV namespace created for registry storage

已启用Workers的Cloudflare账户
已安装Wrangler CLI（
```
npm install -g wrangler
```
）
已创建用于注册存储的KV命名空间

Quick Deploy

快速部署

bash

cd skills/cloudflare/worker
npm install
wrangler deploy

bash

cd skills/cloudflare/worker
npm install
wrangler deploy

Environment Setup

环境配置

Before deploying, set the required secrets:

bash

cd skills/cloudflare/worker
npx wrangler secret put CLERK_PEM_PUBLIC_KEY
npx wrangler secret put CLERK_WEBHOOK_SECRET

部署前，设置所需的密钥：

bash

cd skills/cloudflare/worker
npx wrangler secret put CLERK_PEM_PUBLIC_KEY
npx wrangler secret put CLERK_WEBHOOK_SECRET

Deploy Script

部署脚本

For deploying with static assets (index.html, bundles, assets):

bash

node scripts/deploy-cloudflare.js --name myapp --file index.html --clerk-key "pk_test_xxx"

The

--clerk-key

flag auto-fetches the PEM public key from Clerk's JWKS endpoint and sets it as

CLERK_PEM_PUBLIC_KEY

. Without it, the Worker can't verify JWTs for authenticated endpoints like

/claim

This automatically:

Copies index.html to worker's public/
Copies bundles/*.js (fireproof-vibes-bridge.js + fireproof-clerk-bundle.js)
Copies assets/ directory (images, icons)
Runs wrangler deploy

如需部署包含静态资源（index.html、打包文件、资源）的应用：

bash

node scripts/deploy-cloudflare.js --name myapp --file index.html --clerk-key "pk_test_xxx"

--clerk-key

参数会自动从Clerk的JWKS端点获取PEM公钥，并将其设置为

CLERK_PEM_PUBLIC_KEY

。如果没有该参数，Worker无法验证

/claim

等认证端点的JWT。

该脚本会自动执行以下操作：

将index.html复制到worker的public/目录
复制bundles/*.js文件（fireproof-vibes-bridge.js + fireproof-clerk-bundle.js）
复制assets/目录（图片、图标）
执行wrangler deploy

Endpoints

端点

Endpoint	Method	Description
`/registry.json`	GET	Public registry read
`/check/:subdomain`	GET	Check subdomain availability
`/claim`	POST	Claim a subdomain (auth required)
`/webhook`	POST	Clerk subscription webhooks
`/api/ai/chat`	POST	AI proxy to OpenRouter (requires OPENROUTER_API_KEY)

端点	方法	描述
`/registry.json`	GET	公开注册信息读取
`/check/:subdomain`	GET	检查子域名可用性
`/claim`	POST	认领子域名（需要认证）
`/webhook`	POST	Clerk订阅Webhook
`/api/ai/chat`	POST	指向OpenRouter的AI代理（需要OPENROUTER_API_KEY）

KV Storage

KV存储

The registry is stored in Cloudflare KV under the key

registry

. Schema:

json

{
  "claims": { "subdomain": { "userId": "...", "claimedAt": "..." } },
  "reserved": ["admin", "api", "www"],
  "preallocated": {}
}

注册信息存储在Cloudflare KV中，键为

registry

。数据结构：

json

{
  "claims": { "subdomain": { "userId": "...", "claimedAt": "..." } },
  "reserved": ["admin", "api", "www"],
  "preallocated": {}
}

Important: Custom Domain Required for Subdomains

重要提示：子域名需要自定义域名

Workers.dev domains only support one subdomain level for SSL. For multi-tenant apps with subdomains (tenant.myapp.workers.dev), you MUST use a custom domain.

Won't work:

tenant.myapp.username.workers.dev

(SSL error) Will work:

tenant.myapp.com

(with custom domain)

On workers.dev, use the

?subdomain=

query parameter for testing:

```
myapp.username.workers.dev
```
→ landing page

myapp.username.workers.dev?subdomain=tenant

→ tenant app

myapp.username.workers.dev?subdomain=admin

→ admin dashboard

Workers.dev域名仅支持一级子域名的SSL证书。对于带有子域名的多租户应用（如tenant.myapp.workers.dev），你必须使用自定义域名。

不可用：

tenant.myapp.username.workers.dev

（SSL错误）可用：

tenant.myapp.com

（使用自定义域名）

在workers.dev上，可使用

?subdomain=

查询参数进行测试：

```
myapp.username.workers.dev
```
→ 着陆页

myapp.username.workers.dev?subdomain=tenant

→ 租户应用

myapp.username.workers.dev?subdomain=admin

→ 管理后台

Custom Domain Setup

自定义域名配置

Add domain to Cloudflare (get nameservers from Cloudflare DNS dashboard)
Point registrar nameservers to Cloudflare's assigned nameservers
Delete conflicting DNS records for the apex domain (A, AAAA, CNAME)
Add Custom Domain in Workers & Pages → your worker → Settings → Domains & Routes → Add → Custom Domain (apex: yourdomain.com)
Add wildcard CNAME in DNS: Name:
```
*
```
, Target:
```
<worker-name>.<username>.workers.dev
```
(Proxied: ON)
Add Route in Workers & Pages → your worker → Settings → Domains & Routes → Add → Route:
```
*.yourdomain.com/*
```

After setup:

```
yourdomain.com
```
→ landing page
```
tenant.yourdomain.com
```
→ tenant app
```
admin.yourdomain.com
```
→ admin dashboard

将域名添加到Cloudflare（从Cloudflare DNS控制台获取域名服务器）
将注册商的域名服务器指向Cloudflare分配的域名服务器
删除 apex 域名的冲突DNS记录（A、AAAA、CNAME）
添加自定义域名：在Workers & Pages → 你的worker → 设置 → 域名与路由 → 添加 → 自定义域名（apex：yourdomain.com）
添加通配符CNAME记录：在DNS中，名称：
```
*
```
，目标：
```
<worker-name>.<username>.workers.dev
```
（代理：开启）
添加路由：在Workers & Pages → 你的worker → 设置 → 域名与路由 → 添加 → 路由：
```
*.yourdomain.com/*
```

配置完成后：

```
yourdomain.com
```
→ 着陆页
```
tenant.yourdomain.com
```
→ 租户应用
```
admin.yourdomain.com
```
→ 管理后台

Required Secrets

所需密钥

Secret	Source	Purpose
`CLERK_PEM_PUBLIC_KEY`	Clerk JWKS endpoint	JWT signature verification
`PERMITTED_ORIGINS`	Your domains	JWT azp claim validation
`CLERK_WEBHOOK_SECRET`	Clerk dashboard	Webhook signature verification
`OPENROUTER_API_KEY`	OpenRouter dashboard	AI proxy for `useAI()` hook (optional)

Setting secrets:

bash

cd skills/cloudflare/worker
npx wrangler secret put CLERK_PEM_PUBLIC_KEY

密钥	来源	用途
`CLERK_PEM_PUBLIC_KEY`	Clerk JWKS端点	JWT签名验证
`PERMITTED_ORIGINS`	你的域名	JWT azp声明验证
`CLERK_WEBHOOK_SECRET`	Clerk控制台	Webhook签名验证
`OPENROUTER_API_KEY`	OpenRouter控制台	`useAI()` 钩子的AI代理（可选）

设置密钥：

bash

cd skills/cloudflare/worker
npx wrangler secret put CLERK_PEM_PUBLIC_KEY

Paste the PEM key (-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----)

粘贴PEM密钥（-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----）

npx wrangler secret put CLERK_WEBHOOK_SECRET

Paste the webhook signing secret from Clerk dashboard

粘贴Clerk控制台中的Webhook签名密钥

npx wrangler secret put PERMITTED_ORIGINS

Enter: https://yourdomain.com,https://*.yourdomain.com

输入：https://yourdomain.com,https://*.yourdomain.com


**Getting CLERK_PEM_PUBLIC_KEY:**

1. Find your Clerk Frontend API URL in Clerk dashboard (e.g., `clerk.yourdomain.com`)
2. Fetch JWKS: `curl https://clerk.yourdomain.com/.well-known/jwks.json`
3. Convert JWK to PEM using Node.js:
```javascript
const crypto = require('crypto');
const jwk = { /* paste the key from jwks.json */ };
const pem = crypto.createPublicKey({ key: jwk, format: 'jwk' }).export({ type: 'spki', format: 'pem' });
console.log(pem);


**获取CLERK_PEM_PUBLIC_KEY：**

1. 在Clerk控制台中找到你的Clerk前端API URL（例如：`clerk.yourdomain.com`）
2. 获取JWKS：`curl https://clerk.yourdomain.com/.well-known/jwks.json`
3. 使用Node.js将JWK转换为PEM：
```javascript
const crypto = require('crypto');
const jwk = { /* 粘贴jwks.json中的密钥 */ };
const pem = crypto.createPublicKey({ key: jwk, format: 'jwk' }).export({ type: 'spki', format: 'pem' });
console.log(pem);

Deploy with --name Flag

使用--name参数部署

Always use the

--name

flag to deploy to your app's worker:

bash

node scripts/deploy-cloudflare.js --name myapp --file index.html

Important: The

--name

determines the worker URL. Without it, wrangler uses the name from wrangler.toml (

vibes-registry

), not your app.

请始终使用

--name

参数将应用部署到你的worker：

bash

node scripts/deploy-cloudflare.js --name myapp --file index.html

重要提示：

--name

参数决定了worker的URL。如果不使用该参数，wrangler会使用wrangler.toml中的名称（

vibes-registry

），而不是你的应用名称。

AI Features

AI功能

Apps using the

useAI()

hook call

/api/ai/chat

on the same origin. The worker proxies these requests to OpenRouter.

Deploy with AI enabled:

bash

node scripts/deploy-cloudflare.js --name myapp --file index.html --clerk-key "pk_test_xxx" --ai-key "sk-or-v1-your-key"

The

--ai-key

flag sets the

OPENROUTER_API_KEY

secret on the worker after deployment. Without it,

/api/ai/chat

returns

{"error": "AI not configured"}

Manual setup:

bash

npx wrangler secret put OPENROUTER_API_KEY --name myapp

使用

useAI()

钩子的应用会调用同源的

/api/ai/chat

。Worker会将这些请求代理到OpenRouter。

启用AI功能的部署：

bash

node scripts/deploy-cloudflare.js --name myapp --file index.html --clerk-key "pk_test_xxx" --ai-key "sk-or-v1-your-key"

--ai-key

参数会在部署后为worker设置

OPENROUTER_API_KEY

密钥。如果没有该参数，

/api/ai/chat

会返回

{"error": "AI not configured"}

。

手动配置：

bash

npx wrangler secret put OPENROUTER_API_KEY --name myapp

Paste your OpenRouter API key

粘贴你的OpenRouter API密钥

undefined

undefined