FastAPI配置Nginx反向代理SSL加密教程

1. SSL配置策略概述

在构建Web应用时，确保数据传输的安全性至关重要。对于FastAPI这类后端服务，直接在应用层（如使用Uvicorn的ssl_keyfile和ssl_certfile参数）配置SSL虽然可行，但通常会导致CORS问题，并且将SSL管理的复杂性引入到应用代码中。更推荐的做法是使用专业的反向代理服务器（如Nginx）来处理SSL终止。

Nginx作为反向代理有以下优势：

• SSL终止集中化： Nginx负责解密HTTPS请求并将其转发为HTTP请求到后端服务，减轻了后端服务的负担。
• 性能优化： Nginx在处理静态文件、压缩和缓存方面表现出色，能有效提升整体性能。
• 安全性增强： Nginx提供了强大的安全特性，如DDoS防护、限速等。
• 简化应用配置： 应用服务无需关注SSL细节，只需监听HTTP端口。
• 证书管理： 证书的续期、更新等操作可以在Nginx层面统一管理，例如结合Certbot等工具。

本教程将展示如何利用Nginx为FastAPI后端和React前端配置SSL，并通过Docker Compose进行容器化部署。

2. Nginx配置详解

Nginx的核心作用是将外部的HTTPS请求转发到内部的HTTP服务。这需要配置upstream块定义后端服务，以及server块来监听HTTP和HTTPS端口。

2.1 Nginx Upstream配置

upstream块定义了一组后端服务器，Nginx会将请求代理到这些服务器。为了区分前端和后端服务，我们为它们分别定义了upstream。

# nginx.conf

events {
  worker_connections 1024; # 定义同时处理的最大连接数
}

http {
    # 后端服务（FastAPI）
    upstream back {
        # 注意：这里使用服务名作为主机名，Docker Compose会自动解析
        server back.mysite.ru:8000; 
    }

    # 前端服务（ReactJS）
    upstream front {
        # 注意：这里使用服务名作为主机名，Docker Compose会自动解析
        server mysite.ru:80;
    }

    # ... 其他server块配置 ...
}

在Docker Compose环境中，back.mysite.ru和mysite.ru通常对应于Docker Compose文件中定义的backend和frontend服务名称，或者你为它们在DNS中配置的子域名。8000和80是这些服务在容器内部监听的端口。

2.2 Nginx Server块配置

server块定义了Nginx如何处理特定域名或IP地址的请求。我们需要为每个服务（后端和前端）配置HTTP（端口80）和HTTPS（端口443）的server块。

HTTP到HTTPS的重定向（可选但推荐） 为了强制所有流量通过HTTPS，可以配置一个HTTP server块来将请求重定向到HTTPS。

# 后端服务的HTTP配置 (重定向到HTTPS)
server {
    listen 80;
    server_name back.mysite.ru;

    # 将所有HTTP请求永久重定向到HTTPS
    return 301 https://$host$request_uri;
}

# 前端服务的HTTP配置 (重定向到HTTPS)
server {
    listen 80;
    server_name mysite.ru;

    # 将所有HTTP请求永久重定向到HTTPS
    return 301 https://$host$request_uri;
}

HTTPS配置

HTTPS配置是核心部分，它涉及SSL证书的加载和请求的代理。

# 后端服务的HTTPS配置
server {
    listen 443 ssl; # 监听443端口，启用SSL
    server_name back.mysite.ru; # 对应的域名

    # SSL证书路径，这些证书通常由Certbot生成
    ssl_certificate /etc/letsencrypt/live/back.mysite.ru/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/back.mysite.ru/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/back.mysite.ru/chain.pem;

    location / {
        proxy_pass http://back; # 将请求代理到前面定义的upstream "back"
        proxy_set_header Host $host; # 转发原始Host头
        proxy_set_header X-Real-IP $remote_addr; # 转发客户端真实IP
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 转发代理链IP
        proxy_set_header X-Forwarded-Proto https; # 告知后端服务原始请求协议是HTTPS
    }
}

# 前端服务的HTTPS配置
server {
    listen 443 ssl;
    server_name mysite.ru;

    ssl_certificate /etc/letsencrypt/live/mysite.ru/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mysite.ru/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/mysite.ru/chain.pem;

    location / {
        proxy_pass http://front; # 代理到upstream "front"
        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 https;
    }
}

完整的nginx.conf示例：

events {
  worker_connections 1024;
}

http {

    # 后端服务
    upstream back {
        server backend:8000; # 使用Docker Compose服务名
    }

    # 前端服务
    upstream front {
        server frontend:80; # 使用Docker Compose服务名
    }

    # 后端 HTTP -> HTTPS 重定向
    server {
        listen 80;
        server_name back.mysite.ru;
        return 301 https://$host$request_uri;
    }

    # 后端 HTTPS 配置
    server {
        listen 443 ssl;
        server_name back.mysite.ru;

        ssl_certificate /etc/letsencrypt/live/back.mysite.ru/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/back.mysite.ru/privkey.pem;
        ssl_trusted_certificate /etc/letsencrypt/live/back.mysite.ru/chain.pem;

        location / {
            proxy_pass http://back;
            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 https;
        }
    }

    # 前端 HTTP -> HTTPS 重定向
    server {
        listen 80;
        server_name mysite.ru;
        return 301 https://$host$request_uri;
    }

    # 前端 HTTPS 配置
    server {
        listen 443 ssl;
        server_name mysite.ru;

        ssl_certificate /etc/letsencrypt/live/mysite.ru/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/mysite.ru/privkey.pem;
        ssl_trusted_certificate /etc/letsencrypt/live/mysite.ru/chain.pem;

        location / {
            proxy_pass http://front;
            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 https;
        }
    }
}

注意事项：

• server_name应设置为你的实际域名或子域名。
• ssl_certificate、ssl_certificate_key和ssl_trusted_certificate路径应指向你获取的SSL证书文件。通常，Certbot会将证书存放在/etc/letsencrypt/live/your_domain/目录下。
• proxy_set_header X-Forwarded-Proto https;非常重要，它告诉后端服务原始请求是通过HTTPS发起的，这对于后端处理CORS、重定向和生成URL等场景至关重要。

3. Docker Compose集成

为了将Nginx与FastAPI和React应用一起部署，我们需要更新docker-compose.yml文件。

3.1 Nginx Dockerfile

首先，创建一个简单的Nginx Dockerfile，用于构建Nginx镜像并加载自定义配置。

# ./nginx/Dockerfile
FROM nginx:stable-alpine # 基于轻量级Nginx镜像

COPY nginx.conf /etc/nginx/nginx.conf # 将自定义的nginx.conf复制到容器内

3.2 更新 Docker Compose 文件

在docker-compose.yml中添加Nginx服务，并确保它能访问证书文件和后端服务。

# docker-compose.yml
version: '3.7'
services:
  frontend:
    container_name: "frontend"
    build: 
      context: ./frontend
    stop_signal: SIGTERM
    ports:
      - "80:80" # 前端应用自身监听80端口
    volumes:
      - ./uploads:/app/uploads
    networks:
      - good_network
    depends_on:
      - backend

  backend:
    container_name: "backend"
    build:
      context: ./backend
    stop_signal: SIGTERM
    ports:
      - "8000:8000" # 后端应用自身监听8000端口
    networks:
      - good_network
    volumes:
      - ./uploads:/app/uploads
    depends_on:
      - postgres

  postgres:
    container_name: "postgres"
    image: postgres:16.0
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -d sugar -U postgres" ]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 5s
    restart: unless-stopped
    ports:
      - "5432:5432"
    volumes:
      - ./postgres_data:/var/lib/postgresql/data
    networks:
      - good_network

  nginx: # 新增Nginx服务
    build: ./nginx # 基于上面创建的Dockerfile构建
    ports:
      - "80:80"   # 映射宿主机的80端口到Nginx容器的80端口
      - "443:443" # 映射宿主机的443端口到Nginx容器的443端口
    volumes:
      # 挂载宿主机的Let's Encrypt证书目录，确保Nginx能访问证书文件
      - /etc/letsencrypt:/etc/letsencrypt:ro # 只读挂载
    depends_on:
      - frontend # 确保前端服务启动后Nginx再启动
      - backend  # 确保后端服务启动后Nginx再启动
    networks:
      - good_network # 与其他服务在同一网络

networks:
  good_network:

volumes:
  postgres_data:

关键点说明：

• nginx服务： 定义了一个新的服务，基于./nginx目录下的Dockerfile构建。
• ports： 将宿主机的80和443端口映射到Nginx容器的对应端口，这样外部流量就能通过这些端口访问Nginx。
• volumes： volumes: - /etc/letsencrypt:/etc/letsencrypt:ro 是非常关键的一步。它将宿主机上由Certbot生成的SSL证书目录挂载到Nginx容器内部的相同路径。:ro表示只读，增加了安全性。这意味着在宿主机上，你需要预先使用Certbot（或其他方式）获取并更新证书。
• depends_on： 确保frontend和backend服务在nginx服务启动之前已经运行。
• networks： Nginx服务必须与FastAPI和React服务在同一个Docker网络中（good_network），以便Nginx可以通过服务名称（如backend和frontend）访问它们。

4. 证书获取与管理

SSL证书通常通过Let's Encrypt和Certbot工具获取。在宿主机上运行Certbot，它会自动生成并放置证书文件在/etc/letsencrypt/live/your_domain/目录下。

Certbot安装与使用示例（宿主机操作）：

1. 安装Certbot：

   sudo snap install --classic certbot
   sudo ln -s /snap/bin/certbot /usr/bin/certbot

2. 获取证书（使用Nginx插件）： 如果Nginx已经在宿主机上运行并监听80端口，Certbot可以自动配置Nginx。

   sudo certbot --nginx -d mysite.ru -d back.mysite.ru

   如果Nginx在Docker容器中运行，或者你不想让Certbot自动修改Nginx配置，可以使用webroot或standalone模式。例如，使用webroot模式，你需要指定一个Web根目录让Certbot放置验证文件：

   sudo certbot certonly --webroot -w /path/to/your/frontend/static -d mysite.ru -d back.mysite.ru

   或者使用standalone模式（需要临时停止占用80/443端口的服务）：

   sudo certbot certonly --standalone -d mysite.ru -d back.mysite.ru

3. 自动续期： Certbot会自动设置一个定时任务来续期证书。

确保证书文件生成后，Nginx容器通过卷挂载能够访问到它们。

5. 总结与注意事项

通过Nginx作为反向代理，我们成功地为FastAPI后端和React前端应用配置了SSL加密，并利用Docker Compose实现了服务的容器化部署和管理。

总结：

• 架构清晰： Nginx负责外部流量和SSL，应用服务专注于业务逻辑。
• 安全性提升： 所有外部通信均通过HTTPS加密。
• 可扩展性： 易于添加更多后端服务或前端应用，只需修改Nginx配置。
• CORS处理： 由于Nginx代理了请求，如果前端和后端是不同域名或端口，仍然需要在FastAPI应用中配置CORS策略，允许来自前端域名的请求。

注意事项：

• 域名解析： 确保你的域名（mysite.ru和back.mysite.ru）已正确解析到你的服务器IP地址。
• 防火墙： 确保服务器的80和443端口对外开放。
• Certbot续期： 确认Certbot的自动续期机制正常工作，以避免证书过期。
• 日志监控： 配置Nginx和应用服务的日志，以便于问题排查。
• 生产环境： 在生产环境中，除了SSL配置，还应考虑其他安全加固措施，如更严格的Nginx安全配置、DDoS防护、WAF等。

通过上述步骤，你的FastAPI和React应用将能够通过安全的HTTPS连接进行通信，为用户提供更可靠的服务。