Node 后端實(shí)戰(zhàn) · 邊緣 Cron 定時(shí)任務(wù)怎么寫Cloudflare 三個(gè)實(shí)戰(zhàn)任務(wù)與踩坑各位看官把定時(shí)任務(wù)跑在邊緣網(wǎng)絡(luò)上和我以前在單機(jī)crontab或容器里寫個(gè)Scheduled是完全兩碼事。以前那套心智模型是「一臺(tái)機(jī)器一個(gè)進(jìn)程準(zhǔn)點(diǎn)跑一次」但 Cloudflare Workers 的 Cron Triggers 是「每天某個(gè)時(shí)刻平臺(tái)在世界各地的邊緣節(jié)點(diǎn)挑一個(gè)觸發(fā)你的 Worker」——你不知道它跑在哪、上一秒的實(shí)例還在不在、這一次要跑多久會(huì)被掐。我這個(gè)多租戶系統(tǒng)有四個(gè)每天凌晨跑的定時(shí)任務(wù)預(yù)聚合統(tǒng)計(jì)、攔截名單對(duì)賬、審計(jì)日志冷熱歸檔、導(dǎo)出文件清理。這篇文章把它們的真實(shí)實(shí)現(xiàn)拆開講重點(diǎn)不是「怎么調(diào) API」而是邊緣環(huán)境逼出來(lái)的那幾個(gè)設(shè)計(jì)取舍和真實(shí)踩過(guò)的坑。一、Cron Triggers 長(zhǎng)什么樣配置即代碼寫在wrangler.toml里dev 本地不觸發(fā)只有 test/prod 注冊(cè)# ---- Cron Triggers僅 test/prod 注冊(cè)dev 本地不觸發(fā)---- [env.prod.triggers] crons [0 0 * * *, 0 1 * * *, 0 2 * * *, 0 3 * * *]四個(gè) cron 表達(dá)式分別對(duì)應(yīng)四個(gè)任務(wù)。入口是 Worker 的scheduled鉤子它把事件分發(fā)到我的任務(wù)處理器// src/index.tsasyncscheduled(event:ScheduledEvent,env:Bindings,ctx:ExecutionContext){dispatchCron(env,stats-aggregate).then((r){/* 0 點(diǎn) */});dispatchCron(env,blocklist-reconcile).then((r){/* 1 點(diǎn) */});dispatchCron(env,audit-sweep).then((r){/* 2 點(diǎn) */});dispatchCron(env,export-cleanup).then((r){/* 3 點(diǎn) */});}這里第一個(gè)要建立的認(rèn)知Cron Triggers 是「盡力而為」的不是精確 cron。平臺(tái)正常情況下每天觸發(fā)一次但極端情況下可能漏跑也可能極少見地重跑。所以我的每一個(gè)任務(wù)都設(shè)計(jì)成冪等——重跑不會(huì)重復(fù)寫臟數(shù)據(jù)。后面會(huì)反復(fù)看到這一點(diǎn)。四個(gè)任務(wù)的全貌先放一張表后面對(duì)著看更清楚任務(wù)觸發(fā)時(shí)間(每日)作用冪等方式分批策略stats-aggregate0 點(diǎn)預(yù)聚合昨日統(tǒng)計(jì)寬表upsert存在則更新可重跑單租戶內(nèi)并行聚合無(wú)大表掃blocklist-reconcile1 點(diǎn)刷新攔截標(biāo)記 聯(lián)動(dòng)取消計(jì)劃僅值變更才寫游標(biāo) 1000 條/批audit-sweep2 點(diǎn)審計(jì)日志冷熱分層 R2 冷歸檔先 R2 后刪 D1失敗跳過(guò)游標(biāo) 1000 條/批export-cleanup3 點(diǎn)清理過(guò)期導(dǎo)出文件按 TTL 刪除游標(biāo)詳見導(dǎo)出篇二、通用骨架日志 鎖 錯(cuò)誤脫敏四個(gè)任務(wù)共用一套骨架核心在dispatchCron里exportconstdispatchCronasync(env:Bindings,task:string){constdbgetDb(env);// 分布式鎖KV 讀-寫非原子KV 沒有 CAS純并發(fā)下兩個(gè)調(diào)用可能同時(shí)讀到空都進(jìn)入執(zhí)行。// Cloudflare Cron 正常不會(huì)重復(fù)觸發(fā)此為 best-effort 防護(hù)非嚴(yán)格互斥。constlockKeycron:lock:${task};constlockValawaitenv.KV.get(lockKey);if(lockValrunning)return{ok:true,processed:-1,error:already running};awaitenv.KV.put(lockKey,running,{expirationTtl:600});const{logId,startedMs}awaitcronStart(db,task);// 寫 cron_exec_logstry{// ...按 task 名分發(fā)...awaitcronEnd(db,logId,startedMs,processed,true);return{ok:true,processed};}catch(e:unknown){constraweinstanceofError?e.message:String(e);constmsgraw.length120?raw.slice(0,120)...:raw;// 脫敏截?cái)嘁瞥?SQL/路徑awaitcronEnd(db,logId,startedMs,0,false,msg).catch((){});return{ok:false,error:cron task failed};}finally{awaitenv.KV.delete(lockKey).catch((){});}};三個(gè)設(shè)計(jì)點(diǎn)值得單獨(dú)拎出來(lái)執(zhí)行日志cron_exec_logs每個(gè)任務(wù)首尾都寫一條記錄開始時(shí)間、結(jié)束時(shí)間、處理?xiàng)l數(shù)、耗時(shí)、狀態(tài)、錯(cuò)誤信息。定時(shí)任務(wù)最怕「靜默失敗」——你以為它跑了其實(shí)半路掛了。有了這張表運(yùn)維直接查statusfailed就能知道哪天哪次掛了而不是靠用戶投訴才發(fā)現(xiàn)。KV 分布式鎖是 best-effort鎖用KV.put(key, running, { expirationTtl: 600 })600 秒自動(dòng)過(guò)期兜底。但注釋里寫得很誠(chéng)實(shí)——KV 沒有 CAS比較并交換讀-寫非原子理論上并發(fā)時(shí)兩個(gè)調(diào)用都能讀到空值、都進(jìn)入執(zhí)行。Cloudflare Cron 正常不會(huì)重復(fù)觸發(fā)所以這把鎖只是兜底不能當(dāng)嚴(yán)格互斥用。真要強(qiáng)一致互斥得用 Durable Objects但為了防一個(gè)幾乎不會(huì)發(fā)生的重跑去引入 DO不劃算。錯(cuò)誤信息脫敏異常堆棧里可能含 SQL 語(yǔ)句、表名、路徑直接落庫(kù)有信息泄露風(fēng)險(xiǎn)。所以截?cái)嗟?120 字符對(duì)外只回cron task failed細(xì)節(jié)進(jìn)日志。這條和我在審計(jì)日志里的脫敏思路一致。三、任務(wù)一stats-aggregate 預(yù)聚合統(tǒng)計(jì)這個(gè)任務(wù)每天凌晨把前一天的實(shí)時(shí)數(shù)據(jù)聚合成一張寬表lead_stats_daily接口查統(tǒng)計(jì)時(shí)直接讀這張預(yù)聚合表而不是每次對(duì)大表GROUP BY。為什么必須預(yù)聚合實(shí)時(shí)統(tǒng)計(jì)要同時(shí)算「按狀態(tài)分布、按分類分布、按項(xiàng)目分布、當(dāng)日新增、當(dāng)日跟進(jìn)、當(dāng)日轉(zhuǎn)化、通話統(tǒng)計(jì)、坐席績(jī)效」……這些如果每次請(qǐng)求都現(xiàn)算大表上一堆GROUP BY直接把接口拖垮。每天算一次、結(jié)果落表讀接口從 O(聚合掃描) 變成 O(1 主鍵查)。核心難點(diǎn)是「一次算全」我用Promise.all把七個(gè)無(wú)依賴的聚合查詢并行發(fā)出去而不是串起來(lái)等// 并行執(zhí)行無(wú)依賴的聚合查詢DATA-10const[byStatusRows,catRows,projRows,addedRow,fuRow,convRow,callStatRow]awaitPromise.all([db.select({status:leads.status,n:count()}).from(leads).where(and(eq(leads.tenantId,tid),isNull(leads.deletedAt))).groupBy(leads.status),// ...按分類、按項(xiàng)目、當(dāng)日新增、當(dāng)日跟進(jìn)、當(dāng)日轉(zhuǎn)化...db.select({callCount:count(),answeredCount:sqlnumbersum(case when${callRecords.answerType} answered then 1 else 0 end),noAnswerCount:sqlnumbersum(case when${callRecords.answerType}! answered then 1 else 0 end),}).from(callRecords).where(/* 時(shí)間窗 租戶隔離 */),]);// 坐席績(jī)效用 GROUP BY 聚合查詢替代「循環(huán)內(nèi)每條查一次」的 N1 模式DB-07constuserRowsawaitdb.query.users.findMany({where:/* 租戶內(nèi) */,columns:{id:true,name:true}});constfuAggawaitdb.select({userId:leadFollowups.userId,cnt:count()}).from(leadFollowups).where(/* 時(shí)間窗 租戶 */).groupBy(leadFollowups.userId);// ...通話聚合、轉(zhuǎn)化聚合、最近跟進(jìn)時(shí)間 同理 GROUP BY再用 Map 在內(nèi)存里按 userId 拼裝...兩個(gè)真實(shí)優(yōu)化點(diǎn)Promise.all并行七個(gè)聚合查詢之間沒有依賴串行會(huì)累積延遲并行把總耗時(shí)壓到最慢那一個(gè)。GROUP BY 替代 N1坐席績(jī)效如果按「先查用戶列表、再循環(huán)為每個(gè)用戶發(fā)一條查詢」寫就是經(jīng)典的 N1。我改成幾條GROUP BY聚合 內(nèi)存Map拼裝一次掃全表而不是 N 次。冪等 upsert任務(wù)支持手動(dòng)重跑——如果某天數(shù)據(jù)算錯(cuò)了觸發(fā)一次補(bǔ)算不會(huì)插重復(fù)行而是覆蓋constexistingawaitdb.query.leadStatsDaily.findFirst({where:and(eq(leadStatsDaily.tenantId,tid),eq(leadStatsDaily.statDate,dateStr)),});if(existing){awaitdb.update(leadStatsDaily).set({/* 全部字段 */}).where(eq(leadStatsDaily.id,existing.id));}else{awaitdb.insert(leadStatsDaily).values({id:crypto.randomUUID(),/* 全部字段 */});}一個(gè)真實(shí)的坑必講聚合查詢里sum(case when ... then 1 else 0 end)這種如果當(dāng)天的callRecords一條都沒匹配上空集SQLite 的sum()會(huì)返回NULL而不是 0。而我的表字段是NOT NULL。我第一次跑的時(shí)候直接callStat.callCount當(dāng)數(shù)字用寫進(jìn)去結(jié)果觸發(fā)NOT NULL約束報(bào)錯(cuò)、整批失敗。后來(lái)改成逐字段?? 0兜底——注意?? 0只兜底「缺行」不兜底「行內(nèi)有 NULL 字段」所以每個(gè)answeredCount / noAnswerCount都得單獨(dú)兜底。這種邊緣 case 不跑一次真發(fā)現(xiàn)不了。四、任務(wù)二blocklist-reconcile 攔截名單對(duì)賬這個(gè)任務(wù)每天掃描全量數(shù)據(jù)根據(jù)最新的攔截名單刷新每條記錄的「是否被攔截」標(biāo)記并聯(lián)動(dòng)取消其待執(zhí)行的計(jì)劃。用 Set 消除 N1最蠢的寫法是對(duì)每一條記錄去查一次「它在不在攔截名單里」。正確做法是先把名單一次性查出來(lái)建一個(gè)Set然后 O(1) 判斷constblRowsawaitdb.query.blocklist.findMany({where:and(isNull(blocklist.deletedAt),or(eq(blocklist.scope,platform),and(eq(blocklist.scope,tenant),eq(blocklist.tenantId,tid)))),});constblockedPhonesnewSet(blRows.map((r)r.phone));// 平臺(tái)級(jí) 租戶級(jí)名單合并letcursor0;for(;;){constbatchawaitdb.query.leads.findMany({where:and(eq(leads.tenantId,tid),isNull(leads.deletedAt),gte(leads.createdAt,cursor)),orderBy:[asc(leads.createdAt)],limit:RECONCILE_BATCH,// 1000});if(batch.length0)break;for(constleadofbatch){if(!lead.phone)continue;consttargetblockedPhones.has(lead.phone)?1:0;if(target!lead.isBlocked){// 僅值變更才寫避免無(wú)謂寫放大awaitdb.update(leads).set({isBlocked:target}).where(eq(leads.id,lead.id));if(target1){awaitdb.update(schedules).set({status:cancelled}).where(and(/* 該線索的待執(zhí)行計(jì)劃 */));}affected;}processed;}if(batch.lengthRECONCILE_BATCH)break;cursorbatch[batch.length-1]!.createdAt1;// 游標(biāo)續(xù)跑}兩個(gè)細(xì)節(jié)游標(biāo)分頁(yè)替代 OFFSET大表用OFFSET深翻頁(yè)會(huì)越來(lái)越慢我用createdAt游標(biāo)where createdAt cursor每批 1000 條批次末尾的createdAt1作為下一批起點(diǎn)斷點(diǎn)可續(xù)、深翻頁(yè)穩(wěn)。只寫變更target ! lead.isBlocked才 UPDATE絕大多數(shù)記錄標(biāo)記沒變省下大量寫操作。五、任務(wù)三audit-sweep 審計(jì)日志冷熱分層歸檔審計(jì)日志只增不刪時(shí)間一長(zhǎng) D1 存儲(chǔ)和查詢都扛不住。這個(gè)任務(wù)做分層清理常規(guī)操作保留 365 天關(guān)鍵操作導(dǎo)出、擦除、重置密碼、登出全部設(shè)備等保留 1825 天5 年過(guò)期且非關(guān)鍵的轉(zhuǎn)存到 R2 冷歸檔后從 D1 刪除。原子性鐵律——先歸檔成功才刪源數(shù)據(jù)這是整個(gè)系統(tǒng)我立得最死的一條規(guī)矩。R2 寫入失敗寧可跳過(guò)這一批、絕不刪 D1絕不能「源沒了歸檔也沒成」導(dǎo)致數(shù)據(jù)丟失consthotThresholdMath.floor(Date.now()/1000)-AUDIT_HOT_DAYS*86400;// 365 天constcriticalThresholdMath.floor(Date.now()/1000)-AUDIT_CRITICAL_DAYS*86400;// 1825 天constcriticalActions[lead.export,lead.erase,customer.erase,user.reset-password,logout-all,tenant.suspend,tenant.renew,user.create];for(;;){constbatchawaitdb.select().from(auditLogs).where(and(gte(auditLogs.createdAt,cursor),or(and(not(inArray(auditLogs.action,criticalActions)),lt(auditLogs.createdAt,hotThreshold)),and(inArray(auditLogs.action,criticalActions),lt(auditLogs.createdAt,criticalThreshold)),))).orderBy(asc(auditLogs.createdAt)).limit(SWEEP_BATCH);// 1000if(batch.length0)break;for(constrowofbatch){constndjsonLineJSON.stringify(row)\n;constkeyaudit-archive/${row.tenantId??_platform}/${month}/${row.id}.ndjson;try{awaitenv.BUCKET.put(key,ndjsonLine);// 先寫 R2 冷歸檔awaitdb.delete(auditLogs).where(eq(auditLogs.id,row.id));// 成功后才刪 D1totalArchived;totalDeleted;}catch(e){console.error([audit-sweep] R2 put failed for${row.id}:,e);totalSkipped;// R2 失敗 → 跳過(guò)該條絕不刪源}}if(batch.lengthSWEEP_BATCH)break;cursorbatch[batch.length-1]!.createdAt1;}為什么這條鐵律重要如果反過(guò)來(lái)「先刪 D1 再寫 R2」一旦 R2 那一下網(wǎng)絡(luò)抖了或超限這條審計(jì)記錄就永久消失了——而審計(jì)日志在很多場(chǎng)景下是合規(guī)剛需丟了是要出事的。歸檔和刪除之間如果不保證順序就是在賭 R2 永遠(yuǎn)不出錯(cuò)。所以順序必須「先 R2 成功再刪 D1」R2 掛了就留著 D1 等下輪重試。month用toISOString().slice(0, 7)取YYYY-MM歸檔路徑按租戶月份分目錄方便后續(xù)按時(shí)間檢索或整體刪桶。六、邊緣 Cron 的幾個(gè)心智模型寫完三個(gè)任務(wù)回頭總結(jié)幾條邊緣 Cron 和單機(jī) cron 最大的不同維度單機(jī) cron邊緣 Cron Triggers執(zhí)行位置固定一臺(tái)機(jī)器平臺(tái)挑邊緣節(jié)點(diǎn)不固定觸發(fā)保證準(zhǔn)點(diǎn)一次盡力而為可能漏跑/重跑狀態(tài)共享本地內(nèi)存/磁盤必須走 KV/R2/D1實(shí)例無(wú)狀態(tài)時(shí)長(zhǎng)限制看機(jī)器通常很長(zhǎng)有單次執(zhí)行上限大任務(wù)要分批互斥保證本地鎖即可KV 鎖非嚴(yán)格靠?jī)绲榷档姿赃吘壎〞r(shí)任務(wù)的設(shè)計(jì)主線就兩條冪等重跑不臟數(shù)據(jù)靠 upsert/游標(biāo)續(xù)跑分批大表游標(biāo)掃、每批 1000 條、R2 失敗不刪源。把這兩條焊死漏跑重跑都不怕。七、小結(jié)邊緣 Cron 不是「把 cron 表達(dá)式搬上云」那么簡(jiǎn)單。它逼你重新想清楚狀態(tài)放哪KV/R2/D1、會(huì)不會(huì)重跑冪等 upsert、大表怎么掃游標(biāo)分批、跨存儲(chǔ)操作怎么不丟數(shù)據(jù)先歸檔后刪。我這系統(tǒng)的四個(gè)任務(wù)就是用上面那些真實(shí)代碼一點(diǎn)點(diǎn)磨出來(lái)的——尤其是審計(jì)歸檔的原子性鐵律和聚合查詢的 NULL 兜底都是線上真踩過(guò)才長(zhǎng)記性的。如果你的系統(tǒng)也在用 Cloudflare Workers定時(shí)任務(wù)這塊建議從第一天就把「執(zhí)行日志表 冪等 分批」當(dāng)成標(biāo)配別等半夜被報(bào)警叫起來(lái)才發(fā)現(xiàn)任務(wù)靜默失敗了。相關(guān)閱讀Node 后端實(shí)戰(zhàn) · 后端敏感數(shù)據(jù)怎么防泄露PII 自動(dòng)脫敏與審計(jì)日志實(shí)戰(zhàn)Node 后端實(shí)戰(zhàn) · Cloudflare Workers 限流總誤傷用內(nèi)存固定窗口替代 KV 實(shí)戰(zhàn)Serverless 導(dǎo)出 CSV 總超時(shí)用 Queue R2 異步任務(wù)徹底解決Node 后端實(shí)戰(zhàn) · 多租戶 SaaS 的數(shù)據(jù)隔離Node 后端實(shí)戰(zhàn) · JWT 雙密鑰輪轉(zhuǎn)與 token 版本號(hào)Node 后端實(shí)戰(zhàn) · D1 那些坑Node 后端實(shí)戰(zhàn) · 架構(gòu)決策全景Koa 實(shí)現(xiàn) JWT 會(huì)話與鑒權(quán)前后端分離項(xiàng)目通用方案MySQL 生產(chǎn)環(huán)境備份與恢復(fù)完整方案本文由 FungLeo 主導(dǎo)Deepseek 優(yōu)化校閱轉(zhuǎn)發(fā)請(qǐng)注明首發(fā)地址謝謝大家