# Cloudflare Pages 部署指南

`禾新农事 AI / FieldFlow AI` 使用 Cloudflare Pages 托管静态站点，并使用 Pages Functions 作为 Kimi API 的安全服务端代理。GitHub Pages 仍可用于纯静态预览，但不能承载本项目的 AI 接口。

## 部署前检查

在本地运行：

```powershell
python scripts\run_acceptance.py
```

确认以下文件存在：

```text
functions/api/planting-plan.js
functions/api/image-triage.js
functions/api/_shared.js
```

## 连接 GitHub

1. 将项目推送至 GitHub 仓库 `hexin-agri-ai`；第一阶段建议仓库保持私有。
2. 进入 Cloudflare Dashboard 的 `Workers & Pages`。
3. 选择 `Create application -> Pages -> Connect to Git`。
4. 授权 GitHub 并选择仓库。
5. Framework preset 选择 `None`；Build command 留空；Build output directory 填 `.`；Production branch 选择 `main`。
6. 点击 `Save and Deploy`，确认生成 `https://hexin-agri-ai.pages.dev` 或同类地址。

## 添加 Kimi 密钥

首次部署成功后，进入 Pages 项目：

```text
Settings -> Variables and Secrets -> Add
```

创建：

```text
Type: Secret
Variable name: KIMI_API_KEY
Value: 在 Kimi Open Platform 创建的 API Key
```

保存并点击 `Deploy`。密钥只能放在 Cloudflare Secret，不能放入 `src/`、`functions/`、`.env`、截图或 GitHub 仓库。

## 演示成本保护

- Kimi 项目预算：每日 2 元、每月 20 元。
- 后端：每个 IP、每个功能每天最多 3 次请求。
- 种植计划：输出最多 600 Token；图像初筛：输出最多 500 Token。
- 超过限额、模型超时、结构校验失败或安全审查失败时，前端自动展示规则方案。
- 图片会在浏览器压缩到最长边 1280px，去除 EXIF；只在用户点击分析后转发，项目不保存原图。

## 发布后验收

1. 打开公开站点并生成一次 AI 种植计划。
2. 上传一张授权的叶片图片，点击 AI 图像初筛。
3. 确认结果中没有农药名、精确剂量或确定性确诊结论。
4. 在 Kimi 控制台确认只有预期的少量调用记录。
5. 在 Cloudflare Dashboard 检查部署日志；不要记录完整图片或 API Key。

## 密钥泄露应对

如果 Key 曾进入聊天、浏览器控制台、截图或 Git 提交：立即在 Kimi 控制台删除该 Key，创建新 Key，并更新 Cloudflare Secret 后重新部署。

不使用命令行的完整操作步骤见 `docs/GITHUB_DESKTOP_CLOUDFLARE_CHECKLIST.md`。