Ansible 自动化部署 Open WebUI 集群,核心不是把容器跑起来,而是把“哪台主机跑 WebUI、哪台跑 Ollama、数据存在哪、服务由谁拉起、失败怎么回退”这些决策固化成可复用的配置。单机小规模部署用 Docker Compose 足够;多节点集群建议把 Ollama 与 Open WebUI 节点分离,用 systemd 托管容器生命周期,Ansible 负责节点分组、配置生成和版本回退。
适用场景与前置条件
这套自动化适用的边界:目标是 x86_64 或 arm64 Linux 主机,主机已安装 Docker Engine 与 Compose 插件(或 Docker Compose V2),控制端 Ansible 版本在 2.15 上下并安装 community.docker 集合,控制端到目标主机配置了免密 SSH。开始写 Playbook 前,先确认三件事:容器运行时是 Docker 还是 Podman;systemd 是否为 PID 1;目标端口 8080、11434 等是否已被占用。这些环境差异会直接影响任务写法,不能照搬一套模板。
Inventory 与节点分组
按角色分组,而不是按主机名硬编码。这样后续扩节点时只需要在 inventory 中加一行。以下是一个最小分组,其中 ollama_nodes 与 webui_nodes 合成为 webui_cluster:
[ollama_nodes]
ollama-01 ansible_host=10.0.0.11
ollama-02 ansible_host=10.0.0.12
[webui_nodes]
webui-01 ansible_host=10.0.0.21
[webui_cluster:children]
ollama_nodes
webui_nodes
多节点时,Ollama 后端地址不要写死 localhost,而是用组变量传递。Open WebUI 容器通过 OLLAMA_BASE_URL 环境变量指向后端节点,这个变量建议写入 host_vars 或 group_vars,方便统一调整。Ollama 节点本身不应暴露公网端口,只让 WebUI 节点通过内网访问。
容器、数据卷与 systemd 的边界
Open WebUI 的镜像数据目录通常声明为 /app/backend/data,部署时需要以具名卷或宿主机目录挂载,否则容器重建后配置与登录信息会丢失。具体目录以所选镜像的镜像配置为准,Playbook 中应写成变量,而不是分散在各任务里。
建议把“应用栈定义”和“主机服务定义”分开:用 Compose 文件描述容器端口和卷映射,用 systemd unit 描述容器拉起与开机自启。Ansible 的任务只需要生成这两个文件,再执行一次通知处理器即可。
- name: 写入 Compose 配置
copy:
dest: /opt/open-webui/compose.yaml
content: |
services:
webui:
image: ghcr.io/open-webui/open-webui:main
ports: ['8080:8080']
volumes:
- webui_data:/app/backend/data
environment:
OLLAMA_BASE_URL: http://ollama-01:11434
notify: reload webui unit
- name: 写入 systemd 服务
copy:
dest: /etc/systemd/system/webui-compose.service
content: |
[Unit]
After=docker.service network-online.target
Requires=docker.service
[Service]
WorkingDirectory=/opt/open-webui
ExecStart=/usr/bin/docker compose up `--remove-orphans`
ExecStop=/usr/bin/docker compose down
Restart=on-failure
RestartSec=15s
[Install]
WantedBy=multi-user.target
notify: reload webui unit
handlers 中执行 systemctl daemon-reload 与 systemctl restart webui-compose.service。注意这里使用的是 docker compose 而不是 docker-compose,目标主机需要安装 Compose 插件。如果目标是 CentOS 7 这类旧系统,这套写法需要调整。
如果部署包含 Nginx 或 Caddy 节点,反向代理配置也应由 Ansible 生成,代理目标统一指向 WebUI 节点 8080 端口。这样容器网络变化时,只需要改配置变量,不需要登到代理服务器手动修改。
验证清单
部署完成后,按顺序执行以下检查。先看服务,再看容器,最后看应用健康端点:
systemctl is-active webui-compose.service返回 active,且systemctl is-enabled webui-compose.service显示 enabled。docker compose -f /opt/open-webui/compose.yaml ps显示容器状态 running,端口映射符合预期。curl -s http://127.0.0.1:8080/api/health返回包含健壮状态标记的 JSON。若返回空或连接拒绝,先查容器日志docker logs <容器名>。- 再次执行
ansible-playbook site.yml,确认所有任务处于 ok 状态而不是 changed,以满足幂等性要求。
失败时回退
集群部署失败通常集中在镜像拉取失败、端口冲突和 systemd unit 语法错误三处。执行前用 ansible-playbook `--check` `--diff` 预演,减少直接改线上环境的概率。
回退策略要提前写进版本管理:Playbook 目录本身用 git 管理,镜像 tag 固定到具体版本;部署前备份 /opt/open-webui 目录,并保留上一版 compose 文件为 compose.yaml.bak。如果新配置导致容器无法启动,先停掉当前服务,再用备份文件恢复:
systemctl stop webui-compose.service
cp /opt/open-webui/compose.yaml.bak /opt/open-webui/compose.yaml
systemctl start webui-compose.service
数据卷不要随手删除,容器可以重建,数据卷内的数据库文件才是需要长期保留的部分。任何“重装解决一切”的操作都应放在数据备份之后。