丹青识画快速部署教程：使用docker-compose一键启停全栈服务-开发者社区

丹青识画快速部署教程：使用docker-compose一键启停全栈服务

你是否曾想过，让AI为你的照片或画作，配上充满东方意境的书法题跋？今天要介绍的「丹青识画」智能影像雅鉴系统，就能实现这个想法。它不仅能看懂图片内容，还能用动态行草书法的形式，生成富有诗意的中文描述。

对于开发者或技术爱好者来说，最关心的问题往往是：这么酷的系统，部署起来会不会很复杂？需要配置多少环境？别担心，这篇教程就是为你准备的。我们将使用docker-compose这个工具，带你一步步完成从零到一的完整部署。整个过程就像搭积木一样简单，你只需要几条命令，就能在自己的服务器或电脑上，启动这套融合了AI与美学的全栈服务。

1. 准备工作与环境检查

在开始搭建之前，我们先花几分钟，确保你的“工具箱”是齐全的。这能避免后续步骤中遇到各种奇怪的问题。

1.1 系统与工具要求

首先，你需要一台运行Linux的服务器或你自己的个人电脑（Windows用户可以通过WSL2获得类似的Linux环境）。以下是具体的软件版本要求：

操作系统: Ubuntu 20.04 LTS 或更高版本、CentOS 7+ 或其他主流Linux发行版。
Docker: 版本 20.10.0 或更高。Docker是容器技术的核心，我们的所有服务都将运行在容器里。
Docker Compose: 版本 1.29.0 或更高。它是用来定义和运行多容器Docker应用的工具，通过一个配置文件就能管理所有服务。

简单来说，Docker负责把每个服务（比如AI模型、Web界面）打包成独立的“集装箱”，而Docker Compose就是那个指挥所有集装箱协同工作的“调度员”。

1.2 如何检查与安装

如果你不确定自己的环境是否满足要求，可以打开终端，执行以下命令来检查：

# 检查Docker版本 docker --version # 检查Docker Compose版本 docker-compose --version

如果命令返回了版本号并且高于我们的要求，那么恭喜你，可以直接跳到下一步。如果提示“命令未找到”或版本过低，则需要先进行安装。

安装Docker与Docker Compose（以Ubuntu为例）:

# 更新软件包索引 sudo apt-get update # 安装必要的依赖包 sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common # 添加Docker官方GPG密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - # 添加Docker软件源 sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" # 再次更新并安装Docker CE sudo apt-get update sudo apt-get install -y docker-ce # 安装Docker Compose sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose # 验证安装 docker --version docker-compose --version

安装完成后，建议将当前用户加入docker用户组，这样以后运行Docker命令就不需要每次都加sudo了：

sudo usermod -aG docker $USER

重要提示：执行完用户组修改后，你需要完全退出当前终端会话并重新登录，这个改动才会生效。

2. 获取与配置部署文件

环境准备好后，我们就要把“丹青识画”的蓝图和建筑材料拿到手。这里最关键的文件就是docker-compose.yml。

2.1 获取部署配置文件

你需要将下面的docker-compose.yml配置文件内容，保存到你服务器上的一个目录中，例如/opt/danqing。你可以使用vim或nano编辑器来创建这个文件。

首先，创建一个项目目录并进入：

mkdir -p /opt/danqing cd /opt/danqing

然后，创建并编辑docker-compose.yml文件：

vim docker-compose.yml

将以下配置内容完整地复制粘贴进去：

version: '3.8' services: # 前端Web界面服务 web-ui: image: registry.cn-hangzhou.aliyuncs.com/ai-art-lab/danqing-web:latest container_name: danqing-web restart: unless-stopped ports: - "3000:80" # 将宿主机的3000端口映射到容器的80端口 environment: - API_BASE_URL=http://backend:8000 # 后端API地址，通过服务名`backend`内部通信 depends_on: - backend networks: - danqing-network # 后端AI处理服务 backend: image: registry.cn-hangzhou.aliyuncs.com/ai-art-lab/danqing-backend:latest container_name: danqing-backend restart: unless-stopped expose: - "8000" # 内部暴露8000端口，供前端服务调用 environment: - MODEL_PATH=/app/models/ofa-large # AI模型路径 - DEVICE=cpu # 使用CPU进行推理。如果你有NVIDIA GPU并安装了驱动，可改为 `cuda:0` volumes: - model-cache:/app/models # 将模型数据持久化到卷，避免重复下载 networks: - danqing-network # 定义Docker卷，用于持久化存储AI模型文件 volumes: model-cache: # 定义内部网络，让前端和后端服务可以相互通信 networks: danqing-network: driver: bridge

保存并退出编辑器（在vim中按Esc键，然后输入:wq回车）。

2.2 配置文件详解（小白也能懂）

这个文件看起来有点复杂，但其实结构很清晰。我们来拆解一下，你就能明白每个部分是干什么的：

version: '3.8'：指定了我们使用的Docker Compose文件格式版本。
services（服务）：这是核心部分，定义了两个“集装箱”。
- web-ui（前端服务）：
  - image: 指定从哪个仓库拉取现成的“前端界面”镜像。
  - ports: “3000:80”：这是关键！它把容器内部的80端口（Web服务默认端口）映射到你服务器本地的3000端口。这意味着你稍后可以通过http://你的服务器IP:3000来访问系统界面。
  - environment: 设置了一个环境变量，告诉前端去哪里找后端API。这里用的是服务名backend，Docker Compose会自动处理内部网络DNS解析。
  - depends_on: 表示web-ui服务启动前，会先等待backend服务启动。
- backend（后端服务）：
  - expose: “8000”：只对Docker内部网络暴露8000端口，外部无法直接访问，更安全。
  - environment:DEVICE=cpu表示使用CPU运行AI模型。如果你的服务器有NVIDIA显卡并正确安装了Docker GPU支持，可以尝试改为cuda:0来加速，但这需要额外配置。
  - volumes: 把容器里的模型目录挂载到一个名叫model-cache的持久化存储空间。这样即使容器删除，下载好的大模型文件也不会丢失，下次启动时无需重新下载。
volumes（数据卷）：声明了一个名为model-cache的持久化存储空间。
networks（网络）：创建了一个名为danqing-network的虚拟内部网络，让web-ui和backend两个容器可以安全、方便地互相通话。

3. 一键启动与停止服务

配置文件就绪，最激动人心的时刻来了——启动服务。整个过程是全自动的。

3.1 启动所有服务

确保你的终端当前位于存放docker-compose.yml文件的目录（/opt/danqing），然后执行一条命令：

docker-compose up -d

命令解释：

docker-compose up：根据docker-compose.yml文件创建并启动所有服务。
-d：代表“detached”，让服务在后台运行，这样你的终端就不会被日志占满。

执行这条命令后，Docker会依次做以下几件事：

自动从配置的镜像仓库拉取danqing-web和danqing-backend这两个镜像。
创建danqing-network网络和model-cache数据卷。
按依赖顺序启动backend和web-ui两个容器。

第一次启动会慢一些，因为需要下载镜像，特别是后端镜像包含了较大的AI模型文件（约几个GB）。请耐心等待，下载进度会在终端显示。

3.2 检查服务状态

启动命令执行后，如何知道服务是否正常运行了呢？可以使用以下命令查看：

# 查看所有由当前docker-compose管理的容器状态 docker-compose ps # 或者查看更详细的Docker容器状态 docker ps

如果看到danqing-backend和danqing-web两个容器的状态（STATUS）都是Up，就说明启动成功了。

你还可以查看实时日志，特别是启动初期，可以观察后端模型加载是否完成：

# 查看后端服务的日志 docker-compose logs -f backend # 查看前端服务的日志 docker-compose logs -f web-ui

当在后端日志中看到模型加载完成、服务开始监听端口的相关提示时，就表示系统已经完全就绪。

3.3 访问系统

服务启动成功后，打开你的浏览器，在地址栏输入：

http://你的服务器IP地址:3000

例如，如果你在本地电脑上部署，就访问http://localhost:3000。

如果一切顺利，你将看到「丹青识画」极具水墨韵味的主界面。现在，你就可以尝试上传一张图片，体验AI生成书法题跋的整个过程了！

3.4 停止与重启服务

当你不需要使用系统时，或者想更新配置，可以方便地管理服务。

# 停止所有服务（容器会停止运行，但不会被删除） docker-compose stop # 重启所有服务 docker-compose restart # 停止并删除所有相关的容器、网络（数据卷model-cache会被保留） docker-compose down # 如果想彻底清理，包括删除持久化的模型数据卷（谨慎使用，下次启动需重新下载模型） docker-compose down -v

日常维护中，最常用的就是docker-compose stop和docker-compose restart。

4. 常见问题与使用技巧

即使是傻瓜式部署，也可能遇到一些小波折。这里汇总了几个常见情况和解决方法。

4.1 端口冲突怎么办？

如果你服务器上的3000端口已经被其他程序（比如另一个Web服务）占用了，访问时就会失败。

解决方法：修改docker-compose.yml文件中web-ui服务的端口映射。比如，你想改用8080端口访问，就改成：

ports: - “8080:80”

然后运行docker-compose restart重启服务，并通过http://IP:8080访问。

4.2 模型下载太慢或失败？

由于网络原因，从仓库拉取包含大模型的镜像可能会很慢或中断。

解决方法：

耐心重试：直接再次运行docker-compose up -d，Docker会尝试继续下载未完成的部分。
检查网络：确保你的服务器可以正常访问公网。
使用代理：如果你有为Docker配置镜像加速器的经验，可以配置国内镜像加速源来提升下载速度。

4.3 如何更新到最新版本？

当「丹青识画」发布新版本时，你可以轻松更新。

# 1. 拉取最新的镜像 docker-compose pull # 2. 重新创建并启动容器（使用新镜像） docker-compose up -d

4.4 上传图片后处理失败？

如果上传图片后，系统长时间无响应或报错，很可能是后端AI服务出了问题。

排查步骤：

首先检查后端容器是否正常运行：docker-compose ps。
查看后端日志，寻找错误信息：docker-compose logs backend。常见的可能是模型加载错误或内存不足。
内存不足是常见原因。AI模型运行需要一定内存。确保你的服务器至少有4GB以上的可用内存。如果内存不足，可以考虑增加服务器资源，或者在docker-compose.yml中为backend服务添加内存限制，并确保DEVICE=cpu。