Langfuse 远程缓存实践指南用 Turborepo Remote Cache 打通团队与 CI 的构建缓存【免费下载链接】langfuse Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuseLangfuse 是一个采用 Turborepo 组织的大型 pnpm monorepo根目录 package.json 声明了turbo: 2.10.5其build、lint、test、typecheck等任务全部经由 Turbo 调度。本文以仓库内置的 Turborepo 技能文档remote-cache.md为骨架系统讲解 Turborepo 远程缓存Remote Caching的原理、配置、启用方式与排障手段并对照 Langfuse 仓库的实际配置turbo.json、.github/workflows/ci.yml.template给出可直接落地的操作方案。读完本文你将掌握在本地开发与 CI 流水线之间共享构建缓存、为缓存产物签名防篡改以及自建远程缓存服务器的完整方法。远程缓存解决什么问题Turborepo 缓存的核心原则是永远不要重复做同样的工作。本地缓存.turbo/cache/下的*.tar.zst压缩产物已经能让同一台机器上的重复构建命中缓存但它无法跨机器共享团队成员的构建结果彼此隔离CI 每次都在全新 Runner 上从零开始。远程缓存把这份缓存从单机搬到了共享存储云端或自建服务器从而带来四个直接收益对应 remote-cache.md 的 Benefits 一节团队成员互相命中对方已完成的构建产物CI 命中本地开发产生的缓存反之本地开发也能复用 CI 的产物首次构建之后CI 运行时间大幅缩短彻底告别 在我机器上明明能跑 的重复编译问题——只要输入指纹一致任何机器都能还原出相同的输出。这套机制的底层依据在 caching/RULE.md 中有完整推导fingerprint(inputs) → stored outputs只要任务输入未变化就从缓存恢复输出而不是重新执行任务。缓存采用内容寻址基于输入哈希而非时间戳任何输入变化都会使缓存失效。Langfuse 中的缓存任务配置在 Langfuse 仓库根目录 turbo.json 中可以看到缓存与输入指纹的实际配置方式{ globalDependencies: [.env], globalEnv: [ NEXT_PUBLIC_LANGFUSE_BLOB_EXPORT_CUTOFF, NEXT_PUBLIC_LANGFUSE_BLOB_EXPORTER_CUTOFF, NEXT_PUBLIC_LANGFUSE_ANALYTICS_EXPORTER_CUTOFF, CLICKHOUSE_BIN ], envMode: loose, tasks: { build: { dependsOn: [db:generate, ^build], env: [NEXT_IGNORE_BUILD_ERRORS], outputs: [dist/**, .next/**, !.next/cache/**], cache: true, outputLogs: errors-only }, lint: { dependsOn: [repo/eslint-plugin#build, ^build], cache: true, outputs: [] }, typecheck: { dependsOn: [db:generate, ^build], cache: true, outputs: [] } } }几个与远程缓存直接相关的要点outputs决定哪些产物被缓存build任务声明[dist/**, .next/**, !.next/cache/**]其中!.next/cache/**是 Next.js 官方建议的排除项——Next.js 自身的内部缓存不应被 Turbo 重复打包上传lint、typecheck用空数组[]明确运行但不缓存任何文件此时 Turbo 只缓存任务日志。env决定哪些环境变量进入哈希build任务声明NEXT_IGNORE_BUILD_ERRORS配置注释解释得很清楚——该变量切换 Next.js 的类型检查带与不带它的构建绝不能共享同一缓存条目否则一个未做类型检查的缓存构建会被回放成已类型检查的结果。cache: false的任务不参与缓存Langfuse 中db:migrate、db:deploy、db:reset、db:seed、dev、db:generate等任务均被显式关闭缓存。尤其是db:generatePrisma Client 生成turbo.json 注释指出其副作用写入node_modules而 Turbo 缓存命中只回放日志、不会在全新 CI Runner 上恢复这类副作用因此必须关闭缓存。globalEnv与globalDependencies影响全部任务.env文件或上述四个全局环境变量任何变化都会使所有任务哈希失效。Langfuse 在此设置了envMode: loose即松散模式下允许更多环境变量参与哈希适合 CI 环境变量繁多的大型仓库。根目录 package.json 中的脚本统一以turbo run build、turbo run test等长格式委托 Turbo 调度如build: turbo run build这符合 Turborepo 技能文档 SKILL.md 的规范写入脚本和 CI 的必须是turbo run task而turbo build简写只用于终端交互。启用 Vercel Remote CacheVercel Remote Cache 在部署到 Vercel 时零配置自动启用——Vercel 检测到turbo.json后会自动开启缓存共享无需手动设置TURBO_TOKEN与TURBO_TEAMPreview 与生产构建共享同一份缓存。对于本地开发和其他 CI 平台需要按以下两步配置。本地开发设置# 使用 Vercel 账号认证 npx turbo login # 将仓库关联到你的 Vercel team npx turbo link执行后会生成.turbo/config.json其中写入团队信息该文件默认被 git 忽略。Langfuse 根目录 .gitignore 第 80 与 82 行恰好分别声明了**/.turbo/*与.turbo确保本地缓存目录和认证配置都不会误提交。CI 设置在 CI 环境注入两个环境变量即可TURBO_TOKENyour-token TURBO_TEAMyour-team-slugToken 在 Vercel 控制台 → Settings → Tokens 中创建。Langfuse 仓库自带的 CI 模板 .github/workflows/ci.yml.template 正是这样做的# You can leverage Vercel Remote Caching with Turbo to speed up your builds env: TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} TURBO_TEAM: ${{ secrets.TURBO_TEAM }}对应 GitHub Actions 的完整示例可参考 ci/github-actions.md 的远程缓存章节- name: Build run: npx turbo run build env: TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} TURBO_TEAM: ${{ vars.TURBO_TEAM }}实践建议TURBO_TOKEN属于敏感信息应存入仓库 SecretsTURBO_TEAM是团队 slug存入 Actions Variables 即可。Langfuse 的 CI 模板在 job 级env声明了这两个变量使其对整个 job 内所有turbo run命令生效。turbo.json 中的 remoteCache 配置在turbo.json中可对远程缓存做细粒度开关{ remoteCache: { enabled: true, signature: false } }两个选项的含义enabled是否启用远程缓存。默认值为true当已通过turbo login/turbo link完成认证时生效。设为false则彻底关闭远程缓存的读写但本地缓存不受影响。signature是否要求对缓存产物签名。默认false。开启后只有签名匹配的产物才能被还原。需要注意开启remoteCache后远程缓存与本地缓存是两层独立的存储。若只想关闭本地缓存而保留远程或反之可通过 CLI 的--cache参数精细控制见下文缓存行为控制一节。缓存产物签名防止篡改远程缓存放在共享服务器上任何能访问该服务的人都可能污染产物。Turborepo 提供基于共享密钥的产物签名机制验证缓存产物未被篡改。第一步设置密钥# 设置密钥所有环境必须使用同一个密钥 export TURBO_REMOTE_CACHE_SIGNATURE_KEYyour-secret-key第二步开启签名校验{ remoteCache: { signature: true } }工作原理与注意事项开启后每次上传产物都会附带基于密钥生成的签名还原时 Turborepo 会重新计算并比对签名。签名不匹配的产物将无法被还原从而防止了缓存投毒cache poisoning。实际使用中有三个关键约束同一密钥必须贯穿所有环境——本地开发、CI、自建缓存服务器都要设置相同的TURBO_REMOTE_CACHE_SIGNATURE_KEY否则本地写入的产物 CI 无法还原密钥本身要严格保密只通过 Secret 管理服务注入不要写进代码仓库一旦泄露密钥等于任何人都能伪造合法签名的产物需要立即轮换。自建远程缓存服务器如果不想依赖 Vercel社区提供了多种自托管实现对应 remote-cache.md 的 Self-Hosted Options 一节turbo-remote-cacheNode.js——支持 S3、GCS、Azure 对象存储turborepo-remote-cacheGo——轻量级兼容 S3 协议ducktapeRust——高性能选项。自建服务器通过三个环境变量接入TURBO_APIhttps://your-cache-server.com TURBO_TOKENyour-auth-token TURBO_TEAMyour-teamTURBO_API缓存服务地址自定义 API 端点TURBO_TOKEN访问该服务的认证令牌TURBO_TEAM命名空间用于区分不同团队的缓存。配置完成后无需修改turbo.json即可让所有任务读写远程缓存。自建方案特别适合数据合规要求严格、不能把产物放到外部云的团队其存储后端普遍支持 S3/GCS/Azure可与团队现有对象存储基础设施复用。缓存行为控制远程缓存提供了三种运行期控制手段用于不同的 CI/调试场景# 只读远程缓存读取命中的产物但不上传新产物 turbo run build --remote-cache-read-only # 完全跳过缓存既读也不写 turbo run build --no-cache # 仅使用远程缓存跳过本地缓存 TURBO_REMOTE_ONLYtrue turbo run build三个选项的适用场景--remote-cache-read-only适合临时分支或实验性改动不希望污染共享缓存--no-cache需要验证任务真实行为时等价于逐个任务cache: falseTURBO_REMOTE_ONLYtrue本地磁盘缓存已损坏或想确认远程缓存可用性时使用。此外Turborepo 2.x 还支持--cache参数的细粒度控制参见 cli/commands.md# 默认行为读写本地与远程 turbo run build --cachelocal:rw,remote:rw # 仅本地只读不使用远程 turbo run build --cachelocal:r,remote: # 关闭本地仅远程只读 turbo run build --cachelocal:,remote:r # 完全禁用所有缓存 turbo run build --cachelocal:,remote:在 Langfuse 中如需对build任务临时禁用缓存以排查问题可以运行pnpm turbo run build --cachelocal:,remote:而无需改动 turbo.json。调试远程缓存远程缓存没生效是最常见的问题。Turborepo 提供了两条调试命令# 详细输出显示每次缓存操作 turbo run build --verbosity2 # 检查远程缓存配置状态 turbo config判断是否命中的输出特征运行构建时关注以下信号对应 remote-cache.md 的 Debugging 一节输出中出现Remote caching enabled说明远程缓存已连接运行期间出现upload/download 消息说明正在与远程缓存交换产物出现cache hit, replaying output且带有远程缓存标识说明命中。结合哈希指纹排查缓存未命中如果任务仍然频繁执行未命中缓存可结合 caching/gotchas.md 的调试手段定位输入差异# 生成包含全部哈希输入的 JSON 摘要 turbo run build --summarize # 生成 .turbo/runs/run-id.json可对比两次运行的差异 # 预演不执行任何任务仅展示各任务的缓存状态 turbo run build --dry turbo run build --dryjson # 机器可读输出 # 强制重跑跳过缓存读取验证任务本身真实可用 turbo run build --force--summarize生成的 JSON 包含全局哈希及其输入、每个任务的哈希及其输入、影响哈希的环境变量清单。比较两次运行的摘要文件diff .turbo/runs/first.json .turbo/runs/second.json即可定位是哪份文件或哪个环境变量导致缓存未命中。常见的缓存未命中原因详见 caching/gotchas.md声明在任务env中的环境变量值发生变化如API_URL不同.env文件变化默认不参与哈希需加入inputs或globalDependenciesLangfuse 已通过globalDependencies: [.env]覆盖此场景依赖锁文件变化pnpm-lock.yaml更新使全局哈希变化源码文件或turbo.json本身变化。如果出现本应失效却命中缓存的反向问题重点检查任务使用的环境变量是否已加入env数组、读取的文件是否已加入inputs数组、被读取文件是否位于包目录之外。无 Vercel 时的替代方案缓存本地目录如果团队无法使用 Vercel 远程缓存GitHub Actions 的actions/cache可以退而求其次——把 Turborepo 的本地缓存目录整体缓存起来详见 ci/github-actions.md- uses: actions/cachev4 with: path: .turbo key: turbo-${{ runner.os }}-${{ hashFiles(**/turbo.json, **/pnpm-lock.yaml) }} restore-keys: | turbo-${{ runner.os }}-需要注意该方案的局限性actions/cache的缓存是按分支隔离的不同分支各自缓存跨 PR 的命中率低于远程缓存且缓存容量、保留周期受 GitHub 平台限制。因此它只能作为无法接入远程缓存时的兜底手段效果远不如真正的远程缓存——这也正是 remote-cache.md 把 Vercel Remote Cache 与自建服务器作为首推方案的原因。小结Turborepo 远程缓存的完整启用链路可以归纳为四步本地认证turbo loginturbo link→CI 注入凭据TURBO_TOKEN/TURBO_TEAM→按需开启签名TURBO_REMOTE_CACHE_SIGNATURE_KEYremoteCache.signature→运行期控制与调试--remote-cache-read-only、--no-cache、--verbosity2、turbo config。在 Langfuse 仓库中turbo.json 已为缓存打好了全部基础任务级outputs/env声明、全局globalDependencies/globalEnv、对 Prisma 与迁移类任务的cache: false精确豁免而 .github/workflows/ci.yml.template 则演示了 CI 侧注入远程缓存凭据的标准写法。接入远程缓存后团队、CI 与本地开发将共享同一份构建产物配合turbo run build --affected只构建变更包CI 耗时可以压缩到只跑真实有变动的任务是大型 monorepo 提效投入产出比最高的手段之一。【免费下载链接】langfuse Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考