compose 与数据卷
compose.yaml 定义了组成单账号实例的四个容器服务。除管理面板的 8080 端口外,其余内部端口均无需对外暴露。
| 服务 | 职责 |
|---|---|
qq | 在虚拟屏幕中运行官方未修改的桌面客户端及驱动服务。拥有 SYS_PTRACE 权限,仅用于首次登录时提取一次数据库密钥 |
console | Web 管理面板。唯一对外暴露端口的服务,在单一密码保护下统一代理驱动接口、模型接口与实时画面 |
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 | /out | qq 容器的运行日志: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 卷,容器会在下次启动时自动重新安装客户端。版本升级步骤见更新。