企业官网建设流程全解析

OpenRAG遥测系统解析：匿名使用统计如何实现与关闭

【免费下载链接】openragOpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.项目地址: https://gitcode.com/GitHub_Trending/open/openrag

OpenRAG 是一个基于 Langflow、Docling 和 Opensearch 的一体化 RAG（检索增强生成）平台。它内置了一套匿名遥测（Telemetry）系统，用于收集版本、操作系统、GPU 等使用统计信息，帮助维护者了解用户的真实使用环境。本文将完整解析 OpenRAG 遥测的工作原理、采集了哪些数据，并给出 3 种快速关闭遥测的方法。

一、OpenRAG 遥测是什么？为什么需要它？

对于开源项目来说，"有多少人用、在什么环境下用、哪些功能被频繁使用"这些问题决定了后续开发的方向。OpenRAG 因此内置了遥测：

• 后端遥测：基于 Scarf），记录应用启动、文档摄入、连接器同步、聊天请求等关键事件；
• 前端遥测：基于 Segment 的页面浏览与按钮点击统计，且仅当显式配置了写入密钥时才生效，自托管场景默认关闭。

遥测采用"发射后不管"（fire-and-forget）策略：事件在后台异步发送，永远不会阻塞你的正常操作，即使网络不通或遥测服务不可用，OpenRAG 的功能也完全不受影响。

二、遥测到底采集了哪些数据？

这是用户最关心的问题。打开 client.py 可以看到每条事件携带的字段，整理如下：

⚠️不会采集的内容：你的文档内容、文件名、聊天提问、检索到的知识片段、API 密钥、IP 定位等敏感信息。遥测只反映"你用了什么功能"，而非"你用了什么数据"。

三、事件体系：类别 + 消息 ID 的双层设计

OpenRAG 的后端遥测由三个文件构成，位于 src/utils/telemetry/ 目录：

• category.py：定义 13 类事件大类，覆盖应用启停、OpenSearch 建索引、文档摄入与处理、认证、连接器、任务、聊天、错误、设置变更、新手引导等；
• message_id.py：定义具体事件 ID，统一采用ORB_前缀（OpenRAG Backend），格式为ORB_<类别>_<动作>[_<状态>]，例如ORB_DOC_INGEST_COMPLETE（文档摄入完成）、ORB_AUTH_FAILED（认证失败）；
• client.py：负责组装事件、控制重试（最多 3 次指数退避）并发送。

这种"大类 + 精确 ID"的设计，让维护者既能按功能模块做宏观统计，又能追踪某个具体环节（比如"有多少人的连接器同步失败了"）的微观表现。

四、前端遥测：默认关闭的"可选开关"

前端部分由 analytics.ts 和 analytics-provider.tsx 实现，逻辑非常克制：

1. 只有当服务端下发了SEGMENT_WRITE_KEY时才会初始化采集，否则track/page全部直接返回；
2. 在 docker-compose.yml 中，该变量的默认值为空字符串——也就是说，普通用户自行部署 OpenRAG 时，前端遥测天然处于关闭状态；
3. 即使开启，上报的也是页面浏览、按钮点击这类交互行为，不涉及任何文档或对话内容。

五、如何关闭 OpenRAG 遥测（3 种方法）

方法 1：设置 DO_NOT_TRACK 环境变量（推荐，一键关闭后端遥测）

在 client.py 中，每次发送前都会检查该变量。将以下任意值写入你的.env文件或容器环境变量：

DO_NOT_TRACK=true

true、1、yes、on均生效。设置后，所有后端遥测事件在入口处即被拦截，不会发出任何网络请求。

方法 2：保持前端 SEGMENT_WRITE_KEY 为空

自托管部署中你无需做任何事——docker-compose.yml 默认就是空的。如果你手动设置过该变量，将其删除或置空即可关闭前端统计。

方法 3：断网 / 代理屏蔽（兜底方案）

由于遥测走的是独立的 HTTPS 端点且失败时静默处理，你也可以在防火墙层面屏蔽相关域名。但这属于"治标"，优先推荐方法 1。

💡 额外提示：OpenRAG 还支持独立的 IBM Instana APM 应用性能监控，它默认关闭（INSTANA_ENABLED默认 false），与遥测互不影响。其数据导出边界与关闭方式详见官方文档 docs/docs/reference/observability.mdx。

六、总结

OpenRAG 的遥测设计体现了开源项目数据收集的三条好原则：

1. 最小化：只上报版本、系统、GPU、功能事件 ID，不碰用户数据；
2. 非侵入：异步发送、失败静默，关闭零成本（一个环境变量即可）；
3. 透明：所有采集字段和事件 ID 都明文写在 src/utils/telemetry/ 中，可随时审计。

如果你希望在保留遥测的同时确认它确实关闭了，可以在设置DO_NOT_TRACK=true后查看后端日志，会出现DO_NOT_TRACK is enabled的调试记录。放心使用 OpenRAG 构建你的 RAG 应用吧——你的文档内容，始终只留在你的服务器上。

【免费下载链接】openragOpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.项目地址: https://gitcode.com/GitHub_Trending/open/openrag