新手如何在海外服务器搭建自己的AI聊天助手?从环境准备到上线验证
这套部署把自己的 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:3b | 7B 效果和资源消耗更高 |
| 向量嵌入模型 | BAAI/bge-m3 | 适合多语言和中文文档,首次使用需要下载 |
| Web 界面 | Open WebUI | 提供聊天、账号、知识库和模型选择 |
| Web 入口 | Nginx + Certbot | 提供域名、HTTPS 和长连接转发 |
示例配置使用滚动镜像标签,便于新手直接安装。用于长期生产环境时,完成首次验证后应将镜像改成经过测试的固定版本或镜像摘要,并在升级前保存备份。
3. 服务器资源参考
| 场景 | CPU | 内存 | 可用磁盘 | 建议模型 |
|---|---|---|---|---|
| 轻量测试 | 2 核 | 8 GB | 40 GB | 3B 级模型 |
| 个人知识库 | 4 核 | 16 GB | 60 GB | 7B 级量化模型 |
| 多人并发 | 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 配置和防火墙调整都可能导致远程失联。执行前必须满足两个条件:
- 已经用
aiadmin成功登录; - 当前 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。

五、下载模型并验证对话
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 版本的菜单名称可能略有区别,一般可以按以下顺序操作:
- 登录管理员账号;
- 打开工作区或管理区域;
- 进入
Knowledge、知识库或类似入口; - 创建一个知识库,例如
产品文档; - 上传 Markdown、TXT、PDF 或 DOCX 文件;
- 等待文档解析和向量索引完成;
- 在新建聊天时选择该知识库。
先创建一个小型测试文件,避免一开始就上传数百个文档:
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. 验证知识库检索
在聊天页面选择刚创建的知识库,依次测试以下问题:
产品文档规定的备份周期是多少?
预期回答应包含“每天一次,保留最近七个备份”等信息,并尽量显示引用的文档来源。
再测试一个文档中没有出现的问题:
产品文档是否规定了数据库密码?
合理结果应该是说明文档中没有相关信息,而不是直接编造密码。知识库检索只能降低无依据回答的概率,不能代替权限控制和人工审核。涉及密码、密钥、客户数据或内部配置时,应避免上传到不必要的知识库,并为不同用户设置对应的访问权限。

如果问答内容与文档不相关,按以下顺序排查:
- 确认聊天窗口确实选择了目标知识库;
- 用短文档和明确问题做测试;
- 检查 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 数据,然后重新执行:

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