Fanout

Fanout

单二进制、原生支持 Agent 的 OpenTelemetry 调查工具。

Fanout 将 OpenTelemetry 跟踪、日志和指标保存在一个二进制文件和一个数据目录中，无需运维外部存储服务。Fanout 目前处于预发布阶段，更新时不提供迁移路径；浏览器客户端、内置 Agent、MCP 工具、仪表板和告警均为预览功能 （状态）。请从文档开始，或按下方说明运行。

• 通过 gRPC 和 HTTP 接收 OTLP 数据，使用本地 Parquet 存储和 DuckDB 分析。
• 调查 Agent 可用通俗语言回答有关遥测数据的问题。
• 为外部 Agent 提供 MCP 服务，使用相同的类型化查询工具。
• 提供涵盖跟踪、日志和指标的仪表板，并针对服务错误率、延迟、吞吐量和日志量设置告警。

快速开始

Docker

docker run --name fanout -p 7520:7520 \
  -v fanout-data:/var/lib/fanout/data \
  -e FANOUT_AUTH_CODE_SECRET=$(openssl rand -hex 32) \
  labstack/fanout:latest

打开容器输出的一次性设置 URL，创建首位管理员。Fanout 只会显示一次数据接收令牌；请将其与 Collector 密钥一同保存。若要在之后无需 SMTP 即可登录，可针对运行中的容器控制数据库生成有效期为 15 分钟、只能使用一次的链接：

docker exec fanout fanout login-link [email protected]

UI、API、MCP 和两种 OTLP 传输共用端口 7520。有关镜像默认值和绑定挂载的所有权，请参阅安装；有关设置和 SMTP 登录，请参阅首次启动。

原生二进制文件

安装适用于 Linux 或 macOS、amd64 或 arm64 的校验和已验证版本：

curl -fsSL https://raw.githubusercontent.com/labstack/fanout/main/scripts/install.sh | sh
export FANOUT_AUTH_CODE_SECRET=$(openssl rand -hex 32)
fanout

设置 FANOUT_VERSION=v2026.10.1-alpha 以固定版本，并设置 FANOUT_PREFIX 以选择安装目录。原生安装会绑定到 127.0.0.1:7520；如需远程访问，请设置 FANOUT_ADDR=:7520，然后按照相同的首次启动步骤操作。

发送遥测数据

标准 OTLP/HTTP 导出器可以使用已保存的数据接收令牌：

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:7520
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer%20$INGEST_TOKEN"

对于同一私有容器网络中的 Collector，转发端配置如下：

exporters:
  otlp_http/fanout:
    endpoint: http://fanout:7520
    headers:
      Authorization: "Bearer ${env:INGEST_TOKEN}"

service:
  pipelines:
    traces:  { receivers: [otlp], exporters: [otlp_http/fanout] }
    metrics: { receivers: [otlp], exporters: [otlp_http/fanout] }
    logs:    { receivers: [otlp], exporters: [otlp_http/fanout] }

使用现有的 otlp 接收器，设置 INGEST_TOKEN，并将 fanout 替换为 Collector 可访问的私有主机名。本地使用 OTLP/gRPC 时，请使用 localhost:7520；有关 TLS 和 HTTP/2 设置，请参阅发送遥测数据。

启用聊天

设置 FANOUT_AI_PROVIDER=anthropic 并注入 ANTHROPIC_API_KEY，或者设置 FANOUT_AI_PROVIDER=openai 并注入 OPENAI_API_KEY，然后重启 Fanout；所选提供商要求启动时提供对应的密钥。未配置提供商时，聊天功能会被禁用，其他功能仍可使用。请参阅 AI 设置。

连接 MCP 客户端

将 FANOUT_PUBLIC_URL 设置为稳定、外部可访问的 HTTPS 源地址，然后让远程 MCP 客户端连接到该源地址的 /mcp 端点。客户端会通过 OAuth 自动发现并注册；你可以在浏览器中授权其作用域。客户端必须支持通过无状态 Streamable HTTP 使用 MCP 协议 2026-07-28；不支持较早版本和 initialize 握手。有关设置和权限，请参阅通过 MCP 连接。

对比

如果你使用	Fanout 的不同之处
Grafana、Loki、Tempo 和 Mimir	这套技术栈为每种信号分别保留一个服务和一种查询语言，底层还需要对象存储。Fanout 将三种信号统一到一个进程、一个数据目录和一套类型化契约中，但因此不具备这些组件专为水平扩展而设计的能力。
SigNoz	两者都原生支持 OTLP，且可自托管。SigNoz 由采集器、ClickHouse 和查询服务组成；Fanout 则将数据摄取、权威 Parquet 存储、索引化追踪读取、DuckDB 分析、告警和浏览器客户端编译进一个二进制文件。
Jaeger	Jaeger 支持追踪，并要求你单独运行存储后端。Fanout 将追踪、日志和指标摄取到同一个存储中，无需部署其他组件。
Prometheus 和 Grafana	Prometheus 通过拉取方式采集指标，且在这方面表现出色。Fanout 接受三种信号的推送式 OTLP，专为调查具体事件而构建，而非维护长期指标序列。
Datadog、Honeycomb、Grafana Cloud	这些都是托管服务：存储、扩展和升级由其他人负责，你的遥测数据会离开你的网络。Fanout 是你自行运行的二进制文件，数据留在你的磁盘上。
将 OpenTelemetry Collector 接入 ClickHouse	形态相同，但需要手动组装：采集器、数据库、仪表板以及它们之间的胶合层。Fanout 将这些组装为一个程序，并已将 Agent 和 MCP 服务接入同一套查询契约。

Fanout 是单节点架构。它没有集群、没有复制，也没有对象存储层；如果部署所需的磁盘和 CPU 超出一台机器的能力，就说明 Fanout 已不再适用。

架构

一个进程包含数据摄取、存储、查询、告警、Agent、MCP 和 React 客户端。浏览器客户端和 Agent 客户端共用一套类型化可观测性契约。

Parquet 存储遥测数据，DuckDB 查询状态可重建，SQLite 则保存事务性产品状态。请参阅存储工作原理，了解持久化数据摄取、索引化读取以及在读取持续进行时执行压缩的方式。

配置

配置仅通过环境变量设置：先应用内置默认值，再应用非空的进程环境变量；在打开数据文件或监听器之前会进行验证。设置只在启动时读取；任何变更都需要重启。

环境变量	默认值	用途
FANOUT_ADDR	127.0.0.1:7520	UI、API、MCP 和两种 OTLP 传输
FANOUT_DATA_DIR	./data	Parquet、查询状态和控制用 SQLite
FANOUT_AUTH_MODE	local	登录链接或 SMTP，或 oidc
FANOUT_AUTH_CODE_SECRET	—	local 模式下必填，至少 32 个字符
FANOUT_AI_PROVIDER	—	留空则禁用聊天；设置为 anthropic 或 openai 则启用
ANTHROPIC_API_KEY	—	Anthropic 聊天的必填项
OPENAI_API_KEY	—	OpenAI 聊天的必填项
FANOUT_RETENTION_DAYS	30	遥测数据保留期限
FANOUT_MCP_ENABLED	true	在 /mcp 提供 MCP 端点

每个密钥都可以用 <NAME>_FILE 代替直接填写密钥值；验证规则请参阅设置参考，部署示例请参阅运行时密钥传递。

DuckDB 高级容量规划

Fanout 会自动调整 DuckDB 的容量；如DuckDB 容量规划所述，也可根据测得的工作负载调整内存、连接数和线程数。

有关 TLS、健康检查、备份、升级、保留和恢复，请参阅运维手册。

性能

Fanout v2026.10.8-alpha 在 Hetzner Cloud ccx33（8 个专用 vCPU、32 GB RAM）上，以单独一台 ccx33 运行 telemetrygen，在 303.5 秒内处理了 每秒 415,859 个混合 OpenTelemetry 项。10 月 16 日 2026 年的摄取测试通过了所有质量门槛。请参阅性能测试方法。 Fanout Bench 可在你的硬件上复现这项测量。

从源代码构建

• Go 1.27.3 和 C/C++ 工具链，适用于原生 Linux 或 macOS，amd64 或 arm64。 使用 just build 或 bash scripts/with-duckdb.sh go build ./cmd/fanout 构建； 此封装脚本会提供 DuckDB 固定版本的头文件、静态库和 CGO 标志。 首次构建需要联网下载经过校验和验证的引擎。
• Bun — 编译浏览器资源
• Node.js 24.19.0 — 运行开发辅助工具并构建文档站点
• just — 任务运行器
• 32 个字符的认证码密钥

git clone https://github.com/labstack/fanout.git
cd fanout
just install   # browser dependencies and git hooks
just build     # browser assets, then the binary

使用最小配置运行：

export FANOUT_AUTH_CODE_SECRET=$(openssl rand -hex 32) # must be 32+ characters

./bin/fanout

打开 http://localhost:7520 并按照首次启动设置进行操作。SMTP 和聊天功能均为可选；若未配置 SMTP，请使用相同的配置和数据目录运行 ./bin/fanout login-link [email protected]。

开发

运行 just 查看任务列表，运行 just check 执行完整检查，运行 just test 运行 Go 测试，运行 just ui 重新构建嵌入式浏览器资源。有关环境设置、生成的资源、钩子和项目布局，请参阅 CONTRIBUTING.md。

发布

版本采用 CalVer 格式——vYYYY.M.N[-alpha|-beta|-rc]，每月从 0 开始编号，所有成熟度后缀共用编号。Fanout 目前处于 alpha 阶段（例如 v2026.10.1-alpha）；GA 版本不带后缀。容器标签省略开头的 v，每次发布都会更新 latest。带标签的发布会将相同的清单发布到 Docker Hub（labstack/fanout）和 GHCR（ghcr.io/labstack/fanout）；GHCR 是规范来源，也承载开发镜像。

镜像标签	指向
labstack/fanout:latest	最新发布版本，同时镜像到 Docker Hub
labstack/fanout:2026.10.1-alpha	对应的确切发布版本，同时镜像到 Docker Hub
ghcr.io/labstack/fanout:latest	最新发布版本
ghcr.io/labstack/fanout:2026.10.1-alpha	对应的确切发布版本
ghcr.io/labstack/fanout:main	main 的最新提交
ghcr.io/labstack/fanout:sha-<commit>	某个特定提交

有关支持的平台、校验和、来源证明和验证，请参阅 docs/release.md。

贡献

欢迎提交问题和拉取请求；请遵循 CONTRIBUTING.md，并在提交拉取请求前运行 just check 和 just test-race。请通过 SECURITY.md 报告安全问题。

范围

本仓库可独立构建 Fanout；不包含 LabStack 的部署配置、运行时间监控和公开演示实例。仓库包含 site/ 中的文档站点；其设置页面由与加载器绑定的同一个 internal/config 类型生成，并由 just check 检查。

许可证

Apache-2.0 © LabStack LLC。署名信息请参阅 NOTICE 和 [THIRD_PARTY_NOTICES]（THIRD_PARTY_NOTICES）；关于 Fanout 名称和徽标的使用，请参阅 TRADEMARK。