TKstore API · White Paper

概览

TKstore 把 TikTok 三套独立 API 收敛成一个对外契约，让上层业务专注数据应用而非协议适配。

Developer

Display + Content Posting

用户授权登录、视频列表、内容发布、Webhook 事件 (粉丝/点赞/视频更新)。

Shop Partner

Shop Open API

店铺授权、订单/商品/库存同步、店铺事件 Webhook、多区域 (US / SEA / Global)。

Business

Marketing API

广告账户、Campaign / AdGroup / Ad、投放数据回流（规划中）。

Aggregation

店铺指标

跨数据源聚合店铺级 KPI，统一暴露 /api/shops/:id/metrics。

架构

入口机 (LA) 承担公网接入与 TLS 终止，核心机走 Tailscale 内网保持私有。所有 TikTok 出站走核心机的代理出口。

  ┌────────────┐    HTTPS    ┌──────────────────────┐    Tailscale    ┌──────────────────┐
  │  Client /  │ ──────────▶ │  LA Edge (Caddy)     │ ──────────────▶ │  Core (Go x3)    │
  │  TikTok    │             │  23.224.189.188      │   100.x mesh    │  Postgres/Redis  │
  └────────────┘             │  *.evageek.com TLS   │                 │  Metabase/asynq  │
                             └──────────────────────┘                 └──────────────────┘
                                       │                                       │
                                       └─────── DERP fallback ────────────────┘

  组件:  Caddy 2.11 · Go 1.23 · Postgres 16 · Redis 7 · Metabase · Tailscale 1.96
  进程:  tkstore-api · tkstore-worker · tkstore-scheduler  (systemd 管理)

子域职责

子域	用途	访问
`tk.evageek.com`	对外 API + OAuth + Webhook	Public
`bi.evageek.com`	Metabase BI 看板	账号登录
`q.evageek.com`	asynqmon 任务队列 UI	建议加 basic_auth
`evageek.com` / `www`	本白皮书	Public

快速接入

下面是把店铺接进 TKstore 的最小步骤。

1. 健康检查

# 验证服务可达
curl https://tk.evageek.com/healthz
# → ok

2. 发起店铺授权

# 浏览器打开授权入口，TikTok Shop 完成授权后回调 TKstore
open https://tk.evageek.com/oauth/shop/start

# 回调 URL (TikTok 后台填写)
https://tk.evageek.com/oauth/shop/callback

3. 拉取店铺列表

curl https://tk.evageek.com/api/shops

# 响应示例
{
  "shops": [
    { "id": 1, "name": "Demo Shop", "region": "us", "connected_at": "2026-04-23T01:00:00Z" }
  ]
}

4. 查看指标

curl https://tk.evageek.com/api/shops/1/metrics

OAuth 接入

TKstore 实现了 TikTok Shop 与 Developer Display 两条 OAuth 流程。Token (access / refresh) 经 AES-256 加密入库，绝不出现在日志中。

Shop OAuth

GET

/oauth/shop/start

生成 state、跳转到 TikTok Shop 授权页。

GET

/oauth/shop/callback?code=...&state=...

TikTok 回调；交换 access_token + refresh_token，加密入库，建立 shop 记录。

Display OAuth

GET

/oauth/display/start

用户登录授权入口，scopes: user.info.basic, user.info.profile, user.info.stats, video.list。

GET

/oauth/display/callback?code=...&state=...

回调换 token，落库后跳转回前端。

密钥管理

Token 加密: AES-256 (32 字节十六进制 key，存于 config 不入仓)
Refresh 时机: scheduler 周期检查，过期前 10 分钟主动刷新
State 校验: Redis 5 分钟一次性 token，防 CSRF

Webhook

TKstore 接收两类官方事件，落 asynq 队列异步处理，避免阻塞 TikTok 重试。

POST

/webhook/developer

Developer (Display / Content Posting) 事件：粉丝变动、视频审核结果、点赞数据。签名校验通过 client_secret。

POST

/webhook/shop

Shop 事件：订单状态、退款、商品审核、库存。多区域路由按 shop_id → region。

TikTok 后台填写

# Developer Console
Callback URL: https://tk.evageek.com/oauth/display/callback
Webhook URL : https://tk.evageek.com/webhook/developer

# Shop Partner Center
Redirect URI: https://tk.evageek.com/oauth/shop/callback
Webhook URL : https://tk.evageek.com/webhook/shop

REST API 索引

所有 endpoint base = https://tk.evageek.com。

Method	Path	说明
GET	`/healthz`	存活探针，返回 `ok`
GET	`/oauth/shop/start`	启动 Shop 授权
GET	`/oauth/shop/callback`	Shop 授权回调
GET	`/oauth/display/start`	启动 Display 授权
GET	`/oauth/display/callback`	Display 授权回调
POST	`/webhook/developer`	Developer 事件接收
POST	`/webhook/shop`	Shop 事件接收
GET	`/api/shops`	已授权店铺列表
GET	`/api/shops/:id/metrics`	店铺指标聚合

运维入口

以下为内部运维命令，仅供 SRE 参考。

LA 边缘 (23.224.189.188:57978)

systemctl reload caddy
journalctl -u caddy -f
tailscale status

Core (10.10.10.30:22)

systemctl restart tkstore-api tkstore-worker tkstore-scheduler
tail -f /var/log/tkstore-api.log
docker compose -f /opt/tkstore/deploy/docker-compose.yml ps
PGPASSWORD=tkstore psql -h 127.0.0.1 -U tkstore -d tkstore

常用面板

BI 看板: https://bi.evageek.com
队列监控: https://q.evageek.com
API 健康: https://tk.evageek.com/healthz

FAQ

为什么需要 Tailscale？

核心机在国内 IDC，TikTok 出站需要走海外。LA 机做 exit node + caddy 入口，核心机所有外发流量经过 Tailscale mesh，避免暴露公网且统一出口 IP。

首次请求为什么有 5–8 秒延迟？

首请求触发 Tailscale DERP 握手；建连后稳定在 0.3–0.5 秒。可通过定时心跳保活。

Webhook 多久重试一次？

TKstore 入库即返 200，重试由 TikTok 侧策略决定。处理失败的事件由 asynq retry 链路兜底，最多 10 次指数退避。

Token 过期怎么办？

scheduler 每分钟扫描快过期 token，提前 10 分钟换新；失败回退到下次拉数时按需刷新。