tianon/mojo

Mojolicious Docker镜像技术文档

1. 镜像概述和主要用途

Mojolicious Docker镜像是基于Perl的现代Web框架Mojolicious构建的容器化解决方案，旨在简化Mojolicious Web应用的开发、测试和部署流程。该镜像内置Perl运行环境及Mojolicious框架，提供开箱即用的Web开发和运行环境，支持快速构建和部署Perl Web应用。

2. 核心功能和特性

• 纯Perl实现：框架完全基于Perl开发，无外部依赖，简化部署流程。
• 内置高性能Web服务器：集成Hypnotoad（多进程异步服务器）和Morbo（开发热重载服务器），无需额外配置Web服务器。
• 现代Web支持：原生支持WebSocket、实时Web通信、服务器推送事件（SSE）。
• 完整开发工具链：包含RESTful路由系统、嵌入式模板引擎（EP/TT2）、表单处理、会话管理等组件。
• 异步I/O能力：基于Perl的AnyEvent/IO::Async，支持非阻塞请求处理，提升并发性能。
• 灵活配置：通过环境变量或配置文件支持运行参数自定义，适配开发/生产环境。

3. 使用场景和适用范围

• 快速开发环境搭建：本地开发时一键启动Mojolicious环境，无需手动配置Perl依赖。
• 小型Web应用部署：轻量级应用（如个人博客、内部工具）的容器化部署。
• API服务开发：构建RESTful API或微服务，利用框架的路由和异步特性提升响应效率。
• 实时Web应用：开发即时通讯、实时数据监控等需要WebSocket/SSE支持的应用。
• Perl Web项目容器化：将现有Mojolicious项目迁移至容器环境，简化跨环境部署。

4. 详细使用方法和配置说明

4.1 拉取镜像

bash
docker pull docker.xuanyuan.run/mojolicious:latest

4.2 基本运行示例

运行默认演示应用（验证环境可用性）：

bash
docker run -d -p 3000:3000 --name mojolicious-demo docker.xuanyuan.run/mojolicious:latest

访问 http://localhost:3000 即可查看默认演示页面。

4.3 挂载本地应用代码

将本地Mojolicious应用（如 app.pl）挂载至容器内运行：

bash
# 假设本地应用目录为 ./myapp，入口文件为 ./myapp/app.pl
docker run -d \
  -p 3000:3000 \
  -v $(pwd)/myapp:/app \
  --name my-mojolicious-app \
  docker.xuanyuan.run/mojolicious:latest

容器会自动执行 /app/app.pl 作为应用入口（需确保 app.pl 有可执行权限）。

4.4 Docker Compose部署

创建 docker-compose.yml 配置文件：

yaml
version: '3.8'
services:
  mojolicious-app:
    image: docker.xuanyuan.run/mojolicious:latest
    container_name: mojolicious-app
    restart: always
    ports:
      - "8080:3000"  # 宿主机8080端口映射至容器3000端口
    volumes:
      - ./myapp:/app  # 挂载本地应用代码
    environment:
      - MOJO_LISTEN=http://*:3000  # 容器内监听地址
      - MOJO_MODE=production  # 生产模式运行
      - MOJO_HOME=/app  # 应用根目录
    command: hypnotoad /app/app.pl  # 使用Hypnotoad服务器（生产环境推荐）

启动服务：

bash
docker-compose up -d

5. 配置参数与环境变量说明

5.1 核心环境变量

5.2 服务器配置（Hypnotoad）

生产环境推荐使用Hypnotoad服务器，支持多进程和热重启。通过容器命令或 hypnotoad.conf 配置：

bash
# 启动Hypnotoad并指定应用入口
docker run -d -p 80:8080 -v ./myapp:/app docker.xuanyuan.run/mojolicious:latest hypnotoad /app/app.pl

常用Hypnotoad参数（通过 hypnotoad.conf 配置，需挂载至 /app/hypnotoad.conf）：

perl
{
  listen => ['http://*:8080'],
  workers => 4,  # 工作进程数（建议设为CPU核心数）
  pid_file => '/var/run/hypnotoad.pid',
  proxy => 1  # 启用反向代理支持（如前置Nginx）
}

6. 注意事项

• 开发模式：MOJO_MODE=development 下，Morbo服务器会自动检测代码变更并重启，适合开发调试；生产环境需切换为 production 并使用Hypnotoad。
• 数据持久化：若应用需持久化数据（如日志、数据库文件），需额外挂载数据卷（如 -v ./logs:/app/logs）。
• 安全配置：生产环境必须设置 MOJO_SECRET 并使用HTTPS（可配合Nginx反向代理或设置 MOJO_LISTEN=https://*:443?cert=./cert.pem&key=./key.pem）。
• 权限问题：挂载本地目录时，确保宿主机目录权限允许容器内用户（通常为非root用户）读取，避免权限拒绝错误。