跳转到主要内容
妇女事务局有两种单独的认证类型:
  1. API 访问:谁可以调用 GOWA。这是HTTP Basic Auth。
  2. 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 。 仪表盘处理这个流程。要自行驱动它:
  1. GET /app/passkey 返回待处理的挑战。
  2. POST /app/passkey/response 提交了 WebAuthn 断言(PublicKeyCredential.toJSON() 格式)。
  3. 等待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 权限。请同样谨慎地保护备份。