丹青幻境部署指南：Docker Compose一键部署Z-Image+WebUI+API服务

聚合收藏

130人浏览 · 2026-03-31 05:24:55

聚合收藏 · 2026-03-31 05:24:55 发布

丹青幻境部署指南：Docker Compose一键部署Z-Image+WebUI+API服务

想体验一个充满东方美学意境的AI绘画工具吗？丹青幻境将带你告别冰冷的科技界面，进入一个以宣纸、墨色和宋体字构建的数字艺术空间。它基于强大的Z-Image模型和Cosplay LoRA技术，将4090显卡的澎湃算力，巧妙地隐藏在古典雅致的交互背后，为创作者打造一个专注灵感的“数字画室”。

今天，我将手把手教你如何通过Docker Compose，一键部署完整的丹青幻境服务，包括其精美的Web用户界面和可供调用的API接口。整个过程简单清晰，无论你是开发者还是艺术爱好者，都能轻松上手。

1. 部署前准备：理清思路与环境检查

在开始挥毫泼墨之前，我们需要确保“文房四宝”齐全。丹青幻境的部署主要依赖于Docker环境，它将模型、代码和依赖全部打包，省去了繁琐的环境配置。

1.1 核心概念快速理解

为了让你更顺畅地理解后续步骤，我们先快速过几个关键名词：

丹青幻境 (Z-Image Atelier)：本文要部署的核心应用。它是一个拥有古风UI的AI绘画Web工具，你可以理解为是一个特别设计的网站，打开就能用。
Z-Image：背后的“绘画大师”，一个强大的文生图基础模型，负责理解你的文字描述并生成图像。
Cosplay LoRA：给“绘画大师”的“风格秘籍”。加载它之后，模型就特别擅长生成具有Cosplay（角色扮演）风格的人物图像。
Docker：一个“集装箱”技术。我们把“丹青幻境”这个应用，连同它需要的所有环境（比如Python、模型文件、库），一起打包进一个标准的集装箱里。这样在任何支持Docker的电脑上，都能一键运行，不会出现“在我电脑上好好的，到你那就报错”的情况。
Docker Compose：一个“集装箱船队调度员”。我们的部署其实包含两个服务：Web界面和API接口。Docker Compose用一个配置文件就能同时定义、启动和管理这多个“集装箱”，非常方便。

1.2 环境与资源确认

开始前，请确认你的“画案”（服务器或本地电脑）满足以下条件：

操作系统：推荐Linux（如Ubuntu 20.04/22.04）或Windows/macOS（需安装Docker Desktop）。本文以Linux为例。
Docker与Docker Compose：确保已安装。在终端输入以下命令检查：
```
docker --version
docker-compose --version
```
如果未安装，请参考Docker官方文档进行安装。
硬件资源（非常重要）：
- GPU：推荐拥有NVIDIA GPU，且显存不小于8GB。丹青幻境针对24GB显存（如RTX 4090）深度优化，但8GB或以上显存也可运行（可能需要调整参数）。
- 驱动：确保已安装正确的NVIDIA显卡驱动。
- NVIDIA Container Toolkit：这是让Docker容器能使用GPU的关键。安装命令通常如下（Ubuntu）：
```
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker
```
磁盘空间：准备至少15-20GB的可用空间，用于存放模型文件。

2. 一键部署：使用Docker Compose启动服务

一切准备就绪，现在开始最核心的部署步骤。我们将通过一个编写好的 docker-compose.yml 配置文件来启动所有服务。

2.1 获取部署配置文件

首先，创建一个专门的工作目录，并进入该目录：

mkdir -p ~/z-image-atelier && cd ~/z-image-atelier

接下来，创建 docker-compose.yml 文件。你可以使用 vim 或 nano 编辑器，将以下内容复制进去：

version: '3.8'

services:
  webui:
    image: your_custom_zimage_webui_image:latest # 请替换为实际构建的WebUI镜像名
    container_name: zimage-atelier-webui
    restart: unless-stopped
    ports:
      - "8501:8501" # Streamlit 默认端口
    volumes:
      - ./output:/app/output # 挂载输出目录，生成的图片保存在本地
      - ./models:/root/ai-models # 挂载模型目录，方便管理模型文件
    environment:
      - BASE_MODEL_PATH=/root/ai-models/Z-Image
      - LORA_DIR_PATH=/root/ai-models/yz-bijini-cosplay
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    networks:
      - zimage-network

  api:
    image: your_custom_zimage_api_image:latest # 请替换为实际构建的API镜像名
    container_name: zimage-atelier-api
    restart: unless-stopped
    ports:
      - "7860:7860" # 常用的API服务端口，如Gradio
    volumes:
      - ./models:/root/ai-models # 与WebUI共享模型目录
    environment:
      - BASE_MODEL_PATH=/root/ai-models/Z-Image
      - LORA_DIR_PATH=/root/ai-models/yz-bijini-cosplay
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    networks:
      - zimage-network

networks:
  zimage-network:
    driver: bridge

volumes:
  models:
  output:

重要说明：这个配置文件定义了两个服务（webui和api），并假设你已经将丹青幻境的代码分别打包成了两个Docker镜像（your_custom_zimage_webui_image:latest 和 your_custom_zimage_api_image:latest）。在下一步，我们会介绍如何获取或构建这些镜像。

2.2 获取与准备模型文件

丹青幻境运行需要两个核心模型文件：

Z-Image 基础模型：主绘画模型。
yz-bijini-cosplay LoRA模型： Cosplay风格适配器。

通常，你需要从模型发布平台（如Hugging Face）下载这些文件。假设你已经下载好，请按照配置文件中定义的路径，在本地创建目录并放置模型：

# 在工作目录下创建模型目录结构
mkdir -p ./models/Z-Image
mkdir -p ./models/yz-bijini-cosplay

# 将下载的 Z-Image 模型文件（通常是一个包含多个文件的文件夹）放入 ./models/Z-Image/
# 将下载的 yz-bijini-cosplay.safetensors 文件放入 ./models/yz-bijini-cosplay/

路径是关键：务必确保模型文件放对了位置，因为Docker容器内的路径（如/root/ai-models/Z-Image）正是通过volumes映射到你本地./models/Z-Image目录的。

2.3 构建或获取Docker镜像

你有两种方式来准备镜像：

方式一：使用预构建的镜像（如果作者提供） 如果项目作者在Docker Hub等平台发布了镜像，你只需修改docker-compose.yml中的image字段为正确的镜像名即可，例如：

image: registry.cn-hangzhou.aliyuncs.com/namespace/zimage-atelier-webui:latest

方式二：自行构建镜像（如果需要） 如果作者提供了Dockerfile，你需要先构建镜像。假设项目代码已克隆到当前目录（./app目录下是WebUI代码，./api目录下是API代码）：

# 构建WebUI镜像
docker build -t your_custom_zimage_webui_image:latest -f ./app/Dockerfile ./app

# 构建API镜像
docker build -t your_custom_zimage_api_image:latest -f ./api/Dockerfile ./api

构建完成后，docker-compose.yml中配置的镜像名就能正确识别了。

2.4 启动丹青幻境

完成以上所有准备后，只需一条命令，即可启动整个服务：

cd ~/z-image-atelier # 确保在docker-compose.yml所在目录
docker-compose up -d

-d参数表示在后台运行。执行后，你会看到Docker开始拉取或使用本地镜像，并启动两个容器。

使用以下命令查看服务状态：

docker-compose ps

如果状态显示为 Up，说明服务已成功启动。

3. 访问与使用：进入你的数字画室

服务启动后，如何访问呢？

访问WebUI（绘画界面）：
- 打开你的浏览器。
- 地址栏输入：http://你的服务器IP地址:8501 （如果在本地电脑，就是 http://localhost:8501）。
- 你将看到丹青幻境那充满宣纸质感的中文界面。
访问API服务接口：
- 如果你需要通过编程方式调用生图功能，可以访问：http://你的服务器IP地址:7860。
- 通常API会提供类似/generate的端点，接收提示词等参数，返回图像。具体API文档需参考项目说明。
开始你的第一次创作：
- 在WebUI中，左侧选择“历练卷轴”（即LoRA模型）。
- 在“画意描述”中输入你的灵感，例如：“一位侠客，立于竹林之中，细雨蒙蒙”。
- 在“避讳”中写下不希望出现的元素。
- 调整画布尺寸、生成步数等参数。
- 点击“🏮 挥毫泼墨”，静候佳作生成。
- 生成的图片会自动保存在你本地./output目录下。

4. 常见问题与维护

首次运行可能会遇到一些小问题，这里提供一些排查思路。

4.1 部署常见问题排查

容器启动失败，提示端口被占用：检查8501或7860端口是否已被其他程序使用。可以修改docker-compose.yml中的ports映射，例如将“8501:8501”改为“8502:8501”，然后通过新端口访问。
容器日志报错“No such file or directory”：这通常是模型路径错误。请再次确认：
1. docker-compose.yml中volumes映射的本地路径（如./models）是否存在。
2. 该路径下是否有正确的Z-Image和yz-bijini-cosplay文件夹及文件。可以通过命令进入容器内部检查：
```
docker exec -it zimage-atelier-webui bash
ls -la /root/ai-models/
```
生成图片时卡住或报CUDA out of memory：这是显存不足的典型表现。可以尝试以下方法：
1. 降低参数：在WebUI中减少生成图片的尺寸（如从1024x1024降到512x512）、减少生成步数。
2. 启用CPU Offload：如果项目代码支持，可以设置环境变量启用更多计算卸载到CPU，但这会降低速度。
3. 检查GPU是否被容器识别：在容器内执行nvidia-smi，看是否能输出GPU信息。

4.2 日常维护命令

查看实时日志：docker-compose logs -f webui （查看WebUI服务日志）
停止服务：docker-compose down
停止并删除容器、网络：docker-compose down -v （注意：-v也会删除volumes，慎用）
重启服务：docker-compose restart

更新服务：如果镜像有更新，需要重新拉取或构建镜像，然后运行：

docker-compose pull # 如果使用远程镜像
docker-compose up -d --force-recreate # 强制重新创建容器

5. 总结

通过以上步骤，我们已经成功地将丹青幻境这个富有诗意的AI绘画工具部署了起来。回顾一下关键点：

理解架构：丹青幻境通过Docker Compose管理WebUI和API两个核心服务，共享模型资源。
准备环境：确保拥有NVIDIA GPU、足够的显存和磁盘空间，并正确安装Docker及相关GPU支持。
配置部署：核心是编写正确的docker-compose.yml文件，并确保模型文件放置在正确的挂载目录下。
一键启动：使用docker-compose up -d命令即可拉起所有服务。
访问使用：通过浏览器访问指定端口即可开始创作，生成的图片保存在本地。

这种Docker化的部署方式极大简化了复杂AI应用的安装流程，避免了环境冲突，也便于后续的迁移和升级。现在，你的“数字画室”已经准备就绪，可以开始沉浸在那片由代码与算法构建的墨色山水之中，让灵感自由流淌了。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责