first

docs/DOCKER_COMPOSE.md

@@ -0,0 +1,84 @@
+# Docker Compose
+
+ToolHub 提供 Docker Compose 入口，适合 Linux 主机部署，或不想在 Windows 宿主机安装 Python 的用户。这是一条可选路线，不替代 Windows 原生脚本主线。
+
+---
+
+## 前提条件
+
+- Docker 和 Docker Compose 已安装
+- NVIDIA GPU 驱动已安装，且 NVIDIA Container Toolkit 可用
+
+验证 GPU 容器环境：
+
+```bash
+docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi
+```
+
+---
+
+## 启动与停止
+
+```bash
+docker compose up --build         # 前台启动
+docker compose up --build -d      # 后台启动
+docker compose down               # 停止
+```
+
+首次启动时后端容器会自动下载模型文件，之后缓存在 Docker 命名卷 `toolhub-models` 中。
+
+启动后浏览器访问 [http://127.0.0.1:8080](http://127.0.0.1:8080)。
+
+如果后端还在下载模型或加载模型到 GPU，浏览器会先显示准备中页面。此时直接查看：
+
+```bash
+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` 让它自动修改，然后重启容器：
+
+```bash
+docker compose down
+docker compose up --build -d
+```
+
+> 容器内模型缓存（命名卷）和 Windows 路线的本地缓存（`.tmp/models/`）是两套独立缓存，互不影响。
+
+---
+
+## 配置
+
+Compose 通过 `.env` 文件读取配置。以下变量会影响容器行为：
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `GATEWAY_PORT` | `8080` | 网关对外端口 |
+| `BACKEND_PORT` | `8081` | 后端对外端口 |
+| `THINK_MODE` | `think-on` | 思考模式 |
+| `CTX_SIZE` | `16384` | 上下文窗口大小 |
+| `IMAGE_MIN_TOKENS` | `256` | 图像最小 token 数 |
+| `IMAGE_MAX_TOKENS` | `1024` | 图像最大 token 数 |
+| `MMPROJ_OFFLOAD` | `off` | 视觉投影卸载开关 |
+
+修改 `.env` 后重启容器生效。