新手如何在海外服务器搭建自己的AI聊天助手?从环境准备到上线验证

发布人:A5数据发布时间:2026-10-09 10:25阅读量:198

这套部署把自己的 AI 聊天助手拆成四个部分:Ubuntu 海外服务器负责运行环境,Ollama 负责本地大语言模型推理,Open WebUI 提供聊天和知识库界面,Nginx 负责域名访问与 HTTPS。完成后,用户可以通过浏览器登录自己的域名,选择本地模型对话,并基于上传的文档进行检索问答。

教程默认使用 Ubuntu 22.04/24.04 LTS、Docker Compose 和 CPU 推理,不依赖特定云厂商。适合个人知识库、产品文档问答、内部运维手册检索等场景。服务器至少准备 2 核 CPU、8 GB 内存和 40 GB 可用磁盘;如果希望运行 7B 级模型并同时处理文档索引,建议使用 4 核 CPU、16 GB 内存和 60 GB 以上磁盘。

面向海外部署的 AI 聊天助手,A5数据提供中国香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器资源,覆盖 AMD EPYC、Xeon、GPU、NVMe 存储及多种带宽线路。大内存与高速磁盘可承载模型文件、知识库索引和容器数据,香港及美国的 A100、RTX 4090 等 GPU 方案也可用于 AI 推理与模型测试,满足不同访问区域和计算负载下的部署需求。

一、部署目标与准备条件

1. 最终架构

请求路径如下:

浏览器
  │
  │ HTTPS
  ▼
Nginx:443
  │
  │ 反向代理
  ▼
Open WebUI:127.0.0.1:3000
  │
  ├── Ollama:11434 ── 本地聊天模型
  │
  └── Open WebUI 持久化数据 ── 用户、聊天记录、知识库索引

Ollama 只加入 Docker 内部网络,不直接暴露到公网。Open WebUI 也只绑定服务器本机的 127.0.0.1:3000,外部访问统一经过 Nginx 和 HTTPS。

本教程的上线目标包括:

  • 可以通过域名打开 Open WebUI;
  • 可以创建管理员账号并关闭公开注册;
  • 可以下载并运行一个中文对话模型;
  • 可以上传 Markdown、TXT、PDF 或 DOCX 文档;
  • 可以创建知识库并验证检索问答;
  • 重启容器后模型、账号和知识库仍然存在;
  • 能够在配置错误或升级失败时恢复。

2. 软件与版本范围

项目示例选择说明
操作系统Ubuntu 22.04/24.04 LTS,amd64其他发行版需要调整包管理命令
容器运行时Docker Engine + Compose Plugin负责运行 Open WebUI 和 Ollama
聊天模型qwen2.5:7b 或 qwen2.5:3b7B 效果和资源消耗更高
向量嵌入模型BAAI/bge-m3适合多语言和中文文档,首次使用需要下载
Web 界面Open WebUI提供聊天、账号、知识库和模型选择
Web 入口Nginx + Certbot提供域名、HTTPS 和长连接转发

示例配置使用滚动镜像标签,便于新手直接安装。用于长期生产环境时,完成首次验证后应将镜像改成经过测试的固定版本或镜像摘要,并在升级前保存备份。

3. 服务器资源参考

场景CPU内存可用磁盘建议模型
轻量测试2 核8 GB40 GB3B 级模型
个人知识库4 核16 GB60 GB7B 级量化模型
多人并发8 核以上32 GB 以上100 GB 以上GPU 或外部模型服务更合适

模型文件、嵌入模型、聊天数据和文档索引都会占用磁盘。qwen2.5:7b 的实际占用会随量化格式和模型标签变化,通常需要数 GB;BAAI/bge-m3 首次下载也可能占用数 GB。上表是部署规划参考,不是固定容量要求。

如果服务器只有 2 GB 或 4 GB 内存,不建议直接部署 7B 模型。可以先使用 3B 模型验证完整流程,再根据内存、响应速度和文档规模扩容。

4. 网络和域名条件

上线前准备以下信息:

  • 服务器公网 IPv4;
  • 一个已经注册的域名或子域名,例如 assistant.example.com;
  • 域名的 A 记录指向服务器 IPv4;
  • 云厂商安全组放行 TCP 22、80 和 443;
  • 服务器本机防火墙也允许 SSH 和 Web 端口;
  • 能够从服务器正常访问 Docker 镜像仓库和模型下载地址。

建议先确认 DNS:

dig +short assistant.example.com

预期结果应包含服务器公网 IPv4。如果命令没有输出,或者返回了其他地址,应先修正 DNS,再执行 HTTPS 配置。

二、初始化 Ubuntu 服务器

1. 核对系统、架构和资源

登录服务器后,先不要急于安装软件,确认操作系统和资源是否符合预期:

cat /etc/os-release
uname -m
nproc
free -h
df -h /

常见的可接受结果类似:

NAME="Ubuntu"
VERSION_ID="24.04"

x86_64
4
Mem:           15Gi
Avail Mem:     13Gi
Filesystem      Size  Used Avail Use%
/                80G   10G   66G  14%

需要重点关注:

  • uname -m 是否为 x86_64;
  • 可用内存是否满足模型要求;
  • / 分区是否有足够空间;
  • 服务器是否是 Ubuntu,而不是 Debian、AlmaLinux 等其他系统。

如果系统不是 Ubuntu,不要直接照搬后面的 apt 命令,应先根据发行版调整 Docker、Nginx 和防火墙安装方式。

2. 创建日常管理账号

不要长期使用 root 账号运行应用。使用具备 sudo 权限的普通账号进行部署:

sudo adduser aiadmin
sudo usermod -aG sudo aiadmin

命令会要求设置密码和用户信息。随后从本地电脑为该用户配置 SSH 公钥。以下命令应在本地电脑执行,而不是服务器上执行:

ssh-copy-id aiadmin@SERVER_IP

替换为实际服务器地址后,重新打开一个终端测试:

ssh aiadmin@SERVER_IP

只有在新账号可以登录后,才进行 SSH 加固。如果无法登录,不要关闭当前 root 会话或现有 SSH 会话。

3. 更新系统并设置时区

先查看当前时区:

timedatectl

个人知识库和日志通常使用 UTC 更容易排查跨地区问题,也可以根据业务所在地设置其他时区。以下以 UTC 为例:

sudo timedatectl set-timezone Etc/UTC
sudo apt-get update
sudo apt-get upgrade -y

系统升级可能涉及内核和基础库,执行前应确认服务器有云厂商快照或可用控制台。升级完成后检查是否需要重启:

sudo needrestart

如果提示需要重启,选择业务低峰期执行:

sudo reboot

重启后重新登录,并再次确认 Docker、SSH 和网络状态。

4. 加固 SSH,并配置防火墙

SSH 配置和防火墙调整都可能导致远程失联。执行前必须满足两个条件:

  1. 已经用 aiadmin 成功登录;
  2. 当前 root 或旧 SSH 会话仍然保持连接,便于回滚。

先安装并配置 UFW:

sudo apt-get install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status numbered

如果 SSH 使用的不是 22 端口,应放行实际端口,不要只放行 22。确认云厂商安全组也放行相同端口后,再启用防火墙:

sudo ufw enable
sudo ufw status verbose

之后再配置 SSH 公钥登录。确认新 SSH 会话正常后,创建加固配置:

sudo tee /etc/ssh/sshd_config.d/99-ai-assistant-hardening.conf >/dev/null <<'EOF'
PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin no
PubkeyAuthentication yes
UsePAM yes
EOF

先检查语法,再重新加载 SSH:

sudo sshd -t
sudo systemctl reload ssh

如果 sshd -t 没有输出,通常代表语法通过。此时使用新终端再次测试:

ssh aiadmin@SERVER_IP

如果测试失败,不要关闭当前可用会话。可以从服务器控制台或原有 root 会话回滚:

sudo rm -f /etc/ssh/sshd_config.d/99-ai-assistant-hardening.conf
sudo systemctl reload ssh
sudo ufw disable

ufw disable 只用于远程失联排查,恢复连接后应重新按实际端口配置防火墙。

三、安装 Docker 和 Compose

1. 添加 Docker 软件源

以下命令适用于 Ubuntu 22.04/24.04:

sudo apt-get update
sudo apt-get install -y ca-certificates curl

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "${VERSION_CODENAME}") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

启动 Docker 并设置为开机启动:

sudo systemctl enable --now docker
sudo systemctl status docker --no-pager

把当前用户加入 Docker 用户组:

sudo usermod -aG docker "$USER"

Docker 用户组具备接近 root 的宿主机控制能力,因此只给可信的管理账号使用。执行后退出 SSH,再重新登录,或者临时刷新当前会话:

newgrp docker

2. 验证 Docker 环境

docker run --rm hello-world
docker compose version

预期结果应包含 Docker 的欢迎信息和 Compose 版本。如果出现 permission denied,通常是用户组尚未刷新;如果出现 Docker daemon 连接错误,检查:

sudo systemctl restart docker
sudo systemctl status docker --no-pager

不要在 Docker 服务未正常运行时继续创建应用容器。

四、创建 Open WebUI 与 Ollama

1. 创建项目目录

使用普通管理账号进入项目目录:

sudo mkdir -p /opt/ai-assistant/backups
sudo chown -R "$USER":"$USER" /opt/ai-assistant
cd /opt/ai-assistant
umask 077

目录中将保存 Compose 配置、环境变量和备份文件。环境变量文件包含密钥,不应设置为公开可读。

2. 创建环境变量文件

先替换域名,再生成随机密钥:

WEBUI_SECRET_KEY="$(openssl rand -hex 32)"

cat > .env <<EOF
WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY}
WEBUI_URL=https://assistant.example.com
ENABLE_SIGNUP=true
TZ=Etc/UTC
EOF

chmod 600 .env

将 assistant.example.com 改成自己的域名。ENABLE_SIGNUP=true 只用于第一次注册管理员账号,完成注册后要改为 false。

检查文件权限,但不要直接把密钥打印到终端:

ls -l .env
grep -E '^(WEBUI_URL|ENABLE_SIGNUP|TZ)=' .env

3. 编写 Compose 配置

创建 compose.yaml:

cat > compose.yaml <<'EOF'
services:
  ollama:
    image: ollama/ollama:latest
    container_name: ai-ollama
    restart: unless-stopped
    volumes:
      - ollama-/root/.ollama

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: ai-open-webui
    restart: unless-stopped
    depends_on:
      - ollama
    ports:
      - "127.0.0.1:3000:8080"
    environment:
      OLLAMA_BASE_URL: http://ollama:11434
      WEBUI_SECRET_KEY: ${WEBUI_SECRET_KEY}
      WEBUI_URL: ${WEBUI_URL}
      ENABLE_SIGNUP: ${ENABLE_SIGNUP:-true}
      TZ: ${TZ:-Etc/UTC}
      RAG_EMBEDDING_ENGINE: sentence_transformers
      RAG_EMBEDDING_MODEL: BAAI/bge-m3
      HF_HOME: /app/backend/data/cache/huggingface
    volumes:
      - open-webui-/app/backend/data

volumes:
  ollama-
    name: aiassistant-ollama-data
  open-webui-
    name: aiassistant-open-webui-data
EOF

这里有几个关键点:

  • Ollama 没有 ports 配置,只能被同一 Docker 网络中的 Open WebUI 访问;
  • Open WebUI 绑定到 127.0.0.1:3000,外部不能直接访问 3000 端口;
  • open-webui-data 保存账号、聊天和知识库数据;
  • ollama-data 保存已经下载的模型;
  • BAAI/bge-m3 用于文档向量化,适合中文和多语言内容,但首次索引前会下载模型。

如果服务器内存较小,运行嵌入模型时可能会出现内存压力。可以先把 RAG_EMBEDDING_MODEL 改为 Open WebUI 镜像默认的嵌入模型,但中文检索效果需要用自己的文档测试。更换嵌入模型后,已有知识库通常需要重新索引,不建议在没有备份的情况下频繁切换。

4. 检查并启动容器

先检查 Compose 文件能否正确展开:

docker compose config

如果输出了完整配置且没有 variable is not set、YAML 缩进错误等提示,再拉取镜像:

docker compose pull

启动服务:

docker compose up -d
docker compose ps

预期状态类似:

NAME             IMAGE                              STATUS
ai-ollama        ollama/ollama:latest               Up
ai-open-webui    ghcr.io/open-webui/open-webui:main Up

Open WebUI 的状态显示为 Up 即可,不一定会显示 healthy,因为示例配置没有额外添加健康检查。

5. 验证容器内部连接

先检查本机 3000 端口:

curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  http://127.0.0.1:3000/

常见成功结果是 HTTP 200 或 HTTP 302。

检查 Ollama 容器和模型列表:

docker compose exec ollama ollama list

刚启动时列表可能为空,这是正常的。再查看最近日志:

docker compose logs --tail=100 ollama
docker compose logs --tail=100 open-webui

如果 Open WebUI 日志反复出现连接 Ollama 失败,先确认两个容器都在运行,再检查 Compose 中的地址是否为:

http://ollama:11434

不要把容器之间的地址写成 127.0.0.1:11434。在 Open WebUI 容器里,127.0.0.1 指向的是 Open WebUI 自身,不是 Ollama。

外层为Ubuntu宿主机,内层为Docker内部网络及两个独立容器;分别标注宿主机127.0.0.1:3000、Open WebUI容器8080和Ollama容

五、下载模型并验证对话

1. 下载中文聊天模型

16 GB 内存的服务器可以先尝试 7B 模型:

docker compose exec ollama ollama pull qwen2.5:7b

如果只有 8 GB 内存,或者下载后推理时频繁被系统终止,改用 3B 模型:

docker compose exec ollama ollama pull qwen2.5:3b

查看已下载模型:

docker compose exec ollama ollama list

输出可能类似:

NAME           ID              SIZE      MODIFIED
qwen2.5:7b     xxxxxxxx        4.7 GB    a few seconds ago

这里的大小是示例格式,实际模型大小会因标签和量化方式不同而变化。

2. 从命令行做一次推理测试

在接入 Web 界面前,可以先确认 Ollama 能否加载模型:

docker compose exec ollama ollama run qwen2.5:7b \
  "请用一句话说明知识库检索的作用。"

如果使用的是 3B 模型,将命令中的模型名替换为 qwen2.5:3b。

首次运行会加载模型,CPU 服务器可能需要较长时间。成功时应返回一段中文回答,并回到终端提示符。常见失败情况如下:

  • model not found:模型没有下载成功,重新执行 ollama pull;
  • no space left on device:磁盘不足,清理无关镜像或扩容;
  • 容器被系统终止:通常与内存不足有关,改用 3B 模型;
  • 下载速度很慢或中断:检查服务器对镜像仓库和模型下载地址的出站访问。

3. 通过浏览器访问 Open WebUI

模型验证通过后,再配置正式域名入口。先确认域名 A 记录已经生效:

dig +short assistant.example.com

安装 Nginx 和 Certbot:

sudo apt-get update
sudo apt-get install -y nginx certbot python3-certbot-nginx
sudo systemctl enable --now nginx

创建 Nginx 站点配置:

sudo tee /etc/nginx/sites-available/ai-assistant >/dev/null <<'EOF'
server {
    listen 80;
    listen [::]:80;

    server_name assistant.example.com;

    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
        proxy_buffering off;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/ai-assistant \
  /etc/nginx/sites-enabled/ai-assistant

将配置中的 assistant.example.com 替换为真实域名,然后检查并加载:

sudo nginx -t
sudo systemctl reload nginx

在 HTTPS 证书申请前,先验证 HTTP 反向代理:

curl -I -H 'Host: assistant.example.com' http://127.0.0.1/

如果返回 200 或 302,说明 Nginx 已经能够连接 Open WebUI。如果返回 502 Bad Gateway,检查:

sudo systemctl status nginx --no-pager
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:3000/
docker compose ps

4. 申请 HTTPS 证书

确认域名已经解析到本机,并且云安全组和 UFW 都允许 80、443 端口后执行:

sudo certbot --nginx -d assistant.example.com --redirect

Certbot 会交互式询问邮箱和协议选项。成功后测试自动续期:

sudo certbot renew --dry-run

再从服务器或外部网络检查 HTTPS:

curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  https://assistant.example.com/

浏览器打开:

https://assistant.example.com

如果看到 Open WebUI 注册界面,说明 Web 入口已经打通。

六、创建管理员并搭建知识库

1. 注册第一个管理员账号

首次打开页面时,使用准备好的邮箱和密码注册第一个账号。Open WebUI 通常会把首个注册账号作为管理员账号。

注册完成后,不要继续保持公开注册状态。回到服务器项目目录:

cd /opt/ai-assistant
cp .env ".env.bak.$(date +%Y%m%d%H%M%S)"
sed -i 's/^ENABLE_SIGNUP=.*/ENABLE_SIGNUP=false/' .env
docker compose up -d open-webui

确认变量已经修改:

grep '^ENABLE_SIGNUP=' .env

预期结果:

ENABLE_SIGNUP=false

如果后续需要增加用户,应通过管理员界面创建或邀请账号,而不是重新开放匿名注册。

2. 在界面中创建知识库

不同 Open WebUI 版本的菜单名称可能略有区别,一般可以按以下顺序操作:

  1. 登录管理员账号;
  2. 打开工作区或管理区域;
  3. 进入 Knowledge、知识库 或类似入口;
  4. 创建一个知识库,例如 产品文档;
  5. 上传 Markdown、TXT、PDF 或 DOCX 文件;
  6. 等待文档解析和向量索引完成;
  7. 在新建聊天时选择该知识库。

先创建一个小型测试文件,避免一开始就上传数百个文档:

cat > /tmp/knowledge-demo.md <<'EOF'
# 产品部署规范

本项目的备份周期为每天一次,保留最近七个备份。
生产环境的应用端口只允许通过 Nginx 反向代理访问。
文档检索测试口令为:蓝松树-2025。
EOF

将这个文件通过 Web 界面上传到 产品文档 知识库。首次使用 BAAI/bge-m3 时,Open WebUI 需要下载嵌入模型并建立索引,可能消耗一定时间和内存。可以通过日志观察处理状态:

cd /opt/ai-assistant
docker compose logs -f --tail=100 open-webui

如果日志持续输出下载、解析或 embedding 相关信息,可以等待任务完成。若出现错误,先按后文的故障处理步骤检查磁盘、内存和网络。

3. 验证知识库检索

在聊天页面选择刚创建的知识库,依次测试以下问题:

产品文档规定的备份周期是多少?

预期回答应包含“每天一次,保留最近七个备份”等信息,并尽量显示引用的文档来源。

再测试一个文档中没有出现的问题:

产品文档是否规定了数据库密码?

合理结果应该是说明文档中没有相关信息,而不是直接编造密码。知识库检索只能降低无依据回答的概率,不能代替权限控制和人工审核。涉及密码、密钥、客户数据或内部配置时,应避免上传到不必要的知识库,并为不同用户设置对应的访问权限。

六、创建管理员并搭建知识库 / 3. 验证知识库检索配图

如果问答内容与文档不相关,按以下顺序排查:

  • 确认聊天窗口确实选择了目标知识库;
  • 用短文档和明确问题做测试;
  • 检查 PDF 是否为扫描图片,纯图片 PDF 可能没有可检索文本;
  • 检查上传任务是否已经完成;
  • 查看 Open WebUI 日志中是否出现 embedding 或索引错误;
  • 不要先急着更换聊天模型,先确认检索链路正常。

七、常见异常与处理方式

1. Open WebUI 显示 502

先区分是 Nginx 问题还是应用问题:

curl -sS -o /dev/null -w 'local HTTP %{http_code}\n' \
  http://127.0.0.1:3000/

sudo nginx -t
sudo systemctl status nginx --no-pager
docker compose ps

不同结果代表的含义:

  • 本机 3000 返回 200,域名返回 502:检查 Nginx 配置、端口和 SELinux 等系统策略;
  • 本机 3000 也无法访问:检查 ai-open-webui 容器日志;
  • 容器显示 Exited:执行 docker compose logs --tail=200 open-webui;
  • Nginx 配置检查失败:不要 reload,修正配置后再次执行 nginx -t。

查看应用日志:

docker compose logs --tail=200 open-webui

不要直接删除容器数据目录。大多数启动问题都可以通过修正环境变量、恢复 Compose 配置或重新创建容器解决。

2. 模型加载时内存不足

检查内存和容器占用:

free -h
docker stats --no-stream
dmesg -T | grep -i -E 'out of memory|killed process'

如果确认是 7B 模型占用过高,先下载 3B 模型:

docker compose exec ollama ollama pull qwen2.5:3b

然后在 Open WebUI 中选择 qwen2.5:3b 测试。如果 3B 模型可用且需要释放磁盘,再删除旧模型:

docker compose exec ollama ollama rm qwen2.5:7b

ollama rm 只删除指定模型,不会删除 Open WebUI 账号和知识库,但执行前应确认模型名称无误。不要用删除 Docker 卷的方式释放模型空间,因为那会同时影响持久化数据。

3. 模型下载失败

先查看容器日志和磁盘空间:

docker compose logs --tail=100 ollama
df -h /

重新执行:

docker compose exec ollama ollama pull qwen2.5:3b

如果下载反复中断,应检查服务器的出站网络、DNS 和云厂商网络策略。不要把 Ollama 的 11434 端口直接暴露到公网来“测试连接”,本教程的正确方式是使用 Open WebUI 容器内部访问。

4. 知识库索引失败

检查磁盘、内存和 Open WebUI 日志:

df -h /
free -h
docker compose logs --tail=200 open-webui | \
  grep -i -E 'embedding|index|error|exception'

常见原因包括:

  • 磁盘空间不足;
  • 首次下载嵌入模型时网络中断;
  • 文档本身是扫描图片,没有文本层;
  • 单个文件过大或格式解析失败;
  • 更换嵌入模型后没有重新建立索引。

可以先删除测试文档中的复杂格式,改用纯 Markdown 或 TXT 验证。对于扫描 PDF,需要先经过 OCR,再上传可检索的文本版本。

如果服务器无法下载 BAAI/bge-m3,可以在 .env 之外修改 Compose 中的嵌入模型配置,使用镜像默认模型作为临时验证方案:

RAG_EMBEDDING_MODEL: sentence-transformers/all-MiniLM-L6-v2

修改后执行:

docker compose config
docker compose up -d open-webui

该模型对中文内容的检索效果需要自行验证。已经建立的知识库可能需要重新索引,正式切换前应先备份数据。

5. 浏览器提示证书申请失败

检查域名解析:

dig +short assistant.example.com

检查 80 端口:

curl -I http://assistant.example.com

常见原因有:

  • A 记录没有指向当前服务器;
  • 云安全组没有放行 80;
  • UFW 没有放行 80;
  • Nginx 没有启动;
  • 域名存在错误的 AAAA 记录,导致部分网络访问到了另一台 IPv6 主机;
  • Nginx server_name 与实际域名不一致。

修正 DNS 或 Nginx 后,先执行:

sudo nginx -t
sudo systemctl reload nginx

再重新运行 Certbot。不要在证书问题未解决时反复删除证书目录。

6. 上传文档返回 413

413 Request Entity Too Large 通常是 Nginx 的上传大小限制导致。配置中的:

client_max_body_size 50m;

表示单次请求最大约 50 MB。修改后执行:

sudo nginx -t
sudo systemctl reload nginx

如果确实需要更大的文档,应同时考虑上传耗时、内存和索引时间,不建议只盲目增加到数百 MB。大型文档更适合拆分成章节后分别上传,便于检索和定位来源。

7. 3000 端口被公网监听

检查监听地址:

sudo ss -lntp | grep -E ':(3000|80|443)\b'

正确结果中,3000 应类似:

127.0.0.1:3000

如果显示为 0.0.0.0:3000 或 [::]:3000,说明 Compose 配置被改成了公网绑定。确认 compose.yaml 中存在:

ports:
  - "127.0.0.1:3000:8080"

然后重新创建容器:

docker compose up -d --force-recreate open-webui

再次检查监听地址。不要仅依赖 UFW 保护错误暴露的应用端口,应用本身应先绑定到本机回环地址。

八、上线后的备份与升级

1. 保存配置和数据

应用数据、模型和配置分别保存:

  • .env:密钥、域名和注册开关;
  • compose.yaml:容器结构和环境变量;
  • aiassistant-open-webui-data:账号、聊天、知识库和索引;
  • aiassistant-ollama-data:已下载的模型。

建议首次上线后立即做一次完整备份:

cd /opt/ai-assistant
umask 077

TS="$(date +%Y%m%d%H%M%S)"
cp compose.yaml "backups/compose-${TS}.yaml"
cp .env "backups/env-${TS}"

docker compose down

docker run --rm \
  -v aiassistant-open-webui-/ro \
  -v "$PWD/backups:/backup" \
  alpine:3.20 \
  tar czf "/backup/open-webui-data-${TS}.tar.gz" -C /data .

docker run --rm \
  -v aiassistant-ollama-/ro \
  -v "$PWD/backups:/backup" \
  alpine:3.20 \
  tar czf "/backup/ollama-data-${TS}.tar.gz" -C /data .

chmod 600 backups/*
docker compose up -d

备份过程中会短暂停止聊天服务,模型文件备份也可能需要较长时间。磁盘空间不足时,可以只备份 Open WebUI 数据,模型文件以后重新拉取:

docker compose down

docker run --rm \
  -v aiassistant-open-webui-/ro \
  -v "$PWD/backups:/backup" \
  alpine:3.20 \
  tar czf "/backup/open-webui-data-$(date +%Y%m%d%H%M%S).tar.gz" -C /data .

docker compose up -d

备份文件包含登录数据和知识库内容,应复制到另一台受控存储位置,不能直接放在公开 Web 目录中。

2. 升级前的操作顺序

升级前按以下顺序执行:

cd /opt/ai-assistant
docker compose ps
docker compose config

确认配置有效后,先按上一节备份,再拉取新镜像:

docker compose pull
docker compose up -d
docker compose ps

验证以下项目:

curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  http://127.0.0.1:3000/

docker compose exec ollama ollama list
docker compose logs --tail=100 open-webui

如果使用 main 或 latest,历史镜像回滚能力取决于本地缓存,不能把滚动标签当成可靠的版本记录。正式环境应在测试通过后,把 Compose 中的镜像替换为固定版本标签或摘要,并记录升级前后的版本。

九、回滚操作

1. 只回滚配置文件

如果升级后只是域名、环境变量或 Compose 配置错误,先停止受影响的服务,再恢复升级前文件:

cd /opt/ai-assistant
docker compose down

找到对应备份文件后恢复:

cp backups/compose-YYYYMMDDHHMMSS.yaml compose.yaml
cp backups/env-YYYYMMDDHHMMSS .env
chmod 600 .env

docker compose config
docker compose up -d

将 YYYYMMDDHHMMSS 替换为实际备份时间。docker compose down 不会删除命名卷,正常回滚不要添加 -v 参数。

2. 恢复 Open WebUI 数据

如果聊天记录、账号或知识库数据损坏,需要从归档恢复。以下操作会清空目标 Docker 卷中的现有内容,执行前确认备份文件可读,并确认服务已经停止:

cd /opt/ai-assistant
docker compose down

BACKUP_FILE="$(ls -1t backups/open-webui-data-*.tar.gz | head -n1)"
test -s "$BACKUP_FILE"

docker run --rm \
  -v aiassistant-open-webui-/data \
  -v "$PWD:/restore" \
  alpine:3.20 \
  sh -c "find /data -mindepth 1 -maxdepth 1 -exec rm -rf -- {} + && tar xzf /restore/$BACKUP_FILE -C /data"

docker compose up -d

上述 find 命令只清空 aiassistant-open-webui-data 卷,不会删除宿主机项目目录,但仍属于破坏性操作。执行前必须确认 BACKUP_FILE 指向正确归档。

如果需要恢复 Ollama 模型:

cd /opt/ai-assistant
docker compose down

BACKUP_FILE="$(ls -1t backups/ollama-data-*.tar.gz | head -n1)"
test -s "$BACKUP_FILE"

docker run --rm \
  -v aiassistant-ollama-/data \
  -v "$PWD:/restore" \
  alpine:3.20 \
  sh -c "find /data -mindepth 1 -maxdepth 1 -exec rm -rf -- {} + && tar xzf /restore/$BACKUP_FILE -C /data"

docker compose up -d

如果没有备份 Ollama 模型,也可以只恢复 Open WebUI 数据,然后重新执行:

九、回滚操作 / 2. 恢复 Open WebUI 数据配图

docker compose exec ollama ollama pull qwen2.5:3b

3. 回滚后的验证

恢复后依次检查:

docker compose ps
docker compose exec ollama ollama list
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' \
  http://127.0.0.1:3000/
curl -sS -o /dev/null -w 'HTTPS %{http_code}\n' \
  https://assistant.example.com/

然后在浏览器中确认:

  • 管理员账号仍然可以登录;
  • 原有聊天记录仍能打开;
  • 知识库仍然存在;
  • 选择知识库后可以回答测试问题;
  • HTTPS 证书和域名没有变化;
  • 3000 端口没有对公网监听。

十、上线验收清单

正式交付前,可以按以下清单逐项确认:

  • [ ] Ubuntu 版本和 CPU 架构符合部署要求;
  • [ ] 磁盘和内存有足够余量;
  • [ ] aiadmin 可以通过 SSH 公钥登录;
  • [ ] SSH 加固前已经测试新会话;
  • [ ] UFW 和云安全组只放行必要端口;
  • [ ] Docker 服务设置为开机启动;
  • [ ] docker compose config 检查通过;
  • [ ] Ollama 和 Open WebUI 容器状态为 Up;
  • [ ] 聊天模型已经下载并完成命令行推理;
  • [ ] Open WebUI 只绑定 127.0.0.1:3000;
  • [ ] Nginx 配置检查通过;
  • [ ] 域名 A 记录指向当前服务器;
  • [ ] HTTPS 页面可以正常打开;
  • [ ] Certbot 自动续期演练通过;
  • [ ] 第一个账号已经注册为管理员;
  • [ ] 公开注册已经关闭;
  • [ ] 测试文档能够完成解析和索引;
  • [ ] 知识库问题能够返回相关内容;
  • [ ] 文档外问题不会直接暴露内部信息;
  • [ ] Open WebUI 数据已经备份;
  • [ ] 需要时可以恢复 Compose 配置和 Docker 卷;
  • [ ] 升级前后的镜像版本已经记录。

完成这些检查后,海外服务器上的本地 AI 聊天助手就具备了基本上线条件。后续扩容时,优先观察内存、磁盘、模型响应时间、知识库索引耗时和并发请求数量,再决定是否更换更大模型、增加 GPU 或拆分推理与 Web 服务。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/2939.html