> ## 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.

# 会话和连接生命周期

> GOWA 如何保存 WhatsApp 会话，在重启后重新连接，以及注销和移除会起什么作用。

**session** 是指当您配对设备栏位时会出现加密身份WhatsApp问题。 GOWA将其保留在数据库中，所以在重新启动时保持插槽连接，直到从GOWA或手机登出。

## 生命周期：

```mermaid theme={null}
flowchart LR
  A[POST /devices] --> B[disconnected]
  B -->|login: QR / pairing code| C[connected]
  C -->|scan or code accepted| D[logged_in]
  D -->|network drop| E[connecting]
  E --> D
  D -->|logout from GOWA or phone| B
  B -->|DELETE /devices/id| F[removed]
```

| 事件 | GOWA 做什么 |
| - | - |
| 服务器启动 | 加载每个槽位，大约2秒后启动，重新连接一个存储的会话。 |
| 连接丢失 | whatsmeow 自动重新连接。后台检查每5分钟运行一次，重新连接掉的客户端。 |
| 手动重新连接 | `POST /devices/{device_id}/reconnect` 或 `GET /app/reconnect`。 |
| 注销 | `POST /devices/{device_id}/logout` 或 `GET /app/logout`。解除与 WhatsApp 的关联，删除会话密钥，并保留槽位。 |
| 从手机上取消连接 | 与注销相同：空位仍然存在，必须重新配对。 |
| 移除 | `DELETE /devices/{device_id}`。先登出，再删除槽位及其聊天数据。 |

随时检查一个槽位：

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/my-device/status
```

`is_connected` 反映套接字；`is_logged_in` 反映会话是否有效。两者都必须是 `true` 才能发送。

## 存储会话的位置

| 设置 | 默认设置 | 目录 |
| - | - | - |
| `DB_URI` | `file:storages/whatsapp.db` | whatsmeow 设备存储: identity keys, sessions, contacts. SQLite or PostgreSQL (`postgres://...`). |
| `DB_KEYS_URI` | 空(使用 `DB_URI`) | 用于加密密钥缓存的可选单独数据库。避免在内存存储在生产中；重启会失去会话状态。 |
| (固定) | `file:storages/chatstorage.db` | 设备注册表、 聊天和消息历史记录、 预定的发送、 Chatwoot 链接。 |

任何拥有这些文件的人都可以使用已关联账户进行操作。GOWA 以 `0700` 权限创建本地存储目录，并以 `0600` 权限保护本地会话数据库文件及 SQLite 辅助文件。请加密备份，并在恢复时保留这些权限。不要将会话存储放在公开的 `statics/` 目录下。

### 备份并恢复

停止 GOWA（或为卷创建快照），然后复制 `storages/`。当 `DB_URI` 使用 PostgreSQL 时，请同时备份该数据库**和** `storages/chatstorage.db`。恢复两者即可恢复所有设备槽位，无需重新配对。

不要根据相同会话数据运行两个GOWA实例。WhatsApp 看到两个客户端具有一个身份并断开其中一个身份。

退出登录并重新配对时，设备槽位会保留其各自的 Webhook URL、签名密钥和事件过滤器。删除槽位则会移除其配置。订阅 `device.logged_out`、`device.temporary_ban` 和 `device.reachout_timelock`，以区分账户限制和网络断开。参见 [Webhook](https://gowa-docs.mintlify.site/zh/concepts/webhooks.md)。

要管理的 PostgreSQL 会话，请参阅[Neon setup guide](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/neon.md)。更改 `DB_URI` 并不迁移现有的会话。 注册表和聊天记录仍然存在于本地的 SQLite，所以也持续了 `storages/` 。

## 存在

| 设置 | 默认设置 | 效果 |
| - | - | - |
| `WHATSAPP_PRESENCE_ON_CONNECT` | `unavailable` | 连接后发送的在线状态：`available`、`unavailable` 或 `none`。 |
| `WHATSAPP_PRESENCE_PULSE_ENABLED` | `true` | 定期将账户短暂标记为 `available`，随后再次标记为 `unavailable`。 |
| `WHATSAPP_PRESENCE_PULSE_INTERVAL` | `24h` | 脉冲之间的时间。 |
| `WHATSAPP_PRESENCE_PULSE_DURATION` | `5m` | 每次脉冲保持 `available` 的时长。 |

使用 `POST /send/presence`（`{"type": "available"}` 或 `"unavailable"`）手动设置在线状态。

## 故障排除

| Symptom | 可能的原因 | 修复 |
| - | - | - |
| `is_logged_in: false` | 会话已从手机取消关联，或 `storages/` 未进行持久化存储。 | 将`/app/storages`挂载为一个音量；再次配对 |
| 卡片断断开连接 | 另一个过程使用相同的会话，或者手机已经离线约14天。 | 运行一个实例；在手机上打开 WhatsApp |
| 扫描前过期的 QR | `qr_duration`已经过期。 | 再次调用登录端点或使用配对代码。 |
| 发送失败，"未登录" | 槽位已存在，但不配对。 | 检查 `/devices/{device_id}/status`；重新配对。 |


## Related topics

- [服务器指标](https://gowa-docs.mintlify.site/zh/api-reference/metrics.md)
- [认证](https://gowa-docs.mintlify.site/zh/authentication.md)
- [生产最佳做法](https://gowa-docs.mintlify.site/zh/advanced/best-practices.md)
- [获取服务器健康度量表](https://gowa-docs.mintlify.site/zh/api-reference/app/获取服务器健康度量表.md)
- [获取连接状态](https://gowa-docs.mintlify.site/zh/api-reference/app/获取连接状态.md)


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