本地部署Qwen3.8-27B-AWQ全栈实战：从零搭建私有大模型服务

摘要：本文为从零到一生产级落地的私有大模型部署手把手教程，基于双Tesla V100-32GB服务器，采用Qwen3.8-27B-AWQ量化模型、LMDeploy高性能推理引擎，搭配Nginx HTTPS安全网关、Open WebUI网页端、Chatbox跨平台客户端，搭建一套全私有化、可鉴权、高稳定、可商用的AI服务体系。全文遵循「原理介绍→硬件拓扑分析→环境搭建→前台试运行调参→生产脚本落地→安全网关配置→多客户端对接→排错总结」的标准运维流程，所有命令、参数、日志、拓扑分析均为真机实测，无冗余无效步骤，可直接复刻部署。

适用人群：大模型部署工程师、企业私有AI平台搭建、内网离线AI服务落地、服务器模型调优实战学习者

部署硬件与软件栈：8卡Tesla V100-SXM2-32GB（双卡NVLink组网）、CUDA12.4、Python3.12、LMDeploy、Nginx、Docker、Open WebUI、Chatbox

前面我们已经用v100成功部署了DeepSeek-R1-Distill-Qwen-32B-AWQ大模型，环境可以复用，具体可以参考：v100双显卡本地部署DeepSeek-R1-Distill-Qwen-32B-AWQ大模型

一、模型核心认知：Qwen3.8-27B 部署前置原理

Qwen3.8-27B是阿里巴巴2026年8月开源的新一代稠密通用大语言模型，基于Apache 2.0开源协议，完全免费开放商用，无版权限制，是中小规模服务器私有化部署的最优27B级模型。

1.1 模型核心优势

• 纯稠密架构：区别于MoE稀疏模型，每次推理激活全部参数，无路由抖动、延迟稳定、兼容性极强，适配生产稳定场景；

• 超长原生上下文：原生支持262K超长Token窗口，可一次性处理几十万字长文档、完整代码工程、超长对话会话；

• 多模态能力：原生支持图文输入，可实现图片解析、图表识别、视觉内容理解，拓展性更强；

• 精细化推理调控：支持 reasoning_effort（low/medium/high）参数，可自由平衡推理速度与思考深度；

• 顶尖基准性能：SWE-bench Pro跑分达61.7，推理、代码、逻辑能力超越多款更大参数量开源模型；

• 极致量化适配：官方原生支持AWQ/GGUF/GPTQ主流量化方案，其中AWQ 4-bit量化为V100服务器专属最优方案。

详见modelapce模型介绍：https://modelscope.cn/models/Qwen/Qwen3.8-27B

1.2 量化方案选型逻辑（V100专属适配）

Qwen3.8-27B原生FP16权重显存占用高达67GB+，单卡、普通双卡服务器无法承载，必须通过量化压缩显存，三大主流方案对比：

• FP8量化：精度损耗极低，但显存占用仍超38GB，32GB V100显卡无法加载；

• GGUF量化：适配llama.cpp框架，推理速度慢、不支持高并发，仅适合本地测试，不适合服务化部署；

• AWQ 4-bit量化：生产最优解，量化后模型体积压缩至17GB左右，双卡张量并行拆分后，单卡显存占用约26.4GB，完美适配双V100-32GB，兼顾推理速度、并发能力与模型精度。

二、硬件环境核查与GPU拓扑深度分析

大模型双卡部署的核心瓶颈并非仅显存大小，GPU拓扑、NVLink互联、NUMA节点绑定直接决定推理速度与稳定性。部署前必须完成硬件核查与最优卡号选型。

2.1 基础硬件状态核查

登录服务器后，首先执行命令查看显卡型号、显存占用、运行进程，规避显卡占用冲突：

nvidia-smi

真机实测输出：

2.2 GPU拓扑与NUMA节点深度分析

张量并行（TP）部署对GPU通信带宽要求极高，必须选择同NUMA节点、NVLink直连的显卡组合，降低通信延迟。执行拓扑查询命令：

nvidia-smi topo -m

拓扑核心解读规则：

• NV#：NVLink直连，带宽最高、延迟最低，为张量并行最优组合；

• PIX：PCIe桥接通信，性能次之；

• SYS：跨NUMA节点通过PCIe/QPI通信，延迟最高、性能最差；

• NUMA Affinity：显卡所属NUMA节点，跨节点部署会大幅降低内存访问效率。

本机拓扑结论：GPU0-3隶属于NUMA 0节点，GPU4-7隶属于NUMA 1节点；其中GPU5与GPU7同属NUMA1节点，具备NV2高速直连，是双卡张量并行的最优组合，本文全程采用该卡号组合部署。

2.3 NUMA亲和性优化说明

GPU5、GPU7对应的CPU亲和核心为12-23、36-47，NUMA节点为1。脚本中预留了numactl绑定配置，可按需开启，绑定后可进一步优化内存访问效率，减少跨节点性能损耗。

三、标准化环境准备

为避免系统Python、CUDA依赖冲突，全程采用Conda独立虚拟环境，同时统一目录结构，方便后续运维、迁移、迭代。

3.1 全局目录结构约定

所有部署文件统一存放于/home/yxn/data_share/，标准化目录如下：

/home/yxn/data_share/
├── envs/lmd/                     # LMDeploy专属Conda虚拟环境
├── models/Qwen3.8-27B-AWQ/       # 量化模型权重文件
├── logs/                         # 服务运行日志、PID文件
├── scripts/                      # 启停运维脚本
└── nginx/                        # HTTPS网关配置、证书、日志
    ├── ssl/
    ├── conf/
    └── logs/

3.2 创建专属虚拟环境

Python3.12为LMDeploy与Qwen3系列模型的最优适配版本，执行命令创建并激活环境：

# 创建隔离环境
conda create -n lmd python=3.12 -y

# 激活环境
conda activate lmd

# 安装完整推理依赖
pip install lmdeploy[all] modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple

首次pip的话可以要下载一百多个依赖包，网络不好的话要耐心等待一下。这里我就直接激活环境了：

3.3 高速下载模型并校验完整性

采用ModelScope国内镜像下载，规避HuggingFace外网超时问题，一键下载完整量化权重（下面下载方式二选一）：

命令行下载:

sudo mkdir ./Qwen3.8-27B-AWQ
modelscope download --model YanfeiSong/Qwen3.8-27B-AWQ --local_dir ./Qwen3.8-27B-AWQ

SDK下载：

python -c "
from modelscope import snapshot_download
model_dir = '/home/yxn/data_share/models/Qwen3.8-27B-AWQ'
snapshot_download('Qwen/Qwen3.8-27B-AWQ', local_dir=model_dir)
print('模型下载完成，路径：', model_dir)
"

完整性校验和查看：模型目录必须包含config.json、tokenizer.json、safetensors权重文件，缺失核心文件会直接导致服务启动失败。

四、前台试运行+参数调优

生产部署铁律：先前台裸跑调试、迭代参数、验证可用性，再编写后台守护脚本。直接使用nohup后台启动，报错无日志、问题无法定位。

4.1 前台启动命令

激活前面创建的conda环境后，执行前台启动命令，阻塞终端实时查看启动日志：

# 绑定指定GPU卡号
export CUDA_VISIBLE_DEVICES=5,7
# 关闭NCCL冗余校验、优化显存分配
export NCCL_WIN_ENABLE=0
export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True

# 前台启动推理服务
lmdeploy serve api_server \
  /home/yxn/data_share/models/Qwen3.8-27B-AWQ \
  --model-format awq \
  --tp 2 \
  --dtype float16 \
  --quant-policy 8 \
  --session-len 16384 \
  --cache-max-entry-count 0.6 \
  --max-prefill-token-num 4096 \
  --max-batch-size 2 \
  --model-name qwen3.8-27b-awq \
  --server-name 0.0.0.0 \
  --server-port 60080

终端输出Uvicorn running on http://0.0.0.0:60080即代表服务前台启动成功。

4.2 双终端API可用性测试

保持前台终端运行，新开终端执行接口测试，验证模型推理正常：

# 终端2：测试模型列表（无需key）
curl http://127.0.0.1:60080/v1/models

# 终端2：测试对话（无需key）
curl -H "Content-Type: application/json" \
  -d '{"model":"qwen3.8-27b-awq","messages":[{"role":"user","content":"你好"}]}' \
  http://127.0.0.1:60080/v1/chat/completions

两个接口均正常返回JSON数据，代表模型、参数、环境完全可用，按下Ctrl+C停止前台进程，进入生产脚本编写阶段。

查看显存使用情况：

4.3 多轮参数迭代调优对照表

针对V100显存短板，经过多轮真机测试，迭代出最优参数组合，兼顾稳定性与性能：

参数名称	初始测试值	最终生产值	参数说明与避坑
session-len	16384	32768	双卡V100稳定支撑32K上下文，OOM报错可回落至16K
cache-max-entry-count	0.8	0.6	KV Cache显存占用比例，预留40%显存余量，OOM可降至0.5
max-prefill-token-num	4096	8192	提升文本预填充速度，优化长文本首响应延迟
max-batch-size	4	2	限制并发数，适配V100显存上限，多用户场景可微调至4
enable-prefix-caching	关闭	开启	复用重复前缀缓存，大幅提升批量、重复Prompt推理速度

五、生产级守护脚本落地

基于前台调试的最优参数，编写高健壮性启停脚本，包含进程防重复启动、环境校验、日志自动备份、路径校验、优雅退出提示，适配7×24小时后台常驻运行。

5.1 启动脚本：start_Qwen3.8-27B.sh

#!/bin/bash
# ============================================
# LMDeploy 启动脚本 - Qwen3.8-27B-AWQ-INT4
# GPU: 5,7 (TP=2 NVLink组网) | 生产稳定版
# ============================================
set -e

# ---------- 可自定义配置区 ----------
CONDA_ENV_PATH="/home/yxn/data_share/envs/lmd"
MODEL_PATH="/home/yxn/data_share/models/Qwen3.8-27B-AWQ"
PORT=60080
GPUS="5,7"
LOG_DIR="/home/yxn/data_share/logs"
LOG_FILE="$LOG_DIR/qwen38_awq.log"
PID_FILE="$LOG_DIR/qwen38_awq.pid"

# 真机最优调参
SESSION_LEN=32768
CACHE_ENTRY_COUNT=0.6
MAX_PREFILL=8192
MAX_BATCH=2
API_KEY="sk-q12we3rr4r4referwgwe344398f"
# --------------------------------------

# 防重复启动校验
if [ -f "$PID_FILE" ] && kill -0 $(cat "$PID_FILE") 2>/dev/null; then
    echo "[ERROR] 服务已在运行 (PID $(cat $PID_FILE))"
    echo "[INFO] 重启请先执行: bash $(dirname "$0")/stop_Qwen3.8-27B.sh"
    exit 1
fi

# 初始化并激活Conda环境
eval "$(conda shell.bash hook 2>/dev/null || true)"
if ! command -v conda >/dev/null; then
    echo "[ERROR] Conda未配置至系统PATH"
    exit 1
fi

echo "[INFO] 激活推理环境: $CONDA_ENV_PATH"
conda activate "$CONDA_ENV_PATH" 2>/dev/null || {
    source activate "$CONDA_ENV_PATH" 2>/dev/null || {
        echo "[ERROR] 环境激活失败，请校验路径"
        exit 1
    }
}

# 全局性能优化环境变量
export CUDA_VISIBLE_DEVICES="$GPUS"
export PYTHONNOUSERSITE=1
export NCCL_WIN_ENABLE=0
export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True

# 可选：NUMA节点绑定，进一步优化性能
# numactl --cpunodebind=1 --membind=1 \

# 模型文件完整性校验
if [ ! -d "$MODEL_PATH" ] || [ ! -f "$MODEL_PATH/config.json" ]; then
    echo "[ERROR] 模型路径异常或缺失config.json"
    exit 1
fi

# 日志初始化与旧日志备份
mkdir -p "$LOG_DIR"
if [ -f "$LOG_FILE" ]; then
    BACKUP="$LOG_DIR/qwen38_awq_$(date +%Y%m%d_%H%M%S).log"
    mv "$LOG_FILE" "$BACKUP"
    echo "[INFO] 旧日志已备份至: $BACKUP"
fi

# 后台启动服务
echo "[INFO] 启动LMDeploy生产服务，模型：Qwen3.8-27B-AWQ"
nohup lmdeploy serve api_server \
  "$MODEL_PATH" \
  --model-format awq \
  --tp 2 \
  --dtype float16 \
  --quant-policy 8 \
  --session-len $SESSION_LEN \
  --cache-max-entry-count $CACHE_ENTRY_COUNT \
  --max-prefill-token-num $MAX_PREFILL \
  --enable-prefix-caching \
  --max-batch-size $MAX_BATCH \
  --max-log-len 1024 \
  --model-name qwen3.8-27b-awq \
  --server-name 0.0.0.0 \
  --server-port "$PORT" \
  --api-keys "$API_KEY" \
  > "$LOG_FILE" 2>&1 &

# 记录进程PID
PID=$!
echo $PID > "$PID_FILE"

# 启动成功提示
echo ""
echo "[INFO] ============================="
echo "[INFO] 服务启动成功 PID: $PID"
echo "[INFO] 接口地址: http://0.0.0.0:$PORT"
echo "[INFO] 实时日志: tail -f $LOG_FILE"
echo "[INFO] 服务停止: bash $(dirname "$0")/stop_Qwen3.8-27B.sh"
echo "[INFO] 接口测试: curl -H 'Authorization: Bearer $API_KEY' http://localhost:$PORT/v1/models"
echo "[INFO] ============================="
echo ""

5.2 配套停止脚本：stop_Qwen3.8-27B.sh

#!/bin/bash
# ============================================
# LMDeploy 停止脚本 - Qwen3.8-27B
# ============================================

LOG_DIR="/home/yxn/data_share/logs"
PID_FILE="$LOG_DIR/qwen38_awq.pid"
LOG_FILE="$LOG_DIR/qwen38_awq.log"

# 查找 PID
if [ ! -f "$PID_FILE" ]; then
    echo "[WARN] PID 文件不存在，尝试通过进程名查找..."
    PID=$(pgrep -f "lmdeploy serve api_server.*qwen3.8-27b-awq-int4" | head -1)
    if [ -z "$PID" ]; then
        echo "[INFO] 未找到运行中的 Qwen3.8-27B 服务"
        exit 0
    fi
    echo "[INFO] 找到进程 PID: $PID"
else
    PID=$(cat "$PID_FILE")
    if ! kill -0 "$PID" 2>/dev/null; then
        echo "[WARN] PID $PID 已失效，清理 PID 文件"
        rm -f "$PID_FILE"
        exit 0
    fi
fi

echo "[INFO] 正在停止服务 (PID: $PID)..."

# 先尝试优雅终止
kill "$PID" 2>/dev/null

# 等待最多 10 秒
for i in {1..10}; do
    if ! kill -0 "$PID" 2>/dev/null; then
        echo "[INFO] 服务已正常退出 (耗时 ${i}s)"
        break
    fi
    sleep 1
done

# 如果还在，强制终止
if kill -0 "$PID" 2>/dev/null; then
    echo "[WARN] 进程未响应，执行强制终止 (kill -9)..."
    kill -9 "$PID" 2>/dev/null
    sleep 1
    echo "[INFO] 已强制终止"
fi

rm -f "$PID_FILE"
echo "[INFO] PID 文件已清理"

# 显示 GPU 状态
echo ""
echo "[INFO] 当前 GPU 显存状态:"
nvidia-smi --query-gpu=index,name,memory.used,memory.total --format=csv,noheader | grep -E "^[57],"

5.3 脚本授权与生产启动

# 添加执行权限
chmod +x /home/yxn/data_share/scripts/*.sh

# 后台启动生产服务
bash /home/yxn/data_share/scripts/1start_Qwen3.8-27B.sh

# 实时监控启动日志，确认服务就绪
tail -f /home/yxn/data_share/logs/qwen38_awq.log

六、Nginx HTTPS安全网关部署（加密+鉴权）

裸HTTP接口存在明文传输、非法访问风险，通过Nginx实现HTTPS加密传输、全局API密钥鉴权、请求限流、非法路径拦截，构建生产级安全访问入口。

6.1 多IP适配自签名证书生成

证书必须配置SAN多IP适配，包含内网IP、公网IP、本地回环，彻底解决证书域名不匹配报错：

# 创建证书目录
mkdir -p /home/yxn/data_share/nginx/ssl && cd /home/yxn/data_share/nginx/ssl

# 生成2048位私钥
openssl genrsa -out privkey.pem 2048

# 生成多IP自签名证书（有效期365天）
openssl req -x509 -new -nodes -key privkey.pem -sha256 -days 365 \
  -subj "/C=CN/ST=Yunnan/L=Chuxiong/O=Local/OU=Dev/CN=192.168.5.23" \
  -addext "subjectAltName=IP:192.168.5.23,IP:192.168.5.4,IP:36.147.93.146,IP:127.0.0.1" \
  -out fullchain.pem

# 配置证书权限
chmod 600 privkey.pem && chmod 644 fullchain.pem

# 校验SAN配置是否生效
openssl x509 -in fullchain.pem -text -noout | grep -A2 "Subject Alternative Name"

6.2 完整Nginx安全配置

路径：/home/yxn/data_share/nginx/conf/api_gateway.conf，无重复路由、严格鉴权、超时优化：

server {
    listen 60443 ssl;
    server_name _;

    # SSL证书配置
    ssl_certificate     /home/yxn/data_share/nginx/ssl/fullchain.pem;
    ssl_certificate_key /home/yxn/data_share/nginx/ssl/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    # 日志配置
    access_log /home/yxn/data_share/nginx/logs/api_access.log;
    error_log  /home/yxn/data_share/nginx/logs/api_error.log;

    # 全局合法API密钥
    set $valid_api_key "sk-f9b141cae7e6425b89070cdfe2fd7052";

    # 免鉴权健康检查
    location = /health {
        return 200 "OK\n";
    }

    # 模型列表接口（免鉴权，方便客户端探测）
    location = /v1/models {
        proxy_pass http://127.0.0.1:60080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 对话核心接口（强制鉴权）
    location /v1/chat/completions {
        if ($http_authorization != "Bearer $valid_api_key") {
            return 401 '{"error":"Unauthorized"}';
        }
        proxy_pass http://127.0.0.1:60080;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 120s;
        proxy_buffering off;
    }

    # 其余OpenAI兼容接口
    location /v1/ {
        if ($http_authorization != "Bearer $valid_api_key") {
            return 401 '{"error":"Unauthorized"}';
        }
        proxy_pass http://127.0.0.1:60080;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_read_timeout 120s;
        proxy_buffering off;
    }

    # 拦截非法路径
    location / {
        return 404;
    }
}

6.3 配置生效与HTTPS接口验证

# 校验Nginx配置合法性
sudo nginx -t

# 重载配置生效
sudo systemctl reload nginx

# 跳过证书验证，测试HTTPS接口连通性
curl -k https://127.0.0.1:60443/v1/models

七、Open WebUI 团队网页客户端部署

Open WebUI是开源全能型AI网页控制台，支持多用户管理、RAG知识库、文档解析、Prompt预设，适合团队协作使用，通过Docker Compose一键部署。

7.1 Docker Compose 配置文件

创建 docker-compose.yml（建议放在 /home/yxn/data_share/openwebui/ 目录），内容如下：

services:
  open-webui:
    # 南京大学镜像加速（国内稳定），也可使用官方镜像 open-webui/open-webui:v0.3.33
    image: ghcr.nju.edu.cn/open-webui/open-webui:v0.3.33
    container_name: open-webui
    restart: always  # 异常退出自动重启
    ports:
      - "3000:8080"  # 宿主机3000端口 → 容器8080端口（Web UI）
    environment:
      # ========== API 连接配置（对接 Nginx 网关） ==========
      - OPENAI_API_BASE_URL=https://127.0.0.1:60443/v1  # Nginx 代理后的 HTTPS 地址（若 Nginx 与 Open WebUI 同机，用 127.0.0.1；跨机用内网 IP）
      - OPENAI_API_KEY=sk-f9b141cae7e6425b89070cdfe2fd7052  # 与 Nginx 配置的全局 API Key 一致

      # ========== 证书信任配置（解决自签名证书验证失败） ==========
      # 方法 1：强制容器信任宿主机自签名证书（推荐）
      - REQUESTS_CA_BUNDLE=/usr/local/share/ca-certificates/lmdeploy.crt
      # 方法 2：禁用 aiohttp 证书验证（备用，安全性略低）
      # - AIOHTTP_CLIENT_SESSION_SSL=false

      # ========== 功能优化（可选） ==========
      - ANONYMIZED_TELEMETRY=false  # 关闭匿名遥测（保护隐私）
      - DO_NOT_TRACK=true           # 禁止跟踪
      - SCARF_NO_ANALYTICS=true     # 禁止 Scarf Analytics 统计
      - TZ=Asia/Shanghai            # 时区同步

      # ========== 禁用 Ollama（避免无关报错） ==========
      - USE_OLLAMA_DOCKER=false
      - OLLAMA_BASE_URL=

    volumes:
      # 数据持久化（对话记录、知识库、用户配置）
      - open-webui-data:/app/backend/data
      # 挂载 Nginx 自签名证书到容器 CA 目录（关键！使容器信任后端 HTTPS）
      - /home/yxn/data_share/nginx/ssl/fullchain.pem:/usr/local/share/ca-certificates/lmdeploy.crt:ro

    # 启动前自动更新系统证书信任库（确保证书生效）
    command: >
      sh -c "update-ca-certificates && bash start.sh"

    # 健康检查（确保服务就绪）
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s   # 每 30 秒检查一次
      timeout: 10s    # 超时时间 10 秒
      retries: 3      # 失败 3 次后标记为 unhealthy

volumes:
  open-webui-data:  # 命名卷，自动管理数据持久化
    driver: local

7.2 部署与模型对接

以下是优化后的 Open WebUI 团队网页客户端部署 章节，结合实战排错、安全配置与细节补全，直接替换原第七节即可：

---

七、Open WebUI 团队网页客户端部署

Open WebUI 是开源企业级 AI 协作平台，支持多用户管理、RAG 知识库、文档解析、Prompt 预设、团队权限控制，适合企业/团队私有化知识库与 AI 协作场景。本章基于 Docker Compose 一键部署，并解决自签名证书信任核心痛点（关键！否则容器会因证书验证失败无法连接后端）。

7.1 Docker Compose 配置文件（生产级）

创建 docker-compose.yml（建议放在 /home/yxn/data_share/openwebui/ 目录），内容如下：

version: '3.8'

services:
  open-webui:
    # 南京大学镜像加速（国内稳定），也可使用官方镜像 open-webui/open-webui:v0.3.33
    image: ghcr.nju.edu.cn/open-webui/open-webui:v0.3.33
    container_name: open-webui
    restart: always  # 异常退出自动重启
    ports:
      - "3000:8080"  # 宿主机3000端口 → 容器8080端口（Web UI）
    environment:
      # ========== API 连接配置（对接 Nginx 网关） ==========
      - OPENAI_API_BASE_URL=https://127.0.0.1:60443/v1  # Nginx 代理后的 HTTPS 地址（若 Nginx 与 Open WebUI 同机，用 127.0.0.1；跨机用内网 IP）
      - OPENAI_API_KEY=sk-f9b141cae7e6425b89070cdfe2fd7052  # 与 Nginx 配置的全局 API Key 一致

      # ========== 证书信任配置（解决自签名证书验证失败） ==========
      # 方法 1：强制容器信任宿主机自签名证书（推荐）
      - REQUESTS_CA_BUNDLE=/usr/local/share/ca-certificates/lmdeploy.crt
      # 方法 2：禁用 aiohttp 证书验证（备用，安全性略低）
      # - AIOHTTP_CLIENT_SESSION_SSL=false

      # ========== 功能优化（可选） ==========
      - ANONYMIZED_TELEMETRY=false  # 关闭匿名遥测（保护隐私）
      - DO_NOT_TRACK=true           # 禁止跟踪
      - SCARF_NO_ANALYTICS=true     # 禁止 Scarf Analytics 统计
      - TZ=Asia/Shanghai            # 时区同步

      # ========== 禁用 Ollama（避免无关报错） ==========
      - USE_OLLAMA_DOCKER=false
      - OLLAMA_BASE_URL=

    volumes:
      # 数据持久化（对话记录、知识库、用户配置）
      - open-webui-data:/app/backend/data
      # 挂载 Nginx 自签名证书到容器 CA 目录（关键！使容器信任后端 HTTPS）
      - /home/yxn/data_share/nginx/ssl/fullchain.pem:/usr/local/share/ca-certificates/lmdeploy.crt:ro

    # 启动前自动更新系统证书信任库（确保证书生效）
    command: >
      sh -c "update-ca-certificates && bash start.sh"

    # 健康检查（确保服务就绪）
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s   # 每 30 秒检查一次
      timeout: 10s    # 超时时间 10 秒
      retries: 3      # 失败 3 次后标记为 unhealthy

volumes:
  open-webui-data:  # 命名卷，自动管理数据持久化
    driver: local

7.2 部署与验证

步骤 1：启动容器并检查状态

在 docker-compose.yml 所在目录执行：

# 启动容器（-d 后台运行）
docker compose up -d

# 查看实时日志（确认启动过程无报错）
docker compose logs -f

当日志出现 Application startup complete 或健康检查状态为 healthy 时，服务就绪。

步骤 2：浏览器访问与初始化

1. 打开浏览器，访问 http://<服务器IP>:3000（如 http://192.168.5.23:3000）。
2. 注册管理员账号（首次访问需创建管理员，后续用户可通过邀请码加入）。

步骤 3：配置模型连接

进入 管理员设置 → 连接 → OpenAI（或 外部连接）：

• 接口地址：填写 https://<Nginx服务器IP>:60443/v1（如 https://192.168.5.23:60443/v1）。
• API 密钥：填写 sk-xxx（与 Nginx 配置的 valid_api_key 一致）。

点击 “连接测试”，若提示“连接成功”则忽略；若提示“证书验证失败”或“连接超时”，按以下排错：

• 检查 Nginx 是否运行：sudo systemctl status nginx。
• 检查证书路径：容器内证书路径应为 /usr/local/share/ca-certificates/lmdeploy.crt，可在容器内执行 ls /usr/local/share/ca-certificates/ 验证。
• 临时绕过：设置 AIOHTTP_CLIENT_SESSION_SSL=false（重启容器生效）。

步骤 4：手动添加模型

在 管理员设置 → 模型 → 添加模型：

• 模型 ID：填写 qwen3.8-27b-awq（需与 LMDeploy 启动时的 --model-name 完全一致）。
• 模型类型：选择 OpenAI 兼容。

保存后，在聊天界面右上角的模型选择器中切换到 qwen3.8-27b-awq，即可开始对话（支持长文本、代码、多轮记忆）。

步骤 5：高级功能（团队与知识库）

• 多用户协作：管理员在“用户管理”中创建账号/邀请码，团队成员共享知识库与对话记录。
• RAG 知识库：在“知识库”页面上传 PDF/Markdown/TXT 文件，模型会自动检索文档内容回答（需确保 session-len 足够大，如 32768）。
• Prompt 预设：在“Prompt 模板”中创建常用提示词（如“学术论文润色”“代码注释生成”），一键调用。

7.3 实战排错

报错现象	根因分析	解决方案
容器启动后立即退出	证书路径错误（fullchain.pem 未正确挂载）	检查 volumes 中证书路径是否与宿主机一致（/home/yxn/data_share/nginx/ssl/fullchain.pem）
连接测试提示“证书验证失败”	容器未信任自签名证书	确认 REQUESTS_CA_BUNDLE 环境变量与证书挂载路径正确，或临时设置 AIOHTTP_CLIENT_SESSION_SSL=false
对话时模型无响应	LMDeploy 进程未运行或 OOM	执行 bash /home/yxn/data_share/scripts/1start_Qwen3.8-27B.sh 重启服务，或降低 session-len/cache-max-entry-count
知识库上传文件失败	文件格式不支持或大小超限	仅支持 PDF/Markdown/TXT，单文件建议 ≤ 100MB（大文件需拆分）
多用户登录后看不到对话	数据卷权限错误	检查 open-webui-data 卷权限：sudo chown -R 1000:1000 /var/lib/docker/volumes/open-webui_data/_data

7.4 效果验证

部署成功后，Open WebUI 界面应类似下图：

• 左侧：对话列表、工作空间、知识库入口。
• 右侧：聊天窗口支持 Markdown 渲染、代码高亮、文件上传。
• 顶部：模型选择器可切换 qwen3.8-27b-awq，对话支持长文本上下文。

八、Chatbox 跨平台客户端配置（桌面/手机）

Chatbox 是一款轻量级、无广告、跨平台的 AI 对话客户端，支持 Windows/Mac/Linux/Android/iOS。其核心优势包括：

• 对话本地存储，保护隐私；
• 界面简洁，操作门槛低；
• 原生支持 OpenAI 兼容接口，可无缝对接私有大模型服务。

8.1 软件获取与安装

• 官网下载：https://chatboxai.app/（根据系统选择对应版本，如 Windows .exe、Mac .dmg、Linux .AppImage）。
• 开源仓库：https://github.com/Bin-Huang/chatbox（可编译源码或获取最新测试版）。
• 移动端：在应用商店搜索“Chatbox”，或通过官网二维码下载（支持 Android/iOS）。

8.2 连接私有模型的配置步骤

打开 Chatbox → 点击左下角 设置 → 进入 模型提供方 → 点击 添加提供方 → 选择 OpenAI 兼容。

步骤 1：基础连接配置

• 身份验证：

  • API 密钥：填写 Nginx 配置的全局密钥 sk-xx（需与服务端 valid_api_key 完全一致）。
  • （可选）通过 OAuth 登录：若服务端支持，可免手动输入密钥，但私有部署场景建议直接用 API Key。

• API 主机：
  填写 Nginx 的 HTTPS 接口地址：

  https://<你的公网IP或域名>:60443/v1
  

  示例：https://36.147.93.146:60443/v1（需与 Nginx 配置的 listen 60443 ssl 端口一致）。

• 点击“检查”：若返回“连接成功”，则基础连通性验证通过；若报错，参考下方“排错指南”。

步骤 2：模型参数与能力配置

点击 “模型”区域的“新建”（或编辑已有模型），配置以下核心参数：

参数项	配置值/说明
模型 ID	填写 LMDeploy 启动时的 --model-name：qwen3.8-27b-awq（需完全一致）。
显示名称	自定义（如 Qwen3.8-27B-AWQ），便于识别。
模型类型	选择 “聊天”（适配对话场景）。
能力勾选	根据模型特性勾选： - ✅ 视觉（若需图像理解，需模型支持多模态）； - ✅ 推理（Qwen 系列强项）； - ✅ 工具使用（如需调用外部工具，需服务端支持）。
上下文窗口	建议设为 32768（与 LMDeploy 配置的 session-len 一致，最大化利用长文本能力）。
最大输出 Token 数	设为 8192（平衡响应速度与长度，可根据需求调整）。

步骤 3：保存与测试

点击 “保存” 后，在聊天界面右上角的模型选择器中切换到 qwen3.8-27b-awq，发送测试消息（如“你好，介绍一下你自己”），若模型正常回复（如图 8-3），则配置成功。

8.3 跨平台使用示例

• 桌面端（Windows/Mac/Linux）：
  安装后打开，按上述步骤配置，即可在本地离线使用（数据存储在本地，不依赖云端）。

• 移动端（Android/iOS）：

  1. 确保手机与 GPU 服务器在同一内网，或通过 VPN/公网 IP 连通服务器的 60443 端口；
  2. 打开 Chatbox，进入设置 → 模型提供方 → 选择已配置的 OpenAI 兼容服务；
  3. 输入消息测试，支持语音输入、图片上传（若模型开启视觉能力）。

8.4 常见问题与排错

报错现象	根因分析	解决方案
“连接失败”/“超时”	1. Nginx 未运行；2. 公网 IP/端口错误；3. 防火墙拦截。	1. 执行 sudo systemctl status nginx 检查 Nginx；2. 核对 API 主机地址；3. 开放服务器 60443 端口（sudo firewall-cmd --add-port=60443/tcp）。
“API 密钥无效”	密钥与服务端 valid_api_key 不匹配。	重新填写 Nginx 配置的密钥 sk-f9b141cae7e6425b89070cdfe2fd7052。
“模型不存在”	模型 ID 与 LMDeploy 配置的 --model-name 不一致。	检查 LMDeploy 启动命令的 --model-name，确保与 Chatbox 配置的模型 ID 完全一致。
“证书验证失败”	自签名证书未被客户端信任。	1. 桌面端：在系统设置中导入 Nginx 证书（fullchain.pem）；2. 移动端：暂时关闭“证书验证”（部分客户端支持）。

8.5 效果验证

配置成功后，Chatbox 界面应类似下图：

• 图 8-1：OpenAI 兼容接口配置页面（红框标注 API 密钥、API 主机）。
• 图 8-2：模型编辑页面（红框标注模型 ID、能力勾选、上下文窗口）。
• 图 8-3：对话界面（模型正常回复，支持 Markdown 渲染、代码高亮）。

九、全场景报错汇总与终极解决方案

汇总真机部署所有踩坑问题，覆盖启动、接口、证书、客户端全场景，快速定位排错：

报错现象	根因分析	精准解决方案
URL拼写错误、接口无响应	服务未启动、端口未放行、URL后缀不匹配、未携带鉴权头	重启服务、放行60080/60443端口、适配/v1后缀、请求携带Bearer密钥
服务启动秒退、显存溢出(OOM)	上下文长度、KV缓存占比超出V100显存上限	下调session-len至16384或cache-max-entry-count至0.5
Nginx报duplicate location错误	配置文件存在重复路由规则	删除冗余location块，保证路由唯一不重复
HTTPS证书域名不匹配	SAN字段未包含当前访问IP	重新生成含所有内网/公网IP的多SAN证书
Chatbox连接失败	客户端版本差异导致/v1后缀适配冲突	交替测试带/不带/v1的接口地址，适配当前版本
重复启动服务报错	PID文件残留，进程未彻底终止	执行停止脚本清理残留进程与PID文件后重启
Open WebUI连接校验失败	模型接口返回格式不完全兼容校验规则	忽略校验报错，手动添加模型ID即可正常对话

十、部署架构总结与拓展方向

本文从零完成Qwen3.8-27B-AWQ + LMDeploy + Nginx + Open WebUI + Chatbox全栈生产级部署，依托双V100-32GB、NVLink互联、同NUMA节点组网，通过精细化参数调优、进程守护、HTTPS加密鉴权，搭建了一套100%私有化、高稳定、可商用的大模型服务体系。

整体架构链路：多端客户端 → Nginx HTTPS安全网关 → LMDeploy推理服务 → 双V100 NVLink算力集群

核心优势：数据全程私有化无上传、兼容全量OpenAI生态工具、加密鉴权保障安全、多端适配、老旧服务器高效复用。

后续拓展方向：开启推理深度参数调控、接入RAG知识库、Nginx多模型负载均衡、GPU监控告警、多用户权限精细化管理。