> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/rmyndharis/OpenWA) · [上游 README](https://github.com/rmyndharis/OpenWA/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

OpenWA Logo

OpenWA

开源 WhatsApp API 网关

特性 • 快速开始 • 文档 • API • 贡献

CI Version License Node NestJS Docker TypeScript

--- ## ✨ 为什么选择 OpenWA？ **OpenWA** 是一款免费、开源的 WhatsApp API 网关（Gateway），面向需要完全掌控消息基础设施、且不愿被厂商锁定或遭遇隐藏付费墙的开发者。 基于**可插拔架构（Pluggable Architecture）**，OpenWA 允许你通过配置更换数据库引擎（SQLite/PostgreSQL）、存储后端（Local/S3）和缓存层（Memory/Redis），而无需修改应用代码中的任何一行。 | | | | ----------------------------- | ------------------------------------------------------------ | | 🔓 **100% 开源** | 无许可费用、无功能锁定、可访问完整源代码 | | 🏗️ **可插拔架构** | 通过配置切换数据库、存储和缓存适配器 | | 🖥️ **完整仪表盘** | 现代化的 React UI，用于管理会话、Webhook 和 API 密钥 | | 🔹 **多会话就绪** | 在单个实例上并发运行多个 WhatsApp 会话 | | 🐳 **原生 Docker 支持** | 开箱即用，可用于生产环境，零配置 | | 🔗 **n8n 集成** | 用于工作流自动化的社区节点 | | 🧩 **社区适配器** | 第三方集成（例如 ioBroker）— 参见 [文档](./docs/23-community-integrations.md) | --- ## 🎯 特性 ### 核心特性 | 特性 | 状态 | 描述 | | ------------- | ------ | ------------------------------------ | | REST API | ✅ | 通过 HTTP 端点提供完整的 WhatsApp API | | 多会话 | ✅ | 管理多个 WhatsApp 账户 | | Webhook | ✅ | 实时事件，支持 HMAC 签名及可选的智能预分发过滤器 | | Web 仪表盘 | ✅ | 可视化管理界面 | | API 密钥认证 | ✅ | 安全的 API 身份验证 | | Swagger 文档 | ✅ | 交互式 API 文档 | ### 消息 | 特性 | 状态 | 描述 | | ----------------- | ------ | -------------------------------- | | 文本消息 | ✅ | 发送/接收文本消息 | | 媒体消息 | ✅ | 图片、视频、文档、音频 | | 消息回应 | ✅ | 使用表情符号回应消息 | | 批量消息 | ✅ | 向多个收件人发送 | | 消息状态 | ✅ | 跟踪送达和已读回执 | ### 高级功能 | 特性 | 状态 | 描述 | | ------------------- | ------ | ---------------------------------- | | 群组 API | ✅ | 创建、管理群组并发送消息 | | 频道/Newsletter | ✅ | 支持 WhatsApp 频道 | | 标签管理 | ✅ | 使用标签整理聊天 | | 代理支持 | ✅ | 按会话配置代理 | | 速率限制 | ✅ | 可配置的请求限制 | | CIDR 白名单 | ✅ | 基于 IP 的访问控制 | | 审计日志 | ✅ | 跟踪所有 API 操作 | ### 基础设施 | 特性 | 状态 | 描述 | | ---------------- | ------ | ------------------------------ | | SQLite | ✅ | 零配置嵌入式数据库 | | PostgreSQL | ✅ | 生产级数据库 | | Redis 缓存 | ✅ | 可选的性能缓存 | | S3/MinIO 存储 | ✅ | 可扩展的媒体存储 | | Docker | ✅ | 一条命令完成部署 | | 健康检查 | ✅ | 适用于 Kubernetes 的探针 | | 数据迁移 | ✅ | 在后端之间导出/导入 | --- ## 🚀 快速开始 ### 方案 A：Docker（推荐） ```bash # Clone and start git clone https://github.com/rmyndharis/OpenWA.git cd OpenWA docker compose -f docker-compose.dev.yml up -d # Access (the dashboard is bundled into the API image and served on the same port) # Dashboard: http://localhost:2785 # API: http://localhost:2785/api # Swagger: http://localhost:2785/api/docs ``` > **使用 Podman 而非 Docker？** > Podman 无 root 模式需要 socket 正在运行，并设置 `DOCKER_HOST`： > > ```bash > systemctl --user start podman.socket > systemctl --user enable podman.socket > export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock > ``` > > 将 `export` 这一行添加到你的 `~/.bashrc` 中，以使其永久生效。 ### 方案 B：本地开发 ```bash # Clone repository git clone https://github.com/rmyndharis/OpenWA.git cd OpenWA # Install dependencies (includes dashboard) npm install # Start API + Dashboard (config is auto-generated on first run) npm run dev # Access (in dev the dashboard runs on the Vite server with hot reload) # Dashboard: http://localhost:2886 # API: http://localhost:2785/api # Swagger: http://localhost:2785/api/docs ``` --- ## 🔒 安全架构 ### Docker Socket 代理 生产环境技术栈绝不会将 `/var/run/docker.sock` 直接暴露给应用容器。相反，一个专用的 `docker-proxy` 边车（sidecar，基于 [`tecnativa/docker-socket-proxy`](https://github.com/Tecnativa/docker-socket-proxy))）作为访问 Docker 守护进程的唯一网关： ``` openwa-api ──TCP 2375──▶ docker-proxy ──unix──▶ /var/run/docker.sock ``` 仅启用容器编排所需的操作（`CONTAINERS`、`IMAGES`、`VOLUMES`、`INFO`、`PING`、`POST`、`DELETE`）。应用通过 `DOCKER_HOST=tcp://docker-proxy:2375` 环境变量连接，`DockerService` 会自动检测该变量。 --- ## 🔒 安全架构 ### 非 root 容器执行 生产镜像绝不会以 root 身份运行 Node.js 进程。启动时，容器遵循以下链路： ``` dumb-init (PID 1) └─ docker-entrypoint.sh (root — fixes named-volume ownership via chown) └─ gosu openwa node dist/main (drops to the openwa user) ``` - **dumb-init** 作为 PID 1，转发信号（SIGTERM 等）以实现优雅关闭。 - **docker-entrypoint.sh** 仅以 root 身份运行足够长的时间，以便 `chown` 命名卷挂载点，使 `openwa` 用户可以写入它们。 - **gosu** 执行基于 `exec` 的干净权限降级 — 不使用 `su` 或 `sudo` 包装器，因此 node 进程是 dumb-init 的直接子进程。 命名卷（例如 `openwa-data`）在每次启动时都会自动修正所有权，因此在创建卷后无需手动执行 `chown` 步骤。 --- ## 🏭 生产部署 生产环境请使用主 `docker-compose.yml`，并可按需启用可选服务： ```bash # Basic production (SQLite, local storage) docker compose up -d # With PostgreSQL database docker compose --profile postgres up -d # Full stack (PostgreSQL, Redis, MinIO) docker compose --profile full up -d ``` | 配置方案（Profile） | 服务 | | ---------- | --------------------- | | `postgres` | PostgreSQL 数据库 | | `redis` | Redis 缓存 | | `minio` | S3 兼容存储 | | `full` | 上述所有服务 | > Dashboard 已打包进 API 镜像，由 NestJS 在 API 端口提供服务，因此无需 profile —— 只要 `openwa-api` 运行，它就始终可用。如需 TLS/公网暴露，请在前方放置你自己的反向代理（nginx、Caddy、云负载均衡器或 k8s Ingress）；参见 `docs/12-troubleshooting-faq.md` 中的 nginx 示例。 > **开发环境 vs 生产环境** > > - 开发环境（`docker-compose.dev.yml`）：SQLite、本地存储，API 提供打包的 dashboard > - 生产环境（`docker-compose.yml`）：可配置数据库，通过 profile 启用可选服务 > > 官方 GHCR 镜像以多架构 manifest 形式发布： > - `linux/amd64` > - `linux/arm64` ## 🔌 端口 | 服务 | 端口 | 说明 | | --------------- | --------------- | --------------------------------------------- | | API & Dashboard | `2785` | REST API + 打包的 Web 仪表盘（同一端口） | | Swagger | `2785/api/docs` | 交互式 API 文档 | | Dashboard (dev) | `2886` | 带热重载的 Vite 开发服务器（`npm run dev`） | --- ## 📡 API 示例 ### 创建会话 ```bash curl -X POST http://localhost:2785/api/sessions \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{"name": "my-bot"}' ``` ### 启动会话并获取二维码 ```bash # Start the session curl -X POST http://localhost:2785/api/sessions/{sessionId}/start \ -H "X-API-Key: YOUR_API_KEY" # Get QR code (scan with WhatsApp) curl http://localhost:2785/api/sessions/{sessionId}/qr \ -H "X-API-Key: YOUR_API_KEY" ``` ### 发送消息 ```bash 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 ```bash 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" }' ``` > **智能过滤器（可选）：** 添加 `filters` 对象，仅在条件匹配（AND）时触发 webhook，例如 `{ "conditions": [{ "field": "sender", "operator": "is", "value": ["1234567890@c.us"] }] }`。 > 字段：`sender` / `recipient` / `body` / `type` / `mentions` / `fromMe` / `hasMedia` / `isGroup`。不带过滤器的 webhook 行为与之前完全一致。完整 schema 请参阅 API 规范。 ## 🤖 MCP Server（AI 智能体） OpenWA 可通过 [Model Context Protocol](https://modelcontextprotocol.io)** so AI agents（Claude、Cursor 等）驱动 WhatsApp。默认**关闭**且为**附加功能** —— 所有 REST 路由保持原样不变。 将 `MCP_ENABLED=true` 设置为在现有服务器的 **`POST /mcp`** 上挂载无状态 Streamable-HTTP 传输（同一端口，无需额外进程）。它暴露约 39 个精选工具（会话、消息、联系人、基础群组操作、webhook 读取）—— 相比完整 API 是精简面，避免智能体不堪重负，并将破坏性操作排除在智能体路径之外。 ```bash MCP_ENABLED=true npm run start:prod # or set MCP_ENABLED in your .env / compose ``` 将 MCP 客户端指向该端点（例如 Claude Code，在项目根目录放置 `.mcp.json`）： ```json { "mcpServers": { "openwa": { "type": "http", "url": "http://localhost:2785/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` 密钥可通过 `Authorization: Bearer …` 或 `X-API-Key: …` 传递。每次工具调用均经过与 REST **相同的 API 密钥认证、角色和按会话作用域**。 **安全指南：** - **为智能体签发专用的最小权限密钥** —— 非管理员、**按会话作用域**的密钥（最多 `OPERATOR` 角色）。明文密钥仅在创建时显示一次；如需轮换，请创建新密钥并删除旧密钥。 - 密钥**不得**携带 IP 允许列表（`allowedIps`）—— MCP 无法获取真实客户端 IP，此类密钥会被拒绝。 - 设置 **`MCP_READONLY=true`** 仅挂载只读工具（无发送/写入）。 - 设置 **`MCP_RATE_LIMIT_MAX`**（默认 `60`）以限制每个 API 密钥在每个时间窗口内的工具调用次数。 - 设置 **`MCP_RATE_LIMIT_WINDOW_MS`**（默认 `60000`）以控制滑动窗口大小（毫秒）。 - **不要在没有前置认证代理的情况下将 `/mcp` 暴露到公网。** 对于自托管、仅本地访问的部署，静态 API 密钥是合适的；公网暴露应使用 OAuth 2.1（尚未实现）。 --- ## 🛠 技术栈 | 层级 | 技术 | | ------------- | ----------------------- | | **Runtime** | Node.js 22 LTS | | **Framework** | NestJS 11.x | | **Language** | TypeScript 5.x | | **WA Engine** | whatsapp-web.js（默认）/ baileys — 通过 `ENGINE_TYPE` 设置 | | **Database** | SQLite / PostgreSQL | | **Cache** | Redis（可选） | | **Storage** | Local / S3 / MinIO | | **ORM** | TypeORM | | **Container** | 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/` 文件夹： | 文档 | 说明 | | ------------------------------------------------------- | ---------------------------- | | [Project Overview](./docs/01-project-overview.md) | 简介与目标 | | [Requirements](./docs/02-requirements-specification.md) | 功能规格说明 | | [Architecture](./docs/03-system-architecture.md) | 系统设计 | | [Security](./docs/04-security-design.md) | 安全实现 | | [Database](./docs/05-database-design.md) | 数据模型与迁移 | | [API Spec](./docs/06-api-specification.md) | 完整 API 参考 | | [Development](./docs/08-development-guidelines.md) | 编码规范 | | [Migration Guide](./docs/14-migration-guide.md) | 数据库与存储迁移 | --- ## 🤝 贡献 欢迎贡献！入门步骤如下： 1. **Fork** 本仓库 2. **创建** 你的功能分支（`git checkout -b feature/amazing-feature`） 3. **提交** 你的更改（`git commit -m 'Add amazing feature'`） 4. **推送** 到该分支（`git push origin feature/amazing-feature`） 5. **打开** Pull Request 请阅读我们的 [Development Guidelines](./docs/08-development-guidelines.md) 了解编码规范与最佳实践。 --- ## 📄 许可证 本项目采用 **MIT License** 许可 —— 可免费用于个人和商业用途。 详见 [LICENSE](./LICENSE)。 ---
**OpenWA** – 免费、开源的 WhatsApp API 网关 [📖 文档](./docs/README.md) · [🔌 API 文档](http://localhost:2785/api/docs) · [🐛 报告 Bug](https://github.com/rmyndharis/OpenWA/issues) · [💡 功能建议](https://github.com/rmyndharis/OpenWA/issues)
由 Yudhi Armyndharis 与 OpenWA 社区用 ❤️ 制作