基于Cloudflare Workers构建轻量级反向代理：无服务器边缘计算实践

1. 项目概述：一个基于Cloudflare Workers的轻量级反向代理工具

最近在折腾个人项目，经常遇到需要将一些API或者静态资源部署到全球，但又不想搞个服务器那么麻烦。VPS要钱，还要维护，对于个人开发者或者小团队来说，成本有点高。这时候，Cloudflare Workers就进入了我的视野。它是一个无服务器函数平台，在全球有几百个节点，能让你写的代码在离用户最近的地方运行，延迟低，还免费。mduongvandinh/openclaw-cloudflare这个项目，就是一个专门为Cloudflare Workers设计的反向代理工具，你可以把它理解为一个轻量级的“爪子”，帮你把请求抓到别的地方去处理，再返回结果。

简单来说，它就是一个跑在Cloudflare边缘网络上的、用JavaScript写的反向代理。你不需要服务器，只需要一个Cloudflare账户，就能把对某个域名的请求，转发到你指定的后端服务（比如你的家庭NAS、某个内网API、或者另一个不支持HTTPS的旧服务）。这对于需要暴露内网服务、做API聚合、或者给某些服务套上Cloudflare强大的安全与CDN能力来说，非常有用。我最初用它是为了安全地访问家里树莓派上跑的服务，不用在路由器上做复杂的端口映射，也不用担心公网IP变化的问题。

2. 核心设计思路与架构拆解

2.1 为什么选择Cloudflare Workers？

首先得明白我们面对的核心痛点：低成本、全球化、易部署、高可用。传统的反向代理方案，比如Nginx，需要一台有公网IP的服务器。这台服务器就成了单点，如果它宕机或者所在区域网络不佳，服务就挂了。而且，服务器的带宽和流量都是要钱的，尤其是面对突发流量时。

Cloudflare Workers完美地解决了这些问题：

1. 无服务器与全球边缘网络：代码部署在Cloudflare的全球边缘节点上，用户访问时，请求由离他最近的节点处理。这意味着极低的网络延迟和天生的高可用性（一个节点挂了，流量会自动路由到其他节点）。
2. 免费额度慷慨：免费计划每天提供10万次请求，对于个人项目、博客、或者中小型API来说，完全够用。这几乎实现了零成本运维。
3. 开发部署极其简单：不需要配置服务器环境，不需要管理运行时。直接在Web编辑器里写JavaScript/TypeScript代码，或者通过Wrangler CLI工具一键部署，整个流程几分钟就能搞定。
4. 内置安全与性能特性：自动获得HTTPS、DDoS防护、缓存等Cloudflare全家桶功能，省去了大量配置工作。

openclaw-cloudflare就是基于这些优势，将反向代理的核心逻辑封装成一个简洁的Worker脚本。它的设计目标不是替代Nginx这种功能全面的网关，而是在Cloudflare Workers这个特定环境下，提供一个开箱即用、配置灵活的反向代理解决方案。

2.2 项目架构与核心工作流

这个项目的架构非常直接，核心就是一个JavaScript文件（通常是index.js或worker.js），它导出一个处理fetch事件的函数。Cloudflare Workers平台会监听你绑定的域名（或路由），当有请求到达时，就执行这个函数。

它的核心工作流可以分解为以下几步：

1. 请求拦截：Worker接收到用户发起的HTTP/HTTPS请求。
2. 规则匹配与目标URL重写：根据预设的规则（比如路径前缀、域名），解析出用户想要访问的实际后端服务地址。这是反向代理的核心逻辑，openclaw-cloudflare通常通过配置一个“目标主机”映射表来实现。
3. 请求转发：Worker构造一个新的Request对象，将原始请求的头部、方法、体等，转发到上一步确定的后端URL。这里可以添加或修改头部，比如添加认证信息、修改Host头等。
4. 响应处理：收到后端服务的响应后，Worker可以对响应进行一些处理（比如修改头部、状态码，或者简单的响应体转换），然后再返回给最终用户。
5. 错误处理：如果后端服务不可达、超时或返回错误，Worker需要返回一个友好的错误页面或状态码，而不是将内部错误信息直接暴露给用户。

整个过程中，用户感知的始终是你的Cloudflare Workers域名（比如proxy.yourdomain.com），完全不知道背后真正的服务在哪里。这既保护了后端服务的真实地址，也让你能灵活地迁移后端服务而不影响用户。

3. 核心配置与功能详解

3.1 环境变量与配置管理

一个健壮的反向代理需要灵活的配置。openclaw-cloudflare通常利用Cloudflare Workers的环境变量（Environment Variables）或KV命名空间来存储配置，避免将敏感信息（如后端地址、API密钥）硬编码在代码中。

常见的配置项包括：

• UPSTREAM_URL或TARGET_HOST：这是最核心的配置，指定默认的后端服务基础URL。例如https://api.internal.com。
• 路径重写规则：你可能只想代理特定路径。例如，将所有访问/api/*的请求转发到后端，而/static/*的请求则直接由Cloudflare的CDN处理。这需要在代码逻辑中实现路径匹配和替换。
• 请求头修改：转发时，经常需要修改或添加头部。比如，将Host头设置为后端服务认可的值，或者添加一个X-Forwarded-For头告知后端真实用户IP。
• 超时与重试策略：设置转发请求的超时时间（如30秒），以及失败时是否重试、重试几次。这能防止一个慢后端拖垮整个Worker。

在代码中，你可以通过env对象来访问这些环境变量。一个典型的配置读取逻辑如下：

export default { async fetch(request, env, ctx) { // 从环境变量读取上游地址 const upstreamUrl = env.UPSTREAM_URL; // 如果没有配置，可以提供一个默认值或直接返回错误 if (!upstreamUrl) { return new Response('上游服务未配置', { status: 502 }); } // ... 后续代理逻辑 } }

注意：环境变量在Worker部署时注入，修改后需要重新部署才能生效。对于需要频繁动态变更的配置，可以考虑使用Cloudflare KV来存储。

3.2 请求转发与响应处理的实现细节

这是代码的核心部分。我们来看一个简化但功能完整的实现片段：

export default { async fetch(request, env, ctx) { // 1. 定义上游基础URL const baseUpstream = env.UPSTREAM_URL || ‘https://default-backend.example.com‘; // 2. 解析原始请求的URL const url = new URL(request.url); const path = url.pathname; const search = url.search; // 3. 构建新的上游请求URL (这里示例为简单拼接，实际可根据规则复杂匹配) const upstreamUrl = `${baseUpstream}${path}${search}`; // 4. 准备新的请求头 const newHeaders = new Headers(request.headers); // 重要：修改Host头，许多后端服务依赖此头进行虚拟主机路由 newHeaders.set(‘Host‘, new URL(baseUpstream).host); // 添加X-Forwarded-For头，传递用户真实IP（Cloudflare会将真实IP放在CF-Connecting-IP头中） const userIP = request.headers.get(‘CF-Connecting-IP‘); if (userIP) { newHeaders.set(‘X-Forwarded-For‘, userIP); } // 5. 构造新的请求对象 const newRequest = new Request(upstreamUrl, { method: request.method, headers: newHeaders, body: request.body, redirect: ‘manual‘, // 不自动跟随重定向，由Worker处理 }); // 6. 发起转发请求，并设置超时 const timeoutMs = 10000; // 10秒超时 const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(‘上游服务响应超时‘)), timeoutMs) ); try { // 使用Promise.race实现超时控制 const response = await Promise.race([fetch(newRequest, { cf: { resolveOverride: new URL(baseUpstream).hostname } }), timeoutPromise]); // 7. （可选）处理响应，例如修改响应头 const newResponse = new Response(response.body, response); // 添加CORS头，如果后端没有设置的话 newResponse.headers.set(‘Access-Control-Allow-Origin‘, ‘*‘); // 移除一些可能暴露上游信息的头部 newResponse.headers.delete(‘x-powered-by‘); return newResponse; } catch (error) { // 8. 错误处理 console.error(`代理请求失败: ${error.message}`); return new Response(‘网关错误，请稍后重试‘, { status: 502, headers: { ‘Content-Type‘: ‘text/plain;charset=utf-8‘ }, }); } }, };

关键点解析：

• cf: { resolveOverride }：这是Cloudflare Workers特有的fetch选项。它强制Worker的DNS解析指向指定的主机名，这在你的上游服务域名也使用了Cloudflare（且与Worker在同一账户）时非常有用，可以避免循环解析问题。
• 超时控制：边缘函数的执行时间有限制（免费计划10ms CPU时间，但网络I/O时间另计）。为转发请求设置超时是必须的，防止坏的上游服务耗尽Worker资源。
• 头部处理：正确处理Host和X-Forwarded-For头是反向代理工作的关键。许多Web框架（如Spring Boot, Express）依赖这些头来做安全校验、日志记录或路由。
• 错误隔离：用try...catch包裹转发逻辑，确保任何错误（网络错误、超时、上游5xx错误）都能被捕获，并返回一个统一的5xx错误页面，而不是将内部堆栈信息泄露出去。

3.3 高级功能：路径重写、多目标与负载均衡

基础的代理只能转发到单一后端。openclaw-cloudflare这类项目的高级形态，往往会支持更复杂的路由规则。

1. 路径前缀剥离/重写：用户访问https://proxy.example.com/api/v1/users，但你希望后端收到的是/v1/users。这就需要从请求路径中剥离/api前缀。

   const path = url.pathname; let upstreamPath = path; if (path.startsWith(‘/api/‘)) { upstreamPath = path.replace(‘^/api‘, ‘‘); // 剥离 /api 前缀 } const upstreamUrl = `${baseUpstream}${upstreamPath}${search}`;

2. 多目标路由（基于路径或域名）：你可以配置一个映射表，将不同的路径指向不同的后端服务。

   const routeMap = { ‘/service1/‘: ‘https://backend1.example.com‘, ‘/service2/‘: ‘https://backend2.example.net‘, ‘/blog/‘: ‘https://my-cms.workers.dev‘, }; // 遍历映射表，找到匹配的前缀 for (const [prefix, target] of Object.entries(routeMap)) { if (path.startsWith(prefix)) { upstreamBase = target; // 可以在这里进行路径重写 break; } }

3. 简易负载均衡：虽然Workers本身不是专业的负载均衡器，但可以实现简单的轮询策略，将请求分发到多个后端实例，提高可用性。

   const backends = [ ‘https://backend-a.example.com‘, ‘https://backend-b.example.com‘, ‘https://backend-c.example.com‘, ]; let currentIndex = 0; // 注意：Worker是无状态的，这个索引在多次请求间无法保持！需要外部存储。 // 更实用的方法：使用随机选择或根据请求的某些特征（如用户ID哈希）选择后端 const selectedBackend = backends[Math.floor(Math.random() * backends.length)];

   重要提醒：Worker是无状态且瞬时执行的，传统的内存轮询索引无效。要实现有状态的负载均衡，需要借助外部存储如Durable Objects或KV，但这会引入复杂度。对于简单场景，随机选择或一致性哈希（基于请求URL或IP）是更可行的方案。

4. 完整部署与配置实操指南

4.1 前期准备与环境搭建

在开始之前，你需要准备好以下几样东西：

1. 一个Cloudflare账户：如果你没有，去官网免费注册一个。
2. 一个域名（可选但推荐）：你可以使用Cloudflare分配的*.workers.dev子域名，但为了专业性和灵活性，建议使用自己的域名，并将其DNS托管到Cloudflare。
3. Node.js与npm环境：用于安装和运行Wrangler CLI工具。
4. Wrangler CLI：Cloudflare官方命令行工具，用于管理Workers。通过npm install -g wrangler安装。

首先，登录Wrangler：

wrangler login

这会打开浏览器，授权Wrangler访问你的Cloudflare账户。

4.2 项目初始化与代码获取

你可以从mduongvandinh/openclaw-cloudflare的GitHub仓库获取代码。假设我们创建一个新项目：

# 创建一个新目录 mkdir my-openclaw-proxy && cd my-openclaw-proxy # 初始化一个Wrangler项目 wrangler init # 在初始化过程中，选择“JavaScript”或“TypeScript”模板。

初始化后，你会得到wrangler.toml（配置文件）和src/index.js（入口文件）等。

接下来，将openclaw-cloudflare的核心代理逻辑代码复制到src/index.js中，替换掉默认内容。或者，你也可以直接克隆原仓库，在其基础上修改。

4.3 配置 wrangler.toml 与环境变量

wrangler.toml是项目的核心配置文件。一个基本的配置如下：

name = "my-openclaw-proxy" # Worker的名称 main = "src/index.js" # 入口文件 compatibility_date = "2024-03-20" # 兼容性日期，很重要 # 配置你的自定义域名（如果你有自己的域名） # routes = [ # { pattern = "proxy.yourdomain.com/*", zone_name = "yourdomain.com" } # ] # 使用 workers.dev 域名 workers_dev = true # 定义环境变量 [vars] UPSTREAM_URL = "https://your-real-backend.com" # 你的后端服务地址 # 可以定义多个变量，如 API_KEY、TIMEOUT等 # 如果你需要更动态的配置，可以绑定一个KV命名空间 # [[kv_namespaces]] # binding = "PROXY_CONFIG" # id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

关键配置项说明：

• compatibility_date：指定Worker运行时的兼容性日期。Cloudflare会不断更新运行时，这个日期确保你的代码行为在特定版本下保持一致。建议设置为最近的日期。
• routes：将Worker绑定到你的自定义域名的特定路由。例如，将所有发往proxy.yourdomain.com的请求都交给这个Worker处理。
• [vars]：这里定义的环境变量，在Worker代码中可以通过env.变量名访问。切勿将密码、密钥等敏感信息直接写在这里，对于敏感信息，应使用wrangler secret put命令设置。

设置秘密环境变量：

wrangler secret put MY_API_KEY # 随后命令行会提示你输入值，输入的值会被加密存储。

4.4 本地开发、测试与部署

本地开发：Wrangler提供了强大的本地开发服务器，可以模拟Cloudflare边缘环境。

wrangler dev

启动后，默认在http://localhost:8787提供服务。你可以在浏览器访问，或使用curl、Postman等工具测试你的代理逻辑。wrangler dev支持热重载，修改代码后会自动刷新。

测试：在本地，你可以通过修改环境变量来测试不同的上游地址。创建一个.dev.vars文件（不会被提交到Git），其内容类似于：

UPSTREAM_URL=http://localhost:3000 # 指向你本地运行的后端服务

在运行wrangler dev时，它会自动加载这个文件中的变量。

部署到生产环境：测试无误后，部署非常简单。

wrangler deploy

这条命令会将你的Worker代码打包并发布到Cloudflare全球网络。部署成功后，你会得到一个*.workers.dev的URL，或者如果你配置了自定义路由，就可以通过你自己的域名访问了。

4.5 域名绑定与SSL证书

如果你使用自己的域名（例如proxy.yourdomain.com）：

1. 确保你的域名DNS由Cloudflare托管（即NS记录指向Cloudflare）。
2. 在Cloudflare仪表板的Workers & Pages部分，找到你部署的Worker，进入Triggers标签页。
3. 点击Add Route，输入你的路由，例如proxy.yourdomain.com/*。
4. 保存后，Cloudflare会自动为这个路由配置SSL证书（HTTPS），整个过程完全免费且自动化。

至此，一个功能完整的、基于Cloudflare Workers的反向代理服务就搭建完成了。用户访问https://proxy.yourdomain.com/any/path，请求会被你的Worker拦截，转发到UPSTREAM_URL对应的后端，并将响应返回给用户。

5. 性能调优、安全加固与监控

5.1 性能优化策略

虽然Workers本身性能很高，但代理逻辑写不好也会成为瓶颈。

1. 减少不必要的计算和转发：

   • 静态资源直出：对于图片、CSS、JS等静态资源，如果它们已经托管在Cloudflare CDN或另一个快的源站，可以考虑让请求直接通过，而不经过Worker代理逻辑。可以在代码开头进行判断：

     if (url.pathname.endsWith(‘.jpg‘) || url.pathname.endsWith(‘.css‘) || url.pathname.endsWith(‘.js‘)) { // 直接转发到某个CDN，或者直接返回fetch(request) return fetch(request); }

   • 缓存响应：对于不经常变化的API响应，可以利用Worker Cache API或Cloudflare CDN缓存，显著减少回源请求，降低延迟和上游压力。

     const cache = caches.default; let response = await cache.match(request); if (!response) { response = await fetch(upstreamRequest); // 设置缓存，例如缓存1分钟 ctx.waitUntil(cache.put(request, response.clone())); } return response;

2. 优化网络请求：

   • 使用持久连接（HTTP/1.1 Keep-Alive, HTTP/2）：Cloudflare的fetchAPI默认会优化连接复用，我们只需确保不要为每个请求创建不必要的连接开销。
   • 压缩传输：确保后端返回的响应支持gzip或br压缩，Worker会保持这些压缩头，减少传输数据量。

3. 控制超时与重试：为fetch设置合理的超时（如5-10秒），避免等待缓慢的上游。对于非幂等的请求（如POST），要谨慎使用重试，以免重复提交。

5.2 安全加固措施

将服务暴露在公网，安全是第一要务。

1. 输入验证与路径遍历防护：严格检查请求路径，防止攻击者使用../等字符进行路径遍历，访问到上游服务器上的敏感文件。

   const pathname = new URL(request.url).pathname; if (pathname.includes(‘..‘) || pathname.includes(‘//‘)) { return new Response(‘Invalid path‘, { status: 400 }); }

2. 限制请求方法与大小：只允许必要的HTTP方法（如GET, POST），并限制请求体大小，防止DoS攻击。

   const ALLOWED_METHODS = [‘GET‘, ‘POST‘, ‘PUT‘, ‘DELETE‘]; if (!ALLOWED_METHODS.includes(request.method)) { return new Response(‘Method Not Allowed‘, { status: 405 }); } // 检查Content-Length头 const contentLength = request.headers.get(‘content-length‘); if (contentLength && parseInt(contentLength) > 10 * 1024 * 1024) { // 10MB return new Response(‘Payload Too Large‘, { status: 413 }); }

3. 敏感信息过滤：在将上游响应返回给用户前，仔细检查响应头，移除可能泄露后端信息的头部，如Server、X-Powered-By、X-AspNet-Version等。

4. 身份验证与授权：可以在Worker层实现统一的API网关认证。例如，检查请求头中的Authorization令牌是否有效。

   const authToken = request.headers.get(‘Authorization‘); if (!isValidToken(authToken)) { return new Response(‘Unauthorized‘, { status: 401 }); } // isValidToken 函数可以查询KV或调用外部认证服务

5. 利用Cloudflare防火墙规则：在Cloudflare仪表板中，为你的Worker路由设置防火墙规则（WAF），可以轻松屏蔽特定IP、国家/地区，或防御SQL注入、XSS等常见Web攻击。

5.3 日志、监控与告警

无服务器架构下，可观测性尤为重要。

1. 日志记录：使用console.log()、console.error()输出的日志，可以在Cloudflare仪表板的Workers & Pages-> 选择你的Worker ->Logs中查看。建议记录关键信息，如请求ID、上游URL、响应状态码、处理时间等。

   const startTime = Date.now(); // ... 处理逻辑 ... const duration = Date.now() - startTime; console.log(`Proxied ${request.url} to ${upstreamUrl} - Status: ${response.status} - Duration: ${duration}ms`);

2. 监控指标：Cloudflare提供Worker的请求次数、错误次数、CPU时间消耗等基本指标。你可以在仪表板的Analytics & Logs->Workers中查看。关注错误率（5xx）和超时比例。

3. 设置告警：在Cloudflare仪表板中，可以基于这些指标设置告警。例如，当5分钟内的错误率超过1%时，发送邮件或Slack通知，让你能及时发现问题。

4. 分布式追踪：对于复杂场景，可以考虑集成像OpenTelemetry这样的分布式追踪，将Worker的请求作为整个调用链的一环，便于排查跨服务的性能问题。

6. 常见问题与故障排查实录

在实际使用中，你肯定会遇到各种各样的问题。下面是我踩过的一些坑和解决方案。

6.1 问题排查清单

6.2 实战避坑经验

1. Host头是万恶之源：90%的代理问题都和Host头有关。很多后端框架（Nginx虚拟主机、Spring Boot的server.servlet.context-path等）都依赖Host头来做路由。务必在转发前，将Host头设置为上游服务域名的主机部分（不含端口）。同时，保留原始Host头的信息可以通过X-Forwarded-Host传递。

2. 小心循环代理：如果你的上游服务也使用了Cloudflare（并且和Worker在同一个域名下），可能会形成循环代理。例如，WorkerA代理到service.yourdomain.com，而service.yourdomain.com的DNS又指向Cloudflare，并且也触发了一个WorkerB或回源到A。使用cf: { resolveOverride: ‘your-real-origin-ip‘ }可以强制DNS解析到源站IP，打破循环。

3. 处理流式响应和大文件：默认情况下，await response.text()或await response.json()会将整个响应体读入内存。对于大文件或流式响应（如视频），这会耗尽Worker的内存限制（免费计划128MB）。应该使用响应体的流式接口：

   const upstreamResponse = await fetch(newRequest); const { readable, writable } = new TransformStream(); upstreamResponse.body.pipeTo(writable); return new Response(readable, upstreamResponse);

   这样，数据是流式地从上游传输到客户端，Worker只充当管道，不占用大量内存。

4. 环境变量与秘密管理：永远不要将密钥、密码等硬编码在代码或wrangler.toml的[vars]中。务必使用wrangler secret put命令。对于需要区分开发和生产的环境变量，可以利用wrangler.toml中的[env.dev]、[env.production]节，结合wrangler deploy --env来管理。

5. 免费额度的瓶颈：免费计划每天10万次请求，对于大多数个人项目足够。但要注意CPU时间限制。如果你的代理逻辑非常复杂，或者上游响应极慢导致请求挂起时间过长，都可能消耗大量CPU时间。监控你的Worker的“Duration”指标，优化代码，设置合理的超时，是避免超额的关键。

通过这个项目，你将得到一个极其灵活、强大且成本极低的边缘代理工具。它不仅仅是简单的请求转发，更是一个可以植入业务逻辑（认证、限流、修改响应）的全球化接入点。无论是用于个人项目、初创公司原型，还是作为现有架构的补充，Cloudflare Workers + 反向代理的模式都值得你深入探索和实践。