mirror of
https://github.com/exchanges-lab/tradesync.git
synced 2026-08-05 05:06:07 +08:00
0xcathiefish
bba06206ab
- Add README_CN.md as a full Chinese translation of README.md - Add a Notion Template & Preview section with the database template link, collapsible preview screenshots, and a note on the companion TradeSnap service that provides the TradingView screenshots - Add a Deployment section documenting Docker Compose (recommended) and local build - Use relative links so they resolve on GitHub - Drop the Code Example and Requirements sections and renumber Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
163 lines
7.6 KiB
Markdown
163 lines
7.6 KiB
Markdown
# tradesync
|
||
|
||
一个高效、解耦的 Hyperliquid 钱包持仓监控与 Notion 数据库记录工具。
|
||
|
||
> English version: [README.md](./README.md)
|
||
|
||
## 1. 简介
|
||
`tradesync` 是一个基于 Rust 构建的实时钱包持仓监控与分析工具。它通过 WebSocket 订阅指定的 Hyperliquid 钱包地址，实时捕获开仓交易，将单个订单的多笔分批成交（基于 500ms 防抖聚合机制）合并聚合，并自动将格式化后的交易数据同步到 Notion 数据库。
|
||
|
||
## 2. 核心特性
|
||
* **实时钱包订阅**：使用 `hyperliquid-rust-sdk` 与钱包的 `UserEvents` 建立持久化 WebSocket 连接，以毫秒级延迟感知持仓变化。
|
||
* **基于 `oid` 的成交聚合**：将同一订单（`oid`）在 500ms 窗口内的多笔分批成交聚合为一行统一记录，避免拆单产生重复的数据库条目。
|
||
* **开仓事件捕获**：通过校验起始仓位（`start_position`）是否为零来识别开仓动作。目前仅捕获开仓（忽略平仓，以规避拆单的复杂性）。
|
||
* **订单类型识别**：自动识别订单执行类型（taker 成交 `crossed == true` 记为 `MARKET`，maker 成交 `crossed == false` 记为 `LIMIT`）。
|
||
* **健壮的重连机制**：实现了健壮的连接循环，在网络抖动或 WebSocket 断开后自动重连。
|
||
* **Notion 集成**：集成 `notion-client` API，将结构化数据行（`Symbol`、`Quantity`、`Filled Price`、`Direction`、`Exchange`、`DataTime`、`Order ID`、`Order Type`、`Check`）直接写入目标 Notion 数据库。
|
||
|
||
## 3. Notion 模板与效果预览
|
||
本项目向 Notion 数据库写入数据，你需要先准备一个字段结构匹配的数据库。可直接复制官方模板（点击右上角 **Duplicate** 即可一键复制到你的工作区）：
|
||
|
||
> 📋 **Notion 数据库模板**：<https://annafish.notion.site/2026-2e08f81ac37080c6a474f00373d13287>
|
||
|
||
复制后，将该数据库的 ID 填入 `.env` 的 `NOTION_DATABASE_ID`，并把你的 Notion 集成（integration）连接到该页面即可。
|
||
|
||
<details>
|
||
<summary>🗂️ Notion 数据库示例页面（点击展开）</summary>
|
||
|
||
<img src="https://img.cathiefish.art/github/tradesync/tradesync1.png" width="720" alt="tradesync 数据库示例" />
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>📜 单条记录页完整长截图（点击展开）</summary>
|
||
|
||
<img src="https://img.cathiefish.art/github/tradesync/tradesync2.png" width="420" alt="tradesync 记录页示例" />
|
||
|
||
</details>
|
||
|
||
|
||
> 🖼️ **关于记录页里的 TradingView 实时截图**
|
||
> 记录页中多周期（15m / 1h / 4h / 1D）的 TradingView 实时截图，并非由 `tradesync` 自身生成，而是由配套服务 **TradeSnap**（独立仓库：<https://github.com/exchanges-lab/tradesnap>）负责。`tradesync` 在写入 Notion 后，通过 `TRADESNAP_URL` 调用 TradeSnap 拉取截图并追加到对应页面。
|
||
> 该功能为可选项，由 `ENABLE_SCREENSHOT` 控制；关闭时 `tradesync` 仅写入交易数据行，不依赖 TradeSnap。
|
||
|
||
## 4. 架构与模块
|
||
目录结构与模块说明如下：
|
||
|
||
```
|
||
tradesync/
|
||
├── src/
|
||
│ ├── lib.rs # 统一模块导出
|
||
│ ├── structs.rs # 数据模型与事件定义（如 NotionRowData）
|
||
│ ├── hyperliquid.rs # Hyperliquid WebSocket 监控实现
|
||
│ └── notion.rs # Notion 数据库写入实现
|
||
├── examples/ # 开发示例
|
||
│ ├── demo.rs # 实时钱包监控示例
|
||
│ └── fetch_notion_db.rs # 用于获取 Notion 数据库 schema 属性的开发脚本
|
||
├── tests/ # 集成测试与单元测试
|
||
│ └── monitor_test.rs # 监控连通性与重连循环测试
|
||
├── references/ # 本地参考子模块
|
||
├── docker-compose.yml # Docker Compose 部署编排
|
||
├── Dockerfile # 容器镜像构建文件
|
||
├── .env # 本地环境变量配置（已被 git 忽略）
|
||
├── .env.example # 环境变量配置模板
|
||
├── Cargo.toml # Cargo 包文件，含远程 Git 依赖
|
||
└── CHANGELOG.md # 变更日志
|
||
```
|
||
|
||
* **HyperliquidMonitor**（`src/hyperliquid.rs`）：长期运行的服务，维护与 Hyperliquid API 的 WebSocket 连接，并发出聚合后的交易事件。
|
||
* **NotionWriter**（`src/notion.rs`）：将捕获到的数据行格式化并写入 Notion 数据库。
|
||
* **structs**（`src/structs.rs`）：定义 `PositionTradeEvent`、`NotionRowData` 等数据模型。
|
||
|
||
## 5. 部署
|
||
|
||
### 方式一：Docker Compose（推荐）
|
||
项目已提供 `docker-compose.yml`，直接拉取预构建镜像 `ghcr.io/exchanges-lab/tradesync:latest` 运行，无需本地安装 Rust 工具链。
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/cathiefish/tradesync.git
|
||
cd tradesync
|
||
|
||
# 复制并配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env，填入 WALLET_ADDRESS、NOTION_API_KEY、NOTION_DATABASE_ID 等
|
||
|
||
# compose 使用了一个名为 cycle 的外部网络，首次部署需先创建
|
||
docker network create cycle
|
||
|
||
# 拉取最新镜像并后台启动
|
||
docker compose pull
|
||
docker compose up -d
|
||
|
||
# 查看实时日志
|
||
docker compose logs -f
|
||
|
||
# 停止并移除容器
|
||
docker compose down
|
||
```
|
||
|
||
> **说明**
|
||
> - `docker-compose.yml` 中的服务接入外部网络 `cycle`，便于与同网络下的其他服务（如截图服务 `tradesnap`）通信。若启用截图功能，请将 `TRADESNAP_URL` 设为该网络内可达地址（默认 `http://tradesnap:8003`）。
|
||
> - 容器配置了 `restart: unless-stopped`，宿主机重启后会自动拉起。
|
||
|
||
### 方式二：本地构建运行
|
||
适合开发调试或自行构建二进制：
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/cathiefish/tradesync.git
|
||
cd tradesync
|
||
|
||
# 复制并配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，填入你的 WALLET_ADDRESS、Notion 集成 token 与数据库 ID
|
||
|
||
# 构建项目
|
||
cargo build --release
|
||
|
||
# 运行监控同步服务
|
||
cargo run
|
||
|
||
# 运行本地监控示例
|
||
cargo run --example demo
|
||
```
|
||
|
||
## 6. 环境变量
|
||
| 变量 | 说明 | 是否必填 | 默认值 / 示例值 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `WALLET_ADDRESS` | 要监控的 Ethereum/Hyperliquid 钱包地址 | **是** | `0xc64cc00b46101bd40aa1c3121195e85c0b0918d8` |
|
||
| `IS_TESTNET` | 连接 Hyperliquid 测试网（`true`/`false`） | 否 | `true` |
|
||
| `NOTION_API_KEY` | Notion 集成 token（内部密钥） | **是** | `secret_xxxxxx...` |
|
||
| `NOTION_DATABASE_ID` | Notion 数据库 ID | **是** | `2b08f81ac37083389c5c01242f3c1557` |
|
||
| `RUST_LOG` | 日志详细级别（error、warn、info、debug） | 否 | `info` |
|
||
| `ENABLE_SCREENSHOT` | 在 Notion 页面中启用 TradingView 图表截图（`true`/`false`） | 否 | `false` |
|
||
| `TRADESNAP_URL` | TradeSnap 服务的 API 端点 URL | 否 | `http://tradesnap:8003` |
|
||
| `BTCUSDT_SNAPSHOT` | 截图使用币安 USDT 合约（`true`）而非 USDC 合约（`false`） | 否 | `false` |
|
||
| `SYMBOL_15M_SNAPSHOT` | 捕获并插入 15m 周期截图（`true`/`false`） | 否 | `false` |
|
||
| `SYMBOL_1H_SNAPSHOT` | 捕获并插入 1h 周期截图（`true`/`false`） | 否 | `false` |
|
||
| `SYMBOL_4H_SNAPSHOT` | 捕获并插入 4h 周期截图（`true`/`false`） | 否 | `false` |
|
||
| `SYMBOL_1D_SNAPSHOT` | 捕获并插入 1D 周期截图（`true`/`false`） | 否 | `false` |
|
||
|
||
|
||
## 7. 开发与测试
|
||
### Git 分支策略
|
||
* `dev`：活跃开发分支。新功能与修复先合并到此分支。
|
||
* `main`：稳定的生产可用分支。
|
||
|
||
### 本地质量检查
|
||
在提交 Pull Request 之前，你**必须**运行：
|
||
```bash
|
||
# 自动格式化代码库
|
||
cargo fmt --all
|
||
|
||
# 运行 lint 检查
|
||
cargo clippy --all-targets --all-features -- -D warnings
|
||
|
||
# 执行测试套件
|
||
cargo test
|
||
```
|
||
|
||
## 8. 变更日志
|
||
有关项目更新的详细记录，请参阅 [CHANGELOG.md](./CHANGELOG.md)。
|