devilbox/nginx-stable

Nginx Stable (Devilbox)

镜像概述

devilbox/nginx-stable 是基于官方 Nginx Docker 镜像构建的增强版 Web 服务器镜像。它集成了 watcherd 和 vhost-gen 工具，扩展了自动创建虚拟主机和自动签发 SSL 证书的能力。用户只需将本地项目目录挂载到容器的 /shared/httpd 路径下，在该目录中创建的任何新文件夹都会自动生成同名的虚拟主机。每个虚拟主机均支持静态文件、PHP-FPM 或反向代理后端配置，且默认对所有 SSL 连接启用 HTTP/2。

核心功能与特性

• 自动批量虚拟主机：无需手动配置 Web 服务器，在挂载目录中创建新项目文件夹即可自动生成对应的虚拟主机。
• 自动化 PHP-FPM 集成：镜像本身不包含 PHP，但可通过环境变量轻松链接远程 PHP-FPM 镜像，方便随时切换 PHP 版本。
• 自动化反向代理：支持将任意 HTTP/HTTPS 后端（如 Node.js、Python 等）作为反向代理目标，并由 Nginx 统一处理 SSL 卸载。
• 自动 SSL 证书生成：为每个虚拟主机自动生成 SSL 证书。内置内部证书颁发机构（CA），将其设为系统信任后，所有生成的虚拟主机即可实现可信 HTTPS 访问。
• 虚拟主机深度自定义：支持通过 vhost-gen 模板对每个虚拟主机进行独立的精细化配置。
• 本地文件权限同步：通过在 docker run 时指定 UID 和 GID，可确保容器内外的文件系统权限和所有权保持一致。
• 广泛的框架兼容性：经过全面测试，完美支持 WordPress、Drupal、Laravel、Magento、Shopware、Typo3 等主流 Web 框架。
• 智能入口验证：入口脚本提供详细的输入验证和错误提示，帮助用户快速定位和修复配置问题。

使用场景与适用范围

• 本地开发环境：为开发者提供免配置的 LEMP/LNMP 堆栈，新建目录即可运行新项目。
• 多项目托管：在单一容器中托管大量独立的 Web 应用或微服务前端。
• 微服务反向代理：作为统一网关，为后端的 Node.js、Python 或 Go 服务提供 SSL 终止和路由分发。
• 快速原型验证：无需编写复杂的 Nginx 配置文件，即可快速搭建支持 HTTPS 的原型环境。

镜像标签与架构支持

支持的 CPU 架构：amd64, arm64, 386, arm/v7, arm/v6

滚动发布标签 (Rolling releases)

每晚自动构建并更新，适合追求最新特性的开发环境。

固定版本标签 (Point in time releases)

基于特定 Git Tag 构建，版本永不改变，适合需要可重复构建的生产环境或 CI/CD 流水线。

详细配置说明

环境变量

镜像提供了丰富的环境变量以控制各项功能。如果输入错误，容器启动时的验证脚本会输出详细的修复建议。

数据卷挂载

暴露端口

部署与使用示例

示例 1：使用 Docker Run 部署静态文件服务（批量虚拟主机）

此示例将本地 ./projects 目录挂载到容器中，并自动为其中的每个子目录创建一个静态文件虚拟主机。

bash
docker run -d \
  --name nginx-stable \
  -p 80:80 \
  -v $(pwd)/projects:/shared/httpd \
  -e MASS_VHOST_ENABLE=1 \
  -e MASS_VHOST_BACKEND=static \
  -e MASS_VHOST_TLD_SUFFIX=.loc \
  -e NEW_UID=$(id -u) \
  -e NEW_GID=$(id -g) \
  docker.xuanyuan.run/devilbox/nginx-stable

访问方式：如果在 ./projects 下创建了 myapp 目录，则可通过 http://myapp.loc 访问。

示例 2：使用 Docker Compose 部署 LEMP 堆栈（PHP-FPM + 自动 HTTPS）

此示例展示如何结合 PHP-FPM 镜像，搭建支持自动 HTTPS 和批量虚拟主机的完整开发环境。

yaml
version: '3.8'

services:
  nginx:
    image: docker.xuanyuan.run/devilbox/nginx-stable:latest
    container_name: devilbox-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./projects:/shared/httpd
      - ./ca:/ca
    environment:
      - MASS_VHOST_ENABLE=1
      - MASS_VHOST_BACKEND=php-fpm:php:9000
      - MASS_VHOST_SSL_TYPE=both
      - MASS_VHOST_TLD_SUFFIX=.loc
      - NEW_UID=1000
      - NEW_GID=1000
      - HTTP2_ENABLE=1
    depends_on:
      - php

  php:
    image: docker.xuanyuan.run/devilbox/php-fpm:8.2
    container_name: devilbox-php
    volumes:
      - ./projects:/shared/httpd
    environment:
      - NEW_UID=1000
      - NEW_GID=1000

说明：启动后，在 ./projects 中创建新项目，Nginx 会自动生成 SSL 证书并配置 PHP-FPM 代理。将 ./ca 目录中的 CA 证书导入宿主机系统并设为信任，即可实现浏览器无警告的 HTTPS 访问。

架构设计

镜像内部采用模块化设计，确保自动化流程的高效与稳定：

1. 入口脚本 (docker-entrypoint.sh)：负责环境变量验证、权限调整和初始化配置。
2. 进程管理 (supervisord)：作为 PID 1 进程，同时管理 Nginx 和 watcherd。
3. 文件监控 (watcherd)：实时监控 /shared/httpd 目录的文件系统事件（创建/删除目录）。
4. 配置生成 (vhost-gen & cert-gen)：当检测到新目录时，自动调用证书生成工具签发 SSL，并通过 vhost-gen 渲染 Nginx 虚拟主机配置文件，最后平滑重载 Nginx。