跳到主要内容

首次启动与扫码登录 ​

任何容器镜像内都不包含 QQ 客户端。qq 容器在首次启动时会从以下两种来源中二选一安装固定版本的安装包:

安装来源配置方式
下载地址在 .env 中设置 QQ_DEB_URL=https://example.com/QQ_3.2.34_260924_amd64_01.deb
本地 deb 安装包在 compose.yaml 中取消 /qq/QQ.deb 挂载行的注释,并将 QQ_DEB_URL 留空

无论选择哪种方式,容器在安装前都会校验文件的 SHA-256 是否与镜像内置的固定摘要一致;一旦不一致便拒绝安装,并输出期望的版本号与摘要。安装完成后程序保存在 qq_install 命名卷中,后续启动会自动跳过安装。如果未提供任何来源,或同时配置了两种来源,容器会报错退出并提示正确的配置方式。

官方下载地址会返回 403

官方下载链接在缺少签名参数时会返回 403。若从镜像站下载 deb 文件,请先自行核对 SHA-256 摘要,然后在 compose.yaml 中直接将其挂载到 /qq/QQ.deb(或放在容器可访问的 HTTP 服务上并填入 QQ_DEB_URL)。

扫码登录 ​

  1. 执行 docker compose up -d 启动服务后,在浏览器打开 http://localhost:8080,用 CONSOLE_PASSWORD 登录管理面板。
  2. 进入左侧导航的 QQ 页面,下方的 实时画面 显示的就是客户端画面。待二维码出现后,使用手机 QQ 扫码确认。首次扫码必须由人工完成。
  3. 登录时勾选客户端界面上的自动登录,以便后续容器重启后自动恢复登录。
  4. 扫码登录成功后,驱动服务会提取本地数据库密钥,提取完成后状态栏的 DB 密钥 会变为 密钥正常(QQ 页面显示 正常)。

此后容器重启或客户端回到已保存账号页时,驱动服务会自动点击一次登录按钮恢复会话;QQ 页面上的 登录 按钮则是该动作的手动重试入口。只有删除重建了客户端配置卷(qq_profile)才需要重新扫码。

数据库密钥提取 ​

数据库密钥用于读取客户端本地数据库,驱动服务只读取其私有副本,绝不修改或写入客户端自身的文件。提取出的密钥保存在宿主机 data/driver/secrets/db_key(权限 0600),不会离开本机。

密钥仅在首次登录时提取一次,后续重启直接复用。状态显示 缺失 表示仍在提取中,可在宿主机查看 ./logs/keyx.log;若显示 失效,说明客户端更新了密钥或数据库副本无法读取,按 QQ 页面顶部横幅给出的命令重新提取即可。

常见启动报错 ​

现象原因与处理
error: no QQ source: set exactly one of ...未设置 QQ_DEB_URL,也未挂载 /qq/QQ.deb
error: sha256 mismatch: expected ... got ...提供的 deb 安装包不是当前要求的固定版本,请更换正确文件
error: both QQ_DEB_URL and the mounted deb ... are set同时配置了两种安装来源,请去掉其中一种
实时画面一直停留在二维码界面正常现象,首次登录需要人工用手机扫码
面板页面返回 502qq 或 bot 容器仍在启动中,可执行 docker compose logs qq bot 查看日志

更多常见问题见排障。