YuLan-OneSim 项目 Docker 容器化部署指南

项目概述

YuLan-OneSim 是一个集成了前端界面、后端服务和命令行工具的统一仿真平台。本文将从技术角度详细解析其 Docker 容器化部署方案，帮助开发者理解其架构设计和实现原理。

容器架构设计

YuLan-OneSim 采用多阶段构建的 Docker 镜像方案，主要包含两个构建阶段：

1. 前端构建阶段：基于 Node.js 18 的轻量级镜像
2. 主服务阶段：基于 Python 3.10 的完整运行环境

这种设计既保证了构建环境的完整性，又确保了最终镜像的精简性。

详细构建过程解析

前端构建阶段

FROM node:18-slim AS frontend-builder
WORKDIR /frontend
COPY src/frontend/package*.json ./
RUN npm install
COPY src/frontend/ ./
RUN npm run build

这一阶段完成了：

• 前端依赖安装（npm install）
• 前端项目构建（npm run build）
• 生成静态文件存储在 /frontend/dist 目录

主服务阶段

主服务阶段基于 Python 3.10 构建，包含以下关键配置：

环境变量设置

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PYTHONPATH=/app/src \
    DEBIAN_FRONTEND=noninteractive

这些环境变量优化了 Python 运行环境，确保日志输出实时可见，并设置了正确的模块导入路径。

系统依赖安装

RUN apt-get update && apt-get install -y \
    nginx \
    process-manager \
    curl \
    procps \
    build-essential

安装了必要的系统组件：

• Nginx：作为 Web 服务器
• 进程管理工具
• 其他工具：curl（健康检查）、procps（进程管理）、build-essential（Python 包编译）

Python 依赖安装

COPY setup.py README.md ./
COPY src/ ./src/
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -e .

采用可编辑模式安装（-e），便于开发调试。

前端部署

COPY --from=frontend-builder /frontend/dist /var/www/html

将前端构建产物复制到 Nginx 的默认静态文件目录。

服务配置

COPY config/ ./config/
COPY docker/nginx.conf /etc/nginx/nginx.conf
COPY docker/process-manager.conf /etc/process-manager/conf.d/process-manager.conf

复制了项目配置文件、Nginx 配置和进程管理配置，实现服务的统一管理。

启动脚本

COPY docker/start.sh /start.sh
RUN chmod +x /start.sh

自定义启动脚本，通过进程管理工具管理所有服务进程。

健康检查机制

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
    CMD curl -f http://localhost/health || exit 1

容器内置了健康检查机制，定期访问 /health 端点验证服务可用性。

部署实践建议

1. 端口映射：容器暴露 80 端口，运行时需映射到宿主机端口

   docker run -p 8080:80 yulan-onesim
   

2. 数据持久化：建议将日志目录挂载到宿主机

   docker run -v ./logs:/app/logs yulan-onesim
   

3. 配置覆盖：可通过挂载方式覆盖默认配置

   docker run -v ./custom_config:/app/config yulan-onesim
   

技术亮点总结

1. 多阶段构建：有效减小最终镜像体积
2. 进程管理：使用进程管理工具管理多进程服务
3. 健康监控：内置健康检查机制确保服务可用性
4. 开发友好：可编辑模式安装便于调试
5. 一体化部署：前端+后端+CLI 全功能集成

通过这种容器化方案，YuLan-OneSim 实现了"一次构建，随处运行"的部署目标，大大降低了环境配置的复杂度。