在Ansible中自动化部署Open WebUI集群:从容器到系统服务的配置管理

文章导读
Ansible 自动化部署 Open WebUI 集群,核心不是把容器跑起来,而是把“哪台主机跑 WebUI、哪台跑 Ollama、数据存在哪、服务由谁拉起、失败怎么回退”这些决策固化成可复用的配置。单机小规模部署用 Docker Compose 足够;多节点集群建议把 Ollama 与 Open WebUI 节点分离,用 systemd 托管容器生命周期,Ansible 负责节点分组、配置生成和
📋 目录
  1. 壹 适用场景与前置条件
  2. 贰 Inventory 与节点分组
  3. 叁 容器、数据卷与 systemd 的边界
  4. 肆 验证清单
  5. 伍 失败时回退
A A

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 这类旧系统,这套写法需要调整。

在Ansible中自动化部署Open WebUI集群:从容器到系统服务的配置管理

如果部署包含 Nginx 或 Caddy 节点,反向代理配置也应由 Ansible 生成,代理目标统一指向 WebUI 节点 8080 端口。这样容器网络变化时,只需要改配置变量,不需要登到代理服务器手动修改。

验证清单

部署完成后,按顺序执行以下检查。先看服务,再看容器,最后看应用健康端点:

  1. systemctl is-active webui-compose.service 返回 active,且 systemctl is-enabled webui-compose.service 显示 enabled。
  2. docker compose -f /opt/open-webui/compose.yaml ps 显示容器状态 running,端口映射符合预期。
  3. curl -s http://127.0.0.1:8080/api/health 返回包含健壮状态标记的 JSON。若返回空或连接拒绝,先查容器日志 docker logs <容器名>。
  4. 再次执行 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

数据卷不要随手删除,容器可以重建,数据卷内的数据库文件才是需要长期保留的部分。任何“重装解决一切”的操作都应放在数据备份之后。