日常工作知识库

Appearance

Cloudflare 混合部署模式与 Wrangler CLI 运维指南 ​

本指南主要总结 panjiayuan-helper 项目在 Cloudflare 平台上的混合部署模式（Hybrid Deployment）、服务调用链路，并详细拓展了 npx wrangler CLI 的高频用法，以方便后续的日常运维和故障排查。

一、 混合部署架构与现状链路 ​

在实际的边缘云部署中，panjiayuan-helper 并没有将前端和后端绑定在同一种 CI/CD 流程中，而是采用了**“前端自动化联动 + 后端本地命令行推送”**的混合部署架构。

1. 架构拓扑概览 ​

2. 前后端部署机制对比 ​

模块部署方式现状与自动化联动机制
frontend/ (前端)GitHub 联动在线更新 (Pages)已经与 GitHub 仓库关联。每当代码合并到 main 分支时，Cloudflare 就会在云端拉取 frontend/ 目录进行自动构建与部署，无需人工干预。
cloudflare-worker/ (后端)本地环境推送 (Wrangler CLI)没有配置 GitHub Actions。由开发者在本地运行 npx wrangler deploy 手动将 worker.js 代码推送到边缘端。

3. 为何对后端 Workers 采用本地推送？（优缺点权衡） ​

  • 优势 (为何采用)：
    1. 极速迭代与调试：后端代码更新直接在本地运行 npx wrangler deploy，仅需 3~5 秒即可在边缘端生效，远比 GitHub CI/CD（需 1-2 分钟）高效。
    2. D1/Vectorize 本地联动紧密：后端在迭代时经常伴随着 D1 数据库结构更新（schema.sql）以及向量重构。在本地能直接以 CLI 形式一键执行数据库迁移，调试极其灵活。
    3. 降低密钥泄露风险：免去了在 GitHub Actions 中配置和维护 Cloudflare API Token、Account ID 等敏感凭证的麻烦。
  • 劣势与规避方法：
    • 劣势：多人共同开发时，本地推送可能会产生覆盖冲突。
    • 规避：在部署前，务必使用 git pull 保证本地代码为最新，并在部署时加上 --keep-vars 以防覆盖云端手动配置的环境变量。

二、 Cloudflare Pages 与 Workers 服务绑定机制 ​

前端和后端在 Cloudflare 上是通过 Pages Service Bindings (服务绑定) 相互联动的：

  1. 统一域名与免跨域：在 Cloudflare Pages 的配置页面中（Settings -> Functions -> Service bindings），我们将路径 /api 绑定到了后端 Worker panjiayuan-backend。
  2. 无缝路由：当用户访问 https://panjiayuan.rowkin.xyz/api/get-verdict 时，Pages 会在边缘端自动把该请求路由到 panjiayuan-backend Worker，前端在调用接口时可以直接写相对路径 /api/get-verdict，彻底消除了跨域 (CORS) 问题。

三、 Wrangler CLI 高频与进阶命令指南 ​

Wrangler 是 Cloudflare 开发与运维 Workers 的核心命令行工具。以下是高频使用的命令：

1. 登录与身份核验 ​

bash
# 1. 唤起浏览器完成 Cloudflare 账号授权登录
npx wrangler login

# 2. 验证当前登录的用户信息及关联的 Account ID
npx wrangler whoami

2. Workers 开发与部署 ​

bash
# 1. 本地模拟运行 Worker（会虚拟模拟 KV, D1 等绑定关系）
npx wrangler dev

# 2. 推送部署到生产环境（推荐加上 --keep-vars 避免覆盖控制台上已存在的环境变量）
npx wrangler deploy --keep-vars

# 3. 查看最近的部署版本历史（包含 Version ID、时间、作者、部署来源）
npx wrangler deployments list

# 4. 如果新部署的代码有严重 Bug，可一键回滚到指定版本 ID
npx wrangler deployments rollback <version_id>

3. D1 关系型数据库操作 (核心场景) ​

D1 是 Serverless SQL 数据库。Wrangler 允许在本地调试和线上云端分别操作：

bash
# 1. 创建一个新的 D1 数据库（记录输出的 database_id 填入 wrangler.toml）
npx wrangler d1 create panjiayuan-db

# 2. 列出当前账户下的所有 D1 数据库
npx wrangler d1 list

# 3. 本地测试：在本地的 SQLite 影子数据库中执行 SQL 文件
npx wrangler d1 execute panjiayuan-db --local --file=./schema.sql

# 4. 生产部署：将 SQL 文件注入到远程线上的 D1 数据库中
npx wrangler d1 execute panjiayuan-db --remote --file=./schema.sql

# 5. 在线查询：直接在命令行对线上 D1 执行 SQL 命令
npx wrangler d1 execute panjiayuan-db --remote --command="SELECT COUNT(*) FROM panjiayuan_wiki;"

4. Vectorize 向量索引管理 ​

Vectorize 是配合 RAG 知识库检索使用的向量数据库：

bash
# 1. 创建 1024 维的向量索引（与 bge-large-en-v1.5 模型维度对齐）
npx wrangler vectorize create panjiayuan-vector-index --dimensions=1024 --metric=cosine

# 2. 获取向量索引详情及当前向量条数
npx wrangler vectorize get panjiayuan-vector-index

四、 panjiayuan-helper 场景实战运维手册 ​

在 panjiayuan-helper 的混合部署架构下，面对常见运维场景，可以按照以下标准步骤操作：

场景一：更新文玩防坑百科数据与向量重灌 (RAG 同步) ​

当您在本地修改了 cloudflare-worker/schema.sql 里的预置数据后，需要将数据与向量同步至云端：

  1. 推送最新的 SQL 数据到线上 D1 数据库：
    bash
    cd cloudflare-worker
npx wrangler d1 execute panjiayuan-db --remote --file=./schema.sql
  2. 触发向量重构接口： 通过调用后端的 /api/sync-rag 接口，强制 Worker 将 D1 中的全部文本重新嵌入并上传到 Vectorize：
    bash
    curl -X POST https://panjiayuan.rowkin.xyz/api/sync-rag
    预期返回： {"success":true,"message":"Sync D1 to Vectorize database successfully!","recordsSynced":x}
  3. 验证检索功能： 使用测试接口检查 RAG 逻辑是否会成功从 D1 召回并添加 RAG 标识：
    bash
    curl -X POST https://panjiayuan.rowkin.xyz/api/get-verdict
    验证重点：检查返回的 JSON 中，source 字段是否以 CF_RAG_WIKI_ID_ 开头。

场景二：部署 Worker 时防止环境变量丢失 ​

痛点：因为 VOLCENGINE_API_KEY 和 DEEPSEEK_API_KEY 是在 Cloudflare Workers 控制台的 Settings -> Variables 中手动添加的敏感字段，没有写进 wrangler.toml。 正确部署操作：

  • 每次推送 Workers 后端代码时，必须加参数：
    bash
    npx wrangler deploy --keep-vars
  • 如果不小心漏掉了 --keep-vars 导致线上接口报错，只需在 Cloudflare Workers 控制台重新填入 API Key 并点击部署即可。

场景三：前后端本地全套闭环调试 ​

在不推送到线上的情况下，如何在本地完成前后端的完整联调：

  1. 启动本地 Python FastAPI 后端（为前端提供本地 SSE 接口）：
    bash
    cd backend
pip install -r requirements.txt
python app.py
  2. 启动本地静态页面：
    • 在 frontend 目录下通过任意本地服务器（如 Live Server 或直接双击 index.html）启动。
    • 前端会自动探测本地的 8000 端口。如果检测到 http://127.0.0.1:8000 可达，将自动在“云端接口”与“本地接口”之间建立无缝切换。