当前位置：首页 > news >正文

快速上手：使用Docker Compose一键部署LiuJuan模型及WebUI

news 2026/8/27 19:57:04

快速上手：使用Docker Compose一键部署LiuJuan模型及WebUI

你是不是也对那些能生成图片、能对话的AI模型感到好奇，想自己动手试试，但又被复杂的安装步骤和命令行劝退？别担心，今天我们就来聊聊一个超级简单的方法——用Docker Compose，像搭积木一样，把LiuJuan模型和它的网页操作界面（WebUI）一键部署起来。

这个方法最大的好处就是省心。你不用去操心Python版本对不对、依赖包缺不缺、环境变量怎么配。你只需要准备一个写好的配置文件，然后运行一条命令，剩下的就交给Docker去处理。整个过程就像安装一个桌面软件一样直观。接下来，我会带你一步步走完这个流程，即使你之前没怎么用过Docker，也能轻松搞定。

1. 准备工作：确保你的电脑已经就绪

在开始搭建之前，我们需要确保你的电脑上已经安装好了必要的工具。这就像做饭前要先备好锅和灶一样。

1.1 安装Docker和Docker Compose

Docker是我们这次部署的核心工具，而Docker Compose则是用来编排多个容器的“指挥家”。如果你还没安装，可以按照以下步骤进行：

访问Docker官网：打开你的浏览器，搜索“Docker Desktop”并进入官方网站。
下载对应版本：根据你的操作系统（Windows、macOS或Linux），下载相应的Docker Desktop安装包。
完成安装：运行下载的安装程序，并按照提示完成安装。安装过程中可能需要你重启电脑。
验证安装：安装完成后，打开终端（在Windows上是命令提示符或PowerShell，在macOS或Linux上是Terminal），输入以下命令来检查是否安装成功：
```
docker --version docker-compose --version
```
如果这两条命令都能正确输出版本号，比如Docker version 20.10.17和docker-compose version 1.29.2，那就说明一切准备就绪了。

1.2 获取模型文件（如果需要）

LiuJuan模型通常需要下载对应的模型权重文件。有些Docker镜像会内置一些基础模型，但如果你需要使用特定的、更大的模型，可能需要提前下载。

情况一（推荐给新手）：如果你只是想快速体验，可以直接使用Docker镜像里自带的模型。这样你不需要额外下载任何文件，部署过程最简单。
情况二（需要特定模型）：如果你已经从官方渠道获得了模型的权重文件（通常是.safetensors或.bin等格式的文件），请把它们放在你电脑上一个容易找到的文件夹里，比如D:/ai_models/liujuan或/home/yourname/models/liujuan。我们稍后会把这个文件夹“映射”到Docker容器里。

好了，工具和材料都齐了，接下来我们开始编写最重要的“搭建说明书”。

2. 编写一键部署的“说明书”：docker-compose.yml

docker-compose.yml文件就是我们这次部署的“总说明书”。它是一个用YAML格式写的文本文件，告诉Docker Compose需要启动哪些服务、用什么镜像、怎么配置。我们来创建一个。

在你电脑上找一个合适的位置，新建一个文件夹，名字可以叫liujuan-deploy。
在这个文件夹里，新建一个文本文件，命名为docker-compose.yml。
用文本编辑器（比如VS Code、Notepad++，甚至系统自带的记事本）打开这个文件，把下面的内容复制进去。

version: '3.8' services: liujuan-model: image: registry.cn-hangzhou.aliyuncs.com/your_namespace/liujuan-model:latest container_name: liujuan-model-service restart: unless-stopped volumes: - ./model_weights:/app/models - ./config:/app/config environment: - MODEL_NAME=default - DEVICE=cuda # 如果你有NVIDIA显卡并安装了驱动，用这个。否则改为 cpu ports: - "8000:8000" networks: - liujuan-net deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] # 如果没有GPU，请注释掉上面的 deploy 部分 liujuan-webui: image: registry.cn-hangzhou.aliyuncs.com/your_namespace/liujuan-webui:latest container_name: liujuan-webui-interface restart: unless-stopped depends_on: - liujuan-model volumes: - ./output:/app/output environment: - MODEL_API_URL=http://liujuan-model-service:8000 ports: - "7860:7860" networks: - liujan-net

别被这一大段代码吓到，我们来拆解一下每个部分都是干什么的，你可以根据自己的情况调整。

2.1 核心配置项详解

version：指定我们使用的Docker Compose文件格式版本，用3.8是一个比较新且稳定的选择。
services：这是文件的主体，定义了两个我们要运行的服务。
- liujuan-model：这是模型推理服务。它负责加载模型、接收请求并生成结果。
  - image：指定使用的Docker镜像地址。你需要将其中的your_namespace替换成实际的镜像仓库路径。这个信息通常由模型提供方给出。
  - volumes：卷映射，把主机（你的电脑）的目录挂载到容器内部。
    - ./model_weights:/app/models：将当前目录下的model_weights文件夹映射到容器的/app/models。这样，你可以把下载好的模型文件放在./model_weights里，容器就能直接使用了。
    - ./config:/app/config：映射配置文件夹，方便你修改一些模型参数。
  - environment：设置容器内的环境变量。
    - MODEL_NAME：指定要加载的模型名称，对应你放在model_weights里的文件名。
    - DEVICE：指定运行设备。如果你有NVIDIA显卡并且正确安装了Docker GPU支持，填cuda可以加速。如果没有，一定要改成cpu，否则服务会启动失败。
  - ports：端口映射，8000:8000表示将容器内部的8000端口映射到你电脑的8000端口。这样你就能通过http://你的电脑IP:8000访问模型API了。
  - deploy.resources：这部分是申请GPU资源。只有在你使用DEVICE=cuda并且Docker支持GPU时才需要。如果使用CPU，请将这一整块（从deploy:开始到capabilities: [gpu]）用#注释掉。
- liujuan-webui：这是基于Gradio构建的网页用户界面。它提供了一个友好的网页，让你可以通过点击和输入来与模型交互，而不用直接调用API。
  - depends_on：表示这个服务依赖于liujuan-model服务，会等模型服务启动后再启动自己。
  - volumes：./output:/app/output将输出目录映射出来，这样模型生成的结果（如图片）会保存在你电脑的./output文件夹里，方便查看。
  - environment：MODEL_API_URL告诉WebUI，模型API服务在哪里。这里用的是Docker内部网络的服务名liujuan-model-service和端口8000。
  - ports：7860:7860将Gradio默认的7860端口映射出来。部署成功后，你就可以在浏览器里通过http://localhost:7860访问这个Web界面了。
networks：为这两个服务创建一个共同的Docker网络liujuan-net，让它们可以在内部相互通信。

现在，这份“说明书”就写好了。记得根据你的实际情况修改镜像地址、设备类型（CPU/CUDA）以及是否需要GPU配置。

3. 一键启动与验证

配置文件准备好之后，真正的部署只需要一条命令。

打开终端（命令行），使用cd命令进入到刚才创建的那个包含docker-compose.yml文件的文件夹。
```
cd /path/to/your/liujuan-deploy
```
运行以下命令来启动所有服务：
```
docker-compose up -d
```
-d参数表示在“后台”运行。执行后，Docker会开始拉取镜像（如果本地没有）、创建容器、并启动它们。你会看到一系列下载和启动的日志。
查看运行状态：启动完成后，可以运行下面的命令来检查两个服务是否都在正常运行。
```
docker-compose ps
```
如果看到两个服务的状态（State）都是Up，那就恭喜你，部署成功了！
访问WebUI：打开你的浏览器，在地址栏输入http://localhost:7860。稍等片刻，你应该就能看到LiuJuan模型的网页操作界面了。
查看日志（如果遇到问题）：如果页面打不开或者服务状态不对，可以查看具体容器的日志来排查问题。
```
# 查看模型服务的日志 docker-compose logs liujuan-model # 查看WebUI的日志 docker-compose logs liujuan-webui
```
常见的启动问题可能是镜像地址不对、端口被占用、或者GPU驱动没装好（却配置了cuda）。根据日志提示调整你的docker-compose.yml文件即可。

4. 使用与管理你的AI服务

服务跑起来之后，怎么用、怎么管呢？这里有几个日常操作。

4.1 开始使用模型

访问http://localhost:7860后，你会看到一个交互界面。根据LiuJuan模型的具体功能（比如是文生图还是对话），界面会有所不同。通常会有输入框让你输入文字描述（Prompt），然后点击“生成”或“提交”按钮。生成的结果（图片或文本）会显示在页面上，并且根据我们的配置，图片文件也会保存到你本地文件夹的./output目录里。

4.2 常用的管理命令

学会这几个命令，你就能轻松管理这个部署好的环境了：

停止服务：当你暂时不用时，可以停止容器，但不会删除它们。
```
docker-compose stop
```
启动服务：重新启动之前停止的服务。
```
docker-compose start
```
重启服务：如果修改了配置或者服务运行异常，可以重启。
```
docker-compose restart
```
停止并移除所有资源：这会停止容器，并删除由docker-compose up创建的所有容器、网络。但你的./model_weights和./output等本地卷里的数据不会被删除。
```
docker-compose down
```
查看实时日志：像看一个滚动的控制台输出。
```
docker-compose logs -f
```

4.3 可能遇到的问题与小技巧

端口冲突：如果7860或8000端口被其他程序占用了，你可以在docker-compose.yml文件里修改左边的主机端口，比如改成“8899:7860”，那么访问地址就变成了http://localhost:8899。
模型加载慢：第一次启动时，如果镜像里没有内置模型，或者你需要加载一个很大的模型文件，初始化时间可能会比较长。多给点耐心，查看模型服务的日志直到看到加载完成的提示。
想换模型：把你新下载的模型文件放进./model_weights目录，然后修改docker-compose.yml中MODEL_NAME环境变量为对应的模型文件名（不含路径），最后执行docker-compose restart liujuan-model重启模型服务即可。
资源监控：可以使用docker stats命令来查看各个容器对CPU、内存的占用情况，帮助你判断资源是否够用。

5. 写在最后

用Docker Compose来部署像LiuJuan这样的AI模型，确实大大简化了流程。它把复杂的依赖和环境打包在一起，让你能专注于使用模型本身，而不是折腾环境。这次我们通过一个配置文件，就把模型服务和网页界面都跑起来了，整个过程清晰可控。

你可以基于这个docker-compose.yml文件进行各种扩展，比如增加一个数据库服务来保存生成历史，或者挂载更多的配置目录。这种“基础设施即代码”的方式，也方便你分享和复现这个部署环境。希望这个教程能帮你顺利踏出第一步，在实际操作中如果遇到具体问题，多看看日志，大部分都能找到线索。接下来，就尽情去探索你的AI模型能创造出什么吧。