MogFace模型Docker容器化部署基于GitHub Actions的CI/CD实践今天咱们来聊聊一个非常实用的工程化话题如何把一个AI模型比如MogFace打包成一个可以“拎包入住”的Docker镜像并且实现从代码提交到最终部署的全自动化。听起来有点复杂别担心我会用最直白的方式带你一步步走完这个流程。想象一下这个场景你开发了一个很棒的MogFace WebUI应用想在团队里分享或者部署到云端服务器上。传统做法是你得写一份长长的环境配置文档告诉同事“先装Python 3.8再装这个库、那个库注意版本冲突……”。结果往往是在你电脑上跑得好好的到别人那儿就各种报错。Docker就是为了解决这个“在我机器上能跑”的经典问题而生的。它能把你的应用和它所有的依赖像打包成一个集装箱一样封装成一个镜像。这个镜像在任何支持Docker的地方都能以完全相同的方式运行。而我们今天要做的不仅仅是打包还要让这个打包、测试、发布的过程完全自动化。这就是CI/CD持续集成/持续部署的魅力。通过这篇教程你将学会如何搭建一套自动化流水线你只需要把代码推送到GitHub剩下的构建、测试、发布流程全部由GitHub Actions自动完成。最终在星图GPU这样的平台上你只需要一条命令就能拉取最新的镜像并运行起来。这能极大提升开发效率和部署的可靠性。1. 环境准备与项目概览在开始动手之前我们先确保手头有必要的工具并了解一下我们要处理的项目结构。1.1 你需要准备什么要跟着做一遍你的电脑上需要安装以下软件。别怕都是免费且容易获取的。Docker Desktop这是核心工具用于在本地构建和运行容器。去Docker官网下载对应你操作系统Windows、macOS、Linux的安装包按照指引安装即可。安装后在终端输入docker --version能显示版本号就说明安装成功了。Git代码版本管理工具。同样从官网下载安装。安装后在终端输入git --version检查。一个GitHub账号这是免费的我们将用它的仓库来存代码用它的GitHub Actions功能来做自动化。一个Docker Hub账号或其他容器镜像仓库账号如阿里云容器镜像服务用于存放我们构建好的Docker镜像。Docker Hub提供免费的公开仓库。1.2 理解MogFace WebUI项目为了教程的通用性我们假设一个典型的MogFace WebUI项目结构。你的实际项目可能略有不同但核心文件是类似的。一个基本的项目文件夹可能长这样mogface-webui/ ├── app/ │ ├── main.py # Web应用主入口可能是FastAPI或Gradio应用 │ ├── model_handler.py # 加载和运行MogFace模型的代码 │ └── requirements.txt # Python依赖包列表 ├── Dockerfile # Docker镜像构建说明书 ├── .dockerignore # 告诉Docker哪些文件不需要打包进镜像 ├── .github/ │ └── workflows/ │ └── ci-cd.yml # GitHub Actions自动化工作流定义文件 ├── tests/ │ └── test_app.py # 简单的单元测试 └── README.md其中requirements.txt文件列出了所有Python依赖例如fastapi0.104.0 uvicorn[standard] torch2.0.0 torchvision pillow gradio4.0.0 # 以及其他MogFace模型可能需要的库Dockerfile是我们接下来要重点编写的“食谱”它告诉Docker如何一步步搭建镜像。.github/workflows/ci-cd.yml则是自动化流水线的“剧本”。2. 编写Dockerfile创建标准化镜像Dockerfile就像一份详细的组装说明书。我们从一个基础镜像开始一步步添加我们需要的东西最终生成我们自己的应用镜像。2.1 基础镜像选择选择合适的基础镜像很重要它决定了镜像的初始环境。对于AI应用我们通常选择包含Python和常用科学计算库的镜像。# 使用官方Python镜像作为基础选择较小的slim版本以减少镜像体积 FROM python:3.10-slim # 设置工作目录后续的指令都会在这个目录下执行 WORKDIR /app这里我们选择了python:3.10-slim。slim版本比完整版小很多适合生产环境。WORKDIR /app设定容器内的当前工作目录为/app。2.2 安装系统依赖与Python包有些Python包比如OpenCV、PyTorch的某些功能需要系统级别的库支持。我们需要先安装它们。# 安装系统依赖例如图形库、编译工具等根据你的模型需求调整 RUN apt-get update apt-get install -y \ libgl1-mesa-glx \ libglib2.0-0 \ rm -rf /var/lib/apt/lists/* # 清理缓存以减小镜像大小接下来将我们本地的依赖文件复制到镜像中并用pip安装。# 首先复制依赖文件这样可以利用Docker的缓存层避免依赖未变更时重复安装 COPY requirements.txt . # 安装Python依赖使用清华镜像源加速下载国内用户建议 RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt--no-cache-dir告诉pip不要缓存下载的包进一步减小镜像体积。-i参数指定了镜像源在国内网络环境下能显著提升下载速度。2.3 复制应用代码并设置启动命令现在把我们的应用源代码复制到镜像里。# 复制应用源代码 COPY ./app ./app COPY ./models ./models # 假设模型文件放在本地models目录 # 复制其他必要的文件比如配置文件 # COPY config.yaml .最后我们需要告诉Docker当容器启动时应该运行什么命令来启动我们的应用。# 声明容器运行时监听的端口FastAPI/Gradio默认端口 EXPOSE 7860 # 设置容器启动命令 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 7860]EXPOSE 7860是一个声明说明这个容器会使用7860端口Gradio常用端口。CMD指令定义了默认的启动命令。这里我们使用uvicorn来启动一个FastAPI应用。如果你的应用是Gradio直接启动的命令可能是[python, app/main.py]。2.4 完整的Dockerfile示例把上面的步骤组合起来一个完整的Dockerfile可能如下所示# Dockerfile FROM python:3.10-slim WORKDIR /app # 安装系统依赖 RUN apt-get update apt-get install -y \ libgl1-mesa-glx \ libglib2.0-0 \ rm -rf /var/lib/apt/lists/* # 复制并安装Python依赖 COPY requirements.txt . RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt # 复制应用代码 COPY ./app ./app COPY ./models ./models EXPOSE 7860 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 7860]别忘了创建.dockerignore文件它类似于.gitignore可以避免将虚拟环境、缓存文件等不必要的文件打包进镜像从而减小镜像体积。# .dockerignore __pycache__/ *.pyc *.pyo *.pyd .Python env/ venv/ .venv .env .git/ .DS_Store *.log3. 本地构建与测试镜像在交给自动化流水线之前我们先在本地验证一下Dockerfile是否正确。3.1 构建Docker镜像打开终端进入你的项目根目录即Dockerfile所在的目录执行构建命令docker build -t mogface-webui:latest .-t mogface-webui:latest给镜像打一个标签Tag名称是mogface-webui版本是latest。.表示构建上下文是当前目录Docker会在这里寻找Dockerfile。这个过程会花费一些时间Docker会按照Dockerfile的指令一层层构建。如果一切顺利最后会看到Successfully built和Successfully tagged的提示。3.2 运行并测试容器镜像构建成功后我们可以运行它看看应用是否能正常启动。docker run -d -p 7860:7860 --name mogface-app mogface-webui:latest-d在后台运行容器守护进程模式。-p 7860:7860将宿主机的7860端口映射到容器的7860端口。--name mogface-app给这个运行的容器实例起个名字方便管理。mogface-webui:latest指定要运行的镜像。运行后打开浏览器访问http://localhost:7860。如果看到你的MogFace WebUI界面恭喜你本地Docker化成功了你可以用以下命令查看容器日志或停止容器# 查看容器日志 docker logs mogface-app # 停止容器 docker stop mogface-app # 删除容器 docker rm mogface-app4. 使用GitHub Actions实现自动化CI/CD手动构建和推送镜像太麻烦了。我们的目标是每次把代码推送到GitHub的主分支比如main就自动完成构建、测试和发布。GitHub Actions可以完美实现这一点。4.1 创建GitHub仓库与密钥首先将你的代码推送到一个GitHub仓库如果还没做的话。git init git add . git commit -m Initial commit with Dockerfile # 在GitHub上创建一个新仓库比如叫 mogface-docker-demo git remote add origin https://github.com/你的用户名/mogface-docker-demo.git git branch -M main git push -u origin main然后我们需要在GitHub仓库设置里添加两个密钥Secrets用于安全地登录Docker Hub。进入你的GitHub仓库页面。点击Settings-Secrets and variables-Actions。点击New repository secret。创建两个密钥DOCKERHUB_USERNAME你的Docker Hub用户名。DOCKERHUB_TOKEN你的Docker Hub访问令牌Token。需要在Docker Hub网站生成Account Settings - Security - New Access Token。4.2 编写GitHub Actions工作流文件在项目根目录创建.github/workflows/ci-cd.yml文件。这个YAML文件定义了自动化流水线的每一步。# .github/workflows/ci-cd.yml name: Build and Push Docker Image # 触发条件当代码推送到main分支或者发起Pull Request到main分支时 on: push: branches: [ main ] pull_request: branches: [ main ] # 定义环境变量 env: IMAGE_NAME: mogface-webui # 你的Docker Hub用户名这里通过 secrets 引用 DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} jobs: build-and-push: runs-on: ubuntu-latest # 在GitHub提供的Ubuntu最新版虚拟机上运行 steps: # 步骤1: 检出代码 - name: Checkout repository uses: actions/checkoutv4 # 步骤2: 登录到Docker Hub - name: Log in to Docker Hub uses: docker/login-actionv3 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} # 步骤3: 设置Docker构建器可选用于多平台构建这里简化 - name: Set up Docker Buildx uses: docker/setup-buildx-actionv3 # 步骤4: 提取元数据标签、镜像名 - name: Extract metadata (tags, labels) id: meta uses: docker/metadata-actionv5 with: images: ${{ env.DOCKERHUB_USERNAME }}/${{ env.IMAGE_NAME }} tags: | typeref,eventbranch typesha,prefix{{branch}}- # 步骤5: 构建并推送Docker镜像 - name: Build and push Docker image uses: docker/build-push-actionv5 with: context: . push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }}这个工作流做了以下几件事触发代码推送到main分支时自动运行。环境定义了镜像名称和从密钥读取的用户名。任务只有一个名为build-and-push的任务。步骤检出你的代码。使用你的密钥登录Docker Hub。设置构建环境。根据Git分支和提交信息自动生成镜像标签例如main-latest、main-abc123。构建Docker镜像并推送到你的Docker Hub仓库例如你的用户名/mogface-webui:main-latest。4.3 添加测试步骤可选但推荐一个健壮的CI/CD流水线应该包含测试。我们可以在构建镜像后运行一个简单的测试容器来验证基本功能。在build-and-push任务的步骤中在构建推送步骤之前或之后可以插入一个测试步骤# 步骤X: 运行单元测试在构建之后推送之前 - name: Run Tests run: | # 构建一个用于测试的镜像标签 docker build -t ${{ env.IMAGE_NAME }}-test:latest . # 运行测试假设你的tests目录有测试脚本 # 这里示例为运行一个简单的HTTP健康检查你可以替换为pytest等 docker run --rm ${{ env.IMAGE_NAME }}-test:latest python -m pytest tests/ -v将代码推送到GitHub后你可以在仓库的Actions标签页下看到工作流的运行状态。绿色对勾表示成功。5. 在星图GPU平台一键部署镜像已经自动推送到Docker Hub了。现在我们可以在任何支持Docker的环境比如星图GPU云平台上部署它。这里以在星图平台操作为例流程非常直观。5.1 拉取并运行镜像在星图GPU平台创建实例时通常可以选择预置环境或自定义镜像。我们选择自定义Docker镜像。创建实例/容器在平台的控制台找到创建计算实例或容器的入口。选择镜像源在“镜像”或“容器配置”部分选择“自定义镜像”或“Docker镜像”。填写镜像地址输入你在Docker Hub上的镜像地址格式为你的用户名/mogface-webui:标签。例如如果你使用了上面的工作流最新的镜像标签可能是你的用户名/mogface-webui:main-latest。配置端口映射在容器配置中添加端口映射。将容器内部的7860端口映射到主机的一个端口比如7860这样你才能从外部访问WebUI。配置资源根据MogFace模型的大小和预期并发分配合适的GPU、CPU和内存资源。启动点击创建或启动按钮。5.2 验证部署实例启动后平台会提供一个访问地址通常是一个IP和端口。在浏览器中打开http://平台提供的IP:映射的端口例如http://123.45.67.89:7860你应该就能看到和本地运行一模一样的MogFace WebUI界面了。至此整个自动化流水线就打通了你在本地修改代码 - 推送到GitHub - GitHub Actions自动构建并推送新镜像 - 在星图平台重启容器或使用新镜像创建实例 - 新功能上线。整个过程无需手动介入构建和传输镜像实现了高效的持续部署。6. 总结走完这一整套流程你会发现将AI应用Docker化并搭配CI/CD带来的好处是实实在在的。首先是环境的一致性彻底告别了“依赖地狱”。其次是部署的便捷性无论是在本地、团队内部服务器还是像星图这样的云平台都是一条docker run命令的事。最重要的是自动化它把开发者从重复的构建、上传工作中解放出来让发布变得可预测、可追溯。刚开始接触Docker和GitHub Actions可能会觉得步骤有点多但一旦搭建好这个框架它就会成为你开发流程中一个非常可靠的基础设施。下次当你再开发一个新的AI应用时只需要复制这套模板稍微修改一下Dockerfile和requirements.txt就能立刻拥有同样的自动化超能力。不妨现在就为你手头的项目试试看吧。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。