ae-tracking 0.1.0

package/wiki/te-docs/raw//350/277/233/351/230/266/346/225/260/346/215/256/347/261/273/345/236/213.md

@@ -0,0 +1,22 @@
+---
+code: advanced_data_type
+name: "进阶数据类型"
+wikiToken: Ljs3w406DiyDLnktFuAcHogInvg
+parentWikiToken: Iufpwws70iX4tUk5qOOcwG5fnFb
+updateTime: 1745310938000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=advanced_data_type
+---
+# 进阶数据类型
+
+本章节主要介绍 AE 系统中的进阶数据类型，进阶数据类型在系统接收时会有进行额外的数据处理逻辑，在结构上和标准的数据结构也有一些区别，可以查看对应文档了解每种进阶数据类型的能力。
+
+::: warning
+
+ 进阶数据类型会有较大的性能开销，为了保证数据处理效率，建议只在合适的场景下使用
+
+ :::
+
+目前存在的进阶数据类型如下：
+
+- 可更新事件：可以对事件属性进行更新的特殊事件
+- 首次事件校验：通过加入首次事件校验标识 ID 来判断事件是否首次发生，只允许让 ID 首次出现的数据入库

package/wiki/te-docs/schema.md

@@ -0,0 +1,17 @@
+# AE docs Wiki Schema
+
+## Layout
+- `index.md` — catalog of pages with raw paths and source URLs
+- `raw/` — Feishu docx → markdown mirror (read-only, crawler-owned)
+- `synthesis/` — topic pages authored by synthesizer agents
+- `log.md` — last build report
+
+## Query flow for consuming skills
+1. Read `index.md` first.
+2. For topic overviews, prefer `synthesis/`.
+3. For exact API / config lookup, read `raw/`.
+4. Cite `sourceUrl` from page frontmatter when quoting.
+
+## Rules
+- Do not edit `raw/` — it is regenerated by the crawler.
+- Hand-authored or LLM-synthesized notes go in `synthesis/`.

package/wiki/te-docs/synthesis/batch-ingest-comparison.md

@@ -0,0 +1,117 @@
+---
+topic: 批量日志接入方案对比
+sources:
+  - raw/接入指南/数据导入.md
+  - raw/接入指南/数据导入/logbus2-使用指南.md
+  - raw/接入指南/数据导入/logbus-使用指南.md
+  - raw/接入指南/数据导入/ta-datax-writer-插件使用指南.md
+  - raw/接入指南/数据导入/filebeat-logstash-使用指南.md
+  - raw/接入前准备工作/数据规则.md
+generated: 2026-04-15
+---
+
+# 批量日志接入方案对比
+
+AE 提供多种批量/日志类数据导入工具，适用于服务端日志同步、历史数据迁移、多数据源对接等场景。所有工具上传的数据必须遵循 AE 数据格式 [[raw/接入前准备工作/数据规则.md]]。
+
+## 方案总览
+
+[[raw/接入指南/数据导入.md]]
+
+| 工具 | 数据来源 | 吞吐 | 历史数据 | 维护状态 | 主要限制 |
+|---|---|---|---|---|---|
+| **LogBus2** | 日志文件 / Kafka / SLS / CLS | 高 | 最优 | 活跃（推荐） | 需要 Linux/Mac/Win 部署 |
+| LogBus v1 | 日志文件 / Kafka | 中 | 支持 | 维护中（建议迁移） | 内存占用高，速度慢 |
+| DataX Writer | MySQL/HDFS 等多数据源 | 批量 | 适合 | 稳定 | 需要 Java 环境 |
+| Filebeat + Logstash | 日志文件 | 低 | 不推荐 | 稳定 | 吞吐量低 |
+
+## LogBus2（推荐）
+
+[[raw/接入指南/数据导入/logbus2-使用指南.md]]
+
+**版本**：v2.1.2.2（2025-11-07），相比 LogBus v1 内存减少 80%、速度提升 5 倍。
+
+**支持数据源**：
+- 本地日志文件（监听目录变更）
+- Kafka（需开启 Consumer Group，默认从 earliest 消费）
+- SLS（需联系阿里云开启 Kafka 协议消费）
+- CLS（需关闭自动分裂，申请 AK/SK）
+
+**安装包**：Linux amd64/arm64、Windows、macOS Apple Silicon/Intel、Docker Image
+
+**注意事项**：
+- 不要对监听目录下已上传的日志直接重命名（重命名 = 新建文件，会重复上传）
+- 不要手动修改 `runtime/` 目录下的进度快照文件
+- 从 LogBus v1 迁移需联系数数技术支持
+
+## LogBus v1（维护中）
+
+[[raw/接入指南/数据导入/logbus-使用指南.md]]
+
+**版本**：v1.5.17（2022-11-08）
+
+**升级方式**（v1.5.0+）：
+```bash
+./logbus stop
+./logbus update
+```
+
+**每个 APP_ID 至少预留 10G 磁盘空间**（因内部数据缓冲区）。
+
+**建议**：新项目直接使用 LogBus2；现有 v1 用户联系技术支持迁移。
+
+## DataX Writer（ta-datax-writer）
+
+[[raw/接入指南/数据导入/ta-datax-writer-插件使用指南.md]]
+
+**适用场景**：从 MySQL、PostgreSQL、HDFS、HBase 等 DataX 支持的数据源迁移数据至 TE。
+
+**安装步骤**：
+```bash
+# 1. 下载并解压 DataX
+wget http://datax-opensource.oss-cn-hangzhou.aliyuncs.com/datax.tar.gz
+tar -zxvf datax.tar.gz
+
+# 2. 安装 ta-datax-writer 插件
+wget https://download.thinkingdata.cn/tools/release/ta-datax-writer.tar.gz
+cp ta-datax-writer.tar.gz datax/plugin/writer/
+cd datax/plugin/writer && tar -zxvf ta-datax-writer.tar.gz
+```
+
+**特性**：支持 gzip/lzo/lz4/snappy 压缩；支持多线程传输；仅支持写入 AE 集群。
+
+## Filebeat + Logstash
+
+[[raw/接入指南/数据导入/filebeat-logstash-使用指南.md]]
+
+**适用场景**：团队已有 ELK 日志采集栈，希望复用已有管道将数据同步至 TE。
+
+**安装 Logstash 插件**：
+```bash
+bin/logstash-plugin install logstash-output-thinkingdata
+# 验证安装
+bin/logstash-plugin list
+```
+
+**插件版本**：v1.2.0（2023-04-25），需 Logstash 6.x+（依赖 JDK）
+
+**限制**：**吞吐量低**，不适合大批量历史数据导入，如需大量历史数据请改用 DataX 或 LogBus2。
+
+## 数据格式要求
+
+所有批量导入工具上传的数据必须是符合 AE 数据格式的 JSON，每行一条 [[raw/接入前准备工作/数据规则.md]]：
+
+```json
+{
+  "#account_id": "USER_ID",
+  "#distinct_id": "VISITOR_ID",
+  "#type": "track",
+  "#time": "2026-01-01 10:00:00.000",
+  "#event_name": "event_name",
+  "properties": {
+    "key": "value"
+  }
+}
+```
+
+`#type` 可选值：`track`、`user_set`、`user_setOnce`、`user_add`、`user_unset`、`user_append`、`user_del`。

package/wiki/te-docs/synthesis/js-sdk-cheatsheet.md

@@ -0,0 +1,136 @@
+---
+topic: JavaScript SDK 速查手册
+sources:
+  - raw/接入指南/客户端-sdk/javascript.md
+  - raw/接入指南/客户端-sdk/javascript/进阶指南.md
+  - raw/接入前准备工作/用户识别规则.md
+  - raw/接入前准备工作/预置属性与系统字段.md
+generated: 2026-04-15
+---
+
+# JavaScript SDK 速查手册
+
+适用于 Web（Vue2/3、React、Angular）及 Electron 桌面应用。最新版本 **v2.3.1**（2026-01-07）[[raw/接入指南/客户端-sdk/javascript.md]]。
+
+## 安装
+
+```bash
+# npm
+npm install thinkingdata-browser --save
+```
+
+或者手动载入（`thinkingdata.min.js` 异步 / `thinkingdata.umd.min.js` 同步）。
+
+## 初始化
+
+```js
+import ta from "thinkingdata-browser";
+ta.init({
+  appId: "YOUR_APP_ID",               // 必填
+  serverUrl: "https://YOUR_SERVER_URL/sync_js", // 必填；云服务用 https://global-receiver-ta.thinkingdata.cn
+  autoTrack: {
+    pageShow: true,   // 自动采集页面展示事件 ta_page_show
+    pageHide: true,   // 自动采集页面隐藏事件 ta_page_hide
+  }
+});
+```
+
+[[raw/接入指南/客户端-sdk/javascript.md]]
+
+## 用户 ID 管理
+
+AE 使用三层 ID 体系：访客 ID（`#distinct_id`）、账号 ID（`#account_id`）、AE 用户 ID（系统内部）[[raw/接入前准备工作/用户识别规则.md]]。
+
+```js
+// 设置自定义访客 ID（一般不需要，SDK 自动生成）
+ta.setDistinctId("custom-visitor-id");
+
+// 获取访客 ID
+const vid = ta.getDistinctId();
+
+// 用户登录 → 设置账号 ID
+ta.login("user-account-id");   // 不会上报登录事件
+
+// 用户登出 → 清除账号 ID
+ta.logout();                   // 不会上报登出事件
+```
+
+[[raw/接入指南/客户端-sdk/javascript/进阶指南.md]]
+
+## 事件上报
+
+```js
+// 普通事件
+ta.track("product_buy", { product_name: "商品名", price: 99 });
+
+// 首次事件（同设备只记录一次）
+ta.trackFirstEvent("first_launch", {}, "first_check_id");
+
+// 可更新事件
+ta.trackUpdate("order_pay", { status: "paid" }, "ORDER_ID_001");
+
+// 可覆盖事件
+ta.trackOverwrite("order_pay", { status: "refunded" }, "ORDER_ID_001");
+```
+
+事件名只能以字母开头，包含字母/数字/下划线，最长 50 字符 [[raw/接入指南/客户端-sdk/javascript.md]]。
+
+## 公共事件属性
+
+```js
+// 设置（持久化到缓存）
+ta.setSuperProperties({
+  channel: "ta",
+  age: 25,
+  isVip: true,
+  birthday: new Date(),
+  obj: { key: "value" },
+  arr: ["a", "b"]
+});
+
+// 动态超级属性（每次 track 时实时计算）
+ta.setDynamicSuperProperties(() => ({ current_time: Date.now() }));
+
+// 清除单个
+ta.unsetSuperProperties("channel");
+
+// 清除全部
+ta.clearSuperProperties();
+
+// 设置页面级属性
+ta.setPageProperty({ page_title: document.title });
+```
+
+[[raw/接入指南/客户端-sdk/javascript/进阶指南.md]]
+
+## 用户属性
+
+```js
+ta.userSet({ username: "Alice", level: 10 });       // 覆盖
+ta.userSetOnce({ register_date: new Date() });       // 仅首次设置生效
+ta.userAdd({ total_spend: 99.9 });                   // 数值累加
+ta.userDel();                                        // 删除用户
+```
+
+## 时间事件
+
+```js
+// 开始计时
+ta.timeEvent("product_view");
+// 触发时自动附加 #duration 属性（秒）
+ta.track("product_view", { product_id: "P001" });
+```
+
+## 预置属性说明
+
+[[raw/接入前准备工作/预置属性与系统字段.md]] 中，系统自动填充以 `#` 开头的字段（`#ip`、`#country`、`#os` 等），**不建议手动覆盖**，除 `#ip` 外其他预置属性需在 AE 工作人员指导下设置。
+
+## 多实例
+
+```js
+ta.initInstance("sub");         // 创建子实例
+ta.sub.init({ appId: "SUB_APP_ID", serverUrl: "..." });
+ta.sub.track("event_name", {});
+```
+
+[[raw/接入指南/客户端-sdk/javascript/进阶指南.md]]

package/wiki/te-docs/synthesis/restful-api-reference.md

@@ -0,0 +1,142 @@
+---
+topic: RESTful API 接入速查
+sources:
+  - raw/接入指南/restful-api-使用指南.md
+  - raw/接入前准备工作/数据规则.md
+  - raw/接入前准备工作/用户识别规则.md
+generated: 2026-04-15
+---
+
+# RESTful API 接入速查
+
+AE RESTful API 允许在不集成 SDK 或传输工具的情况下，通过 HTTP POST 直接向 AE 上报数据。适用于脚本对接、第三方系统集成、快速验证等场景 [[raw/接入指南/restful-api-使用指南.md]]。
+
+## 接入前提
+
+上报数据必须遵循 AE 数据格式，详见 [[raw/接入前准备工作/数据规则.md]]。用户 ID 需同时包含 `#account_id`（登录后）或 `#distinct_id`（未登录），详见 [[raw/接入前准备工作/用户识别规则.md]]。
+
+## 接口地址
+
+| 部署类型 | form-data 接口 | raw JSON 接口 |
+|---|---|---|
+| 云服务 | `https://global-receiver-ta.thinkingdata.cn/sync_data` | `https://global-receiver-ta.thinkingdata.cn/sync_json` |
+| 私有化部署 | `http://数据采集地址/sync_data` | `http://数据采集地址/sync_json` |
+
+## 方式一：form-data 上报（`/sync_data`）
+
+### 单条数据
+
+```bash
+# 原始 JSON
+{
+  "#account_id": "testing",
+  "#time": "2019-01-01 10:00:00.000",
+  "#type": "track",
+  "#event_name": "testing",
+  "properties": { "test": "test" }
+}
+
+# urlencode 后
+curl "http://receiver:9080/sync_data" \
+  --data "appid=YOUR_APP_ID&data=%7b%22%23account_id%22%3a%22testing%22...%7d"
+```
+
+### 多条数据
+
+```bash
+curl "http://receiver:9080/sync_data" \
+  --data "appid=YOUR_APP_ID&data_list=URLENCODed_JSON_ARRAY"
+```
+
+### 请求参数
+
+| 参数 | 说明 | 必填 |
+|---|---|---|
+| `appid` | 项目 APP ID | 是 |
+| `data` | 单条 JSON，UTF-8 + urlencode | 二选一 |
+| `data_list` | JSONArray 格式多条数据，UTF-8 + urlencode | 二选一 |
+| `client` | 0（默认）/ 1（强制用上报端 IP 替换 `#ip`） | 否 |
+| `debug` | 0（关闭）/ 1（开启调试，返回详细错误） | 否 |
+
+**注意**：Python3 requests 库、Postman 等工具会自动 urlencode，无需手动编码。
+
+## 方式二：raw JSON 上报（`/sync_json`）
+
+### 单条数据
+
+```bash
+curl -X POST "https://global-receiver-ta.thinkingdata.cn/sync_json" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "appid": "YOUR_APP_ID",
+    "debug": 0,
+    "data": {
+      "#type": "track",
+      "#event_name": "test",
+      "#time": "2019-11-15 11:35:53.648",
+      "#distinct_id": "visitor-001",
+      "properties": { "a": "123", "b": 2 }
+    }
+  }'
+```
+
+### 多条数据
+
+```bash
+curl -X POST "https://global-receiver-ta.thinkingdata.cn/sync_json" \
+  -H "Content-Type: application/json" \
+  -d '[
+    { "appid": "YOUR_APP_ID", "data": { "#type": "track", ... } },
+    { "appid": "YOUR_APP_ID", "data": { "#type": "track", ... } }
+  ]'
+```
+
+## 返回码
+
+| code | 含义 |
+|---|---|
+| `0` | 上报成功 |
+| `-1` | 数据格式错误（开启 debug 模式时返回详细原因） |
+
+Debug 示例错误响应：
+```json
+{"code":-1,"msg":"#time字段格式不对,需传递[yyyy-MM-dd HH:mm:ss]或者[yyyy-MM-dd HH:mm:ss.SSS]格式"}
+```
+
+## 数据结构速查
+
+[[raw/接入前准备工作/数据规则.md]]
+
+```json
+{
+  "#account_id": "ABCDEFG-123",        // 登录 ID（与 #distinct_id 至少一个必填）
+  "#distinct_id": "UUID-xxx",          // 访客 ID
+  "#type": "track",                    // 数据类型
+  "#time": "2026-01-01 10:00:00.000", // 时间，精确到秒或毫秒
+  "#event_name": "event_name",         // 事件名（type=track 时必填）
+  "#ip": "1.2.3.4",                    // 可选，用于地理信息
+  "#uuid": "unique-uuid",              // 可选，用于去重
+  "properties": {
+    "key": "value"                     // 自定义属性
+  }
+}
+```
+
+`#type` 枚举值：
+
+| 值 | 含义 |
+|---|---|
+| `track` | 普通事件 |
+| `track_update` | 可更新事件 |
+| `track_overwrite` | 可覆盖事件 |
+| `user_set` | 设置用户属性（覆盖） |
+| `user_setOnce` | 首次设置用户属性 |
+| `user_add` | 用户属性数值累加 |
+| `user_unset` | 清空用户属性 |
+| `user_append` | 用户属性数组追加 |
+| `user_del` | 删除用户 |
+
+## Debug 模式建议
+
+- `debug=1` 时每条数据都会校验并立即入库，**仅用于测试少量数据**
+- **禁止在生产环境开启 debug 模式**，会严重影响上报性能

package/wiki/te-docs/synthesis/sdk-selection.md

@@ -0,0 +1,79 @@
+---
+topic: SDK 选型指南
+sources:
+  - raw/接入指南/客户端-sdk.md
+  - raw/接入指南/服务端-sdk.md
+  - raw/接入指南/数据导入.md
+  - raw/接入指南/restful-api-使用指南.md
+  - raw/接入前准备工作/数据规则.md
+generated: 2026-04-15
+---
+
+# SDK 选型指南
+
+本页综合各接入方式的特点，帮助您快速选择最适合场景的 AE 数据接入方案。
+
+## 接入方式总览
+
+| 接入方式 | 适用场景 | 数据延迟 | 开发成本 | 批量历史数据 |
+|---|---|---|---|---|
+| 客户端 SDK | 移动端/Web/游戏客户端行为采集 | 实时 | 低 | 不适合 |
+| 服务端 SDK + LogBus | 后端业务事件、高精度数据 | 近实时 | 中 | 支持 |
+| LogBus2（独立） | 日志文件监听、Kafka消费、大批量历史数据 | 近实时 | 低（配置型） | 最优 |
+| DataX Writer | 多数据源迁移、离线同步 | 批量 | 中 | 适合 |
+| Filebeat + Logstash | 已有ELK栈、日志管道复用 | 近实时 | 中（吞吐低） | 不推荐 |
+| RESTful API | 无法集成SDK的场景、快速验证 | 实时 | 中（需自行处理） | 支持（手动） |
+
+## 客户端 SDK
+
+[[raw/接入指南/客户端-sdk.md]] 中列出的客户端覆盖范围：
+
+**移动原生**：Android、iOS、OpenHarmony、macOS
+
+**Web**：JavaScript（Vue2/3、React、Angular、Electron，~58 KB）
+
+**小程序/小游戏**：微信小程序等
+
+**游戏引擎**：Unity、Unreal、Cocos2d-x、Cocos2d-Lua、CocosCreator、LayaAir、Egret、Corona
+
+**跨平台框架**：React Native、Flutter、uni-app、C++客户端、C#客户端
+
+客户端 SDK 自动管理访客 ID、账号 ID 的绑定，并在本地缓存 ID，适合需要自动采集用户行为的场景。
+
+## 服务端 SDK
+
+[[raw/接入指南/服务端-sdk.md]] 中支持的语言：Java、Golang、C、C#、Erlang、Ruby、Lua、Node.js、PHP、Python、C++。
+
+服务端 SDK 的推荐模式是 **SDK 写本地日志文件 + LogBus 监听上传**，既保证数据不丢失，又避免对业务线程产生阻塞影响（[[raw/接入指南/服务端-sdk/java.md]]）。
+
+## 批量日志接入（LogBus / DataX / Filebeat）
+
+| 工具 | 推荐版本 | 特点 |
+|---|---|---|
+| LogBus2 | v2.1.2.2（推荐） | 内存占用减至 LogBus v1 的 1/5、速度提升 5 倍，支持 Kafka/SLS/CLS [[raw/接入指南/数据导入/logbus2-使用指南.md]] |
+| LogBus v1 | v1.5.17（维护中） | 经典版本，仍可用，但建议迁移至 v2 [[raw/接入指南/数据导入/logbus-使用指南.md]] |
+| DataX Writer | — | 适合从 MySQL/HDFS 等多数据源迁移数据，使用 ta-datax-writer 插件 [[raw/接入指南/数据导入/ta-datax-writer-插件使用指南.md]] |
+| Filebeat + Logstash | Logstash 6.x+ | 已有 ELK 栈时复用，**吞吐量低，不适合大批量历史数据** [[raw/接入指南/数据导入/filebeat-logstash-使用指南.md]] |
+
+## RESTful API
+
+[[raw/接入指南/restful-api-使用指南.md]] 提供两种上报方式：
+
+- **form-data**：`POST /sync_data`，参数 `appid`、`data`（urlencode）、`client`
+- **raw JSON**：`POST /sync_json`，Body 直接包含 `appid` + `data` 字段
+
+适用于：不便集成 SDK 的脚本/工具、快速数据验证、第三方系统对接。数据格式必须遵循 AE 数据规则（[[raw/接入前准备工作/数据规则.md]]）。
+
+## 选型决策树
+
+```
+需要采集客户端行为？
+  └─ 是 → 选对应平台的客户端 SDK
+需要服务端业务事件？
+  └─ 是 → 服务端 SDK + LogBus2
+需要同步历史数据/多数据源迁移？
+  └─ 大量 → LogBus2 或 DataX Writer
+  └─ 少量 → RESTful API
+已有 ELK 栈？
+  └─ 是 → Filebeat + Logstash（注意吞吐限制）
+```

package/wiki/te-docs/synthesis/server-sdk-overview.md

@@ -0,0 +1,124 @@
+---
+topic: 服务端 SDK 总览
+sources:
+  - raw/接入指南/服务端-sdk.md
+  - raw/接入指南/服务端-sdk/java.md
+  - raw/接入指南/服务端-sdk/python.md
+  - raw/接入指南/服务端-sdk/golang.md
+  - raw/接入指南/服务端-sdk/nodejs.md
+  - raw/接入前准备工作/用户识别规则.md
+generated: 2026-04-15
+---
+
+# 服务端 SDK 总览
+
+AE 服务端 SDK 用于从后端服务采集业务事件，支持 11 种语言。推荐架构：**SDK 写本地日志 → LogBus 监听上传**，避免直接 HTTP 推送对业务线程的阻塞影响。
+
+## 支持语言对照表
+
+[[raw/接入指南/服务端-sdk.md]]
+
+| 语言 | 包名/获取方式 | 最新版本 | 更新时间 |
+|---|---|---|---|
+| Java | Maven: `cn.thinkingdata:thinkingdatasdk` | v3.0.4-beta.1 | 2026-01-07 |
+| Python | `pip install ThinkingDataSdk` | v3.0.0 | 2023-10-07 |
+| Golang | `go get github.com/ThinkingDataAnalytics/go-sdk/v2` | v2.1.0 | 2024-12-19 |
+| Node.js | `npm install thinkingdata-node` | v1.5.0 | 2024-03-26 |
+| PHP | Composer / 源码 | — | — |
+| Ruby | 源码 | — | — |
+| Lua | 源码 | — | — |
+| C (服务端) | 源码 | — | — |
+| C# (服务端) | 源码 | — | — |
+| C++ (服务端) | 源码 | — | — |
+| Erlang | 源码 | — | — |
+
+## 初始化模式对比
+
+所有服务端 SDK 均支持以下两种 Consumer 模式：
+
+| 模式 | 说明 | 推荐场景 |
+|---|---|---|
+| **LoggerConsumer（推荐）** | 写入本地日志文件，配合 LogBus 上传 | 生产环境 |
+| **BatchConsumer** | 批量直接 HTTP 上报 | 低流量/测试场景 |
+
+### Java 示例
+
+```java
+// LoggerConsumer 模式
+TDAnalytics te = new TDAnalytics(new TDLoggerConsumer("LOG_DIRECTORY"), false);
+
+// 带文件名前缀
+TDLoggerConsumer.Config config = new TDLoggerConsumer.Config("LOG_DIRECTORY");
+config.setFilenamePrefix("server_events");
+TDAnalytics te = new TDAnalytics(new TDLoggerConsumer(config), false);
+```
+
+[[raw/接入指南/服务端-sdk/java.md]]
+
+### Python 示例
+
+```python
+from tgasdk.sdk import *
+consumer = TDLogConsumer(
+    "LOG_DIRECTORY",
+    rotate_mode=TD_ROTATE_MODE.HOURLY,
+    file_prefix="LOG_FILE_PREFIX"
+)
+te = TDAnalytics(consumer)
+```
+
+[[raw/接入指南/服务端-sdk/python.md]]
+
+### Golang 示例
+
+```go
+import "github.com/ThinkingDataAnalytics/go-sdk/v2/src/thinkingdata"
+// 创建 LogConfig 后初始化 TDAnalytics
+```
+
+[[raw/接入指南/服务端-sdk/golang.md]]
+
+### Node.js 示例
+
+```js
+const ThinkingData = require('thinkingdata-node');
+let teSDK = ThinkingData.initWithLoggingMode('LOG_DIRECTORY', {
+    filePrefix: 'test',
+    rotateHourly: true
+});
+```
+
+[[raw/接入指南/服务端-sdk/nodejs.md]]
+
+## 核心 API（跨语言通用）
+
+所有服务端 SDK 提供一致的 API 语义：
+
+| API | 作用 |
+|---|---|
+| `track(accountId, distinctId, event, properties)` | 上报普通事件 |
+| `trackFirstEvent(...)` | 首次事件（同 firstCheckId 只入库一次） |
+| `trackUpdate(...)` | 可更新事件 |
+| `trackOverwrite(...)` | 可覆盖事件 |
+| `userSet(...)` | 设置用户属性（覆盖） |
+| `userSetOnce(...)` | 首次设置用户属性 |
+| `userAdd(...)` | 数值类用户属性累加 |
+| `userDel(...)` | 删除用户 |
+| `flush()` | 手动刷新缓冲区 |
+| `close()` | 关闭 SDK，确保数据落盘 |
+
+## 用户 ID 注意事项
+
+服务端 SDK 不会自动管理 ID，调用方需同时传入 `accountId` 和 `distinctId`。若只传其中一个，可能导致 ID 无法绑定、用户重复计算 [[raw/接入前准备工作/用户识别规则.md]]。
+
+## 推荐部署架构
+
+```
+业务服务 → 服务端 SDK（LoggerConsumer）→ 本地日志文件
+                                           ↓
+                                    LogBus2 监听
+                                           ↓
+                                     AE 接收端
+```
+
+详细 LogBus2 配置见 `synthesis/batch-ingest-comparison.md`。