1. 这不是“装个软件”而是本地大模型交互入口的完整基建工程Open WebUI 的部署远不止是执行几条docker run命令那么简单。它本质上是在你自己的机器上亲手搭建一个可长期稳定运行、能无缝对接本地推理引擎、具备用户管理与数据持久化能力的AI对话前端基础设施。很多人卡在第一步——容器跑起来了页面打不开或者页面打开了模型列表为空再或者登录成功了一提问就报错“Connection refused”。这些都不是偶然而是因为 Open WebUI 并非一个独立运行的“应用”它是一个严格依赖外部服务、对网络拓扑和环境变量极其敏感的协同系统。核心关键词里反复出现的OLLAMA_BASE_URL就是这整套系统的“神经中枢”。它不是一个可有可无的配置项而是 Open WebUI 与 Ollama 之间建立通信的唯一信道。如果你把它设成http://localhost:11434而 Ollama 实际监听的是127.0.0.1:11434在 Docker 容器网络环境下这二者根本不在同一个“世界”里——容器内的localhost指向的是容器自己而不是宿主机。这就是为什么大量新手在 Ubuntu 或 macOS 上能一次成功却在 openEuler 或 CentOS 等服务器发行版上反复失败的根本原因他们复制粘贴的命令没有适配不同操作系统默认的网络命名空间隔离策略。更关键的是openEuler 这个词高频出现在热搜中绝非偶然。它代表了一类典型的国产化、高安全、强管控的生产级操作系统环境。在这里systemd服务管理、防火墙策略、SELinux或其等效机制、以及默认禁用的net.ipv4.ip_forward内核参数都会成为部署路上的隐形路障。你看到的docker run -p 3000:8080命令在 openEuler 上可能需要额外加上--networkhost才能打通 Ollama 的调用链而这又会带来端口冲突的新问题。所以这篇博文不叫“Open WebUI 安装教程”而叫“Open WebUI.1部署”这个“.1”代表的是从零开始构建一个可信赖、可审计、可维护的本地大模型交互平台的第一步。它面向的不是想“试试看”的小白而是准备把大模型真正用起来、管起来、长期跑下去的工程师、研究员和系统管理员。接下来的所有内容都将围绕这个目标展开每一步操作都附带其背后的系统原理和 openEuler 特有的注意事项。2. 为什么必须先搞定 Ollama——Open WebUI 的“大脑”与“小脑”分工在动手部署 Open WebUI 之前我强烈建议你把所有精力先投入到 Ollama 的安装与验证上。这不是本末倒置而是由整个技术栈的职责划分决定的。你可以把 Ollama 理解为整个系统的“大脑”它负责模型的加载、卸载、推理计算、GPU 资源调度以及最底层的 HTTP API 服务。而 Open WebUI 则是“小脑”兼“手和嘴”它不进行任何计算只负责接收用户的输入文字、文件将请求格式化后通过OLLAMA_BASE_URL这个地址转发给 Ollama 的 API再把 Ollama 返回的 JSON 响应解析、渲染成漂亮的网页界面并管理用户会话和历史记录。这个分工意味着Open WebUI 的健康状态完全取决于 Ollama 的可用性与可达性。如果 Ollama 没启动或者启动了但没监听正确的地址或者被防火墙拦住了那么无论你把 Open WebUI 配置得多么完美它都只能显示一个冰冷的错误“Failed to fetch models” 或 “Connection refused”。在 openEuler 环境下Ollama 的安装尤其需要谨慎。官方推荐的curl -fsSL https://ollama.com/install.sh | sh命令在 openEuler 22.03/24.03 上可能会遇到两个经典问题一是glibc版本兼容性二是curl默认不信任某些国内镜像站的 SSL 证书。我试过三次有两次都卡在curl: (60) SSL certificate problem。解决方法不是强行加-k参数那会带来安全风险而是先更新系统证书库sudo dnf update -y ca-certificates然后再执行安装脚本。安装完成后Ollama 默认是以systemd服务形式运行的其配置文件位于/etc/systemd/system/ollama.service。这里就是第一个也是最关键的配置点。打开它sudo vim /etc/systemd/system/ollama.service找到[Service]这一节在下面添加两行EnvironmentOLLAMA_HOST0.0.0.0:11434 EnvironmentOLLAMA_ORIGINShttp://localhost:3000,http://127.0.0.1:3000,http://192.168.*.*:3000第一行OLLAMA_HOST是核心中的核心。它告诉 Ollama“别只听 localhost要把服务绑定到所有网络接口上让其他机器比如你的 Open WebUI 容器也能访问到我。” 第二行OLLAMA_ORIGINS是 CORS跨域资源共享白名单它定义了哪些来源的网页可以向 Ollama 发起 API 请求。http://192.168.*.*:3000这个通配符写法是为了覆盖你在局域网内可能使用的各种 IP 地址段避免部署完后只能在服务器本机访问而无法从办公室电脑或手机浏览器访问。修改完配置后千万别忘了重载并重启服务sudo systemctl daemon-reload sudo systemctl restart ollama sudo systemctl status ollama # 检查状态确认 Active: active (running)验证是否成功最直接的方法是用curl在服务器本机测试curl http://127.0.0.1:11434/api/tags如果返回一个包含models数组的 JSON说明 Ollama 的 API 已经正常工作。如果返回curl: (7) Failed to connect to 127.0.0.1 port 11434: Connection refused那就说明OLLAMA_HOST配置没生效或者服务根本没起来。此时你应该立刻查看日志sudo journalctl -u ollama -f --since 2 minutes ago日志里通常会清晰地告诉你是权限问题、端口被占用还是配置语法错误。记住在 openEuler 上journalctl是你最忠实的朋友它的日志比任何文档都来得真实。提示在 openEuler 上firewalld防火墙默认是开启的。即使 Ollama 监听了0.0.0.0:11434如果防火墙没放行这个端口外部请求依然会被丢弃。执行sudo firewall-cmd --permanent --add-port11434/tcp和sudo firewall-cmd --reload来永久开放端口。3. Docker 镜像拉取的“三重门”网络、镜像源与架构兼容性当你确认 Ollama 已经稳稳当当地运行在0.0.0.0:11434后下一步才是部署 Open WebUI。但别急着docker run先要过 Docker 镜像拉取这一关。这看似简单的一步在 openEuler 环境下实际上横亘着三道必须跨越的“门”。第一道门网络连通性与 DNS 解析。ghcr.ioGitHub Container Registry是 Open WebUI 的官方镜像源但它在国内的访问速度极不稳定经常超时或直接连接失败。这不是 Docker 的问题而是网络路由的问题。很多 openEuler 服务器部署在阿里云、华为云等国内云厂商的 VPC 内其默认的 DNS 解析策略可能无法高效地解析ghcr.io的域名。一个立竿见影的验证方法是在服务器上执行ping -c 4 ghcr.io如果出现unknown host或者100% packet loss那你就必须更换镜像源。这时热搜词里提到的swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/open-webui/open-webui就派上用场了。这是华为云 SWRSoftware Repository for Containers提供的国内加速镜像。使用它命令变为docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/open-webui/open-webui:latest第二道门镜像标签Tag的选择。latest标签看似方便实则暗藏风险。它指向的是最新构建的镜像但这个“最新”可能是一个尚未经过充分测试的开发版本。对于生产环境或希望长期稳定的个人工作站我强烈推荐使用main标签它对应的是主分支的稳定快照。官方文档也明确指出main是推荐用于生产的标签。因此最终的拉取命令应该是docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/open-webui/open-webui:main第三道门CPU 架构的兼容性。这是最容易被忽略却会导致最诡异问题的一点。openEuler 24.03 LTS 支持 x86_64 和 aarch64ARM64两种主流架构。而ghcr.io/open-webui/open-webui官方镜像目前主要提供的是linux/amd64即 x86_64架构的镜像。如果你的 openEuler 服务器是一台基于鲲鹏Kunpeng或飞腾Phytium的 ARM64 服务器直接拉取amd64镜像Docker 会报错no matching manifest for linux/arm64。此时你有两个选择一是寻找社区编译的 ARM64 兼容镜像例如ghcr.io/open-webui/open-webui:main-arm64但这需要你自己去 GitHub Issues 里搜索确认二是退而求其次使用--platform linux/amd64参数强制运行 x86_64 镜像这需要你的 ARM64 CPU 支持qemu-user-static模拟性能会有损耗。我建议优先尝试第一种因为第二种方案在处理大模型推理时性能下降会非常显著。拉取成功后用docker images命令检查镜像是否已存在。你会看到类似这样的输出REPOSITORY TAG IMAGE ID CREATED SIZE swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/open-webui/open-webui main abc123def456 2 weeks ago 1.2GB注意IMAGE ID这一列它是一个唯一的指纹。在后续的docker run命令中你可以直接用这个 ID 来启动容器这样可以彻底规避因镜像名过长或包含特殊字符如斜杠带来的潜在问题。这也是我在实际运维中养成的一个习惯一旦镜像拉取成功立刻记下它的 ID后续所有操作都基于 ID确保万无一失。注意在 openEuler 上Docker 的存储驱动默认可能是overlay2这没问题。但如果你的根分区空间不足小于 20GBdocker pull可能会失败并提示no space left on device。此时你需要清理旧的镜像和容器或者将 Docker 的根目录迁移到一个更大的磁盘分区上。df -h是你排查此类问题的第一个命令。4. 启动命令的“七十二变”从基础运行到生产就绪的完整演进现在镜像有了Ollama 也活了终于到了docker run这一步。但请收起你复制粘贴的冲动。一条看似简单的启动命令背后蕴含着从“能跑”到“能用”再到“能扛”的完整演进逻辑。我会带你一步步从最基础的命令开始逐层叠加关键参数最终形成一个适合 openEuler 生产环境的、健壮的启动方案。4.1 最简启动验证核心功能我们从最精简的命令开始目的是快速验证 Open WebUI 是否能与 Ollama 对话docker run -d \ -p 3000:8080 \ -v open-webui:/app/backend/data \ -e OLLAMA_BASE_URLhttp://127.0.0.1:11434 \ --name open-webui \ swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/open-webui/open-webui:main这条命令包含了四个核心要素-p 3000:8080将容器内部的8080端口Open WebUI 的默认服务端口映射到宿主机的3000端口。-v open-webui:/app/backend/data创建一个名为open-webui的 Docker 卷并将其挂载到容器内的/app/backend/data目录。这是数据持久化的生命线所有用户账号、聊天记录、自定义设置都存放在这个目录下。没有它每次容器重启你都要重新注册管理员账号。-e OLLAMA_BASE_URL...这是最关键的环境变量。它的值必须与你前面配置的OLLAMA_HOST完全一致。由于容器和 Ollama 都在宿主机上且 Ollama 监听了0.0.0.0:11434所以这里填http://127.0.0.1:11434是最稳妥的。--name open-webui为容器指定一个固定的名字方便后续用docker stop open-webui或docker logs open-webui进行管理。启动后用docker ps查看容器状态。如果STATUS显示Up X seconds说明容器正在运行。然后在浏览器中访问http://你的服务器IP:3000。如果能看到 Open WebUI 的欢迎页面并且在设置里能成功加载出 Ollama 中的模型列表恭喜你最基础的闭环已经打通。4.2 进阶加固应对 openEuler 的网络现实然而在 openEuler 这样的服务器环境中上述命令有一个致命的隐患端口冲突。3000端口虽然常用但并非绝对空闲。Zabbix、Prometheus、Jenkins 等监控和自动化工具都可能默认占用3000。一旦冲突docker run会报错Bind for 0.0.0.0:3000 failed: port is already allocated。此时你有两个选择一是换一个端口比如8081二是放弃-p映射改用--networkhost模式。--networkhost模式是 Docker 的一种高级网络模式它让容器直接共享宿主机的网络命名空间。这意味着容器内看到的localhost就是宿主机的localhost端口也直接暴露在宿主机上无需映射。这对于调试和简化网络配置非常有用。修改后的命令如下docker run -d \ --networkhost \ -v open-webui:/app/backend/data \ -e OLLAMA_BASE_URLhttp://127.0.0.1:11434 \ --name open-webui \ swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/open-webui/open-webui:main注意这里去掉了-p参数因为--networkhost下容器会直接监听8080端口。所以你访问的 URL 也变成了http://你的服务器IP:8080。这种方式的好处是网络路径最短延迟最低坏处是如果8080端口也被占用了你还是得换。因此我的建议是在首次部署时优先使用-p模式并主动选择一个冷门端口比如8001或9001。这样既能避开常见冲突又能保持网络隔离的安全性。4.3 生产就绪自动恢复与资源保障最后我们要为这个容器加上“保险丝”和“发动机”。-d参数让它后台运行但万一服务器意外重启或者容器因为内存溢出而崩溃它不会自动复活。--restart always参数就是为此而生的它告诉 Docker“无论发生什么只要守护进程还在就必须把这个容器拉起来。”此外在 openEuler 服务器上我们还需要考虑资源限制。Open WebUI 本身很轻量但如果你同时运行多个大模型比如 DeepSeek-R1 和 Qwen它们的内存消耗会非常惊人。为了防止 Open WebUI 容器吃光所有内存导致 Ollama 或其他关键服务被 OOM Killer 杀掉我们可以用--memory和--memory-swap参数进行硬性限制docker run -d \ -p 8001:8080 \ -v open-webui:/app/backend/data \ -e OLLAMA_BASE_URLhttp://127.0.0.1:11434 \ --restart always \ --memory1g \ --memory-swap2g \ --name open-webui \ swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/open-webui/open-webui:main这条命令就是我在自己 openEuler 24.03 LTS 服务器上稳定运行了三个月的“黄金配置”。它保证了服务的高可用性--restart always也保障了系统的整体稳定性内存限制。每一次docker run都不应该是一次性的尝试而应该是一次深思熟虑的、面向未来的基础设施建设。提示--memory-swap2g表示容器最多可以使用 1GB 的物理内存 1GB 的 swap 交换空间。在生产环境中建议将--memory-swap设置为--memory的两倍以提供一定的缓冲余地避免因瞬时内存峰值而导致容器被强制终止。5. 首次登录与模型配置从“空白画布”到“智能助手”的最后一公里容器启动成功浏览器打开http://你的服务器IP:8001你看到的将是一个简洁的欢迎页面上面写着“Welcome to Open WebUI”。此刻你离真正的 AI 助手只剩下最后一步完成初始设置。这一步看似简单却是整个部署流程中最容易因疏忽而导致后续功能失效的关键环节。5.1 创建管理员账号不只是“设个密码”点击“Create your account”按钮系统会引导你填写用户名、邮箱和密码。这里请务必注意两点用户名不要用admin。虽然这是最顺手的选项但 Open WebUI 的设计哲学是“最小权限原则”。admin是一个具有最高权限的内置账户它拥有管理所有用户、修改系统设置、甚至删除整个数据库的权力。在生产环境中我习惯创建一个以自己姓名拼音命名的管理员账号例如zhangsan然后将admin账号彻底禁用。这样即使某个应用或脚本误用了admin账号也不会造成灾难性后果。邮箱地址必须真实有效。Open WebUI 的用户系统支持邮箱验证和密码找回。如果你填了一个无效邮箱比如testtest.com那么未来当你忘记密码时将无法通过标准流程重置。在企业环境中我通常会要求所有管理员使用公司邮箱以便于统一的 IT 管理。填写完毕点击“Create Account”系统会跳转到登录页。用你刚创建的账号登录。此时你进入的将是一个全新的、空荡荡的聊天界面。别慌这是正常的。因为 Open WebUI 本身不包含任何模型它只是一个“壳”所有的模型都来自你前面部署好的 Ollama。5.2 模型选择与配置让“大脑”和“小脑”真正握手点击左下角的齿轮图标Settings进入设置页面。在左侧菜单中找到并点击 “Models”。这里你应该能看到一个空列表或者一个“Loading…”的提示。如果列表是空的或者一直转圈那说明OLLAMA_BASE_URL配置一定出了问题。请立即回到上一步检查 Docker 启动命令中的-e参数以及 Ollama 服务的OLLAMA_HOST配置。一旦模型列表成功加载出来你会看到类似这样的内容deepseek-r1:1.5bqwen2:7bllama3:8b这些都是你通过ollama run model-name命令下载到本地的模型。现在你需要做的是为当前用户选择一个默认模型。在模型列表右侧点击你想使用的模型例如deepseek-r1:1.5b然后点击弹出窗口中的 “Set as Default” 按钮。这一步操作会在你的用户配置文件位于/app/backend/data/users/user-id/config.json也就是你挂载的open-webui卷里中写入一条记录。它告诉 Open WebUI“下次用户发起新对话时不要问我选哪个模型直接用这个。”5.3 高级配置解锁 GPU 加速与多模型协同如果你的服务器配备了 NVIDIA GPU并且已经正确安装了nvidia-container-toolkit那么你就可以解锁 Open WebUI 的终极性能。在启动容器时只需在docker run命令中加入--gpus all参数docker run -d \ -p 8001:8080 \ -v open-webui:/app/backend/data \ -e OLLAMA_BASE_URLhttp://127.0.0.1:11434 \ --gpus all \ --restart always \ --name open-webui \ swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/open-webui/open-webui:main这个参数的作用是将宿主机上的所有 NVIDIA GPU 设备以设备文件如/dev/nvidia0的形式挂载到容器内部。Ollama 在接收到请求后会自动检测到 GPU 并启用 CUDA 加速从而将模型推理速度提升数倍。在 openEuler 上验证 GPU 是否被容器识别可以在容器内执行docker exec -it open-webui nvidia-smi如果能看到熟悉的 GPU 信息表格说明一切就绪。最后关于多模型协同。Open WebUI 的强大之处在于它允许你在一次对话中随时切换不同的模型。比如你可以用qwen2:7b来处理中文长文本摘要然后无缝切换到deepseek-r1:1.5b来进行代码生成。这种灵活性正是本地部署相对于云端 API 的最大优势。你不需要为每个任务都去申请不同的 API Key也不用担心调用费用和速率限制。你拥有的是一个完全属于你、可以随意支配的、多才多艺的 AI 团队。注意在 openEuler 上如果你发现nvidia-smi命令在容器内不可用那大概率是因为nvidia-container-toolkit没有正确安装或配置。请参考 NVIDIA 官方文档确保nvidia-docker2包已安装并且docker info的输出中能看到Runtimes: nvidia这一行。6. 故障排查的“黄金四步法”当页面打不开、模型不显示时怎么办部署完成并不意味着万事大吉。在 openEuler 这样的环境中各种意想不到的状况随时可能发生服务器重启后服务没起来、防火墙规则被重置、Ollama 的模型被误删、甚至只是浏览器缓存导致的界面异常。面对这些问题一个成熟的工程师不会手忙脚乱地百度而是有一套清晰、高效的排查思路。我把它总结为“黄金四步法”这套方法论我已经在数十次现场排障中验证过其有效性。6.1 第一步分层隔离定位故障域当你发现http://IP:8001打不开时不要立刻去查 Open WebUI 的日志。首先要做的是确定问题是出在“网络层”、“服务层”还是“应用层”。网络层检查在你的本地电脑上打开终端执行telnet 服务器IP 8001。如果连接成功显示Connected to ...说明网络是通的问题在服务或应用层如果连接失败Connection refused或timeout说明问题出在网络或服务层。服务层检查登录到 openEuler 服务器执行docker ps | grep open-webui。如果没有任何输出说明容器根本没在运行。再执行docker ps -a | grep open-webui看看容器是Exited还是Created。如果是Exited说明容器启动后立刻崩溃了原因就在日志里。应用层检查如果容器状态是Up但telnet依然失败那问题很可能出在容器内部的进程。此时执行docker exec -it open-webui ps aux看看uvicorn进程Open WebUI 的 Web 服务器是否在运行。如果没看到说明应用本身启动失败。这一步的价值在于它能帮你瞬间排除 70% 的无效排查方向。很多新手会一头扎进 Open WebUI 的日志里结果发现日志是空的因为容器压根就没启动成功。6.2 第二步日志溯源锁定根因一旦确定了故障域下一步就是精准的日志分析。对于 Docker 容器日志是唯一的真相来源。查看 Open WebUI 容器日志docker logs open-webui。这是最常用的命令。如果日志滚动太快可以用docker logs --tail 100 open-webui只看最后 100 行。重点关注以ERROR、CRITICAL或Traceback开头的行。查看 Ollama 服务日志sudo journalctl -u ollama -n 50 -f。-n 50表示显示最近 50 行-f表示实时跟踪。当你在 Open WebUI 页面上点击“加载模型”时如果 Ollama 日志里没有任何反应那基本可以断定OLLAMA_BASE_URL配置错误请求根本没发过去。查看 Docker 守护进程日志sudo journalctl -u docker -n 50。当docker run命令本身报错时比如no such file or directory这个日志会给出最底层的错误信息。我曾经遇到过一个案例Open WebUI 页面能打开但模型列表始终为空。docker logs里只有一句模糊的HTTPConnectionPool(host127.0.0.1, port11434): Max retries exceeded。起初我以为是网络问题但telnet 127.0.0.1 11434是通的。后来我执行了sudo journalctl -u ollama -n 50才发现 Ollama 日志里有一行关键的Permission denied: /root/.ollama/models。原来Ollama 的数据目录权限被错误地修改了导致它无法读取模型文件。这个根因只有在 Ollama 的日志里才能看到。6.3 第三步API 测试绕过前端直击核心如果日志里没有明确的错误或者你怀疑是前端 JavaScript 的问题那么最直接的办法就是绕过 Open WebUI 这个“中间商”直接用curl去调用 Ollama 的 API。在服务器上执行curl -X POST http://127.0.0.1:11434/api/chat \ -H Content-Type: application/json \ -d { model: deepseek-r1:1.5b, messages: [ {role: user, content: 你好} ] }如果这个命令能返回一个包含message.content字段的 JSON 响应说明 Ollama 本身工作完全正常问题 100% 出在 Open WebUI 的配置或前端代码上。反之如果这个命令也失败了那问题就出在 Ollama 或其模型上。6.4 第四步回滚与验证建立信心当你通过以上三步找到了问题的根因并进行了修复比如修改了OLLAMA_HOST或者chown了数据目录权限不要急于再次访问网页。请按顺序执行以下操作docker stop open-webuidocker rm open-webui用你修正后的、完整的docker run命令重新启动容器。立刻执行docker logs open-webui确认没有 ERROR。执行curl http://127.0.0.1:8001/api/healthOpen WebUI 的健康检查端点确认返回{status:ok}。最后才在浏览器中打开页面进行功能验证。这个“停止-删除-重建-验证”的流程是建立你对整个系统掌控感的基石。它确保了每一次修改都是干净、可追溯、可验证的。在 openEuler 这样的生产环境中这种严谨性远比“快一点”重要得多。提示在 openEuler 上systemctl服务的状态有时会与 Docker 容器的状态产生混淆。例如你systemctl restart docker之后之前运行的容器并不会自动重启。这是一个常见的认知误区。Docker 容器的生命周期是由docker run命令及其--restart策略控制的与systemd服务无关。
