文档目录

Velotrak 文档

Velotrak 是自托管广告追踪器:一个 Go 程序,PostgreSQL 存账本,ClickHouse 存点击。这些页面说明如何安装,以及当前产品里的活动、分流、回传、CAPI、报表、MCP、备份和授权如何工作。

开始

  • Velotrak 入门

    Velotrak 是自托管广告追踪器:Linux 上一个 Go 程序,PostgreSQL 存账本,ClickHouse 存点击。一条命令安装,在向导里创建管理员,然后把流量指到 /click/ 链接。

  • 在 Linux 上安装 Velotrak

    在 Linux 服务器上以 root 运行 curl -fsSL https://velotrak.app/install.sh | sudo bash。脚本会在需要时安装 Docker,在本机启动 PostgreSQL 和 ClickHouse,并用 systemd 运行 Velotrak。

  • Cloudflare 代理下的 Velotrak

    Cloudflare 直接连到 Velotrak 时,点击记下的是 CF-Connecting-IP 里的访客,不是边缘节点的地址。SSL 模式用 Full (strict),并安装证书文件。橙色云终结 TLS 时,内置 ACME 无法签发,也无法续期。

追踪

  • 活动、流量源、Offer 和 Flow

    活动把流量源、域名和 Flow 绑在一起。公开链接是 /click/<活动 id>。Flow 先选路径,再选落地页或 Offer,点击 ID 会跟着访客直到联盟回传。

  • Flow 规则和条件字段

    Flow 按优先级判断已启用的规则,把点击送到一条路径或一个安全页。内置字段是 15 个访客属性加上 token1–token10。流量源参数是额外字段。没有条件的已启用规则不会命中。

  • Velotrak 里的落地页

    落地页要么是 Velotrak 在 /lp/<id>/ 上提供的文件,要么是一个外部 URL。上传不超过 25 MiB 的 ZIP,或在文件接口里编辑 HTML、CSS 和 JS。把 index.html 放在根上,落地页地址才有页面。

  • Velotrak 的转化和回传

    联盟调用 /postback/<联盟密钥> 并带上点击 ID。入账状态是 approved、pending、rejected、refunded 和 trash。一次点击只能由它被送到的那个 Offer 所属的联盟入账。

  • Meta、TikTok 和 Google 的 CAPI

    Velotrak 把已批准的转化从你在后台创建的集成发到 Meta、TikTok 或 Google。Free 每个平台一个 CAPI 账号。Pro、Team 和 Founder 不限制个数。CAPI 投递不受授权开关限制。

  • Velotrak 的成本模型和分摊

    每个活动有一个成本模型。CPC 和 CPM 在点击上写入成本。CPA、manual 和 auto 在点击当时写 0。manual 和 auto 可以接收一笔按当天点击分摊的每日总额。从广告账户自动拉取是 Pro 功能。

  • 报表和保存的视图

    报表按活动、Offer、地理、设备、token 和时间汇总点击日志。Free 查询最近 15 天,最多 2 个维度。Pro 及以上保留全部历史,可用 5 个维度。每个用户可以保存视图。CSV 导出使用同一次查询。

运维

  • 用 MCP 连接 AI 助手

    管理员在 Velotrak 后台创建令牌。客户端向追踪器源站的 POST /mcp 发送 Authorization: Bearer vtmcp_…。编辑和删除会先返回 diff,并等待同一次调用带上 diff_token。Free 的令牌只读。

  • 备份和恢复 Velotrak

    备份是 PostgreSQL 的逻辑导出,放在数据目录下,保留七份。ClickHouse 的点击历史不在文件里。恢复会在你送出确认词之后,用一个事务替换行,并且不包含 master.key。

  • 套餐、上限和离线宽限

    Free 是 $0,Pro 是每月 $49 或每年 $490,Team 是每月 $99 或每年 $990,Founder 是一次性 $399。点击不计费。订阅过期后有 7 天只读的付费权限,然后回到 Free。已付费的授权如果 30 天联系不上服务器,仍然保持完整付费权限。

  • 从 Binom 或 Keitaro 导入

    Velotrak 导入自己的导出文件,以及 Binom 或 Keitaro 的 JSON。产品里没有 Voluum 导入器。Binom 和 Keitaro 适配器带入路径、Offer 和外部落地页。它们不导入 Flow 规则。Free 一次导入停在 20 个活动。

  • 用户、角色和 API 密钥

    角色是 admin、operator 和 viewer。操作员和只读只在 Team 上存在。API 密钥是 Team 功能,要么只读,要么读写,读写最多相当于操作员。停用用户会立刻结束其会话。

  • Velotrak 故障排查

    活动或 Flow 不是进行中,或路径上没有可用的落地页和 Offer 时,点击返回 404。联盟密钥不属于这次点击的 Offer 时,回传返回 403。LP Protect 对其他人返回空白的 403。