> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装

> 通过 Docker Compose, Docker Compose, 发行二进制或从源代码安装GOWA, 然后用反向代理运行它。

![GOWA 部署和访问概述](https://mintcdn.com/gowa-docs/xwa06XWUO2vnG9_f/images/GOWA-Deployment-and-Access-Overview.png?fit=max\&auto=format\&n=xwa06XWUO2vnG9_f\&q=85\&s=dc847e074e7578d3cfb8c83f1d756040)

GOWA 以单个二进制文件分发。REST API、Webhook、仪表板和 MCP 端点均通过 `whatsapp rest` 启动。

## B. 所需经费

| 项目 | 需要为 |
| - | - |
| FFmpeg | 媒体转换(视频，语音记号)。包含在Docker图像中。 |
| libwebp 工具 (`cwebp`, `dwebp`, `webpmux`) | 貼圖，包括动画 WebP 已包含在 Docker 圖像中。 |
| 去1.26+ | 仅从源代码构建。 |

支持的平台：Linux (amd64, arm64, armv7, 386), macOS (Intel, Apple Silicon), Windows (amd64, 386; WSL 推荐)。

## 停靠栏

图片已发布到 Docker Hub 和 GHCR：

* `aldinokemal2104/go-whatsapp-web-multidevice`
* `ghcr.io/aldinokemal/go-whatsapp-web-multidevice`

```bash theme={null}
docker volume create gowa_storages
docker volume create gowa_statics

docker run -d --name gowa --restart always \
  -p 3000:3000 \
  -v gowa_storages:/app/storages \
  -v gowa_statics:/app/statics \
  -e APP_BASIC_AUTH=admin:changeme \
  aldinokemal2104/go-whatsapp-web-multidevice:latest
```

* `/app/storages` 持有SQLite 数据库 (会话、 聊天历史、 schedules, OAuth)。每个设备都丢失它。
* `/app/statics`持有QR图像、上传和下载的媒体。
* 默认命令为 `rest`。请在它之后传递标志，例如 `... go-whatsapp-web-multidevice rest --autoreply="Away"`。
* 切入点修正音量所有权，并将权限移至`gowauser` (UID 20001, GID 20000)。
* 容器时间是 UTC (`TZ=UTC`)。如果你需要本地日志时间戳，则覆盖`TZ`。

### Docker 配置

```yaml docker-compose.yml theme={null}
services:
  gowa:
    image: aldinokemal2104/go-whatsapp-web-multidevice:latest
    container_name: gowa
    restart: always
    ports:
      - "3000:3000"
    environment:
      APP_BASIC_AUTH: admin:changeme
      WHATSAPP_WEBHOOK: https://example.com/wa-hook
      WHATSAPP_WEBHOOK_SECRET: ${WHATSAPP_WEBHOOK_SECRET}
    volumes:
      - gowa_storages:/app/storages
      - gowa_statics:/app/statics

volumes:
  gowa_storages:
  gowa_statics:
```

使用 `openssl rand -hex 32` 生成稳定的 webhook 密钥，并在你的 shell 或 Compose `.env` 中设置`WHATSAPP_WEBHOOK_SECRET` ，然后再开始这个例子。

这个仓库自己的`docker-compose.yml`可以从 `docker/golang.Dockerfile` 构建图像并读取`src/.env`。当你想要本地构建时使用它：`cp src/.env.example src/.env && docker compose up -d --build`。

## 释放二进制文件

从 [GitHub Releases](https://github.com/aldinokemal/go-whatsapp-web-multidevice/releases/latest) 下载压缩包。压缩包的命名格式为 `whatsapp_<version>_<os>_<arch>.zip`，例如：

```bash theme={null}
curl -fLO https://github.com/aldinokemal/go-whatsapp-web-multidevice/releases/download/v9.9.0/whatsapp_9.9.0_linux_amd64.zip
unzip whatsapp_9.9.0_linux_amd64.zip
chmod +x whatsapp
./whatsapp rest --basic-auth=admin:replace-with-a-strong-password
```

在主机上安装媒体工具：

```bash theme={null}
# Debian/Ubuntu
sudo apt install ffmpeg webp
# macOS
brew install ffmpeg webp
```

使用同一版本的 `checksums.txt` 验证下载；`./whatsapp version` 打印版本；`./whatsapp --help` 列出每个标记。

## 从来源

```bash theme={null}
git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice.git
cd go-whatsapp-web-multidevice/src
cp .env.example .env    # optional
go build -o whatsapp
./whatsapp rest --basic-auth=admin:replace-with-a-strong-password
```

在 macOS 上，构建前还需执行 `export CGO_CFLAGS_ALLOW="-Xpreprocessor"`。

### 没有C工具链的ARM

`purego` 构建标签选择了一个 pure-Go SQLite 驱动程序，所以您可以使用 CGO 交叉编译：

```bash theme={null}
# Raspberry Pi 2/3/4 (ARMv7)
CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -tags purego -o whatsapp-armv7
# Raspberry Pi Zero/1 (ARMv6)
CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=6 go build -tags purego -o whatsapp-armv6
```

## 存储

默认情况下，所有都是 `storages/`下的 SQLite ：

| 数据 | 默认设置 | 设置 |
| - | - | - |
| WhatsApp 会话和密钥 | `file:storages/whatsapp.db` | `DB_URI` |
| 会话密钥缓存 (可选，独立的DB) | uses `DB_URI` | `DB_KEYS_URI` |
| 聊天历史记录、设备注册表、计划 | `file:storages/chatstorage.db` | 不可配置 |
| MCP OAuth 客户端和令牌 | `file:storages/oauth.db` | `MCP_OAUTH_DB_URI` |

`DB_URI` 也接受 PostgreSQL 语句，例如`postgres://user:pass@host:5432/gowa?sslmode=verify-full` 。远程PostgreSQL 会话保存默认证书验证时未设置有效的 TLS 模式。 明确的 URI、环境或 PostgreSQL 服务 TLS 设置仍然适用。请参阅[存储配置](https://gowa-docs.mintlify.site/zh/configuration.md#%E5%AD%98%E5%82%A8)。

GOWA 创建 SQLite 文件，拥有所有者唯一的 `0600` 权限和新的 `0700` 父目录。现有目录保留其权限。 备份`storages/` (或PostgreSQL加`storages/`)以在重建过程中保持配对的设备。将这些备份作为凭据处理。

## 反向代理

通过 `APP_BASE_PATH` 服务到 GOWA 的子路径，并且信任代理的转发信头和`APP_TRUSTED_PROXIES`：

```bash theme={null}
./whatsapp rest --basic-auth=admin:replace-with-a-strong-password \
  --base-path=/gowa --trusted-proxies=10.0.0.0/8
```

```nginx theme={null}
location /gowa/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;     # WebSocket at /gowa/ws
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    client_max_body_size 100m;                  # largest upload GOWA accepts
}
```

`/health` 停留在根目录下(`/health` ，而不是`/gowa/health` )，所以不论基础路径，都可以工作。

浏览器来源防护需要获取公共主机信息。请按上文所示保留 `Host`，或通过受信任的代理发送 `X-Forwarded-Host`。单独托管的仪表板需要在 `APP_TRUSTED_ORIGINS` 或 `APP_CORS_ALLOWED_ORIGINS` 中配置其确切来源。通配符不会授权更改状态的操作或 WebSocket 连接。请通过 HTTP 或 HTTPS 提供仪表板，因为 `file://` 页面的来源为不受信任的 `null`。

默认监听器拒绝在没有完整基本认证凭据的情况下启动。 只有当代理认证来电者和客户端无法绕过时，才启用`APP_ALLOW_UNAUTHENTICATED=true`。对于没有认证的本地开发，绑定`APP_HOST=127.0.0.1`。

## 验证

```bash theme={null}
curl http://localhost:3000/health                      # OK, no auth needed
curl -u admin:changeme http://localhost:3000/app/info  # server info, no device needed
curl -u admin:changeme http://localhost:3000/devices   # registered devices
```

存储初始化完成后，`/health` 会返回 `OK`。它不会报告是否有 WhatsApp 账号已连接；如需查看连接状态，请使用 `GET /devices/{device_id}/status`。

## 升级

备份 `storages/`，拉取新镜像或二进制文件，然后重启。请先阅读[发行说明](https://github.com/aldinokemal/go-whatsapp-web-multidevice/releases)，了解不兼容的变更。值得注意的变更包括：v6 强制要求使用 `rest` 子命令；v7 将二进制文件移至 GoReleaser 归档文件中；v8 增加了多设备支持（一旦存在多个设备，针对设备的调用就需要 `X-Device-Id`）；独立的 `whatsapp mcp` 模式（`:8080/sse`）已被 REST 服务器上的 `/mcp` 端点取代。


## Related topics

- [媒体处理](https://gowa-docs.mintlify.site/zh/examples/media-handling.md)
- [快速开始](https://gowa-docs.mintlify.site/zh/quickstart.md)
- [JavaScript](https://gowa-docs.mintlify.site/zh/api-reference/sdks/javascript.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.