tdp 客户端文档

下载安装、登录同步、命令一览与错误排障 —— 从安装到首次同步约 5 分钟。

安装

推荐使用一键脚本：自动识别系统 / 架构、下载对应二进制并安装至 PATH（无权限时自动使用 sudo，或回退至 ~/.local/bin）。安装完成后运行 tdp -v 验证。

一键安装（推荐）

# Linux / macOS
curl -fsSL https://tdp-site.pages.dev/install.sh | sh

# Windows (PowerShell)
irm https://tdp-site.pages.dev/install.ps1 | iex

脚本支持环境变量覆盖：TDP_BIN_DIR 修改安装目录、TDP_BASE 修改下载源。

手动安装

如不使用脚本，可选择对应平台的单行命令：

# Linux x86_64（ARM64 替换为 tdp-linux-arm64）
wget -O tdp https://pub-2929ddee7aa7487d9e6bb71b4c2f5b8a.r2.dev/tdp-linux-amd64 && chmod +x tdp && sudo mv tdp /usr/local/bin/tdp

# macOS Apple Silicon（Intel 替换为 tdp-darwin-amd64）
curl -fL https://pub-2929ddee7aa7487d9e6bb71b4c2f5b8a.r2.dev/tdp-darwin-arm64 -o tdp && chmod +x tdp && sudo mv tdp /usr/local/bin/tdp

# Windows (PowerShell)；ARM64 替换为 arm64
iwr https://pub-2929ddee7aa7487d9e6bb71b4c2f5b8a.r2.dev/tdp-windows-amd64.exe -OutFile tdp.exe

Windows 手动安装：将 tdp.exe 放入固定目录（如 C:\Users\<你>\bin\）并加入用户 Path，重新打开 PowerShell 运行 tdp -v。

校验完整性（可选）

如有安全需求，可另行下载 SHA256SUMS 至同一目录进行校验：

# Linux
sha256sum -c SHA256SUMS --ignore-missing      # 期望: tdp-linux-amd64: OK
# macOS
shasum -a 256 -c SHA256SUMS --ignore-missing

校验失败请勿运行

说明文件在传输过程中被篡改或截断。请删除后重新下载；若仍失败，请联系运营重新发送。

首次运行的系统警告

当前发行包未做代码签名，操作系统首次运行时会拦截。这是已知问题，待用户规模稳定后将补充签名。

macOS：「无法打开，来自身份不明的开发者」

在终端移除隔离属性（一次即可）：xattr -d com.apple.quarantine /usr/local/bin/tdp
或在 Finder 中右键 → 打开 → 在弹窗中再次点击「打开」。

Windows：「Windows 已保护你的电脑」

点击「更多信息」→「仍要运行」。

Linux 无此问题。

登录与同步

安装完成后三步即可跑通。--dburi 会将 ClickHouse 连接串写入本地配置，后续 sync 无需重复传入。

# 1. 登录（key 填入运营发送的激活串）
tdp login --email you@example.com \
          --dburi 'clickhouse://default@127.0.0.1:9000/tdx_pro?http_port=8123'

# 2. 拉取增量，解密后写入本地 ClickHouse
tdp sync

# 3. 查看状态（订阅到期、本地数据水位、版本）
tdp status

命令一览

命令	作用
`tdp login`	激活设备，校验订阅，写入本地 `~/.tdp/auth.json`
`tdp sync`	按 server 最新可用日期向 ClickHouse 增量追加（写入独立 `tdx_pro` 库）
`tdp import <file.tdpa>`	导入运营交付的离线历史包（断网超过 30 天时使用）
`tdp status`	订阅状态 + 已绑设备 + 数据水位 + 版本
`tdp support`	一键诊断报告（出现问题时提供给运营）
`tdp config`	查看 / 修改本地配置（如持久化 DSN）
`tdp logout`	清除本地登录态（不影响 server 绑定与本地数据）
`tdp -v`	显示版本号

升级：以新版本覆盖旧 binary 即可，~/.tdp/ 与本地 ClickHouse 数据均无需改动。完全卸载：删除 binary 并执行 rm -rf ~/.tdp（本地库表不受影响）。

常见错误排障

遇到问题时，请先运行 tdp support 并将输出提供给运营 —— 该命令会汇总 build 信息、登录态、server 健康状况、ClickHouse 连通性与 sync 判定。以下为高频问题的自助解法：

SHA256 校验 MISMATCH

文件在传输过程中被篡改或截断。请删除后重新下载；若仍失败，说明链路存在问题，请联系运营重新发送。

macOS / Windows 打不开、被系统拦截

参见首次运行的系统警告 —— 移除隔离属性 /「仍要运行」即可。

命令找不到：`tdp: command not found`

二进制所在目录未加入 PATH。上述安装命令默认放置于 /usr/local/bin（通常已在 PATH 中）；若放置于其他目录，请确认该目录已加入 PATH 并重新打开终端；Windows 修改环境变量后需重新打开 PowerShell。

sync 报错：落后超过 30 天

watermark 落后于线上保留窗口（约 30 天），旧数据已不在线，sync 不负责补充较早的历史。补充此部分需使用离线历史包：由运营生成 .tdpa 文件，再执行 tdp import xxx.tdpa。

重新拉取某段数据

sync 的水位由 ClickHouse 现有数据自动推算，无手动覆盖的 flag。请先通过 ALTER TABLE ... DROP PARTITION 删除该段数据，再执行 tdp sync 即会自动补回。

ClickHouse 连接失败 / 未写入

检查 DSN：通过 tdp config 查看当前持久化的 dburi，或临时覆盖 tdp sync --dburi 'clickhouse://...'。确认 ClickHouse 正在运行，端口（9000 native / 8123 http）与库名正确。

key 遗失 / 更换设备无法登录

key 不会保存在本地。如遗失，请联系运营重置，使用新 key 重新执行 tdp login 即可。单份订阅默认绑定单台设备。