# 📋 项目结构分析报告 > **项目名称**: 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 服务器 ```