NGINX Static Server 镜像文档

镜像概述和主要用途

NGINX Static Server 是一个基于 NGINX 的轻量级 Docker 镜像，专为高效托管静态内容设计。该镜像默认集成性能优化特性，可快速部署静态网站、单页应用（SPA）及各类静态资源，适用于需要高效内容传输和缓存的场景。

核心功能和特性

• 高效静态内容托管：基于 NGINX 优化配置，提供高性能静态文件服务
• 默认支持 ETags：自动生成实体标签（ETag），优化浏览器缓存及资源重新验证机制
• 内置压缩支持：默认启用 Brotli 和 GZip 压缩算法，显著减少静态资源传输大小
• 轻量级设计：精简镜像体积，降低部署资源占用，加速启动速度

使用场景和适用范围

• 静态网站部署：适用于纯静态 HTML/CSS/JS 网站，或通过前端框架（如 React、Vue、Angular）构建的静态产物
• 单页应用（SPA）：支持前端路由，可配置将 404 请求重定向至 index.html，适配 SPA 路由模式
• 静态资源服务：托管图片、字体、文档等静态资源，通过压缩和缓存提升加载速度
• 轻量静态内容托管：需要低资源占用、快速部署的静态内容场景（如个人博客、项目文档站）

详细使用方法和配置说明

快速启动

通过 docker-compose 可快速部署，默认配置下将本地静态文件目录挂载至容器，即可通过 80 端口访问。

docker-compose 配置示例

# docker-compose.yml
version: '3.7'

services:
  static-server:  # 服务名称
    image: cupcakearmy/static  # 使用目标镜像
    restart: unless-stopped  # 除非手动停止，否则自动重启
    ports:
      - 80:80  # 端口映射：主机 80 端口 -> 容器 80 端口
    volumes:
      - ./public:/srv:ro  # 挂载本地静态文件目录（./public）至容器内 /srv（只读权限）

启动命令

在 docker-compose.yml 所在目录执行：

docker-compose up -d  # 后台启动服务

此时，访问 http://localhost 即可查看 ./public 目录下的静态内容。

自定义配置

若默认配置不满足需求（如修改端口、调整路由规则、添加跨域头），可通过挂载自定义 NGINX 配置文件覆盖默认配置。

自定义配置文件示例

创建 my.conf 文件，定义自定义 NGINX 服务配置：

# my.conf - 自定义静态服务配置
server {
    listen 80;  # 监听端口
    server_name _;  # 匹配所有域名（默认）

    location / {
        root   /srv;  # 静态文件根目录（对应容器内 /srv，需与挂载路径一致）
        try_files $uri /index.html =404;  # SPA 路由支持：优先匹配文件，否则重定向至 index.html，最后返回 404
    }

    # 可选：添加缓存控制头
    location ~* \.(js|css|png|jpg|jpeg|gif|ico)$ {
        expires 1y;  # 设置长期缓存
        add_header Cache-Control "public, max-age=31536000";
    }
}

应用自定义配置

修改 docker-compose.yml，通过 volumes 挂载自定义配置文件至容器默认配置路径：

version: '3.7'

services:
  static-server:
    image: cupcakearmy/static
    restart: unless-stopped
    ports:
      - 80:80
    volumes:
      - ./public:/srv:ro  # 静态文件目录
      - ./my.conf:/usr/local/nginx/conf/sites/default.conf  # 挂载自定义配置覆盖默认配置

重启服务使配置生效：

docker-compose up -d --force-recreate  # 重建并启动服务

直接使用 docker run 命令部署

若无需 docker-compose，可直接通过 docker run 命令启动容器：

docker run -d \
  --name static-server \
  --restart unless-stopped \
  -p 80:80 \
  -v ./public:/srv:ro \
  cupcakearmy/static

如需应用自定义配置，添加配置文件挂载参数：

docker run -d \
  --name static-server \
  --restart unless-stopped \
  -p 80:80 \
  -v ./public:/srv:ro \
  -v ./my.conf:/usr/local/nginx/conf/sites/default.conf \
  cupcakearmy/static

配置说明

默认配置路径

容器内默认配置文件路径：/usr/local/nginx/conf/sites/default.conf，可通过挂载自定义文件覆盖此路径实现配置自定义。

核心配置项说明

• 根目录：默认静态文件根目录为 /srv，需通过 -v 挂载本地目录至该路径（建议设为只读权限 :ro）
• 监听端口：默认监听 80 端口，可通过 NGINX 配置文件修改（需同步调整 -p 端口映射）
• 压缩配置：默认启用 Brotli（优先）和 GZip 压缩，无需额外配置
• ETags：默认自动生成 ETags，基于文件内容和修改时间，优化缓存验证

注意事项

• 挂载静态文件目录时建议使用 :ro 只读权限，增强容器安全性
• 自定义配置时需确保 root 路径与挂载的静态文件目录一致（默认 /srv）
• 若需使用非 80 端口，需同时修改 NGINX 配置中的 listen 指令和容器端口映射（-p）