跳到主要内容

环境变量(.env) ​

.env 是放在 compose.yaml 同目录的标准环境变量文件,仅包含 KEY=value 赋值行和 # 注释行。请先将 .env.example 复制为 .env 再填写。

必填项 ​

变量说明
CONSOLE_PASSWORDWeb 管理面板的登录密码。这是面板对外唯一的鉴权屏障,请使用足够长的强密码
DRIVER_TOKEN驱动服务内部鉴权令牌;未设置时驱动拒绝启动,控制台与模型服务用它调用驱动接口
BOT_TOKEN模型服务内部鉴权令牌;由控制台服务端持有,绝不会下发给浏览器
SANDBOX_EXEC_TOKEN沙箱执行服务鉴权令牌;模型服务用它调用沙箱,沙箱内仅 root 进程可读,命令执行用户无权读取

三个内部令牌均可使用 openssl rand -hex 32 生成。这些令牌仅在容器内部网络流转,各服务只挂载自己所需的那一项。

QQ 安装包来源(二选一) ​

变量说明
QQ_DEB_URLqq 容器首次启动时下载固定版本安装包的 HTTP(S) 地址。若改用本地文件挂载(/qq/QQ.deb),请将此项留空

未提供任何来源或同时设置了两种来源时,容器都会拒绝启动并打印配置说明。详见首次启动与扫码登录。

可选项 ​

变量默认值说明
PI_OFFLINE0设为 1 时禁止从 pi.dev 拉取在线模型目录,适用于纯离线环境
KEYX_TIMEOUT_S900首次启动等待数据库密钥提取的秒数。实测提取最多约需 8 分钟,低配机器可适当调大;超时后驱动仍会在后台继续等待
PERSONAL_BOT_TAG空(即 latest)要运行的镜像标签。留空使用最新发布版;填入 v2026.1025.0 等标签可固定在指定版本

模型的运行策略在控制台中管理 ​

选用哪个主模型、允许参与哪些会话、人设内容、笔记数量上限、沙箱放行域名、消息合并等待时长、轮次排队规则等设置,均在控制台中实时修改生效,无需改动 .env 或重启容器。

此外,compose.yaml 中还定义了虚拟屏幕分辨率变量 SCREEN_W 与 SCREEN_H(默认 1280 × 800),用于控制客户端窗口和实时画面的尺寸;修改后只需执行 docker compose up -d 重建 qq 容器即可生效。