# 排查问题

按顺序检查：哨站进程 → 邮箱 → 订阅文件夹 → 通知渠道 → 手机。渠道测试跳过邮箱监听，新邮件才能验证完整链路。

## 哨站或控制台无法访问

检查 `docker compose ps` 和 `docker compose logs --tail=100 core`。默认端口绑定本机；其他设备通过 SSH 隧道或正常工作的 [HTTPS 代理](https.md)访问。启动报告 `data_directory_permission_denied` 或 `data_directory_read_only` 时，检查数据卷写权限。容器使用 `10001:10001` 用户。

## 初始化码或管理员密码问题

完成初始化前，每次重启哨站都会轮换初始化码，请读取当前进程日志。重置管理员密码时，停止哨站，使用同一 Compose 项目和数据卷执行：

```sh
docker compose stop core
docker compose run --rm -it core admin reset-password
docker compose start core
```

交互式重置会退出浏览器会话，保留 API Token、邮箱和待处理任务。恢复命令需要获取数据目录锁，因此操作前停止正在运行的哨站。

## 新邮件没有通知

1. 验证邮箱连接和 IMAP 凭据。
2. 检查邮件所在的实际服务器文件夹是否已订阅。新订阅会跳过已有邮件。
3. 等待所选定时间隔，或检查实时连接状态。
4. 查看投递历史。没有事件时检查监听；事件失败时查看渠道错误。
5. 发送渠道测试。使用 Mailwake App 时，同时检查接收手机选择和普通推送权益。

重试次数为 0 表示只尝试一次。需要自动重试时先明确配置次数。渠道“已接受”表示服务接收了请求，最终显示问题还要检查下游服务和手机。

## App 连接失败

先用 Safari 打开哨站的 HTTPS 地址。确认证书与网络正常，创建新的 5 分钟邀请，并核对哨站指纹。出现 `clock_skew` 时同步哨站宿主机时间。检查站主是否授予所需权限，以及需要 Pro 的操作是否已有有效权益。

手机被撤销后，选择新接收手机并保存渠道。更换推送中继服务环境后，按[部署说明](deploy.md)执行运维重置并重新配对，各环境身份独立。

## 寻求帮助

可复现的哨站问题可以提交到 [GitHub Issues](https://github.com/mingzaily/mailwake/issues)，附上版本、错误码、时间和控制台脱敏诊断。公开报告中保留诊断线索，移除密码、API Token、邀请链接和邮件内容。安全问题按 [SECURITY.md](https://github.com/mingzaily/mailwake/blob/main/SECURITY.md) 私下报告。