开源埋点分析平台 ClkLog 本地部署 + Web JS 埋点测试实战--九五小庞

作者：[很多人叫我庞工]
平台：CSDN
项目官网 ：https://clklog.com
部署文档 ：https://clklog.com/install/docker/quickmode.html
发布时间：2026年1月31日

一、为什么选择 ClkLog？

在数据驱动运营的时代，用户行为埋点分析已成为产品优化的核心手段。然而，商业埋点平台（如神策、GrowingIO）成本高昂，而自研又耗时耗力。

ClkLog 是一款开源、轻量、功能完整的 用户行为分析系统（UBA），支持：

全埋点（AutoTrack）与代码埋点
页面浏览（PV/UV）、点击、曝光等事件统计
用户路径分析、漏斗转化、留存分析
RESTful API & 可视化 Dashboard
支持私有化部署，数据完全自主可控

更关键的是，它提供了 Docker 一键部署方案，非常适合中小团队快速搭建自己的埋点平台。

本文将带你从零开始，完成 ClkLog 的本地 Docker 部署 ，并编写一段 Web JS 埋点代码进行测试验证。

二、本地 Docker 快速部署 ClkLog

1. 环境要求

Linux / macOS / Windows（WSL2）
Docker ≥ 20.10
Docker Compose ≥ v2.0
至少 4GB 内存（推荐 8GB）

2. 下载部署包

根据官方快速模式文档，我们使用 Gitee 镜像加速下载（国内更快）：

复制代码

curl -O https://gitee.com/clklog/clklog-deploy/raw/main/releases/clklog-docker-compose-1.2.0.tar.gz
tar -zxvf clklog-docker-compose-1.2.0.tar.gz
cd clklog-docker-compose

3. 初始化数据目录权限

复制代码

mkdir -p clklog_dc_data/redis
chown 999 clklog_dc_data/redis

mkdir -p clklog_dc_data/processing/checkpoints
chown 9999 clklog_dc_data/processing/checkpoints
chgrp 9999 clklog_dc_data/processing/checkpoints

mkdir -p clklog_dc_data/zookeeper
chown 1001 clklog_dc_data/zookeeper
chgrp 1001 clklog_dc_data/zookeeper

mkdir -p clklog_dc_data/kafka
chown 1001 clklog_dc_data/kafka
chgrp 1001 clklog_dc_data/kafka

💡 这些权限设置是为了避免容器内服务因权限不足而启动失败。

4. 启动服务

复制代码

docker compose -f docker-compose-clklog-simple.yml up -d

等待 2~5 分钟（首次启动需拉取镜像并初始化数据库）。

5. 验证部署是否成功

查看容器状态：

复制代码

docker compose -f docker-compose-clklog-simple.yml ps

应看到所有服务（nginx、web、receiver、flink、kafka、zookeeper、redis 等）均为 running 状态。

访问 Web 控制台（假设你的本机 IP 为 192.168.1.100）：

👉 http://192.168.1.100/

默认登录账号：

用户名：admin
密码：clklog

🌐 若在本地测试，可直接用 http://localhost/；若部署在服务器，请替换为实际 IP 或域名。

三、创建测试项目并获取埋点参数

登录 ClkLog 后台
进入 「项目管理」→「新建项目」
- 项目名称：test-web
- 项目标识（projectKey）：clklogapp（可自定义，但需记住）
创建成功后，进入 「集成管理」→「Web JS SDK」
复制以下关键信息：
- 接收地址（Receiver URL） ：
  http://YOUR_DOMAIN/receiver/api/gp?project=clklogapp&token=xxxxxx
- Token ：一串 32 位字符串（如 5388ed7459ba4c4cad0c8693fb85630a）

⚠️ 注意：YOUR_DOMAIN 需替换为你的实际访问地址（如 192.168.1.100）

四、编写 Web JS 埋点测试页面

创建一个简单的 HTML 文件 test-clklog.html：

复制代码

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <title>ClkLog 埋点测试</title>
  <script>
    // ========== ClkLog 埋点 SDK ==========
    (function(w, d, s, q, p) {
      w[p] = w[p] || function() { (w[p].q = w[p].q || []).push(arguments); };
      var js, fjs = d.getElementsByTagName(s)[0];
      if (d.getElementById(q)) return;
      js = d.createElement(s); js.id = q;
      js.src = "http://192.168.1.100/static/js/clklog-sdk.js"; // 替换为你的 ClkLog 地址
      fjs.parentNode.insertBefore(js, fjs);
    })(window, document, 'script', 'clklog-sdk', 'clklog');

    // 初始化配置
    clklog('init', {
      project: 'clklogapp',
      token: '5388ed7459ba4c4cad0c8693fb85630a', // 替换为你的 Token
      host: 'http://192.168.1.100/receiver/api/gp'
    });

    // 自动采集 PV
    clklog('track', 'page_view', {
      title: document.title,
      url: location.href
    });
  </script>
</head>
<body>
  <h1>欢迎使用 ClkLog！</h1>
  <button id="btn-click">点击测试按钮</button>

  <script>
    document.getElementById('btn-click').addEventListener('click', function() {
      clklog('track', 'button_click', {
        button_id: 'btn-click',
        label: '测试按钮'
      });
      alert('埋点已发送！');
    });
  </script>
</body>
</html>

🔧 请务必修改以下两处：

js.src 中的 IP 地址

token 和 host 中的值（从 ClkLog 后台获取）

将该文件放在任意 Web 服务器下（如 http-server、Nginx、或直接用 VS Code Live Server 打开），不能直接双击 file:// 协议打开（跨域问题）。

五、验证埋点数据是否上报成功

刷新测试页面 → 触发 page_view 事件
点击按钮 → 触发 button_click 事件
登录 ClkLog 后台，进入 「实时分析」→「事件流」
查看是否出现新事件：

✅ 成功标志：

能看到 page_view 和 button_click 事件
包含你自定义的属性（如 label: "测试按钮"）
用户 IP、UserAgent、时间戳等信息完整

🕒 注意：数据可能有 10~30 秒延迟（因 Flink 流处理缓冲）

六、常见问题排查

❓ Q1：页面加载时提示 "Failed to load resource"？

检查 clklog-sdk.js 地址是否可访问（浏览器直接打开该 JS 链接）
确保 ClkLog 的 Nginx 服务正常运行

❓ Q2：事件未出现在后台？

检查 Token 是否正确（区分大小写）
查看 Receiver 容器日志：
复制代码
```
docker logs clklog_receiver_1
```
确认请求是否被防火墙拦截（尤其云服务器）

❓ Q3：能否支持 HTTPS？

可以！需配置 Nginx SSL 证书，并将 SDK 地址改为 https://...。ClkLog 社区版默认不启用 HTTPS，但可通过挂载自定义 Nginx 配置实现。

七、总结

通过本次实战，我们完成了：

✅ 使用 Docker 快速部署开源埋点平台 ClkLog
✅ 创建测试项目并获取埋点参数
✅ 编写 Web JS 埋点代码并成功上报事件
✅ 在后台验证数据完整性

ClkLog 作为国产开源 UBA 系统，不仅降低了埋点分析的技术门槛，也为数据隐私和合规提供了保障。对于希望掌控用户行为数据的团队来说，是一个极具性价比的选择。

🔗 项目资源：

官网：https://clklog.com

GitHub：https://github.com/clklog

社区版文档：https://clklog.com/install/intro.html

欢迎点赞、收藏、评论！

如果你也成功部署了 ClkLog，或者有更多埋点场景（如 SPA 路由跟踪、曝光埋点等）想分享，欢迎留言交流～