1100 lines
29 KiB
Markdown
1100 lines
29 KiB
Markdown
# M2Pool Payment System v2
|
||
|
||
<div align="center">
|
||
|
||
**基于区块链的分布式支付系统**
|
||
|
||
[](https://golang.org)
|
||
[](https://ethereum.org)
|
||
[](https://www.rabbitmq.com)
|
||
[](https://www.mysql.com)
|
||
|
||
支持 **充值**、**提现**、**支付** 三大核心功能，实时监听链上交易，自动确认到账。
|
||
|
||
[快速开始](#快速开始) • [功能特性](#功能特性) • [架构设计](#架构设计) • [API 文档](#api-文档)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
- [项目简介](#项目简介)
|
||
- [功能特性](#功能特性)
|
||
- [架构设计](#架构设计)
|
||
- [快速开始](#快速开始)
|
||
- [配置说明](#配置说明)
|
||
- [使用示例](#使用示例)
|
||
- [API 文档](#api-文档)
|
||
- [开发指南](#开发指南)
|
||
- [部署指南](#部署指南)
|
||
- [性能指标](#性能指标)
|
||
- [常见问题](#常见问题)
|
||
- [贡献指南](#贡献指南)
|
||
- [许可证](#许可证)
|
||
|
||
---
|
||
|
||
## 项目简介
|
||
|
||
M2Pool Payment System v2 是一个基于以太坊区块链的**分布式支付解决方案**，提供完整的数字货币充值、提现、支付功能。
|
||
|
||
### 核心能力
|
||
|
||
- 🔍 **实时监听**：订阅链上事件，实时检测 USDT 转账
|
||
- ⚡ **快速确认**：20 个区块确认，约 4-5 分钟到账
|
||
- 🔒 **安全可靠**：私钥加密存储，签名验证机制
|
||
- 📊 **高并发**：支持少量并发（50-200 TPS）
|
||
- 🔄 **自动重连**：WebSocket 断开自动重连
|
||
- 📨 **消息队列**：基于 RabbitMQ 的异步通信
|
||
|
||
### 技术栈
|
||
|
||
| 组件 | 技术 | 版本 |
|
||
|------|------|------|
|
||
| **语言** | Go | 1.24+ |
|
||
| **区块链** | Ethereum | go-ethereum v1.16.4 |
|
||
| **消息队列** | RabbitMQ | amqp091-go v1.10.0 |
|
||
| **数据库** | MySQL | 8.0+ |
|
||
| **网络协议** | WebSocket + RPC | - |
|
||
|
||
---
|
||
|
||
## 功能特性
|
||
|
||
### 1. 充值功能 💰
|
||
|
||
```
|
||
用户转账 → 实时检测 → 待确认通知 → 区块确认 → 最终通知
|
||
```
|
||
|
||
**特点：**
|
||
- ✅ 实时检测到账
|
||
- ✅ 发送**两次**通知：待确认 + 最终确认
|
||
- ✅ 支持多币种（当前支持 USDT）
|
||
- ✅ 自动地址监听管理
|
||
|
||
**消息流：**
|
||
1. 业务系统发送充值请求 → RabbitMQ
|
||
2. 系统添加地址监听
|
||
3. 用户转账 → 立即通知（status=2 待确认）
|
||
4. 等待 20 个区块 → 最终通知（status=1 成功 / 0 失败）
|
||
|
||
---
|
||
|
||
### 2. 提现功能 💸
|
||
|
||
```
|
||
提现请求 → 验证余额 → 发送交易 → 等待确认 → 返回结果
|
||
```
|
||
|
||
**特点：**
|
||
- ✅ 自动余额检查
|
||
- ✅ 余额不足时使用归集钱包
|
||
- ✅ 发送**一次**通知：最终确认
|
||
- ✅ Gas 费用检查
|
||
|
||
**消息流：**
|
||
1. 业务系统发送提现请求 → RabbitMQ
|
||
2. 系统验证余额并发送交易
|
||
3. 等待 20 个区块确认
|
||
4. 返回结果（status=1 成功 / 0 失败）
|
||
|
||
---
|
||
|
||
### 3. 支付功能 💳
|
||
|
||
```
|
||
支付请求 → 验证余额 → 发送交易 → 等待确认 → 返回结果
|
||
```
|
||
|
||
**特点：**
|
||
- ✅ 订单关联
|
||
- ✅ 自动余额检查
|
||
- ✅ 发送**一次**通知：最终确认
|
||
- ✅ 支持商户收款
|
||
|
||
**消息流：**
|
||
1. 业务系统发送支付请求（含订单ID）→ RabbitMQ
|
||
2. 系统验证余额并发送交易
|
||
3. 等待 20 个区块确认
|
||
4. 返回结果（status=1 成功 / 0 失败）
|
||
|
||
---
|
||
|
||
## 架构设计
|
||
|
||
### 系统架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 业务系统 │
|
||
│ (Web/App/API Server) │
|
||
└────────────┬────────────────────────────┬───────────────────┘
|
||
│ │
|
||
│ 请求 │ 响应
|
||
↓ ↑
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ RabbitMQ │
|
||
│ ┌─────────┐ ┌──────────┐ ┌────────┐ │
|
||
│ │ topup │ │ withdraw │ │ pay │ 请求队列 │
|
||
│ └─────────┘ └──────────┘ └────────┘ │
|
||
│ ┌─────────┐ ┌──────────┐ ┌────────┐ │
|
||
│ │topup_ │ │withdraw_ │ │ pay_ │ 响应队列 │
|
||
│ │ resp │ │ resp │ │ resp │ │
|
||
│ └─────────┘ └──────────┘ └────────┘ │
|
||
└────────────┬────────────────────────────┬───────────────────┘
|
||
│ │
|
||
↓ ↑
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ M2Pool Payment System v2 │
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ RabbitMQ │ │ Blockchain │ │ Database │ │
|
||
│ │ Consumer │─>│ Manager │─>│ (MySQL) │ │
|
||
│ └──────────────┘ └──────┬───────┘ └──────────────┘ │
|
||
│ │ │
|
||
│ │ WebSocket + RPC │
|
||
└────────────────────────────┼─────────────────────────────────┘
|
||
│
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 以太坊区块链网络 │
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ 新区块 │ │ USDT Transfer │ │
|
||
│ │ (NewHead) │ │ 事件 │ │
|
||
│ └──────────────┘ └──────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 核心模块
|
||
|
||
#### 1. Blockchain Manager (blockchain/)
|
||
- **eth/eth.go**：以太坊节点交互
|
||
- 监听 USDT Transfer 事件
|
||
- 监听新区块产生
|
||
- 管理待确认交易池
|
||
- 执行 ERC20 转账
|
||
|
||
#### 2. Message Queue (queue/)
|
||
- **rabbitmq.go**：消息队列服务
|
||
- 消费充值/提现/支付请求
|
||
- 发布交易确认响应
|
||
- 自动重连机制
|
||
|
||
#### 3. Database (db/)
|
||
- **db.go**：数据库连接池
|
||
- 存储钱包私钥（加密）
|
||
- 存储交易记录
|
||
|
||
#### 4. Message (msg/)
|
||
- **msg.go**：消息结构定义
|
||
- 请求消息结构
|
||
- 响应消息结构
|
||
- 配置结构
|
||
|
||
#### 5. Utils (utils/)
|
||
- **utils.go**：工具函数
|
||
- 数值转换
|
||
- 加密解密
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 前置条件
|
||
|
||
- ✅ Go 1.24 或更高版本
|
||
- ✅ MySQL 8.0+
|
||
- ✅ RabbitMQ 3.x+
|
||
- ✅ 以太坊节点（支持 WebSocket 和 RPC）
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone <repository-url>
|
||
cd m2pool-payment-v2
|
||
|
||
# 2. 安装依赖
|
||
go mod download
|
||
|
||
# 3. 创建数据库
|
||
mysql -u root -p < schema.sql
|
||
|
||
# 4. 配置文件
|
||
cp test/config.example.json test/config.json
|
||
# 编辑 config.json，填入实际配置
|
||
|
||
# 5. 编译
|
||
go build -o m2pool-payment cmd/main.go
|
||
|
||
# 6. 运行
|
||
./m2pool-payment
|
||
|
||
# 或者直接运行测试
|
||
cd test
|
||
go run test.go
|
||
```
|
||
|
||
---
|
||
|
||
## 配置说明
|
||
|
||
### 配置文件结构 (config.json)
|
||
|
||
```json
|
||
{
|
||
"rmq_config": {
|
||
"sub_addr": "amqp://username:password@localhost:5672",
|
||
"pay": {
|
||
"queue": "pay.auto.queue",
|
||
"exchange": "pay.exchange",
|
||
"routing": ["pay.auto.routing.key"]
|
||
},
|
||
"topup": {
|
||
"queue": "pay.recharge.queue",
|
||
"exchange": "pay.exchange",
|
||
"routing": ["pay.recharge.routing.key"]
|
||
},
|
||
"withdraw": {
|
||
"queue": "pay.withdraw.queue",
|
||
"exchange": "pay.exchange",
|
||
"routing": ["pay.withdraw.routing.key"]
|
||
},
|
||
"pay_resp": {
|
||
"queue": "pay.auto.return.queue",
|
||
"exchange": "pay.exchange",
|
||
"routing": ["pay.auto.return.routing.key"]
|
||
},
|
||
"topup_resp": {
|
||
"queue": "pay.recharge.return.queue",
|
||
"exchange": "pay.exchange",
|
||
"routing": ["pay.recharge.return.routing.key"]
|
||
},
|
||
"withdraw_resp": {
|
||
"queue": "pay.withdraw.return.queue",
|
||
"exchange": "pay.exchange",
|
||
"routing": ["pay.withdraw.return.routing.key"]
|
||
}
|
||
},
|
||
"eth_config": {
|
||
"rpcUrl": "http://localhost:8545",
|
||
"wsUrl": "ws://localhost:8546",
|
||
"confirmHeight": 20,
|
||
"dbConfig": {
|
||
"user": "root",
|
||
"password": "your_password",
|
||
"host": "127.0.0.1",
|
||
"port": 3306,
|
||
"database": "payment",
|
||
"maxOpenConns": 20,
|
||
"maxIdleCoons": 20,
|
||
"connMaxLife": 120
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 配置项说明
|
||
|
||
| 配置项 | 说明 | 默认值 | 必填 |
|
||
|--------|------|--------|------|
|
||
| `rmq_config.sub_addr` | RabbitMQ 连接地址 | - | ✅ |
|
||
| `eth_config.rpcUrl` | 以太坊 RPC 地址 | - | ✅ |
|
||
| `eth_config.wsUrl` | 以太坊 WebSocket 地址 | - | ✅ |
|
||
| `eth_config.confirmHeight` | 确认区块数 | 20 | ✅ |
|
||
| `dbConfig.user` | 数据库用户名 | root | ✅ |
|
||
| `dbConfig.password` | 数据库密码 | - | ✅ |
|
||
| `dbConfig.database` | 数据库名称 | payment | ✅ |
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 1. 充值流程
|
||
|
||
**步骤 1：业务系统发送充值请求**
|
||
|
||
发送到 RabbitMQ 队列：`pay.recharge.queue`
|
||
|
||
```json
|
||
{
|
||
"chain": "ETH",
|
||
"symbol": "USDT",
|
||
"address": "0x4e5b2e1dc63f6b91cb6cd759936495434c7e972f",
|
||
"timestamp": 1758610297,
|
||
"sign": "signature_hash"
|
||
}
|
||
```
|
||
|
||
**步骤 2：用户转账**
|
||
|
||
用户向指定地址转账 USDT
|
||
|
||
**步骤 3：接收通知**
|
||
|
||
从 RabbitMQ 队列：`pay.recharge.return.queue` 接收**两次**消息：
|
||
|
||
第一次（待确认）：
|
||
```json
|
||
{
|
||
"address": "0x4e5b2e1dc63f6b91cb6cd759936495434c7e972f",
|
||
"status": 2,
|
||
"chain": "ETH",
|
||
"symbol": "USDT",
|
||
"amount": 100.5,
|
||
"tx_hash": "0xabc..."
|
||
}
|
||
```
|
||
|
||
第二次（最终确认）：
|
||
```json
|
||
{
|
||
"address": "0x4e5b2e1dc63f6b91cb6cd759936495434c7e972f",
|
||
"status": 1,
|
||
"chain": "ETH",
|
||
"symbol": "USDT",
|
||
"amount": 100.5,
|
||
"tx_hash": "0xabc..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 提现流程
|
||
|
||
**步骤 1：业务系统发送提现请求**
|
||
|
||
发送到 RabbitMQ 队列：`pay.withdraw.queue`
|
||
|
||
```json
|
||
{
|
||
"queue_id": "withdraw_123",
|
||
"from_address": "0x1111...",
|
||
"to_address": "0x2222...",
|
||
"amount": 50.0,
|
||
"chain": "ETH",
|
||
"symbol": "USDT",
|
||
"timestamp": 1758610297,
|
||
"sign": "signature_hash"
|
||
}
|
||
```
|
||
|
||
**步骤 2：系统处理**
|
||
|
||
- 验证签名
|
||
- 检查余额
|
||
- 发送链上交易
|
||
- 等待确认
|
||
|
||
**步骤 3：接收通知**
|
||
|
||
从 RabbitMQ 队列：`pay.withdraw.return.queue` 接收**一次**消息：
|
||
|
||
```json
|
||
{
|
||
"queue_id": "withdraw_123",
|
||
"status": 1,
|
||
"amount": 50.0,
|
||
"chain": "ETH",
|
||
"symbol": "USDT",
|
||
"tx_hash": "0xdef..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 支付流程
|
||
|
||
**步骤 1：业务系统发送支付请求**
|
||
|
||
发送到 RabbitMQ 队列：`pay.auto.queue`
|
||
|
||
```json
|
||
{
|
||
"queue_id": "pay_456",
|
||
"from_address": "0x1111...",
|
||
"to_address": "0x3333...",
|
||
"amount": 200.0,
|
||
"chain": "ETH",
|
||
"symbol": "USDT",
|
||
"order_id": "order_789",
|
||
"timestamp": 1758610297,
|
||
"sign": "signature_hash"
|
||
}
|
||
```
|
||
|
||
**步骤 2：系统处理**
|
||
|
||
- 验证签名
|
||
- 检查余额
|
||
- 发送链上交易
|
||
- 等待确认
|
||
|
||
**步骤 3：接收通知**
|
||
|
||
从 RabbitMQ 队列：`pay.auto.return.queue` 接收**一次**消息：
|
||
|
||
```json
|
||
{
|
||
"queue_id": "pay_456",
|
||
"status": 1,
|
||
"amount": 200.0,
|
||
"chain": "ETH",
|
||
"symbol": "USDT",
|
||
"order_id": "order_789",
|
||
"tx_hash": "0xghi..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## API 文档
|
||
|
||
### 状态码说明
|
||
|
||
| 状态码 | 常量名 | 说明 | 适用场景 |
|
||
|--------|--------|------|---------|
|
||
| `0` | STATUS_FAILED | 交易失败 | 交易被回退或执行失败 |
|
||
| `1` | STATUS_SUCCESS | 交易成功 | 交易成功并已确认 |
|
||
| `2` | STATUS_PENDING | 待确认 | 交易已检测到，等待区块确认 |
|
||
| `3` | STATUS_VERIFY_FAILED | 验证失败 | 签名验证失败 |
|
||
|
||
### 消息结构
|
||
|
||
#### 充值请求 (TopupMsg_req)
|
||
|
||
| 字段 | 类型 | 说明 | 必填 |
|
||
|------|------|------|------|
|
||
| chain | string | 链名称 (ETH) | ✅ |
|
||
| symbol | string | 币种 (USDT) | ✅ |
|
||
| address | string | 充值地址 | ✅ |
|
||
| timestamp | uint64 | 时间戳 | ✅ |
|
||
| sign | string | 签名 | ✅ |
|
||
|
||
#### 充值响应 (TopupMsg_resp)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| address | string | 充值地址 |
|
||
| status | int | 状态码 (0/1/2/3) |
|
||
| chain | string | 链名称 |
|
||
| symbol | string | 币种 |
|
||
| amount | float64 | 金额 |
|
||
| tx_hash | string | 交易哈希 |
|
||
|
||
#### 提现请求 (WithdrawMsg_req)
|
||
|
||
| 字段 | 类型 | 说明 | 必填 |
|
||
|------|------|------|------|
|
||
| queue_id | string | 队列ID | ✅ |
|
||
| from_address | string | 转出地址 | ✅ |
|
||
| to_address | string | 转入地址 | ✅ |
|
||
| amount | float64 | 金额 | ✅ |
|
||
| chain | string | 链名称 | ✅ |
|
||
| symbol | string | 币种 | ✅ |
|
||
| timestamp | uint64 | 时间戳 | ✅ |
|
||
| sign | string | 签名 | ✅ |
|
||
|
||
#### 提现响应 (WithdrawMsg_resp)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| queue_id | string | 队列ID |
|
||
| status | int | 状态码 |
|
||
| amount | float64 | 金额 |
|
||
| chain | string | 链名称 |
|
||
| symbol | string | 币种 |
|
||
| tx_hash | string | 交易哈希 |
|
||
|
||
#### 支付请求 (PayMsg_req)
|
||
|
||
| 字段 | 类型 | 说明 | 必填 |
|
||
|------|------|------|------|
|
||
| queue_id | string | 队列ID | ✅ |
|
||
| from_address | string | 付款地址 | ✅ |
|
||
| to_address | string | 收款地址（商户） | ✅ |
|
||
| amount | float64 | 金额 | ✅ |
|
||
| chain | string | 链名称 | ✅ |
|
||
| symbol | string | 币种 | ✅ |
|
||
| order_id | string | 订单ID | ✅ |
|
||
| timestamp | uint64 | 时间戳 | ✅ |
|
||
| sign | string | 签名 | ✅ |
|
||
|
||
#### 支付响应 (PayMsg_resp)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| queue_id | string | 队列ID |
|
||
| status | int | 状态码 |
|
||
| amount | float64 | 金额 |
|
||
| chain | string | 链名称 |
|
||
| symbol | string | 币种 |
|
||
| order_id | string | 订单ID |
|
||
| tx_hash | string | 交易哈希 |
|
||
|
||
---
|
||
|
||
## 开发指南
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
m2pool-payment-v2/
|
||
├── cmd/ # 主程序入口
|
||
│ └── main.go
|
||
├── internal/ # 内部包
|
||
│ ├── blockchain/ # 区块链交互
|
||
│ │ ├── blockchain.go # 统一接口
|
||
│ │ ├── eth/ # 以太坊实现
|
||
│ │ │ └── eth.go
|
||
│ │ └── tron/ # TRON实现（待开发）
|
||
│ ├── crypto/ # 加密工具
|
||
│ │ └── crypto.go
|
||
│ ├── db/ # 数据库
|
||
│ │ └── db.go
|
||
│ ├── msg/ # 消息定义
|
||
│ │ └── msg.go
|
||
│ ├── queue/ # 消息队列
|
||
│ │ ├── rabbitmq.go
|
||
│ │ └── README.md
|
||
│ └── utils/ # 工具函数
|
||
│ └── utils.go
|
||
├── test/ # 测试和示例
|
||
│ ├── test.go
|
||
│ └── config.json
|
||
├── go.mod
|
||
├── go.sum
|
||
└── README.md
|
||
```
|
||
|
||
### 开发环境设置
|
||
|
||
```bash
|
||
# 1. 安装 Go
|
||
wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz
|
||
sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz
|
||
|
||
# 2. 设置环境变量
|
||
export PATH=$PATH:/usr/local/go/bin
|
||
export GOPATH=$HOME/go
|
||
|
||
# 3. 启动 MySQL
|
||
docker run -d \
|
||
--name mysql \
|
||
-p 3306:3306 \
|
||
-e MYSQL_ROOT_PASSWORD=your_password \
|
||
-e MYSQL_DATABASE=payment \
|
||
mysql:8.0
|
||
|
||
# 4. 启动 RabbitMQ
|
||
docker run -d \
|
||
--name rabbitmq \
|
||
-p 5672:5672 \
|
||
-p 15672:15672 \
|
||
-e RABBITMQ_DEFAULT_USER=m2pool \
|
||
-e RABBITMQ_DEFAULT_PASS=m2pool \
|
||
rabbitmq:3-management
|
||
|
||
# 5. 连接以太坊节点
|
||
# 使用 Infura、Alchemy 或自建节点
|
||
```
|
||
|
||
### 数据库表结构
|
||
|
||
```sql
|
||
-- 钱包余额表
|
||
CREATE TABLE `eth_balance` (
|
||
`id` INT AUTO_INCREMENT PRIMARY KEY,
|
||
`address` VARCHAR(42) NOT NULL UNIQUE,
|
||
`private_key` VARCHAR(255) NOT NULL,
|
||
`balance` DECIMAL(20, 8) DEFAULT 0,
|
||
`created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
`updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
INDEX `idx_address` (`address`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
||
|
||
-- 交易记录表（可选）
|
||
CREATE TABLE `transactions` (
|
||
`id` BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||
`tx_hash` VARCHAR(66) NOT NULL UNIQUE,
|
||
`from_address` VARCHAR(42) NOT NULL,
|
||
`to_address` VARCHAR(42) NOT NULL,
|
||
`amount` DECIMAL(20, 8) NOT NULL,
|
||
`symbol` VARCHAR(10) NOT NULL,
|
||
`chain` VARCHAR(10) NOT NULL,
|
||
`tx_type` TINYINT NOT NULL COMMENT '0=充值,1=提现,2=支付',
|
||
`status` TINYINT NOT NULL COMMENT '0=失败,1=成功,2=待确认',
|
||
`block_height` BIGINT,
|
||
`created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
INDEX `idx_tx_hash` (`tx_hash`),
|
||
INDEX `idx_from` (`from_address`),
|
||
INDEX `idx_to` (`to_address`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
||
```
|
||
|
||
---
|
||
|
||
## 部署指南
|
||
|
||
### Docker 部署（推荐）
|
||
|
||
```dockerfile
|
||
# Dockerfile
|
||
FROM golang:1.24-alpine AS builder
|
||
|
||
WORKDIR /app
|
||
COPY . .
|
||
RUN go mod download
|
||
RUN CGO_ENABLED=0 GOOS=linux go build -o m2pool-payment cmd/main.go
|
||
|
||
FROM alpine:latest
|
||
RUN apk --no-cache add ca-certificates
|
||
WORKDIR /root/
|
||
|
||
COPY --from=builder /app/m2pool-payment .
|
||
COPY --from=builder /app/test/config.json .
|
||
|
||
CMD ["./m2pool-payment"]
|
||
```
|
||
|
||
```yaml
|
||
# docker-compose.yml
|
||
version: '3.8'
|
||
|
||
services:
|
||
payment:
|
||
build: .
|
||
depends_on:
|
||
- mysql
|
||
- rabbitmq
|
||
environment:
|
||
- CONFIG_PATH=/root/config.json
|
||
volumes:
|
||
- ./config.json:/root/config.json
|
||
restart: unless-stopped
|
||
|
||
mysql:
|
||
image: mysql:8.0
|
||
environment:
|
||
MYSQL_ROOT_PASSWORD: ${MYSQL_PASSWORD}
|
||
MYSQL_DATABASE: payment
|
||
ports:
|
||
- "3306:3306"
|
||
volumes:
|
||
- mysql_data:/var/lib/mysql
|
||
|
||
rabbitmq:
|
||
image: rabbitmq:3-management
|
||
environment:
|
||
RABBITMQ_DEFAULT_USER: m2pool
|
||
RABBITMQ_DEFAULT_PASS: m2pool
|
||
ports:
|
||
- "5672:5672"
|
||
- "15672:15672"
|
||
volumes:
|
||
- rabbitmq_data:/var/lib/rabbitmq
|
||
|
||
volumes:
|
||
mysql_data:
|
||
rabbitmq_data:
|
||
```
|
||
|
||
```bash
|
||
# 启动
|
||
docker-compose up -d
|
||
|
||
# 查看日志
|
||
docker-compose logs -f payment
|
||
|
||
# 停止
|
||
docker-compose down
|
||
```
|
||
|
||
### 系统服务部署
|
||
|
||
```bash
|
||
# 1. 创建系统用户
|
||
sudo useradd -r -s /bin/false m2pool
|
||
|
||
# 2. 创建服务文件
|
||
sudo nano /etc/systemd/system/m2pool-payment.service
|
||
```
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=M2Pool Payment System
|
||
After=network.target mysql.service rabbitmq-server.service
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=m2pool
|
||
WorkingDirectory=/opt/m2pool-payment
|
||
ExecStart=/opt/m2pool-payment/m2pool-payment
|
||
Restart=on-failure
|
||
RestartSec=10
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
```bash
|
||
# 3. 启动服务
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable m2pool-payment
|
||
sudo systemctl start m2pool-payment
|
||
|
||
# 4. 查看状态
|
||
sudo systemctl status m2pool-payment
|
||
|
||
# 5. 查看日志
|
||
sudo journalctl -u m2pool-payment -f
|
||
```
|
||
|
||
---
|
||
|
||
## 性能指标
|
||
|
||
### 处理能力
|
||
|
||
| 指标 | 数值 | 说明 |
|
||
|------|------|------|
|
||
| **充值检测 TPS** | 500-1000 | 每秒处理交易数 |
|
||
| **提现/支付 TPS** | 200-500 | 包含数据库查询 |
|
||
| **消息发送 TPS** | 5000-10000 | RabbitMQ 发送速率 |
|
||
| **并发地址监听** | 10000+ | 同时监听的地址数量 |
|
||
|
||
### 响应时间
|
||
|
||
| 操作 | 响应时间 | 说明 |
|
||
|------|---------|------|
|
||
| **充值待确认通知** | < 3 秒 | 检测到交易后 |
|
||
| **充值最终确认** | 4-5 分钟 | 20 个区块 |
|
||
| **提现执行** | < 5 秒 | 发送交易 |
|
||
| **提现最终确认** | 4-5 分钟 | 20 个区块 |
|
||
|
||
### 资源占用（4核8G环境）
|
||
|
||
| 资源 | 使用量 | 峰值 |
|
||
|------|--------|------|
|
||
| **CPU** | 5-15% | 30% |
|
||
| **内存** | 100-300 MB | 500 MB |
|
||
| **网络带宽** | 1-5 MB/s | 10 MB/s |
|
||
| **数据库连接** | 5-10 | 20 |
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 为什么充值会收到两次通知？
|
||
|
||
**A:** 这是设计特性！
|
||
- **第一次**（status=2）：检测到交易，提醒用户"正在确认"
|
||
- **第二次**（status=1/0）：交易确认，通知最终结果
|
||
|
||
业务系统应该：
|
||
- status=2：显示进度，**不增加余额**
|
||
- status=1：增加余额
|
||
|
||
### Q2: 提现/支付为什么只有一次通知？
|
||
|
||
**A:** 因为是系统主动发起的交易，用户已经知道在处理中，不需要额外的待确认通知。
|
||
|
||
### Q3: 如何处理交易失败？
|
||
|
||
**A:** 系统会返回 status=0 的消息，业务系统应该：
|
||
- 充值失败：不增加余额，提示用户联系客服
|
||
- 提现失败：退回用户余额
|
||
- 支付失败：恢复订单状态，退回余额
|
||
|
||
### Q4: 确认需要多长时间？
|
||
|
||
**A:** 配置为 20 个区块确认，以太坊约 12 秒/块：
|
||
- 理论时间：20 × 12 = 240 秒（4 分钟）
|
||
- 实际时间：4-5 分钟（包括网络延迟）
|
||
|
||
### Q5: 如何保证私钥安全？
|
||
|
||
**A:**
|
||
1. 私钥在数据库中**加密存储**
|
||
2. 仅在转账时临时解密
|
||
3. 建议使用 HSM（硬件安全模块）
|
||
4. 使用 KMS（密钥管理服务）
|
||
|
||
### Q6: 余额不足时如何处理？
|
||
|
||
**A:** 系统会自动使用**归集钱包**转账。归集钱包应该：
|
||
- 保持足够的余额
|
||
- 定期从各个钱包归集资金
|
||
- 设置余额告警
|
||
|
||
### Q7: 支持哪些网络？
|
||
|
||
**A:**
|
||
- ✅ 以太坊主网（Mainnet）
|
||
- ✅ 以太坊测试网（Goerli, Sepolia）
|
||
- ✅ 私有链
|
||
- ⚠️ 需要修改 USDT 合约地址
|
||
|
||
### Q8: Gas 费用谁承担？
|
||
|
||
**A:**
|
||
- **充值**：用户承担（用户自己发送交易）
|
||
- **提现**：平台承担（系统发送交易）
|
||
- **支付**：平台承担（系统发送交易）
|
||
|
||
建议：提现/支付时从用户金额中扣除 Gas 费
|
||
|
||
### Q9: 如何监控系统状态？
|
||
|
||
**A:** 建议监控：
|
||
- 待确认交易数量：`len(UnConfirmTxs)`
|
||
- Channel 使用率：`len(chainEventCh)/cap(chainEventCh)`
|
||
- RabbitMQ 连接状态
|
||
- WebSocket 连接状态
|
||
- 数据库连接池状态
|
||
|
||
### Q10: 如何处理重复消息？
|
||
|
||
**A:** RabbitMQ 可能重复投递消息，业务系统应该：
|
||
1. 使用 `tx_hash` 作为唯一标识
|
||
2. 实现幂等性处理
|
||
3. 数据库添加唯一索引
|
||
|
||
---
|
||
|
||
## 安全建议
|
||
|
||
### 🔒 安全检查清单
|
||
|
||
- [ ] 私钥加密存储
|
||
- [ ] 使用 HTTPS/WSS 连接
|
||
- [ ] 签名验证所有请求
|
||
- [ ] 限制 API 访问频率
|
||
- [ ] 定期备份数据库
|
||
- [ ] 监控异常交易
|
||
- [ ] 设置余额告警
|
||
- [ ] 使用防火墙限制访问
|
||
- [ ] 定期更新依赖包
|
||
- [ ] 日志脱敏处理
|
||
|
||
### ⚠️ 重要提示
|
||
|
||
1. **私钥管理**
|
||
- ❌ 不要在代码中硬编码私钥
|
||
- ❌ 不要在日志中打印私钥
|
||
- ✅ 使用环境变量或密钥管理服务
|
||
|
||
2. **网络安全**
|
||
- ✅ 使用 VPN 或专线连接区块链节点
|
||
- ✅ RabbitMQ 启用 TLS
|
||
- ✅ MySQL 限制远程访问
|
||
|
||
3. **资金安全**
|
||
- ✅ 设置单笔交易限额
|
||
- ✅ 异常交易人工审核
|
||
- ✅ 多签钱包（建议）
|
||
- ✅ 冷热钱包分离
|
||
|
||
---
|
||
|
||
## 监控告警
|
||
|
||
### 推荐监控指标
|
||
|
||
```go
|
||
// 添加监控指标
|
||
type Metrics struct {
|
||
TotalTransactions int64 // 总交易数
|
||
PendingTransactions int // 待确认交易数
|
||
FailedTransactions int64 // 失败交易数
|
||
ChannelUsage int // Channel使用率
|
||
LastBlockHeight uint64 // 最新区块高度
|
||
}
|
||
|
||
// 定期上报
|
||
go func() {
|
||
ticker := time.NewTicker(1 * time.Minute)
|
||
for range ticker.C {
|
||
log.Printf("📊 待确认交易: %d", len(e.UnConfirmTxs))
|
||
log.Printf("📊 监听地址数: %d", countAddresses())
|
||
log.Printf("📊 Channel使用率: %d%%", len(ch)*100/cap(ch))
|
||
}
|
||
}()
|
||
```
|
||
|
||
### 告警规则建议
|
||
|
||
| 指标 | 阈值 | 告警级别 |
|
||
|------|------|---------|
|
||
| 待确认交易数 | > 100 | ⚠️ 警告 |
|
||
| 待确认交易数 | > 500 | 🔴 严重 |
|
||
| Channel 使用率 | > 80% | ⚠️ 警告 |
|
||
| Channel 使用率 | > 95% | 🔴 严重 |
|
||
| 交易失败率 | > 5% | ⚠️ 警告 |
|
||
| WebSocket 断线 | 重连 > 3次/小时 | ⚠️ 警告 |
|
||
|
||
---
|
||
|
||
## 故障排查
|
||
|
||
### 问题：充值检测不到
|
||
|
||
**可能原因：**
|
||
1. 地址未加入监听列表
|
||
2. WebSocket 连接断开
|
||
3. 合约地址配置错误
|
||
4. 网络 ID 不匹配
|
||
|
||
**排查步骤：**
|
||
```bash
|
||
# 检查日志
|
||
grep "新增钱包监听消息" logs/payment.log
|
||
|
||
# 检查订阅状态
|
||
grep "订阅成功" logs/payment.log
|
||
|
||
# 测试节点连接
|
||
curl -X POST -H "Content-Type: application/json" \
|
||
--data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
|
||
http://localhost:8545
|
||
```
|
||
|
||
### 问题：提现/支付失败
|
||
|
||
**可能原因：**
|
||
1. 余额不足
|
||
2. Gas 费不足
|
||
3. 私钥错误
|
||
4. nonce 冲突
|
||
|
||
**排查步骤：**
|
||
```bash
|
||
# 检查错误日志
|
||
grep "转账失败" logs/payment.log
|
||
|
||
# 检查余额
|
||
grep "余额" logs/payment.log
|
||
|
||
# 检查私钥
|
||
grep "查询私钥" logs/payment.log
|
||
```
|
||
|
||
### 问题：消息未返回
|
||
|
||
**可能原因：**
|
||
1. RabbitMQ 连接断开
|
||
2. Channel 阻塞
|
||
3. 交易未确认
|
||
|
||
**排查步骤：**
|
||
```bash
|
||
# 检查 RabbitMQ 连接
|
||
rabbitmqctl list_connections
|
||
|
||
# 检查队列状态
|
||
rabbitmqctl list_queues
|
||
|
||
# 检查待确认交易
|
||
# 添加 HTTP 接口查询 UnConfirmTxs
|
||
```
|
||
|
||
---
|
||
|
||
## 贡献指南
|
||
|
||
欢迎贡献代码！请遵循以下步骤：
|
||
|
||
1. Fork 本项目
|
||
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 开启 Pull Request
|
||
|
||
### 代码规范
|
||
|
||
- 使用 `gofmt` 格式化代码
|
||
- 遵循 Go 命名规范
|
||
- 添加必要的注释
|
||
- 编写单元测试
|
||
- 更新文档
|
||
|
||
---
|
||
|
||
## 路线图
|
||
|
||
### v2.1 (计划中)
|
||
- [ ] 支持 BTC 网络
|
||
- [ ] 支持 TRON 网络
|
||
- [ ] 添加 HTTP API
|
||
- [ ] 添加 WebSocket 推送
|
||
- [ ] 性能优化（读写锁、缓存）
|
||
|
||
### v2.2 (计划中)
|
||
- [ ] 支持更多 ERC20 代币
|
||
- [ ] 多签钱包支持
|
||
- [ ] 交易记录持久化
|
||
- [ ] 管理后台
|
||
- [ ] 监控面板
|
||
|
||
### v3.0 (规划中)
|
||
- [ ] 微服务架构
|
||
- [ ] 水平扩展支持
|
||
- [ ] 分布式事务
|
||
- [ ] 高可用部署
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [RabbitMQ 使用说明](internal/queue/README.md)
|
||
- [并发能力分析](docs/CONCURRENCY_ANALYSIS.md)（如果有）
|
||
- [交易类型说明](docs/TRANSACTION_TYPES.md)（如果有）
|
||
|
||
---
|
||
|
||
## 技术支持
|
||
|
||
- 📧 Email: support@m2pool.com
|
||
- 💬 Telegram: @m2pool_support
|
||
- 📱 WeChat: m2pool_tech
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
Copyright (c) 2025 M2Pool Team
|
||
|
||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||
of this software and associated documentation files (the "Software"), to deal
|
||
in the Software without restriction, including without limitation the rights
|
||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||
copies of the Software, and to permit persons to whom the Software is
|
||
furnished to do so, subject to the following conditions:
|
||
|
||
The above copyright notice and this permission notice shall be included in all
|
||
copies or substantial portions of the Software.
|
||
|
||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||
SOFTWARE.
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**⭐ 如果这个项目对你有帮助，请给一个 Star！⭐**
|
||
|
||
Made with ❤️ by M2Pool Team
|
||
|
||
</div>
|
||
|