基于Cloudflare Workers的RSS阅读器实战：从KV存储到Tunnel部署

Cloudflare WorkersRSS阅读器KV存储

于 2026-10-02 02:38:44 修改

·本内容遵循CC 4.0 BY-SA版权协议

最近一个多月，我把每天读的东西收拢到了一个自己搓的阅读器里。项目名叫 CFRSS，完整一点说就是“基于 Cloudflare Workers 的 RSS 阅读器”。以前我用的在线阅读器要么免费版功能砍得厉害，要么得自己找服务器跑，后来想想其实几十个订阅源完全用不着上服务器，用 Cloudflare 的边缘 KV 加定时任务就能搞定。这篇文章想把我从选型、写代码到部署踩坑的完整过程写出来，尤其是后来折腾 Cloudflare Tunnel 和 Docker 部署 cloudflared 时遇到的那堆环境变量问题，应该能帮你少走几天弯路。

1. 把RSS阅读器搬到Cloudflare：项目整体思路与选型纠结

1.1 为什么不是VPS，不是普通云函数

最早我有一台小 VPS，装了 Miniflux，功能没得说，但每个月固定支出先不说，还得定期给系统打补丁、处理偶尔的进程崩溃。后来有一次机房线路抽风，整整两天登录不上机器，我就下定决心把这种“重资产”逻辑砍掉。RSS 阅读器本质上就是“抓 XML + 存条目 + 展示”，这里面没有需要长时间运行的服务，全是请求驱动的逻辑，所以 Serverless 反而更合适。

市面上 Serverless 平台不少，我特意选 Cloudflare 而不是别的云函数，有几个现实原因：

首先是免费额度对个人足够友好。Worker 每天有百万级别的免费请求额度，KV 读写在个人订阅量下完全用不完。
其次是它自带全球边缘缓存。RSS 抓取结果可以放到 KV 里，用户请求时从最近节点返回，不用折腾 CDN。
然后是 Cron Triggers。Serverless 平台里能免费定时触发函数的不多，而这恰恰是 RSS 阅读器最重要的能力，我需要定时去各源站看看有没有新文章。
最后是开发体验。Cloudflare 的 Wrangler 工具链很成熟，部署就是一个命令的事，甚至不用自己搭前端打包流程。

我不是说 VPS 方案不行，Miniflux 这类工具确实成熟。但如果你和我一样只有几十个订阅源、每天阅读量不大，而且不想为了一个阅读器去维护系统环境，Cloudflare 这套边缘方案明显更轻。特别是后来我把 Cloudflare Tunnel 也接进来之后，等于把“自建服务 + 边缘 API”揉在了一起，既有 Serverless 的省心，又保留了本地调试的灵活性。

1.2 CFRSS 的整体架构与数据流

CFRSS 的整体结构并不复杂，核心是三个角色：

前端展示页。我没有单独搞一套前端框架，直接用 Worker 返回一个静态 HTML 页面，里面就是订阅列表和文章列表。省去了域名解析、托管流程。
一组 REST API。同一个 Worker 根据 URL path 区分接口，比如 /api/feeds 返回订阅源列表，/api/items?feed_id=xxx 返回某个源的最新文章。
定时抓取任务。通过 Cron Triggers 每天跑几次，遍历所有订阅源，把新文章写进 KV，同时清理过期数据。

整个数据流大概是这样的：用户浏览器打开 Worker 的域名，拿到 HTML 页面；页面里的 JS 请求 /api/items；Worker 去 KV 读缓存好的文章列表并返回；如果 KV 缓存不存在，Worker 再直接抓取对应 RSS 源。这个“回源”逻辑只在缓存失效时才发生，所以最终用户看到的几乎没有加载等待。定时任务则充当“预热”角色，每隔几小时把全量订阅源抓一遍，让 KV 里始终有最新内容。

这个架构的好处是，所有逻辑都跑在 Worker 上，没有单独的数据库。KV 虽然慢一点，但 RSS 场景本来就是读多写少，最终一致性根本无伤大雅。后面我会详细说 KV 的 key 设计，那部分坑比较多。

1.3 免费额度边界与合理预期

开始动手前先想清楚限额。Cloudflare Workers 免费版有每日请求次数限制，KV 也有读写次数限制。实际体验下来，个人阅读器一天的外呼请求大概是订阅数乘以抓取频率，比如 50 个源、每 4 小时抓一次，一天最多 300 次抓取请求，加上用户访问页面、API 调用的几十次，离额度上限还有很大空间。真正需要小心的是 KV 的写入次数，因为每次抓取会把所有源的文章批量写入，一个源哪怕只有 10 篇新文章，就可能产生 10 次写入。好在 KV 的免费写入次数足够我造，至少这个项目到现在没触发过限流。

关于 KV 的另一个限制是单个 key 的 value 大小上限是 25MB。单篇文章全文塞进去一般在 100KB 以内，所以只要不是把几百篇文章塞进一个 key，基本不会超。我一般会控制单个 key 只存一个源最近 50 条文章的索引，这样既不会撑爆 size，也方便清理。

2. 核心模块拆解：订阅管理、抓取调度和KV数据结构

2.1 订阅源与文章条的存储设计

KV 本质上是一个全局数据字典，不适合做复杂查询，所以我尽量让每次读取都只依赖单一 key。我的 key 设计分了三层：

sub:list：一个 JSON 数组，保存所有订阅源的基础信息，比如名称、URL、上次抓取时间。
feed:<feedId>:items：一个 JSON 数组，保存该源最近的文章列表，每项包含文章标题、链接、发布时间，以及可选的摘要。
item:<md5>:content：单篇文章的全文缓存，key 用文章链接的 MD5 保证唯一。

为什么不用一个 key 存所有文章？因为 KV 的每一次读取都会把整个 value 拉回来，如果所有文章混在一起，列表越往后越大，接口响应会越来越慢。拆成“源”维度后，每次读取只拿一个源的列表，数据量可控。还有个好处是清理简单，我可以在每次抓取时直接计算该源最新的 50 条，然后整体覆盖 feed:<feedId>:items，不需要额外写删除逻辑。

这里不得不提醒一句：KV 没有类似数据库的事务和索引，一切“列表”都靠手工序列化。你不要指望对某个 key 做部分更新，现实中通常就是读出来、改完、整个写回去。对于 RSS 阅读器来说完全够用，但如果你要拿它做复杂业务系统，趁早换数据库。

2.2 用Cron Triggers做定时抓取

定时抓取是 CFRSS 最依赖的能力。在 wrangler.toml 里配置 Cron 非常简单，只需要加一个 triggers 段：

TOML

name = "cfrss"

main = "src/index.js"

compatibility_date = "2025-04-01"

[[kv_namespaces]]

binding = "CFRSS_KV"

id = "xxxxxxxxxxxxxxxxxxxxxxxx"

[triggers]

crons = ["0 */4 * * *"]

这里 0 */4 * * * 表示每隔 4 小时的整点执行一次。Cron 表达式是 UTC 时间，如果你想让它在北京时间每天早 8 点更新，直接用 0 0 * * * 会感觉差了 8 小时，得自己换算成 0 8 * * * 才对应下午 4 点。这种小细节，真要忘了能让你排查半天。

在 Worker 代码里，定时任务和普通请求是分开的两个入口。fetch 处理页面和 API，scheduled 处理定时抓取。两个函数不要写成同一个逻辑，否则本地调试时容易把数据写乱。抓取逻辑我看起来大概是这样：

export default {

async scheduled(event, env, ctx) {

const subList = await env.CFRSS_KV.get("sub:list", "json");

if (!subList) return;

for (const feed of subList.feeds) {

// 这里用 Promise.all 控制并发，避免一次抓太多导致超时

await ctx.waitUntil(updateFeed(env, feed));

}

async fetch(request, env, ctx) {

// 路由分发

}

};

用 ctx.waitUntil 可以告诉 Worker 我还有一些异步任务在跑，不用急着销毁。但要注意 Cron 本身有执行时长限制，免费版跑一次任务别想塞太多源，我一般会按源的数量分批，或者直接用 for await 不进行跨源并发。实测 50 个源在几分钟内能全部跑完，属于安全范围。

2.3 源站反爬与“Cloudflare爬虫”的身份问题

刚开始跑抓取时，有好几个源站直接返回 403。后来我抓了请求日志一看，源站看到的 User-Agent 是 Cloudflare-Workers，不是常见浏览器，对方大概率把这个请求当成爬虫了。这里就涉及到很多人会忽略的点：用 Cloudflare Worker 去抓别人的 RSS，本质上你就是一只爬虫。

RSS 阅读器是合法应用，但也要懂规矩。我的做法是给每个抓取请求设置一个明确的 User-Agent，比如 CFRSSBot/1.0 (+https://yourdomain.com)，这样源站管理员一看就能知道你在干什么，还能联系到你。不要伪装成浏览器，那不是长久之计。另外一定要尊重对方的 robots.txt，如果某个源明确写了不允许抓取，你就要么放弃，要么等对方公开允许后再加。

实际测试中，很多技术博客不会封杀带自报家门 UA 的请求，反而是一些个人镜像站会做防御，这种情况我会降低抓取频率，基本就不会被拒了。如果你发现某个源一直超时，也不要无限重试，最多重试三次，然后记录下来，下次 Cron 再试。这不是懒，而是避免自己的 Worker 因为重试风暴被 Cloudflare 判定为异常。

3. 实操全过程：配置Worker、绑定KV、定时任务部署

3.1 初始化项目与wrangler配置

如果你也想快点把这个项目跑起来，先别急着抄代码，把工具链理清。我环境里的 Node 是 LTS 版本，然后全局安装了 Wrangler：

BASH

npm install -g wrangler

wrangler login

登录之后，创建一个项目目录：

BASH

mkdir cfrss && cd cfrss

wrangler init --yes

Wrangler 会生成一个基础的 src/index.js 和 wrangler.toml。我们要做的第一件事是创建 KV 命名空间：

BASH

wrangler kv namespace create CFRSS_KV

执行完会输出类似下面的一段信息：

TOML

[[kv_namespaces]]

binding = "CFRSS_KV"

id = "a1b2c3d4...applicationId"

把这段复制到 wrangler.toml 里。注意 binding 的名字不要带横杠，我用的是 CFRSS_KV。接下来把 Cron 配置加进去，最终的 wrangler.toml 大概是前面展示的那个样子。这个文件是整个项目的核心，将来改域名、改迁移时区、改 Cron 频率都靠它。

3.2 编写Worker核心代码：fetch、scheduled与CORS

Worker 的入口文件要处理两类事件。先封装一个最简单的路由分发，让一个 Worker 同时承担页面和 API：

async function handleRequest(request, env) {

const url = new URL(request.url);

const route = url.pathname;

if (route === "/") {

return new Response(INDEX_HTML, {

headers: { "content-type": "text/html; charset=utf-8" },

});

}

if (route === "/api/feeds") {

const data = await env.CFRSS_KV.get("sub:list", "json");

return jsonResponse(data ?? { feeds: [] });

}

if (route === "/api/items") {

const feedId = url.searchParams.get("feed_id");

if (!feedId) return jsonResponse({ error: "missing feed_id" }, 400);

const key = `feed:${feedId}:items`;

const items = await env.CFRSS_KV.get(key, "json");

return jsonResponse(items ?? []);

}

return jsonResponse({ error: "not found" }, 404);

}

function jsonResponse(data, status = 200) {

return new Response(JSON.stringify(data), {

status,

headers: {

"content-type": "application/json",

"access-control-allow-origin": "*",

"cache-control": "no-store",

});

}

export default {

fetch: handleRequest,

scheduled: async (event, env, ctx) => {

// 定时抓取逻辑

}

};

关于 CORS 头，如果你不想在前端页面直接调用同一个域名，留着这行能让你在本地调试时省很多事。但如果你有固定的前端域名，最好把 * 改成具体的源，否则谁都能调用你的 API，虽然我这里只是读文章，无所谓。

3.3 部署与联调验证

代码写完后，直接执行部署：

BASH

wrangler deploy

部署成功后控制台会给你一个 *.workers.dev 地址。用浏览器打开能看到页面，但最开始里面的订阅列表应该是空的，因为还没有初始化数据。这时候可以手动通过 Worker 的接口插入一个订阅源，或者干脆在 KV 里面手动写一条 sub:list。我为了省事，直接在 Worker 里加了一个调试路由，请求 /api/init 会在 KV 里写入几条默认的 RSS 源，第一次部署后调用一次就行，跑通后再把这个路由删掉。

联调时可以先看 Worker 的实时日志：

BASH

wrangler tail

然后打开页面，或者用 curl 请求一下：

BASH

curl "https://your-service.workers.dev/api/items?feed_id=example"

正常情况下能看到一个 JSON 数组。如果返回空，大概率是 feed:example:items 这个 key 还没被定时任务写入，可以等下一次 Cron 触发，或者手动执行一次 /api/refresh 来触发抓取。这里的核心思路是：先把链路打通，再调样式和功能，别一上来就堆料。

4. 踩坑记录：Cloudflare Tunnel的错误排查与Docker环境变量写法

4.1 为什么要把Tunnel拉进来？

CFRSS 本身并不需要 Cloudflare Tunnel，纯靠 Worker + KV 就能跑。但我个人在开发过程中遇到了一个场景：RSS 全文提取服务需要借助本地的机器学习模型，我把这个服务放在家里的 NAS 上，不想把端口直接暴露到公网。这时候 Cloudflare Tunnel 就派上了用场，它可以把本地服务通过加密链路安全地暴露到 Cloudflare 边缘，再从 Worker 侧通过内网路径访问，外部用户全程接触不到我的真实 IP。

Tunnel 在很多人的印象里可能和网络代理有关，但这里的定位很明确：它是一个内网穿透工具，把本地服务端口映射到 Cloudflare 网络。官方名字叫 Cloudflare Tunnel，本质上是你在用户端跑一个 cloudflared 进程，它主动向 Cloudflare 边缘建立出站连接，所以不需要在路由器上开任何端口。这对我来说很友好，尤其适合放在 Docker 容器里跑。

4.2 常见的Cloudflare Tunnel错误与解决顺序

跑 Tunnel 最常见的坑集中在连接失败。下面是我遇到过最典型的几类错误：

Failed to determine Tunnel protocol。这个通常是 QUIC 握手失败。许多内网环境对 QUIC 不友好，解决方法是强制 cloudflared 走 HTTP/2，参数是 --protocol http2，或者在环境变量里设 TUNNEL_TRANSPORT_PROTOCOL=http2。
certificate has expired。这经常发生在你长期不更新本地证书之后，尤其是 Docker 容器里的镜像版本太旧。解决办法是重新执行 cloudflared tunnel login，把证书更新到本地。
Cannot connect to tunnel: service unavailable。多半是目标服务的端口没起对，cloudflared 找不到本地进程。先确认你映射的本地端口是不是真的在监听。
timeout。排查的顺序先看本机时间是否和网络时间差太多，再看防火墙有没有封出站连接。

我自己的排查顺序一般固定为：先 cloudflared tunnel list 确认隧道存在 && 令牌有效，然后看 cloudflared 的启动日志，看看是连接边缘失败还是服务发现失败，最后才怀疑配置问题。不要一出错就删配置文件，很多问题是旧版本 bug 导致的，直接升级镜像版本往往就解决了。

4.3 Docker方式运行cloudflared：环境变量踩坑

本地直接跑 cloudflared 没问题，但服务器上我更推荐用 Docker。官方镜像叫 cloudflare/cloudflared，使用方式不算复杂，不过环境变量这块很容易被忽略。

cloudflared 支持从环境变量读取配置，命名规则是 TUNNEL_ 前缀加上对应命令行参数名的大写，然后下划线代替中划线。例如：

TUNNEL_TOKEN 对应 --token，用来指定一个临时的 tunnel token。
TUNNEL_TRANSPORT_PROTOCOL 对应 --protocol http2，这个前面提过。
TUNNEL_METRICS 对应 --metrics，用于控制监控接口监听地址。
TUNNEL_ORIGIN_CERT 对应 --origincert，如果你用证书而不是 token 的话。

我最终用的是 token 方式，所以 docker-compose 长这样：

YAML

services:

cloudflared:

image: cloudflare/cloudflared:latest

restart: unless-stopped

command: tunnel run

environment:

- TUNNEL_TOKEN=${CF_TUNNEL_TOKEN}

- TUNNEL_TRANSPORT_PROTOCOL=http2

network_mode: host

这里有个特别容易踩的坑：command: tunnel run 后面的 token 不用再写了，因为环境变量里已经定义。如果你在 command 里又写一遍 --token xxx，会导致 token 被当成两个来源，有些版本会报错。环境变量的优先级其实高于配置文件的默认值，但低于显式的命令行参数，所以省略 command 里的 token 是更稳的写法。

另一个坑是 network_mode: host 的使用。在 Linux Docker 上，cloudflared 需要访问宿主机的本地服务，如果用默认 bridge 网络，映射的 localhost 会指向容器自己，连不到宿主机。改成 host 网络模式是最简单的解法。macOS 上 Docker 对 host 网络支持不够好，就需要用 host.docker.internal 这样的特殊地址了。我最初在笔记本上测试就卡在这里很久。

4.4 如何判断Tunnel是否正常？

Tunnel 启动后，通常可以在 Cloudflare Zero Trust 面板里看到连接状态。如果面板显示 Healthy，说明隧道和边缘连接正常。但有时候面板正常，实际请求却不通，这时要去验证你映射的内网服务本身。我的做法是先在服务器上用 curl 访问本地端口，确保服务确实返回了内容；再从浏览器访问 Cloudflare 分配的域名，如果通了，才说明整条链路没问题。

还有一个快速排查技巧：cloudflared 默认会在本地启动一个 metrics 服务，地址一般是 http://localhost:2000/metrics。直接 curl 这个地址，能看到连接状态、请求数和错误码，比看面板更有用。

5. 再进一步：全文抓取、阅读状态与日常维护经验

5.1 全文提取：把RSS摘要升级为完整文章

很多 RSS 源只输出摘要，想读全文还得跳转页面。这件事我也尝试在 CFRSS 里做，但实现起来比预想的复杂。原因很简单，Worker 环境里没有 DOM，不能直接运行 Readability 这类依赖浏览器的库。但我找到一个折中方案：如果摘要太短，就主动抓取文章链接对应的 HTML，然后用正则或者 HTMLRewriter 把不需要的标签去掉，再截取前几百个字作为扩展摘要。

诚实的说，效果不如浏览器端完整提取，但对于大多数技术博客来说已经够了。如果你需要更好的质量，可以考虑用 Cloudflare 的 Browser Rendering 服务，不过那是付费能力，我还没舍得开。另外要注意，全文抓取会显著增加源站的负担，所以我只对用户真正点开的文章做全文提取，并且把结果缓存到 item:<md5>:content 里，避免重复回源。

5.2 阅读状态与收藏

阅读状态是每个阅读器的基本功能。最初我想把已读状态存在 KV 里，每次点击文章都会触发一次 KV 写入。后来算了下 KV 的费用和延迟，决定改用浏览器 localStorage。因为只要你不跨设备同步，localStorage 已经够用。点过的文章，前端在渲染时把 hash 过滤掉，或者置灰显示，逻辑简单，也不消耗 Worker 请求。

如果你真的需要跨设备同步正在阅读的状态，那就得考虑一个用户系统了，这明显超出“个人阅读器”的范围。我更建议把精力放在订阅源的管理上，而不是把私有数据搞复杂。这个阶段的取舍很关键，别让一个个人项目长成怪兽。

5.3 免费额度以外的日常维护

CFRSS 已经跑了一段时间，日常维护其实就三件事：加源、清旧数据、看日志。加源我是在 sub:list 里直接追加一个对象，然后重新部署。清理旧数据靠 Cron 里顺带执行，比如对于超过 30 天的 item: 开头 key 直接删掉。看日志用 wrangler tail 或者 Cloudflare 控制台，多盯着 Worker 错误里是不是有 exceeded limits，如果有，说明你的抓取频率太密了。

最后再分享一个小技巧：善用 Cache API。KV 虽然很快，但终归要读一遍数据。Cron 抓取到了新 RSS XML 之后，我可以先用 caches.default.match(feedUrl) 缓存原始 XML，下次如果有源暂时抓不到，直接拿缓存的旧数据顶上，而不是让用户看到“抓取失败”的空白页面。这个技巧既降低源站压力，也让阅读器表现得稳定得多。个人项目的价值就在这些细节里，别只盯着功能列表看。