Docker Compose 启动成功、浏览器能打开控制台，说明安装步骤走通了。离生产可用还差得很远。自托管把数据边界和部署控制权交给团队，也把数据库、队列、对象存储、安全和升级责任一并交了过来。
先看懂数据怎样流动
Langfuse v4 的自托管架构由两个应用容器、四类存储和可选的模型服务组成。
SDK / API / UI
│
▼
Langfuse Web ── Postgres
│ Redis / Valkey
├──────── Blob Storage
│ │
│ Worker
│ │
└────────── ClickHouse
可选：LLM API / Gateway，供 Playground、模型评估等功能使用
Web 提供控制台和 API，处理登录、项目配置、Prompt 读取及观测事件接收。Worker 消费异步任务并加工事件。Postgres 保存用户、组织、项目、API Key 和 Prompt 等事务数据；ClickHouse 保存 Trace、Observation、Score 等高容量分析数据；Redis 或 Valkey 同时承担缓存和队列；S3 兼容对象存储保存原始事件、多模态附件和大规模导出。
观测事件进入 Web 后，原始内容先写入 Blob Storage，Redis 只保存待处理引用，Worker 取回事件并写入 ClickHouse。这段设计把接收与分析存储解耦，流量突增或数据库短暂变慢时，入口不必同步等待。它也解释了常见故障：页面能登录但 Trace 迟迟查不到，应沿 Blob Storage、队列、Worker、ClickHouse 检查；附件打不开，重点看对象存储和访问策略；Prompt 获取慢，则看 Web、Postgres 和缓存。
外部 LLM API 或 Gateway 不是记录 Trace 的前提。只有 Playground、LLM-as-a-Judge 等需要调用模型的功能才依赖它。生产环境应按已启用功能开放出站网络，不必给整个部署默认互联网访问。
部署方式由可靠性目标决定
官方把 Docker Compose 定位为本地、测试和低规模部署，它本身不提供高可用、自动扩缩和完整备份。生产环境可使用 Kubernetes Helm，或 AWS、Azure、GCP 等官方 Terraform 方案。选择之前先回答：允许中断多久，最多能丢多少数据，查询延迟上限是多少，谁负责值守。团队偏好的云排在这些条件之后。
Web 和 Worker 可以独立横向扩展。入口压力高时扩 Web；事件积压时看 Worker CPU 和 ingestion queue depth，再扩 Worker。ClickHouse 的分析查询慢，通常需要检查时间过滤、资源和存储设计，简单增加 Web 副本没有帮助。Redis、Postgres、ClickHouse 和对象存储都有状态，必须按各自机制设计高可用，不能把无状态容器的扩容经验直接套过来。
所有基础设施组件，尤其 Postgres 和 ClickHouse，必须使用 UTC。官方明确指出非 UTC 时区会造成查询返回错误或为空。这个问题很隐蔽：数据可能已经写入，页面却像“没有上报”。上线检查要验证实际数据库时区，而不只看容器环境变量。
备份的目标是恢复，不是生成文件
至少备份 Postgres、ClickHouse 和 Blob Storage。Postgres 里有组织、项目、API Key 和 Prompt；ClickHouse 里有观测明细；Blob Storage 里有原始事件、媒体和导出文件。Redis 是否需要持久化取决于使用方式，但队列恢复策略必须说明。
备份任务成功不代表系统能恢复。应在隔离环境定期演练，核对项目配置、Prompt、Trace、Score 和附件能否重新访问，并记录恢复耗时。对象存储的生命周期规则也要慎重：原始事件参与恢复和部分处理流程，过早删除可能改变可恢复范围。备份副本应与生产故障域隔离，并拥有独立权限。
生产监控不能只看容器是否存活。负载均衡器和编排系统通过 health、readiness 端点决定实例能否接流量；平台团队还要观察 Web/Worker 资源与错误、队列积压、处理延迟、ClickHouse 查询、Redis 负载和存储容量。发送一条已知 Trace 并检查它能否被查询，是验证“接收、排队、处理、读取”整条链路的简单探针。
自托管不自动获得安全
数据留在公司网络内，只是改变了数据边界。生产实例仍要关闭开放注册，接入组织身份体系，按最小权限控制项目管理、原文查看、导出和删除。密钥集中管理，入口和出站网络按需开放，存储位于受控网络。脱敏、保留期限、删除和审计也要落实到具体负责人。
部分管理、安全和脱敏能力需要企业版许可证。第 11 章提到的服务端 ingestion masking 就是其中之一，并且只覆盖 OTel ingestion；自托管不等于所有企业功能免费，也不等于旧 ingestion 路径会自动经过脱敏回调。评估方案时要把开源能力、企业附加能力和自建补充项分开。
升级是一条持续运行的生产流程
Langfuse Server 与 SDK 独立版本化，v3 升 v4 还有明确的基础设施门槛：ClickHouse 至少 25.12、PostgreSQL 至少 15、Redis 至少 7.0。使用 Helm 内置 ClickHouse（clickhouse.deploy: true）的既有部署，当前官方文档尚未提供直接升级路径；外接 ClickHouse 不受这项限制。执行前必须再次核对迁移指南，因为这些条件会随版本变化。
迁移可以分阶段进行。legacy 保留 v3 行为，dual 同时写入新旧数据模型，最终再切到 v4 默认的 events_only；前两种是迁移工具，不应成为永久运行模式。选择历史数据自动回填时，ClickHouse 需要预留约三倍现有数据量的临时空间；若已有全局保留策略，也可以保持双写一个完整保留周期后自然切换。Python SDK 4.7.0+、JS/TS SDK 5.4.0+ 或带 v4 ingestion header 的 OTel 数据能实时进入新模型，较早的小版本可能出现约 15 分钟延迟。
Web 容器启动时会执行部分数据库迁移，Worker 负责耗时更长的后台回填。迁移期间要同时验证生产者、读取 API、Observation-level Evaluator、导出源和历史数据；切到 events_only 后，旧读写接口与 Trace-level Evaluator 会停止工作。预生产验证、备份、容量评估和回退方案都应围绕这一切换点展开。
一次上线评审应该问什么
评审不需要再做一张“已安装组件”清单，可以沿故障场景追问：Web 挂掉时谁接流量；Worker 积压时如何发现；ClickHouse 不可用时事件是否仍在 Blob Storage；Postgres 丢失后能恢复哪些配置；回调脱敏服务超时时是放行还是丢弃；升级卡在后台迁移时谁决定继续或回退。
上线前要为这些问题补齐责任人、告警、操作手册和最近一次演练记录；任一项缺失，都应作为明确的上线风险登记。
参考资料
系列目录：AI 应用可观测性与评估