---
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, eventName, properties)` | 上报普通事件（**⚠️ Python 位置参数顺序为 `distinct_id, account_id`，其余 SDK 为 `accountId, distinctId`；Python 建议用 keyword args**） |
| `trackFirstEvent(...)` | 首次事件（同 firstCheckId 只入库一次） |
| `trackUpdate(...)` | 可更新事件 |
| `trackOverwrite(...)` | 可覆盖事件 |
| `userSet(...)` | 设置用户属性（覆盖） |
| `userSetOnce(...)` | 首次设置用户属性 |
| `userAdd(...)` | 数值类用户属性累加 |
| `userDel(...)` | 删除用户 |
| `flush()` | 手动刷新缓冲区 |
| `close()` | 关闭 SDK，确保数据落盘 |

### ⚠️ track() 参数顺序差异（重要）

各服务端 SDK 的 `track()` 参数位置**不完全一致**，生成代码时必须按对应 SDK 实际顺序：

| SDK | 位置参数顺序 | 建议写法 |
|---|---|---|
| Java | `track(accountId, distinctId, eventName, properties)` | 位置参数 |
| Go | `Track(accountId, distinctId, eventName, properties)` | 位置参数 |
| **Python** | **`track(distinct_id, account_id, eventName, properties)`** — **distinct_id 在前** | **优先用 keyword args** |
| Node.js | 单个 object 参数 `{accountId, distinctId, event, ...}` | object arg |

**Python keyword args 示例**（避免顺序混淆）：
```python
te.track(account_id="...", distinct_id="...", event_name="...", properties={...})
```

## 用户 ID 注意事项

服务端 SDK 不会自动管理 ID，调用方需同时传入 `accountId` 和 `distinctId`。若只传其中一个，可能导致 ID 无法绑定、用户重复计算 [[raw/接入前准备工作/用户识别规则.md]]。

## 推荐部署架构

```
业务服务 → 服务端 SDK（LoggerConsumer）→ 本地日志文件
                                           ↓
                                    LogBus2 监听
                                           ↓
                                     AE 接收端
```

详细 LogBus2 配置见 `synthesis/batch-ingest-comparison.md`。
