# cryptotrader

**Repository Path**: hylaz/cryptotrader

## Basic Information

- **Project Name**: cryptotrader
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: spot
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-15
- **Last Updated**: 2026-01-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CryptoTrader

一个基于 Go 语言开发的加密货币自动交易系统，支持多交易所统一管理、策略回测、实时交易等功能。

## 目录

- [快速开始](#快速开始)
- [主要功能](#主要功能)
- [交易所支持](#交易所支持)
- [架构设计](#架构设计)
- [开发指南](#开发指南)
- [命令行工具](#命令行工具)
- [文档](#文档)
- [许可证](#许可证)

## 快速开始

### 前置要求

- Go 1.25 或更高版本
- PostgreSQL 数据库（可选，用于历史数据存储）

### 安装

**Linux/macOS:**

```bash
git clone https://github.com/hylaz/cryptotrader.git
cd cryptotrader
go build
mkdir ~/.gocryptotrader
cp config_example.json ~/.gocryptotrader/config.json
./cryptotrader
```

**使用 Docker:**

```bash
docker-compose up -d
```

### 高级构建选项

**启用 Sonic JSON（提升性能）：**

```bash
go build -tags=sonic_on
```

**启用开发模式：**

```bash
go build -tags=dev
```

## 主要功能

### 核心交易功能

- **多交易所支持** - 统一 API 管理多个交易所账户，支持交易所多实例
- **完整的订单管理** - 下单、撤单、查询订单状态、订单历史
- **投资组合管理** - 实时跟踪所有交易所的资产余额和持仓
- **事件驱动系统** - 灵活的事件触发和处理机制
- **数据历史记录** - 保存和查询历史交易数据（K线、成交、订单等）

### 技术特性

- **FX 框架集成** - 使用 Uber FX 进行依赖注入和生命周期管理
- **分阶段启动** - 按依赖关系分阶段启动子系统
- **gRPC 服务** - 独立的 RPC 包，支持远程控制和代理
- **WebSocket 支持** - 实时市场数据推送和订单更新
- **REST API** - 完整的交易所 REST API 封装
- **数据库支持** - PostgreSQL 支持（使用 GORM + pgx）
- **脚本系统** - gctscript 基于 Tengo 虚拟机，支持自定义交易策略
- **回测引擎** - 独立的回测工具，支持历史数据验证策略

### 安全与管理

- AES256 配置文件加密
- OTP 双因素认证支持
- HTTP 代理和用户代理自定义
- 连接监控和自动重连
- NTP 时间同步
- 请求速率限制

## 交易所支持

项目支持 30+ 主流加密货币交易所：

| 交易所 | REST API | WebSocket | 多实例支持 |
|--------|----------|-----------|------------|
| Binance | ✅ | ✅ | ✅ |
| Binance.US | ✅ | ✅ | ✅ |
| OKX (Okx) | ✅ | ✅ | ✅ |
| Bybit | ✅ | ✅ | ✅ |
| Huobi | ✅ | ✅ | ✅ |
| Gate.io | ✅ | ✅ | ✅ |
| Kucoin | ✅ | ✅ | ✅ |
| Bitfinex | ✅ | ✅ | ✅ |
| Kraken | ✅ | ✅ | ✅ |
| Coinbase | ✅ | ✅ | ❌ |
| Bitstamp | ✅ | ✅ | ❌ |
| Gemini | ✅ | ✅ | ❌ |
| HitBTC | ✅ | ✅ | ❌ |
| Poloniex | ✅ | ✅ | ✅ |
| BitMEX | ✅ | ✅ | ✅ |
| Deribit | ✅ | ✅ | ❌ |
| BTSE | ✅ | ✅ | ✅ |
| Bithumb | ✅ | ✅ | ✅ |
| BTC Markets | ✅ | ✅ | ✅ |
| COINUT | ✅ | ✅ | ✅ |
| Exmo | ✅ | ❌ | ✅ |
| Bitflyer | ✅ | ❌ | ✅ |
| Lbank | ✅ | ❌ | ✅ |
| Yobit | ✅ | ❌ | ✅ |

> 查看完整列表和详细说明：[交易所文档](docs/exchange/README.md)

## 架构设计

### 项目结构

```
cryptotrader/
├── container/           # FX 依赖注入容器（统一入口）
│   └── subsystems/      # 子系统提供者
├── engine/              # 核心引擎 - 各子系统 FX 模块
│   ├── *_fx.go         # 各子系统的 FX 提供者
│   ├── *_manager.go    # 各子系统管理器
│   └── types.go        # 核心类型定义
├── rpc/                 # gRPC 服务器实现（独立包）
│   ├── account.go       # 账户相关 RPC
│   ├── config.go        # 配置相关 RPC
│   ├── exchange_*.go    # 交易所相关 RPC
│   └── server.go        # gRPC 服务器
├── gctrpc/              # gRPC 协议定义（protobuf）
├── exchanges/           # 交易所实现
├── backtester/          # 回测引擎
├── gctscript/           # 脚本系统
├── database/            # 数据库层
│   ├── drivers/postgres/ # PostgreSQL 驱动
│   ├── migrations/       # 数据库迁移文件
│   └── repository/       # 数据访问层
├── config/              # 配置管理
├── portfolio/           # 投资组合管理
├── dispatch/            # 任务分发系统
├── log/                 # 日志系统
├── currency/            # 货币处理
├── types/               # 通用类型定义
├── communications/      # 通信模块
├── connchecker/         # 连接检查
├── signaler/            # 信号处理
├── core/                # 核心常量和版本
└── cmd/                 # 命令行工具
    ├── gctcli/          # gRPC 客户端
    ├── dbmigrate/       # 数据库迁移工具
    ├── dbseed/          # 数据库种子数据
    ├── config_builder/  # 配置构建工具
    └── exchange/        # 交易所工具
```

### 关键架构特性

#### 1. FX 依赖注入框架

项目使用 Uber FX 框架进行依赖注入和生命周期管理：

- **统一入口**: `container/app.go` 创建 FX 应用
- **分阶段启动**: 子系统按依赖关系分 5 个阶段启动
- **生命周期管理**: 通过 FX 的 OnStart/OnStop 管理子系统启停

#### 2. 分阶段启动架构

```
阶段 0: 基础设施（日志、配置、数据库连接）
阶段 1: 独立子系统（NTP、连接管理、通信管理）
阶段 2: 中等复杂度（交易所管理器、同步管理器）
阶段 3: 复杂子系统（订单管理器、事件管理器、组合管理器）
阶段 4: 交易所服务层
阶段 5: RPC 服务层
```

#### 3. 独立 RPC 包

- `rpc/` 包包含完整的 gRPC 服务实现
- 避免与 engine 包的循环依赖
- 通过 `service_bridge.go` 连接引擎服务

#### 4. 数据库架构

- 仅支持 PostgreSQL
- 使用 GORM 作为 ORM
- 使用 pressly/goose 管理迁移
- 使用 pgx/v5 作为底层驱动

详细架构文档：
- [RPC 架构](docs/grpc/rpc-architecture.md)
- [交易所架构](docs/exchange/multi-instance-architecture.md)

## 开发指南

### 前置要求

- Go 1.25+
- PostgreSQL（用于数据库功能）
- Make（可选，用于构建任务）

### 项目设置

```bash
# 克隆仓库
git clone https://github.com/hylaz/cryptotrader.git
cd cryptotrader

# 安装依赖
go mod download

# 运行测试
go test ./...

# 构建
go build
```

### 编码规范

1. **代码格式**
   - 使用 `gofmt` 格式化代码
   - 遵循 [Effective Go](https://go.dev/doc/effective_go)
   - 遵循 [Go Style Guide](https://google.github.io/styleguide/go/)

2. **命名约定**
   - 请求结构体: `XxxRequest`
   - 响应结构体: `XxxResponse`
   - 使用指针传递请求/响应结构体

3. **类型使用**
   - 整数: `uint64`
   - 时间戳: `time.Time` 或 `types.Time`
   - 数值: `types.Number` 或 `float64`
   - 高精度计算: `shopspring/decimal`

4. **FX 模块规范**
   - 每个子系统需提供 `*_fx.go` 文件
   - 使用 `fx.Annotate` 标注依赖
   - 实现 `OnStart` 和 `OnStop` 生命周期

### 添加新子系统

1. 在 `engine/` 创建子系统的 FX 模块
2. 在 `container/subsystems/` 添加提供者
3. 根据依赖关系放入对应阶段
4. 在 `container/container.go` 中注册

### 数据库开发

```bash
# 创建新迁移
go run ./cmd/dbmigrate/main.go -config config.json -command create add_new_table sql

# 运行迁移
go run ./cmd/dbmigrate/main.go -config config.json -command up

# 生成 ORM 模型
sqlboiler -c sqlboiler.json
```

## 命令行工具

### gctcli - gRPC 客户端

```bash
# 构建客户端
cd cmd/gctcli
go build

# 查看账户信息
./gctcli account info

# 查询订单
./gctcli order list --exchange binance

# 管理配置
./gctcli config get
./gctcli config set remotecontrol.grpc.enabled true
```

### 其他工具

```bash
# 数据库迁移
go run ./cmd/dbmigrate/main.go -config config.json -command up

# 数据库种子数据
go run ./cmd/dbseed/main.go -config config.json

# 生成 OTP
go run ./cmd/gen_otp/main.go

# 配置构建
go run ./cmd/config_builder/main.go

# 交易所工具
go run ./cmd/exchange/main.go
```

## 文档

### 快速入门

- [配置指南](docs/configuration_guide.md) - 配置文件详解
- [gctcli 使用](docs/gctcli.md) - 命令行客户端教程
- [gctscript 教程](docs/gctscript.md) - 脚本编写指南

### 开发文档

- [AI Agent 开发指南](AGENTS.md) - 供 AI 助手使用的开发指南
- [数据库操作指南](docs/database/database_guide.md) - 数据库迁移、Model 生成、Repository 实现标准流程
- [Makefile 命令参考](docs/Makefile.md) - Makefile 命令完整参考
- [编码规范](docs/coding_guidelines.md)
- [添加新交易所](docs/exchange/add_new_exchange.md)
- [交易所 API 设计](docs/exchange/api-design.md)
- [回测器文档](docs/backtester/README.md)

### 架构文档

- [RPC 架构](docs/grpc/rpc-architecture.md) - RPC 服务设计
- [交易所架构](docs/exchange/multi-instance-architecture.md) - 多实例架构
- [数据库配置](docs/exchange/database-configuration-guide.md)

## 技术栈

| 类别 | 技术 |
|------|------|
| 语言 | Go 1.25 |
| 依赖注入 | Uber FX |
| RPC | gRPC + gRPC-Gateway |
| 数据库 | PostgreSQL (GORM + pgx/v5) |
| WebSocket | Gorilla WebSocket |
| 配置管理 | Viper |
| 脚本引擎 | Tengo |
| 日志 | Zap |
| 迁移工具 | pressly/goose/v3 |
| 技术分析 | gct-ta |

## 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件