Docker下Nginx的容器化部署与数据持久化配置指南

docker run -d \
  --name nginx-dev \
  -p 80:80 -p 443:443 \
  -v $(pwd)/nginx/conf:/etc/nginx/conf.d:ro \
  -v $(pwd)/nginx/certs:/etc/nginx/certs:ro \
  -v $(pwd)/nginx/html:/usr/share/nginx/html:ro \
  nginx:alpine

FROM nginx:alpine
COPY nginx/conf.d/*.conf /etc/nginx/conf.d/
COPY nginx/certs/ /etc/nginx/certs/
COPY frontend/dist/ /usr/share/nginx/html/
# 覆盖默认 index.html，注入构建时间戳
RUN echo "<h1>Frontend v1.2.0 built at $(date)</h1>" > /usr/share/nginx/html/index.html

# nginx-configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-config
data:
  default.conf: |
    server {
      listen 80;
      location /api/ {
        proxy_pass http://spring-boot-svc:8080/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Request-ID $request_id; # 关键：透传请求ID
      }
    }
---
# nginx-deployment.yaml
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        volumeMounts:
        - name: nginx-config
          mountPath: /etc/nginx/conf.d
      volumes:
      - name: nginx-config
        configMap:
          name: nginx-config

# docker-compose.yml
version: '3.8'
services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      # 配置：实时热加载（需配合 nginx-reload.sh）
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      # 证书：独立挂载，便于轮换
      - ./nginx/certs:/etc/nginx/certs:ro
      # 静态资源：前端构建产物
      - ./frontend/dist:/usr/share/nginx/html:ro
      # 日志：持久化到宿主机，便于 ELK 收集
      - ./logs:/var/log/nginx:rw
      # Java 应用上传目录（关键！见下文）
      - ./uploads:/usr/share/nginx/uploads:rw
    environment:
      - NGINX_ENV=${NGINX_ENV:-dev}
    env_file:
      - .env
    depends_on:
      - spring-boot-app
    # 健康检查：验证 upstream 是否可达
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
      interval: 30s
      timeout: 10s
      retries: 3

// FileUploadController.java
@RestController
@RequestMapping("/api")
public class FileUploadController {
    // 上传目录映射到容器卷 /usr/share/nginx/uploads
    private static final String UPLOAD_BASE_PATH = "/usr/share/nginx/uploads";
    @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<Map<String, Object>> handleFileUpload(
            @RequestParam("file") MultipartFile file,
            @RequestHeader(value = "X-Request-ID", required = false) String requestId) {
        try {
            // 1. 生成唯一文件名，避免覆盖
            String originalFilename = file.getOriginalFilename();
            String safeFilename = UUID.randomUUID() + "_" + 
                originalFilename.replaceAll("[^a-zA-Z0-9.-]", "_");
            Path uploadPath = Paths.get(UPLOAD_BASE_PATH, safeFilename);
            // 2. 使用 Files.write 流式写入，避免 OOM
            Files.write(uploadPath, file.getBytes(), 
                StandardOpenOption.CREATE, StandardOpenOption.WRITE);
            // 3. 记录日志（含 X-Request-ID，实现全链路追踪）
            log.info("File uploaded successfully. ID: {}, Name: {}, Size: {} bytes", 
                requestId, safeFilename, file.getSize());
            Map<String, Object> response = new HashMap<>();
            response.put("filename", safeFilename);
            response.put("size", file.getSize());
            response.put("url", "/uploads/" + safeFilename); // Nginx 静态服务路径
            response.put("requestId", requestId);
            return ResponseEntity.ok(response);
        } catch (IOException e) {
            log.error("Failed to upload file: {}", e.getMessage(), e);
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(Map.of("error", "Upload failed"));
        }
    }
    // 获取上传文件（Nginx 已配置 /uploads/ 路径为静态服务）
    @GetMapping("/uploads/{filename:.+}")
    public ResponseEntity<Resource> serveUploadedFile(@PathVariable String filename) {
        try {
            Path file = Paths.get(UPLOAD_BASE_PATH).resolve(filename);
            Resource resource = new UrlResource(file.toUri());
            if (resource.exists() && resource.isReadable()) {
                return ResponseEntity.ok()
                    .header(HttpHeaders.CONTENT_TYPE, 
                        Files.probeContentType(file))
                    .body(resource);
            } else {
                return ResponseEntity.notFound().build();
            }
        } catch (Exception e) {
            return ResponseEntity.internalServerError().build();
        }
    }
}

# nginx.conf
user  nginx;
worker_processes  auto;

# 启用 request_id 模块（Alpine 默认已编译）
# https://nginx.org/en/docs/http/ngx_http_core_module.html#request_id
pid        /var/run/nginx.pid;
events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    # 全局启用 request_id，供下游服务消费
    # https://nginx.org/en/docs/http/ngx_http_core_module.html#request_id
    # 注意：此模块在 nginx >= 1.11.0 可用，Alpine 3.18+ nginx 1.24.x 默认支持
    # 若需更高级 ID 生成（如 Snowflake），可使用 lua-nginx-module
    map $request_id $request_id_for_log {
        "" "-";
        default $request_id;
    }

    log_format main '$remote_addr - $remote_user [$time_local] '
                     '"$request" $status $body_bytes_sent '
                     '"$http_referer" "$http_user_agent" '
                     'req_id="$request_id_for_log"';

    access_log  /var/log/nginx/access.log  main;
    error_log   /var/log/nginx/error.log warn;

    sendfile        on;
    keepalive_timeout  65;

    # Gzip 压缩，提升 API 响应速度
    gzip  on;
    gzip_types application/json text/plain text/css application/javascript;

    # 包含所有站点配置
    include /etc/nginx/conf.d/*.conf;
}

# conf.d/spring-boot.conf
upstream spring-boot-backend {
    server spring-boot-app:8080 max_fails=3 fail_timeout=30s;
    # 启用健康检查（需 Spring Boot Actuator）
    # https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html
    # check interval=3 rise=2 fall=5 timeout=10 type=http;
    # check_http_send "HEAD /actuator/health HTTP/1.0\r\n\r\n";
    # check_http_expect_alive http_2xx http_3xx;
}

server {
    listen 80;
    server_name localhost;

    # 重定向 HTTP 到 HTTPS（生产必须）
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name localhost;

    # SSL 证书（由 volume 挂载）
    ssl_certificate     /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    # 强化 TLS 安全（符合 OWASP TLS 2.0 建议）
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    # HSTS（强制浏览器使用 HTTPS）
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # CORS 支持（若前端跨域）
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
    add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,X-Request-ID' always;
    add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;

    # 静态资源服务（前端 dist）
    location / {
        root /usr/share/nginx/html;
        try_files $uri $uri/ /index.html;
        # 缓存静态资源
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # 上传文件静态服务（Nginx 直接提供，不经过 Java）
    location /uploads/ {
        alias /usr/share/nginx/uploads/;
        # 禁止执行脚本（安全加固）
        location ~ \.(php|pl|py|jsp|sh|cgi)$ {
            return 403;
        }
        # 设置合适缓存头
        expires 7d;
        add_header Cache-Control "public";
    }

    # API 代理到 Spring Boot
    location /api/ {
        proxy_pass http://spring-boot-backend/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Request-ID $request_id; # 关键：透传 request_id

        # 超时设置（避免大文件上传中断）
        proxy_connect_timeout 60s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;

        # 传递原始 URI（Spring Boot 需要）
        proxy_redirect off;
        proxy_buffering on;
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size 256k;
    }

    # Actuator 健康检查（供 Nginx healthcheck 或 Prometheus 抓取）
    location /actuator/ {
        proxy_pass http://spring-boot-backend/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

#!/bin/bash
echo "=== 步骤1：启动服务 ==="
docker-compose up -d
echo "=== 步骤2：模拟文件上传（调用 Java API） ==="
curl -X POST http://localhost:8080/api/upload \
  -F "file=@./test-upload.txt" \
  -H "X-Request-ID: test-$(date +%s)" \
  -w "\nHTTP Status: %{http_code}\n" -s -o /dev/null
echo "=== 步骤3：验证文件是否写入 uploads 目录 ==="
ls -la ./uploads/
echo "=== 步骤4：重启 Nginx 容器（不删卷） ==="
docker-compose restart nginx
echo "=== 步骤5：验证上传文件仍在 ==="
ls -la ./uploads/
echo "=== 步骤6：通过 Nginx 下载该文件 ==="
curl -I http://localhost/uploads/$(ls ./uploads/ | head -1) -w "\nHTTP Status: %{http_code}\n" -s
echo "✅ 持久化测试完成！"

// MdcFilter.java - Spring Boot 拦截器，将 request_id 注入 MDC
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class MdcFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
                         FilterChain chain) throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        String requestId = httpRequest.getHeader("X-Request-ID");
        if (requestId == null || requestId.isBlank()) {
            requestId = UUID.randomUUID().toString();
        }
        // 将 request_id 放入 MDC，日志框架（Logback/Log4j2）会自动打印
        MDC.put("requestId", requestId);
        try {
            chain.doFilter(request, response);
        } finally {
            MDC.clear(); // 清理，避免线程复用污染
        }
    }
}

<configuration>
  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <!-- 输出 requestId -->
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %X{requestId} - %msg%n</pattern>
    </encoder>
  </appender>
  <root level="INFO">
    <appender-ref ref="CONSOLE"/>
  </root>
</configuration>

# docker-compose.yml 片段
  nginx-exporter:
    image: nginx/nginx-prometheus-exporter:0.11.0
    command: [
      "-nginx.scrape-uri=http://nginx:8080/stub_status",
      "-web.listen-address=:9113"
    ]
    ports:
      - "9113:9113"
    depends_on:
      - nginx

# 在 http 块内添加
server {
    listen 127.0.0.1:8080;
    location /stub_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
}

# prometheus.yml
scrape_configs:
  - job_name: 'nginx'
    static_configs:
      - targets: ['nginx-exporter:9113']

# 查看 uploads 目录权限
ls -ld ./uploads
# 应为 755，且属主可读（nginx 进程运行在 nginx 用户下）
chmod 755 ./uploads
# 若文件由 Java 创建，确保其 umask 允许 group/o 读取
# 在 Java 中设置：Files.createFile(path, PosixFilePermissions.asFileAttribute(…))

# docker-compose.yml 必须有：
services:
  spring-boot-app:  # ← 此名称必须与 upstream 中 server 地址一致
    image: spring-boot-app:1.0
    # ...
  nginx:
    # ...
    depends_on:
      - spring-boot-app  # ← 依赖关系确保启动顺序

upstream spring-boot-backend {
    server spring-boot-app:8080; # ← 名称必须与 service 名完全相同
}

client_max_body_size 512M;

spring:
  servlet:
    context-path: /api
  web:
    resources:
      static-locations: classpath:/static/
  servlet:
    multipart:
      max-file-size: 512MB
      max-request-size: 512MB