常见问题

扫码登录

二维码在哪里？

启动后访问 http://你的服务器IP:13000/qrcode，会显示 QR 码 PNG 图片。

扫码后一直没反应？

检查 Docker 日志 docker logs qq-bridge。常见原因：

• QQ 版本过旧被服务器拒绝
• 网络问题导致无法连接 QQ 服务器

快速登录失败？

快速登录可能因 QQ 服务器的安全风控被拒绝（"登录需要手Q验证"），这在 Docker 容器中较常见。建议：

1. 在 docker-compose.yml 中设置 hostname: waylay，保持容器设备标识一致
2. 设置 AUTO_LOGIN_QQ=你的QQ号，每次启动自动尝试快速登录
3. 快速登录失败时会自动回退到扫码登录

如果 Token 完全失效，清除数据卷后重新扫码：

docker compose down
docker volume rm waylay_qq_data
docker compose up -d --build

连接问题

Yunzai 连不上 Waylay？

1. 确认端口映射正确（3001:3001）
2. 确认 Yunzai 的 OneBot 连接地址是 ws://IP:3001/
3. 如果用反向 WS，确认 ONEBOT_WS_REVERSE_URLS 配置正确
4. 检查防火墙是否放行了端口

Token 验证失败？

确保 Waylay 和 Bot 框架两端的 Token 完全一致。Token 通过 URL 参数 access_token 或 HTTP 头 Authorization: Bearer <token> 传递。

功能相关

发消息超时？

v0.4.0 之前，媒体下载使用同步调用（execSync），会阻塞整个 Node.js 事件循环。如果一个请求包含图片 URL 下载缓慢或失败，后续所有请求都会被阻塞直到超时。

解决：升级到 v0.4.0+，媒体下载已改为异步，不再阻塞其他请求。

发图片失败？

确认 Docker 容器内有足够的 /tmp 空间。图片会先下载到 /tmp/waylay-media/ 再注册到 QQ 媒体路径。

接收到的图片 URL 无法访问？

NTQQ 3.2.27 的 originImageUrl 不包含 rkey 鉴权参数，导致 CDN 直链返回 HTTP 400。此外，无头模式下 NTQQ 不会自动下载接收的图片。

解决：v0.4.1 起，Waylay 会自动通过 NTQQ 内部 API 下载接收到的图片，并通过本地 HTTP 代理（http://127.0.0.1:{OneBot端口}/file/{md5}.{ext}）提供访问。Bot 框架收到的图片 URL 会自动指向此代理，无需手动配置。

发视频没有缩略图？

Dockerfile 中已包含 ffmpeg。如果使用自定义镜像，确保安装了 ffmpeg：

RUN apt-get install -y ffmpeg

@成员显示为 QQ 号而不是昵称？

这通常在 Bot 刚启动时发生。Waylay 需要先接收到群成员列表事件才能解析 UID 和昵称。等待约 10 秒让群成员数据缓存完成即可。

性能相关

内存占用多少？

正常运行约 150 MB，包含 QQ 内核。如果超过 300 MB，可能是内存泄漏，建议重启容器。

为什么查询这么快？

Waylay 使用事件驱动的内存缓存。QQ 内核的事件监听器在数据变更时自动更新缓存，查询时直接从内存读取，不需要调用 QQ API 或查数据库。