tdp 客户端手册

安装与更新、登录同步、状态与排障 —— 从安装到首次同步约 5 分钟。

tdp 是终端用户客户端：登录激活订阅，把加密数据增量解密后写入你自己的本地 ClickHouse。一个二进制即可，无后台常驻。数据落库后如何查询，见数据库表与查询。

先免费体验？

无需付费即可跑通完整 login → sync 流程、看真实数据长什么样 —— 公开 demo 账号见首页快速开始。本页讲订阅后的正式用法，二者是同一个二进制、同一条代码路径。

安装与更新

推荐一键脚本：自动识别系统 / 架构、下载对应二进制并装入 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 改下载源。

手动安装

不使用脚本时，按平台挑一条单行命令。共 6 个变体，ARM64 机器把 amd64 换成 arm64：

# Linux x86_64
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)
iwr https://pub-2929ddee7aa7487d9e6bb71b4c2f5b8a.r2.dev/tdp-windows-amd64.exe -OutFile tdp.exe

你的系统	文件名
Linux x86_64	`tdp-linux-amd64`
Linux ARM64	`tdp-linux-arm64`
macOS Intel	`tdp-darwin-amd64`
macOS Apple Silicon（M 系列）	`tdp-darwin-arm64`
Windows x64	`tdp-windows-amd64.exe`
Windows ARM64	`tdp-windows-arm64.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 无此问题。

更新与卸载

更新：用新版本二进制覆盖旧的即可 —— 重跑一键脚本，或重复上面的手动安装命令。~/.tdp/（登录态、本地配置）与本地 ClickHouse 数据均无需改动。

卸载：删除二进制并执行 rm -rf ~/.tdp。本地 ClickHouse 库表不受影响；如需一并清除数据，自行 DROP DATABASE。

同步与导入（sync · import）

日常只用两条命令：tdp sync 跟最新（每天盘后增量），tdp import 接离线历史包（断线过久或补早期数据时）。

登录与首次同步

安装完成后三步即可跑通。--dburi 会把 ClickHouse 连接串写入本地配置，后续 sync 无需重复传入。库名（DSN 末尾的 tdp）由你决定，可自定义。

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

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

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

`tdp login` 参数	说明
`--email`	用户邮箱（留空则提示输入）
`--dburi`	可选：把 ClickHouse DSN 一并写入本地配置；不传则不写入

key 不会保存在本地，server 端也只存其哈希。登录成功后写入 ~/.tdp/auth.json（chmod 600）。tdp logout 清除本地登录态，不影响 server 端设备绑定与本地数据。

tdp sync —— 每日增量

按 server 端最新可用日期，向各表增量追加。水位（watermark）= 每张表 max(日期列) 的最小值，全部由 ClickHouse 里现有数据自动推算，没有手动指定起止日期的参数。

tdp sync                                    # 跟到最新
tdp sync --dburi 'clickhouse://...'         # 临时换库（不写入配置）
TDP_DBURI='clickhouse://...' tdp sync       # 同上，环境变量形式

落后超过 30 天会硬报错

线上数据保留窗口约 30 天，更早的数据已不在线，sync 不负责补充。断线过久或要补早期历史，请改用 tdp import 接离线包。

tdp import —— 离线历史包

导入运营交付的 .tdpa 离线历史包（如 A 股逐笔全历史、断线超 30 天后的补数）。可传单个文件，也可传目录（目录内所有 .tdpa 按文件名顺序逐个导入，按月切分的一堆月文件直接丢进去即可）。

tdp import alice-history-2024_2025.tdpa      # 单文件
tdp import ./cn_tick_2024/                   # 目录：批量导入其中所有 .tdpa
tdp import --dburi 'clickhouse://...' xxx.tdpa

遇错即停，修好重跑安全：建表用 CREATE IF NOT EXISTS、写入为 INSERT 追加，重跑不会破坏已建结构。
不会 OOM：客户端把每张表转成 ArrowStream 流式灌入 ClickHouse，服务端内存恒定（约 90MB），与文件大小无关 —— 几个 GB 的月度 tick 包也能稳定导入。
转码需要落一份临时文件（约等于解密后大小，占客户端本地磁盘，不是 ClickHouse），可用 TMPDIR 改落盘位置。

import 与 sync 的分工

sync 管「最近 30 天的每日增量」，import 管「离线交付的历史包」。两者写入同一批表，互不冲突。

重新拉取某段数据

sync 的水位由现有数据自动推算，没有强制覆盖的参数。要重拉某段，先用 ClickHouse 删掉该段，再 tdp sync 自动补回：

-- 在 clickhouse-client 中删除某个分区后重新同步
ALTER TABLE tdp.raw_kline_daily DROP PARTITION '202405';

tdp sync

状态与支持

出问题先跑 tdp support 把输出贴给运营 —— 它会汇总 build 信息、登录态、server 健康、ClickHouse 连通性与 sync 判定，绝大多数问题据此即可定位。

tdp status —— 订阅与设备

查 server 端订阅状态（到期时间）+ 已绑设备清单 + 本地数据水位 + 版本。不连 ClickHouse。

tdp support —— 一键诊断

生成一份诊断报告：build 信息 + 登录态 + server 健康 + ClickHouse 连通性 + sync 判定。server 不可达时回落到本地缓存（~/.tdp/sync_state.json）。遇到任何问题，跑它、把输出发给运营。

tdp config —— 本地配置

查看 / 修改本地配置（refresh_token 等敏感字段脱敏显示）：

tdp config                            # 查看当前配置
tdp config dburi 'clickhouse://...'   # 持久化 ClickHouse DSN
tdp config dburi ''                   # 清除已持久化的 DSN

DSN 优先级：命令行 --dburi > 环境变量 TDP_DBURI > 配置文件 > 报错。

命令一览

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

常见问题排障

SHA256 校验 MISMATCH —— 文件在传输中被篡改或截断。删除后重新下载；若仍失败请联系运营重发。

macOS / Windows 打不开、被系统拦截 —— 参见首次运行的系统警告，移除隔离属性 /「仍要运行」即可。

tdp: command not found —— 二进制所在目录不在 PATH。一键脚本默认装到 /usr/local/bin 或 ~/.local/bin；手动放到其他目录时，确认该目录已加入 PATH 并重开终端（Windows 改环境变量后需重开 PowerShell）。

sync 报错：落后超过 30 天 —— watermark 落后于线上保留窗口（约 30 天），旧数据已不在线。补充历史需由运营生成 .tdpa 文件，再 tdp import。

ClickHouse 连接失败 / 未写入 —— 用 tdp config 查看持久化的 dburi，或临时 tdp sync --dburi '...' 覆盖。确认 ClickHouse 正在运行，端口（9000 native / 8123 http）与库名正确。

key 遗失 / 更换设备无法登录 —— key 不保存在本地，遗失请联系运营重置，用新 key 重新 tdp login。单份订阅默认绑定单台设备。