基于Cloudflare生态的应用部署与开发全解

谁在黄金彼岸
0 阅读6分钟

基于Cloudflare生态的应用部署与开发全解

一、项目背景

本文档聚焦基于Cloudflare生态（Workers、Pages、R2等核心能力）构建的 AI 内容重写器项目，汇总部署配置、功能开发、问题解决全流程关键内容，核心解决跨域访问、域名路由、LLM模型集成等核心问题，保障AI内容重写服务的稳定部署与高效运行。

二、核心部署配置问题及解决方案

2.1 Workers部署失败 - 自定义域名规则限制

问题表现

部署Workers时触发路由验证错误，提示自定义域名不支持路径及通配符格式，错误信息如下：

X [ERROR] Invalid Routes:
  [脱敏域名]/api/*:
  Wildcard operators (*) are not allowed in Custom Domains
  Paths are not allowed in Custom Domains
根因分析

Cloudflare自定义域名的路由规则中，不支持在域名后拼接路径或使用通配符（*）作为路由匹配符。

解决方案
  • 子域名分流方案：放弃原域名+路径通配符的配置形式，改用独立子域名承载API服务（如api.[脱敏主域名]）；
  • 统一域名透传方案：采用主域名统一接入，通过Pages路由透传规则实现前端与后端接口的路径隔离。

2.2 DNS 记录冲突

问题表现

添加自定义域名时提示域名已存在外部管理的DNS记录，无法完成配置，错误信息：

Hostname '[脱敏域名]' already has externally managed DNS records
解决方案
  • 在Cloudflare控制台（Dashboard）中删除该域名下冲突的现有DNS记录；
  • 或在添加自定义域的流程中，选择“覆盖原有记录”选项完成配置。

2.3 R2存储桶未启用

问题表现

部署过程中提示指定名称的R2存储桶未找到，需先启用对应功能，错误信息：

R2 bucket '[脱敏存储桶名称]' not found.
Please enable R2 through the Cloudflare Dashboard. [code: 10042]
解决方案
  • 临时移除配置文件中与R2存储桶相关的配置项，优先完成核心服务部署；
  • 后续在Cloudflare控制台手动启用R2功能，并创建指定名称的存储桶，再补全相关配置。

三、跨域与API路径适配问题

3.1 API请求 404 错误

问题表现

前端调用/auth/register等API接口时返回404错误，核心原因为前后端API路径配置不匹配：

  • 前端环境变量配置：VITE_API_URL=https://[脱敏子域名]；
  • 后端Workers路由定义：/api/auth/register。
解决方案

统一前后端API路径前缀，修正前端环境变量配置：

# 正确配置示例
VITE_API_URL=https://[脱敏子域名]/api

3.2 统一域名透传架构配置

为简化域名管理、降低跨域复杂度，设计统一域名+Pages路由透传的架构方案：

[脱敏主域名]/        → Pages（前端页面）
[脱敏主域名]/api/*   → Workers（后端接口，通过_routes.json透传）
关键配置
  • 前端工程中新增web/public/_routes.json文件，配置Pages路由透传规则，实现/api路径下的请求转发至Workers；
  • 扩展Workers的CORS（跨域资源共享）配置，将前端主域名添加至允许列表，确保跨域请求正常。

四、LLM模型集成问题及优化

4.1 模型访问权限与名称配置

问题1：模型访问被拒绝

调用LLM模型时返回权限错误：

{
  "code": "Model.AccessDenied",
  "message": "Model access denied."
}

解决方案：登录对应大模型平台控制台，手动申请目标模型（如 qwen -plus）的访问权限。

问题2：模型不存在错误

调用模型时返回参数错误，核心原因为模型名称格式不规范：

{
  "code": "InvalidParameter",
  "message": "Model not exist."
}

解决方案：统一模型名称为小写格式，示例配置：

LLM_MODEL = "qwen-plus-2025-12-01"

4.2 LLM错误信息精细化透传

为提升用户体验，优化模型调用错误的处理逻辑，解析平台错误码并返回人性化提示：

// 解析大模型平台错误码，返回精准提示
if (errorJson.code === 'InvalidApiKey') {
  errorDetail = 'API Key 无效或已过期，请检查配置';
} else if (errorJson.code === 'InsufficientBalance') {
  errorDetail = '账户余额不足，请充值';
} else if (errorJson.code === 'InvalidModel') {
  errorDetail = `模型 ${this.env.LLM_MODEL} 不存在或不可用`;
}

4.3 流式响应错误处理

针对AI内容重写的流式响应场景，优化错误捕获与透传逻辑，确保前端能获取详细错误信息：

} catch (error) {
  const errorMessage = error instanceof Error ? error.message : 'Unknown error';
  const errorData = `data: ${JSON.stringify({ 
    error: 'Failed to rewrite content', 
    details: errorMessage 
  })}\n\n`;
  controller.enqueue(encoder.encode(errorData));
  controller.close();
}

五、核心配置文件调整

5.1 Workers部署配置（wrangler.toml）

  • 简化多环境配置块，删除[env.dev]和[env.production]，仅保留核心部署配置；
  • 修正LLM模型名称配置，统一为小写规范格式。

5.2 前端环境配置（.env.production）

  • 从子域名方案迁移至统一域名方案，简化API地址配置：
# 原配置（子域名）
VITE_API_URL=https://[脱敏子域名]/api

# 新配置（统一域名）
VITE_API_URL=/api

5.3 CORS跨域配置

扩展允许的源地址列表，覆盖本地开发、生产环境、子域名及Pages默认域名：

origin: [
  'http://localhost:5173',
  'https://[脱敏主域名]',
  'https://[脱敏子域名]',
  'https://[脱敏Pages默认域名].pages.dev'
]

六、部署架构设计

6.1 子域名分流架构（基础方案）

用户 → [脱敏主域名] (Pages 前端)
         ↓
    API 调用 → [脱敏子域名] (Workers 后端)

6.2 统一域名透传架构（优化方案）

用户 → [脱敏主域名]
         ├── /           → Pages (前端页面)
         └── /api/*      → Workers (后端接口，Pages路由透传)

七、前端功能开发优化

7.1 多语言选择功能

为满足多场景内容重写需求，新增语言选择功能：

  • 新增selectedLanguage状态管理选中的输出语言；
  • 支持语言选项：English / 中文 / Français / Deutsch；
  • 将语言参数绑定至rewriteStream请求，实现不同语言的内容重写输出。

7.2 关键文件清单

文件路径核心作用
workers/wrangler.tomlWorkers部署配置（模型、环境变量）
workers/src/services/llm.tsLLM模型调用逻辑，含错误码解析
workers/src/index.tsWorkers入口，含CORS跨域配置
web/.env.production前端生产环境API地址配置
web/public/_routes.jsonPages路由透传规则配置
web/src/views/Rewrite.vue重写功能页面，含语言选择交互

八、待完成配置与后续优化

8.1 Cloudflare控制台待配置项

  1. Workers自定义域名：添加api.[脱敏主域名]；
  2. Pages自定义域名：添加[脱敏主域名]；
  3. R2存储桶（可选）：启用R2功能并创建指定名称存储桶。

8.2 功能优化建议

  1. 权限管理：完成大模型平台目标模型的访问权限开通；
  2. 错误监控：集成Sentry或Cloudflare Logs实现错误监控；
  3. 性能优化：前端代码分割，减小打包体积，提升加载速度。

九、测试验证示例

9.1 API健康检查

curl https://[脱敏子域名]/health

9.2 流式内容重写测试

curl -X POST https://[脱敏子域名]/api/rewrite/stream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [脱敏TOKEN]" \
  -d '{
    "text": "Test content",
    "style": "professional",
    "language": "en"
  }'

十、总结

本次项目开发与部署核心完成以下目标：

  1. 解决Cloudflare Workers/Pages部署中的域名路由、DNS冲突等配置问题；
  2. 优化跨域访问策略，支持子域名与统一域名两种架构方案；
  3. 完成LLM模型集成，解决权限、名称格式、错误透传等核心问题；
  4. 实现多语言输出、流式响应错误处理等前端功能优化；
  5. 形成标准化的配置文件与测试验证流程。

后续可重点推进控制台域名配置、模型权限开通及全链路测试，确保服务稳定上线运行。

avatar
文章
阅读
粉丝