部署前先明确适用场景
Text Generation WebUI 是常见的本地大模型工具，适合在 Linux 服务器上运行开源语言模型，提供网页对话、参数调节、模型切换、API 调用等能力。它常用于个人研究、团队内部测试、私有知识问答原型、模型效果对比和推理服务验证。相比直接写推理脚本，WebUI 的优势是上手快、界面友好、插件生态较丰富；不足是对显存、依赖版本和启动参数比较敏感，生产环境还需要额外做权限控制、日志管理和资源隔离。
服务器部署前应先确认三件事：第一，硬件是否满足模型体积要求，例如 7B 量级模型通常建议至少 8GB 到 16GB 显存，量化模型可降低需求；第二，系统是否便于长期运行，推荐 Ubuntu 20.04/22.04、Debian 11/12 或 Rocky Linux 等常见发行版；第三，使用目标是单人测试还是多人访问，多人使用要提前规划端口、账号、反向袋里和资源限制。
环境准备：系统、驱动与基础工具
建议不要直接使用 root 用户长期运行服务，可创建普通用户并加入必要权限。先更新软件源并安装基础工具，Ubuntu 系统可执行：apt update && apt install -y git wget curl build-essential python3 python3-venv python3-pip。若服务器使用 NVIDIA 显卡，需要提前安装匹配的显卡驱动，并通过 nvidia-smi 检查显卡是否可见、驱动版本是否正常。没有显卡也能用 CPU 运行，但速度通常较慢，只适合小模型或功能验证。
Python 环境推荐使用 Conda 或 venv 隔离，避免与系统自带依赖混在一起。使用 venv 时，可执行：python3 -m venv ~/venvs/textgen && source ~/venvs/textgen/bin/activate。之后升级基础组件：pip install -U pip setuptools wheel。若使用 Conda，可创建 Python 3.10 环境，兼容性通常较稳。部署时尽量固定一套 Python、PyTorch、CUDA 组合，不要频繁混装不同版本，否则容易出现找不到算子、显存无法调用、扩展编译失败等问题。
下载项目并安装依赖
进入准备好的目录，例如 /opt/apps 或用户家目录，拉取项目：git clone https://github.com/oobabooga/text-generation-webui.git，然后进入目录：cd text-generation-webui。项目通常提供启动脚本和依赖安装方式，Linux 环境可优先查看 README 中对应显卡类型的说明。如果选择手动安装，可根据显卡环境安装合适版本的 PyTorch，再安装项目依赖。对于不熟悉依赖细节的用户，建议使用项目自带的启动脚本，它会引导安装所需组件，减少漏装问题。
安装过程中常见问题主要集中在三类：一是 PyTorch 与 CUDA 版本不匹配，表现为检测不到 GPU 或运行时报错；二是编译扩展失败，通常缺少 gcc、g++、make、python-dev 等工具；三是网络下载中断导致依赖不完整，可清理 pip 缓存后重试。为便于回滚，建议部署前记录关键版本，例如 python --version、pip list | grep torch、nvidia-smi 输出结果。
准备模型文件与目录结构
Text Generation WebUI 默认会从 models 目录读取模型。可在项目根目录下创建 models，并将模型文件放入独立子目录，例如 models/your-model-name。不同模型格式对应不同加载器，常见有 Transformers、GGUF、GPTQ、AWQ 等。选择模型时要同时关注参数规模、量化格式、上下文长度、许可证和所需加载器，不要只看文件大小。
如果是 GGUF 格式，通常会配合 llama.cpp 相关加载方式；如果是 Transformers 格式，目录里一般包含 config.json、tokenizer 文件、权重分片等。模型目录不要随意改动文件名，尤其是分片权重和 tokenizer 配置。多人共享服务器时，建议把模型存放在统一路径，并设置只读权限，避免误删或被覆盖。
前台启动与参数验证
第一次启动建议先前台运行，便于观察报错。常见命令为：python server.py --listen --listen-port 7860。如果只允许本机访问，可不加 --listen，默认绑定本地地址更安全。需要 API 能力时可加 --api。需要简单账号保护时可使用 --gradio-auth 用户名:强密码。启动后在浏览器访问 https://服务器地址:7860，进入界面后选择模型并加载。
加载模型前可先设置 loader、gpu-memory、cpu-memory、max_seq_len 等参数。显存不足时，可尝试量化模型、降低上下文长度、减少批处理参数，或使用部分 CPU offload。若界面能打开但模型加载失败，应优先查看终端日志，确认是文件路径、格式、依赖还是显存问题。不要一开始就叠加大量参数，建议先用最小配置启动成功，再逐步调整。
后台运行的三种方式
临时测试可使用 nohup：nohup python server.py --listen --listen-port 7860 --gradio-auth user:strongpass > ~/textgen-webui.log 2>&1 &。这种方式简单，但进程管理较弱，适合短期验证。查看日志可用 tail -f ~/textgen-webui.log，停止进程可通过 ps aux | grep server.py 找到进程号后结束。
日常运维更推荐 tmux 或 screen。先执行 tmux new -s textgen，进入会话后启动 WebUI，按 Ctrl+b 再按 d 可离开会话，服务继续运行。需要查看时执行 tmux attach -t textgen。它适合调试阶段，因为日志实时可见，重启和修改参数也方便。
长期部署建议使用 systemd。可创建服务文件 /etc/systemd/system/textgen-webui.service，内容包括工作目录、运行用户、环境变量和启动命令。关键项可设置为：User=普通用户、WorkingDirectory=/path/text-generation-webui、ExecStart=/path/venv/bin/python server.py --listen --listen-port 7860 --gradio-auth user:strongpass、Restart=always。保存后执行 systemctl daemon-reload、systemctl enable textgen-webui、systemctl start textgen-webui。查看状态用 systemctl status textgen-webui，查看日志用 journalctl -u textgen-webui -f。
访问控制与安全边界
服务器部署不能只追求“能打开”。如果服务暴露在公网地址上，必须设置强密码，并限制来源地址或通过网关统一鉴权。更稳妥的做法是仅监听 127.0.0.1，再由反向袋里提供 HTTPS 和访问控制。不要把管理端口、日志目录、模型目录开放给无关人员，也不要使用弱口令或默认口令。
模型输出具有不确定性，不能直接替代专业判断。涉及合同、医疗、教育评估、客服答复等场景，应增加人工复核。上传到 WebUI 的提示词、文档和对话记录可能被写入日志或缓存，内部资料要先确认脱敏策略。插件功能也要谨慎启用，只安装来源明确、社区反馈较好的扩展，避免让服务执行不必要的系统命令。
常见故障排查
如果页面无法访问，先确认进程是否存在、端口是否监听，可使用 ss -lntp | grep 7860 检查；再确认服务器安全组和系统防火墙是否放行对应端口。若本机能访问、远程不能访问，多半是绑定地址或端口策略问题。若启动后立刻退出，查看终端或 systemd 日志，通常能看到缺包、路径错误或参数不兼容信息。
如果提示显存不足，可换用更小模型或量化版本，降低上下文长度，关闭多余扩展，并确认没有其他进程占用显存。若模型加载很慢，检查磁盘是否为机械盘、模型是否位于网络挂载目录、内存是否频繁交换。若升级后无法启动，建议回退到旧版本代码和依赖环境；部署前用 git status、pip freeze > requirements-lock.txt 记录状态，能显著降低恢复成本。
实用部署建议
稳定运行的关键是“少改动、可追踪、能回滚”。建议把项目、模型、日志分目录存放；启动参数写入固定脚本或 systemd 服务文件；重要更新先在测试目录验证，再切换到正式服务。多人使用时要约定模型加载规则，避免频繁切换大模型导致显存碎片和响应中断。
对于只做体验的用户，单机前台启动即可；对于团队内部试用，建议 tmux 加账号保护；对于长期服务，应使用 systemd、反向袋里、日志轮转和访问限制。按“环境确认—项目安装—模型放置—前台验证—后台守护—安全加固”的顺序推进，基本可以完成一套可维护的 Text Generation WebUI Linux 服务器部署流程。
