常见问题

按“进程 → 数据库 → HTTP → 凭证 → WebSocket → 媒体”的顺序检查。浏览器能打开后台并不能证明实时连接和所有资源都已配置正确。

提示 ngram_token_size 必须为 1

将 deploy/mysql-search.cnf 的内容放进 MySQL [mysqld] 配置，重启数据库，然后检查：

SHOW VARIABLES LIKE 'ngram_token_size';
SHOW VARIABLES LIKE 'innodb_ft_enable_stopword';

已有数据库改变分词长度后需重建相关全文索引；先备份，按当前版本的升级步骤操作，不重新导入安装 SQL。

页面返回 502

查看 PHP 进程状态和日志，确认 HTTP 上游 8787 在监听。服务重启瞬间的短暂 502 可能是上游尚未就绪；持续失败时检查 PHP 扩展、配置语法、目录权限和端口冲突。

sudo systemctl status popoim --no-pager
sudo journalctl -u popoim -n 100 --no-pager
ss -lntp

SDK 登录失败

确认宿主取票接口成功、data.user.user_id 与当前账号一致，且 expireAt 使用秒。不要把宿主 Cookie 直接当 IM Token，也不要把 SDK Secret 填到客户端 Token 字段。业务失败通常仍是 HTTP 200，必须检查 JSON code，见请求约定。

能看到历史，收不到新消息

检查 /ws 的 Upgrade 代理、WSS 证书和首帧认证。connection.ready 表示连接订阅成功；仅有 TCP 连接或 WebSocket HTTP 101 并不表示业务认证完成。内部 API 地址与公网服务地址不要互换。

上传失败或视频没有预览

核对当前 media_limits、Nginx client_max_body_size、PHP 限制、GD 的 JPEG / WebP 支持以及文件实际格式。视频使用 H.264 MP4，并通过带封面接口上传；语音编码要求见资源接口。文件上传后发送完整返回的 media，不自行拼接路径。

刷新后退出或更新后会话丢失

检查宿主是否保存并正确携带 PHPSID，同源代理是否透传 Cookie / 会话头，以及发布时是否保留 runtime/sessions。前端只预热缓存不会恢复服务端身份，仍需调用 SDK login()。

Docker 连接不上数据库

容器中的数据库地址是 mysql。检查 docker compose ps 的健康状态、.env 凭据和数据库卷初始化记录。已有卷的数据库账号不会因为你修改 .env 就自动改密码；凭据变更应通过数据库管理流程同步。