flashspys/nginx-static 镜像文档

1. 镜像概述与主要用途

flashspys/nginx-static 是一款超级轻量级的 Nginx 镜像，专为静态文件服务设计。相较于官方 Nginx 镜像，该镜像体积不足 4MB（约为官方镜像的 1/10），运行时内存占用仅约 1MB，适合对资源敏感的静态文件托管场景。其核心用途是高效提供静态文件（如 HTML、CSS、JavaScript、图片等）访问服务。

2. 核心功能与特性

• 极致轻量化：镜像体积小于 4MB，远小于官方 Nginx 镜像，节省存储空间和网络传输成本。
• 低资源占用：运行时容器内存占用约 1MB，适合资源受限环境或大规模部署场景。
• 专注静态服务：仅支持静态文件托管，去除非必要模块，简化配置与维护。
• 无 SSL 模块：不包含 Nginx SSL 模块，无法独立实现 HTTPS 功能，需配合反向代理（如 traefik）实现 SSL 终止。

3. 使用场景与适用范围

适用场景

• 静态网站托管（如个人博客、产品文档、营销页面）。
• 前端构建产物（如 React、Vue 应用的 dist 目录）部署。
• 轻量级静态资源服务器（如图片、文件下载服务）。

不适用场景

• 需要直接配置 HTTPS 的场景（需配合反向代理实现）。
• 需动态内容处理（如 PHP、Python 后端）的场景。
• 依赖 Nginx 高级模块（如 Lua、Perl）的场景。

4. 使用方法与配置说明

4.1 基本使用（docker run）

通过 docker run 命令快速启动容器，将主机目录挂载到容器内 /static 目录（镜像默认静态文件根目录），并映射端口：

docker run -v /绝对路径/待服务目录:/static -p 8080:80 flashspys/nginx-static

• 参数说明：
  • -v /绝对路径/待服务目录:/static：将主机上的静态文件目录挂载到容器内的 /static 目录（Nginx 会从该目录读取文件）。
  • -p 8080:80：将容器内 Nginx 监听的 80 端口映射到主机的 8080 端口，外部可通过 [***] 访问静态文件。

4.2 docker-compose 配置

在 docker-compose.yaml 中定义服务，适合多容器协同场景：

version: '3'
services:
  example.org:  # 服务名称，可自定义
    image: flashspys/nginx-static
    container_name: example.org  # 容器名称，可自定义
    ports:
      - 8080:80  # 端口映射：主机端口:容器端口（容器内固定为80）
    volumes: 
      - /path/to/serve:/static  # 挂载主机静态文件目录到容器/static

启动命令：docker-compose up -d

4.3 与 traefik 2.x 集成（实现 HTTPS）

由于镜像不含 SSL 模块，需配合反向代理（如 traefik）实现 HTTPS。以下是 docker-compose.yaml 中集成 traefik 2.x 的示例：

前提条件

• 已配置 traefik 2.x（参考 traefik 基础示例）。
• 确保 traefik 与 nginx-static 在同一网络（若分属不同 docker-compose.yaml，需手动创建并关联网络）。

配置示例

services:
  traefik:
    image: traefik:2.4  # 建议检查是否有更新版本
    # traefik 基础配置（如入口点、证书解析器等），参考官方文档
    ...

  example.org:  # nginx-static 服务
    image: flashspys/nginx-static
    container_name: example.org
    expose:  # 仅暴露端口给内部网络（由 traefik 转发），不直接映射主机端口
      - 80
    labels:  # traefik 路由规则标签
      - "traefik.enable=true"  # 允许 traefik 发现该服务
      - "traefik.http.routers.<router名称>.rule=Host(`example.org`)"  # 替换 <router名称> 和域名
      - "traefik.http.routers.<router名称>.entrypoints=<入口点>"  # 替换 <入口点>（如 websecure）
      # 启用 HTTPS 时取消下方注释，替换 <certresolver>（如 letsencrypt）
      # - "traefik.http.routers.<router名称>.tls.certresolver=<certresolver>"
    volumes: 
      - /host/path/to/serve:/static  # 挂载静态文件目录

4.4 多阶段构建集成

适用于前端项目（如 Node.js 构建），通过多阶段构建将产物直接复制到镜像中：

示例 Dockerfile（Node.js 应用）：

# 第一阶段：构建前端项目
FROM node:alpine AS builder
WORKDIR /usr/src/app
COPY . /usr/src/app
RUN npm install && npm run build  # 执行构建命令（如 npm run build）

# 第二阶段：使用 nginx-static 运行时
FROM flashspys/nginx-static
# 可选：更新系统包（如需）
RUN apk update && apk upgrade
# 将构建产物复制到容器静态文件目录
COPY --from=builder /usr/src/app/dist /static

构建命令：docker build -t my-static-app .
运行命令：docker run -p 8080:80 my-static-app

4.5 自定义 Nginx 配置

默认配置位于容器内 /etc/nginx/conf.d/default.conf，可通过以下方式自定义（如添加重写规则、HTTP 头）：

方法 1：通过 Dockerfile 替换配置

在自定义 Dockerfile 中删除默认配置并复制自定义配置：

FROM flashspys/nginx-static
# 删除默认配置
RUN rm -rf /etc/nginx/conf.d/default.conf
# 复制自定义配置（需提前准备 your-custom-nginx.conf 文件）
COPY your-custom-nginx.conf /etc/nginx/conf.d/default.conf

方法 2：通过卷挂载配置

无需构建镜像，直接挂载主机配置文件覆盖默认配置：

# docker run 命令中添加卷挂载
docker run -v /absolute/path/to/custom.conf:/etc/nginx/conf.d/default.conf ...

或在 docker-compose.yaml 中添加：

volumes:
  - /path/to/custom.conf:/etc/nginx/conf.d/default.conf

5. 注意事项

• 无 SSL 支持：镜像不含 Nginx SSL 模块，不可直接配置 HTTPS，必须通过反向代理（如 traefik、nginx-proxy）处理 SSL 终止。
• 静态文件路径：容器内静态文件根目录固定为 /static，需通过卷挂载或多阶段构建将文件放入该目录。
• 资源限制：因极致轻量化，不支持动态模块加载或高级功能（如 PHP 解析、WebSocket 代理等）。