OpenWA

开源 WhatsApp API 网关

功能特性 • 快速开始 • 文档 • API • 贡献指南

## ✨ 为什么选择 OpenWA？ **OpenWA** 是一个免费、开源的 WhatsApp API 网关，专为需要完全掌控其消息基础设施的开发者设计——没有供应商锁定或隐藏付费墙。 基于 **可插拔架构** 构建，OpenWA 让您可以更换数据库引擎（SQLite/PostgreSQL）、存储后端（本地/S3）和缓存层（内存/Redis），而无需修改一行应用程序代码。 | | | | ----------------------------- | ------------------------------------------------------------ | | 🔓 **100% 开源** | 无许可费，无功能锁，完整源代码访问 | | 🏗️ **可插拔架构** | 通过配置更换数据库、存储和缓存适配器 | | 🖥️ **完整仪表盘** | 现代 React UI，用于会话、Webhook 和 API 密钥管理 | | 🔹 **多会话就绪** | 在一个实例上并发运行多个 WhatsApp 会话 | | 🐳 **Docker 原生支持** | 生产就绪，零配置 | | 🔗 **n8n 集成** | 用于工作流自动化的社区节点 | ## 🎯 功能特性 ### 核心功能 | 功能 | 状态 | 描述 | | ------------- | ------ | ------------------------------------ | | REST API | ✅ | 通过 HTTP 端点访问完整的 WhatsApp API | | 多会话 | ✅ | 管理多个 WhatsApp 账户 | | Webhooks | ✅ | 带有 HMAC 签名的实时事件 | | 网页仪表盘 | ✅ | 可视化管理界面 | | API 密钥认证 | ✅ | 安全的 API 认证 | | Swagger 文档 | ✅ | 交互式 API 文档 | ### 消息传递 | 功能 | 状态 | 描述 | | ----------------- | ------ | -------------------------------- | | 文本消息 | ✅ | 发送/接收文本消息 | | 媒体消息 | ✅ | 图片、视频、文档、音频 | | 消息回应 | ✅ | 使用表情符号回应消息 | | 批量消息 | ✅ | 发送给多个收件人 | | 消息状态 | ✅ | 跟踪送达和已读回执 | ### 高级功能 | 功能 | 状态 | 描述 | | ------------------- | ------ | ---------------------------------- | | 群组 API | ✅ | 创建、管理和向群组发送消息 | | 频道/新闻通讯 | ✅ | 支持 WhatsApp Channels | | 标签管理 | ✅ | 使用标签组织聊天 | | 代理支持 | ✅ | 基于会话的代理配置 | | 速率限制 | ✅ | 可配置的请求限制 | | CIDR 白名单 | ✅ | 基于 IP 的访问控制 | | 审计日志 | ✅ | 跟踪所有 API 操作 | ### 基础设施 | 功能 | 状态 | 描述 | | ---------------- | ------ | ------------------------------ | | SQLite | ✅ | 零配置嵌入式数据库 | | PostgreSQL | ✅ | 生产级数据库 | | Redis 缓存 | ✅ | 可选的性能缓存 | | S3/MinIO 存储 | ✅ | 可扩展的媒体存储 | | Docker | ✅ | 单命令部署 | | 健康检查 | ✅ | Kubernetes 就绪的探测探针 | | 数据迁移 | ✅ | 后端之间导出/导入 | ## 🚀 快速开始 ### 选项 A：Docker（推荐） ``` # 克隆并启动 git clone https://github.com/rmyndharis/OpenWA.git cd OpenWA 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 # Swagger: http://localhost:2785/api/docs ``` ## 🏭 生产部署 对于生产环境，请使用主 `docker-compose.yml` 文件，其中包含可选服务： ``` # 基础生产环境（SQLite，本地存储） docker compose up -d # 使用 PostgreSQL 数据库 docker compose --profile postgres up -d # 全栈部署（PostgreSQL, Redis, Dashboard, Traefik） docker compose --profile full up -d ``` | 配置文件 | 服务 | | ---------------- | --------------------- | | `postgres` | PostgreSQL 数据库 | | `redis` | Redis 缓存 | | `minio` | S3 兼容存储 | | `with-dashboard` | 网页仪表盘 | | `with-proxy` | Traefik 反向代理 | | `full` | 以上所有服务 | ## 🔌 端口 | 服务 | 端口 | 描述 | | --------- | --------------- | ------------------------ | | API | `2785` | REST API 端点 | | 仪表盘 | `2886` | 网页管理界面 | | Swagger | `2785/api/docs` | 交互式 API 文档 | ## 📡 API 示例 ### 创建会话 ``` curl -X POST http://localhost:2785/api/sessions \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{"name": "my-bot"}' ``` ### 启动会话 & 获取二维码 ``` # 启动会话 curl -X POST http://localhost:2785/api/sessions/{sessionId}/start \ -H "X-API-Key: YOUR_API_KEY" # 获取二维码（使用 WhatsApp 扫描） 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": "628123456789@c.us", "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" }' ``` ## 🛠 技术栈 | 层 | 技术 | | ------------- | ----------------------- | | **运行时** | Node.js 22 LTS | | **框架** | NestJS 11.x | | **语言** | TypeScript 5.x | | **WA 引擎** | whatsapp-web.js | | **数据库** | SQLite / PostgreSQL | | **缓存** | Redis（可选） | | **存储** | 本地 / S3 / MinIO | | **ORM** | TypeORM | | **容器** | Docker + Docker Compose | ## 📁 项目结构 ``` openwa/ ├── src/ │ ├── main.ts # Application entry point │ ├── app.module.ts # Root module │ ├── config/ # Configuration │ ├── common/ # Shared utilities │ │ ├── cache/ # Redis caching │ │ └── storage/ # File storage (Local/S3) │ ├── core/ # Core systems │ │ ├── hooks/ # Plugin hooks │ │ └── plugins/ # Plugin system │ ├── engine/ # WhatsApp engine abstraction │ └── modules/ │ ├── session/ # Session management │ ├── message/ # Message handling │ ├── webhook/ # Webhook management │ ├── group/ # Groups API │ ├── contact/ # Contacts API │ ├── auth/ # API key authentication │ ├── infra/ # Infrastructure management │ └── health/ # Health checks ├── dashboard/ # React web dashboard ├── docs/ # Documentation ├── docker-compose.yml ├── Dockerfile └── package.json ``` ## 📚 文档 全面的文档位于 `docs/` 文件夹中： | 文档 | 描述 | | ------------------------------------------------------- | ---------------------------- | | [项目概述](./docs/01-project-overview.md) | 介绍和目标 | | [需求](./docs/02-requirements-specification.md) | 功能规格 | | [架构](./docs/03-system-architecture.md) | 系统设计 | | [安全](./docs/04-security-design.md) | 安全实现 | | [数据库](./docs/05-database-design.md) | 数据模型和迁移 | | [API 规范](./docs/06-api-specification.md) | 完整的 API 参考 | | [开发](./docs/08-development-guidelines.md) | 编码标准 | | [迁移指南](./docs/14-migration-guide.md) | 数据库和存储迁移 | ## 📄 许可证 本项目采用 **MIT 许可证** – 可免费用于个人和商业用途。 详情请参见 [LICENSE](./LICENSE)。

标签：API 网关, Docker, GNU通用公共许可证, MITM代理, NestJS, Node.js, TypeScript, Webhook, WhatsApp API 网关, 云存储, 免费开源软件, 力导向图, 即时通讯, 可插拔架构, 多会话支持, 威胁情报, 安全插件, 安全防御评估, 开发者工具, 开源, 搜索引擎查询, 数据库集成, 测试用例, 消息传递, 漏洞探索, 管理仪表板, 缓存技术, 网络测绘, 自动化攻击, 自托管, 请求拦截, 通信平台