从零到一：在Ubuntu 20.04上容器化部署Bisheng大模型的完整实战指南

最近有不少朋友在尝试本地部署大模型应用，特别是像Bisheng这样集成了知识库、对话和RAG能力的开源平台。但很多人在第一步——环境部署上就卡住了，尤其是面对Docker、端口、依赖项这些“拦路虎”。我自己在几台不同配置的Ubuntu 20.04服务器上反复折腾过好几次，踩了不少坑，也总结出了一套相对平滑的部署流程。今天这篇内容，我就把自己从系统准备到服务上线的完整操作，以及那些让人头疼的常见错误和解决方案，毫无保留地分享出来。无论你是刚接触Linux的开发者，还是想快速搭建一个私有化大模型应用环境的技术负责人，相信这篇手把手的指南都能帮你省下大量排查时间。

1. 部署前的系统环境审视与准备

在直接敲命令之前，花几分钟时间检查并准备好你的Ubuntu 20.04系统，是避免后续一系列诡异报错的关键。很多人部署失败，根源往往在于基础环境不纯净或资源不足。

首先，确认你的系统版本。打开终端，输入：

lsb_release -a

你应该能看到类似 Ubuntu 20.04.6 LTS 的输出。如果不是20.04，部分软件源的兼容性可能需要额外注意。

接下来，是磁盘空间检查。大模型部署，动辄需要几十GB的存储空间，用于存放Docker镜像、模型文件和各种依赖。运行：

df -h

重点关注根目录 / 的可用空间。我个人建议，为这次部署预留至少 50GB 的可用空间。如果空间不足，你需要考虑清理旧文件、挂载新数据盘，或者从一开始就选择一个大容量的目录作为工作区。

内存和交换空间 是另一个隐形杀手。Bisheng及其依赖的服务（如Elasticsearch）对内存有一定要求。使用 free -h 查看可用内存。如果物理内存小于8GB，强烈建议配置足够的交换空间（Swap），这能防止构建或运行容器时因内存不足（OOM）而崩溃。如果你的服务器没有交换分区，可以临时创建一个交换文件：

# 创建一个4GB的交换文件（根据你的磁盘空间调整大小）
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# 使其永久生效，编辑 /etc/fstab 文件，添加一行：/swapfile none swap sw 0 0

最后，一个常被忽略的步骤是更新现有软件包。这能确保系统层面的库处在一个较新的状态，减少冲突。

sudo apt update && sudo apt upgrade -y

更新完成后，重启一次系统是个好习惯，能让所有更新生效。别嫌麻烦，这步能避免很多难以追溯的底层库冲突。

注意：如果你是在公司内网或受代理管理的服务器上操作，可能需要预先配置好系统的HTTP/HTTPS代理，否则后续的 apt update 和 docker pull 都可能失败。配置方法因环境而异，通常需要修改 /etc/apt/apt.conf 和 Docker的守护进程配置。

2. Docker与Docker Compose的稳固安装

容器化部署的核心是Docker。Ubuntu 20.04的默认仓库里的Docker版本可能较旧，我们直接从Docker官方仓库安装。

第一步，卸载可能存在的旧版本。这是一个清洁安装的好开端。

sudo apt remove docker docker-engine docker.io containerd runc -y

即使系统提示未安装这些包，执行也无害。

第二步，安装必要的工具包并添加Docker官方GPG密钥。

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common gnupg lsb-release

接着，下载并添加Docker的官方GPG密钥，用于验证软件包的完整性：

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

第三步，添加稳定的Docker APT源。这里用 echo 命令直接写入源列表，比 add-apt-repository 更清晰可控。

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

第四步，安装Docker Engine。

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

安装完成后，立刻验证是否成功，并将当前用户加入docker组，这样以后就不用每次都加 sudo 了。

docker --version
sudo usermod -aG docker $USER

提示：执行 usermod 后，你需要完全退出当前终端会话并重新登录，或者新开一个终端窗口，用户组的变更才会生效。否则，运行 docker ps 可能还会提示权限错误。

第五步，安装Docker Compose。虽然Docker现在有 compose 插件，但很多现有项目（包括Bisheng）的配置文件仍基于独立的 docker-compose 命令。我们安装独立的v2版本。

# 下载二进制文件到 /usr/local/bin
sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
# 赋予执行权限
sudo chmod +x /usr/local/bin/docker-compose
# 创建软链接，确保在PATH中
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
# 验证安装
docker-compose --version

如果输出类似 Docker Compose version v2.24.0，说明安装成功。

3. 获取Bisheng代码与核心依赖服务部署

Bisheng平台本身是一个由多个微服务组成的应用，它依赖几个外部服务才能完全工作，主要是向量数据库和搜索引擎。我们需要按顺序来启动它们。

首先，克隆Bisheng项目代码。选择一个空间充足的目录，例如你的家目录 ~。

cd ~
git clone https://github.com/dataelement/bisheng.git
cd bisheng

克隆后，你可以看到项目的目录结构。核心的Docker编排文件在 docker 子目录下。

部署Milvus（向量数据库）。Bisheng使用Milvus来存储和检索文本嵌入向量。我们需要先单独启动它。

# 回到家目录，避免路径干扰
cd ~
# 下载Milvus standalone模式的docker-compose配置文件
wget https://github.com/milvus-io/milvus/releases/download/v2.3.3/milvus-standalone-docker-compose.yml -O milvus-docker-compose.yml
# 使用下载的配置文件启动Milvus
docker-compose -f milvus-docker-compose.yml up -d

启动后，使用 docker ps 检查名为 milvus-standalone 的容器是否处于 Up 状态。Milvus默认会占用 19530 和 9091 端口。你可以用 netstat -tlnp | grep 19530 来确认端口监听情况。

部署Elasticsearch（搜索引擎）。Bisheng用ES来索引和搜索文档元数据。这里有个关键点：避免端口冲突。ES默认使用9200和9300端口，这两个端口非常常用，可能已被其他服务占用。

1. 检查端口占用：

   sudo lsof -i:9200
   sudo lsof -i:9300
   

   如果端口被占用，记录下进程ID，考虑停止无关进程，或者为ES映射其他主机端口（如 -p 19200:9200）。

2. 创建Docker网络并运行ES容器。为ES创建一个独立的网络有助于服务间隔离和通信。

   docker network create bisheng-net
   docker run -d \
     --name elasticsearch \
     --net bisheng-net \
     -p 9200:9200 -p 9300:9300 \
     -e "discovery.type=single-node" \
     -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" \
     -e "xpack.security.enabled=false" \
     docker.elastic.co/elasticsearch/elasticsearch:8.11.1
   

   • -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" 限制了ES的堆内存，防止它在小内存机器上吞掉所有资源。
   • -e "xpack.security.enabled=false" 禁用了安全认证，简化初次部署。生产环境请务必启用。

3. 验证ES是否运行正常：

   curl -X GET "localhost:9200/"
   

   如果返回一个包含 "you know, for search" 的JSON，说明ES启动成功。

4. 模型文件准备与Git LFS大文件下载难题破解

Bisheng-RT是Bisheng的推理服务组件，它需要加载具体的大语言模型（LLM）才能工作。这里我们以 chatglm3-6b 模型为例。下载模型最大的坑在于 Git LFS（大文件存储），动辄几个GB的模型文件，用普通 git clone 只会下载到几个KB的指针文件。

第一步，安装Git LFS。

sudo apt install -y git-lfs
git lfs install

第二步，克隆模型仓库。建议在一个单独的目录（如 ~/models）下操作，方便管理。

mkdir -p ~/models
cd ~/models
git clone https://huggingface.co/THUDM/chatglm3-6b
cd chatglm3-6b

此时，如果你直接 ls -lh，会发现 pytorch_model-00001-of-00007.bin 这类大文件只有几百字节，这是LFS指针。

第三步，也是最关键的一步：拉取真实的LFS大文件。

git lfs pull

这个过程可能非常缓慢，并且极易失败，原因通常是网络连接不稳定或Hugging Face仓库限流。下面是我亲测有效的几种解决方案：

• 方案A：配置Git代理（如果你有稳定的网络代理）。这能显著提升克隆和拉取速度。

  # 设置HTTP/HTTPS代理（请替换为你自己的代理地址和端口）
  git config --global http.proxy http://your-proxy-ip:port
  git config --global https.proxy https://your-proxy-ip:port
  # 单独为LFS设置代理
  git config --global http.https://huggingface.co.proxy http://your-proxy-ip:port
  # 然后重新执行 git lfs pull
  

• 方案B：使用--all参数和重试。如果中途失败，可以尝试：

  git lfs fetch --all
  git lfs checkout
  

  或者，更彻底地清理后重试：

  # 回到模型目录的上一级
  cd ..
  # 删除未下载完整的仓库
  rm -rf chatglm3-6b
  # 重新克隆，并使用 --depth 1 减少历史记录下载
  git clone --depth 1 https://huggingface.co/THUDM/chatglm3-6b
  cd chatglm3-6b
  git lfs pull --include="*.bin,*.safetensors" # 只拉取最核心的模型权重文件
  

• 方案C：手动下载（终极备用方案）。如果Git LFS始终无法成功，可以去Hugging Face模型页面的“Files and versions”标签页，手动点击下载每个大文件（.bin, .safetensors等），然后放入克隆下来的仓库对应目录中。虽然繁琐，但绝对可靠。

第四步，验证模型文件。下载完成后，检查文件大小是否正常（几个GB），并确认LFS文件列表。

ls -lh *.bin *.safetensors 2>/dev/null | head -5
git lfs ls-files

5. 启动Bisheng核心服务与配置整合

当Milvus、Elasticsearch和模型文件都就位后，我们就可以启动Bisheng自己的服务了。

第一步，修改Bisheng的Docker Compose配置。进入Bisheng项目的docker目录，编辑 .env 或 docker-compose.yml 文件，确保服务配置指向我们刚才启动的依赖服务。

cd ~/bisheng/docker
# 通常需要检查或创建 .env 文件来设置环境变量
cat > .env << EOF
MILVUS_HOST=host.docker.internal # 或者你的宿主机实际IP
MILVUS_PORT=19530
ES_HOST=elasticsearch # 因为我们把ES放到了bisheng-net网络，可以用服务名访问
ES_PORT=9200
MODEL_PATH=/app/models/chatglm3-6b # 这里需要映射宿主机模型路径到容器内
EOF

关键点在于网络互通。Bisheng的容器需要能访问到Milvus和ES。有几种方式：

1. 使用 host.docker.internal（Docker Desktop概念，在Linux上可能需要额外配置）。
2. 更可靠的方式：将所有服务（Milvus, ES, Bisheng）放在同一个自定义Docker网络中。这就是我们之前创建 bisheng-net 的原因。你需要修改Bisheng的 docker-compose.yml，在 services 下的每个服务定义中加入 networks: ["bisheng-net"]，并确保 docker-compose.yml 文件末尾定义了该网络。

第二步，配置模型路径映射。在 docker-compose.yml 中，找到 bisheng-rt 服务，添加一个卷映射，将你下载好的 chatglm3-6b 模型目录挂载到容器内。

# 在 bisheng-rt 服务定义中添加 volumes 部分
services:
  bisheng-rt:
    image: dataelement/bisheng-rt:latest
    # ... 其他配置
    volumes:
      - ~/models/chatglm3-6b:/app/models/chatglm3-6b
    # ... 其他配置

第三步，启动Bisheng服务栈。

# 在 bisheng/docker 目录下执行
docker-compose up -d

使用 docker-compose ps 或 docker ps 查看所有服务（frontend, backend, bisheng-rt等）是否都正常启动。这个过程可能会首次拉取Bisheng的各个镜像，需要一些时间。

第四步，访问与验证。所有服务启动成功后，Bisheng的Web界面默认在宿主机的 3001 端口提供服务。打开浏览器，访问 http://你的服务器IP:3001。你应该能看到登录界面。默认的账号密码通常在项目的README或 .env.example 文件中，常见的是 admin / admin。

6. 部署后常见问题诊断与运维技巧

即使一切顺利启动，在后续使用中也可能遇到问题。这里汇总几个高频问题及其排查思路。

问题一：端口冲突导致服务无法启动 这是最经典的问题。症状是 docker-compose up -d 后，某个服务状态一直是 Restarting 或 Exit。

• 排查：使用 docker-compose logs [服务名] 查看具体日志。如果看到 bind: address already in use 错误，说明端口被占。
• 解决：
  1. sudo netstat -tlnp | grep :端口号 找出占用进程。
  2. 停止无关进程，或者修改 docker-compose.yml 中该服务的端口映射，例如将 "3001:3001" 改为 "3002:3001"（左边是宿主机端口，右边是容器端口）。

问题二：容器启动后，Web页面无法访问或登录失败

• 排查：
  1. 检查所有容器状态：docker-compose ps，确保所有服务都是 Up 状态。
  2. 检查后端日志：docker-compose logs backend，看是否有数据库连接错误（连不上Milvus或ES）。
  3. 检查网络：确保Bisheng的容器能连通Milvus和ES。可以进入容器内部测试：docker exec -it bisheng-backend容器ID ping elasticsearch。
• 解决：
  • 如果是网络问题，确保所有相关容器在同一个自定义网络中。
  • 如果是依赖服务未就绪，可以尝试重启Bisheng栈：docker-compose restart。
  • 有时后端服务初始化数据库需要时间，稍等一两分钟再刷新页面。

问题三：模型加载失败，对话功能报错

• 排查：查看 bisheng-rt 服务的日志：docker-compose logs bisheng-rt。常见错误是找不到模型文件或模型文件损坏。
• 解决：
  1. 确认 docker-compose.yml 中的卷映射路径是否正确，宿主机路径是否存在模型文件。
  2. 进入 bisheng-rt 容器检查：docker exec -it bisheng-rt容器ID ls -la /app/models/。
  3. 确认模型文件完整，没有在Git LFS下载过程中中断。

问题四：如何更新Bisheng到新版本？

• 步骤：

  cd ~/bisheng
  git pull origin main
  cd docker
  # 拉取最新的镜像
  docker-compose pull
  # 重启服务
  docker-compose up -d
  

• 注意：更新前最好备份数据库（如果有重要数据的话）。更新后检查 .env 和 docker-compose.yml 配置是否有变动，可能需要调整。

日常运维命令备忘：

# 查看所有容器状态
docker-compose ps
# 查看特定服务日志（-f 持续输出）
docker-compose logs -f backend
# 停止所有服务
docker-compose down
# 停止并删除所有容器、网络（不会删除镜像和卷）
docker-compose down -v
# 进入容器内部执行命令
docker exec -it [容器名] /bin/bash
# 清理所有未使用的Docker资源（镜像、容器、网络、构建缓存），释放磁盘空间
docker system prune -a -f

部署完成后，第一次登录系统，建议你花点时间熟悉一下Bisheng的界面，创建一个知识库，上传一些文档进行索引测试，再尝试与内置的模型进行对话。整个流程跑通后，你会对基于大模型的RAG应用有一个非常直观的感受。我自己在部署过程中最大的体会就是，耐心和仔细查看日志是最重要的“工具”，大部分错误信息都已经指明了方向。如果遇到上面没覆盖的怪问题，不妨去项目的GitHub Issues里搜一搜，很可能已经有人遇到过并给出了解决方案。