Langfuse PR 预览环境（PR Preview）完整指南：从自动化构建、数据注入到 kubectl 调试

Langfuse PR 预览环境PR Preview完整指南从自动化构建、数据注入到 kubectl 调试【免费下载链接】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每个合并到langfuse/langfuse主仓库的 Pull Request 都会自动获得一个一次性的全栈预览环境https://pr-N.preview.langfuse.com——web 与 worker 镜像随之构建Argo CD 负责部署PR 关闭即整体销毁。本文以仓库内 .agents/skills/langfuse-previews/SKILL.md 为骨架结合.github/workflows/下的真实工作流与 seeder 源码完整讲解预览的访问模型、使用流程、数据注入、故障排查与权限开通帮助你或你的 coding agent把预览用成日常开发的一部分。⚠️ 仅限合成数据Synthetic data only预览的登录是共享的、URL 是公开的——永远不要把真实凭据、API Key 或客户数据放进预览。把每个预览都当成一次性的。访问模型两道相互独立的门槛Langfuse 的 PR 预览系统把「构建」与「部署」拆成两个独立决策任何一道不过关都不会有可用的预览。第一道构建——任何拥有写权限的成员每一个同仓库same-repoPR在打开时都会被自动打上preview标签并构建 web worker 两个镜像。这里的门槛是写push权限——打开同仓库 PR 本身就需要 push 权限。Fork 的 PR 永远不会构建或部署公开仓库的 PR 无法铸造云凭据OIDC 信任被限制在subrepo:langfuse/langfuse:pull_request且refrefs/pull/*。从源码看自动打标签由 .github/workflows/preview-autolabel.yml 完成触发器使用普通的pull_request不是pull_request_target不暴露云凭据、不 checkout、不执行 PR 代码只做 GitHub API 调用if: vars.AWS_PREVIEW_ECR_PUSH_ROLE_ARN ! ——该变量同时充当整个预览系统的功能开关未设置即表示系统关闭不自动打标签脚本第一件事就是检查pr.head.repo.full_name !${owner}/${repo}Fork PR 直接 return自动打标签仅限于同仓库分支该工作流还会根据改动文件自动追加api-spec与storybook标签触发 api-spec-preview.yml 与 storybook-preview.yml 两个额外的预览构建。第二道部署——基于作者的允许名单一个预览只有在 PR作者位于部署允许名单上时才会得到真实可访问的 URL。允许名单是 Argo CD ApplicationSet 里的authorselector位于私有仓库langfuse/infrastructure。不在名单上PR 仍然会构建镜像但 URL 会 404——按下文 Getting access 把自己加进去即可。构建与部署流水线真正的构建在 .github/workflows/preview-build.yml 中实现其设计与 SKILL.md 的描述一一对应镜像标签pr-n-full-40-char-sha。注释明确警告Argo 的 ApplicationSet 部署pr-n-{{.head_sha}}Argo 的全长 40 位 SHA所以推送的 tag 必须用完整 SHA否则部署的镜像永远无法解析形成永久ImagePullBackOff。并行构建web 与 worker 是两个独立工件、推送到两个独立 ECR 仓库、同一 tag 下无顺序依赖因此在不同 runner 上并行构建。metajob 只解析 tag 并发布一次 building 评论矩阵buildjob 并行构建两个镜像notifyjob 在两者都完成后发布唯一的成功/失败评论。墙钟时间从「两者之和」降为「两者取 max」。web 镜像的构建参数NEXT_PUBLIC_SIGN_UP_DISABLEDfalse开放注册Mailpit 捕获邮件且不转发、NEXT_PUBLIC_LANGFUSE_CLOUD_REGIONDEV云区域必须在构建期烘焙进客户端 bundle预览才能渲染云专属 AI 功能、NEXT_PUBLIC_PREVIEW_DEMO_AUTO_SIGN_INtrue共享 demo 身份自动登录。幂等性预览 ECR 仓库是 tag 不可变tag-immutable的重复推送同一 tag 会失败。因此先aws ecr describe-images检查——只有ImageNotFoundException才判定「缺失→构建」其他任何 describe 失败都大声失败而不是落入对不可变 tag 的硬失败。预览环境本身的命名空间是langfuse-pr-Nchart 把一切组件都命名为namespace-component如langfuse-pr-42-web、langfuse-pr-42-worker这也是后续所有 kubectl 调试命令的推导基础。使用一个预览启动Spin up打开一个同仓库 PR 即可全自动PR 打开即被自动打上preview标签并开始构建约 5 分钟机器人评论发布预览 URL 与登录信息一行Live preview:会被钉在 PR 描述顶部拆除时会移除共享的 GitHubPR Preview环境会为该 PR 生成一个View deployment按钮。从 preview-build.yml 的notifyjob 可以看到三个发布面marker-tagged 状态评论、原生 GitHub deploymentView deployment 按钮、钉在 PR 描述顶部的机器管理块用!-- aws-preview-pin:start --/!-- aws-preview-pin:end --隐藏标记包裹只动自己那段从不触碰作者在下方写的正文。登录预览会用共享 demo 用户自动登录直接打开 URL 即可。若要走常规登录流程例如测试 auth 相关改动打开/auth/sign-in?autoSignInfalse使用机器人 PR 评论唯一事实来源中的凭据通过 UI 登出也会落到这个退出登录的表单直到你下次打开受保护页面。共享种子身份为demolangfuse.com/passwordAPI keys 为pk-lf-1234567890/sk-lf-1234567890。这些在源码 packages/shared/scripts/seeder/seed-postgres.ts 与 packages/shared/scripts/seeder/utils/postgres-seed-constants.ts 中都有定义——共享且合成永远不要把预览当作私有环境。真正的加密机密ENCRYPTION_KEY/SALT/NEXTAUTH、DB 密码由 chart 的 pre-sync hook 在集群内随机生成从不离开命名空间。从 Linear 打开任何关联到 PR 的 Linear issue 上预览位于该 issue 的Preview快捷键之后。Linear 通过解析 PR 描述和机器人评论中标签以 preview 结尾的 markdown 链接来构建这个快捷键所以两个预览面都把链接标成那样pr-N app preview、pr-N storybook preview——编辑任一条评论时都要保留这个后缀否则快捷键会消失。裸 URL 不会被匹配。读取捕获的邮件每个预览都有一个命名空间内的 Mailpit SMTP 接收端邀请、密码重置、批量导出、消费告警、提及都走它不发送真实邮件。UI 不公开需要端口转发kubectl -n langfuse-pr-N port-forward svc/preview-mailpit 8025:8025然后打开http://localhost:8025。知道你在哪每个预览页面顶部都有一条条带链接回对应的 PR并显示作者与预览内容最后变更时间。这正是 preview-build.yml 在构建 web 镜像时通过NEXT_PUBLIC_PREVIEW_PR_URL、NEXT_PUBLIC_PREVIEW_PR_AUTHOR、NEXT_PUBLIC_PREVIEW_LAST_UPDATED三个构建参数烘焙进客户端 bundle 的 PR 元数据。更新推送到 PR 即触发重建并滚动到新镜像约 5 分钟URL 不变、数据保留。重建期间出现短暂的ImagePullBackOff是正常的会自愈——工作流里的 AWS preview building评论也预告了这一点。拆除关闭 PR或移除preview标签命名空间、数据与 DNS 记录全部删除。合并会关闭 PR所以合并同样触发拆除。preview-deactivate.yml 在closed/unlabeled事件下清除该 PR 在共享PR Preview环境中的原生 GitHub deployment 记录避免 GitHub 继续宣传一个死 URL真正的资源拆除则由 Argo CD ApplicationSet只对 open 且带标签的 PR 生成 Application完成。另外 preview-stale-cleanup.yml 每天 06:00 UTC 运行一次也可workflow_dispatch手动触发把超过stale_days默认 2 天无活动的 open PR 上的preview标签移除从而回收空闲预览。要点备忘Good to know非工作时间休眠预览只在欧洲/柏林时间 周一至周五 08:00–24:00运行夜间和周末缩容到零并保持是调度驱动的——请求不会唤醒它们。非工作时间要用需要集群访问权限去唤醒kubectl annotate ns langfuse-pr-N downscaler/force-uptimetrue --overwrite副本约 60 秒恢复就绪约 3–5 分钟之后用尾带-的形式downscaler/force-uptime-撤销让它重新按调度休眠。容量同时运行的预览数量有限集群满时新预览的 pod 会停在Pending直到旧预览被关闭。数据一次性关闭 PR 即销毁其数据库重新打开得到的是全新的环境而不是旧的。Fork 无法预览外部 / fork PR 从不构建或部署。在预览中注入或改进数据预览启动时预置了 demo 项目和一些合成 trace。要注入你正在测试的特定形态——极深的 trace、巨大的 session、用于列表性能的批量 trace、v4 事件、畸形 payload——在你的本地 checkout 上运行确定性的seed CLI通过port-forward指向预览的数据存储。前提需要集群访问权限见 Getting access以及一份可用的本地.env即你正常的本地开发配置——它提供除 DB 连接以外的一切DB 连接由下面的命令覆盖。NSlangfuse-pr-N # e.g. langfuse-pr-42 # 1. 把 Postgres ClickHouse 隧道到 localhost保持运行 kubectl -n $NS port-forward svc/$NS-postgresql 5432:5432 CH$(kubectl -n $NS get svc -o name | grep clickhouse | head -1) kubectl -n $NS port-forward $CH 8123:8123 # 2. 每个预览生成的密码合成、一次性 PGPW$(kubectl -n $NS get secret langfuse-secrets -o jsonpath{.data.postgres-password} | base64 -d) CHPW$(kubectl -n $NS get secret langfuse-secrets -o jsonpath{.data.clickhouse-password} | base64 -d) # 3. seed —— 只覆盖 DB 连接其余由你的 .env 提供 # NEXTAUTH_URL 让 CLI 打印的深链指向预览 UI cd packages/shared DATABASE_URLpostgresql://postgres:$PGPWlocalhost:5432/postgres_langfuse \ CLICKHOUSE_URLhttp://localhost:8123 CLICKHOUSE_PASSWORD$CHPW \ NEXTAUTH_URLhttps://pr-N.preview.langfuse.com \ pnpm run seed:scenario -- deep-chain --v4命令seed:scenario在 packages/shared/package.json 中定义为dotenv -e ../../.env -- tsx scripts/seeder/cli.ts场景代码位于 packages/shared/scripts/seeder/scenarios/已有deep-chain.ts、agent-timeline.ts、many-traces.ts、session-shapes.ts、payload.ts等 20 余个场景。使用要点pnpm run seed:scenario -- list列出所有场景和 flag加--dry-run可预测计数且不写入任何数据。完整目录见 .agents/skills/seed-test-data/SKILL.md。最后一行 stdout 是一个 JSON 摘要包含verified和可点击的links直达预览 UI。从一个migrations 与 PR 匹配的 checkout 运行——场景代码与预览 DB 必须一致所以要从 PR 的分支 seed通常已 checkout而不是过期的main。仅合成数据——与预览中其他任何地方同样的规则。调试一个预览需要集群访问权限见下。先把 PR 的命名空间设置好——chart 把所有东西都命名为namespace-component其余都能从它推导NSlangfuse-pr-N # e.g. langfuse-pr-42在运行什么 / 健康吗kubectl -n $NS get pods # web, worker, postgresql, clickhouse, redis, minio kubectl -n $NS get pods,svc,ingress,pvc # 更全的视图什么都没列出大概是非工作时间睡着了——唤醒它见下。应用日志——通常第一站kubectl -n $NS logs deploy/$NS-web --tail200 -f # web: UI / API 服务器 kubectl -n $NS logs deploy/$NS-worker --tail200 -f # worker: 摄取 异步任务去掉-f是一次性转储--since15m按时间限定-p/--previous显示重启后崩溃容器的日志处理CrashLoopBackOff时用。数据存储日志单节点确切的 pod 名从get pods获取kubectl -n $NS logs sts/$NS-postgresql --tail100 CH$(kubectl -n $NS get pods -o name | grep clickhouse | head -1) kubectl -n $NS logs $CH --tail100 # 单节点 ClickHouse —— 留意 OOM / 重启pod 起不来Pending / CrashLoopBackOff / ImagePullBackOffkubectl -n $NS describe pod pod # 底部的 Events 列表就是原因 kubectl -n $NS get events --sort-by.lastTimestamp | tail -30进入 shell / 重启 / 绕过 ALB 访问kubectl -n $NS exec -it deploy/$NS-web -- sh # 检查 env、curl 内部服务 kubectl -n $NS rollout restart deploy/$NS-web # 修复后重新滚动 kubectl -n $NS port-forward deploy/$NS-web 3000:3000 # 访问 localhost:3000绕过 ALB唤醒休眠中的预览非工作时间kubectl annotate ns $NS downscaler/force-uptimetrue --overwrite # 副本约 60 秒恢复就绪约 3–5 分钟 kubectl annotate ns $NS downscaler/force-uptime- # 之后撤销让它按调度休眠症状 → 修复症状可能原因 / 修复预览环境不可用检查preview标签并查看AWS preview build工作流。如果 PR 打开时带合并冲突解决冲突下一次更新会补上标签。其他 CI 检查不会阻塞预览构建。 构建评论已发但 URL 404PR 作者不在部署允许名单上——镜像构建了但什么都没部署。把自己加上见 Getting access。构建后 URL 尚未就绪构建仍在收尾约 5 分钟或短暂的ImagePullBackOff——会自愈。夜间 / 周末无响应非工作时间睡着了——唤醒它见上。pod 一直Pending无法调度集群达到预览容量上限——关闭一个旧预览。ClickHouse pod 重启 / OOM单节点 ClickHouse 是最脆弱的一环——先查它的日志。获取访问权限Getting access部署访问——自助服务把自己的 GitHub 登录名加进k8s/preview/bootstrap/applicationset.yaml私有仓库langfuse/infrastructure的authorselector开一个 PR 并合并到main。Argo 重新同步后你的带标签 PR 就会部署——无需管理员。集群访问——所有 Langfuse 工程师可用只有调试kubectl时需要使用预览不需要打开~/.aws/config从内部 tracker 文档Connect to AWS instances (Aurora, Redis) from local machine添加[sso-session langfuse][profile preview]两个块保留你已有的[sso-session langfuse]。aws sso login --profile previewaws eks update-kubeconfig --name langfuse-preview --region eu-west-1 --profile preview不需要--role-arn——该 role 有自己的 EKS access entry。预览系统的架构边界预览的基础设施——EKS 集群、Argo CD ApplicationSet、Helm chart、管理员入职 runbook——全部位于私有仓库langfuse/infrastructure的k8s/preview/目录。SKILL.md 明确指出要改预览系统去那个仓库改而不是在这里。当前仓库内的 .github/workflows/preview-autolabel.yml、preview-build.yml、preview-deactivate.yml、preview-stale-cleanup.yml 只负责构建、发布与 GitHub 侧的记录管理预览环境的真实生命周期创建命名空间、部署、缩容、休眠、级联删除始终由 Argo CD 拥有。从整体设计可以看出这套预览体系把「写权限即可构建」「作者名单才能部署」「调度驱动休眠」「标签即生命周期开关」几个原则组合起来在保证安全边界Fork 不碰、合成数据、公开登录的同时把同仓库 PR 的体验压到了「开 PR 即得环境」的零门槛。对 Langfuse 的贡献者与 coding agent 来说.agents/skills/langfuse-previews/SKILL.md 就是这套系统的操作手册而.github/workflows/下的四个工作流则是它的可读实现。【免费下载链接】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），仅供参考