🐾 小黑微信群聊助手
xiaoyuan-chatmate — 基于 iPad 协议的智能微信机器人
✨ 智能对话 · 群管理 · 知识库 · 签到积分 · Web 管理后台 ✨
---
## 📖 简介 QQ：3194938940
**小黑微信群聊助手**（xiaoyuan-chatmate）是一个基于 **iPad 协议** 的智能微信群聊机器人，采用 **Go** 后端 + **React** 前端架构，支持 AI 智能对话、群管理自动化、签到积分、知识库问答等功能。
**核心特色：**
- 🚀 **纯 Go + CGO 架构** — 高性能，低资源占用
- 🔌 **插件系统** — 可插拔扩展，内置 4 个开箱即用插件（AI、签到、积分、菜单）
- 📱 **原生 iPad 协议** — 稳定扫码登录，无需越狱
- 🧠 **DeepSeek / OpenAI 兼容** — 灵活切换 AI 模型
- 🪟 **Web 管理后台** — React + TypeScript 可视化配置和管理
- 🐳 **Docker 一键部署** — 开箱即用
---
## 🎯 功能特性
| 功能 | 说明 | 状态 |
|------|------|:----:|
| 🤖 **AI 智能对话** | @机器人即可对话，基于 DeepSeek 大模型 | ✅ |
| 📚 **RAG 知识库** | 上传文档，AI 基于知识库精准回答 | ✅ |
| 🔑 **关键词回复** | 精确/包含/正则匹配，自动回复 | ✅ |
| 👋 **进群欢迎** | 新成员入群自动发送欢迎语 | ✅ |
| 📊 **签到积分** | 每日签到，连续签到奖励 | ✅ |
| 🛡️ **违禁词拦截** | 敏感词自动提醒 | ✅ |
| ⏰ **定时推送** | 天气、提醒等定时消息 | ✅ |
| 📈 **群统计** | 消息量、活跃用户等数据分析 | ✅ |
| 🌐 **Web 管理后台** | 可视化配置管理 | ✅ |
| 👥 **多账号管理** | 同时管理多个微信账号 | ✅ |
---
## 🏗️ 技术架构
```
┌─────────────────────────────────────────────┐
│ 前端 (Vite + React) │
│ TypeScript · Element Plus · Axios │
└──────────────────┬──────────────────────────┘
│ HTTP / WebSocket
┌──────────────────▼──────────────────────────┐
│ Go 后端 (Gin Framework) │
│ ┌─────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ HTTP API │ │ 插件系统 │ │ WebSocket Hub │ │
│ │ 路由层 │ │ 4个内置插件│ │ 实时消息推送 │ │
│ └────┬─────┘ └────┬─────┘ └──────┬───────┘ │
│ └────────────┼──────────────┘ │
│ ┌─────▼─────┐ │
│ │ 协议适配层 │ │
│ │ ipad860 │ │
│ │ CGO 封装 │ │
│ └─────┬─────┘ │
└────────────────────┼────────────────────────┘
│
┌────────────────────▼────────────────────────┐
│ 外部依赖 (MySQL / Redis / AI API) │
└─────────────────────────────────────────────┘
```
| 组件 | 技术栈 | 说明 |
|------|--------|------|
| **协议层** | ipad860 (CGO) | 原生 iPad 协议封装，扫码登录 |
| **后端框架** | Gin + zap | 高性能 HTTP 框架 + 结构化日志 |
| **AI 引擎** | DeepSeek / OpenAI | 大语言模型对话 |
| **知识库** | ChromaDB | RAG 向量检索 |
| **数据库** | MySQL 8.0 | 业务数据持久化 |
| **缓存** | Redis 7 | 去重/限流/会话/队列 |
| **前端** | React 19 + Element Plus | Web 管理后台 |
| **部署** | Docker / 一键脚本 | 灵活部署方式 |
---
## 🚀 快速开始
### 前置要求
- Linux 服务器（推荐 Ubuntu 22.04+ / CentOS 7+）
- Go 1.24+
- Node.js 18+
- MySQL 8.0（可选，不影响核心功能）
- Redis 7（可选，不影响核心功能）
- DeepSeek / OpenAI API Key（用于 AI 对话）
### 一键启动
```bash
# 1. 克隆仓库
git clone https://gitee.com/black--rose/xiaoyuan-chatmate.git
cd xiaoyuan-chatmate
# 2. 一键构建 & 启动
bash start.sh
```
### 手动构建
```bash
# 1. 编译后端
cd back-end
cp config.yaml.example config.yaml
# 编辑 config.yaml 填入 API Key 等配置
CGO_ENABLED=1 go build -ldflags="-s -w" -o xiaoyuan-chatmate-server ./cmd/main.go
# 2. 编译前端（可选，管理后台）
cd ../web-src
npm install
npm run build
# 3. 启动服务
cd ../back-end
./xiaoyuan-chatmate-server config.yaml
```
### Docker 部署
```bash
# 构建镜像
docker build -t xiaoyuan-chatmate .
# 运行容器（需要挂载配置文件和网络）
docker run -d --name xiaoyuan \
-p 18000:18000 \
-v /path/to/config.yaml:/app/config.yaml \
-e TZ=Asia/Shanghai \
xiaoyuan-chatmate
```
### 使用步骤
1. 打开管理后台 `http://your-server-ip:18000`
2. 点击「登录微信」，用手机微信扫描二维码
3. 配置要管理的群组
4. 上传知识库文档（可选）
5. 🎉 **开始使用！**
---
## 📱 群聊指令
| 指令 | 说明 | 权限 |
|------|------|:----:|
| `@机器人 + 问题` | AI 智能对话 | 所有人 |
| `/菜单` `/help` | 显示功能列表 | 所有人 |
| `/签到` `/打卡` | 每日签到领积分 | 所有人 |
| `/积分` `/我的积分` | 查询积分 | 所有人 |
| `/关键词 添加/删除` | 关键词回复管理 | 管理员 |
| `/欢迎语 内容` | 设置进群欢迎语 | 管理员 |
| `/统计` | 群消息统计 | 管理员 |
| `/配置` | 查看/修改群配置 | 管理员 |
> 💡 **私聊模式**：直接发消息即可，无需 @。
---
## 📂 项目结构
```
xiaoyuan-chatmate/
├── back-end/ # Go 后端
│ ├── cmd/main.go # 主入口
│ ├── internal/ # 内部模块
│ │ ├── api/ # HTTP API (Gin)
│ │ ├── core/ # 核心逻辑 (插件路由、协议适配)
│ │ ├── gateway/ # WebSocket 实时推送
│ │ ├── storage/ # 存储层 (MySQL/Redis)
│ │ ├── config/ # 配置加载
│ │ └── ai/ # AI 引擎 (DeepSeek/OpenAI)
│ ├── plugins/ # 插件系统
│ │ ├── ai/ # AI 对话插件
│ │ ├── menu/ # 菜单插件
│ │ ├── signin/ # 签到插件
│ │ └── points/ # 积分插件
│ ├── ipad869/ # iPad 协议 (独立 go.mod)
│ ├── pkg/models/ # 数据模型
│ ├── config.yaml.example # 配置模板
│ └── go.mod
├── web-src/ # 前端 (React + Vite)
├── start.sh # 一键启动脚本
├── stop.sh # 停止服务
├── Dockerfile # Docker 构建
└── README.md # 本文件
```
---
## ⚙️ 配置说明
主要配置项在 `back-end/config.yaml`：
```yaml
server:
host: "0.0.0.0"
port: 18000 # API 服务端口
mysql:
host: "127.0.0.1"
port: 3306
user: "wechatbot"
password: "" # 填入 MySQL 密码
database: "chatmate"
redis:
addr: "127.0.0.1:6379"
password: ""
db: 0
ai:
provider: "deepseek" # deepseek / openai
deepseek:
api_key: "" # 填入 API Key
model: "deepseek-chat"
```
---
## 🔌 插件系统
小黑群聊助手采用 **插件架构**，所有功能以插件形式注册运行：
| 插件 | 描述 | 优先级 | 开箱即用 |
|:----|:----|:-----:|:--------:|
| **menu** | 显示机器人功能菜单 | 50 | ✅ |
| **signin** | 每日签到领积分 | 51 | ✅ |
| **points** | 查询和管理积分 | 50 | ✅ |
| **ai** | AI 智能对话（DeepSeek） | 25 | ✅ |
插件通过 `internal/plugin` 框架管理，支持运行时 **启用/禁用/重载**。
---
## 📸 界面预览
> 管理后台基于 React 19 + Element Plus 构建，提供可视化配置界面。
| 功能 | 说明 |
|:----|:----|
| 📊 仪表盘 | 运行状态、消息统计概览 |
| 💬 消息管理 | 查看/发送消息记录 |
| 👥 群管理 | 入群欢迎、关键词、违禁词配置 |
| 🤖 AI 配置 | 模型选择、Prompt 调优 |
| 📚 知识库 | 文档上传、检索管理 |
| 👤 登录 | 微信扫码登录 / 滑块验证 |
| ⚙️ 系统设置 | 全局参数配置 |
---
## ⚠️ 免责声明
1. 本项目 **仅供学习研究使用**，请遵守当地法律法规
2. 基于 iPad 协议的微信机器人存在 **封号风险**，请谨慎使用
3. 使用者需 **自行承担** 因使用本软件而产生的一切法律责任
4. 请勿用于非法用途，开发者不承担任何法律责任
---
## 👥 讨论与支持交流
- 📦 QQ：3194938940
- 🌟 给个 Star：如果觉得有用，请点右上角 ⭐ 支持
---
