






























今天在 GitHub Trending 上看到一个有意思的项目:OpenWA,一个完全开源、自托管的 WhatsApp API 网关。如果你曾经被商业消息 API 的昂贵费用、功能锁定和隐私顾虑所困扰,这个项目可能会成为你的新选择。
OpenWA(Open WhatsApp API Gateway)是一个为开发者设计的开源 WhatsApp 消息网关,旨在让你完全掌控消息基础设施,告别供应商锁定和隐藏付费墙。
核心定位:为需要程序化发送 WhatsApp 消息的场景提供免费、可自托管的 HTTP API 层。
解决的核心问题:
核心特性一览:
| 特性 | 说明 |
|---|---|
| 🔓 100% 开源 | MIT 协议,无功能锁,完整源代码访问 |
| 🏗️ 可插拔架构 | 数据库、存储、缓存均可通过配置切换,无需改代码 |
| 🖥️ 完整 Dashboard | 现代 React UI,管理会话、Webhook、API Key |
| 🔹 多会话并发 | 单实例运行多个 WhatsApp 账号 |
| 🐳 Docker 原生 | 生产级容器化,零配置启动 |
| 🔗 n8n 集成 | 社区节点支持工作流自动化 |
OpenWA 采用经典的分层架构,基于 NestJS 框架构建:
┌─────────────────────────────────────────────┐
│ REST API (HTTP 2785) │
│ Sessions / Messages / Groups / Webhooks │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ Core Modules (NestJS) │
│ ├─ SessionModule (多会话管理) │
│ ├─ MessageModule (消息收发) │
│ ├─ WebhookModule (事件推送) │
│ ├─ AuthModule (API Key 认证) │
│ └─ InfraModule (基础设施编排) │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ Engine Abstraction Layer │
│ whatsapp-web.js (WA Engine 抽象接口) │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ Pluggable Adapters (可插拔适配器) │
│ ├─ Database: SQLite / PostgreSQL │
│ ├─ Storage: Local / S3 / MinIO │
│ └─ Cache: Memory / Redis │
└─────────────────────────────────────────────┘
| 层级 | 技术 | 选型理由 |
|---|---|---|
| 运行时 | Node.js 22 LTS | 长期支持版本,稳定性保障 |
| 框架 | NestJS 11.x | 依赖注入、模块化、Swagger 集成开箱即用 |
| 语言 | TypeScript 5.x | 类型安全,大型项目可维护性 |
| WA 引擎 | whatsapp-web.js | 成熟稳定,社区活跃,支持多会话 |
| ORM | TypeORM | 数据库无关,支持 SQLite/PostgreSQL 无缝切换 |
| 容器 | Docker + Compose | 生产级编排,支持多 Profile 部署 |
OpenWA 的核心设计哲学是适配器模式。以数据库为例:
// 数据库适配器接口 (简化示意)
interface IDatabaseAdapter {
connect(config: DBConfig): Promise<void>;
getRepository<T>(entity: Entity): Repository<T>;
}
// SQLite 适配器
class SqliteAdapter implements IDatabaseAdapter {
async connect(config: DBConfig) {
return createConnection({
type: 'sqlite',
database: config.sqlite.path,
// ...
});
}
}
// PostgreSQL 适配器
class PostgresAdapter implements IDatabaseAdapter {
async connect(config: DBConfig) {
return createConnection({
type: 'postgres',
host: config.postgres.host,
// ...
});
}
}
通过 ConfigModule 读取环境变量,动态注入对应的适配器实例,应用层代码完全无感知。
发送消息流程:
HTTP Request (POST /api/sessions/{id}/messages/send-text)
↓
AuthGuard (验证 X-API-Key)
↓
MessageController
↓
MessageService (业务逻辑)
↓
SessionService (获取 WA 客户端实例)
↓
WhatsAppEngine (whatsapp-web.js)
↓
WhatsApp Web 协议
↓
目标聊天 ([email protected])
Webhook 事件流程:
WhatsApp 收到消息
↓
whatsapp-web.js 触发事件 (message_create)
↓
WebhookService 捕获事件
↓
过滤订阅了此事件的 Webhook 配置
↓
HMAC-SHA256 签名 (可选 secret)
↓
HTTP POST 到配置的 URL
# 克隆仓库
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
# 启动开发环境(SQLite + 本地存储)
docker compose -f docker-compose.dev.yml up -d
# 访问服务
# Dashboard: http://localhost:2886
# API: http://localhost:2785/api
# Swagger 文档: http://localhost:2785/api/docs
# 克隆仓库
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
# 安装依赖(会自动安装 Dashboard 前端依赖)
npm install
# 启动开发模式(API + Dashboard 同时启动)
npm run dev
# 访问
# Dashboard: http://localhost:2886
# API: http://localhost:2785/api
http://localhost:2886)CONNECTED 后即可发送消息# 创建会话
curl -X POST http://localhost:2785/api/sessions \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"name": "my-bot"}'
# 启动会话(返回 sessionId)
# 获取 QR 码并扫描
curl http://localhost:2785/api/sessions/{sessionId}/qr \
-H "X-API-Key: YOUR_API_KEY"
# 发送消息
curl -X POST http://localhost:2785/api/sessions/{sessionId}/messages/send-text \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"chatId": "[email protected]",
"text": "Hello from OpenWA!"
}'
curl -X POST http://localhost:2785/api/sessions/{sessionId}/webhooks \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"url": "https://your-server.com/webhook",
"events": ["message.received", "session.status"],
"secret": "your-hmac-secret"
}'
Webhook 请求会带上 HMAC 签名,接收端可以验证:
// Webhook 接收端示例 (Node.js/Express)
app.post('/webhook', (req, res) => {
const signature = req.headers['x-openwa-signature'];
const payload = JSON.stringify(req.body);
const expected = crypto
.createHmac('sha256', 'your-hmac-secret')
.update(payload)
.digest('hex');
if (signature !== expected) {
return res.status(401).send('Invalid signature');
}
// 处理事件
console.log('Event:', req.body.event);
res.status(200).send('OK');
});
// 使用 OpenWA API 构建简单客服机器人
import axios from 'axios';
const API_BASE = 'http://localhost:2785/api';
const API_KEY = 'YOUR_API_KEY';
const SESSION_ID = 'your-session-id';
// 监听 webhook 事件 (message.received)
async function handleIncomingMessage(event: any) {
const { from, body } = event.data;
// 简单关键词回复
let reply = '';
if (body.includes('你好') || body.includes('hello')) {
reply = '您好!我是客服机器人,请问有什么可以帮您?';
} else if (body.includes('价格') || body.includes('price')) {
reply = '我们的产品价格为 $99/年,详情请访问 https://example.com';
} else {
reply = '感谢您的留言,我们会尽快回复您。';
}
// 发送回复
await axios.post(
`${API_BASE}/sessions/${SESSION_ID}/messages/send-text`,
{ chatId: from, text: reply },
{ headers: { 'X-API-Key': API_KEY } }
);
}
# 使用生产 Profile(PostgreSQL + Redis + MinIO)
docker compose --profile full up -d
# 或直接指定 Profile
docker compose --profile postgres --profile redis up -d
配置文件 .env:
# 数据库
DATABASE_PROVIDER=postgres
DATABASE_HOST=postgres
DATABASE_PORT=5432
DATABASE_USER=openwa
DATABASE_PASSWORD=secret
DATABASE_NAME=openwa
# 缓存
CACHE_PROVIDER=redis
REDIS_HOST=redis
REDIS_PORT=6379
# 存储
STORAGE_PROVIDER=s3
S3_ENDPOINT=http://minio:9000
S3_BUCKET=openwa-media
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
问题:npm install 时 whatsapp-web.js 构建失败。
原因:需要系统有 Python 3、make、g++ 等构建工具(用于编译原生模块)。
解决方案:
# macOS
xcode-select --install
# Ubuntu/Debian
sudo apt-get install python3 make g++
# 然后重新安装
rm -rf node_modules package-lock.json
npm install
问题:Docker 启动后,Chrome/Chromium 崩溃(日志显示 SIGTRAP / chrome_crashpad_handler)。
原因:OpenWA 使用非 root 用户运行,但 Chromium 尝试访问不存在的 home 目录。
解决方案:此问题在 v0.2.7 中已通过 XDG_CONFIG_HOME 和 XDG_CACHE_HOME 环境变量修复。如果使用旧版本,请确保使用最新 Dockerfile,或手动在容器中创建 /home/openwa 目录。
问题:WhatsApp 会话经常断开,需要重新扫码。
原因:
解决方案:
data/sessions 目录已挂载为卷(Docker)SESSION_RECONNECT_ATTEMPTS=5(自动重连)问题:发送大量消息时 API 响应变慢。
原因:未启用缓存,或数据库 I/O 瓶颈。
解决方案:
# 启用 Redis 缓存
docker compose --profile redis up -d
# 配置限流(防止过载)
RATE_LIMIT_TTL=60
RATE_LIMIT_LIMIT=100
问题:Node.js 版本不兼容。
解决方案:OpenWA 要求 Node.js 22 LTS。使用 nvm 切换版本:
nvm install 22
nvm use 22
OpenWA 是一个非常务实的开源项目,它巧妙地封装了 whatsapp-web.js,填补了"库"和"生产级服务"之间的空白。其可插拔架构设计尤其值得称道——你可以从最简单的 SQLite 单机部署起步,随业务增长无缝迁移到 PostgreSQL + Redis + S3 的生产级架构,而无需修改一行业务代码。
适合场景:
不适合场景:
项目亮点:
如果你正为商业消息 API 的高昂费用而头疼,或者希望完全掌控消息数据,OpenWA 绝对值得一试。项目遵循 MIT 协议,你可以自由修改、部署、甚至集成到自己的产品中。
GitHub: https://github.com/rmyndharis/OpenWA
本文基于 OpenWA v0.2.7 的 README 和源代码分析撰写。
此内容由惯性聚合(RSS阅读器)自动聚合整理,仅供阅读参考。 原文来自 — 版权归原作者所有。