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