# gewechat

**Repository Path**: ai-sales/gewechat

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-17
- **Last Updated**: 2025-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="logo.png" width="500px" height="350px" alt="Gewechat Logo">
</p>

## 👉 Gewechat🤖

Gewechat是一个功能完备的个人微信开源框架，支持二次开发和多语言接入，通过标准化的Restful API提供丰富的微信操作能力。

### 框架优势：

- **零安装配置**：无需安装电脑微信客户端，无需安装手机破解插件，只需扫码登录即可使用
- **简单易用**：提供直观的API接口，降低开发和接入难度
- **稳定可靠**：采用大厂主流使用方案，确保服务稳定性
- **多语言支持**：提供标准化的Restful API，任何语言都可轻松接入
- **功能丰富**：支持消息收发、好友管理、群组管理等全方位微信操作

### 主要能力：

* **消息管理**：发送文本、图片、文件、emoji表情、小程序、语音、视频等多种类型消息，接收各类消息并下载内容
* **自动回复**：支持自定义消息处理、关键字回复、AI回复等自动化交互场景
* **好友管理**：获取通讯录信息、搜索好友、添加好友、删除好友、设置备注等功能
* **群组管理**：创建群组、修改群名称、邀请成员、删除成员、退出群聊等操作
* **标签管理**：添加、删除标签，修改好友标签
* **个人管理**：获取个人资料、修改个人信息、隐私设置等
* **收藏夹管理**：同步收藏夹、获取收藏夹内容、删除收藏夹
* **第三方集成**：支持接入ChatGPT、Sora等AI模型及各类业务系统
* **事件驱动架构**：提供消息回调机制，便于实现复杂的自动化业务逻辑

<br/>
<details><summary>免责声明【必读】</summary>
<br/>
- 本框架仅供学习和技术研究使用，不得用于任何商业或非法行为，否则后果自负。

- 本框架的作者不对本工具的安全性、完整性、可靠性、有效性、正确性或适用性做任何明示或暗示的保证，也不对本工具的使用或滥用造成的任何直接或间接的损失、责任、索赔、要求或诉讼承担任何责任。

- 本框架的作者保留随时修改、更新、删除或终止本工具的权利，无需事先通知或承担任何义务。

- 本框架的使用者应遵守相关法律法规，尊重微信的版权和隐私，不得侵犯微信或其他第三方的合法权益，不得从事任何违法或不道德的行为。

- 本框架的使用者在下载、安装、运行或使用本工具时，即表示已阅读并同意本免责声明。如有异议，请立即停止使用本工具，并删除所有相关文件。
</details>
<br/>
<details><summary>点击查看功能清单</summary><br/>
  
+ [x] 登录模块：获取登录二维码、执行登录、设置消息回调地址

+ [x] 联系人模块：获取通讯录列表、获取通讯录信息、搜索好友、添加好友、同意添加好友、删除好友、设置好友仅聊天、设置好友备注

+ [x] 群模块：创建微信群、修改群名称、修改群备注、修改群昵称、邀请/添加入群、删除群成员、退出群聊、解散群聊

+ [x] 消息模块：发送文字/文件/图片/视频/语音/小程序/链接/各类APP消息、转发文件/图片/链接/视频/链接/小程序等、接收各类消息及下载消息内容

+ [x] 标签模块：添加标签、删除标签、标签列表、修改好友标签

+ [x] 个人模块：获取个人资料、获取自己的二维码、隐私设置、修改个人信息、修改头像

+ [x] 收藏夹模块：同步收藏夹、获取收藏夹内容、删除收藏夹

+ [x] 账号管理模块：断线重连、退出微信、检查在线
</details>
<br/>

## 🚀 快速入门

### 环境要求

- **操作系统**：推荐Centos7或Ubuntu22.04
- **硬件配置**：推荐4核8G及以上
- **网络要求**：服务器需能正常访问外网，且确保2531和2532端口未被占用
- **特殊要求**：为保证账号稳定性，建议在微信账号注册地所在省份的服务器上部署

### 安装Docker

> Centos Docker安装，已安装Docker可跳过

1、安装gcc相关依赖

```bash
yum -y install gcc
yum -y install gcc-c++
```

2、配置Docker镜像源

```bash
yum install -y yum-utils
yum-config-manager --add-repo http://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
yum makecache fast
```

3、安装Docker组件

```bash
yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

4、启动Docker服务并设置开机自启

```bash
systemctl start docker
systemctl enable docker.service
```

### 启动服务

1、拉取Docker镜像

```bash
# 拉取最新镜像
docker pull registry.cn-hangzhou.aliyuncs.com/gewe/gewe:latest
# 设置镜像标签
docker tag registry.cn-hangzhou.aliyuncs.com/gewe/gewe gewe
```

2、创建数据目录并启动容器

```bash
# 创建临时目录
mkdir -p /root/temp
# 运行容器，映射端口和数据卷
docker run -itd -v /root/temp:/root/temp -p 2531:2531 -p 2532:2532 --privileged=true --name=gewe gewe /usr/sbin/init
```

3、设置容器开机自启动

```bash
docker update --restart=always gewe
```

### API服务调用

1. **基础API地址**：`http://{服务ip}:2531/v2/api/{接口名}`
2. **文件下载地址**：`http://{服务ip}:2532/download/{接口返回的文件路径}`
3. **详细API文档**：[点击查看完整API文档](https://apifox.com/apidoc/shared-69ba62ca-cb7d-437e-85e4-6f3d3df271b1)

### 技术架构

Gewechat采用经典的分层架构设计，结合事件驱动模式，实现了高内聚、低耦合的系统设计，便于扩展和维护。

#### 系统架构概述

 <img src="liucheng.jpg" width="600px" height="350px" alt="系统架构图">

#### 核心分层设计

1. **接入层**
   - 提供标准化的RESTful API接口，支持多语言（Java、Python、Node.js等）接入
   - 负责请求的路由和参数校验，提供统一的访问入口
   - 主要组件：`GeWechatMessageController`

2. **业务API层**
   - 封装各类微信操作API，提供简洁易用的接口
   - 按功能模块划分，包括登录、消息、好友、群组等API
   - 主要组件：`LoginApi`、`MessageApi`、`ContactApi`、`GroupApi`等

3. **事件驱动层**
   - 基于观察者模式实现事件的发布和订阅
   - 处理微信消息、离线通知等事件的分发和处理
   - 主要组件：`Publisher`、`EventByNewMessage`、`EventByOffline`

4. **数据持久层**
   - 基于MyBatis-Plus和MySQL实现数据存储
   - 提供消息和配置数据的CRUD操作
   - 主要组件：`GewechatMessageMapper`

5. **消息处理层**
   - 负责消息的接收、解析、处理和发送
   - 支持多种消息类型的处理逻辑
   - 主要组件：`MessageService`、各类Listener实现

6. **工具层**
   - 提供HTTP请求、JSON处理等通用功能
   - 封装常用工具方法，提升开发效率
   - 主要组件：`OkhttpUtil`

#### 核心功能模块

1. **API模块**：提供完整的微信操作接口
   - 登录模块：扫码登录、登出、状态检查等
   - 消息模块：发送各类消息、接收消息等
   - 联系人模块：好友管理、通讯录操作等
   - 群组模块：群聊创建、管理等
   - 标签模块：联系人标签管理
   - 个人模块：个人信息管理
   - 收藏夹模块：微信收藏管理

2. **事件监听模块**：实现事件的处理和分发
   - 新消息监听器：处理接收到的新消息
   - 离线消息监听器：处理离线通知
   - 消息持久化监听器：将消息保存到数据库
   - 消息回显监听器：将消息回显给调用方

3. **数据模型**：定义系统的数据结构
   - 消息模型：各类微信消息的定义
   - 事件模型：系统事件的定义
   - DTO模型：数据传输对象的定义

#### 技术栈

- **后端框架**：Spring Boot 2.3.0 - 提供Web应用基础框架
- **数据库迁移工具**：Flyway - 实现数据库的自动创建和版本更新

#### 数据库自动创建与更新（Flyway）

Gewechat集成了Flyway数据库迁移工具，实现了数据库结构的自动创建和版本控制，确保应用在不同环境部署时数据库结构的一致性和可追溯性。

**主要功能**：
- 自动执行数据库迁移脚本，创建表结构和初始数据
- 版本化管理数据库变更，支持回滚和追踪
- 保证多环境部署时数据库结构的一致性
- 避免手动执行SQL脚本导致的错误和不一致

**迁移脚本位置**：`src/main/resources/db/migration`

**配置方式**：
```properties
# Flyway配置（application.properties）
spring.flyway.enabled=true
spring.flyway.locations=classpath:db/migration
spring.flyway.baseline-on-migrate=true
spring.flyway.table=schema_version
```

**使用流程**：
1. 按照Flyway命名规范创建SQL迁移脚本（如：V1.0.0__Create_Table.sql）
2. 启动应用时，Flyway会自动检测并执行未应用的迁移脚本
3. 所有执行记录保存在`schema_version`表中，便于追踪和管理

通过Flyway的集成，Gewechat实现了数据库的自动化管理，大大简化了应用部署和升级过程，提高了系统的稳定性和可靠性。
- **数据库**：MySQL 5.1.34 - 数据持久化存储
- **缓存**：Redis - 提升系统性能和响应速度
- **ORM框架**：MyBatis-Plus 3.4.2 - 简化数据库操作
- **HTTP客户端**：OkHttp 3.10.0 - 处理HTTP请求
- **JSON处理**：Fastjson2 - 高效的JSON序列化和反序列化
- **工具库**：Hutool 5.6.3 - 提供丰富的工具方法
- **容器化**：Docker - 简化部署和环境一致性

## 基本用法

Gewechat提供了完整的API接口，下面以Java为例展示基本的使用流程。其他语言只需通过RESTful接口调用即可实现相同功能。

### Java客户端使用示例

#### 1. 获取API Token
```java
// 获取接口访问Token
JSONObject token = LoginApi.getToken();

// 将Token设置到请求头中（每个API调用都需要）
header.put("X-GEWE-TOKEN", token.getString("token"));
```

#### 2. 微信登录流程
```java
/**
 * 获取登录二维码
 * @param appId 设备id，首次登录传空，后续登录传返回的appid
 */
JSONObject qr = LoginApi.getQr(appId);

/**
 * 确认登录
 * @param appId 设备id
 * @param uuid 二维码返回的uuid
 * @param captchCode 登录验证码（同省登录可避免此问题，提高账号稳定性）
 */
JSONObject loginResult = LoginApi.checkQr(appId, uuid, captchCode);

// 登录成功后可执行其他操作
if (loginResult.getInteger("code") == 0) {
    System.out.println("微信登录成功！");
    // 执行后续操作...
}
```

#### 3. 发送消息示例
```java
/**
 * 发送文本消息
 * @param appId 设备id
 * @param toWxid 接收者微信id
 * @param content 消息内容
 * @param ats @的用户（群聊时使用，多个用户用逗号分隔）
 */
JSONObject textResult = MessageApi.postText(appId, "wxid_xxxxxx", "你好，这是一条测试消息", "");

/**
 * 发送图片消息
 * @param appId 设备id
 * @param toWxid 接收者微信id
 * @param imgUrl 图片URL地址
 */
JSONObject imgResult = MessageApi.postImage(appId, "wxid_xxxxxx", "http://example.com/image.jpg");
```

### 核心API模块

登录成功后，可以使用以下核心API类实现各种功能：
- `LoginApi.class` - 登录模块（获取二维码、确认登录、退出登录等）
- `PersonalApi.class` - 个人账号模块（获取个人资料、修改信息等）
- `ContactApi.class` - 联系人模块（获取好友列表、添加/删除好友等）
- `GroupApi.class` - 微信群模块（创建群聊、群管理等）
- `MessageApi.class` - 消息模块（发送各类消息、接收消息等）
- `LabelApi.class` - 标签模块（创建标签、管理标签等）
- `FavorApi.class` - 收藏夹模块（管理微信收藏夹）
```

## 注意事项

1. **系统环境要求**：推荐使用Centos7或Ubuntu22.04操作系统
2. **硬件配置**：建议使用4核8G及以上配置以保证服务稳定运行
3. **端口占用**：确保服务器的2531和2532端口未被其他服务占用
4. **网络要求**：服务器需能正常访问外网，确保可以连接腾讯服务
5. **地域限制**：为保证账号稳定，建议在微信账号注册地所在省份的服务器上部署
6. **使用范围**：本框架面向个人学习和娱乐使用，请勿用于任何商用场景

## 常见问题与解决方案

1. **登录验证码问题**：
   - 问题：登录时提示需要验证码
   - 解决：在微信账号注册地所在省份的服务器上部署服务

2. **消息收发延迟**：
   - 问题：消息收发有延迟
   - 解决：检查服务器网络连接，确保网络通畅

3. **容器启动失败**：
   - 问题：Docker容器无法正常启动
   - 解决：检查服务器网络连接，确保可以访问腾讯服务和Docker镜像源

4. **端口占用冲突**：
   - 问题：端口2531或2532被占用
   - 解决：停止占用该端口的服务，或修改Docker运行命令中的端口映射配置

## 社区交流

<p align="center">
  <img src="mine.jpg" width="300px" height="300px" alt="交流群二维码">
</p>
<p align="center">
 添加好友备注「GW加群交流」，加入技术交流群
</p>

## 版本更新

### 更新流程

1. 停止并删除旧版本容器
```bash
# 停止运行中的容器
docker stop gewe
# 删除容器
docker rm gewe
```

2. 拉取最新版本镜像
```bash
docker pull registry.cn-hangzhou.aliyuncs.com/gewe/gewe:latest
docker tag registry.cn-hangzhou.aliyuncs.com/gewe/gewe gewe
```

3. 重新启动容器
```bash
docker run -itd -v /root/temp:/root/temp -p 2531:2531 -p 2532:2532 --privileged=true --name=gewe gewe /usr/sbin/init
docker update --restart=always gewe
```

> **注意**：每次更新后会被视为新设备登录，建议新设备登录后先保持一段时间稳定运行再进行频繁操作，以避免账号异常。


## 生态与扩展

### 社区扩展项目

- [gewechaty](https://github.com/mikoshu/gewechaty) - 基于Node.js的Gewechat封装，提供更加易用的API接口
- [dify-on-wechat](https://github.com/hanfangyuan4396/dify-on-wechat) - 对chatgpt-on-wechat项目的扩展，实现了Gewechat通道
- [Coze-on-Wechat](https://github.com/JC0v0/Coze-on-Wechat) - 对接Coze平台的Gewechat扩展
- [rgewe-api](https://github.com/momo402/rgewe-api) - 基于Rust语言的Gewechat API封装，同步API文档
- [gewechat-python](https://github.com/hanfangyuan4396/gewechat-python) - 基于Python语言的Gewechat API实现示例

### 第三方集成

Gewechat可以与多种第三方服务进行集成：
- **AI模型**：ChatGPT、Sora、Dify、Coze等
- **业务系统**：客服系统、RPA自动化流程、数据分析平台等
- **开发语言**：Java、Node.js、Python、Rust等多种编程语言支持
  

## 版本更新历史

### 1.0.2
- **发布日期**：2023年
- **更新内容**：修复已知bug，优化系统稳定性
- **注意事项**：历史版本会逐渐失效，更新后将视为新设备登录
- **更新建议**：新设备登录后建议先稳定运行几天再进行频繁操作

### 1.0.1
- **发布日期**：2023年
- **更新内容**：优化图片下载功能，提高兼容性
- **注意事项**：本次更新后将视为新设备登录

### 1.0.0
- **发布日期**：2023年
- **更新内容**：Gewechat框架正式版发布，提供完整的微信API功能
- **主要特性**：消息收发、好友管理、群组管理、标签管理等基础功能

<details><summary>点击查看更多版本更新历史</summary>

早期版本更新信息已归档，如有需要可联系项目维护者获取。
</details>