工作杂谈 on My Learning Notes

【工作杂谈_20260901】数据监控：ADTK Python 项目搭建与验证

Tue, 01 Sep 2026 17:20:17 +0800

本文记录一套已经验证成功的 ADTK 项目搭建流程，适用于 Windows、PowerShell 与 VS Code。各步骤给出具体操作、采用原因和成功判据，可以直接从零复现。

验证日期：2026-09-01
操作系统：Windows
工作区根目录：BigDataLearningNotes

开始前需要安装 Python 3.12、Python Launcher 和 VS Code 的 Python 扩展。下面的 PowerShell 命令均在项目根目录中执行，并显式调用虚拟环境解释器，因此不要求预先激活虚拟环境。

1. 最终项目状态

项目最终使用独立的 Python 虚拟环境运行 ADTK 示例：

项目	最终值	作用
环境类型	`venv`	隔离本项目与系统 Python 的依赖
Python	`3.12.10`	兼顾 Python 3.12 支持和 ADTK 旧依赖的兼容性
解释器	`.venv\Scripts\python.exe`	安装依赖、运行脚本和 VS Code 分析统一使用该解释器
ADTK	`0.6.2`	当前 PyPI 上使用的 ADTK 版本
示例入口	`examples\basic_detection.py`	生成合成时序、检测异常并绘图
图片输出	`artifacts\basic_detection.png`	保存检测结果，便于人工检查

最终核心依赖版本如下：

包	已验证版本
`adtk`	`0.6.2`
`numpy`	`1.26.4`
`pandas`	`2.3.3`
`scikit-learn`	`1.5.2`
`statsmodels`	`0.14.6`
`matplotlib`	`3.10.9`

2. 从零搭建与验证

步骤 1：检查工作区并确定项目根目录

在 VS Code 中直接打开 BigDataLearningNotes 文件夹，并在终端中确认当前位置和 Python 3.12：

1
2
3


Get-Location
py -0p
py -3.12 --version

py -0p 应列出 Python 3.12 的安装路径，最后一条命令应输出 Python 3.12.x。如果列表中没有 3.12，需要先安装对应版本并启用 Python Launcher。当前项目验证时使用的是 Python 3.12.10。

直接把当前文件夹作为项目根目录，不再嵌套一层同名目录。

这样做的原因：

VS Code 打开当前文件夹后，可以直接识别 .venv、requirements.txt 和示例代码。
运行命令时路径更短，输出目录也固定在项目根目录下。
避免形成 BigDataLearningNotes/BigDataLearningNotes/... 之类的重复结构。

明确指定 Python 3.12，是为了避免误用本机的 Python 3.13，并让虚拟环境与本文验证过的版本保持一致。

最终目录结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


BigDataLearningNotes/
├── .venv/ # 本地虚拟环境，不提交到 Git
├── .vscode/
│ └── settings.json # 当前工作区的 VS Code 设置
├── artifacts/ # 示例生成的图片，不提交到 Git
├── examples/
│ └── basic_detection.py # ADTK 基础检测示例
├── .gitignore
├── ADTK_PROJECT_SETUP.md # 本文档
├── README.md # 项目使用入口
└── requirements.txt # 可复现依赖约束

成功判据：Get-Location 指向项目根目录，并且 py -3.12 --version 能正常输出版本。

步骤 2：创建并确认虚拟环境

通过 VS Code 的 Python 环境工具在项目根目录创建 .venv。等价的 PowerShell 命令是：

1

py -3.12 -m venv .venv

虚拟环境创建后，直接使用其中的解释器确认版本：

1

.\.venv\Scripts\python.exe --version

输出应为 Python 3.12.x，本项目验证时为 Python 3.12.10。

这样做的原因：

ADTK 0.6.2 发布较早，先在独立环境中验证不会污染系统 Python。
机器上还存在 Python 3.13，最初编辑器可能选中系统解释器；项目实际需要统一使用 .venv。
依赖安装、编辑器类型分析和脚本运行使用同一解释器，可以避免“终端能运行但编辑器报无法导入”或相反的情况。

后续命令都显式调用 .\.venv\Scripts\python.exe，不依赖终端中的 python 或虚拟环境激活状态。这样即使系统 PATH 指向其他 Python，也不会安装到错误的环境。

在 VS Code 中确认解释器的方法：

按 Ctrl+Shift+P。
执行 Python: Select Interpreter。
选择 .venv\Scripts\python.exe。
查看 VS Code 状态栏，确认当前解释器来自项目 .venv。

本次最终检查表明，VS Code/Pylance 当前选中的解释器已经是项目 .venv。

成功判据：项目根目录中存在 .venv，版本检查成功，并且 VS Code 状态栏显示该虚拟环境。

步骤 3：编写兼容的依赖约束

创建 requirements.txt，最终内容为：

1
2
3
4
5
6


adtk==0.6.2
matplotlib>=3.8,<3.11
numpy>=1.26,<2
pandas>=2.1,<3
scikit-learn>=1.3,<1.6
statsmodels>=0.14,<0.15

ADTK 0.6.2 发布于 2020 年，主要依赖没有完整的版本上限。仅执行不带约束的 pip install adtk，可能会得到远晚于 ADTK 发布的新主版本。pip 能完成安装并不代表这些包的运行时 API 仍与 ADTK 兼容，因此本项目主动限定经过验证的范围。

各项约束的作用：

约束	原因
`adtk==0.6.2`	固定学习目标，避免未来解析到行为不同的版本
`numpy>=1.26,<2`	Python 3.12 需要较新的 NumPy，同时避开 NumPy 2 的大版本兼容风险
`pandas>=2.1,<3`	保留 Python 3.12 支持，避开 pandas 3 的 API 变化
`scikit-learn>=1.3,<1.6`	使用具有 Python 3.12 轮子的版本，并限制在已验证范围内
`statsmodels>=0.14,<0.15`	使用支持当前 Python 的 0.14 系列
`matplotlib>=3.8,<3.11`	Python 3.12 使用新版 Matplotlib，但避开 3.11 删除的 ADTK 依赖 API

这里使用“版本范围”而不是把所有传递依赖完全锁死，是为了让学习项目在兼容区间内仍能接收补丁版本。上表中的具体版本则是本机已经验证通过的组合。

这组范围约束用于控制兼容性，并不保证不同日期安装到完全相同的传递依赖。若需要在 CI 或其他机器上精确复现当前环境，可以在验证通过后额外生成锁定文件：

1

.\.venv\Scripts\python.exe -m pip freeze | Set-Content requirements-lock.txt

之后使用 pip install -r requirements-lock.txt 安装锁定版本；日常学习仍可继续使用 requirements.txt 中的兼容范围。

成功判据：项目根目录存在 requirements.txt，并且内容包含上述六项约束。

步骤 4：安装项目依赖

先升级虚拟环境中的 pip：

1

.\.venv\Scripts\python.exe -m pip install --upgrade pip

再按照项目约束安装依赖：

1

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

使用 .venv 中的 python.exe -m pip，可以明确保证依赖安装到当前项目环境，而不是系统 Python。

可以用下面的命令查看核心包的实际版本：

1

.\.venv\Scripts\python.exe -m pip show adtk matplotlib numpy pandas scikit-learn statsmodels

实际版本应落在约束范围内；本文验证通过的具体组合见第 1 节。

成功判据：安装命令正常结束，pip show 能找到上述六个包，并且版本位于 requirements.txt 指定的范围内。

检查依赖冲突

1

.\.venv\Scripts\python.exe -m pip check

结果：No broken requirements found.

作用：确认当前已安装包之间没有缺失依赖或声明冲突。

步骤 5：创建项目文件

创建或补充以下文件：

`.gitignore`

忽略以下本地文件和生成物：

1
2
3
4
5
6


.venv/
__pycache__/
*.py[cod]
.pytest_cache/
.mypy_cache/
artifacts/

原因是虚拟环境体积较大且与机器相关，缓存和生成图片也可以由代码重新产生，不应提交到 Git。

`README.md`

提供项目简介、环境要求、安装命令、示例运行命令和后续 ADTK 学习方向。它作为日常使用入口，本文则保留更详细的搭建与排查过程。

`examples/basic_detection.py`

先创建示例目录：

1

New-Item -ItemType Directory -Force examples | Out-Null

examples\basic_detection.py 的完整代码如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88


from pathlib import Path

import matplotlib

# Select a non-interactive backend before importing pyplot so the example can
# save a chart without opening a desktop window.
matplotlib.use("Agg")

import numpy as np
import pandas as pd
from adtk.data import to_events, validate_series
from adtk.detector import InterQuartileRangeAD
from adtk.visualization import plot
from matplotlib import pyplot as plt


# ADTK 0.6.2 requests the old name for this bundled Matplotlib style.
if "seaborn-whitegrid" not in plt.style.library:
 plt.style.library["seaborn-whitegrid"] = plt.style.library[
 "seaborn-v0_8-whitegrid"
 ]


def build_sample_series() -> tuple[pd.Series, pd.DatetimeIndex]:
 """Create a regular hourly series with two known outliers."""
 # A fixed seed makes the generated data and detection result reproducible.
 random_generator = np.random.default_rng(seed=42)
 index = pd.date_range("2026-01-01", periods=24 * 14, freq="h")
 hours = np.arange(len(index))

 # Combine a daily cycle with small random noise to model a normal signal.
 values = (
 20
 + 2 * np.sin(2 * np.pi * hours / 24)
 + random_generator.normal(0, 0.35, len(index))
 )

 # Inject one high and one low outlier at known positions for verification.
 anomaly_positions = [24 * 4 + 6, 24 * 10 + 18]
 values[anomaly_positions] += [12, -12]

 series = pd.Series(values, index=index, name="metric")

 # ADTK expects an ordered DatetimeIndex with a valid, regular frequency.
 return validate_series(series), index[anomaly_positions]


def main() -> None:
 series, injected_anomalies = build_sample_series()

 # Fit IQR boundaries on the series and return one anomaly flag per point.
 detector = InterQuartileRangeAD(c=1.5)
 anomalies = detector.fit_detect(series)

 # Treat any undefined flags as normal before using the result as an index.
 detected_anomalies = anomalies.fillna(False).astype(bool)
 detected_times = series.index[detected_anomalies]

 # Fail loudly if the detector misses either deliberately injected outlier.
 missed_times = injected_anomalies.difference(detected_times)
 if not missed_times.empty:
 raise RuntimeError(f"Known anomalies were not detected: {list(missed_times)}")

 print(f"Detected {len(detected_times)} anomalous points:")
 for timestamp in detected_times:
 print(f"- {timestamp}: {series.loc[timestamp]:.2f}")

 # Convert point-wise flags into time intervals suitable for alert records.
 print(f"Anomaly events: {to_events(anomalies)}")

 # Create the output directory on first run and persist the annotated chart.
 output_path = Path("artifacts/basic_detection.png")
 output_path.parent.mkdir(parents=True, exist_ok=True)
 plot(
 series,
 anomaly=anomalies,
 anomaly_color="red",
 anomaly_tag="marker",
 )
 plt.title("ADTK interquartile-range anomaly detection")
 plt.tight_layout()
 plt.savefig(output_path, dpi=150)
 plt.close("all")
 print(f"Chart saved to {output_path.resolve()}")


if __name__ == "__main__":
 main()

示例按以下顺序工作：

用固定随机种子生成 14 天的小时级周期数据。
手工注入两个已知异常点。
用 validate_series 校验时间序列格式。
用 InterQuartileRangeAD(c=1.5) 拟合并检测异常。
检查两个已知异常是否都被发现；若漏检则主动抛出异常。
用 to_events 把布尔异常序列转换为事件。
用 ADTK 的 plot 绘图并保存到 artifacts\basic_detection.png。

选择合成数据的原因：

不依赖网络和外部数据文件，任何机器都能直接运行。
已知异常点的位置，可对检测结果做自动断言，而不是只凭肉眼判断。
固定随机种子后结果可重复，便于修改检测器参数并比较变化。

脚本使用 Matplotlib 的 Agg 后端，因为示例的目标是保存图片，不要求弹出桌面窗口。这也更适合自动化验证。

ADTK 0.6.2 使用旧 Matplotlib 样式名 seaborn-whitegrid，当前示例在旧名称不存在时，把它映射到新版名称 seaborn-v0_8-whitegrid。这个兼容处理让代码仍然调用 ADTK 原生的 plot，同时能够使用当前验证过的 Matplotlib。

脚本通过 output_path.parent.mkdir(parents=True, exist_ok=True) 自动创建 artifacts 目录，因此第一次运行前不需要手工创建输出目录。

成功判据：.gitignore、README.md 和 examples\basic_detection.py 均已存在，示例文件包含数据生成、检测、结果断言和绘图逻辑。

步骤 6：执行语法检查

正式运行前，先检查示例能否被 Python 正确编译：

1

.\.venv\Scripts\python.exe -m py_compile examples\basic_detection.py

语法检查成本很低，可以先排除缩进、括号和其他语法错误，再把完整运行用于验证依赖和程序行为。命令没有输出且正常返回，就表示检查通过。

成功判据：命令退出码为 0，终端中没有错误信息。

步骤 7：端到端运行验证

执行：

1

.\.venv\Scripts\python.exe examples\basic_detection.py

最终结果：

ADTK 成功导入。
两个注入的异常点都被检测到。
to_events 成功生成异常事件。
图片成功保存到 artifacts\basic_detection.png。
图片中的异常点以红色标记显示，位置与注入点一致。

运行输出为：

1
2
3
4
5


Detected 2 anomalous points:
- 2026-01-05 06:00:00: 33.88
- 2026-01-11 18:00:00: 5.95
Anomaly events: [(Timestamp('2026-01-05 06:00:00'), Timestamp('2026-01-05 06:59:59.999999999')), (Timestamp('2026-01-11 18:00:00'), Timestamp('2026-01-11 18:59:59.999999999'))]
Chart saved to <项目根目录>\artifacts\basic_detection.png

检测结果如下：

一次完整运行会同时验证 NumPy 和 pandas 数据构造、ADTK 导入、序列校验、检测器拟合、异常事件转换、Matplotlib 绘图以及文件写入路径。

成功判据：程序退出码为 0，终端列出两个异常时间，并且生成的图片中有两个红色异常标记。

3. 一次性复查

完成搭建后，可以在项目根目录依次执行以下命令：

1
2
3
4
5


.\.venv\Scripts\python.exe --version
.\.venv\Scripts\python.exe -m pip check
.\.venv\Scripts\python.exe -m py_compile examples\basic_detection.py
.\.venv\Scripts\python.exe examples\basic_detection.py
Test-Path .\artifacts\basic_detection.png

pip check 应输出 No broken requirements found.，语法检查应无错误，示例应列出两个注入的异常时间，最后的 Test-Path 应返回 True。此外，还应确认 VS Code/Pylance 选择了 .venv\Scripts\python.exe，且 .venv、缓存文件和生成图片均未被 Git 跟踪。

至此，ADTK 学习验证项目已经可以稳定运行。后续可以在同一个虚拟环境中继续练习 ThresholdAD、PersistAD、SeasonalAD，或把合成时间序列替换为自己的 CSV 数据。

【工作杂谈_20260825】数据平台与工程治理: Benchmark 与 Baseline：从基准测试到生产基线

Tue, 25 Aug 2026 19:14:25 +0800

1. Benchmark 与 Baseline 分别是什么

在性能工程和大数据平台建设中，Benchmark 与 Baseline 经常同时出现，但它们并不处于同一个层次：

Benchmark（基准测试）是一把定义了使用方法的“尺子”，Baseline（基线）是团队选定并保存下来的“参考刻度”。

Benchmark 主要回答：在什么数据、负载、资源和执行规则下，系统表现如何？
Baseline 主要回答：这次结果相对某个已知状态，是改善、退化，还是异常？

例如，团队固定使用 1 TB 数据、20 条 SQL、相同计算资源和 10 个并发用户测试两个查询引擎，这套测试协议和执行过程是 Benchmark。旧版本测得的 P95 = 8.2 s 被批准为后续版本的比较起点，这个值才是 Baseline。

实际交流中，英文 benchmark 还可能指测试套件、一次测试结果，甚至外部标杆。为了避免歧义，工程文档最好明确使用下面四个词：

术语	含义	示例
Benchmark specification	测试协议：数据、负载、环境、步骤和指标	“1 TB 数据、并发 10、预热 2 次、正式运行 5 次”
Benchmark run/result	某次执行及其测量结果	“本次 P95 查询延迟为 8.2 秒”
Baseline	被接受并保存的参考值或参考范围	“发布版本 v3.2 的 P95 Baseline 为 8.2 秒”
Target / SLO	希望达到或承诺达到的目标	“P95 必须小于 6 秒”

Baseline 描述的是参照状态，Target/SLO 描述的是期望状态。 Baseline 可以低于目标，也可能已经不满足目标，不能把二者混为一谈。

1.1 Benchmark（基准测试）

定义：一套可重复执行的测试协议或工作负载，用于度量系统或组件在明确条件下的性能、容量、稳定性、正确性和成本。它包括测试方法，也包括承载该方法的数据集、脚本与工具。
特点：测试目标、数据集、负载模型、运行环境、操作步骤和度量口径都必须明确并尽量保持一致。
举例：TPC-H 的 22 条 SQL 查询；HiBench 中的 WordCount、K-Means 作业；JMeter 压测脚本。

用途：

场景	说明
技术选型	选 Spark 还是 Flink？选 ClickHouse 还是 Doris？跑一套 Benchmark 用数据说话。
版本升级验证	从 Spark 2.x 升到 3.x，性能是提升还是回退？用 Benchmark 量化对比。
容量规划	数据量翻 10 倍需要加多少机器？通过 Benchmark 推算线性扩展能力。
参数调优验证	改了 JVM 参数或并行度，用 Benchmark 确认是否真的有提升。
SLA 定义	承诺客户 99% 查询 < 2 秒，需要先 Benchmark 验证平台能力。
硬件/云厂商评估	不同机型（如计算型 vs 内存型）跑同样任务，选性价比最高的。

1.1.1 常见的 Benchmark 工具与标准

工具/标准	测什么
TPC-H / TPC-DS	决策支持/数仓查询性能（SQL 复杂度高）
HiBench	Hadoop/Spark 综合套件（含 WordCount、Sort、SQL 等）
TPCx-HS	Hadoop 系统整体性能
YCSB	NoSQL 数据库（HBase、Cassandra）的读写性能
TPCx-BB	大数据基准测试（BigBench，覆盖结构化+半结构化）
Sysbench	底层系统（CPU、内存、磁盘 IO）性能

标准套件保证了工作负载有共同语言，但不等于真实生产负载。正式选型时通常需要同时运行“标准套件”和“从生产中抽取的代表性任务”。如果对外宣称官方 TPC 成绩，还需要遵守对应规范的审计和披露要求；内部跑了相似 SQL，不应直接称为官方 TPC 成绩。

1.1.2 Benchmark 在项目生命周期中的位置

1
2
3
4
5
6
7
8
9


架构设计 → 技术选型（Benchmark ①）
 ↓
开发完成 → 性能测试（Benchmark ②）
 ↓
预上线 → 容量规划（Benchmark ③）
 ↓
生产运行 → 建立 Baseline → 日常监控告警
 ↓
版本迭代 → 回归测试（Benchmark ④）

它是贯穿始终的活动，而不是只在某个阶段做一次。

1.2 Baseline（基线）

定义：一个已经确认、可用于后续比较的数值、范围或状态。它既可以来自某次受控 Benchmark，也可以来自一段稳定的生产历史。
特点：是一个具体的数字（如“单节点排序耗时 120 秒”）或一组指标（如“P99 延迟 50ms”）。它不一定是固定值，也可能是动态范围。
举例：优化前的“旧版本 Flink 作业吞吐量 10 万条/秒”；生产环境的“正常 CPU 使用率 40%”。
用途：
1. 量化改进：只有知道优化前是多少，才能说“提升了 30%”。
2. 异常告警：当线上指标偏离 Baseline 超过阈值时触发报警（例如 CPU 突然飙升到 80%，而 Baseline 是 40%）。
3. 目标设定：团队可以约定“新版本必须达到 Baseline 的 1.2 倍性能”作为交付标准。
4. 历史追溯：排查问题时能回看 Baseline，确认是从哪个版本开始变慢的。

一个可用的 Baseline 不能只保存孤立的数字，还要保存它成立的上下文：

1
2
3
4
5
6


Baseline = 指标值/范围
 + 工作负载与数据规模
 + 软件版本与配置
 + 硬件和运行环境
 + 统计口径与样本窗口
 + 生效时间与负责人

否则，“P95 延迟为 50 ms”无法说明是在单并发还是百并发、热缓存还是冷缓存、哪个版本和哪种数据规模下得到的，也就无法公平比较。

1.3 区别

在大数据场景里，Baseline（基线）和 Benchmark（基准测试/标杆） 都用于比较，但比较对象不同：

Baseline 主要回答“相对自己过去有没有异常或改善？”
Benchmark 主要回答“在统一条件下，系统能力到底怎么样，和目标或其他方案相比如何？”

公开资料通常也把 Baseline 定义为衡量变化的起点，而 Benchmark 更多使用行业标准、竞争对象或统一测试标准作为参照。 [usertesting.com]

维度	Benchmark	Baseline
本质	测量协议、工作负载和执行过程	被接受的参考值、范围或状态
核心问题	“在这些条件下，系统能力如何？”	“相对参考状态，发生了多大变化？”
主要组成	数据、负载、环境、步骤、指标、报告	指标值、统计口径、适用条件、生效时间
典型用途	技术选型、参数调优、容量测试、版本回归	趋势比较、回归门禁、生产告警、异常检测
变化方式	测试协议应版本化；条件改变时形成新版本	系统稳定演进后可审批更新，旧值仍需保留
举例	“使用固定 1 TB 数据运行 TPC-DS 类查询”	“当前发布版本的 P95 是 8.2 秒”
常见误区	只跑一次、只看平均值，或在不同环境中比较	把 Baseline 当成目标、极限值，或发现异常后立即覆盖

1.4 关系

Benchmark 结果经过正确性校验、重复性检查和团队确认后，可以被选为测试 Baseline。
生产系统稳定运行一段时间后，也可以根据历史分位数或动态区间建立生产 Baseline，不要求先跑标准 Benchmark。
没有历史 Baseline 时，Benchmark 仍然可以横向比较候选方案，或直接与 Target/SLO 比较。
有 Baseline 但不重复执行相同测量，也无法判断变化。因此，真正有价值的是“可重复的 Benchmark + 有上下文的 Baseline”。

实际工作中常说的“打 Baseline”，通常是指执行一轮受控测试，确认结果有效后，将它登记为后续版本的比较起点。

flowchart LR
 S["Benchmark 协议"] --> R["执行并得到结果"]
 R --> V{"正确且可重复？"}
 V -->|否| F["修正测试或系统"]
 V -->|是| B["批准为测试 Baseline"]
 B --> N["下一版本重复 Benchmark"]
 N --> C["与 Baseline 和 Target 比较"]

2. 如何设计一个可信的 Benchmark

Benchmark 的可信度不来自脚本跑得多复杂，而来自三个条件：

可控：除待比较变量外，其他关键条件尽量一致。
可重复：其他人根据记录可以重现测试。
有代表性：测试负载能够覆盖真正关心的生产模式。

2.1 先定义决策

开始测试前，先把问题写成可证伪的判断。例如：

1
2
3
4
5
6
7


决策：Spark 3.5 是否可以替换 Spark 3.4？

保持不变：数据快照、集群资源、作业代码、配置和执行时段
唯一变量：Spark 版本
正确性门槛：输出行数和关键指标必须一致
性能门槛：核心作业耗时回退不超过 5%
成本门槛：每 TB 计算成本回退不超过 10%

这比“比较两个版本谁更快”更有效，因为它明确了比较对象、控制变量和通过标准。技术选型也一样：不是寻找脱离场景的“最快引擎”，而是判断哪个候选方案更符合当前工作负载和约束。

2.2 固定测试契约

一份完整的 Benchmark specification 至少要记录下面这些信息：

维度	需要固定或记录的内容	常见陷阱
数据	规模、快照、分布、倾斜、文件格式、压缩方式	只生成均匀随机数据，掩盖生产倾斜
负载	查询/作业集合、读写比例、并发数、到达速率	只测单条最快 SQL，不测混合负载
环境	节点数、CPU、内存、磁盘、网络、可用区	两个方案实际拿到的资源不同
软件	引擎、JDK、依赖、配置、镜像和代码版本	升级引擎时顺便修改多个参数
执行	冷/热缓存、预热次数、重复次数、运行顺序	A 永远先跑，结果受时段影响
指标	P50/P95/P99、吞吐量、错误率、资源和成本	只看平均耗时，忽略长尾与失败请求

可以把这些内容版本化保存为测试清单：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


benchmark_id: sql-engine-1tb-v1
dataset: sales_snapshot_2026_08_20
data_size: 1TB
workload: decision_support_queries_v3
concurrency: 10
environment: 5_nodes_16c64g
cache_mode: warm
warmup_runs: 2
measured_runs: 5
metrics: [p50_latency, p95_latency, throughput, error_rate, cost]

只要数据、负载或环境发生了会影响可比性的变化，就应该生成新的协议版本，而不是悄悄覆盖旧定义。

2.3 让负载接近真实生产

标准套件适合建立共同语言，生产样本适合回答自己的问题。两者通常需要结合：

用 TPC-DS、YCSB 或 HiBench 覆盖标准化能力。
从生产日志中抽取高频、关键和长尾任务，形成业务工作负载。
保留真实的数据分布、热点 Key、小文件比例和数据倾斜。
按高峰期重放并发与请求到达节奏，而不是只做串行测试。
同时覆盖正常路径、资源紧张和故障恢复，但把不同场景分开报告。

性能比较之前必须先校验正确性。一个因为少处理了数据而更快的方案不是优化。常见校验包括输出行数、关键聚合值、空值率、主键重复数，以及文件或结果集校验和。

2.4 执行和统计结果

一次相对可靠的执行流程是：

清理或明确缓存状态，并执行预热轮次。
按预先规定的次数重复测试；A/B 交替或随机运行顺序，降低时段噪声。
每次只改变一个待验证因素，其他配置保持一致。
保存每轮原始结果，不只保存最终平均值。
报告中位数和 P95/P99 等分位数，同时报告错误率与波动范围。
保存执行日志、引擎指标、资源利用率、配置快照和代码版本。

不同指标的“变好方向”不同，报告中应明确标注：

指标	变好方向	相对变化示例
延迟、作业耗时、错误率、成本	越低越好	`(current - baseline) / baseline` 大于 0 表示回退
吞吐量、每秒处理行数	越高越好	`(current - baseline) / baseline` 大于 0 表示提升

如果 Baseline 作业耗时为 100 分钟，新版本为 112 分钟，则耗时回退 12%。如果吞吐量从每秒 10 万条升到 11.5 万条，则吞吐量提升 15%。不要只写“快了 15%”，必须同时说明指标、方向和计算口径。

2.5 结果不是一个孤立排名

下面是一份简化后的查询引擎评测结果：

方案	P50 延迟	P95 延迟	吞吐量	错误率	每 1,000 次查询成本
Engine A	1.8 s	7.6 s	42 QPS	0.1%	18 元
Engine B	2.2 s	5.1 s	39 QPS	0%	14 元

不能简单得出“Engine A 更快”。它的中位延迟和吞吐量更好，但 Engine B 的长尾、稳定性和成本更好。最终结论应绑定决策条件，例如：

在 P95 小于 6 秒、错误率小于 0.1% 且月度预算固定的约束下，本次交互式查询场景选择 Engine B；该结论只适用于 sql-engine-1tb-v1 定义的负载和环境。

这才是一份可以被评审、复现和推翻的 Benchmark 结论。

3. 如何建立和治理 Baseline

Baseline 不是“第一次测出来的数字”那么简单。它必须能够代表某种稳定状态，并且和当前指标处于可比条件下。

3.1 测试 Baseline 与生产 Baseline

大数据工程中常见的 Baseline 可以分成两类：

类型	数据来源	主要用途	更新方式
测试 Baseline	受控 Benchmark 中已批准版本的结果	升级、调优、代码变更和硬件变更的回归判断	随发布版本显式更新，旧版本永久留档
生产 Baseline	稳定生产窗口中的历史指标分布	日常监控、异常检测、容量趋势和数据质量告警	按日/周滚动计算，但需防止异常污染

二者不要混用。测试环境的 50 分钟成绩不能直接成为生产告警线，因为生产还存在资源争用、数据倾斜和流量波动；生产历史值也不适合直接比较两个引擎，因为它无法控制其他变量。

3.2 建立生产 Baseline 的步骤

以每日离线 Pipeline 为例，可以按下面的顺序建立生产 Baseline：

定义对象：明确是哪个作业、数据集、租户、区域和版本。
选择指标：运行时间、输入行数、输入字节、数据到达时间、失败率、Shuffle 量等。
划分可比组：按工作日/周末、小时、数据量区间或业务季节分组。
选择样本窗口：例如最近 28 个正常生产日，覆盖四个完整星期。
选择统计量：使用中位数、P95、四分位距等稳健统计量，而不是只用平均值。
定义告警规则：Baseline 描述正常状态，告警阈值还要结合容忍度和 SLO。
版本化保存：记录计算口径、生效时间、排除窗口和审批人。

例如某文件在最近 30 个工作日的到达时间为：

指标	Baseline
P50 到达时间	08:08
P95 到达时间	08:25
业务 SLO	08:35 前到达

可以将 08:25 设为预警观察点，将 08:35 设为违反 SLO 的严重告警点。这里的 P95 是历史 Baseline，08:35 是业务目标，两者含义不同。

数据量也应该按可比组建立基线。假设工作日通常写入 0.9 亿至 1.1 亿行，周末通常只有 0.5 亿至 0.7 亿行。如果只计算一个全月平均值，周一写入 0.65 亿行可能看似正常，实际上已经明显缺数。

3.3 静态、分组与动态 Baseline

方式	适用场景	优点	风险
静态 Baseline	发布回归、固定负载测试	可审计、比较稳定	系统演进后可能失真
分组 Baseline	工作日/周末、高峰/低峰、不同数据量	简单且能表达周期性	分组过细会导致样本不足
滚动 Baseline	流量和业务持续缓慢变化	能跟随趋势	事故数据可能被学习成“正常”
模型 Baseline	多重季节性和复杂依赖关系	能表达复杂模式	可解释性和维护成本更高

动态 Baseline 不能无条件自动更新。常见保护措施包括：

延迟若干天再纳入新样本，给事故确认留出时间。
排除已确认故障、发布窗口、回填任务和节假日活动。
限制单次更新幅度，突变必须人工审批。
同时保留绝对 SLO，避免 Baseline 随性能持续恶化而不断放宽。
保存历史版本，保证事后能够还原“当时为什么告警”。

3.4 Baseline 记录示例

一个 Baseline 注册表可以使用数据库表或配置文件实现，重点是让参考值和上下文绑定：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


baseline_id: ingestion-runtime-prod-v4
object: ods_order_ingestion
metric: runtime_minutes
statistic: p95
value: 60
segment:
 input_size_tb: "0.8-1.2"
 day_type: weekday
sample_window: "2026-07-01/2026-07-28"
excluded_dates: ["2026-07-09"]
effective_from: "2026-08-01"
owner: data-platform

当输入量变成 3 TB、作业架构重写或资源池发生变化时，应建立新版本，而不是拿不再可比的数据强行延长旧 Baseline。

4. 应用实战场景

下面的数据均为说明方法而构造，重点是展示 Benchmark、Baseline 和决策如何衔接。

4.1 Spark 版本升级：性能回归门禁

场景

团队计划从 Spark 3.4 升级到 Spark 3.5，希望升级后结果正确，并且核心作业性能回退不超过 5%。

Benchmark 设计

固定一份脱敏后的生产数据快照。
选择扫描、聚合、Join、窗口函数和数据倾斜等 20 个代表性作业。
使用相同节点、资源队列、JDK、作业代码和 Spark 配置。
每个版本先预热 2 次，再交替运行 5 次。
先比较行数、关键聚合值和校验和，再比较耗时与资源指标。

Spark 3.4 当前批准结果是测试 Baseline。部分结果如下：

作业	3.4 Baseline 中位耗时	3.5 中位耗时	相对变化	结论
`orders_etl`	42 分钟	43 分钟	+2.4%	通过
`customer_join`	24 分钟	28 分钟	+16.7%	阻断
`session_agg`	31 分钟	29 分钟	-6.5%	提升

customer_join 的输出正确，但耗时回退 16.7%，同时 Shuffle Read 从 310 GB 增至 470 GB。发布门禁应阻断升级，并继续检查执行计划、Join 策略、数据倾斜和 Adaptive Query Execution 配置，而不是用另外两个作业的提升抵消它。

回归判断的基本形式可以写成：

1
2
3
4


耗时回退率 = (当前耗时 - Baseline 耗时) / Baseline 耗时

当正确性校验失败：直接阻断
当耗时回退率 > 5%，且差异超过历史正常波动：阻断并分析

升级通过并稳定发布后，Spark 3.5 的批准结果可以成为下一轮变更的测试 Baseline，但 Spark 3.4 的记录仍需保留。

4.2 查询引擎选型：不仅比较谁最快

场景

为 3 TB 数据上的交互式 BI 查询选择引擎。业务要求 30 并发下 P95 小于 10 秒，数据新鲜度小于 15 分钟，同时控制总成本。

Benchmark 设计

从生产查询日志中抽取 120 条查询，按频率和重要性加权。
使用相同数据快照、并发模型和测试时段。
允许每个引擎进行合理的生产级调优，但完整披露索引、物化视图和缓存策略。
成本包括计算、存储、数据导入和持续运维，不只比较机器单价。

一组示例结果如下：

方案	P95 延迟	吞吐量	成功率	额外数据准备	综合成本
Spark SQL	24.8 秒	7.2 QPS	100%	无	低
Trino	8.6 秒	18.4 QPS	99.9%	无	中
ClickHouse	2.1 秒	56.0 QPS	100%	需要持续导入	高

Benchmark 不能自动替团队做决定：

Spark SQL 没有达到交互式查询的 P95 目标。
ClickHouse 的查询性能最好，但增加了数据复制、新鲜度和运维成本。
Trino 达到当前 SLO，且可以直接查询现有数据湖。

如果当前目标是以较小架构改动满足 10 秒 SLO，可以选择 Trino；如果未来业务明确要求亚秒级查询，再评估 ClickHouse 的额外成本。这一结论只适用于本次负载，不能泛化为某个引擎“永远更快”。

4.3 容量规划：找到满足 SLA 的安全容量

场景

某 Ingestion Pipeline 当前每日处理 1 TB 数据，要求在 120 分钟内完成。团队需要判断现有 10 个节点能否支撑半年后的增长。

Benchmark 设计与结果

保持数据分布、文件格式、节点数和作业配置不变，逐级增加输入量：

输入量	完成时间	是否满足 120 分钟 SLA	现象
0.5 TB	28 分钟	是	资源充足
1.0 TB	55 分钟	是	接近线性增长
1.5 TB	88 分钟	是	出现少量磁盘 Spill
2.0 TB	134 分钟	否	Shuffle Spill 和长尾 Task 明显增加

测试说明性能在 1.5 TB 到 2 TB 之间出现拐点，不能按 0.5 TB 的结果做线性外推。下一步应在边界附近补测 1.6、1.7、1.8 TB，定位满足 SLA 的最大容量。

即使最终测得 1.7 TB 可以在 120 分钟内完成，也不应把 1.7 TB 当作日常规划容量。按 20% 的资源余量计算，安全规划容量约为 1.36 TB，用于吸收重试、资源争用和数据倾斜。若半年预测达到 1.5 TB，就应提前扩容或优化分区与 Shuffle，而不是等 SLA 已经失败再处理。

4.4 生产监控：从测试成绩到动态基线

场景

新 Ingestion Pipeline 上线前，固定 1 TB 数据的 Benchmark 结果为：

旧方案：90 分钟
新方案：55 分钟
上线目标：60 分钟以内

55 分钟 是一次 Benchmark 结果。团队确认测试可重复后，可以暂时把它登记为初始测试 Baseline，但它还不是生产系统的正常范围。

上线并稳定运行 30 天后，按 0.8 至 1.2 TB 的工作日任务统计：

指标	生产 Baseline
运行时间 P50	52 分钟
运行时间 P95	60 分钟
输入量正常范围	0.8 至 1.2 TB
输入行数正常范围	0.9 亿至 1.1 亿
数据到达时间 P95	08:25

这组分布才是用于日常监控的生产 Baseline。之后某天输入量为 1 TB，作业却运行了 85 分钟，即使最终成功，也应该判定为性能异常。如果作业只运行 20 分钟，但输入行数只有 0.2 亿，则更可能是上游缺数，不能把“更快”误判为优化。

这一场景中可以同时建立三类规则：

数据到达告警：超过历史 P95 时预警，超过业务 SLO 时严重告警。
数据质量告警：行数、空值率、重复率偏离同类日期的正常范围。
性能告警：在相近输入量下，运行时间或单位数据成本显著偏离 Baseline。

因此，完整链路是：

flowchart LR
 A["上线前 Benchmark"] --> B["批准测试 Baseline"]
 B --> C["方案上线"]
 C --> D["积累稳定生产样本"]
 D --> E["建立生产 Baseline"]
 E --> F["监控、告警与容量趋势"]
 F --> G["变更后再次 Benchmark"]

5. 常见误区

5.1 把 Benchmark 等同于压测

性能测试是一个总称，几种常见测试关注的问题不同：

测试类型	主要问题
Benchmark	在明确、可重复的条件下，系统表现如何，方案之间如何比较？
Load Test	在预期业务负载下，系统是否满足要求？
Stress Test	不断增加压力时，系统在哪里失效，能否优雅降级？
Soak Test	长时间运行后，是否出现泄漏、累积延迟或稳定性问题？

一次 Load Test 可以被设计成可重复的 Benchmark，但二者并非天然等价。

5.2 只看平均值

平均 2 秒可能掩盖 P99 为 40 秒，也可能掩盖 5% 请求直接失败。查询服务要关注延迟分位数、吞吐量和错误率；批处理要关注中位耗时、长尾 Task、失败重试和资源峰值。

5.3 忽略正确性和工作量

少扫描分区、漏掉 Join 结果或输入数据不足都会让作业“变快”。性能指标必须和输出校验、输入量、扫描字节数一起看。

5.4 在不可比的条件下比较

不同数据规模、资源配置、缓存状态、并发数和测试时段得到的结果不能直接放在一起排名。如果条件无法完全一致，应披露差异并说明它会怎样影响结论。

5.5 发现回退后立即刷新 Baseline

Baseline 的作用就是暴露变化。为了让告警消失而覆盖它，会把异常重新定义为正常。只有当变化符合预期、完成验证并经过审批后，才能创建新的 Baseline 版本。

5.6 把外部成绩当成自己的生产承诺

厂商或社区成绩可以帮助筛选候选方案，但无法替代自身工作负载测试。硬件、数据分布、查询模式、调优程度和成本口径不同，结论就可能完全不同。

6. 一份可直接复用的检查清单

执行 Benchmark 前，至少回答下面的问题：

这次测试要支持哪个具体决策？
唯一计划改变的变量是什么？
数据和负载是否代表真实场景？
哪些环境、配置和版本必须固定并记录？
如何校验结果正确性？
需要测量哪些延迟、吞吐、稳定性、资源和成本指标？
预热、重复次数和执行顺序是什么？
要与哪个 Baseline、Target 或 SLO 比较？

建立 Baseline 时，再确认下面的问题：

它是测试 Baseline 还是生产 Baseline？
指标值对应什么对象、分组、数据规模和统计口径？
样本窗口是否足够，是否包含事故或特殊活动？
告警阈值与业务 SLO 是否单独定义？
什么情况下允许更新，谁负责审批？
是否保留旧版本和原始测量数据？

7. 总结

最后可以用三句话记住这两个概念：

Benchmark 定义怎样测：固定数据、负载、环境、步骤和指标，得到可重复的测量结果。
Baseline 定义和谁比：保存某个已知状态及其上下文，用来判断改善、回退或异常。
Target/SLO 定义要达到哪里：它是期望或承诺，不等于当前 Baseline。

Benchmark 的结果可以被批准为测试 Baseline，稳定生产历史也可以形成生产 Baseline。真正完整的工程闭环不是“跑一次分”，而是持续执行：

1
2


明确决策 -> 设计 Benchmark -> 校验并测量 -> 建立 Baseline
 -> 监控与回归 -> 审批新 Baseline -> 保留历史

当测试协议可复现、参考值有上下文、判断标准提前定义时，Benchmark 和 Baseline 才能真正服务于技术选型、版本升级、容量规划和生产治理。

参考资料

Transaction Processing Performance Council：TPC 系列 Benchmark 的规范与结果。
Intel HiBench：面向大数据框架的工作负载套件。
Yahoo Cloud Serving Benchmark：面向云数据库和 NoSQL 系统的工作负载生成与评测框架。

【工作杂谈_20260817】多维分析与数据建模: 维度上卷——从明细粒度到汇总层级

Mon, 17 Aug 2026 20:51:34 +0800

1. 什么是“维度上卷”

维度上卷 Roll-up 本质上是维度建模和 OLAP 中的分析概念；ETL 中的维度上卷，是通过数据转换和聚合，将细粒度事实数据加工为更高层级、更粗粒度的汇总数据。

Roll-up 是分析语义
ETL 是实现手段
聚合表、汇总事实表是落地结果

所谓上卷，就是从更细维度层级聚合成更高维度层，例如：

时间维度：日 → 月 → 季度 → 年
地域维度：城市 → 省份 → 国家
产品维度：SKU → SubCategory → Category

例如原始数据是：

Date	City	Province	Country	Product	Revenue
2026-08-01	City1	Province1	Country1	A	100
2026-08-02	City3	Province2	Country1	A	150
2026-08-01	City2	Province1	Country1	A	80

经过时间和地域上卷（C1/C2都属于P1）：

Month	Province	Product	Revenue
2026-08	Province1	A	180
2026-08	Province12	A	150

这里发生了两个变化：

Date → Month
City → Province

同时：Revenue = SUM(100 + 150 + 80) = 330

2. ETL 中上卷的核心是“改变事实粒度”

上卷不能只理解为 GROUP BY。

它真正改变的是：

事实表中一行数据所代表的业务范围。

例如：

状态	一行含义	粒度
上卷前	某一天 + 某城市 + 某SKU 的销售情况	Date + City + SKU
上卷后	某个月 + 某省份 + 某产品类别的销售情况	Month + Province + Category

事实表中的维度键决定事实数据的粒度。事实可以存储在更高粒度，但高粒度事实通常无法再准确拆分回更细粒度

即日级 → 月级通常是可完成的；

但月级 → 日级如果没有保留日级明细，无法准确恢复。

3. ETL 中上卷的完整流程

flowchart TD
 A["原始数据"] --> B["Step1: 数据质量检查"]

 B --> B1["检查 City → Province 是否唯一"]
 B --> B2["检查 Province → Country 是否唯一"]
 B --> B3["识别缺失、错误和历史变更"]

 B1 --> C["Step2: 加载维表"]
 B2 --> C
 B3 --> C

 C --> C1["DimDate"]
 C --> C2["DimGeography"]
 C --> C3["DimProduct"]

 C1 --> D["Step3: 生成明细事实表"]
 C2 --> D
 C3 --> D

 D --> D1["FactRevenueDaily"]
 D1 --> E["Step4: 预聚合上卷"]

 E --> E1["FactRevenueMonthlyCity"]
 E --> E2["FactRevenueMonthlyProvince"]
 E --> E3["FactRevenueMonthlyCountry"]

 E1 --> F["Step5: 一致性校验"]
 E2 --> F
 E3 --> F

 F --> F1["各级 Revenue 总和均应为 330"]

 classDef step fill:#FFE08A,stroke:#A86700,color:#3D2900,stroke-width:2px
 class B,C,D,E,F step

3.1 数据质量检查

检查 City → Province

City	Province	是否唯一
City1	Province1	是
City2	Province1	是
City3	Province2	是

当前数据中，每个 City 只属于一个 Province，因此层级关系正常。

检查 Province → Country

Province	Country	是否唯一
Province1	Country1	是
Province2	Country1	是

最终可以建立稳定的地理层级：

flowchart TD
 A1["City1"] --> B1["Province1"]
 A2["City2"] --> B1["Province1"]
 A3["City3"] --> B2["Province2"]

 B1["Province1"] --> C2["Country1"]
 B2["Province2"] --> C2["Country1"]

3.2 加载维表

不建议在事实表里重复保存 City、Province、Country 名称。所以按照星型模型可以拆分事实数据与维度数据：

地域维表 DimGeography
日期维表 DimDate
产品表 DimProduct

地域维表 DimGeography

GeographyKey	City	Province	Country
101	City1	Province1	Country1
102	City3	Province2	Country2
103	City2	Province1	Country1

日期维表 DimDate

DateKey	Date	Month	Quarter	Year
20260801	2026-08-01	2026-08	2026-Q3	2026
20260802	2026-08-02	2026-08	2026-Q3	2026

产品表 DimProduct

ProductKey	Product
201	A

如果存在产品类别，还可以设计为：Product → ProductCategory → ProductLine

3.3 生成明细事实表

明细事实表FactRevenueDaily

DateKey	GeographyKey	ProductKey	Revenue
20260801	101	201	100
20260802	103	201	150
20260801	102	201	80

粒度仍然是：Date + GeographyKey + Product

City、Province、Country 名称不需要重复保存在事实表中，而是通过 GeographyKey 关联 DimGeography

3.4 预聚合上卷

上卷一：Date → Month

目标粒度：Month + City + Product，生成 FactRevenueMonthlyCity

Month	City	Product	Revenue
2026-08	City1	A	100
2026-08	City2	A	80
2026-08	City3	A	150

这里只提升了时间层级：Date → Month

City 维度仍保留在原层级

上卷二：City → Province

目标粒度：Month + Province + Product，生成 FactRevenueMonthlyProvince

Month	Province	Product	Revenue
2026-08	Province1	A	180
2026-08	Province2	A	150

计算过程：

1
2


Province1 = City1 100 + City2 80 = 180
Province2 = City3 150

这里同时发生：

Date → Month

City → Province

上卷三：Province → Country

目标粒度：Month + Country + Product，生成 FactRevenueMonthlyCountry

Month	Country	Product	Revenue
2026-08	Country1	A	330

计算过程：

1

Country1 = Province1 180 + Province2 150 = 330

完整上卷路径为：

Date → Month

City → Province → Country

3.5 一致性校验

层级	Revenue 总和
原始明细数据	330
Monthly City	330
Monthly Province	330
Monthly Country	330

因此满足：

1
2
3
4
5


明细层 Revenue
= 城市层 Revenue
= 省份层 Revenue
= 国家层 Revenue
= 330

最终的数据流可以概括为：

flowchart TD
 A["明细事实:Date + City + Product"] --> B["月度城市汇总:Month + City + Product"]

 B["月度城市汇总:Month + City + Product"] --> C["月度省份汇总:Month + Province + Product"]

 C["月度省份汇总:Month + Province + Product"] --> D["月度国家汇总:Month + Country + Product"]

这就是 ETL 中维度上卷的核心：维度层级向上提升，事实粒度变粗，同时按照目标粒度重新聚合度量值。

【工作杂谈_20260815】用户分析与身份体系: CanonicalUserId：从用户标识到身份图谱

Sat, 15 Aug 2026 22:15:38 +0800

1. 先说结论：CanonicalUserId 到底是什么

CanonicalUserId 不是行业统一标准字段，也不是天然存在于客户端的某个 ID。

更准确地说，它是身份解析系统根据一组用户标识及其关联证据，为某个业务实体生成或选定的内部主键。它让下游不必分别使用 user_id、device_id、Cookie ID、手机号或第三方平台 ID，而是通过一个统一键查询该实体的事件、属性和关系。

可以先记住下面这句话：

CanonicalUserId 是身份解析的结果，不是身份解析的依据；它代表的是规则定义下的业务实体，不一定等于现实世界中的自然人。

例如，系统收集到以下标识：

1
2
3
4


anonymous_id = web_7f8a
device_id = ios_a91c
account_id = user_1001
crm_id = crm_8872

经过可靠的登录、绑定或业务系统映射后，它们可能被归到：

1

canonical_user_id = cu_01J5YQ...

这里的 cu_01J5YQ... 通常只是一个不透明、稳定的内部代理键。它本身不包含手机号、邮箱等业务含义。

1.1 第一个问题不是“用哪个 ID”，而是“要统一什么实体”

“用户”在不同业务中可能指完全不同的对象：

实体粒度	典型定义	适用场景	容易混淆的地方
自然人 Person	现实中的一个人	跨渠道客户经营、合规客户视图	很难仅凭设备和行为绝对确认
账号 Account	一个可登录账号	产品分析、权限、会员体系	一人可有多账号，家庭也可能共用账号
设备 Device	一次安装或浏览器实例	设备风控、推送、匿名分析	会重装、清 Cookie，也可能多人共用
会话 Session	一段连续访问	流量与访问路径分析	生命周期很短，不能代表长期用户
家庭 Household	一组家庭成员或共用地址	家庭订阅、电视、零售营销	不能直接替代自然人视图
企业/组织 Organization	公司、门店或租户	B2B SaaS、账号层分析	一个自然人可属于多个组织

因此，在建立 CanonicalUserId 之前必须先写清楚：

这个 ID 代表自然人、账号，还是设备？
是否允许一个人对应多个账号？
是否允许一个账号被多人共用？
发生账号合并、手机号换绑时，历史如何处理？

对于大多数产品行为分析，把“稳定业务账号”作为已登录用户实体，把匿名浏览器或 App 安装实例作为临时实体，往往比宣称“已经识别出自然人”更准确。

1.2 几个容易混用的概念

概念	含义	示例
Identifier	外部系统产生的标识值	`user_1001`、`web_7f8a`、手机号
Namespace	标识所属的命名空间和语义	`account_id`、`anonymous_id`、`crm_id`
Identity Edge	两个标识属于同一实体的证据	某设备成功登录了某账号
Identity Graph	以标识为节点、关联证据为边的图	`web_7f8a -> user_1001 <- ios_a91c`
Identity Resolution	根据规则合并、拒绝或拆分身份的过程	登录绑定、冲突检测、解绑
CanonicalUserId	解析后实体的稳定内部主键	`cu_01J5YQ...`
User Profile	以统一主键聚合出的属性和行为视图	会员等级、最近活跃时间、累计消费

One ID、ID-Mapping、Identity Graph、Entity Resolution 经常在同一个话题中出现，但侧重点不同：

ID-Mapping 强调标识之间如何建立映射。
Identity Graph 强调标识和实体之间的图关系。
Entity Resolution 范围更广，还可能根据姓名、地址、邮箱等进行规则或概率匹配。
CanonicalUserId / One ID 强调最终供下游使用的统一主键。

2. 为什么需要身份归一

2.1 一个用户为什么会产生多个标识

假设同一个账号经历了下面的访问路径：

时间	行为	当时可见的标识
T1	在浏览器匿名查看商品	`anonymous_id=web_7f8a`
T2	在该浏览器注册并登录	`web_7f8a + account_id=user_1001`
T3	在 iPhone App 匿名浏览	`device_id=ios_a91c`
T4	在 App 登录同一账号	`ios_a91c + account_id=user_1001`
T5	在线下 CRM 完善资料	`account_id=user_1001 + crm_id=crm_8872`

如果只按原始标识计数，系统可能把它看成四个用户；如果利用 T2、T4、T5 的确定性关联，则可以得到：

flowchart LR
 W["anonymous_id:web_7f8a"] -->|成功登录| A["account_id:user_1001"]
 D["device_id:ios_a91c"] -->|成功登录| A
 C["crm_id:crm_8872"] -->|业务主数据映射| A
 A --> P["canonical_user_id:cu_01J5YQ"]

身份归一真正解决的是：同一个业务实体在不同时间、终端和系统中留下了不同的键，而分析与服务需要一个连续视图。

2.2 不做身份归一会怎样

匿名浏览和注册事件分属两人，注册漏斗被截断。
同一账号换设备后被重复计算，AU、留存和新增用户数偏高。
广告点击、站内浏览和最终订单无法形成完整归因链路。
客服、CRM、交易和行为数据无法拼成统一客户视图。
已退订用户在另一个标识下仍被营销触达。
风控系统看不到同一账号与多个设备、支付工具之间的关系。

不过，错误合并通常比漏合并更危险。漏合并会把一人看成多人；错误合并则可能把甲的画像、订单或营销授权给乙，既污染数据，也可能形成隐私和合规事故。

2.3 为什么 `user_id + device_id` 不能成为统一用户键

user_id + device_id 描述的是“某账号在某设备上的组合”，不是用户实体：

一个账号登录三台设备，会产生三个组合键。
同一设备先后登录两个账号，会产生两个组合键。
匿名阶段没有 user_id，组合键无法生成。
清 Cookie、重装 App 或更换设备后，组合键会再次变化。

同样，下面这种写法也只能作为临时降级方案：

1

COALESCE(user_id, device_id)

匿名时它返回 device_id，登录后却返回 user_id，前后仍是两个用户。只有在身份解析已经建立 device_id -> canonical_user_id 映射后，COALESCE 才能用于选择解析结果或兜底标识。

3. 身份归一是怎样工作的

3.1 把标识看成节点，把证据看成边

最直观的模型是图：

节点：(namespace, normalized_value)，例如 (account_id, user_1001)。
边：两个节点属于同一实体的证据，例如“设备 D 在认证成功后登录账号 U”。
连通实体：经过规则校验后可归并到同一 CanonicalUserId 的节点集合。

为什么节点必须包含 Namespace？因为不同系统都可能出现值 12345：

1

(crm_id, 12345) != (account_id, 12345) != (store_member_id, 12345)

一条生产可用的边也不能只有 left_id 和 right_id，至少还要能回答：

关系来自登录、人工绑定、CRM 导入，还是模型推断？
哪个系统、哪条事件产生了这条关系？
关系何时生效、何时失效？
使用了哪个规则版本？
能否撤销，发生冲突时如何重算？

3.2 关联证据并不等价

证据类型	示例	一般处理方式
强确定性证据	服务端确认账号登录、账号合并、主数据映射	可直接建立高可信边
中等确定性证据	已验证邮箱、已验证手机号	需考虑共享、回收、换绑和有效期
弱标识	Cookie、广告 ID、安装 ID、设备 ID	可辅助串联匿名行为，不应单独证明自然人相同
概率证据	姓名、地址、IP、User-Agent、行为相似度	输出候选或置信度，谨慎自动合并

产品行为分析通常优先采用确定性匹配：只有同一事件或可信业务关系同时带出两个标识时才建边。跨 CRM 的客户去重可能使用规则或机器学习匹配，但必须保留分数、阈值和人工复核机制。

需要特别注意：

邮箱和手机号会变更、共享或被运营商回收，不是天然永久主键。
IP 地址、机型和 User-Agent 的共现不能证明是同一人。
对邮箱或手机号做哈希只是降低明文暴露，不会让错误数据变准确，也不自动满足匿名化要求。

3.3 标识规范化先于匹配

身份解析前通常需要进行标准化和质量校验：

邮箱按业务规则处理大小写、空格和非法格式。
手机号转换为带国家码的 E.164 格式。
明确业务 ID 是否区分大小写，不应无条件转小写。
拒绝 null、unknown、-1、全零值等公共占位符。
每个来源系统声明它能生产哪些 Namespace，以及这些值是否唯一。

如果把公共占位符当成有效标识，数以万计的用户可能通过 user_id=null 被合并成一个巨型身份簇，这类事故常被称为 Graph Collapse（图坍缩）。

3.4 CanonicalUserId 应该怎么生成

常见方案有三种：

方案	优点	风险与限制
直接使用业务 `user_id`	简单、可读、容易关联业务库	账号迁移、跨租户、多账号合并时不稳定
平台选定某个已有 ID	无需额外生成主键	选择规则可能不可控，外部 ID 变化会影响使用
生成不透明内部 ID	与邮箱、设备、账号解耦，便于合并和版本管理	需要额外维护成员关系和重定向表

复杂系统通常更适合第三种方案：为 Profile 生成 UUID、ULID 或内部序列号，把所有外部标识作为成员挂到 Profile 下。

当两个 Profile 合并时，不要批量修改所有下游事实表的主键。可以保留一个存活 ID，并记录重定向：

1

cu_old_02 -> cu_survivor_01

下游解析时沿重定向找到当前主 ID，同时仍能追溯历史上使用过的 ID。

3.5 为什么不能直接对所有边求连通分量

假设一台共享平板先后登录两个账号：

1

account_A -- device_shared -- account_B

如果只使用“存在路径即同一人”的传递闭包，account_A 和 account_B 会被合并。这显然不合理：设备可以共享，而账号 ID 在当前业务中可能要求一个 Profile 最多只能有一个。

生产系统会增加约束和保护规则：

唯一性约束：一个 Profile 最多允许一个 account_id 或 crm_id。
标识优先级：稳定账号 ID 高于邮箱，邮箱高于匿名 ID。
数量与时间窗口：限制一个 Profile 在一定时间内可关联的设备、邮箱或匿名 ID 数量。
来源可信度：服务端认证关系高于客户端自报关系。
阻断值：占位符、测试账号和已知异常值不能参与合并。
冲突隔离：规则无法判断时进入待处理队列，而不是强行归并。
可解绑与重算：错误边失效后可以重新计算受影响的局部身份簇。

3.6 确定性 ID-Mapping 与概率实体解析

两者解决的是相邻但不完全相同的问题：

维度	确定性 ID-Mapping	概率 Entity Resolution
输入	登录关系、绑定关系、稳定业务 ID	姓名、地址、邮箱、电话等属性
判断	有明确证据才关联	根据规则或模型计算相似度
输出	绑定/不绑定	匹配组和置信度
典型场景	埋点、跨设备产品分析	多 CRM 去重、线下客户主数据整合
主要风险	埋点错误导致错误合并	阈值不当导致误匹配或漏匹配

第一次建设时，应该先把确定性的登录和绑定链路做好，再评估是否真的需要概率匹配。不要用 IP、设备指纹等弱信号偷偷“猜人”，然后把结果包装成确定的 CanonicalUserId。

4. 用完整用户旅程理解 CanonicalUserId

4.1 匿名浏览到登录

以 Mixpanel 的 Simplified ID Merge API 为例，客户端 SDK 会先生成 $device_id。调用 identify(user_id) 后，后续事件会同时包含 $device_id 和 $user_id；当 Mixpanel 首次收到二者共存的事件时，会建立映射。

1
2


mixpanel.identify("user_1001");
mixpanel.track("Login Succeeded");

官方文档特别要求 identify() 后至少发送一个事件，因为 Simplified API 是由同时包含 $device_id 与 $user_id 的事件触发合并，而不是仅凭本地函数调用完成服务端映射。

在自己的数仓中，也应该保留两个层次：

层次	保存内容	是否允许重写
原始事实	事件发生时实际携带的匿名 ID、账号 ID、时间和来源	不重写
解析结果	当前或指定版本下的 CanonicalUserId	可随规则重算

这样既能用“当前映射”回看完整注册漏斗，也能用“事件发生时映射”复现历史报表。不同平台的“回溯合并”实现并不相同：有的平台在查询时应用映射，有的平台会更新分析索引；不能简单理解为所有历史原始事件都被物理改写。

4.2 跨设备统一

跨设备不是通过相似设备特征自动完成的，而是两个设备都出现了同一个可信账号标识：

1
2


web_7f8a --登录--> user_1001
ios_a91c --登录--> user_1001

于是二者可解析到同一个 CanonicalUserId。若 Mac 浏览器始终没有登录、绑定或其他可靠证据，它就应继续保持匿名。无法确认的身份不合并，是正确结果，不是系统缺陷。

4.3 退出登录与共享设备

共享设备是最容易发生错误合并的场景。建议把以下状态变化写入统一的 SDK 规范：

登录成功后设置稳定账号 ID，并发送一条成功事件。
退出或认证超时后清理本地账号身份。
当使用者可能变化时，生成新的匿名 ID 或会话作用域 ID。
不要把硬件设备 ID 永久等同于最近一次登录账号。

reset() 的具体语义是厂商和版本相关的：

Mixpanel 当前 Simplified API 文档建议在退出或认证超时时调用 .reset()。
Mixpanel Original API 文档为了避免频繁增加身份簇成员，讨论了只在明确切换使用者时 reset 的策略。
Amplitude 要显式匿名化时，建议把 User ID 设为 null，同时生成新的 Device ID；否则后续匿名事件可能继续归到该设备上最后一个已知用户。

因此，不能总结成“退出一定 reset”或“普通退出永远不 reset”。正确做法是先确认所用 SDK 版本，再根据共享设备、匿名期归因和身份簇限制设计状态机。

4.4 账号合并、解绑与手机号回收

真实系统还会遇到：

用户把两个业务账号申请合并。
客服误绑账号后需要撤销。
手机号从用户 A 换绑，并在未来被用户 B 使用。
企业客户更换 CRM，主数据 ID 被重新编码。

这说明映射不是静态字典，而是带时间和版本的关系：

1
2


(phone, +86138...) -> account_A [2025-01-01, 2026-03-01)
(phone, +86138...) -> account_B [2026-07-01, ...)

解绑不应删除原始事件和审计记录，而应使关系在某个时间点失效，并重新计算受影响的 Profile。对历史报表，还要明确使用“当时身份”还是“当前最新身份”。

4.5 CanonicalUserId 能支持哪些应用

应用	CanonicalUserId 的作用	仍需额外定义的规则
AU、留存	跨设备去重同一用户	活跃事件、时间窗口、实体粒度
注册漏斗	串联注册前匿名行为与注册后行为	转化窗口、匿名行为归属策略
渠道归因	连接广告点击、站内行为和订单	First-touch、Last-touch 等归因模型
用户画像	汇总 CRM、交易和行为属性	属性优先级、有效期、冲突规则
营销触达	跨渠道去重、退订和频控	授权、同意状态、渠道可达性
风控	发现账号、设备、支付工具之间的关系	风险边、图遍历、模型和人工审核

CanonicalUserId 只解决“这些记录当前应归到哪个实体”。它不会自动解决指标口径、归因模型、画像属性冲突和隐私授权。

5. 从旧方案到身份图谱

方案	能解决什么	主要问题
只用 `device_id`	匿名设备内连续访问	换设备、清 Cookie、共享设备都会失真
只用 `user_id`	已登录账号分析	注册前行为丢失，未登录用户不可见
`COALESCE(user_id, device_id)`	为每条事件临时选一个非空键	登录前后仍是两个实体
拼接 `user_id + device_id`	标识账号和设备的组合	一人多设备会被拆分，匿名期无法表示
单行 `user_id -> device_id` 映射	最简单的一对一关联	无法表示多设备、多个 Namespace、历史和解绑
节点、边、Profile 模型	多标识、可追溯、可合并和拆分	需要规则治理、版本管理和质量监控

并不是所有公司都必须一开始就建设图平台：

产品只允许登录后使用，而且 user_id 全局稳定时，直接使用 user_id 已经足够。
需要串联注册前后行为时，增加 anonymous_id -> user_id 的确定性映射即可。
需要跨 CRM、多渠道、绑定/解绑和共享设备治理时，才需要完整 Identity Graph。
需要根据姓名、地址等模糊属性匹配时，再引入 Entity Resolution。

复杂度应该由真实业务问题推动，而不是因为“CanonicalUserId”听起来高级就先造一套大系统。

6. 如何在自己的数据平台中落地

6.1 先写 Identity Contract

在建表和写 Flink 任务之前，先由产品、账号、数据、隐私和安全团队共同确认一份身份契约：

CanonicalUserId 代表什么实体，在哪些租户和业务域内唯一？
有哪些 Namespace，格式、大小写和标准化规则是什么？
哪些标识是强标识，哪些可能共享或回收？
哪些事件可以创建绑定，客户端自报是否可信？
一个 Profile 允许出现多少个同类标识？
冲突时按来源、时间还是人工结果决定？
合并和拆分是否需要回算历史，保留多久？
哪些标识属于 PII，谁可以查询和导出？

规则不明确时，技术系统只会更快地产生不明确的结果。

6.2 推荐的数据模型

一行同时放 canonical_user_id + user_id + device_id 无法表达一对多、来源、有效期和解绑。更可扩展的模型至少包含以下几类表：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


CREATE TABLE identity_node (
 node_id BIGINT PRIMARY KEY,
 namespace VARCHAR(64) NOT NULL,
 identifier_token VARCHAR(128) NOT NULL,
 pii_class VARCHAR(32) NOT NULL,
 first_seen_at TIMESTAMP NOT NULL,
 last_seen_at TIMESTAMP NOT NULL,
 UNIQUE (namespace, identifier_token)
);

CREATE TABLE identity_edge (
 edge_id BIGINT PRIMARY KEY,
 left_node_id BIGINT NOT NULL,
 right_node_id BIGINT NOT NULL,
 evidence_type VARCHAR(64) NOT NULL,
 source_system VARCHAR(64) NOT NULL,
 source_event_id VARCHAR(128),
 confidence DECIMAL(5, 4) NOT NULL,
 valid_from TIMESTAMP NOT NULL,
 valid_to TIMESTAMP,
 status VARCHAR(32) NOT NULL,
 rule_version VARCHAR(32) NOT NULL
);

CREATE TABLE canonical_profile (
 canonical_user_id VARCHAR(64) PRIMARY KEY,
 entity_type VARCHAR(32) NOT NULL,
 profile_status VARCHAR(32) NOT NULL,
 created_at TIMESTAMP NOT NULL,
 updated_at TIMESTAMP NOT NULL
);

CREATE TABLE profile_membership (
 node_id BIGINT NOT NULL,
 canonical_user_id VARCHAR(64) NOT NULL,
 valid_from TIMESTAMP NOT NULL,
 valid_to TIMESTAMP,
 mapping_version BIGINT NOT NULL,
 is_current BOOLEAN NOT NULL,
 PRIMARY KEY (node_id, canonical_user_id, mapping_version)
);

CREATE TABLE profile_redirect (
 retired_user_id VARCHAR(64) PRIMARY KEY,
 survivor_user_id VARCHAR(64) NOT NULL,
 reason VARCHAR(128) NOT NULL,
 created_at TIMESTAMP NOT NULL
);

其中 identifier_token 可以是受控的内部 Token，或由密钥保护的 HMAC。普通无盐哈希仍容易遭受邮箱、手机号字典枚举，不能替代访问控制和加密。

6.3 数据处理链路

flowchart LR
 S["Web / App / Server / CRM"] --> R["不可变原始事件"]
 R --> N["Namespace 校验与标准化"]
 N --> Q{"质量与冲突检查"}
 Q -->|通过| E["Identity Edge Ledger"]
 Q -->|异常| X["隔离与人工处理"]
 E --> G["Identity Resolution Engine"]
 G --> H["当前映射 + 历史版本"]
 H --> K["在线 KV / Profile API"]
 H --> W["数仓宽表 / BI / 标签"]
 G --> A["合并决策与审计日志"]

核心原则是：

原始事件保持不可变。
标识关系采用追加式事实和有效期，而不是直接覆盖。
当前映射和历史映射同时保留。
在线服务与离线分析可以共享规则，但使用不同的物化形式。

6.4 一次解析决策的基本步骤

1
2
3
4
5
6
7
8
9


1. 从事件中提取所有已声明的 Namespace 和标识值
2. 标准化并过滤空值、占位符、测试值和非法格式
3. 查找每个标识当前所属的 Profile
4. 若均未命中，创建新 Profile
5. 若只命中一个，检查数量和唯一性约束后添加成员
6. 若命中多个，按证据、来源和优先级判断是否允许合并
7. 冲突时拒绝该边或进入隔离队列
8. 记录决策、规则版本和来源事件
9. 更新受影响 Profile 的成员关系和在线缓存

登录关系最好由服务端认证成功事件确认，而不是完全信任客户端传来的任意 user_id。否则攻击者或埋点错误可能把一个设备绑定到其他账号。

6.5 合并容易，拆分更难

Union-Find（并查集）非常适合只增加边的离线合并，但不擅长删除边。一旦发生误绑或手机号回收，需要拆分身份簇时，单纯并查集很难恢复原关系。

可撤销系统通常会：

保留不可变的边和决策日志。
将错误边标记为失效，而不是物理删除。
从受影响连通子图重新计算 Profile。
生成新的 Membership 版本。
通过 Redirect 或变更日志通知下游更新。

这也是为什么“支持解绑”不是多写一个 DELETE 接口，而是一项涉及历史、缓存、画像、分群和下游导出的系统能力。

6.6 实时链路与离线链路

链路	目标	常见实现
实时解析	登录后立即拿到统一 Profile，用于个性化和风控	Kafka/Flink + KV/缓存 + 规则服务
离线重算	处理迟到数据、规则升级、合并和拆分	Spark/Hive/图计算 + 版本化结果表
在线查询	按任一标识查当前 CanonicalUserId	Profile API、KV 索引
历史分析	按当前映射或 As-of 映射统计	数仓 Membership 快照或 SCD2 表

CanonicalUserId 不等于必须使用图数据库。若主要查询是“给定 ID 找 Profile”，关系表加 KV 索引通常已经足够；只有在风控等场景需要多跳关系遍历、路径查询和高扇出分析时，图数据库的价值才明显。

6.7 必须监控什么

建议至少监控：

匿名事件占比、已解析事件占比和映射延迟。
每种 Namespace 的空值率、非法率和阻断值命中率。
每日新增边、合并、拒绝、冲突和解绑数量。
Profile 成员数、设备数的 P95/P99 与最大值。
超大连通分量数量，是否出现单点异常增长。
同一 Profile 包含多个唯一账号 ID 的违规数量。
使用身份归一前后的 DAU、漏斗和留存变化。
规则版本发布后被重分配的事件和 Profile 数量。

上线前应覆盖以下测试：

场景	预期结果
同一账号登录两台设备	两台设备可解析到同一账号 Profile
两个账号先后使用共享设备	两个账号不被设备节点合并
退出后新用户注册	新用户的匿名行为不归到旧账号
手机号换绑或回收	新旧有效期正确，历史可追溯
`user_id=null` 或测试占位值	不参与合并并触发告警
错误绑定后解绑	受影响身份簇可拆分并生成新版本
迟到登录事件到达	当前视图更新，原始事件保持不变

6.8 隐私和安全不是附加项

只采集业务确实需要的标识，并记录用途和同意状态。
PII 与普通分析字段分层存储，使用加密、Tokenization 和最小权限。
不把邮箱、手机号直接编码进 CanonicalUserId。
Profile API 只允许服务端访问，避免在客户端暴露可枚举的身份查询能力。
删除请求需要传播到节点、Profile、画像、导出和备份策略中。
跨地区、跨产品合并前确认数据驻留和用途限制。
概率匹配结果必须可解释、可申诉，不能直接用于高风险自动决策。

7. 主流平台和大规模系统的公开实现

以下内容基于截至 2026-08-21 可访问的官方文档。各平台解决的问题和术语并不完全相同，不能把某一家的实现直接当成行业标准。

7.1 Mixpanel：产品分析中的事件流拼接

Mixpanel Simplified ID Merge 使用 $device_id 和 $user_id：

匿名事件只有 $device_id 时，以设备标识作为 distinct_id。
首次收到同时包含 $device_id 与 $user_id 的事件时创建身份簇。
Simplified API 中 canonical distinct_id 固定为 $user_id。
可以用簇内任一 ID 写入，但查询和导出使用 canonical ID。
Simplified API 不允许合并两个不同的 $user_id。
官方建议在退出或认证超时时调用 .reset()，避免共享设备误合并。

Mixpanel Original ID Merge 则不同：

$identify 只接受 UUIDv4 匿名 ID，且该匿名 ID 不能已属于其他 identified ID。
$merge 可以合并任意两个 ID，但身份簇不能超过 500 个 ID。
canonical distinct_id 由平台从簇内选择，未必是业务 user_id。
Original 文档对 reset() 的建议也更偏向“明确要切换使用者时再调用”。

原文将 UUIDv4、500-ID 上限、canonical 选择和 Simplified 流程写在了一起，实际上这些约束分属不同版本。

7.2 Amplitude：生成内部 Amplitude ID

Amplitude 的唯一用户文档描述了三层标识：Device ID、User ID 和平台生成的 Amplitude ID。

匿名事件先按 Device ID 获得 Amplitude ID。
同一设备后来出现 User ID 时，匿名事件可与已识别用户合并。
同一 User ID 出现在多个设备上时，平台优先按 User ID 归一。
Amplitude 不能合并两个不同的 User ID；更换 User ID 会被视为不同用户。
共享设备上的后续匿名事件默认归给最后一个已知用户，除非将 User ID 设为 null 并生成新的 Device ID。
合并映射会在分析查询中生效，但导出到 Redshift 的原始事件不可变，使用原始数据计算 DAU 可能与平台界面不同。

这个例子很好地说明了“统一查询视图”和“改写原始事件”不是同一回事。

7.3 Segment Unify：持久 ID 加合并保护

Twilio Segment Unify 将 Cookie、设备、邮箱、userId 和自定义 External ID 连接到一个持久内部 ID，并公开了比较完整的治理规则：

新事件匹配零个 Profile 时创建，匹配一个时追加，匹配多个时尝试合并。
可为标识设置阻断值、数量限制和优先级。
默认 user_id 限制为一个，其他标识默认允许多个。
高优先级稳定 ID 可以阻止低优先级邮箱或匿名 ID 把两个账号错误合并。
Merge Protection 专门处理共享设备、公共匿名 ID 等问题。

Segment 不只是“收集后转发数据的管道”。它的 Connections 偏采集和路由，而 Unify 提供 Identity Resolution、Profile 和受众能力，两者要分层理解。

7.4 Adobe Experience Platform：防止 Graph Collapse

Adobe Identity Graph Linking Rules 将生产级保护明确抽象为：

Unique Namespace：一个身份图中某类标识最多只能有一个，例如 CRMID。
Namespace Priority：冲突时稳定账号标识优先于设备或浏览器标识。
Identity Optimization Algorithm：违反唯一性约束时重放边，并移除导致两个 Person 合并的低优先级关系。

在共享平板上先后登录两个 CRMID 时，Adobe 不会简单通过共同 ECID 把两人合并，而会拆成两个图。公开文档中的默认匿名归属采用“最后一个已认证用户”逻辑，这也再次说明“匿名行为归第一个用户”不是行业通则。

7.5 神策 ID-Mapping 3.0：显式 ID Key 与绑定/解绑

神策全域用户关联文档的公开机制包括：

预先定义参与关联的 ID Key，明确手机号、邮箱、OpenID 等标识语义。
事件包含未定义的 ID Key 时拒绝入库，避免含义不明的标识进入图谱。
客户端通过 loginWithKey、bind、unbind 建立或解除关系。
客户端绑定结果会进入本地缓存，后续事件携带相关 ID 信息。
服务端 SDK 发送绑定事件，但不会把绑定 ID 持久化到服务端 SDK 本地状态。

神策公开的全域用户关联服务还强调来源可信度差异、历史数据治理以及手机号等标识发生变更时的绑定和解绑。这比“一台设备的匿名行为永远给首个登录用户”更接近真实治理过程。

7.6 AWS Entity Resolution：规则、机器学习与匹配组

AWS Entity Resolution 更接近跨数据源实体解析，而不是客户端埋点 SDK：

对输入进行 Schema Mapping 和标准化。
支持基于规则、机器学习和数据供应商的匹配流程。
规则匹配输出命中的规则编号，机器学习匹配输出 0 到 1 的置信度。
支持批处理、规则场景的增量处理，以及通过 GetMatchId 进行近实时查找。
ID Mapping Workflow 可把 Source Namespace 翻译到 Target Namespace。

它说明了当问题从“登录前后是否同一账号”扩展到“两个 CRM 记录是否属于同一客户”时，系统需要标准化、匹配规则、置信度和工作流，而不只是 identify()。

7.7 Airbnb：大规模关系图基础设施

Airbnb 公开的 Identity Graph 架构主要服务 Trust & Safety，不等同于产品分析中的 CanonicalUserId，但展示了大厂在多跳关系查询下的实现方式：

图中约有 70 亿节点、110 亿条边，每天增加约 500 万条边。
大部分数据通过异步事件近实时写入，在线服务进行低延迟查询。
存储采用 JanusGraph + DynamoDB，OpenSearch 建索引，前面还有 KV 缓存。
典型查询需要 4 到 8 跳，重点处理高扇出、长尾延迟和稳定性。
通过事件写入、批量加载、在线服务和复杂查询预计算等多个应用分离读写职责。

这个案例的启示不是“做 CanonicalUserId 必须上 JanusGraph”，而是：当需求从单跳 ID 映射升级为账号、设备、支付工具和风险关系的多跳遍历时，图存储、缓存、预计算和查询治理才会成为核心问题。

7.8 这些公开实现的共同模式

尽管产品不同，它们大体都在做以下几件事：

为标识声明类型和语义，而不是只存一个字符串。
以登录、绑定、主数据或匹配结果作为关联证据。
使用内部 Profile ID 或 canonical ID 隔离外部标识变化。
为共享设备、公共值和异常高扇出设置合并保护。
保留原始数据，通过映射层提供当前统一视图。
支持冲突检测、解绑、版本或局部重算。
同时服务实时 Profile 查询和离线分析。

8. 一条适合从零开始的建设路径

8.1 第一阶段：只解决匿名到登录

最小可用方案不需要图数据库：

业务账号使用永不复用的数据库 ID，不用邮箱作为 user_id。
Web/App 为匿名访问生成随机 anonymous_id。
每条事件保留事件发生时的 anonymous_id 和可选 account_id。
只有认证成功事件可以建立二者的确定性边。
数仓生成 anonymous_id -> canonical_user_id 的当前映射。
原始事件不改写，分析层按映射版本补充 CanonicalUserId。
先覆盖同设备注册、跨设备登录、退出和共享设备测试。

这一阶段已经能改善注册漏斗、跨设备 AU 和留存。

8.2 第二阶段：增加多来源标识与治理

当 CRM、小程序、门店和客服系统接入后，再增加：

Namespace 注册表和标准化规则。
来源可信度、唯一性、数量和时间窗口约束。
Edge Ledger、Profile Membership 和 Redirect 表。
冲突隔离、解绑、局部重算和审计界面。
当前视图与 As-of 历史视图。

8.3 第三阶段：按需要增加实时和概率能力

只有在业务需要实时个性化或风控时，才把解析结果同步到 KV/Profile API；只有在缺少确定性键、确实需要跨系统客户去重时，才引入规则评分或机器学习匹配。

可以用下面的决策表控制复杂度：

当前问题	建议方案
产品必须登录才能使用	直接使用稳定 `user_id`
需要分析注册前后的行为	匿名 ID + 确定性登录映射
多终端、多 CRM、需要解绑	版本化 Identity Graph
姓名地址相似但无共同 ID	Entity Resolution + 置信度
风控需要多跳关系查询	图数据库、缓存与预计算

9. 对原文几个结论的集中修正

**CanonicalUserId 不保证对应唯一自然人。**它对应的是业务定义和规则版本下的实体，可能是账号或 Profile。
**不是所有 ID 都应使用 UUIDv4。**匿名 ID 常用 UUID；业务账号可以使用稳定、不可复用的内部主键。Mixpanel Original 的 UUIDv4 是特定 API 约束。
**一个 CanonicalUserId 能否包含多个 user_id 取决于系统规则。**Mixpanel Simplified 不允许合并两个 $user_id，Segment 等系统则可以配置不同限制。
**共享设备的匿名行为没有统一行业归属。**有的平台采用最近一次认证用户，有的平台要求 reset，也可以选择保持未解析。
**“匿名行为归首个登录用户”不是通用最佳实践。**它会在共享设备和账号切换中造成错误归属。
**500 个 ID 的簇限制不是 CanonicalUserId 的普遍限制。**它来自 Mixpanel Original API 的具体实现。
**reset() 策略必须结合厂商版本和业务状态机。**Simplified、Original、Amplitude 的建议并不相同。
**一张以 canonical_user_id 为主键的扁平映射表不够。**生产系统还需要节点、边、有效期、来源、版本和重定向。
**Segment 不只是数据管道。**其 Connections、Unify 和 Engage 分别覆盖采集路由、身份解析/Profile 与受众激活能力。

10. 总结

CanonicalUserId 表面上是“给多个 ID 找一个主 ID”，更深一层其实是一个数据治理问题：

先定义要统一的实体，而不是先挑一个字段。
用 Namespace 区分标识语义，用证据边描述为什么关联。
强标识和弱标识采用不同规则，宁可暂不合并，也不要错误合并。
CanonicalUserId 最好与外部账号、邮箱和设备解耦。
原始事件不可变，映射关系要有来源、有效期、版本和审计。
合并之外还要设计冲突、解绑、拆分、回算和删除。
简单 ID-Mapping 不需要图数据库，多跳关系查询才需要图基础设施。

最终，CanonicalUserId 不是一张“身份证”，而是系统在特定业务边界、证据和规则下，对“这些记录当前属于同一实体”做出的可追溯判断。

【工作杂谈_20260810】用户分析与身份体系: Active User：定义、计算口径与常见应用

Mon, 10 Aug 2026 23:58:04 +0800

1. Active User 是什么

Active User，简称 AU，表示在指定时间范围内，完成了某种“有效行为”的去重用户数。

它不是一个天然统一的指标，而是由三个口径共同定义：

口径	要回答的问题	示例
用户标识	“谁”算一个用户	`UserId`、`CookieId`
时间窗口	在什么时间内活跃	一天Daily、一周Weekly、一个月Monthly
活跃行为	做了什么才算活跃	打开 App、阅读内容、观看超过 N 秒、完成购买

因此，一个完整定义应该是：

DAU = 在某自然日内，至少发生一次符合活跃条件事件的去重用户数。

通用计算形式为：

1
2
3


COUNT(DISTINCT CASE
 WHEN is_active_event = 1 THEN user_id
END)

在不同系统中，“Active”口径可能不同。例如，官方定义中，活跃用户通常强调用户在指定日期范围内发生了符合参与条件的行为，而总用户只要求触发过事件。因此，在业务数据场景中不能只写“AU”，还必须同时说明活跃事件、统计窗口和用户标识。 [support.google.com]

1.1 DAU、WAU、MAU

DAU：Daily Active Users，日活跃用户数
WAU：Weekly Active Users，周活跃用户数
MAU：Monthly Active Users，月活跃用户数

假设同一个用户：

8 月 1 日活跃
8 月 2 日活跃
8 月 10 日活跃

那么：

8 月 1 日 DAU：计数 1
8 月 2 日 DAU：计数 1
8 月 1 日至 7 日 WAU：仍然只计数 1（因为这一周出现的是同一个用户）
8 月 MAU：仍然只计数 1（因为这一个月出现的是同一个用户）

所以：

WAU 不能通过七天 DAU 相加得到，MAU 也不能通过每天 DAU 相加得到。

因为 AU 本质上是：集合中不同用户的数量，而不是事件数量。

2. AU在大数据场景中的常见应用

以AU为基础可以扩展出多维分析、漏斗对比、留存计算：

多维分析：如你之前所示，按市场、设备等维度拆分 AU，了解不同分群的用户活跃情况。
漏斗对比：比较不同渠道的 DAU 变化，辅助运营决策。
留存计算：基于每日 AU 计算次日/7日/30日留存率。

2.1 多维分析：不同分群的用户活跃情况

数字产品的用户生命周期分析框架如下：

分析环节	核心问题	对应维度
用户画像	用户是谁？用什么设备？	用户所在地域、设备型号
用户获取	用户从哪里来？	平台、渠道
用户行为	用户在产品里做什么？	兴趣类别、内容
用户体验	用户在不同版本下的体验如何？	APP版本
商业表现	用户在哪些市场/区域贡献价值？	市场、国家

多维 AU 分析，是把整体活跃用户集合按照不同维度进行切分，观察不同用户群体、业务区域或内容类型的活跃表现。

——这个思路在移动应用和广告分析领域是通用的分析方法，各家平台都会提供类似的维度：

百度移动统计的常用维度就包含：品牌、设备型号、操作系统、运营商、、渠道、地域（国家/省/市）等
Apple App Store Connect 的分析维度包含：App Version、Platform Version、Region、Product Page 等
Google Firebase / Google Mobile Ads SDK 自动采集的用户属性包含：国家、设备品牌、设备类别、应用版本、操作系统版本、兴趣类别等
Braze 等用户参与平台也按设备类型、平台、内容互动情况等维度评估活跃用户

2.1.1 基本计算方式

假设原始行为数据如下：

UserId	Date	Market	Device	Content
U001	2026-08-01	US	Mobile	C001
U001	2026-08-01	US	PC	C002
U002	2026-08-01	US	Mobile	C001
U003	2026-08-01	UK	Mobile	C003

按 Market + Device 计算 DAU：

1
2
3


SELECT Date, Market, Device, COUNT(DISTINCT UserId) AS DAU
FROM table
GROUP BY Date, Market, Device;

Date	Market	Device	DAU
2026-08-01	US	Mobile	2
2026-08-01	US	PC	1
2026-08-01	UK	Mobile	1

这里可以回答：

US 市场 Mobile 用户有多少？——2个
不同设备上的用户活跃分布如何？——Mobile的用户活跃度高于PC设备
某个 Market 的 DAU 下跌是否集中在某种设备？——由于目前只有一天的数据，暂时看不出下跌
某个类型文章的活跃用户增长主要来自哪个 Market？——由于目前只有一天的数据，暂时看不出下跌

2.1.2 多维 AU 不能直接上卷

上面的三个分组不能直接相加得到整体 AU：

1
2
3
4
5


US Mobile AU = 2
US PC AU = 1

不能推导：
US Overall AU = 2 + 1 = 3

因为 U001 同时使用了 Mobile 和 PC。

正确结果是：

1
2
3
4
5
6
7
8


US 用户集合：

Mobile = {U001, U002}
PC = {U001}

并集 = {U001, U002}

US Overall AU = 2

用集合表达：

1

AU(Mobile ∪ PC) <= AU(Mobile) + AU(PC)

只有在能够保证用户不会跨分组出现时，分组 AU 才能直接相加。但实际的市场/设备/内容/供应商场景通常不能保证这一点。

2.1.3 什么时候可以直接相加

结合着两个指标理解：

浏览量PageViewCount：发生了多少次内容消费行为
活跃用户数PageViewAUCount：有多少个不同用户发生过内容消费行为

例如：

Partner	Content	PageViewCount	PageViewAUCount
Partner A	C001	10,000	2,000
Partner A	C002	8,000	1,500

PageViewCount 可以反映内容被消费了多少次；
PageViewAUCount 可以反映内容覆盖了多少不同用户。

但 Partner A 的整体 AU 不能计算为2,000 + 1,500 = 3,500，因为同一个用户可能同时看过 C001 和 C002。

正确方式是基于 Partner A 范围内的明细重新去重：

1
2
3
4
5
6
7
8
9


SELECT
 date,
 partner,
 COUNT(DISTINCT user_id) AS partner_au
FROM user_event
WHERE is_active_event = 1
GROUP BY
 date,
 partner;

这也解释了为什么数据模型中需要同时保存：

叶子级别的 Content AU
Content = All 的 Partner AU
Market = All、Device = All 等不同上卷组合的 AU

这些 All 粒度的 AU 不是由叶子行求和得到的，而是针对对应维度组合重新去重计算出来的

2.1.4 多维分析的业务价值

多维 AU 分析主要用于定位“整体变化来自哪里”。

例如整体 DAU 下降 15%，继续拆分可能发现：

1
2
3
4
5
6


整体 DAU -15%
 ├── US Market -3%
 ├── UK Market -2%
 └── DE Market -40%
 ├── Mobile -5%
 └── PC -65%

这样可以将问题进一步定位到：

特定市场
特定设备
特定版本
特定渠道
特定内容类型

如果 PV （浏览量）未明显下降，但 AU （活跃用户数）大幅下降，需要重点检查：

用户标识是否缺失
UserId 生成逻辑是否变化
去重逻辑是否变化
某些用户事件是否没有进入上游
匿名用户是否被统一写成同一个默认 ID

2.2 漏斗对比：不同渠道的用户转化情况

这里需要先区分两个概念：

只比较不同渠道的 DAU 变化，严格来说属于渠道趋势对比，不是完整的漏斗分析。

真正的漏斗要求存在一组有先后顺序的业务阶段，例如：

1
2
3
4
5
6
7
8
9


内容曝光
 ↓
内容点击
 ↓
开始阅读
 ↓
有效阅读
 ↓
订阅或购买

2.2.1 渠道 DAU 对比

如果只是比较渠道活跃情况，可以计算：

Date	Channel	DAU
2026-08-01	Search	20,000
2026-08-01	Recommendation	35,000
2026-08-01	Direct	10,000

这可以回答：

哪个渠道带来的活跃用户最多？
某个渠道 DAU 是否持续增长？
一次运营活动是否带来了更多活跃用户？
渠道增长是新增用户增长，还是老用户回流？

但仅有 DAU 仍不能判断渠道质量。

例如：

Channel	DAU	购买用户数	购买转化率
A	100,000	1,000	1%
B	20,000	800	4%

A 的活跃规模更大，但购买转化率只有：1%

B 的购买转化率是： 4%

所以渠道评估通常需要同时看：

活跃用户规模
转化用户数
转化率
留存率
人均消费深度

2.2.2 真正的用户漏斗

假设定义以下阶段：

ExposureUser：看到内容曝光
ClickUser：点击内容
ReadUser：开始阅读
EffectiveReadUser：阅读超过 N 秒
SubscribeUser：完成订阅

每一步都应该按照用户去重：

1
2
3
4


曝光用户数 = COUNT(DISTINCT exposure_user_id)
点击用户数 = COUNT(DISTINCT click_user_id)
有效阅读用户数 = COUNT(DISTINCT effective_read_user_id)
订阅用户数 = COUNT(DISTINCT subscribe_user_id)

阶段转化率：

1
2
3
4


点击率 = 点击用户数 / 曝光用户数
有效阅读率 = 有效阅读用户数 / 点击用户数
订阅转化率 = 订阅用户数 / 有效阅读用户数
整体转化率 = 订阅用户数 / 曝光用户数

2.2.3 漏斗必须注意用户集合约束

漏斗中的后一步用户，原则上应该是前一步用户集合的子集：

1
2
3


SubscribeUser ⊆ EffectiveReadUser
EffectiveReadUser ⊆ ClickUser
ClickUser ⊆ ExposureUser

实际计算时，不能简单统计每天触发各事件的所有用户，否则可能出现：

1
2


曝光用户数：1,000
点击用户数：1,200

这通常说明：

点击事件缺少对应曝光事件
曝光事件丢失
统计周期对不齐
用户在统计周期之前曝光、周期内点击
不同阶段用了不同的用户标识
Join 条件或事件时间逻辑存在问题

因此，严格漏斗一般需要根据 user_id 和事件顺序建立用户路径。

2.2.4 漏斗中的时间窗口

漏斗还必须定义转化窗口。

例如：

用户曝光后 24 小时内发生点击，点击后 7 天内发生订阅。

如果不定义窗口，一个用户 8 月 1 日曝光、8 月 20 日订阅，是否还算同一次转化就会产生歧义。

因此完整漏斗口径至少包括：

漏斗起始事件
后续阶段事件
用户标识
事件先后顺序
阶段间允许的时间窗口
是否允许跨天
是否允许同一用户多次进入漏斗
用户归属哪个渠道

2.2.5 渠道归因问题

用户可能经过多个渠道：

1
2
3
4


Search 曝光
→ Direct 访问
→ Recommendation 点击
→ 完成订阅

此时订阅算给哪个渠道，需要提前定义归因规则，例如：

First-touch：归因给首次渠道
Last-touch：归因给最后一次渠道
Conversion-touch：归因给直接促成转化的渠道
多触点归因：按照规则分摊

所以“比较渠道漏斗”并不只是按 Channel 做一个 GROUP BY，还需要保证渠道归因规则一致。

2.3 留存计算：次日、7 日、30 日留存

留存用于回答：

一批在某天活跃或首次活跃的用户，经过一段时间后，还有多少人再次活跃？

留存通常基于用户集合或 Cohort，也就是具有共同起始条件的一批用户进行计算。

2.3.1 不能只使用每日 AU 数值计算留存

假设：

1
2


8 月 1 日 DAU = 100
8 月 2 日 DAU = 120

仅凭这两个数字，无法计算次日留存率。因为我们不知道 8 月 2 日的 120 个用户中，有多少人在 8 月 1 日也活跃。

可能是：

1
2
3
4


情况 A：
8 月 1 日用户 = {U001 ... U100}
8 月 2 日用户中有 80 人来自 8 月 1 日
次日留存率 = 80 / 100 = 80%

也可能是：

1
2
3


情况 B：
8 月 2 日用户中只有 10 人来自 8 月 1 日
次日留存率 = 10 / 100 = 10%

所以更准确的表述是：

留存基于每日活跃用户明细集合计算，而不是基于已经聚合好的每日 AU 数值计算。

2.3.2 留存的集合公式

令：

1
2
3
4


A0 = 基准日用户集合
A1 = 基准日后第 1 天的活跃用户集合
A7 = 基准日后第 7 天的活跃用户集合
A30 = 基准日后第 30 天的活跃用户集合

那么：

1
2
3
4
5
6
7
8


次日留存用户数 = |A0 ∩ A1|
次日留存率 = |A0 ∩ A1| / |A0|

7 日留存用户数 = |A0 ∩ A7|
7 日留存率 = |A0 ∩ A7| / |A0|

30 日留存用户数 = |A0 ∩ A30|
30 日留存率 = |A0 ∩ A30| / |A0|

其中：

|A0| 表示集合 A0 的用户数
∩ 表示两个用户集合的交集

2.3.3 新增用户留存和活跃用户留存

这是留存分析中非常重要的口径区别。

2.3.3.1 新增用户留存

基准用户是当天首次出现的用户：

1
2
3
4


8 月 1 日新增用户
→ 8 月 2 日是否再次活跃
→ 8 月 8 日是否再次活跃
→ 8 月 31 日是否再次活跃

适合评估：

新用户质量
拉新渠道质量
首次体验效果
新版本 onboarding 效果

2.3.3.2 活跃用户留存

基准用户是当天所有活跃用户：

1
2


8 月 1 日所有 AU
→ 后续是否再次活跃

适合评估：

整体用户黏性
产品持续使用情况
内容用户回访情况

两种口径不能混用。因为新增用户集合通常只是当日所有活跃用户的一个子集。

2.3.4 “第 7 日留存”与“7 日内留存”

这两个指标也不相同。

2.3.4.1 第 7 日留存

用户必须在基准日后的第 7 个自然日再次活跃：

1
2


cohort_date = 8 月 1 日
retention_date = 8 月 8 日

2.3.4.2 7 日内留存

用户在基准日后的第 1 至第 7 日内，只要任意一天回来就算留存：

1

A0 ∩ (A1 ∪ A2 ∪ ... ∪ A7)

一般来说：

1

7 日内留存率 >= 第 7 日留存率

因此报表中只写“7 日留存”是不够严谨的，需要说明：

是第 7 日留存
还是 7 日内任意一天回来
还是第 7 日及以后仍有活跃

2.3.5 用户留存的SQL 实现思路

假设先生成用户每日活跃表：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


WITH daily_active AS (
 SELECT DISTINCT
 event_date,
 user_id
 FROM user_event
 WHERE is_active_event = 1
),
cohort AS (
 SELECT
 event_date AS cohort_date,
 user_id
 FROM daily_active
 WHERE event_date = '2026-08-01'
)
SELECT
 c.cohort_date,
 COUNT(DISTINCT c.user_id) AS cohort_users,
 COUNT(DISTINCT CASE
 WHEN DATEDIFF(d.event_date, c.cohort_date) = 1
 THEN c.user_id
 END) AS day_1_retained_users,
 COUNT(DISTINCT CASE
 WHEN DATEDIFF(d.event_date, c.cohort_date) = 7
 THEN c.user_id
 END) AS day_7_retained_users,
 COUNT(DISTINCT CASE
 WHEN DATEDIFF(d.event_date, c.cohort_date) = 30
 THEN c.user_id
 END) AS day_30_retained_users
FROM cohort c
LEFT JOIN daily_active d
 ON c.user_id = d.user_id
GROUP BY
 c.cohort_date;

然后计算：

1
2
3


Day 1 Retention = day_1_retained_users / cohort_users
Day 7 Retention = day_7_retained_users / cohort_users
Day 30 Retention = day_30_retained_users / cohort_users

2.4 三类应用之间的关系

可以把三类分析理解成三个不同问题：

分析类型	要回答的问题	说人话就是	去重范围	核心运算
多维分析	活跃用户来自哪些分群	谁在活跃？来自哪个 Market、Device、Partner、Channel？	在某个维度组合内去重	分组后去重
漏斗分析	用户在不同业务阶段流失在哪里	用户做到了哪一步？曝光、点击、阅读、订阅之间在哪里流失？	在每个业务阶段内去重，并建立阶段关系	阶段集合的包含与转化
留存分析	同一批用户后续是否再次回来	用户以后还回来吗？次日、第 7 日、第 30 日是否再次活跃？	在不同日期的用户集合之间求交集	跨时间集合求交集

3. 在数据模型中的关键设计原则

3.1 保留统一的用户标识

如果一部分事件使用 UserId，另一部分使用 DeviceId，则可能出现：

同一个人被识别成多个用户
不同漏斗阶段无法关联
留存率被低估
AU 被高估

因此最好建立统一的 CanonicalUserId 或明确身份拼接规则。

3.2 明确时间口径

需要固定：

使用 UTC 还是 Market Local Time
自然日从几点到几点
跨市场报表按哪个时区计算
迟到数据如何回补
回补后是否重算历史 AU 和留存

对于跨 Market 的全球数据，同一个 UTC 时间可能属于不同地区的不同自然日。

3.3 AU 字段不能默认 SUM

在 BI 或语义模型中，AU 应标记为：

不可加指标
Non-additive Metric
禁止默认 SUM

因为下面这些通常都是错误的：

1
2
3
4


月 AU = 每日 AU 求和
整体 AU = 各 Market AU 求和
Partner AU = 各 Content AU 求和
全设备 AU = 各 Device AU 求和

如果下游经常查询固定的维度组合，可以提前生成每种 All 粒度的精确 AU；如果需要大量灵活的任意维度上卷，则可以考虑用户明细、Bitmap 或近似去重结构。

4. 一句话总结

Active User 的本质是“在特定时间窗口内，满足特定活跃条件的去重用户集合大小”。

因此：

多维分析是在不同维度范围内分别计算这个集合。用来了解不同分群的用户活跃情况。
漏斗分析是在多个有先后关系的行为阶段之间比较用户集合。比较不同渠道的 DAU 变化，辅助运营决策。
留存分析是在不同时间点之间计算同一批用户集合的交集。基于每日 AU 计算次日/7日/30日留存率。
AU 不是普通可加指标，跨日期、设备、市场、内容或渠道汇总时，通常必须重新基于用户粒度去重。

【工作杂谈_20260806】多维分析与数据建模: CROSS JOIN 实战：灵活生成多维聚合组合

Thu, 06 Aug 2026 22:17:08 +0800

1、CROSS JOIN简介

CROSS JOIN 返回两表的笛卡尔积：左表的每一行都会与右表的每一行组合。本例两表各有 3 行，因此返回 3 \times 3 = 9 行；NULL 不参与匹配判断，也不会阻止组合。

连接 Hive 数据库，创建示例表并填充数据：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


create table orders(
user_id string,
amount double
)
row format delimited fields terminated by '\t'
stored as textfile;

insert into orders values
('1',100),
(NULL,200),
('3',300);

create table users(
user_id string,
user_name string
)
row format delimited fields terminated by '\t'
stored as textfile;

insert into users values
('1','Alice'),
('2','Bob'),
(NULL,'Charlie');

select * from orders;
select * from users;

orders

user_id	amount
1	100
NULL	200
3	300

users

user_id	user_name
1	Alice
2	Bob
NULL	Charlie

1
2
3


SELECT *
FROM orders o
CROSS JOIN users u;

结果：

user_id	amount	user_id	user_name
1	100.0	1	Alice
1	100.0	2	Bob
1	100.0	NULL	Charlie
NULL	200.0	1	Alice
NULL	200.0	2	Bob
NULL	200.0	NULL	Charlie
3	300.0	1	Alice
3	300.0	2	Bob
3	300.0	NULL	Charlie

SQL 在没有 ORDER BY 时不保证结果顺序，表格中的顺序仅用于展示。

2、大数据下的应用场景

2.1 引入分组聚合函数

假设SourceTable表的记录如下，其中的Col1, Col2,Col3,Col4, Col5 对应了我们关注的5个统计维度

PartnerID	BrandID	ContentID	Col1	Col2	Col3	Col4	Col5	UserMUID
P1	B1	C1	Video	10	App	CN	Sports	U1
P1	B1	C1	Video	30	Web	CN	Finace	U1
P1	B1	C1	Artical	20	App	CN	Finace	U2
P1	B1	C1	Artical	10	App	CN	Sports	U1

如果想探究Col1与用户的关系，那么就需要计算在不同的Col1值下 User的数量，也就是下面的sql

1
2
3


select Col1,Count(distinct UserMUID)
from SourceTable
group by Col1

同理如果想探究Col2, cols3, col4 col5与用户的关系，那么就需要计算在不同的Col2, cols3, col4 col5值下 User的数量，也就是下面的sql

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


select Col2,Count(distinct UserMUID)
from SourceTable
group by Col2

select Col3,Count(distinct UserMUID)
from SourceTable
group by Col3

select Col4,Count(distinct UserMUID)
from SourceTable
group by Col4

select Col5,Count(distinct UserMUID)
from SourceTable
group by Col5

现在问题变得更复杂，如果想探究Col1, Col2的组合与用户的关系，那么就需要写重新sql进行计算

回想一下数学种的统计知识，已知Col1, Col2, cols3, col4 col5这5个维度是互不干扰的，且每个维度的值都不为空，那么其所有的组合就是对5个位置的独立选择，这5个空位分别有两个值可选：存在/不存在。最后会得到2的5次方=32共32种组合

那么如果我们想全面地分析维度与用户数量的关系，就应该得到32个类似上面的sql。很显然这种做法很蠢，是白白浪费代码和时间，属于是在时间和空间上都不讨巧的笨蛋做法。

所以早在1996年就有人提出了更加优秀的解决办法：分组聚合函数

使用分组聚合函数ROLLUP / CUBE / GROUPING SETS可以用一个sql直接生成上面32种维度的聚合结果指定维度的组合，

2.1.1 大数据领域 OLAP 分组扩展引入时间线

时间点事件

1996 Gray 等学者在论文中提出 CUBE 概念

1999–2002 SQL:1999 标准正式纳入 ROLLUP / CUBE / GROUPING SETS

~2012–2013 Hive 0.10.0 引入 GROUPING SETS、CUBE、ROLLUP(Hadoop 生态最早原生支持)

2015 年中 Spark 1.4.0 在 DataFrame API 中引入 CUBE 算子

2015 年底 Spark 1.6 补齐 rollup()，DataFrame API 多维聚合能力完整

2016 PostgreSQL 9.5 才支持 CUBE / ROLLUP / GROUPING SETS

2017 Hive 2.3.0 对齐标准 SQL 的 GROUPING 语义

由于这篇文章不是为了介绍分组聚合函数的，所以对三个关键字不熟悉或者感兴趣的同学可以看我这篇文章：HIVE高级分组聚合的 GROUPING SETS / ROLL UP / CUBE 关键字

2.2 引入CROSS JOIN搭配辅助表

当想一次SQL跑出多种维度组合的聚合结果时，很容易想到 HIVE高级分组聚合的 GROUPING SETS / ROLL UP / CUBE 关键字

但是有些情况还不够灵活：

如果5个维度之间不存在递进关系，就不能使用ROLL UP
5个维度完全组合会得到2^5次方=32共32种维度组合，但如果某些组合不想要了，就不能使用 CUBE（CUBE是自动按照维度计算全组合的）
假设只需其中30种的维度组合，全部都在GROUPING SETS 中一个个声明也很麻烦。而且如果维度从5个变为6个，那么代码又要重新修改。

此时如果将维度组合显示记录在一个辅助表DimensionCombinations，就可以避免上面的问题：

从数学的角度看，这5个维度的组合就是5个可重复的独立选择，这5个空位分别有两个值可选：不聚合/聚合，分别可以抽象成0/255

0 是一个“保留原始维度值”的控制标记。
255 是一个“将该维度替换为 All”的控制标记。

那么事先将这些组合写入0/255的辅助表中，再和业务表执行 CROSS JOIN就自然可以得出所有维度的组合。当想去掉某些维度的聚合时，只需要将列值置为0则不会进入聚合阶段。

这里的做法我觉得很类似用空间换时间的算法，我们提前将表进行膨胀组合，就省去了后面多次按照不同维度的聚合。

下面以完整的32个组合的辅助表DimensionCombinations为例，讲下具体怎么使用

维度1	维度2	维度3	维度4	维度5
0	0	0	0	0
0	0	0	0	255
0	0	0	255	0
0	0	255	0	0
0	255	0	0	0
…	…	…	…	…
255	255	255	255	255

当一条记录如下，其中的Col1, Col2,Col3,Col4, Col5 对应了我们关注的5个数据维度，分别对应辅助表DimensionCombinations 会进行组合的5个维度

PartnerID	BrandID	ContentID	Col1	Col2	Col3	Col4	Col5	UserMUID
P1	B1	C1	Video	10	App	CN	Sports	U1

这条记录和辅助表的32 行做 CROSS JOIN 后，这一行会在逻辑上扩展成 32 行。

以Col1 被置为255为例，讲一下此类型的组合后续会发生什么，其他组合同理。

当某条 DimensionCombinations 记录的 Col1 = 255 时，该组合下所有原始 Col1 都被映射为统一的 255，虽然 Col1 仍出现在分组列中，但由于其值完全相同，效果等同于消除 Col1 维度。可以理解为此组合下时分组条件从 Col1, Col2,Col3,Col4, Col5 的5列变为了Col2,Col3,Col4,Col5 的4列

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


ExtendedResult =
 SELECT 
 L.PartnerID,
 L.BrandID,
 R.Col1 == 0 ? L.Col1 : 255 AS Col1 ,
 R.Col2 == 0 ? L.Col2 : 255 AS Col2 ,
 R.Col3 == 0 ? L.Col3 : 255 AS Col3 ,
 R.Col4 == 0 ? L.Col4 : 255 AS Col4 ,
 R.Col5 == 0 ? L.Col5 : 255 AS Col5 ,
 UserMUID
 FROM SourceTable AS L
 CROSS JOIN DimensionCombinations AS R;

那么此时再执行 COUNT(DISTINCT UserMUID)（如下），膨胀出来的32行的具有相同的UserMUID，CROSS JOIN只是提前将所有统计维度提前应用到原始行上，组合结果中如果Col1 = 255则表示消除了此维度，只留下一个值255

中文的含义就是以Col1=all维度的汇总数据

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


AggResult = 
 SELECT
 PartnerID,
 BrandID,
 Col1 ,
 Col2 ,
 Col3 ,
 Col4 ,
 Col5 ,
 COUNT(DISTINCT UserMUID) AS AUCount
 FROM ExtendedResult;

以此类推，这样通过一个辅助表DimensionCombinations，就可以通过一次分组计算得到任意5个维度的所有组合，而不必指定具体维度名字。如果有其他表的其他列也需要进行5个维度的全组合，也可以使用同样的辅助表。

以这种方式来计算多维度下的统计数据，可以减少计算资源的浪费，因为只读取了一次源数据，就得到了所有维度的统计结果，避免了重复读取。

2.3 详细步骤

如果上面的使用方法的抽象概念没有看懂，可以看下这里的分步详解；如果上面的讲解能够理解，这一小节可以跳过。

表还是SourceTable，以下面的记录为例

PartnerID	BrandID	ContentID	Col1	Col2	Col3	Col4	Col5	UserMUID
P1	B1	C1	Video	10	App	CN	Sports	U1
P1	B1	C1	Video	30	Web	CN	Finace	U1
P1	B1	C1	Artical	20	App	CN	Finace	U2
P1	B1	C1	Artical	10	App	CN	Sports	U1

为了便于理解，暂时不看DimensionCombinations的全部 32 行，只取下面两个组合：

1
2
3


Col1    Col2    Col3    Col4    Col5
255     0 0 0 0
255     255 0 0 255

它们分别表示：

1
2


255 0 0 0 0 = Col1 上卷为 All，其他四个维度保留原值
255 255 0 0 255 = Col1、Col2、Col5 上卷为 All，其他两个维度保留原值

代码中的表达式：

1

R.Col1 == 0 ? L.Col1 : 255 AS Col1

含义是：

1
2
3
4
5


R.Col1 = 0
 => 输出 L.Col1，保留原值

R.Col1 = 255
 => 输出 255，表示 All Col1 Types

原始4条数据经过下面的sql转换后

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


ExtendedResult =
 SELECT 
 L.PartnerID,
 L.BrandID,
 L.ContentID,
 R.Col1 == 0 ? L.Col1 : 255 AS Col1 ,
 R.Col2 == 0 ? L.Col2 : 255 AS Col2 ,
 R.Col3 == 0 ? L.Col3 : 255 AS Col3 ,
 R.Col4 == 0 ? L.Col4 : 255 AS Col4 ,
 R.Col5 == 0 ? L.Col5 : 255 AS Col5 ,
 UserMUID
 FROM SourceTable AS L
 CROSS JOIN DimensionCombinations AS R;

就会膨胀得到4*32行，表示原始行与32个维度的组合

2.3.1 第一个组合：255 0 0 0 0

当组合为：255 0 0 0 0，表示Col1 上卷为 All。执行下面的代码后

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


ExtendedResult =
 SELECT 
 L.PartnerID,
 L.BrandID,
 L.ContentID,
 R.Col1 == 0 ? L.Col1 : 255 AS Col1 ,
 R.Col2 == 0 ? L.Col2 : 255 AS Col2 ,
 R.Col3 == 0 ? L.Col3 : 255 AS Col3 ,
 R.Col4 == 0 ? L.Col4 : 255 AS Col4 ,
 R.Col5 == 0 ? L.Col5 : 255 AS Col5 ,
 UserMUID
 FROM SourceTable AS L
 CROSS JOIN DimensionCombinations AS R;

表达式会把每条记录的 Col1 都改成 255，此时Col1=all（即不再区分 Col1），第一行、第四行的数据在Col1~Col5这几列是完全一致的

PartnerID	BrandID	ContentID	Col1	Col2	Col3	Col4	Col5	UserMUID
P1	B1	C1	255	10	App	CN	Sports	U1
P1	B1	C1	255	30	Web	CN	Finace	U1
P1	B1	C1	255	20	App	CN	Finace	U2
P1	B1	C1	255	10	App	CN	Sports	U1

这部分数据再进行分组

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


AggResult = 
 SELECT
 PartnerID,
 BrandID,
 ContentID,
 Col1,
 Col2,
 Col3,
 Col4,
 Col5,
 COUNT(DISTINCT UserMUID) AS AUCount
 FROM ExtendedResult;

统计结果如下

PartnerID	BrandID	ContentID	Col1	Col2	Col3	Col4	Col5	AUCount
P1	B1	C1	255	10	App	CN	Sports	1
P1	B1	C1	255	30	Web	CN	Finace	1
P1	B1	C1	255	20	App	CN	Finace	1

需要注意由于原来的第一行和第四行是同一个用户，所以ActiveUser通过DISTINCT只能算作一个

2.3.2 第一个组合：255 255 0 0 255

当组合为：255 255 0 0 255，表示Col1,Col2,Col5 上卷为 All。执行下面的代码后

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


ExtendedResult =
 SELECT 
 L.PartnerID,
 L.BrandID,
 L.ContentID,
 R.Col1 == 0 ? L.Col1 : 255 AS Col1 ,
 R.Col2 == 0 ? L.Col2 : 255 AS Col2 ,
 R.Col3 == 0 ? L.Col3 : 255 AS Col3 ,
 R.Col4 == 0 ? L.Col4 : 255 AS Col4 ,
 R.Col5 == 0 ? L.Col5 : 255 AS Col5 ,
 UserMUID
 FROM SourceTable AS L
 CROSS JOIN DimensionCombinations AS R;

表达式会把每条记录的 Col1,Col2,Col5 的值都改成 255，此时Col1=all, Col2=all, Col5=all,（即不再区分 Col1,Col2,Col5），第一行、第三行、第四行的数据在Col1~Col5这几列是完全一致的

PartnerID	BrandID	ContentID	Col1	Col2	Col3	Col4	Col5	UserMUID
P1	B1	C1	255	255	App	CN	255	U1
P1	B1	C1	255	255	Web	CN	255	U1
P1	B1	C1	255	255	App	CN	255	U2
P1	B1	C1	255	255	App	CN	255	U1

这部分数据再进行分组

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


AggResult = 
 SELECT
 PartnerID,
 BrandID,
 ContentID,
 Col1,
 Col2,
 Col3,
 Col4,
 Col5,
 COUNT(DISTINCT UserMUID) AS AUCount
 FROM ExtendedResult;

统计结果如下

PartnerID	BrandID	ContentID	Col1	Col2	Col3	Col4	Col5	AUCount
P1	B1	C1	255	255	App	CN	255	2
P1	B1	C1	255	255	Web	CN	255	1

2.3.3 组合总结

通过上面的两种组合的案例，应该可以很好地将这个逻辑扩展到剩余的组合中。

当初始表的维度为5个时，光统计一个AUCount（ActiveUserCount）指标我们就可以膨胀出2^5=32倍的记录。也就是说随着表的维度增加，统计的指标增加，最终膨胀出的行数是以指数级别扩张的。（当数据量达到千万以上时需要注意数据倾斜的问题）

所以这时候使用CROSS JOIN辅助表的优势就会越来越明显，因为一次CROSS JOIN可以得出多个维度组合的统计，不仅比分开写多条GROUP BY的代码更简洁，还减少对原始表的重复扫描，并减少了Reduce的次数。

3、CROSS JOIN扩展维度的优势

最后再总结一下使用CORSS JOIN 辅助表的好处：

不依赖特定 CUBE 语法，可通过修改资源文件增加或删除某些组合。
可以统一用 255 表示 All，避免用 NULL 与真实空值混淆。
其他表的处理可以复用相近的维度组合逻辑。

【工作杂谈_20260731】数据平台与工程治理: MySQL 时区转换：UTC、北京时间与 PST/PDT 的对齐

Fri, 31 Jul 2026 18:18:00 +0800

1、问题引入

先介绍一下上游数据：L1事件明细，记录了Web 侧事件级遥测数据，包含用户行为及部分系统/测试/机器人事件。此文件每一个小时记录会生成一个，每个大小为5-30TB左右。

假设当前时间为curr_time，我们需要得到curr_time-2h, curr_time-1h, curr_time, curr_time+1h共计四个文件才能开始当前时间为curr_time的计算任务。每两个小时开始一个这样的计算任务，也就是说一天需要完成12个并生成对应12个文件，每个计算任务完成都会在数据库插入一条记录。

目前的保障措施：因为上游数据数据达到的时间不确定，所以如果想保证计算任务顺利执行，在设计ETL流程时会根据当前时间预判可能的到达时间，并wait10h，在此期间如果需要的所有上游文件都到达就会触发计算任务。同时增加了对上游数据的监控，在规定时间范围内未到达就会触发通知。

但这样做还是有一个遗漏之处，就是是上游文件在规定时间范围内到达，但是由于计算任务时间过长或者计算量太大，就会导致计算任务无法准时完成。而目前监控计算任务是否完成只能通过肉眼去查文件是否生成。

因此引入我的任务：在grafana中新建一个dashboard来可视化计算任务的结果，用来判断计算任务是否完成实现过程也很简单：去查对应时间的数据库内是否有计算任务完成的记录，构造本应在一天中生成的12个文件行，将其与数据库进行Join，对的上的标记为存在，对不上的标记为不存在。

在实现的过程中我发现自己踩了时区转化的坑，导致dashboard中展示的计算结果的create_time和实际create_time不同，具体踩坑点如下：

grafana的dashboard中有时间范围筛选，其默认时区为北京时间
Mysql数据库的时区为UTC时间
计算任务生成的结果存储在Azure云上，其时区为PDT时间

这样就导致了同一条记录在不同的地方查询显示/操作的create_time都是不同的，所以此文章介绍一下时区转换

2、时间解析

2.1 什么是 UTC 时间

2.1.1 UTC 是全球统一的时间基准

UTC 全称：

Coordinated Universal Time，协调世界时

它不是某个国家或城市的地方时间，而是全球系统进行时间同步时使用的基准。

常见表示方式：2026-07-31T06:30:00Z

2026-07-31：日期
T：日期和时间的分隔符
06:30:00：时、分、秒
Z：表示 UTC，也叫 Zulu Time

2.1.2 UTC 和 GMT 的关系

日常业务中，UTC+0和GMT+0两者通常可以视为相同偏移：

但概念上并不完全相同：

UTC：Coordinated Universal Time，现代时间标准，基于原子钟等时间体系。
GMT： Greenwich Mean Time，格林尼治平均时，最初基于天文观测，也常被用作时区名称。

对于日志、数据库、API、Pipeline 和告警系统，建议统一使用 UTC，而不是 GMT。

2.2 什么是北京时间CST

北京时间CST，通常指：

China Standard Time（CST） ，常表示为 UTC+08:00

换算关系：

UTC： 2026-07-31 16:30，对应北京时间： 2026-08-01 00:30（注意，减去或加上 8 小时后，日期也可能变化）

2.2.1 北京时间没有夏令时切换

目前中国标准时间全年固定为：UTC+8

因此，在当前规则下：

夏天是 UTC+8
冬天也是 UTC+8
不存在北京时间突然跳过一小时或重复一小时的问题

不过，跨时区项目中不要把它简单写成模糊的 CST。因为 CST 可能被解释为：

China Standard Time
Central Standard Time
Cuba Standard Time

更明确的写法是：UTC+08:00和 Asia/Shanghai

2.3 什么是 PST 和 PDT

PST 和 PDT 都与北美太平洋时区有关，他们是北美太平洋时区在不同月份范围的细分时区，但是可以统称为Pacific Time（缩写为PT），即PT = PST 或 PDT

按美国现行的一般规则，夏令时从每年 3 月第二个星期日开始，到 11 月第一个星期日结束。这个时间范围内采用PDT时区，剩余时间范围采用PST时区。

2.3.1 PST：Pacific Standard Time

太平洋标准时间 Pacific Standard Time （缩写PST），主要对应不使用夏令时(DST)的时期

UTC 偏移：UTC-8（比 UTC 慢 8 小时）
使用地区：美国西海岸（加州、华盛顿州、俄勒冈州、内华达州等）、加拿大不列颠哥伦比亚省，主要城市包括洛杉矶、旧金山、西雅图、波特兰、温哥华
启用时段：每年 11 月第一个星期日到次年 3 月第二个星期日（即冬令时）
夏令时切换：3 月第二个星期日起切换为 PDT（UTC-7），11 月第一个星期日回切到 PST

2.3.2 PDT：Pacific Daylight Time

太平洋夏令时间 Pacific Daylight Time（PDT）在实行夏令时期间使用

UTC 偏移：PDT = UTC-7（比 UTC 晚 7 小时）
使用地区：美国西海岸（加州、华盛顿州、内华达州、俄勒冈州等）、加拿大不列颠哥伦比亚省，主要城市包括洛杉矶、旧金山、西雅图、波特兰、温哥华等
启用时段：每年 3 月第二个星期日到 11 月第一个星期日
冬令时切换：夏令时结束后切换回 PST（Pacific Standard Time，太平洋标准时间，UTC-8）

💡 注意：PDT 只在夏令时期间有效（3 月中～11 月初）。其余月份美国西海岸用的是 PST（UTC-8）。如果你的业务时间跨度覆盖全年，不能简单地固定减 7 小时，应该用命名时区让 MySQL 自动处理切换：

1

CONVERT_TZ(utc_time, '+00:00', 'America/Los_Angeles')

2.3.3 PST 与 PDT 的关系

两者指的是同一个地理区域的同一条时间线，只是根据季节在"标准时间"和"夏令时"之间切换：

时段	缩写	全称	UTC 偏移
冬季（11 月～3 月）	PST	Pacific Standard Time	UTC-8
夏季（3 月～11 月）	PDT	Pacific Daylight Time	UTC-7

也就是说，PDT = PST + 1 小时。夏令时开始时时钟拨快 1 小时（PST → PDT），结束时拨慢 1 小时（PDT → PST）。

💡 所以严格来说，“Pacific Time（PT）“是一个统称，它底下分 PST 和 PDT 两种状态，随季节切换。

2.4 PST/PDT 与北京时间相差多少

已知：

PDT = UTC-7，PST = UTC-8，北京时间 = UTC+8

所以可以得出：

太平洋当地时间	UTC 偏移	与北京时间的时差
PST	UTC-8	CST=PST+16H
PDT	UTC-7	CST=PST+15H

3、跨时区项目一般怎么处理

原则一：后端和数据层统一使用 UTC

建议以下内容全部保存为 UTC：

数据库时间字段
Pipeline 的运行时间
文件到达时间
日志时间
API 请求时间
事件发生时间
告警检测时间
消息队列中的时间
分布式系统 Watermark
审计记录

例如：2026-07-31T06:30:00Z

而不是只保存：2026-07-31 14:30:00

后者没有说明时区，无法判断它是北京时间、UTC 还是美国当地时间。

原则二：展示时才转成用户当地时间

典型流程是：

1
2
3
4
5
6
7
8
9


事件发生
↓
转换为 UTC
↓
数据库按 UTC 保存
↓
API 返回 UTC
↓
前端根据用户时区显示

4、我的项目怎么处理

因为想的是替换掉手动去云存储那里一个个查文件的过程，所以dashboard这里显示的时间要和云存储的create_time一致

1
2


MySQL create_time = UTC
云存储 create_time = 洛杉矶当地时间

针对目标查询表加一层view视图，将转为洛杉矶当地时间，如下

1

CONVERT_TZ(create_time, '+00:00', 'America/Los_Angeles')

如果转换完得到的时间为NULL，是因为MySQL 必须查询内部时区表，以确定：

America/Los_Angeles 是否存在
2026 年 7 月 31 日是否处于夏令时
此时应该使用 UTC-7 还是 UTC-8
夏令时切换边界如何处理

当前 MySQL 查不到对应的时区规则，因此返回 NULL。解决办法详见下面的4.1、4.2、4.3

4.1 查看MySQL Server 和 Session 当前使用的时区

1
2
3
4


SELECT
 @@system_time_zone AS system_time_zone,
 @@global.time_zone AS global_time_zone,
 @@session.time_zone AS session_time_zone;

system_time_zone	global_time_zone	session_time_zone
China Standard Time	SYSTEM	SYSTEM

4.2 查看命名时区表是否已经加载

1
2
3
4


SELECT
 COUNT(*) AS timezone_count
FROM mysql.time_zone_name
WHERE Name = 'America/Los_Angeles';

timezone_count
0

4.3 开启时区数据库

要在 MySQL 中使用命名时区（如 'America/Los_Angeles'、'Asia/Shanghai'），必须先把系统的 IANA 时区数据库（zoneinfo）加载进 MySQL 自带的 mysql.time_zone_* 系统表里。否则 CONVERT_TZ 用命名时区时会返回 NULL。

4.3.1 windows系统

windows系统则首先下载 MySQL 时区包：MySQL :: Time zone description tables，选择timezone_2026c_posix_sql.zip，解压到对应位置（我的位置是：C:\Users\v-liuyuhang\AppData\Roaming\DBeaverData\workspace6\General\timezone_posix.sql）打开cmd，进入mysql.exe所在目录，我的是 C:\Program Files\MySQL\MySQL Server 8.4\bin

执行命令：

1

mysql -u root -p mysql < C:\Users\v-liuyuhang\AppData\Roaming\DBeaverData\workspace6\General\timezone_posix.sql

4.3.2 Linux系统

大多数 Linux 发行版和 macOS 在 /usr/share/zoneinfo 下都有 IANA 数据库，直接用一行管道加载

1

mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql

4.3.4 云数据库

1

mysql --host="xxx.com" --port=3306 --user="xxx" --password --ssl-mode=REQUIRED mysql < C:\Users\v-liuyuhang\AppData\Roaming\DBeaverData\workspace6\General\timezone_posix.sql

然后弹出 Enter password: 输入密码

4.3.3 验证

1
2
3
4


SELECT
 NOW() AS mysql_original_time,
 CONVERT_TZ( NOW() , '+00:00', 'America/Los_Angeles') AS los_angeles_time,
 CONVERT_TZ( NOW() , '+00:00', '+08:00') AS beijing_time;

mysql_original_time	los_angeles_time	beijing_time
2026-07-31 17:36:02	2026-07-31 10:36:02	2026-08-01 01:36:02

时间点	事件
1996	Gray 等学者在论文中提出 CUBE 概念
1999–2002	SQL:1999 标准正式纳入 ROLLUP / CUBE / GROUPING SETS
~2012–2013	Hive 0.10.0 引入 GROUPING SETS、CUBE、ROLLUP(Hadoop 生态最早原生支持)
2015 年中	Spark 1.4.0 在 DataFrame API 中引入 CUBE 算子
2015 年底	Spark 1.6 补齐 rollup()，DataFrame API 多维聚合能力完整
2016	PostgreSQL 9.5 才支持 CUBE / ROLLUP / GROUPING SETS
2017	Hive 2.3.0 对齐标准 SQL 的 GROUPING 语义

维度1	维度2	维度3	维度4	维度5
0	0	0	0	0
0	0	0	0	255
0	0	0	255	0
0	0	255	0	0
0	255	0	0	0
…	…	…	…	…
255	255	255	255	255

PartnerID	BrandID	ContentID	Col1	Col2	Col3	Col4	Col5	UserMUID
P1	B1	C1	255	255	App	CN	255	U1
P1	B1	C1	255	255	Web	CN	255	U1
P1	B1	C1	255	255	App	CN	255	U2
P1	B1	C1	255	255	App	CN	255	U1

维度1	维度2	维度3	维度4	维度5
0	0	0	0	0
0	0	0	0	255
0	0	0	255	0
0	0	255	0	0
0	255	0	0	0
…	…	…	…	…
255	255	255	255	255

PartnerID	BrandID	ContentID	Col1	Col2	Col3	Col4	Col5	UserMUID
P1	B1	C1	255	255	App	CN	255	U1
P1	B1	C1	255	255	Web	CN	255	U1
P1	B1	C1	255	255	App	CN	255	U2
P1	B1	C1	255	255	App	CN	255	U1

工作杂谈 on My Learning Notes

【工作杂谈_20260901】数据监控：ADTK Python 项目搭建与验证

1. 最终项目状态

2. 从零搭建与验证

步骤 1：检查工作区并确定项目根目录

步骤 2：创建并确认虚拟环境

步骤 3：编写兼容的依赖约束

步骤 4：安装项目依赖

检查依赖冲突

步骤 5：创建项目文件

.gitignore

README.md

examples/basic_detection.py

步骤 6：执行语法检查

步骤 7：端到端运行验证

3. 一次性复查

【工作杂谈_20260825】数据平台与工程治理: Benchmark 与 Baseline：从基准测试到生产基线

1. Benchmark 与 Baseline 分别是什么

1.1 Benchmark（基准测试）

1.1.1 常见的 Benchmark 工具与标准

1.1.2 Benchmark 在项目生命周期中的位置

1.2 Baseline（基线）

1.3 区别

1.4 关系

2. 如何设计一个可信的 Benchmark

2.1 先定义决策

2.2 固定测试契约

2.3 让负载接近真实生产

2.4 执行和统计结果

2.5 结果不是一个孤立排名

3. 如何建立和治理 Baseline

3.1 测试 Baseline 与生产 Baseline

3.2 建立生产 Baseline 的步骤

3.3 静态、分组与动态 Baseline

3.4 Baseline 记录示例

4. 应用实战场景

4.1 Spark 版本升级：性能回归门禁

场景

Benchmark 设计

4.2 查询引擎选型：不仅比较谁最快

场景

Benchmark 设计

4.3 容量规划：找到满足 SLA 的安全容量

场景

Benchmark 设计与结果

4.4 生产监控：从测试成绩到动态基线

场景

5. 常见误区

5.1 把 Benchmark 等同于压测

5.2 只看平均值

5.3 忽略正确性和工作量

5.4 在不可比的条件下比较

5.5 发现回退后立即刷新 Baseline

5.6 把外部成绩当成自己的生产承诺

6. 一份可直接复用的检查清单

7. 总结

参考资料

【工作杂谈_20260817】多维分析与数据建模: 维度上卷——从明细粒度到汇总层级

1. 什么是“维度上卷”

2. ETL 中上卷的核心是“改变事实粒度”

3. ETL 中上卷的完整流程

3.1 数据质量检查

3.2 加载维表

地域维表 DimGeography

日期维表 DimDate

产品表 DimProduct

3.3 生成明细事实表

3.4 预聚合上卷

上卷一：Date → Month

上卷二：City → Province

上卷三：Province → Country

3.5 一致性校验

【工作杂谈_20260815】用户分析与身份体系: CanonicalUserId：从用户标识到身份图谱

1. 先说结论：CanonicalUserId 到底是什么

1.1 第一个问题不是“用哪个 ID”，而是“要统一什么实体”

1.2 几个容易混用的概念

2. 为什么需要身份归一

2.1 一个用户为什么会产生多个标识

2.2 不做身份归一会怎样

2.3 为什么 user_id + device_id 不能成为统一用户键

`.gitignore`

`README.md`

`examples/basic_detection.py`

2.3 为什么 `user_id + device_id` 不能成为统一用户键

维度1	维度2	维度3	维度4	维度5
0	0	0	0	0
0	0	0	0	255
0	0	0	255	0
0	0	255	0	0
0	255	0	0	0
…	…	…	…	…
255	255	255	255	255

PartnerID	BrandID	ContentID	Col1	Col2	Col3	Col4	Col5	UserMUID
P1	B1	C1	255	255	App	CN	255	U1
P1	B1	C1	255	255	Web	CN	255	U1
P1	B1	C1	255	255	App	CN	255	U2
P1	B1	C1	255	255	App	CN	255	U1