惯性聚合 高效追踪和阅读你感兴趣的博客、新闻、科技资讯
阅读原文 在惯性聚合中打开

推荐订阅源

GbyAI
GbyAI
Simon Willison's Weblog
Simon Willison's Weblog
Microsoft Security Blog
Microsoft Security Blog
Y
Y Combinator Blog
The GitHub Blog
The GitHub Blog
Engineering at Meta
Engineering at Meta
F
Fortinet All Blogs
OSCHINA 社区最新新闻
OSCHINA 社区最新新闻
A
About on SuperTechFans
Last Week in AI
Last Week in AI
月光博客
月光博客
有赞技术团队
有赞技术团队
P
Proofpoint News Feed
MyScale Blog
MyScale Blog
Martin Fowler
Martin Fowler
钛媒体:引领未来商业与生活新知
钛媒体:引领未来商业与生活新知
C
Check Point Blog
U
Unit 42
The Register - Security
The Register - Security
奇客Solidot–传递最新科技情报
奇客Solidot–传递最新科技情报
Cyber Security Advisories - MS-ISAC
Cyber Security Advisories - MS-ISAC
Hugging Face - Blog
Hugging Face - Blog
阮一峰的网络日志
阮一峰的网络日志
V
Visual Studio Blog
酷 壳 – CoolShell
酷 壳 – CoolShell
D
DataBreaches.Net
WordPress大学
WordPress大学
aimingoo的专栏
aimingoo的专栏
H
Hacker News: Front Page
Recent Announcements
Recent Announcements
C
CXSECURITY Database RSS Feed - CXSecurity.com
Latest news
Latest news
小众软件
小众软件
P
Palo Alto Networks Blog
PCI Perspectives
PCI Perspectives
Security Latest
Security Latest
S
Secure Thoughts
Scott Helme
Scott Helme
Threat Intelligence Blog | Flashpoint
Threat Intelligence Blog | Flashpoint
T
Threat Research - Cisco Blogs
P
Proofpoint News Feed
M
MIT News - Artificial intelligence
Application and Cybersecurity Blog
Application and Cybersecurity Blog
Google DeepMind News
Google DeepMind News
Recorded Future
Recorded Future
O
OpenAI News
S
Securelist
云风的 BLOG
云风的 BLOG
H
Help Net Security
T
Troy Hunt's Blog

BlogFinder

日常漫步 Vol.24 之漫步前山河 - 雅余 周报 #1-聊聊本周的收获 - Edwin's Blog 我的OpenCode必装插件与Skill Write Something 掌中之物未必在掌握之中 · CRIVU PiliNara,一个更顺手的 PiliPlus 分支 「NekoEcho」:做一个必有回响的猫娘主题博客 2026-05 书影音总结 简化博客主题 - 安迪 我第一次发布 npm 包 拾花小记#45:中考前的二三事 – 小改学习志 黛西花园5月游 #18 枇杷又熟了的五月月报 一些奇奇怪怪的需求?word仿方正书版的几个小操作 - Xiobb's Blog 0419 御温泉之旅 修复了一些bug,网站基本上趋于稳定了 - 新锐博客 又回到四十年前 如何定义成功 迷鹿屋2026已重新上线 科技冰火两重天+一周回顾 ${title} 热度退了,我反而用得更深了-咕咚同学 我到底该不该换个域名? 随身WIFI折腾记 - 安迪 博客撰写体验提升——hexo pro插件 为什么不用相机把屏幕上的接关密码拍下来? 国清寺与天台山 – Ouroboros ★★★★☆《挽救计划》——久违的经济上行感 - Davidの3号基地 删除右键“打开方式”里多余选项 第三周刊_No.53|一切都会被支付两次 安卓APP通话记录与录音上传踩坑记录 - 子舒的博客 天量下跌 inBox 笔记 2.3.8,把工具栏交给了你-咕咚同学 我把小龙虾搬到了微信-咕咚同学 安好 - 响石潭 Compound Engineering Plugin:让每个工程单元都比上一个更容易 MOSS-TTS Family:开源高质量语音与声音生成模型家族深度解析 Crawl4AI:专为 LLM 设计的开源 Web 爬虫与数据抓取工具 Build Your Own X:从零实现你最喜欢的技术——程序员进阶的终极资源清单 Anthropic Skills:用文件夹教 Claude 专业技能的开源框架 1年的去月球(下) - 梅之夏 欢迎回来。 简单讲讲 ASN.1 与 OID DTV - 直播聚合客户端 5.22-5.27 – 不兴江 还没去过鸭川 – 不兴江 张晶晶同学三刷林志颖 关于我 – 不兴江 爱与嫉妒 – 不兴江 港股被持续做空 备案码花了四百块-咕咚同学 一句话生成封面:我给公众号做了4种风格的AI封面生成技能 「官」方認證 再谈费曼学习法 2026-05-28T00:34:11+08:00 2026-05-28T00:28:45+08:00 离谱的英语学习指南:基于AI的英语进阶系统方法论 iii:零集成架构的后端统一运行时 Claude Code Harness:让 Claude Code 工作有迹可循的工程化框架 Heretic:全自动移除大语言模型审查机制的开源工具 MarkItDown:微软开源的万能文档转 Markdown 利器 Harness:让 Claude Code 秒变多智能体协作工厂 这段时间尽折腾AI Agent了,确实极大地提高了效率 近期动态:两个新站点正式上线啦 误判解除!zhouayuan.com 腾讯安全申诉成功 - 周阿源|玩具设计・插画日常・生活随笔 Ralph:让 AI 编码工具自主循环跑完所有 PRD 任务的量产神器 全都违法 – 个人工作记录 关于zhouayuan.com被误判 “含违规信息” 的说明与申诉记录 - 周阿源|玩具设计・插画日常・生活随笔 小米 MiMo v2.5 Pro 白嫖 最大的人间清醒,兜里有钱,但是不花。 夜晚靓歌(12):于文文现场solo - 王志勇的Blog 今日插画:风扬起的倔强 - 周阿源|玩具设计・插画日常・生活随笔 回门习俗 独立网卡 - 忘记了回忆 500亿入股人工智能企业 从命令行到桌面智能体-咕咚同学 第一性原理读书笔记 行者微评论223-加班の守株待兔-博客|政治与时事-风雨行者 ZOZO开源物理接触求解器:GPU加速的可扩展仿真引擎 OpenStock:开源股票市场交易平台技术深度解析 MoneyPrinterTurbo:基于AI的全自动短视频生成工具深度解析 Claude-Mem:为 Claude Code 构建的持久化记忆压缩系统 Twenty:可代码化定制的企业级开源 CRM 平台技术深度解析 2026-05-26T22:59:17+08:00 企业级开源大模型部署平台 GPUStack 实战教程 1年的去月球(上) - 梅之夏 Sevalla - 静态网站托管服务 不用翻墙、不用注册、不用月费,普通人也能用上 Claude Code 装修灯具要注意⚠️ 黄梅天先锋 - 游子微博 公安备案顺利办结,站点备案全部完成 - 周阿源|玩具设计・插画日常・生活随笔 第三次兑换天猫超市卡了宗宗酱-三维狐少儿编程 Don't think, feel. - Rolen's Blog 人这一辈子,到底图个什么 博客迁移 - Edwin's Blog 情感赛道写作模板 再现本轮行情的典型特征 裁员与平常心-咕咚同学 别让“偷懒”,成为隐私泄露的破绽 片刻 - Jdeal | Life is like a Design.
OpenWA:开源 WhatsApp API 网关,彻底摆脱商业短信 API 的枷锁
Cheman · 2026-06-17 · via BlogFinder

今天在 GitHub Trending 上看到一个有意思的项目:OpenWA,一个完全开源、自托管的 WhatsApp API 网关。如果你曾经被商业消息 API 的昂贵费用、功能锁定和隐私顾虑所困扰,这个项目可能会成为你的新选择。

一、项目概述

OpenWA(Open WhatsApp API Gateway)是一个为开发者设计的开源 WhatsApp 消息网关,旨在让你完全掌控消息基础设施,告别供应商锁定和隐藏付费墙。

核心定位:为需要程序化发送 WhatsApp 消息的场景提供免费、可自托管的 HTTP API 层。

解决的核心问题

  1. 商业 WhatsApp Business API 的高门槛:官方 API 需要企业验证、费用不菲,且功能受限于 Meta 的审核
  2. whatsapp-web.js 缺乏生产级封装:直接使用的库虽然强大,但缺少多会话管理、Webhook、Dashboard 等企业级功能
  3. 消息基础设施的黑盒化:商业 SaaS 方案让你无法掌控数据流向、存储位置和可靠性

核心特性一览

特性说明
🔓 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成熟稳定,社区活跃,支持多会话
ORMTypeORM数据库无关,支持 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

三、安装与快速开始

环境要求

  • Docker 20.10+(推荐方式)
  • 或 Node.js 22 LTS + npm 10+

方式 A:Docker 部署(推荐)

# 克隆仓库
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

方式 B:本地开发

# 克隆仓库
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

最简运行示例

  1. 打开 Dashboard (http://localhost:2886)
  2. 创建 API Key(设置 → API Keys)
  3. 创建 Session(会话 → 新建)
  4. 启动 Session,扫描二维码(用 WhatsApp 手机端扫描)
  5. 会话状态变为 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!"
  }'

进阶用法:配置 Webhook 实现实时事件推送

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 } }
  );
}

生产部署:使用 PostgreSQL + Redis

# 使用生产 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 installwhatsapp-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_HOMEXDG_CACHE_HOME 环境变量修复。如果使用旧版本,请确保使用最新 Dockerfile,或手动在容器中创建 /home/openwa 目录。

会话频繁断开

问题:WhatsApp 会话经常断开,需要重新扫码。

原因

  1. WhatsApp Web 限制:同一账号最多 4 个活跃会话
  2. 网络不稳定导致心跳失败
  3. 会话数据未持久化

解决方案

  • 确保 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 的生产级架构,而无需修改一行业务代码。

适合场景

  • 需要程序化发送 WhatsApp 消息的 SaaS 产品
  • 客服系统、营销自动化、通知推送
  • 对数据主权和隐私有严格要求的企业

不适合场景

  • 需要官方 WhatsApp Business API 的绿色勾勾认证
  • 超大规模发送(whatsapp-web.js 基于网页协议,有速率限制)

项目亮点

  1. 生产级 Docker 编排:非 root 运行、dumb-init PID 1、docker-proxy 安全隔离
  2. 完整的前后端分离:React Dashboard + NestJS API,开箱即用
  3. 活跃的社区集成:n8n 节点、ioBroker 适配器

如果你正为商业消息 API 的高昂费用而头疼,或者希望完全掌控消息数据,OpenWA 绝对值得一试。项目遵循 MIT 协议,你可以自由修改、部署、甚至集成到自己的产品中。

GitHub: https://github.com/rmyndharis/OpenWA


本文基于 OpenWA v0.2.7 的 README 和源代码分析撰写。