RevScope

RevScope

RevScope 是网站的营收归因分析工具。页面上的小脚本会记录访客的行为（他们浏览的页面、带来他们的搜索词和引荐来源，以及他们触发的事件）。接着，RevScope 会将这些活动与他们在 Stripe、Polar、Shopify 和其他计费系统中的付款关联起来。最终结果会显示哪些页面、渠道和营销活动真正带来了营收，而不仅仅是流量。

有两种使用方式：

• 托管服务，位于 revscope.co。无需安装任何东西。
• 自己的服务端。此代码库包含运行私有实例所需的一切。最快捷的方式是使用 Docker，具体如下。

Agent 和脚本无需浏览器即可通过命令行设置托管服务：创建账号、安装跟踪器、连接集成并查询分析数据。请参阅 cli/。只能运行本地服务的 MCP 客户端可以通过 mcp-bridge/ 中的 Docker 桥接访问托管的 MCP 服务。

使用 Docker 运行自己的实例

你需要一台安装了 Docker 和 Compose v2 的机器。compose.yaml 会构建一个同时提供 Web 应用的单一后端镜像，并让它与 Postgres 一起运行。

1. 创建配置文件：

   cp docker.env.example .env
   

2. 在 .env 中填写 INTEGRATION_ENCRYPTION_KEY 和 POSTGRES_PASSWORD。每项上方的注释都给出了生成它的命令。

3. 构建并启动：

   docker compose up -d --build
   

   首次构建会编译 Rust 后端，需要几分钟时间。

4. 打开 http://localhost:4320/ui/signup 并立即创建登录账号。第一个注册的人将拥有此实例，之后注册入口会关闭。其他人只能通过邀请加入（请参阅账号的工作方式）。

让外部互联网可以访问

后端仅监听 127.0.0.1:4320，因此一开始服务器外部无法访问它。若要将其部署到公网上的域名，请选择以下一种方式：

• 使用捆绑的 Caddy 服务端。 将域名的 DNS 指向该服务器，并开放端口 80 和 443。然后在 .env 中设置以下内容：

  COMPOSE_PROFILES=caddy
  REVSCOPE_DOMAIN=analytics.example.com
  REVSCOPE_WEB_BASE_URL=https://analytics.example.com/ui
  

  再次运行 docker compose up -d。Caddy 会从 Let's Encrypt 获取证书并提供 HTTPS 服务。

• 使用自己的反向代理（nginx、Traefik 等）。将请求代理到 127.0.0.1:4320，并确保代理设置 X-Forwarded-For 标头。容器会从该标头中读取访客的 IP 地址。这样做是安全的，前提是只有这台机器能访问端口 4320，因此不要将该端口开放给更多来源。

在这两种情况下，REVSCOPE_WEB_BASE_URL 都很重要，因为邀请和密码重置等电子邮件中的链接都会使用此地址。

在网站上添加跟踪器

将 tracker/INSTALL.md 中的代码片段复制到每个页面的 <head> 中。除非你提供实例的 URL，否则该代码片段会将数据发送到托管服务。因此，请将该 URL 作为最后一行的第三个参数添加：

})(window, "examplecom", "https://analytics.example.com/");

examplecom 代表你项目的名称：可以是你注册时选择的名称，也可以是之后添加项目时仪表板显示的名称。

备份、升级和配置

你的数据存储在两个 Docker 卷中。revscope-data 中每个项目都有一个 SQLite 文件，用于存储分析事件；postgres-data 中存储登录信息、设置和集成配置。请备份这两个卷。

要升级，请运行 git pull，然后运行 docker compose up -d --build。数据库迁移会在启动时自动运行。

.env 中的每个变量都会传递给后端，因此 revscope/.env.example 中的任何选项在这里也都适用，例如邮件、AI 聊天或错误报告。更改后请运行 docker compose up -d。

访客位置（国家和城市）需要 MaxMind 免费提供的 GeoLite2-City 数据库，该数据库无法在此仓库中再分发。创建一个免费的 MaxMind 账户，并在构建前于 .env 中设置 MAXMIND_ACCOUNT_ID 和 MAXMIND_LICENSE_KEY，构建过程会下载并嵌入该数据库。如果检出目录中已存在 revscope/GeoLite2-City.mmdb，构建时会改用该文件。两者都没有时，地理定位功能将关闭。

自有实例中的账户工作方式

可自托管的实例只有一个账户，所有用户都能查看该账户的所有项目。注册时会创建第一个项目，名称由你自行选择；之后可以从仪表板添加更多项目。第一个人注册后，可在 Settings 中邀请其他人。邀请链接允许受邀者设置密码，并会在 7 天后过期；如果有人在收到最新邀请后的 30 天内仍未接受邀请，就会被移除，不再占用其电子邮件地址。如果已配置邮件（MAILCHANNELS_API_KEY 和 MAILCHANNELS_FROM_EMAIL），RevScope 会通过邮件发送链接；Settings 中始终会显示该链接，方便你自行发送。

托管服务的套餐限制不适用于此实例。事件数量没有上限，AI 聊天也没有月度预算。文档链接会指向 revscope.co。

不使用 Docker 运行自己的实例

可自托管版本是一个单独的二进制文件，其中包含后端、Web 应用、跟踪脚本、数据库迁移，以及可选的 GeoLite2 数据库。你需要安装先决条件。按如下方式构建：

(cd web && pnpm install && pnpm build:bundle)
cd revscope && cargo build --release --bin revscope --features self-hosted

二进制文件位于 revscope/target/release/revscope。请在与你的服务器使用相同操作系统和 CPU 架构的机器上构建，或进行交叉编译。

运行步骤：

1. 为其创建一个 Postgres 数据库（createdb revscope）。
2. 将 revscope/.env.example 复制到你运行二进制文件的目录中，并命名为 .env，然后填写配置。只有 DATABASE_URL 和 INTEGRATION_ENCRYPTION_KEY 是必填项。将 REVSCOPE_WEB_BASE_URL 设置为你的公开 URL，末尾加上 /ui，例如 https://analytics.example.com/ui。
3. 以非特权用户身份，通过 systemd 等进程管理器运行二进制文件。
4. 在它前面配置一个负责处理 HTTPS 的反向代理，并设置 REVSCOPE_TRUST_X_FORWARDED_FOR=true，使访客 IP 取自代理的 X-Forwarded-For 标头。请确保只能通过代理访问后端端口，否则任何人都可以伪造该标头。

Web 应用在 /ui 下提供服务，/ 会重定向到 /ui/dashboard。它会从同一源调用 API，因此无需配置跨源资源共享（CORS）。项目数据库存储在工作目录下的 data/ 中，因此请连同 Postgres 一起备份该目录。

你也可以不使用反向代理，而让后端自行通过 Let's Encrypt 证书提供 HTTPS。将 REVSCOPE_LISTEN_TLS=0.0.0.0:443、REVSCOPE_LISTEN=0.0.0.0:80（Let's Encrypt 会通过 80 端口验证域名），并将 REVSCOPE_TLS_DOMAINS 设置为你的主机名，例如 analytics.example.com。以非特权用户身份绑定 1024 以下的端口，需要 CAP_NET_BIND_SERVICE 能力。

配置

后端从环境变量以及工作目录中的 .env 文件读取设置。实际环境变量优先级更高。revscope/.env.example 列出了所有选项，并附有说明。主要分组如下：

变量	用途
DATABASE_URL, INTEGRATION_ENCRYPTION_KEY	必填：Postgres URL 和凭据密钥
REVSCOPE_LISTEN	普通 HTTP 的监听地址（默认值为 127.0.0.1:4320）
REVSCOPE_WEB_BASE_URL, REVSCOPE_API_BASE_URL	用于邮件链接和 MCP 元数据的公开 URL
REVSCOPE_TRUST_X_FORWARDED_FOR	从反向代理的标头中读取访客 IP
REVSCOPE_MAX_CONNECTIONS	连接数上限（100,000；若 ulimit -n 较低，则上限也会降低）
MAILCHANNELS_API_KEY, MAILCHANNELS_FROM_EMAIL	发送邮件（邀请、密码重置）
REVSCOPE_GOOGLE_CLIENT_ID, REVSCOPE_APPLE_CLIENT_ID	使用 Google 和 Apple 登录，未配置时隐藏
REVSCOPE_GOOGLE_CLIENT_ID, REVSCOPE_GOOGLE_CLIENT_SECRET	用于导入 Google Analytics 的“连接 Google”功能
REVSCOPE_CHAT_URL, REVSCOPE_CHAT_API_KEY, REVSCOPE_CHAT_*	AI 聊天标签页，未配置时隐藏
SENTRY_DSN	向 Sentry 报告错误
REVSCOPE_CORS_ORIGINS	与后端分开部署的 Web 应用的主机名
REVSCOPE_LISTEN_TLS, REVSCOPE_TLS_DOMAINS, REVSCOPE_ACME_*	使用 Let's Encrypt 证书启用内置 HTTPS
REVSCOPE_REQUIRE_CLOUDFLARE	托管服务服务器的设置
REVSCOPE_MCP_DEMO_TOKEN	仅可读取公开演示内容的 rsm_ MCP 令牌

INTEGRATION_ENCRYPTION_KEY 用于加密你为 Stripe 等集成输入的 API 密钥，再将其存储。如果丢失此密钥，这些密钥将无法解密，必须重新输入。

AI 聊天标签页会向兼容 OpenAI 的 Chat Completions 端点发送请求。它是为通过 Cloudflare AI Gateway 转发到 xAI 而构建的，因此 REVSCOPE_CHAT_GATEWAY_TOKEN 会作为 Cloudflare 的 cf-aig-authorization 标头发送，默认模型为 grok/grok-4.7。

开发

此仓库包含以下部分：

目录	说明
tracker/	tracker.js，一个供网站所有者嵌入网页的单文件 ES5 脚本。
revscope/	Rust 后端：事件接收、查询 API、账户和集成。每个项目使用 SQLite，账户使用 Postgres。
web/	pnpm 工作区，包含 Web 应用（web/app，使用 Astro 和 Solid）及其身份验证客户端（web/shared）。
cli/	revscope 命令行工具，仅调用 HTTP API。
crates/revscope-api/	后端和 CLI 共用的 HTTP 契约：请求和响应类型、路由路径及限制。
e2e/	驱动公开演示仪表板的 Playwright 测试。这些测试只读取数据。

代码规范、需要运行的检查，以及如何提交拉取请求，请参阅 CONTRIBUTING.md。

先决条件

• Rust。rust-toolchain.toml 固定了工具链，rustup 会在首次构建时安装它。
• Node.js 24 和 pnpm 8。请使用 pnpm，而非 npm。每个 JavaScript 项目都有自己的锁文件。
• PostgreSQL 17 或更高版本，用于后端的账户数据库及其测试。
• 可选：MaxMind GeoLite2-City 数据库，用于地理定位。 使用你的 MaxMind 凭据运行 scripts/download-maxmind.sh，即可将其下载到 revscope/。

启动本地环境

(cd web && pnpm install)

createdb revscope
cd revscope
cp .env.example .env    # set DATABASE_URL and INTEGRATION_ENCRYPTION_KEY
cargo run               # serves on http://localhost:4320

在另一个终端中启动 Web 应用：

cd web
pnpm dev                # http://localhost:4322

默认情况下，Web 应用会调用 localhost:4320 上的后端。在浏览器中请使用 localhost，而非 127.0.0.1，否则浏览器不会发送会话 Cookie。

若要为项目填充合成数据，以便试用仪表板，请在 revscope/ 中运行 cargo generate -- <project-id>。不带参数运行即可查看可用选项。

测试和检查

部分	命令
tracker/	pnpm check（代码检查，并验证文件符合 ES5），pnpm test，pnpm build（提交其输出）
revscope/	cargo fmt，然后分别在启用和未启用 --features self-hosted 的情况下运行 cargo clippy 和 cargo test
web/	pnpm tsc（类型检查），pnpm check（代码检查和格式化），pnpm test，pnpm build，pnpm build:bundle
e2e/	pnpm tsc，pnpm check，pnpm test（参见 CONTRIBUTING.md）
cli/	cargo fmt，cargo clippy，cargo test，以及在 cli/npm 中运行 npm test
crates/	cargo fmt，cargo clippy，cargo test，然后运行 revscope/ 和 cli/ 的检查

后端的端到端测试位于 revscope/tests/，需要 Postgres。它们会从环境变量或 revscope/.e2e.env 中读取 DATABASE_URL。请将其指向仅用于测试的数据库。CI 会在每个拉取请求上运行上述所有检查。

若要在本地后端上试用 tracker，请参阅 tracker/example 中的示例网站，以及 tracker/INSTALL.md 末尾的步骤。

托管服务的部署方式

本节介绍 revscope.co 自身的配置。自托管时不需要了解这些内容。

托管服务使用 billing 功能构建后端，而不是使用 self-hosted。它支持多个账户和付费套餐，并且不提供 Web 应用。套餐、结账和账单 Webhook 位于私有仓库 revscope/src/billing 中；不启用该功能构建时，每个注册用户都会获得一个免费且不受限制的账户。Web 应用则作为 revscope-app Cloudflare Worker 运行（参见 web/app/wrangler.jsonc），从 web/ 目录使用 pnpm push 部署。构建时读取的 SERVER_HOST 变量（参见 web/app/.env.example）会告知应用 API 的地址。后端会接受来自 Web 应用主机的已登录请求，这些主机列在 REVSCOPE_CORS_ORIGINS 中。

后端在多个主机名上提供服务：用于 API 的 api.revscope.co、用于跟踪器和事件接收的 in.revscope.co，以及供客户通过 CNAME 指向自有域名的 eu1.revscope.co。设置 REVSCOPE_LISTEN_TLS 后，后端会为 eu1 和 api（默认的 REVSCOPE_TLS_DOMAINS）以及客户的域名获取并续期 Let's Encrypt 证书。只有包含自定义域名的套餐（Starter 及以上）才会为客户的域名申请证书；此外，该域名必须解析到与上述主机名中第一个相同的地址。除每张证书的首次续期尝试外，系统还会限制每个账户和整体的证书申请数量。 设置 REVSCOPE_REQUIRE_CLOUDFLARE=true 后，服务器只会通过 Cloudflare 的 IP 范围提供纯 HTTP 服务，因此无法通过绕过 Cloudflare 代理的方式访问。

安全

请使用仓库 Security 标签页上的 “Report a vulnerability” 按钮私下报告漏洞，不要在公开 issue 中报告。

许可证

RevScope 根据 Functional Source License, Version 1.1, ALv2 Future License（FSL-1.1-ALv2）授权。

简而言之（此摘要不具法律约束力；以 LICENSE 文本为准）：

• 你可以将 RevScope 用于自己的站点和业务、修改它并自行托管，包括用于商业用途。
• 你不能将它或修改后的版本作为具有竞争关系的商业产品或服务提供给他人，例如托管式分析服务。
• 每个版本发布两年后，也会根据 Apache License 2.0 提供，不再受该许可证以外的限制。

RevScope 的图表使用 ApexCharts，它有自己的许可证，RevScope 的许可证不会取代该许可证。其免费的 Community License 适用于年收入低于 2M USD 的组织。如果你的组织收入更高，并且自行托管 RevScope，则需要从 ApexCharts 获取商业许可证。