# 上线清单 · 从零到能用 AI 的薪火网站

> 给一个不一定会写代码的人看的"动手清单"。完整跑完<strong>大约 3 小时</strong>，<strong>第一个月花费约 $20-30</strong>（之后看孩子用量）。
>
> 你可以一个人做完，也可以找一个会一点编程的朋友 / 学生陪你做（很多步骤是"账号注册 + 复制粘贴一个命令"）。

---

## 总览：6 个阶段

| 阶段 | 干什么 | 时间 | 花钱 |
|---|---|---|---|
| 1. 注册账号 | Cloudflare、Groq、OpenRouter、HuggingFace 各注册一个 | 30 分钟 | 免费 |
| 2. 充值 / 拿 API key | 给 OpenRouter 充 $10，其它免费拿 key | 15 分钟 | $10 |
| 3. 部署 Worker | 装命令行工具，按一个命令把后端部署到云上 | 45 分钟 | 免费（Cloudflare 免费层够） |
| 4. 配置自有域名（可选） | 让 worker 用你自己的域名（如 ai.kindling.com） | 30 分钟 | $10/年（域名）或 $0（用免费的 .workers.dev） |
| 5. 改前端 | 把网站里的 endpoint 指向你的 worker | 15 分钟 | 免费 |
| 6. 测试 + 监控 | 跑通几个真请求，第一周看用量 | 持续 | $5-10 工具费/月 |

**第一个月总花费**：约 **$20-30**（含域名）。
**之后每月**：取决于孩子用量；1000 孩子级别约 **$30-50/月**。

---

# 阶段 1 · 注册 4 个账号（30 分钟）

每个都是免费注册。建议<strong>用同一个邮箱</strong>方便管理。

## 1.1 Cloudflare（部署 Worker 用）

1. 打开 [https://dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up)
2. 邮箱 + 密码注册，验证邮件
3. 不需要充值，免费层完全够用

✅ 拿到：Cloudflare 账号（后面 `wrangler login` 时会自动登录这个账号）

## 1.2 Groq（默认主力 AI）

1. 打开 [https://console.groq.com](https://console.groq.com)
2. 用 Google 账号或邮箱注册（免邮箱验证）
3. 进入后点 "API Keys" → "Create API Key"
4. 复制 key，存到一个安全的地方（比如密码管理器）

格式：`gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx`

✅ 拿到：`GROQ_API_KEY`（免费，30 req/min/IP，质量很好的 Llama 3.3 70B）

## 1.3 OpenRouter（多模型聚合，付费）

1. 打开 [https://openrouter.ai](https://openrouter.ai)
2. 用 Google 账号注册
3. 进 Settings → Credits → "Buy credits"
4. **充 $10**（最少额度，够万次调用）
5. Settings → Keys → "Create Key"，复制

格式：`sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

✅ 拿到：`OPENROUTER_API_KEY`（充 $10，能调 200+ 模型，包括 Claude / GPT / Qwen / DeepSeek）

> **省钱小招**：在 OpenRouter Settings → Limits 里设个 hard cap，比如每月不超 $30 —— 防止 worker 出 bug 烧光预算。

## 1.4 HuggingFace（embedding 用）

1. 打开 [https://huggingface.co/join](https://huggingface.co/join)
2. 邮箱注册，验证
3. 进 Settings → Access Tokens → "New token"
4. Token name 写 `kindling-edu`，Type 选 **Read**
5. 复制 token

格式：`hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxx`

✅ 拿到：`HF_TOKEN`（免费，用于中文 embedding）

---

# 阶段 2 · 总结（15 分钟）

打开你电脑里的"密码管理器"或者一个加密的笔记软件，存：

```
=== 薪火 AI 部署用 keys ===
GROQ_API_KEY        = gsk_...
OPENROUTER_API_KEY  = sk-or-v1-...
HF_TOKEN            = hf_...
Cloudflare 账号     = your-email@example.com
=========================
```

⚠️ <strong>千万别</strong>把这些贴到 GitHub、聊天群、或者任何公开地方。被盗用别人会烧你的钱。

---

# 阶段 3 · 部署 Worker（45 分钟）

需要在你电脑上装一个命令行工具，然后跑 4 个命令。

## 3.1 装 Node.js（如果还没装）

打开 [https://nodejs.org](https://nodejs.org)，下 LTS 版本，一路下一步装上。

验证：在命令行（Windows: PowerShell；Mac: Terminal）跑：

```bash
node -v
# 应该输出 v20.x.x 之类
```

## 3.2 装 Wrangler（Cloudflare 官方部署工具）

```bash
npm install -g wrangler
wrangler --version
# 应该输出 ⛅️ wrangler 3.x.x
```

## 3.3 登录 Cloudflare

```bash
wrangler login
# 会自动打开浏览器，点 "Allow"
```

## 3.4 进入 worker 目录

```bash
cd "D:\in UTD\Dropbox\AI research\课程网站\Kindling\final website in 中文\kindling-iteration-2\worker"
```

（路径根据你电脑实际情况改）

## 3.5 创建 KV namespace（用于限流计数）

```bash
wrangler kv:namespace create "KV"
# 输出类似：
# 🌀 Creating namespace with title "kindling-ai-KV"
# ✨ Success!
# Add the following to your configuration file:
# [[kv_namespaces]]
# binding = "KV"
# id = "abc123def456..."
```

打开 `wrangler.toml`，找到 `id = "REPLACE_WITH_YOUR_KV_ID"`，把 `REPLACE_WITH_YOUR_KV_ID` 替换成上面输出的 id。

## 3.6 设置 3 个 secret（API key 不写在代码里）

```bash
wrangler secret put GROQ_API_KEY
# 它会问 "Enter a secret value:"，粘贴 gsk_... 那串，回车

wrangler secret put OPENROUTER_API_KEY
# 粘贴 sk-or-v1-... 回车

wrangler secret put HF_TOKEN
# 粘贴 hf_... 回车
```

## 3.7 部署！

```bash
wrangler deploy
# 输出类似：
# Total Upload: 12.34 KiB / gzip: 4.56 KiB
# Uploaded kindling-ai (1.23 sec)
# Deployed kindling-ai triggers (0.45 sec)
#   https://kindling-ai.<你的-username>.workers.dev
```

✅ <strong>记住这个 URL</strong> —— 这是你的 worker 地址，前端要用。

## 3.8 测试一下

```bash
# 健康检查
curl https://kindling-ai.<你的-username>.workers.dev/v1/health
# 输出：{"ok":true,"costToday":"0.00"}

# 试一次真聊天
curl -X POST https://kindling-ai.<你的-username>.workers.dev/v1/chat \
  -H "Content-Type: application/json" \
  -H "Origin: https://kindling-edu.com" \
  -d '{"system":"你是恐龙小专家","user":"霸王龙能跑多快？","stream":false}'
# 应该输出 AI 答案
```

✅ 如果两个都跑通 → <strong>后端上线了</strong>。

---

# 阶段 4 · 配自己的域名（可选，30 分钟）

如果你不在乎 URL 长什么样，可以跳过这一步，直接用 `kindling-ai.<你的-username>.workers.dev`。

如果你想用 `ai.kindling.com` 这种漂亮的：

## 4.1 买一个域名（如果还没有）

去 [Cloudflare Registrar](https://dash.cloudflare.com/?to=/:account/registrar)（最便宜、不加价）或 Namecheap：
- `.com` 域名约 $10/年
- 推荐买 `kindling-edu.com` 或 `xinhuo-ai.com` 之类

## 4.2 把域名指向 Cloudflare

如果是在 Cloudflare 买的 → 自动指好。
如果在别处买的 → 在 Cloudflare 添加 site，按提示改 nameservers。

## 4.3 改 wrangler.toml

把 `wrangler.toml` 里的：
```
# routes = [
#   { pattern = "ai.kindling-edu.com/*", zone_name = "kindling-edu.com" }
# ]
```
改成（去掉 # 注释，把域名改成你的）：
```
routes = [
  { pattern = "ai.你的域名.com/*", zone_name = "你的域名.com" }
]
```

## 4.4 同时改 ALLOWED_ORIGINS

```toml
[vars]
ALLOWED_ORIGINS = "https://你的网站域名.com,http://localhost:5173"
```

## 4.5 重新部署

```bash
wrangler deploy
```

现在 `https://ai.你的域名.com/v1/chat` 就能用了。

---

# 阶段 5 · 改前端（15 分钟）

让薪火网站使用你的 worker。

## 5.1 改 SDK 默认 endpoint

打开 `kindling-iteration-2/kindling-ai-sdk.js`，第 14 行：

```js
const ENDPOINT = (SCRIPT && SCRIPT.dataset.endpoint) ||
                 global.KINDLING_AI_ENDPOINT ||
                 'https://ai.kindling-edu.com';   // ← 改成你的 worker 地址
```

把 `'https://ai.kindling-edu.com'` 改成你的实际 worker 地址，比如：
- `'https://kindling-ai.your-username.workers.dev'`
- 或 `'https://ai.你的域名.com'`

## 5.2 测试 4 个原型

打开浏览器，逐个开：
1. `kindling-iteration-2/prototype-chat.html` —— 试聊天，应该出真 AI 回答（不是模拟）
2. `kindling-iteration-2/prototype-judge.html` —— 试判官打分
3. `kindling-iteration-2/prototype-image.html` —— 试图像生成（如果失败，可能 Cloudflare AI binding 没启用，看下面排错）
4. `kindling-iteration-2/prototype-voice.html` —— 试语音输入（用 Chrome）

✅ 4 个都能跑 → 前端连上了。

## 5.3 改主网站（可选 · 但建议）

把所有"复制 + 跳 Qwen"的页面升级。最直接的两条路：

**A. 手动改一个看效果**：
打开 `kindling-middle-level/projects/code-01-real-page.html`，按 `INTEGRATION.md` 里的样例，把 demo 里的"复制 prompt"改成"直接 fetch worker"。

**B. 批量自动改**：
跑这个 Python 脚本（但记得先 git commit 一下当前状态）：
```bash
cd "D:\in UTD\Dropbox\AI research\课程网站\Kindling\final website in 中文"
python kindling-iteration-2/scripts/inject-sdk.py
```
（这个脚本不存在 —— 是我建议你之后写的；先手动改 1-2 页看效果）

---

# 阶段 6 · 测试 + 监控（持续）

## 6.1 第一天测试 checklist

- [ ] 健康检查能通：`curl .../v1/health`
- [ ] 自己浏览器开 prototype-chat.html → 能看到真 AI 答
- [ ] 用一个孩子的设备试一次 → 能用
- [ ] 故意刷 35 次 → 第 31 次开始返回 429（限流生效）
- [ ] 关掉 wifi，看 SDK 是否回落到友好错误（"网络不通，请检查"）

## 6.2 监控第一周

每天看一下：

**Cloudflare Workers Dashboard**：
- [https://dash.cloudflare.com](https://dash.cloudflare.com) → Workers & Pages → kindling-ai
- 看 "Requests" 和 "CPU time"
- 免费层每天 100k 请求，看你用了多少

**OpenRouter Activity**：
- [https://openrouter.ai/activity](https://openrouter.ai/activity)
- 看每天烧了多少钱
- 如果第一周内已经 > $10 → 说明流量比预期大，提前给 OpenRouter 加额度，或调整路由让更多走 Groq 免费层

**Groq Dashboard**：
- [https://console.groq.com/usage](https://console.groq.com/usage)
- Groq 免费层很慷慨（30 req/min/IP），看是否经常打到上限

## 6.3 异常告警（强烈建议）

装个免费的 uptime 监控：

1. 注册 [Better Uptime](https://betteruptime.com)（免费 10 个监控）
2. 加一个 monitor：
   - URL：`https://ai.你的域名.com/v1/health`
   - Check every：5 分钟
   - 通知方式：邮箱 + 手机 push
3. 服务挂了你 5 分钟内会收到通知

## 6.4 成本告警（重要）

在 Cloudflare 主账号设置：
- Notifications → Add → "Worker Limit Approaching"
- 在 OpenRouter Settings 设 monthly hard cap = $50（看你愿意承担多少）

这两个加起来 = 钱不会突然爆。

---

# 常见问题

## Q1：我完全不会编程，能搞定吗？

老实说：阶段 3（部署 Worker）需要会用命令行 + 复制粘贴 5-6 个命令。
**建议**：找一个会一点 Python / Node / 命令行的高中生 / 大学生陪你 1-2 个小时（按 1-2 杯咖啡报酬就够了）。
之后阶段 4-6 你完全可以自己做。

## Q2：API key 被盗了怎么办？

立刻去对应平台 dashboard：
- Groq → Console → API Keys → 旁边的 ✕ 删掉
- OpenRouter → Settings → Keys → Delete
- HuggingFace → Settings → Access Tokens → Revoke

然后<strong>重新生成新 key + 重新 `wrangler secret put`</strong>。整个过程 5 分钟。
（这就是为什么我们用 wrangler secret 而不是写在代码里 —— 永远可以滚密钥不重新部署。）

## Q3：流量超过预算怎么办？

worker 自带每日 $30 硬上限，超了自动只走免费层。
但你也可以加更狠的：在 worker.ts 改 `if (todayCost > 30)` 中的 30 → 改成你想要的上限。

## Q4：图像生成的 Cloudflare AI 怎么开？

部署后，进 Dashboard → Workers & Pages → kindling-ai → Settings → Bindings → 应该看到 AI binding 已自动加上。
如果没有，手动添加 → Add → AI → Variable name `AI`，重新部署。

## Q5：我能不能完全不用 OpenRouter，就用 Groq 免费层？

可以！流量不大的话（每天 < 1000 次调用）Groq 免费层完全够。
那就跳过阶段 1.3，把 worker.ts 里所有引用 OpenRouter 的地方注释掉或删掉。
$0 上线、0 维护成本。

## Q6：上线之后怎么改 worker？

```bash
cd worker/
# 改 worker.ts
wrangler deploy
# 几秒钟内全球生效
```

无痛。

---

# 一份"真上线第一天"的迷你计划表

```
9:00 am  注册 Cloudflare、Groq、HF（30 分钟）
9:30 am  注册 OpenRouter，充 $10（10 分钟）
9:40 am  把 4 个 key 存到密码管理器（5 分钟）
9:45 am  装 Node.js + Wrangler（15 分钟）
10:00 am wrangler login + 创 KV + 设 secrets（15 分钟）
10:15 am wrangler deploy → 拿到 worker URL（5 分钟）
10:20 am curl 测试 → 看到真 AI 答（5 分钟）

（如果买域名走完阶段 4：再 + 30 分钟）

10:25 am 改 SDK 的 endpoint，改一个 prototype 试试（10 分钟）
10:35 am 用真用户（家人 / 学生）的设备试 5 个问题（10 分钟）

11:00 am ✅ 上线庆祝。

下午 / 这周：
- 把"复制 + 跳转"的项目页改 1-2 个，看孩子反应
- 装 Better Uptime 监控
- 第一周每天看一次用量
```

---

# 总结：上线后你拥有什么

- ✅ 一个 24×7 跑的 AI 后端，全球低延迟（Cloudflare 网络）
- ✅ 5 大 AI 能力（chat / judge / image / vision / voice）
- ✅ 防滥用 + 防爆预算的护栏
- ✅ 完全自有，不依赖任何第三方平台的 UI
- ✅ 孩子<strong>零注册</strong>就能用 AI

第一个月成本：**$20-30**。之后每月：**$30-80**（看用量）。

完全可负担、完全可控、完全用得起。

> 有任何阶段卡住，回到 `worker/README.md` 或 `RESEARCH.md` 看更详细的解释。
> 也可以问 AI（Claude / Qwen）："我在按薪火 LAUNCH-CHECKLIST.md 走，跑到 X 步报错 Y，怎么办？"—— 一般几句对话就能解决。