Ente 的 Cloudflare Workers 基础设施：基于 npm Workspaces 的多 Worker 部署与日志实践

Ente 的 Cloudflare Workers 基础设施基于 npm Workspaces 的多 Worker 部署与日志实践【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente导读本文基于 Ente 仓库中 infra/workers/README.md 及其源码系统讲解 Ente 如何以「单一 npm 仓库 多个独立部署的 Cloudflare Worker」组织其边缘计算基础设施。你将掌握多个 Worker 共享依赖与 TypeScript 配置的 monorepo 结构、使用 Wrangler 完成登录/部署/实时日志的标准流程、通过tail_consumers将 Worker 日志聚合到 Grafana 的监控链路以及从零新建或从 Cloudflare Dashboard 迁移既有 Worker 的两种实践路径。一、概览一个仓库、多个 Worker 的 monorepo 结构Ente 将全部 Cloudflare Worker 收敛在infra/workers/目录下整体定位是「npm workspaces 的集合」每个 Worker 是一个独立的 workspace共享根部的 package.json 与 tsconfig.base.json但彼此独立部署。从目录结构看目前共有 10 个 Worker每个都包含标准的src/index.ts、package.json、tsconfig.json与wrangler.toml四件套Worker 目录主要职责从源码推断cast-albums面向 Cast 的相册相关边缘接口csp-reporter接收并聚合 Content-Security-Policy 违规报告data-puller数据拉取类任务files文件相关边缘处理health-check周期探活 API 服务并发送告警public-albums公开相册的边缘入口sentry-reporter重写并转发 Sentry 事件 DSNtail消费各 Worker 的日志并推送至 Loki/Grafanathumbnails缩略图代理附带响应安全加固uploader上传入口根部 package.json 的workspaces: [*]声明使所有子目录自动成为 workspace同时锁定统一工具链版本wrangler 4.120.1、typescript 6.0.3、cloudflare/workers-types 5.20260804.1并使用prettier 3.9.6统一代码风格。值得一提的工程细节是根 tsconfig 中types: [cloudflare/workers-types]让所有 Worker 的 TypeScript 代码无需额外安装类型包即可获得Request、Response、ExecutionContext等运行时类型。二、部署工作流登录、部署、日志与退出1. 安装依赖所有 Worker 共享同一份锁文件因此只需在仓库根部执行一次npm cinpm ci会根据 package-lock.json 做干净安装保证 CI 与本地环境依赖完全一致。2. 登录并部署Wrangler 凭据在所有 workspace 之间是共享的因此只需要登录一次即可对任意 Worker 执行部署。以health-check为例npm exec --workspace health-check -- wrangler login npm exec --workspace health-check -- wrangler deploy--workspace health-check会进入对应 workspace 读取其 wrangler.toml。要部署其他 Worker只需把health-check替换为目标 workspace 名例如npm exec --workspace uploader -- wrangler deploy。每个 Worker 独立部署的意义在于单个 Worker 的发布不影响其他服务可以按各自节奏灰度与回滚。3. 实时查看线上日志部署后可以拉取线上运行日志进行排查npm exec --workspace health-check -- wrangler tailwrangler tail会实时流式输出该 Worker 的 console 输出、异常与请求记录适合在发布后立即观察运行状况。4. 完成后退出登录npm exec --workspace health-check -- wrangler logout遵循用完即退的凭据管理习惯避免共享机器上遗留长期有效的认证状态。三、创建新 Worker 的两种路径路径一复制现有 workspace推荐仓库文档明确建议「Copy an existing workspace」即复制一个现成的 Worker 目录作为起点。这样做可以完全避开 Cloudflare 官方模板中大量与本项目无关的样板代码boilerplate新 Worker 天然继承本仓库的tsconfig、工具链版本与目录规范只需修改wrangler.toml的name、main、routes/triggers与src/index.ts的业务逻辑即可。路径二从零创建如果需要从空模板开始使用 Cloudflare 官方脚手架npm create cloudflarelatest路径三从 Cloudflare Dashboard 导入既有 Worker如果某个 Worker 已经存在于 Cloudflare Dashboard 中例如过去在网页控制台手工创建可以将其导入为本地项目npm create cloudflare2 existing-worker-name -- --type pre-existing --existing-script existing-worker-name其中--type pre-existing表示导入既有脚本--existing-script指定 Dashboard 中的脚本名。导入后即可纳入本仓库的 monorepo 统一管理。四、日志链路tail_consumers 与 Grafana 聚合1. 附加日志消费 Worker任何需要上报日志的 Worker只需在其wrangler.toml中加入tail_consumers [{ service tail }]这一配置告诉 Cloudflare该 Worker 的所有 traceconsole 输出与未捕获异常将实时转发给名为tail的 Worker 处理。仓库中health-check、uploader、public-albums、cast-albums等 Worker 均已接入例如 uploader/wrangler.toml 与 public-albums/wrangler.toml。2. tail Worker把日志推送进 Lokitail/src/index.ts 实现了日志汇聚逻辑导出tail(events: TraceItem[], env)处理程序遍历事件并仅筛选出包含 console 日志或未捕获异常的事件event.logs.length || event.exceptions.length丢弃纯请求元数据控制写入量对每条日志调用pushLogLine将事件 JSON 序列化后以 Loki 的 streams 格式 POST 到LOKI_PUSH_URL时间戳按纳秒timestampMs * 1e6写入 Loki 要求的时间格式并打上stream: { job: worker }标签便于在 Grafana 中筛选。其 wrangler.toml 中声明的两个变量均通过 Cloudflare Dashboard 以 Secret 形式注入不在源码中落盘[vars] # Added as a secret via the Cloudflare dashboard # LOKI_PUSH_URL https://${loki_base_url}/loki/api/v1/push # LOKI_AUTH ${btoa(user:pass)}其中LOKI_AUTH是user:pass的 base64 编码——代码注释特别说明Worker 的fetch不接受在 URL 中携带凭据因此只能通过Authorization: Basic请求头传递即 tail/src/index.ts 中的Authorization: \Basic ${env.LOKI_AUTH}。3. 可观测性设计意图tailWorker 的注释点明了一个刻意的设计如果 Loki 宕机导致tail自身抛异常代码不做捕获使其在该 Worker 的统计中计为一次「error」。这样日志链路的健康状态会直接反映在 Worker 级指标中避免「日志悄悄丢失」的盲区。最终所有 Worker 的日志汇聚到 Grafana与仓库 infra/services/grafana 部署的监控体系打通形成「边缘日志 → Loki → Grafana」的闭环。五、源码印证从配置与实现看 Worker 的典型形态1. health-checkCron 驱动的探活与告警health-check/wrangler.toml 展示了「非 HTTP」型 Worker 的配置范式name health-check main src/index.ts compatibility_date 2026-04-23 # Disable the default route, this worker does not handle fetch. workers_dev false tail_consumers [{ service tail }] [vars] # Added as a secret via the Cloudflare dashboard # NOTIFY_URL # CHAT_ID [triggers] crons [ */1 * * * * ]关键点workers_dev false该 Worker 不处理 fetch 请求禁用默认开发路由[triggers] crons每分钟触发一次scheduled处理器NOTIFY_URL与CHAT_ID同样以 Dashboard Secret 注入从代码看是 Telegram Bot 的推送地址与聊天 ID。对应实现 health-check/src/index.ts 的探活逻辑是ctx.waitUntil(ping(env, ctx))异步执行请求https://api.ente.com/ping若 5 秒内未返回或返回非 2xx则通过sendMessage向 Telegram 推送告警消息内容包含失败原因如Ping failed (HTTP 500)或网络异常信息并附带on ${Date()}的服务端时间戳。2. thumbnails带安全加固的反向代理thumbnails/src/index.ts 是典型的 HTTP 型 Worker对GET请求把fileID透传给上游https://api.ente.com/files/thumbnail/v3/${fileID}并在转发时设置X-Forwarded-For为客户端真实 IP取自CF-Connecting-IP让上游能感知真实来源。返回响应前执行hardenResponseHeaders安全加固设置X-Content-Type-Options: nosniff、Content-Security-Policy: sandbox allow-downloads、X-Frame-Options: DENY、Referrer-Policy: no-referrer若内容类型为 HTML/XML/SVG 等可执行类型则强制追加Content-Disposition: attachment防止 XSS 与页面嵌套。同时通过isAllowedOrigin只允许*.ente.com、*.ente.io、*.ente.sh、localhost与ente://app来源访问强化 CORS 边界。3. csp-reporter收集前端安全违规报告csp-reporter/src/index.ts 接收各客户端 POST 来的 CSP 违规报告以[csp-report]前缀写入日志经由tail_consumers进入 Loki供 Grafana 检索源码注释直接给出了对应的 LogQL 查询思路{jobworker} | \[csp-report] | json loglogs[0] | keep log。4. sentry-reporterDSN 重映射的灰度技巧sentry-reporter/src/index.ts 展示了非常实用的工程技巧将已发布客户端中固定的 Sentry DSN 映射到当前项目的 DSN。它解析事件 envelope 头中的dsn若命中 dsnMappings如 photos-mobile、auth-mobile 的旧 DSN则重写事件体与公钥后转发到https://${dsn.host}/api/${projectId}/envelope/。这样即使 Sentry 项目被重建也无需重新发布客户端即可让错误继续上报到新项目。同时只接受sentry.ente.com/sentry.ente.io的 HTTPS DSN拒绝其他来源。5. uploader / public-albums / cast-albums自定义域名路由这几个面向公网的 Worker 通过routes绑定自定义域名例如 uploader/wrangler.tomlroutes [ { pattern uploader.ente.com, custom_domain true }, { pattern uploader.ente.io, custom_domain true } ]custom_domain true表示这些域名是托管在 Cloudflare 上的自定义域请求直接由 Worker 处理无需 Zone 路由配置。六、工程实践要点总结综合 README 与源码Ente 的 Workers 体系可以归纳出四条可复用的实践monorepo 但独立部署共享 package.json 与 tsconfig.base.json后者配置了noEmit——Cloudflare Workers 运行时原生支持 TypeScripttsc仅用于类型检查每个 Worker 却拥有独立的wrangler.toml与发布节奏兼顾依赖统一与部署隔离一套凭据全局复用Wrangler 登录态跨 workspace 共享用npm exec --workspace name -- wrangler cmd统一操作避免在每个目录重复登录日志统一走 tail 消费任何 Worker 一行tail_consumers即可接入 Loki/Grafana并通过「tail 自身异常不捕获」的设计让日志链路故障可被监控到敏感配置一律走 SecretNOTIFY_URL、CHAT_ID、LOKI_PUSH_URL、LOKI_AUTH等均在wrangler.toml中以注释占位、经 Cloudflare Dashboard 注入源码中不出现任何明文凭据。如需深入某个 Worker 的实现细节可继续阅读对应的src/index.ts与wrangler.toml整个 Worker 集合的依赖与工具链版本见 infra/workers/package.json。【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考