Docker Compose

ToolHub 提供 Docker Compose 入口，适合 Linux 主机部署，或不想在 Windows 宿主机安装 Python 的用户。这是一条可选路线，不替代 Windows 原生脚本主线。

前提条件

验证 GPU 容器环境：

docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

docker compose up --build         # 前台启动
docker compose up --build -d      # 后台启动
docker compose down               # 停止

首次启动时后端容器会自动下载模型文件，之后缓存在 Docker 命名卷 toolhub-models 中。

启动后浏览器访问 http://127.0.0.1:8080。

如果后端还在下载模型或加载模型到 GPU，浏览器会先显示准备中页面。此时直接查看：

docker compose logs -f backend

确认下载和加载进度即可。

Compose 启动两个服务：

服务	镜像基础	职责
`gateway`	`python:3.11-slim`	网关层，提供网页入口和 OpenAI 兼容 API（端口 8080）
`backend`	`ghcr.io/ggml-org/llama.cpp:server-cuda`	模型后端，GPU 推理（端口 8081）

架构与 Windows 原生路线一致：浏览器访问网关，网关将推理请求转发给后端。网关容器通过只读方式挂载项目目录（/workspace），文件系统访问行为与 Windows 路线保持一致。

模型不会打进镜像，由后端容器首次启动时从 Hugging Face 下载，缓存在命名卷 toolhub-models 中。默认下载 Q4_K_M 量化。

如需切换到 Q8，在 .env 中将 MODEL_GGUF_URL 改为 Q8 下载地址，也可以先在宿主机执行 .\install_q8.cmd 让它自动修改，然后重启容器：

docker compose down
docker compose up --build -d

容器内模型缓存（命名卷）和 Windows 路线的本地缓存（.tmp/models/）是两套独立缓存，互不影响。

Compose 通过 .env 文件读取配置。以下变量会影响容器行为：

修改 .env 后重启容器生效。