GA 采集流水线指南
按属性显示 GA4 数据卡在注册 → 采集(原始) → AI 汇总 → 展示哪个阶段的诊断页面。
📋 概述
GA4 指标要显示在**GA 分析报告**中,需要经过 4 个阶段。
| 阶段 | 含义 | 存储位置 |
|---|---|---|
| 目录(注册) | 在**GA 媒体资源管理**中注册属性 | tGaProperty |
| 采集(原始) | 采集器从 GA4 Data API 获取的原始指标 | tKVS(kType='ga') |
| AI 汇总 | 将原始指标由 AI 加工成报告 | tGaAiReport |
| 展示 | 在页面上显示上述结果 | /zh-CN/gareport |
如果只注册了属性但没有采集器运行,就会卡在目录阶段,页面上什么都不显示。本页面正是用来显示"哪个阶段是空的"。
🚦 状态说明
| 状态 | 含义 |
|---|---|
| 正常 | 采集和 AI 汇总均正常 |
| AI 待处理 | 原始数据已采集,但 AI 汇总尚未运行 |
| 未采集 | 原始采集本身没有在运行(最常见的问题) |
| 未激活 | 属性已禁用(不采集) |
▶️ "开始采集"按钮
处于未采集状态的属性,行中会显示**[开始采集]**按钮。点击后会立即触发该属性的一次性 GA4 采集(与定期采集计划无关)。
点击后可能出现的消息:
| 消息 | 原因 | 解决方法 |
|---|---|---|
| 已开始采集 | 正常 | 稍后刷新,确认"采集(原始)"时间已填充 |
| 该组织尚未注册 GA 采集器(GA Collector) | 从未为该组织(csn)注册过任何 GA 采集计划(CQE) — 这不是代码问题,而是尚未配置 | 按下方"🔗 关联 GA 采集器服务器"步骤由管理员首次注册 |
| 您没有权限采集此 GA 属性 | 该属性属于其他组织,或登录账号不属于该组织 | 切换到正确的组织(csn)后重试 |
🔗 关联 GA 采集器服务器(管理员操作)
"该组织尚未注册 GA 采集器"意味着没有任何服务器(lssn)被配置为定期运行该组织的 GA 采集任务。这与在页面上注册属性是不同的服务器基础设施关联工作,需要单独的步骤。
为什么仅靠 Web UI 不够
CQE(预约脚本)注册页面(/zh-CN/cqeRepoPut)对脚本正文有4,000 字符限制,而 GA 采集脚本正文远超此长度(Linux 版约 7,800 字符,Windows 版约 9,700 字符)。因此脚本本身的首次注册只能通过 CLI 完成。将其关联到服务器(计划分配)则可以通过 Web UI 完成。
第 1 步 — 注册采集脚本 + 关联服务器(仅首次,CLI)
使用 giipdb/mgmt/register-ga-cqe.ps1。该脚本一次性完成以下两件事:
- 将采集脚本正文注册到 CQE 仓库(
CQERepoPut)→ 生成mssn - 将该脚本分配到指定服务器(
lssn)每日执行(CQEQueuePut)
# 面向 Linux 服务器(推荐 — 自动从数据库获取密钥,无需本地密钥文件)
pwsh .\mgmt\register-ga-cqe.ps1 -Lssn <目标服务器 lssn> -MsType sh `
-Property 'properties/123456789' -Auid '<您的登录 ID>'
# 面向 Windows 服务器(giip-803 之后:省略 -KeyFile 时自动从数据库获取密钥)
pwsh .\mgmt\register-ga-cqe.ps1 -Lssn <目标服务器 lssn> -MsType ps1 `
-Property 'properties/123456789' -Dispatcher 'https://<giip byAK 分发器 URL>' -Auid '<您的登录 ID>'重要: 目标服务器(-Lssn)必须属于该 GA 属性所属的组织(csn)。使用其他组织的服务器注册虽然能通过身份验证,但会一直找不到该组织的 GA 属性/密钥而失败 — 请先在**服务器列表**中确认目标服务器所属的组织。
通过 -Property 指定的属性必须已在**GA 媒体资源管理**页面注册(包括服务账号密钥)。
第 2 步 — 将已注册的脚本关联到其他服务器(可用 Web UI)
如果脚本(mssn)已存在,想在其他服务器上运行同样的采集,可以通过 Web UI 完成。
- 进入**CQE 队列注册**页面
- mssn: 点击[选择]按钮搜索并选择已有的"GA Collector..."脚本
- Lssn Group: 勾选目标服务器
- csn: 目标组织编号
- interval: 采集周期(分钟)。每日一次填
1440 - custom_values: 面向 shell(Linux)目标的示例
(服务账号密钥会自动从数据库获取,无需设置GaProperty='properties/123456789'GaKeyFile) - 保存 — 完成后在**按服务器运行列表**中确认注册
确认注册状态
🔗 后续步骤
版本: 1.0
最后更新: 2026-07-29
源文件: giipv3/public/help/ga-pipeline.zh-CN.md