horneds/muffin

muffin-docker 镜像文档

镜像概述与主要用途

muffin-docker 是基于 Docker 的 Muffin 框架镜像，集成 Gunicorn 和 Uvicorn 作为应用服务器，用于快速部署基于 Muffin 的 ASGI 应用。该镜像提供两个版本：

• 基础版本 (horneds/muffin)：包含 Python、Muffin、Gunicorn、Uvicorn
• NodeJS 版本 (horneds/muffin-node)：在基础版本上增加 NodeJS 环境

支持多种 Python 版本，适用于开发和生产环境中 Muffin 应用的容器化部署。

核心功能与特性

• 多 Python 版本支持：兼容 Python 3.9、3.10、3.11、3.12（最新版）
• 灵活部署：可作为基础镜像构建自定义应用镜像
• 服务器集成：默认集成 Gunicorn 作为进程管理器，Uvicorn 作为 ASGI 服务器
• 依赖管理：支持通过 PIP、Poetry 等工具自定义安装应用依赖
• 环境变量配置：通过环境变量灵活调整应用入口、服务器参数等

支持的镜像标签

使用场景与适用范围

• 快速部署 Muffin 应用：适用于需要标准化部署流程的开发、测试及生产环境
• 指定 Python 版本：支持根据应用需求选择 Python 3.9 至 3.12 版本
• 依赖 NodeJS 的场景：需前端构建工具（如 npm、yarn）的 Muffin 应用可选用 muffin-node 镜像

使用方法

作为基础镜像构建应用

无需克隆 GitHub 仓库，直接将该镜像作为基础镜像，在应用的 Dockerfile 中引用：

dockerfile
FROM docker.xuanyuan.run/horneds/muffin:latest  # 或指定版本标签，如 horneds/muffin:py311

# 将应用代码复制到容器内的 /app 目录
COPY ./app /app

应用代码要求：

• 默认期望应用入口文件为 /app/app.py 或 /app/main.py
• 入口文件中需包含名为 app 的 ASGI 应用实例（即 app = Muffin(__name__) 创建的实例）

安装依赖

应用通常需要安装自定义依赖（如特定版本的 Uvicorn、Gunicorn 或业务库），推荐通过 requirements.txt 或 Poetry 管理并固定版本。

使用 PIP 安装依赖

1. 在应用目录下创建 requirements.txt，列出依赖及版本：

   txt
   # requirements.txt 示例
   muffin==0.9.0
   uvicorn==0.24.0
   gunicorn==21.2.0
   

2. 在 Dockerfile 中添加依赖安装步骤：

   dockerfile
   FROM docker.xuanyuan.run/horneds/muffin:latest
   
   # 复制依赖文件并安装
   COPY ./requirements.txt /app/requirements.txt
   RUN pip install -r /app/requirements.txt
   
   # 复制应用代码
   COPY ./app /app
   

构建与运行镜像

构建镜像

在包含 Dockerfile 的目录下执行构建命令：

bash
docker build -t my-muffin-app ./

运行容器

启动容器并映射端口（示例映射主机 80 端口到容器 80 端口）：

bash
docker run -d --name my-app-container -p 80:80 docker.xuanyuan.run/my-muffin-app

访问应用：
容器启动后，通过 http://<Docker 主机 IP> 访问应用（本地环境通常为 http://127.0.0.1）。

配置说明

环境变量

通过环境变量自定义应用启动参数，支持以下变量：

示例：
启动容器时指定自定义模块和端口：

bash
docker run -d \
  --name my-app-container \
  -p 8080:8080 \
  -e MODULE_NAME=app.entry \
  -e PORT=8080 \
  docker.xuanyuan.run/my-muffin-app

许可证

本项目基于 https://opensource.org/licenses/MIT 开源。