- API 访问:谁可以调用 GOWA。这是HTTP Basic Auth。
- WhatsApp 配对: 将 WhatsApp 帐户链接到设备栏位, 因为你会链接WhatsApp Web.
API 访问:基本认证
基本认证是唯一的 API 认证方法。没有用于REST 调用的 API 密钥或JWT。 设置一个或多个user:password对,逗号分隔:
APP_HOST=0.0.0.0 在凭据不完整时会拒绝启动。如需在本地开发时不使用认证,请绑定 APP_HOST=127.0.0.1。
如果逆向代理认证每个来电者,APP_ALLOW_UNAUTHENTICATED=true 或 --allow-unauthenticated=true 明确允许一个非循环回音监听器而无需基本认证。限制直接访问该监听器。
每次请求时发送凭据:
401 Unauthorized。
基本认证后面没有的内容
其它一切,包括
/、/mcp和/ws的仪表盘,配置时需要基本验证。
WebSocket
浏览器无法在 WebSocket 连接中设置头部,所以/ws 获取查询字符串中的凭据:
authorization 是 base64(user:password) 。使用 TLS (wss://) 并编辑代理日志中的查询字符串。 WebSocket 检查浏览器源与更换状态的 HTTP 请求所使用的相同的信任来源。 当前的 WebSocket 枢纽向所有已连接的套接字播放事件。 一个device_id查询选择设备连接环境,但不隔离事件交付。 使用事件的设备标识符来过滤仪表盘视图,并且只授予所有设备信任的呼叫者API访问。
查看WebSocket 引用 事件代码、有效载荷和客户端示例。
CORS
CORS 默认允许任何来源。使用APP_CORS_ALLOWED_ORIGINS=https://ui.example.com 进行限制(多个来源以逗号分隔)。允许的请求头为 Origin、Content-Type、Accept、Authorization 和 X-Device-Id。
CORS 与浏览器来源检查彼此独立。通配符 CORS 来源不会授权更改状态的请求或 WebSocket 连接。GOWA 信任请求自身的主机、明确指定的 CORS 来源、APP_TRUSTED_ORIGINS,以及为 OAuth 签发者和 Chatwoot 回调 URL 配置的来源。对于单独部署的仪表板,请配置其确切来源:
403 CROSS_SITE_REQUEST_BLOCKED。这也包括登入、注销、重新连接或重置邀请链接的 GET 路由。 客户端,例如无需发送浏览器源头的curl,仍在继续工作。
null 来源永远不会被信任。通过 HTTP 或 HTTPS 提供gowa-ui.html 而不是以 file:// 方式打开它。 在逆向代理后面,保留Host,使用X-Forwarded-Host配置信任代理,或在APP_TRUSTED_ORIGINS中列出公共来源。
WhatsApp 配对
每个 WhatsApp 账号都位于一个设备槽位中。请先创建槽位,再进行配对。/devices/{device_id} 下的路由通过路径指定设备。对应的 /app/* 路由使用 X-Device-Id 请求头。
QR code
qr_link 并从手机扫描它:设置 -> 链接设备 -> 链接设备。 在 qr_duration 秒后请求一个新代码。在 / 中的仪表板直接显示QR 并通过 WebSocket 实时更新。
Pairing code
results.pair_code ,一个8个字符的代码。在手机上选择 链接电话号码 然后键入。 phone 必须是被链接的帐户号码,带有国家代码。
密码
如果在QR登录期间电话请求验证密码,GOWA将在 WebSocket 上存储一个 WebAuthn 挑战和广播PASSKEY_REQUEST 。 仪表盘处理这个流程。要自行驱动它:
GET /app/passkey返回待处理的挑战。POST /app/passkey/response提交了 WebAuthn 断言(PublicKeyCredential.toJSON()格式)。- 等待
PASSKEY_CONFIRMATION。当result.skip_handoff_ux为真时,活动的 QR 流会自动发送确认。 否则将result.code与手机上的代码比较起来,然后调用POST /app/passkey/confirm。
X-Device-Id 。
检查结果
results.is_connected 和 results.is_logged_in 都是true。会话持续在 storages/ 中,所以重新启动不需要配对。
登出并移除
从手机上取消链接的帐户(链接设备-> 注销)将以同样的方式注销:该帐户仍然保留并需要重新配对。
安全清单
- 对于任何可通过网络访问的部署,务必设置
APP_BASIC_AUTH并使用强密码。 - 在逆向代理中终止TLS; 基本认证凭据仅为 base64 编码。
- 当浏览器UI调用API时,限制
APP_CORS_ALLOWED_ORIGINS。 - 生成一个稳定的
WHATSAPP_WEBHOOK_SECRET与openssl rand -hex 32。空或已发布的示例密钥被替换为每个进程的随机密钥,在重启时会更改。 - 将
storages/视为敏感数据。它包含每个已关联账户的会话密钥。新建的 SQLite 文件仅允许所有者访问,为其创建的目录使用0700权限。请同样谨慎地保护备份。
