OpenLabs-so/openanalytics · 上手攻略

• 仓库：OpenLabs-so/openanalytics
• 链接：https://github.com/OpenLabs-so/openanalytics
• 分类：Web Analytics · Privacy Tools
• 作者：Tom
• 更新：2026-08-17

是什么

OpenAnalytics 是一个开源、自托管、无 Cookie 的网站流量分析平台，主打隐私优先和数据主权。支持页面浏览量、自定义事件、会话追踪、Web Vitals、漏斗分析、留存分析等功能，并原生集成 Stripe 收入归因、MCP 服务器和 CLI 工具。

定位类似 Plausible Analytics 和 Umami，但架构上更重：后端采用 PostgreSQL（控制平面）+ ClickHouse（事件流）+ Valkey（队列与缓存），全套 Docker 部署。

解决什么问题

传统 Google Analytics 的问题： - Cookie 依赖 → GDPR/CCPA 合规风险 - 数据存在第三方服务器 → 隐私问题 - 部署复杂、费用高

OpenAnalytics 的解法： - 零 Cookie、零指纹：访客身份基于每日轮换的加盐哈希，IP 地址永不存储 - 全自托管：数据完全在自己的服务器上，支持 Do Not Track 和 GPC 信号 - 收入归因：直接对接 Stripe，追踪每个访客到付费转化 - 本地化地理定位：GeoIP 数据库本地运行，查询不离主机 - ClickHouse 高性能：事件存储在 ClickHouse，查询效率远高于传统 MySQL

快速安装

环境要求

• Linux 主机（Docker 已安装）
• 4 个 DNS 记录指向主机：
• app.example.com（Web Dashboard）
• api.example.com（API 服务）
• c.example.com（Collector 接收端）
• rt.example.com（Realtime SSE 流）
• 约 4 GB RAM + 25 GB 磁盘

一步部署（推荐）

# 1. 克隆仓库并切换到最新稳定版
git clone https://github.com/OpenLabs-so/openanalytics
cd openanalytics
git checkout "$(git tag -l 'v*' --sort=-v:refname | sed '/-/d' | head -1)"

# 2. 进入自托管目录，生成密钥和配置
cd infra/selfhost
./generate-secrets.sh --domain example.com --email you@example.com --with-geoip

# 3. 拉取镜像并启动
docker compose pull && docker compose up -d

# 4. 浏览器打开 https://app.example.com 创建第一个账户

⚠️ 注意：4 个域名必须在启动前解析到主机，否则 TLS 证书申请会失败，且报错信息不直观。

从源码运行（开发模式）

git clone https://github.com/OpenLabs-so/openanalytics
cd openanalytics

# 安装依赖
pnpm install

# 编译（注意顺序：编译在迁移之前）
pnpm run build
pnpm run migrate:postgres   # 先编译后迁移

# 运行测试（无需基础设施）
pnpm run test

# 完整验证（含字节预算检查）
pnpm run verify

ARM64 架构或分支构建

# 默认镜像是 amd64，ARM64 需要从源码构建
docker compose -f docker-compose.build.yml build
# 约 10 分钟 + 4GB 主机需要 swap

升级与回滚

# 升级（自动快照）
./upgrade.sh

# 回滚（需之前运行过 upgrade.sh）
./rollback.sh

⚠️ 回滚注意：迁移不可逆，回滚会丢弃升级后的数据，请提前确认。

核心用法

Web 端 Dashboard

安装后浏览器访问 https://app.example.com，创建站点后得到追踪脚本片段，嵌入目标网站：

<script
  async
  src="https://your-cdn.example.com/script.js"
  data-host-url="https://api.example.com"
  data-site-id="your-site-id"
></script>

Dashboard 提供： - 实时访客：当前在线人数（来自 Valkey 缓存，非表扫描） - 页面浏览量：按天/周/月视图 - 会话轨迹：每个访客的访问路径（身份为当日加盐哈希） - 自定义事件：可定义带属性的业务事件 - 漏斗分析：定义步骤序列，追踪转化率 - 留存分析：按天/周维度 - Web Vitals：LCP、FID、CLS - 收入归因：Stripe 集成，追踪到具体访客的付费转化 - Embed 挂件：可嵌入公开页面的统计面板

CLI 工具（oa）

# 安装（项目内 cli 目录，或通过 npx）
npx @openanalytics/oa-cli oa --help

# 站点管理
oa sites list
oa sites add --name "My Site" --domain example.com

# 查看数据
oa stats --site-id <id> --period 7d
oa pageviews --site-id <id>

# 设备流登录（无需浏览器 UI）
oa login --device-flow

MCP 服务器

OpenAnalytics 提供 MCP 协议接口，可供 AI 助手（如 Claude Desktop）直接查询站点数据。需在 .env 中配置：

OPENAI_API_KEY=sk-...  # 可选，AI 助手功能需要

MCP 工具包括：get_stats、get_realtime、get_funnels、get_events 等。

Stripe 收入归因

在 Dashboard → Site Settings → Revenue 中连接 Stripe API Key，即可开启： - 追踪每个会话到付费的转化路径 - 按来源/媒介/广告系列归因 - 支持 CSV/JSON 导入历史 Stripe 数据

地理定位（本地 GeoIP）

# 手动下载 GeoIP 数据库（首次自动也会拉取）
cd infra/selfhost/geoip
./fetch-dbip.sh

⚠️ GeoIP 数据库约 60 MB，且每月需更新一次，否则地理位置会变陈旧。

典型适用场景

坑与注意

1. 4 个 DNS 记录必须事先配置：证书申请在首次启动时执行，缺少 DNS 会静默失败，半小时后才发现。
2. GeoIP 数据库需定期更新：不更新则城市级定位越来越不准确。
3. ARM64 需从源码构建：官方镜像仅提供 amd64，Apple Silicon 用户需额外构建（约 10 分钟）。
4. 迁移不可逆：upgrade.sh 的回滚依赖快照，若未运行过 upgrade 则无法回滚。
5. 无中文 UI：Dashboard 目前仅英文界面。
6. Tracker 字节预算严格：CI 强制限制追踪脚本大小，新增功能需在预算内删除等量代码。
7. AI 助手功能可选：不填 OPENAI_API_KEY 时 AI 功能自动禁用，其余功能正常运行。
8. 版本锁定很重要：文档明确要求 checkout 到 tag 后再部署，main 分支与发布版本不兼容。

与同类对比

OpenAnalytics 的独特优势：MCP 服务器 + ClickHouse 高性能 + Stripe 收入归因三合一，是目前唯一同时具备这三者的开源方案。

一句话推荐结论

需要完全私有、零 Cookie、带收入归因的网站分析，且希望 AI 助手能直接查询数据 → 选 OpenAnalytics；追求最简单部署或不需要收入归因 → Plausible/Umami 更轻量。