神策埋点迁移最容易出错的地方，不是把一条 JSON 写入数据库，而是迁移后仍然保持原来的用户身份、事件属性、时间口径和失败处理语义。只验证“接口返回成功”远远不够。
SensorFlow 的迁移思路是保留现有神策官方 SDK 和业务埋点，先把标准事件上报指向可控的 Go 接收服务，再写入 ClickHouse，并用 Apache Superset 或 SQL 检查结果。这样可以把客户端重构与服务端迁移拆开。
神策 SDK 数据可以迁移到自建 ClickHouse 吗？
可以，但客户端不应直接连接 ClickHouse。更安全的路径是：神策官方 SDK 将标准事件发送到兼容接收服务，服务完成解析、校验和错误处理后写入 ClickHouse；迁移期间保留旧链路，通过测试事件和灰度流量逐项核对数据语义。
边界声明：SensorFlow 是独立开源项目，与神策数据不存在关联、背书或官方认证关系。“兼容”不等于所有 SDK 版本和插件自动可用；加密、批量、可视化全埋点、用户关联及扩展字段需要单独测试。
迁移前需要盘点什么？
| 对象 | 需要记录 | 为什么重要 |
|---|---|---|
| SDK | 平台、版本、初始化参数、上报模式 | 不同版本的字段与网络行为可能不同 |
| 接收地址 | 生产、测试、代理和备用地址 | 决定灰度与回滚能否快速执行 |
| 身份 | 匿名 ID、登录 ID、设备 ID、关联时机 | 直接影响用户数、漏斗和留存 |
| 事件 | 事件名、必填属性、属性类型、触发端 | 用于逐项对比新旧链路 |
| 时间 | 客户端时间、接收时间、时区、迟到规则 | 影响日报、漏斗窗口和留存日期 |
| 插件 | 加密、压缩、批量、可视化与渠道插件 | 标准请求成功不代表插件兼容 |
| 下游 | 报表、SQL、导出、告警和用户分群 | 迁移完成标准必须覆盖消费端 |
六步完成可回滚迁移
1. 固化旧链路基线
选择注册、登录、支付或关键功能使用等少量事件，记录同一时间窗口内的事件量、用户数、必填属性完整率和典型用户序列。基线用于判断新链路是否保持语义，而不是追求每个网络重试都绝对一致。
2. 搭建隔离环境
先在测试环境部署 SensorFlow 接收服务、ClickHouse、Redis 与 Superset。使用独立数据库、独立密钥和明确的 environment=test 属性，避免测试事件污染生产口径。
3. 发送最小事件集
不要先压入全部历史或生产流量。至少发送匿名浏览、注册、登录、关键业务成功和退出登录事件，覆盖字符串、数值、布尔、时间以及空值等属性类型。
4. 完成三层验证
第一层检查 HTTP 响应与接收日志；第二层查询 ClickHouse 原始行；第三层使用 Superset SQL Lab 或已有查询核对聚合结果。任何一层缺失都不算验证完成。
SELECT event, count() AS event_count
FROM sensors.event
WHERE environment = 'test'
GROUP BY event
ORDER BY event_count DESC;表名和字段以实际部署版本为准。这段 SQL 的目的只是展示最小验证模式，不应未经确认直接用于生产。
5. 双写或小流量灰度
如果现有架构支持双写，可以在有限时间内同时保留旧、新接收路径；否则按测试应用、内部账号、客户端版本或小比例流量逐步切换。对比事件数量时还要检查属性类型、身份关联和迟到事件。
6. 切换并保留回滚窗口
记录正式切换时间、客户端版本和配置变更，保留旧地址与访问权限，直到核心报表覆盖完整业务周期。回滚条件应提前写明，例如错误率、事件缺失率或关键属性异常达到团队阈值。
四类必须通过的验收
| 验收类别 | 测试场景 | 失败表现 |
|---|---|---|
| 身份 | 匿名→注册→登录→跨设备 | 用户重复、漏斗断裂、留存虚低 |
| 类型 | 金额、数量、布尔、日期、数组 | SQL 转换失败或指标不可计算 |
| 时间 | 弱网、离线、批量、跨时区 | 事件落入错误日期或顺序颠倒 |
| 可靠性 | 重复请求、非法字段、服务重启 | 重复计数、静默丢失或无法追查 |
哪些团队适合这条迁移路径？
已有神策官方 SDK 的研发团队
如果业务埋点已经稳定，优先迁移接收边界可以避免同时重写客户端。团队仍需有能力检查 SDK 请求与数据库记录。
重视数据驻留的组织
事件明细进入自有 ClickHouse 后，存储、保留和访问权限由团队控制。但数据自托管也意味着团队负责备份、安全、监控和升级。
依赖 SQL 的数据团队
需要直接检查原始事件、建立可复核指标或连接 BI 的团队，更容易从透明存储中获益。主要依赖无代码分析的团队则应评估额外的产品化成本。
什么时候不应该选择 SensorFlow？
如果团队没有任何基础运维能力，或主要需求是会话回放、A/B 实验、Feature Flag、成熟 CDP 与开箱即用的无代码分析，完整产品分析平台通常更合适。SensorFlow 的价值在于透明、可控的事件数据链路，而不是声称覆盖所有分析产品功能。
官方资料
- 神策分析基础知识：客户端、服务端与自有 SDK 接入概念。
- 神策采集方案设计：事件与属性设计方法。
- ClickHouse 官方文档：数据库配置和查询依据。
- Apache Superset 官方文档：SQL Lab 与看板配置。
- SensorFlow GitHub 仓库：源码和部署文件。
- SensorFlow 部署文档：站内安装与验证入口。
- GitHub 搜索埋点指南：开源项目筛选清单。
常见问题
神策 SDK 可以直接连接 ClickHouse 吗？
不建议。客户端应连接 HTTP 接收服务，由服务端完成鉴权、解析、校验、限流和错误处理，再写入数据库。
迁移必须重写客户端埋点吗？
不一定。标准事件上报可优先尝试调整接收地址，但所有 SDK 版本、插件和身份流程都必须实际验证，不能只依据接口名称判断。
双写期间事件数为什么可能不完全一致？
网络重试、发送时机、去重规则、过滤条件和迟到事件都可能造成窗口差异。应同时比较原始事件标识、属性和时间，而不是只看总数。
历史数据需要一起迁移吗？
取决于合规、连续报表和成本要求。常见做法是确定新系统生效日，保留旧系统只读访问；如需导入历史数据，应单独设计映射和验收。
什么时候可以关闭旧链路？
至少应完成核心事件、身份、类型、时间、失败恢复和下游报表验收，并覆盖一个有代表性的业务周期。关闭前必须确认回滚与历史查询安排。