UshurbakiyevDavlat/WA-SERVICE
GitHub: UshurbakiyevDavlat/WA-SERVICE
兼容 WAHA API 的免费自托管 WhatsApp 多会话 HTTP 服务，解决多账号同时在线消息收发的问题。
Stars: 1 | Forks: 0
# wa-service
基于 [Baileys](https://github.com/WhiskeySockets/Baileys) 构建的自托管 WhatsApp 多会话 HTTP API 服务。与 [WAHA](https://github.com/devlikeapro/waha) API 兼容的即插即用替代品 —— 自行部署，无需订阅。
## 功能特性
- **多会话** — 每个会话都是带有独立凭据的独立手机号码
- **兼容 WAHA API** — 只需替换 base URL，其他一切照常运行
- **QR 码认证** — 扫码一次，凭据在重启后依然保留
- **Webhook** — 收到的消息将以 WAHA payload 格式转发到您的后端
- **自动重连** — 连接断开时采用指数退避策略，注销时转为 FAILED 状态
- **API Key 认证** — 可选的 `X-Api-Key` 请求头保护
- **Docker 就绪** — 单个容器，会话目录作为卷挂载
## 快速开始
### 使用 Docker (推荐)
```
docker build -t wa-service .
docker run -d \
--name wa-service \
-p 3000:3000 \
-v $(pwd)/sessions:/app/sessions \
-e WAHA_API_KEY=your-secret-key \
wa-service
```
### 本地运行 (Node 20+)
```
npm install
WAHA_API_KEY=your-secret-key npm start
```
带有自动重载的开发模式：
```
npm run dev
```
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `PORT` | `3000` | HTTP 端口 |
| `WAHA_API_KEY` | _(空)_ | 用于 `X-Api-Key` 请求头的 API key。如果未设置 —— 开放访问 (开发模式) |
| `SESSIONS_DIR` | `./sessions` | 用于持久化会话凭据的目录 |
| `LOG_LEVEL` | `info` | Pino 日志级别 (`debug`、`info`、`warn`、`error`、`silent`) |
## API 参考
如果配置了 `WAHA_API_KEY`，所有端点都需要 `X-Api-Key: ` 请求头。
### 健康检查
```
GET /health
```
返回服务状态和活动会话数量。
```
{ "status": "ok", "sessions": 2 }
```
### 会话管理
#### 获取会话状态
```
GET /api/sessions/:session
```
如果会话不存在，则返回 `404` (与 WAHA 相同)。
```
{ "name": "default", "status": "WORKING", "me": { "id": "77771234567@s.whatsapp.net", "name": "John" } }
```
**状态：** `STOPPED` → `STARTING` → `SCAN_QR_CODE` → `WORKING` (或在注销时为 `FAILED`)
#### 创建 / 配置会话
```
PUT /api/sessions/:session
Body: { "config": { "webhooks": [{ "url": "https://your-backend/webhook" }] } }
```
创建会话 (如果不存在)，设置 webhook URL，并开始连接。
#### 启动会话
```
POST /api/sessions/:session/start
```
启动一个已配置的会话。如果已经在运行 —— 返回当前状态 (不报错)。
#### 停止会话
```
POST /api/sessions/:session/stop
```
停止会话，从 WhatsApp 登出，并**删除凭据**。下次执行 `start` 将显示新的 QR 码。
#### 登出 (恢复)
```
POST /api/sessions/:session/logout
```
功能同 `stop`，但将会话对象保留在内存中。适用于会话处于 `FAILED` 状态时 —— 登出后，调用 `start` 获取新的 QR 码。
#### 列出所有会话
```
GET /api/sessions
```
返回所有会话状态对象的数组。
### QR 码
```
GET /api/:session/auth/qr
```
仅当会话处于 `SCAN_QR_CODE` 状态时可用。返回 base64 编码的 PNG 图片数据 URL 格式的 QR 码。
```
{ "image": "data:image/png;base64,iVBORw0KGgo..." }
```
### 发送消息
```
POST /api/sendText
Body: { "session": "default", "chatId": "77771234567@c.us", "text": "Hello!" }
```
`chatId` 格式：
- 个人聊天：`@c.us` (例如 `77771234567@c.us`)
- 新式账号：`@lid`
如果会话未处于 `WORKING` 状态，则返回 `{ "success": true }` 或 `500` 错误。
## Webhook Payload
收到的消息将以兼容 WAHA 的格式转发到您配置的 webhook URL：
```
{
"event": "message",
"session": "default",
"payload": {
"from": "77771234567@c.us",
"fromMe": false,
"hasMedia": false,
"body": "Hello!",
"pushName": "John",
"_data": {
"notifyName": "John",
"key": {
"remoteJid": "77771234567@c.us",
"fromMe": false,
"id": "ABCDEF123456"
}
}
}
}
```
自动过滤掉：群组消息 (`@g.us`)、广播消息、纯媒体消息以及发出的消息 (`fromMe: true`)。
## 会话生命周期
```
STOPPED
│ start() called
▼
STARTING
│ Baileys socket created, connecting...
▼
SCAN_QR_CODE ← GET /api/:session/auth/qr available here
│ QR scanned
▼
WORKING ← sendText available here
│
├─ network drop → STARTING → auto-reconnect (5s, 10s, ... up to 60s)
│
└─ user logs out in WA app → FAILED → logout() + start() to recover
```
凭据存储在 `SESSIONS_DIR//` 目录中。持久化此目录 (例如作为 Docker 卷) 意味着会话在重启后无需重新扫描 QR 码即可恢复。
## Docker Compose 示例
```
services:
wa-service:
build: .
ports:
- "3000:3000"
volumes:
- ./sessions:/app/sessions
environment:
WAHA_API_KEY: your-secret-key
LOG_LEVEL: info
restart: unless-stopped
```
## 与 WAHA 的差异
| 功能 | WAHA Free | WAHA Plus ($19/月) | wa-service |
|---|---|---|---|
| 多会话 | ❌ 1 个会话 | ✅ 无限制 | ✅ 无限制 |
| 自托管 | ✅ | ✅ | ✅ |
| QR 码认证 | ✅ | ✅ | ✅ |
| Webhook | ✅ | ✅ | ✅ |
| 发送文本 | ✅ | ✅ | ✅ |
| 发送媒体 | ❌ | ✅ | ❌ (计划中) |
| REST swagger 文档 | ✅ | ✅ | ❌ |
| 价格 | 免费 | $19/月 | 免费 |
## 技术栈
- **[Baileys](https://github.com/WhiskeySockets/Baileys)** — WhatsApp Web 逆向工程客户端
- **Express** — HTTP 服务器
- **Pino** — 结构化日志
- **QRCode** — QR 图像生成
- **Axios** — webhook 投递
标签：API 密钥认证, Baileys, Docker, GNU通用公共许可证, HTTP API, MITM代理, Node.js, Pino 日志, RESTful API, Sessions 持久化, WAHA 替代品, Webhook, WhatsApp API, WhatsApp Web 协议, 二维码认证, 力导向图, 即时通讯, 反向代理, 多会话, 安全防御评估, 开源, 提示词优化, 消息转发, 消息集成, 网络信息收集, 网络调试, 自动化, 自动重连, 自定义脚本, 自托管, 请求拦截, 通信平台