跳到主要内容

compose 与数据卷 ​

compose.yaml 定义了组成单账号实例的四个容器服务。除管理面板的 8080 端口外,其余内部端口均无需对外暴露。

服务职责
qq在虚拟屏幕中运行官方未修改的桌面客户端及驱动服务。拥有 SYS_PTRACE 权限,仅用于首次登录时提取一次数据库密钥
consoleWeb 管理面板。唯一对外暴露端口的服务,在单一密码保护下统一代理驱动接口、模型接口与实时画面
bot模型服务:维护单账号会话、长期记忆笔记,并对每条待发送消息执行出站审核
sandbox命令执行沙箱:接收模型下发的命令并降权至非特权用户运行,仅挂载共享工作区,不持有任何业务密钥

数据挂载与持久化 ​

宿主机路径 / 卷容器内路径存放内容
./data/driver/data/driver数据库密钥(secrets/db_key,权限 0600)、消息镜像库(mirror.db)、驱动配置(config.json)
./data/bot/data/bot模型数据库(bot.db)、模型服务商登录凭据(pi/auth.json,权限 0600)、密钥目录(secrets/)、表情包文件(stickers/)
./workspace/workspace模型读写的文件、已安装的技能、从聊天转存的文件,以及超长工具输出的完整副本
./logs/outqq 容器的运行日志:qq.log、keyx.log、novnc.log
qq_profile(命名卷)/home/qq/.config/QQ客户端配置目录:登录态、加密数据库及图片缓存
qq_install(命名卷)/opt/QQ已安装的客户端程序文件

宿主机上的 ./data/bot、./workspace 和 ./logs 需要归属 UID 1000(见快速开始);两个命名卷由容器引擎自动管理权限。

工作区与沙箱隔离 ​

./workspace 仅挂载给 bot 和 sandbox 两个容器。沙箱没有挂载其他任何目录,因此无法接触消息镜像库、bot.db 或客户端文件;网络层面,沙箱位于无外网网关的内部网络 sandbox_net 上,该网络中只有 bot 与 sandbox,沙箱命令访问互联网必须经过 bot 的 HTTP(S) 出口代理。放行与拦截的域名名单可在面板安全页面的 网络 卡片中查看和管理。

日志与隐私保护 ​

宿主机 ./logs 目录下的文件是 qq 容器运行期间写入的底层诊断日志,可能包含聊天内容,请勿公开分享。面板中的日志页面则是结构化事件流,汇总了驱动动作、模型轮次轨迹与控制台事件,并支持按会话、轮次和类型筛选。

备份与恢复 ​

日常备份只需保存 ./data、./workspace 以及 qq_profile、qq_install 两个命名卷。如果丢失 qq_profile 卷,下次启动需要重新扫码登录且会丢失客户端本地历史;如果丢失 qq_install 卷,容器会在下次启动时自动重新安装客户端。版本升级步骤见更新。