388 lines
21 KiB
Markdown
388 lines
21 KiB
Markdown
# 📋 项目结构分析报告
|
||
|
||
> **项目名称**: wechat_ipad_pro_1224
|
||
> **模块名称**: `xiawan/wx`
|
||
> **技术栈**: Go 1.21 + Gin + MySQL + Redis + Protobuf + Docker
|
||
> **分析日期**: 2026-02-17
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
本项目是一个 **微信 iPad Pro 协议服务端**，通过逆向微信 iPad 协议实现微信功能的 HTTP API 化。服务端基于 Go 语言开发，使用 Gin 框架暴露 RESTful API，支持多账号并发登录管理，提供完整的微信消息、联系人、群管理、朋友圈、支付等功能。
|
||
|
||
### 核心特性
|
||
|
||
- 🔐 MMTLS 加密通信（微信自定义 TLS 协议）
|
||
- 📱 iPad Pro 设备模拟（支持 Mac/Car 转 iPad 模式）
|
||
- 🔄 多账号并发管理（100 并发限制）
|
||
- 📡 WebSocket + HTTP 轮询双模式消息同步
|
||
- 🐳 Docker 容器化部署
|
||
- 📖 Swagger API 文档
|
||
|
||
---
|
||
|
||
## 2. 项目目录结构
|
||
|
||
```
|
||
wechat_ipad_pro_1224/
|
||
├── main.go # 程序入口（初始化配置 → 数据库 → API 服务）
|
||
├── go.mod # Go 模块定义 (xiawan/wx, go 1.21)
|
||
├── go.sum # 依赖校验
|
||
├── Dockerfile # 多阶段 Docker 构建（golang:1.21-alpine）
|
||
├── docker-compose.yaml # 编排：wxserver + redis + mysql
|
||
│
|
||
├── api/ # 🌐 HTTP 接口层（Gin 框架）
|
||
│ ├── apiSetup.go # API 启动入口 + 自动重连逻辑
|
||
│ ├── controller/ # 控制器层（19 个文件）
|
||
│ ├── service/ # API 业务服务层（23 个文件）
|
||
│ ├── router/ # 路由注册（router.go）
|
||
│ ├── req/ # 请求模型（9 个文件）
|
||
│ ├── vo/ # 响应视图对象
|
||
│ ├── middleware/ # 中间件（CORS 等）
|
||
│ ├── swagger/ # Swagger 文档配置
|
||
│ └── utils/ # API 工具函数
|
||
│
|
||
├── srv/ # ⚙️ 核心业务逻辑层
|
||
│ ├── wxcore/ # 微信核心实现（14 个文件）
|
||
│ ├── wxface/ # 接口抽象层（14 个接口定义）
|
||
│ ├── wxrouter/ # 协议路由分发（25 个文件）
|
||
│ ├── wxtask/ # 后台异步任务（9 个文件）
|
||
│ ├── websrv/ # WebSocket 服务
|
||
│ ├── srvconfig/ # 全局配置管理
|
||
│ ├── defines/ # 常量定义
|
||
│ ├── wxaccount.go # 账号管理
|
||
│ └── wxfilemgr.go # 文件管理
|
||
│
|
||
├── clientsdk/ # 📦 微信协议 SDK
|
||
│ ├── request.go # 核心请求封装（5148 行，173KB）
|
||
│ ├── baserequest.go # 基础请求构建
|
||
│ ├── protocol.go # 协议打包/解包
|
||
│ ├── cdnprotocol.go # CDN 协议（图片/视频上传下载）
|
||
│ ├── cdnrequest.go # CDN 请求
|
||
│ ├── hybrid_request.go # 混合请求
|
||
│ ├── oplogitem.go # 操作日志项
|
||
│ ├── demo.go # 示例代码
|
||
│ ├── mmtls/ # MMTLS 加密通信（11 个文件）
|
||
│ ├── cecdh/ # ECDH 密钥交换（7 个文件）
|
||
│ ├── baseinfo/ # 基础数据结构（14 个文件）
|
||
│ ├── baseutils/ # 基础工具函数（8 个文件）
|
||
│ ├── android/ # Android 设备信息（23 个文件）
|
||
│ ├── extinfo/ # 扩展信息
|
||
│ ├── ccdata/ # CC 数据
|
||
│ ├── hybrid/ # 混合模式
|
||
│ ├── proxynet/ # 代理网络
|
||
│ └── xmltool/ # XML 工具
|
||
│
|
||
├── db/ # 💾 数据库层
|
||
│ ├── mysql_db.go # MySQL 操作（48KB，核心 CRUD）
|
||
│ ├── redisOperation.go # Redis 操作（18KB）
|
||
│ ├── cache.go # 缓存管理
|
||
│ ├── proxy.go # 代理管理
|
||
│ ├── message_callback.go # 消息回调
|
||
│ ├── callback_wrapper.go # 回调包装器
|
||
│ └── table/ # 数据表模型定义
|
||
│ ├── mysql_table.go # MySQL 表结构（ORM 模型）
|
||
│ ├── redis_table.go # Redis 数据结构
|
||
│ ├── proxy_mapping.go # 代理映射
|
||
│ ├── messageCallback.go
|
||
│ └── base.go
|
||
│
|
||
├── protobuf/ # 📝 Protobuf 协议定义
|
||
│ ├── wechat/ # 微信 Protobuf 消息（27 个文件）
|
||
│ ├── wechat_proto/ # 原始 Proto 定义（28 个文件）
|
||
│ └── proto_ref/ # 协议参考
|
||
│
|
||
├── lib/ # 🔧 工具函数库（11 个文件）
|
||
│ ├── BytesToInt.go # 字节转整数
|
||
│ ├── IntToBytes.go # 整数转字节
|
||
│ ├── MD5ToLower.go # MD5 小写
|
||
│ ├── GetFileMD5Hash.go # 文件 MD5
|
||
│ ├── Hex2Int.go # 十六进制转换
|
||
│ ├── CreateDeviceId.go # 设备 ID 生成
|
||
│ ├── Get62Data.go # 62 数据获取
|
||
│ ├── Get62Key.go # 62 密钥获取
|
||
│ ├── GetClientSeqId.go # 客户端序列号
|
||
│ ├── RandString.go # 随机字符串
|
||
│ └── ALLGather.go # 聚合工具
|
||
│
|
||
├── assets/ # 📁 配置和资源文件
|
||
│ ├── setting.json # 主配置文件
|
||
│ ├── setting.json.docker # Docker 环境配置
|
||
│ ├── ca-cert # CA 证书
|
||
│ └── sae.dat # SAE 数据文件
|
||
│
|
||
├── apns/ # 🔔 Apple 推送通知
|
||
│ ├── Apns.go
|
||
│ └── deviceToken.go
|
||
│
|
||
├── bin/ # 📦 预编译二进制
|
||
│ ├── linux_amd64/
|
||
│ └── windows_amd64/
|
||
│
|
||
└── static/ # 🌐 静态资源
|
||
├── swagger/ # Swagger UI + API 文档
|
||
├── templates/ # HTML 模板
|
||
├── doc/ # 文档
|
||
└── qrcode/ # 二维码
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 分层架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ HTTP Client / WebSocket │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ api/router 路由注册（13 个路由组，170+ 端点） │
|
||
│ api/middleware 中间件（CORS、Recovery） │
|
||
│ api/controller 控制器层（参数校验 → 调用 Service） │
|
||
│ api/service API 服务层（业务编排 → 调用 srv 层） │
|
||
│ api/req & vo 请求模型 / 响应视图对象 │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ srv/wxcore 核心实现（连接管理、请求调用器） │
|
||
│ srv/wxface 接口抽象（14 个 Interface 定义） │
|
||
│ srv/wxrouter 协议路由（微信协议命令分发） │
|
||
│ srv/wxtask 后台任务（好友、群消息、红包等） │
|
||
│ srv/websrv WebSocket 服务（实时消息推送） │
|
||
│ srv/srvconfig 全局配置管理 │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ clientsdk/ 微信协议 SDK │
|
||
│ ├── request 协议请求封装（登录/消息/联系人等） │
|
||
│ ├── mmtls MMTLS 加密通信层 │
|
||
│ ├── cecdh ECDH 密钥交换 │
|
||
│ └── protocol 数据打包/解包 + CDN 协议 │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ db/ 数据持久层 │
|
||
│ ├── mysql_db MySQL（用户信息、设备、授权、日志） │
|
||
│ ├── redis Redis（缓存、消息同步、代理） │
|
||
│ └── table ORM 模型定义 │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ protobuf/ 微信 Protobuf 消息协议定义 │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 4. API 路由模块总览
|
||
|
||
API 基于 Gin 框架，共 **13 个路由分组**，端点暴露在配置的 `apiVersion` 路径下。
|
||
|
||
| 路由组 | 路径前缀 | 功能 | 端点数 |
|
||
| ------------- | ------------ | ----------------------------------------- | ------ |
|
||
| **admin** | `/admin` | 授权码管理、代理映射 | 7 |
|
||
| **login** | `/login` | 二维码/设备/唤醒登录、验证码 | 9 |
|
||
| **equipment** | `/equipment` | 设备管理、安全信息 | 4 |
|
||
| **ws** | `/ws` | WebSocket 消息同步 | 1 |
|
||
| **message** | `/message` | 消息收发（文本/图片/视频/语音/卡片/表情） | 26 |
|
||
| **sns** | `/sns` | 朋友圈（发布/评论/点赞/时间线） | 17 |
|
||
| **group** | `/group` | 群管理（创建/邀请/踢人/公告/管理员） | 19 |
|
||
| **user** | `/user` | 用户信息修改（昵称/签名/头像/关键词回复） | 19 |
|
||
| **applet** | `/applet` | 公众号/小程序（关注/授权/文章阅读） | 12 |
|
||
| **other** | `/other` | 附近的人、步数、文件上传 | 7 |
|
||
| **favor** | `/favor` | 收藏管理 | 4 |
|
||
| **label** | `/label` | 标签管理 | 5 |
|
||
| **friend** | `/friend` | 好友管理（通讯录/搜索/加好友/删除） | 11 |
|
||
| **pay** | `/pay` | 微信支付（红包/转账/收款码） | 9 |
|
||
| **finder** | `/finder` | 视频号（搜索/关注） | 4 |
|
||
| **shop** | `/shop` | 微信小店（登录确认/扫码） | 4 |
|
||
| **qy** | `/qy` | 企业微信（联系人/群管理） | 23 |
|
||
|
||
---
|
||
|
||
## 5. 核心数据模型
|
||
|
||
### 5.1 MySQL 数据表
|
||
|
||
| 模型 | 说明 | 主键 |
|
||
| ------------------ | ---------------------------------------------- | -------------------- |
|
||
| `UserInfoEntity` | 用户信息（wxId、session、密钥、代理、状态等） | `wxId` |
|
||
| `DeviceInfoEntity` | 设备信息（IMEI、设备ID、品牌、系统、运营商等） | `wxid` |
|
||
| `LicenseKey` | 授权码（许可证、有效期、绑定微信号） | `id` (自增) |
|
||
| `UserLoginLog` | 登录日志 | `id` (自增) |
|
||
| `UserBusinessLog` | 业务行为日志 | `id` (自增) |
|
||
| `UserMessageLog` | 消息去重日志 | `user_name` |
|
||
| `Command` | 指令配置（自动回复、欢迎语、踢人关键词等） | `uuid` |
|
||
| `ModContactDB` | 联系人变更记录 | `user_uuid_combined` |
|
||
| `AddMsgDB` | 消息记录 | `msg_uuid_combined` |
|
||
| `BlackList` | 黑名单 | `id` |
|
||
| `CdnSnsImageInfo` | CDN 朋友圈图片信息 | `ImageMD5` |
|
||
|
||
### 5.2 Redis 数据结构
|
||
|
||
- 消息同步队列（`_syncMsg`、`_syncHttp`、`_wx_sync_msg_topic`）
|
||
- 代理信息缓存（`wechat:Proxy:{UUID}`）
|
||
- 登录状态缓存
|
||
- 消息去重缓存
|
||
|
||
---
|
||
|
||
## 6. 核心组件说明
|
||
|
||
### 6.1 wxcore - 微信核心实现
|
||
|
||
| 文件 | 大小 | 功能 |
|
||
| -------------------- | ----- | --------------------------------------------------- |
|
||
| `wxreqinvoker.go` | 222KB | **请求调用器**（199 个方法，覆盖所有微信 API 操作） |
|
||
| `wxconnect.go` | 38KB | 微信连接管理（长链接/短链接） |
|
||
| `wxcache.go` | 12KB | 连接缓存 |
|
||
| `wxconnectmgr.go` | 6KB | 连接池管理 |
|
||
| `wxfilehelpermgr.go` | 4KB | 文件辅助管理 |
|
||
| `wxusermsgmgr.go` | 3KB | 用户消息管理 |
|
||
| `wxmsghandler.go` | 3KB | 消息处理器 |
|
||
| `wxtaskmgr.go` | 2KB | 任务管理 |
|
||
| `wxsyncmgr.go` | 2KB | 消息同步管理 |
|
||
| `wxserver.go` | 2KB | 服务器实例 |
|
||
|
||
### 6.2 clientsdk - 协议 SDK
|
||
|
||
| 文件 | 大小 | 功能 |
|
||
| ------------------- | ----- | -------------------------------------------------------------- |
|
||
| `request.go` | 173KB | **核心请求封装**（146 个函数：登录、消息、联系人、群、支付等） |
|
||
| `cdnprotocol.go` | 47KB | CDN 协议（图片/视频上传下载） |
|
||
| `cdnrequest.go` | 39KB | CDN 请求实现 |
|
||
| `baserequest.go` | 29KB | 基础请求构建（Protobuf 序列化） |
|
||
| `protocol.go` | 28KB | 协议打包/解包 |
|
||
| `demo.go` | 18KB | 示例代码 |
|
||
| `oplogitem.go` | 15KB | 操作日志 |
|
||
| `hybrid_request.go` | 14KB | 混合请求 |
|
||
|
||
### 6.3 wxface - 接口抽象层
|
||
|
||
定义了 14 个接口，实现了面向接口编程的架构：
|
||
|
||
| 接口 | 说明 |
|
||
| ------------------ | -------------------------------- |
|
||
| `IWXReqInvoker` | 请求调用器接口（18KB，核心接口） |
|
||
| `IWXConnect` | 微信连接接口 |
|
||
| `IWXConnectMgr` | 连接管理器接口 |
|
||
| `IWXCache` | 缓存接口 |
|
||
| `IWXMsgHandler` | 消息处理接口 |
|
||
| `IWXRouter` | 路由接口 |
|
||
| `IWXServer` | 服务器接口 |
|
||
| `IWXSyncMgr` | 同步管理接口 |
|
||
| `IWXTaskMgr` | 任务管理接口 |
|
||
| `IWXUserMsgMgr` | 用户消息管理接口 |
|
||
| `IWXFileHelperMgr` | 文件助手接口 |
|
||
| `IWXGrabHBMgr` | 抢红包管理接口 |
|
||
| `IWXLongRequest` | 长请求接口 |
|
||
| `IWXResponse` | 响应接口 |
|
||
|
||
---
|
||
|
||
## 7. 配置系统
|
||
|
||
配置文件位于 `assets/setting.json`，主要配置项：
|
||
|
||
```json
|
||
{
|
||
"debug": false, // 调试模式
|
||
"host": "0.0.0.0", // 监听地址
|
||
"port": "7006", // 监听端口
|
||
"apiVersion": "", // API 版本路径前缀
|
||
"adminKey": "xxx", // 管理接口授权密钥
|
||
"mac2ipad": true, // Mac 转 iPad 模式
|
||
"version": "1.0.1", // 版本号
|
||
"workerpoolsize": 500, // 工作线程池大小
|
||
"maxworkertasklen": 1000, // 最大任务队列长度
|
||
"redisConfig": { ... }, // Redis 连接配置
|
||
"mySqlConnectStr": "...", // MySQL 连接字符串
|
||
"disabledCmdList": [...], // 禁用的命令列表
|
||
"dt": true // 设备令牌验证
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 部署方案
|
||
|
||
### Docker Compose 架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────┐
|
||
│ Docker Network: wx_network │
|
||
│ │
|
||
│ ┌──────────┐ ┌────────┐ ┌──────────┐ │
|
||
│ │ wxserver │→ │ redis │ │ mysql │ │
|
||
│ │ Port:5253 │ │ (AOF) │ │ 8.0 │ │
|
||
│ │ Go 1.21 │ │ │ │ utf8mb4 │ │
|
||
│ └──────────┘ └────────┘ └──────────┘ │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
- **wxserver**: Go 编译的二进制，多阶段构建（alpine），端口 5253
|
||
- **Redis**: 持久化 AOF 模式，无外部端口暴露
|
||
- **MySQL 8.0**: utf8mb4 字符集，无外部端口暴露
|
||
- **数据卷**: `assets/`、`static/`、`logs/`、`redis_data/`、`mysql_data/`
|
||
|
||
---
|
||
|
||
## 9. 依赖库概览
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
| --------------------- | ------- | --------------------- |
|
||
| `gin-gonic/gin` | v1.6.3 | HTTP 框架 |
|
||
| `jinzhu/gorm` | v1.9.11 | ORM |
|
||
| `gomodule/redigo` | v2.0.0 | Redis 客户端 |
|
||
| `go-sql-driver/mysql` | v1.8.1 | MySQL 驱动 |
|
||
| `gorilla/websocket` | v1.4.1 | WebSocket |
|
||
| `gogo/protobuf` | v1.2.2 | Protobuf 序列化 |
|
||
| `golang/protobuf` | v1.3.3 | Protobuf 工具 |
|
||
| `micro/go-micro` | v1.18.0 | 微服务框架 |
|
||
| `wsddn/go-ecdh` | - | ECDH 密钥交换 |
|
||
| `golang.org/x/crypto` | v0.28.0 | 加密扩展库 |
|
||
| `boombuler/barcode` | v1.0.0 | 条码/二维码生成 |
|
||
| `nfnt/resize` | - | 图片缩放 |
|
||
| `techoner/gophp` | v0.2.0 | PHP 序列化兼容 |
|
||
| `sirupsen/logrus` | v1.4.2 | 结构化日志 |
|
||
| `gogf/gf` | v1.12.3 | GoFrame（Redis 配置） |
|
||
|
||
---
|
||
|
||
## 10. 安全与授权机制
|
||
|
||
1. **授权码系统**: `LicenseKey` 模型管理设备授权，支持按时长（日/周/月/季/半年/年/永久）
|
||
2. **AdminKey 认证**: 管理接口通过 `adminKey` 进行身份验证
|
||
3. **程序时效**: `main.go` 中硬编码了过期日期检查（2030-08-17），过期后程序自动退出
|
||
4. **MMTLS 加密**: 所有微信通信使用 MMTLS（微信自定义 TLS）加密
|
||
5. **ECDH 密钥交换**: 登录过程使用 ECDH 进行密钥协商
|
||
6. **代理支持**: 支持 SOCKS5 代理，每个账号可独立配置代理
|
||
|
||
---
|
||
|
||
## 11. 代码量统计
|
||
|
||
| 模块 | 文件数 | 主要大文件 |
|
||
| ------------ | --------- | ---------------------------------------------------- |
|
||
| `api/` | ~63 | `loginService.go` (63KB), `messageService.go` (43KB) |
|
||
| `srv/` | ~70 | `wxreqinvoker.go` (222KB), `wxnewsync.go` (51KB) |
|
||
| `clientsdk/` | ~90 | `request.go` (173KB), `cdnprotocol.go` (47KB) |
|
||
| `db/` | ~11 | `mysql_db.go` (48KB), `redisOperation.go` (18KB) |
|
||
| `protobuf/` | ~57 | Protobuf 生成代码 |
|
||
| `lib/` | 11 | 工具函数 |
|
||
| **总计** | **~300+** | |
|
||
|
||
---
|
||
|
||
## 12. 启动流程
|
||
|
||
```
|
||
main()
|
||
├── 过期检查 (2030-08-17)
|
||
├── srvconfig.ConfigSetUp() # 读取 assets/setting.json
|
||
├── db.InitDB() # 初始化 MySQL + 自动建表
|
||
├── go db.StartCleanupTask() # 启动定时清理任务
|
||
├── db.RedisSetup() # 初始化 Redis 连接池
|
||
└── api.WXServerGinHttpApiStart() # 启动 HTTP 服务
|
||
├── TLog() # 初始化日志
|
||
├── service.InitWXServerRouter() # 初始化微信协议路由
|
||
├── go InitAnewLogin() # 恢复已登录账号连接
|
||
│ ├── 清理缓存
|
||
│ ├── 查询所有用户信息
|
||
│ ├── 并发初始化已登录用户（100 并发限制）
|
||
│ └── 启动定期清理未登录连接（每 5 分钟）
|
||
├── router.SetUpRouter() # 注册 Gin 路由 + Swagger
|
||
└── app.Run() # 启动 Gin HTTP 服务器
|
||
```
|