Text Generation WebUI Docker一键部署教程：拉取镜像映射端口配置数据目录

部署前先了解：它适合解决什么问题

Text Generation WebUI 是常见的本地大模型工具，适合在个人工作站、实验服务器或小型团队内网环境中运行开源语言模型。它提供浏览器界面，可用于模型加载、参数调试、对话测试、插件扩展和接口调用，比纯命令行方式更适合非研发人员上手。使用 Docker 部署的好处是环境隔离、迁移方便、回滚简单，尤其适合不想反复处理 Python、CUDA、依赖版本冲突的用户。

不过，Docker 并不等于“完全无脑”。部署前仍需确认三件事：第一，机器资源是否足够，尤其是显存和内存；第二，镜像是否来自可信来源；第三，模型文件、角色配置、会话记录等数据是否挂载到宿主机目录。若这些准备不到位，常见结果就是容器能启动但无法加载模型，或者更新容器后配置被清空。

环境准备：系统、Docker 与显卡驱动

推荐使用 Linux 服务器或桌面系统部署，Windows 和 macOS 也可以通过 Docker Desktop 运行，但大模型性能和显卡调用体验通常不如原生 Linux 稳定。基础环境包括 Docker Engine、可用的磁盘空间以及浏览器访问条件。若计划使用 NVIDIA 显卡，还需要安装匹配的显卡驱动和 NVIDIA Container Toolkit，并通过 nvidia-smi 确认显卡可被系统识别。

磁盘空间要按模型规模预留。7B 级别量化模型通常需要数 GB 到十几 GB，多个模型并存时很容易占用数十 GB。建议单独建立数据目录，例如 /data/text-generation-webui，用来存放模型、扩展、配置和日志。这样即使后续删除容器或更新镜像，关键数据也不会随容器一起丢失。

镜像选择与拉取：优先使用可信来源

部署时可以选择官方或社区维护较活跃的 Docker 镜像。选择镜像时要关注三个信息：更新时间、文档说明和支持的后端类型。Text Generation WebUI 常涉及 transformers、llama.cpp、ExLlama、AutoGPTQ 等加载方式，不同镜像预装组件可能不同。若你主要使用 GGUF 模型，应确认镜像支持 llama.cpp；若使用 GPTQ 或 AWQ 模型，则要查看对应依赖是否包含。

拉取镜像的基本思路是先确定镜像名和标签，再执行 docker pull。例如：docker pull ghcr.io/oobabooga/text-generation-webui:latest。latest 便于尝鲜，但生产或长期使用环境更建议固定版本标签，避免更新后依赖变化导致模型加载失败。拉取完成后可用 docker images 查看镜像是否已存在，并记录镜像 ID、标签和体积。

目录规划：把模型和配置放到宿主机

数据目录配置是 Docker 部署中最容易被忽略的环节。建议在宿主机创建统一目录，例如 /data/textgen，并在其下建立 models、loras、presets、characters、extensions、logs 等子目录。容器运行时通过 -v 参数把宿主机目录映射到容器内部对应路径。这样做的好处是模型下载一次即可长期复用，界面参数、预设和扩展也能保留。

一个常见目录方案是：/data/textgen/models 存放模型文件，/data/textgen/loras 存放微调适配文件，/data/textgen/user_data 存放用户配置。不同镜像内部路径可能略有差异，部署前应阅读镜像说明。如果路径挂错，WebUI 可能能正常打开，但模型列表为空。遇到这种情况，不要急着重装，先进入容器检查路径是否一致。

启动容器：端口映射与基础命令

Text Generation WebUI 默认常用 Web 端口为 7860。Docker 启动时需要使用 -p 将容器端口映射到宿主机端口，例如 -p 7860:7860，表示通过宿主机的 7860 访问容器内的 7860。若宿主机 7860 已被占用，可以改为 -p 17860:7860，然后通过 http://服务器地址:17860 打开界面。

一个典型的 GPU 启动命令可以写成：docker run -d --name textgen-webui --gpus all -p 7860:7860 -v /data/textgen:/app/user_data --restart unless-stopped ghcr.io/oobabooga/text-generation-webui:latest。这里 -d 表示后台运行，--name 用于设置容器名称，--gpus all 允许容器调用显卡，-v 负责挂载数据目录，--restart unless-stopped 表示服务异常退出或机器重启后自动恢复。

如果没有独立显卡，也可以去掉 --gpus all，使用 CPU 运行。但需要预期性能会明显下降，大模型响应速度较慢，适合功能验证或小参数模型测试。启动后可用 docker ps 查看容器状态，用 docker logs -f textgen-webui 查看启动日志。日志中若出现依赖下载、模型扫描或端口监听信息，通常说明服务正在正常初始化。

首次访问与模型加载

容器启动后，在浏览器输入 http://宿主机IP:7860 访问 WebUI。首次进入后先查看模型列表，如果为空，需要把模型文件放入映射目录中的 models 子目录。模型格式要与加载器匹配，例如 GGUF 通常选择 llama.cpp 相关加载方式，safetensors 格式模型可能走 transformers 或其他后端。加载模型前建议先阅读模型说明，确认所需显存、量化类型和上下文长度。

模型加载失败时，不要只看页面提示，应结合容器日志判断原因。常见问题包括显存不足、模型路径不正确、文件不完整、加载器选错、CUDA 版本不匹配等。显存不足时可尝试降低上下文长度、使用更低位数量化模型、减少 GPU layers，或改用更小参数模型。盲目提高参数可能导致容器反复重启，影响排查效率。

使用 Docker Compose 管理更稳妥

如果只是临时体验，docker run 足够；如果要长期使用，建议改为 Docker Compose。Compose 文件可以固定镜像、端口、卷挂载、环境变量和重启策略，便于团队复用。日后迁移到新机器时，只需复制 compose 配置和数据目录，再执行 docker compose up -d 即可恢复。

Compose 管理还便于版本回滚。升级前先记录当前镜像标签，或使用 docker image ls 保存旧版本信息。升级后若发现界面异常、模型无法加载或插件失效，可将镜像标签改回旧版本并重新启动。对于经常调试模型的用户，建议把“镜像版本”和“模型版本”分别记录，不要把问题全部归因于 WebUI。

常见问题与排查思路

问题一：页面打不开。先检查容器是否运行，执行 docker ps；再检查端口是否正确映射；最后确认服务器防护规则是否允许访问该端口。如果在本机部署，优先访问 127.0.0.1:7860；如果在远程机器部署，要使用远程机器地址和映射后的宿主机端口。

问题二：模型列表为空。重点检查挂载目录。宿主机模型目录是否有文件，容器内部是否能看到同样文件，WebUI 扫描路径是否一致。还要注意模型通常需要完整目录结构，不能只复制单个残缺文件。

问题三：容器启动后马上退出。使用 docker logs 查看错误信息。常见原因包括镜像拉取不完整、显卡运行时未配置、启动参数不兼容、数据目录权限不足。Linux 下如果容器没有权限读取挂载目录，可调整目录属主或访问权限，但不要为了省事给整个系统目录开放过大权限。

问题四：响应很慢。先确认是否真的调用了 GPU，再检查模型大小、量化方式、上下文长度和并发请求数。WebUI 适合本地调试，不建议在低配置机器上同时给多人高强度使用。

安全边界与实用建议

不要把 WebUI 直接暴露到公网。它通常用于本地或可信内网环境，若必须远程访问，应至少增加访问认证、限制来源地址，并定期更新镜像。模型文件和对话内容可能包含业务资料或个人信息，目录挂载和备份策略要谨慎设置，避免把敏感内容放进公开同步目录。

镜像更新前建议先备份配置目录，尤其是 characters、presets、extensions 和自定义脚本。不要随意安装来源不明的扩展，也不要在容器内执行不理解的命令。Docker 的优势是隔离，但如果挂载了宿主机关键目录，错误操作仍可能影响真实文件。

对于新手，推荐先按“固定镜像版本、单模型、单端口、单数据目录”的方式部署，确认稳定后再增加扩展、接口服务和多模型管理。对于团队使用，建议建立一份内部部署记录，写明镜像标签、启动命令、模型来源、目录位置和更新日期。这样遇到故障时可以快速还原环境，而不是从头排查。

结语：稳定比一步到位更重要

用 Docker 部署 Text Generation WebUI 的核心并不复杂：选对镜像，规划好数据目录，正确映射端口，并根据硬件条件加载合适模型。真正决定体验的是细节管理，包括版本固定、日志排查、目录备份和访问控制。把这些基础工作做好，本地大模型工具就能成为稳定可复用的实验平台，而不是每次更新都要重新折腾的临时环境。