# webhook_v2

**Repository Path**: only-win-wisdom/webhook_v2

## Basic Information

- **Project Name**: webhook_v2
- **Description**: 一个专注于Webhook技术的开源项目，提供灵活的事件触发和消息传递功能，支持多种应用场景，旨在简化开发者的工作流程。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-07
- **Last Updated**: 2026-02-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CrossPay Webhook Service

<div align="center">

![Version](https://img.shields.io/badge/version-v1.0-blue.svg)
![Go Version](https://img.shields.io/badge/go-1.23.0-00ADD8.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)

跨境支付 Webhook 通知处理服务

[功能特性](#功能特性) • [快速开始](#快速开始) • [配置说明](#配置说明) • [API文档](#api文档) • [部署指南](#部署指南)

</div>

---

## 📋 目录

- [项目简介](#项目简介)
- [功能特性](#功能特性)
- [技术架构](#技术架构)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [API文档](#api文档)
- [支付平台](#支付平台)
- [数据库设计](#数据库设计)
- [部署指南](#部署指南)
- [开发指南](#开发指南)
- [监控与运维](#监控与运维)
- [常见问题](#常见问题)
- [更新日志](#更新日志)
- [许可证](#许可证)

---

## 🎯 项目简介

**CrossPay Webhook Service** 是一个高性能、企业级的跨境支付 Webhook 通知处理服务，专为处理多支付平台的异步通知而设计。该服务支持多个主流支付平台的集成，提供统一的 Webhook 处理接口，确保支付通知的可靠接收和处理。

### 核心价值

- 🚀 **统一接入**：支持多个支付平台的统一集成
- 🔒 **安全可靠**：内置签名验证、防重放、数据加密等安全机制
- ⚡ **高性能**：优化的内存管理和GC策略，支持高并发处理
- 📊 **实时监控**：完整的性能监控和日志分析系统
- 🌍 **多时区支持**：支持全球多时区业务场景
- 🔄 **容错机制**：自动重试、超时处理、异常恢复

---

## ✨ 功能特性

### 核心功能

#### 1. Webhook 处理

- ✅ 多支付平台 Webhook 接收和处理
- ✅ 签名验证和防重放攻击
- ✅ 异步处理和消息队列
- ✅ 自动重试机制
- ✅ 幂等性保证

#### 2. 支付平台集成

- ✅ **PhotonPay** - 完整的卡片管理和交易处理
- ✅ **InterlacePay** - 跨境支付和余额管理
- ✅ **JuswayPay** - 第三方支付集成

#### 3. 数据管理

- ✅ MySQL - 核心业务数据存储
- ✅ Redis - 高性能缓存和分布式锁
- ✅ MongoDB - 统计数据和日志存储
- ✅ ClickHouse - 大数据分析和查询

#### 4. 安全特性

- ✅ JWT 认证和授权
- ✅ RSA 加密签名验证
- ✅ AES-GCM 敏感数据加密
- ✅ IP 白名单和地理位置限制
- ✅ 蜜罐检测和防暴力破解

#### 5. 监控与运维

- ✅ 实时性能监控
- ✅ 内存和 GC 优化
- ✅ 分布式日志记录
- ✅ Pprof 性能分析
- ✅ 告警通知（邮件、短信）

#### 6. 高级特性

- ✅ 多时区支持
- ✅ 限流和防刷
- ✅ 缓存策略
- ✅ WebSocket 实时推送
- ✅ 数据导出

---

## 🏗️ 技术架构

### 技术栈

| 类别               | 技术                                                   |
| ------------------ | ------------------------------------------------------ |
| **编程语言** | Go 1.23.0+                                             |
| **Web框架**  | Gin                                                    |
| **ORM**      | GORM                                                   |
| **数据库**   | MySQL 5.7+, Redis 6.0+, MongoDB 4.4+, ClickHouse 21.0+ |
| **认证**     | JWT, RSA, AES-GCM                                      |
| **日志**     | Lumberjack                                             |
| **监控**     | Pprof, Custom Monitoring                               |
| **通知**     | 阿里云短信, SMTP邮件                                   |

### 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                       Webhook API Gateway                    │
│                    (Gin + Middleware)                        │
└───────────────────┬─────────────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
┌───────▼──────┐       ┌───────▼──────┐
│   PhotonPay  │       │ InterlacePay │
│   Webhook    │       │   Webhook    │
└───────┬──────┘       └───────┬──────┘
        │                      │
        └──────────┬───────────┘
                   │
        ┌──────────▼──────────┐
        │  Webhook Service    │
        │  (Business Logic)   │
        └──────────┬──────────┘
                   │
     ┌─────────────┼─────────────┐
     │             │             │
┌────▼────┐  ┌────▼────┐  ┌────▼────┐
│  MySQL  │  │  Redis  │  │ MongoDB │
└─────────┘  └─────────┘  └─────────┘
                   │
            ┌──────▼──────┐
            │ ClickHouse  │
            └─────────────┘
```

### 项目结构

```
crosspay-visa-v1-webhook/
├── src/
│   ├── main.go                      # 应用入口
│   ├── config/                      # 配置管理
│   │   ├── config.go
│   │   ├── honeypot_config.go
│   │   ├── pprof_config.go
│   │   └── throttle_config.go
│   ├── controller/                  # 控制器层
│   │   ├── platform/                # 支付平台控制器
│   │   └── system/                  # 系统控制器
│   ├── service/                     # 业务逻辑层
│   │   ├── core/                    # 核心业务服务
│   │   ├── notification/            # 通知服务
│   │   ├── system/                  # 系统服务
│   │   └── transaction/             # 交易服务
│   ├── models/                      # 数据模型
│   │   ├── interlace/               # InterlacePay 模型
│   │   └── photonpay/               # PhotonPay 模型
│   ├── router/                      # 路由配置
│   │   └── notification/            # Webhook 路由
│   ├── middleware/                  # 中间件
│   │   ├── auth.go                  # 认证中间件
│   │   ├── webhook_auth.go          # Webhook 认证
│   │   └── performance_monitor.go   # 性能监控
│   ├── platform/                    # 支付平台集成
│   │   ├── providers/
│   │   │   ├── photonpay/          # PhotonPay 集成
│   │   │   ├── interlacepay/       # InterlacePay 集成
│   │   │   └── juswaypay/          # JuswayPay 集成
│   │   ├── integration/             # 集成处理器
│   │   └── common/                  # 公共类型
│   ├── database/                    # 数据库连接
│   ├── logger/                      # 日志管理
│   ├── errors/                      # 错误处理
│   └── utils/                       # 工具函数
│       ├── auth/                    # 认证工具
│       ├── cache/                   # 缓存工具
│       ├── common/                  # 公共工具
│       ├── communication/           # 通信工具
│       └── database/                # 数据库工具
├── config/                          # 配置文件
│   ├── config.yaml                  # 开发环境配置
│   └── config.yaml.prod             # 生产环境配置
├── scripts/                         # 数据库脚本
├── logs/                            # 日志文件
├── dist/                            # 编译输出
├── go.mod                           # Go 模块依赖
├── go.sum                           # 依赖校验
├── build.bat                        # Windows 编译脚本
└── README.md                        # 项目文档
```

---

## 🚀 快速开始

### 环境要求

- Go 1.23.0 或更高版本
- MySQL 5.7+
- Redis 6.0+
- MongoDB 4.4+
- ClickHouse 21.0+ (可选)

### 安装步骤

#### 1. 克隆项目

```bash
git clone <repository-url>
cd crosspay-visa-v1-webhook
```

#### 2. 安装依赖

```bash
go mod download
go mod tidy
```

#### 3. 配置环境

复制配置文件并根据实际情况修改：

```bash
cp config/config.yaml.example config/config.yaml
```

编辑 `config/config.yaml`，配置数据库连接等信息。

#### 4. 初始化数据库

确保数据库已创建并运行迁移脚本：

```bash
# 创建数据库
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS cross_pay_go CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 导入数据库结构（如有）
# mysql -u root -p cross_pay_go < scripts/schema.sql
```

#### 5. 运行服务

**开发环境：**

```bash
# 使用 Air 热重载（推荐）
air

# 或直接运行
go run src/main.go
```

**生产环境：**

```bash
# 编译
go build -o crosspay_webhook src/main.go

# 运行
APP_ENV=production ./crosspay_webhook
```

#### 6. 验证服务

访问健康检查接口：

```bash
curl http://localhost:8082/api/v1/health
```

---

## ⚙️ 配置说明

### 核心配置

#### 服务器配置

```yaml
server:
  port: 8082              # 服务端口
  mode: "debug"           # 运行模式: debug/release
```

#### 数据库配置

```yaml
database:
  host: "localhost"
  port: "3306"
  username: "root"
  password: "password"
  dbname: "cross_pay_go"
  max_open_conns: 20      # 最大连接数
  max_idle_conns: 5       # 最大空闲连接数
```

#### Redis 配置

```yaml
redis:
  host: "127.0.0.1"
  port: "6379"
  password: ""
  db: 0
  pool_size: 5
```

#### MongoDB 配置

```yaml
mongodb:
  host: "localhost"
  port: "27017"
  database: "transaction_stats"
  max_pool_size: 100
```

#### ClickHouse 配置

```yaml
clickhouse:
  host: "localhost"
  port: 9000
  database: "default"
  username: "default"
  password: ""
```

### 支付平台配置

#### PhotonPay 配置

```yaml
photonpay:
  app_id: "your_app_id"
  app_secret: "your_app_secret"
  gateway_url: "https://api.photonpay.com"
  merchant_private_key: |
    -----BEGIN PRIVATE KEY-----
    ...
    -----END PRIVATE KEY-----
  platform_public_key: |
    -----BEGIN PUBLIC KEY-----
    ...
    -----END PUBLIC KEY-----
```

#### InterlacePay 配置

```yaml
interlacepay:
  client_id: "your_client_id"
  client_secret: "your_client_secret"
  gateway_url: "https://api.interlace.money"
  account_id: "your_account_id"
  webhook_timeout: 10
```

### 安全配置

#### JWT 配置

```yaml
jwt:
  secret: "your-secret-key-here"
  expires_in: 24          # 过期时间（小时）
```

#### 签名验证

```yaml
signature_verification:
  enabled: true
  webhook_verification: true
  strict_mode: true
```

#### 地理位置限制

```yaml
geo_restriction:
  enabled: true
  allowed_countries:
    - "CN"
    - "US"
    - "SG"
```

### 监控配置

```yaml
monitoring:
  mode: "unified"         # unified/basic/disabled
  unified:
    enabled: true
    check_interval: 60
    memory_warning_threshold: 100
```

### 完整配置示例

请参考 `config/config.yaml` 文件获取完整的配置选项。

---

## 📡 API 文档

### Webhook 接收端点

#### PhotonPay Webhook

```http
POST /api/v1/webhook/photonpay
Content-Type: application/json

{
  "event_type": "transaction.created",
  "data": { ... },
  "timestamp": "2024-01-01T00:00:00Z",
  "signature": "..."
}
```

**响应：**

```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

#### InterlacePay Webhook

```http
POST /api/v1/webhook/interlacepay
Content-Type: application/json

{
  "type": "payment.success",
  "data": { ... },
  "timestamp": 1704067200
}
```

### 管理端点

#### 查询 Webhook 记录

```http
GET /api/v1/webhook/list?page=1&page_size=20
Authorization: Bearer <token>
```

#### 重试 Webhook

```http
POST /api/v1/webhook/retry
Authorization: Bearer <token>
Content-Type: application/json

{
  "webhook_id": "123456"
}
```

### 认证

大多数管理端点需要 JWT 认证。在请求头中包含：

```
Authorization: Bearer <your_jwt_token>
```

---

## 💳 支付平台

### 已集成平台

#### 1. PhotonPay

- **功能**：虚拟卡管理、交易处理、3DS 验证
- **文档**：`src/platform/providers/photonpay/`
- **特性**：
  - 卡片创建和管理
  - 交易通知处理
  - 余额查询
  - 状态更新

#### 2. InterlacePay

- **功能**：跨境支付、余额管理、批量操作
- **文档**：`src/platform/providers/interlacepay/`
- **特性**：
  - OAuth2 认证
  - 余额轮询
  - WebSocket 实时推送
  - 批量卡片操作

#### 3. JuswayPay

- **功能**：第三方支付集成
- **文档**：`src/platform/providers/juswaypay/`
- **特性**：
  - 基础支付处理
  - 订单状态查询

### 集成新平台

参考 `src/platform/integration/` 目录下的集成框架文档。

---

## 🗄️ 数据库设计

### 核心表结构

#### 1. webhooks 表

```sql
CREATE TABLE webhooks (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  platform VARCHAR(50) NOT NULL,
  event_type VARCHAR(100) NOT NULL,
  payload TEXT,
  status VARCHAR(20),
  retry_count INT DEFAULT 0,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  INDEX idx_platform (platform),
  INDEX idx_status (status),
  INDEX idx_created_at (created_at)
);
```

#### 2. transactions 表

```sql
CREATE TABLE transactions (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  transaction_id VARCHAR(100) UNIQUE NOT NULL,
  platform VARCHAR(50) NOT NULL,
  amount DECIMAL(20, 2),
  currency VARCHAR(10),
  status VARCHAR(20),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_transaction_id (transaction_id),
  INDEX idx_platform (platform),
  INDEX idx_status (status)
);
```

更多表结构请参考数据库迁移脚本。

---

## 🚢 部署指南

### Docker 部署（推荐）

#### 1. 构建镜像

```bash
docker build -t crosspay-webhook:latest .
```

#### 2. 运行容器

```bash
docker run -d \
  --name crosspay-webhook \
  -p 8082:8082 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/logs:/app/logs \
  -e APP_ENV=production \
  crosspay-webhook:latest
```

### 手动部署

#### 1. 编译

**Linux/macOS：**

```bash
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o crosspay_webhook_linux_amd64 src/main.go
```

**Windows：**

```bash
build.bat
```

#### 2. 上传服务器

```bash
scp crosspay_webhook_linux_amd64 user@server:/path/to/app/
scp -r config user@server:/path/to/app/
```

#### 3. 配置 Systemd 服务

创建 `/etc/systemd/system/crosspay-webhook.service`：

```ini
[Unit]
Description=CrossPay Webhook Service
After=network.target

[Service]
Type=simple
User=app
WorkingDirectory=/path/to/app
Environment="APP_ENV=production"
ExecStart=/path/to/app/crosspay_webhook_linux_amd64
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
```

启动服务：

```bash
sudo systemctl daemon-reload
sudo systemctl enable crosspay-webhook
sudo systemctl start crosspay-webhook
sudo systemctl status crosspay-webhook
```

### 使用 Air 热重载（开发环境）

#### 1. 安装 Air

```bash
go install github.com/cosmtrek/air@latest
```

#### 2. 运行

```bash
air
# 或使用自定义配置
air -c air.toml
```

---

## 👨‍💻 开发指南

### 代码规范

- 遵循 Go 官方代码规范
- 使用 `gofmt` 格式化代码
- 使用 `golint` 检查代码质量

```bash
# 格式化代码
gofmt -w .

# 代码检查
golint ./...
go vet ./...
```

### 添加新的 Webhook 处理器

1. 在 `src/platform/providers/` 创建新的平台目录
2. 实现 `PlatformHandler` 接口
3. 在 `src/router/notification/` 添加路由
4. 在 `src/service/notification/` 实现业务逻辑
5. 更新配置文件添加平台配置

### 测试

```bash
# 运行所有测试
go test ./...

# 运行特定包的测试
go test ./src/service/notification/photonpay/...

# 生成覆盖率报告
go test -cover ./...
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```

### 调试

使用 Delve 调试器：

```bash
# 安装 Delve
go install github.com/go-delve/delve/cmd/dlv@latest

# 调试运行
dlv debug src/main.go
```

---

## 📊 监控与运维

### 性能监控

#### Pprof 性能分析

访问 Pprof 端点（默认端口 6060）：

```bash
# CPU 分析
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# 内存分析
go tool pprof http://localhost:6060/debug/pprof/heap

# Goroutine 分析
go tool pprof http://localhost:6060/debug/pprof/goroutine
```

#### 监控指标

系统提供两种监控模式：

1. **统一监控** (开发环境)

   - 详细的 GC 统计
   - 内存使用分析
   - Goroutine 泄漏检测
2. **基础监控** (生产环境)

   - 关键指标监控
   - 低开销运行

### 日志管理

日志文件位于 `logs/` 目录：

```bash
# 查看实时日志
tail -f logs/app-$(date +%Y-%m-%d).log

# 搜索错误日志
grep "ERROR" logs/app-*.log

# 分析日志
cat logs/app-*.log | grep "webhook" | wc -l
```

### 告警通知

系统支持多种告警通知方式：

- **邮件通知**：通过 SMTP 发送告警邮件
- **短信通知**：集成阿里云短信服务

配置告警接收人：

```yaml
admin_notification_phones:
  - "13800138000"
  - "13900139000"
```

### 健康检查

```bash
# HTTP 健康检查
curl http://localhost:8082/api/v1/health

# 详细状态
curl http://localhost:8082/api/v1/status
```

---

## ❓ 常见问题

### Q1: 如何配置多个数据库实例？

A: 修改 `config/config.yaml` 中的数据库配置，支持读写分离和主从配置。

### Q2: Webhook 处理失败如何重试？

A: 系统自动实现重试机制，可在配置中设置重试次数和间隔。手动重试可通过管理接口触发。

### Q3: 如何优化内存使用？

A:

- 调整 `GOGC` 环境变量
- 配置 `GOMEMLIMIT` 限制内存
- 优化缓存配置
- 启用内存监控定期清理

### Q4: 支持哪些认证方式？

A:

- JWT Token 认证
- RSA 签名验证
- IP 白名单
- 地理位置限制

### Q5: 如何处理高并发场景？

A:

- 使用 Redis 分布式锁
- 配置合适的数据库连接池
- 启用缓存机制
- 使用限流中间件

---

## 📝 更新日志

### v1.0 (2025-01-01)

#### 新增功能

- ✅ 多支付平台 Webhook 集成
- ✅ 统一监控系统
- ✅ 性能优化和内存管理
- ✅ 安全加固和签名验证
- ✅ 完整的日志和告警系统

#### 改进

- 🔧 优化数据库连接池配置
- 🔧 改进 GC 策略
- 🔧 增强错误处理机制

#### 修复

- 🐛 修复并发处理中的竞态条件
- 🐛 修复内存泄漏问题
- 🐛 修复 Redis 连接超时

---

## 📄 许可证

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

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

### 贡献流程

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- **Issue Tracker**: [GitHub Issues](https://github.com/your-repo/issues)
- **Email**: support@example.com

---

## 🙏 致谢

感谢所有为本项目做出贡献的开发者！

---

<div align="center">

**[⬆ 返回顶部](#crosspay-webhook-service)**

Made with ❤️ by CrossPay Team

</div>