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 即可。单订阅默认绑单设备。