FastAPI配置SSL：Nginx反向代理教程

1. 背景与问题概述

在现代Web应用开发中，数据传输的安全性至关重要，HTTPS已成为标配。对于使用FastAPI构建后端API和React构建前端界面的应用，通常会将其容器化部署。直接在FastAPI（通过Uvicorn）中配置SSL证书虽然可行，但可能引入额外的复杂性，例如CORS（跨域资源共享）配置的挑战，以及在多服务架构中管理证书的繁琐。更常见的做法是利用Nginx作为反向代理，统一处理SSL加密和解密，并将未加密的HTTP请求转发给后端应用。

2. 解决方案：Nginx反向代理实现SSL终止

Nginx作为一款高性能的HTTP和反向代理服务器，是处理SSL终止的理想选择。其核心思想是：Nginx监听外部的HTTPS请求（端口443），使用配置好的SSL证书进行加密/解密，然后将解密后的HTTP请求转发给内部的FastAPI或React应用。这样，FastAPI和React应用本身无需关心SSL，只需监听HTTP端口。

优点：

• 简化应用配置： FastAPI应用只需运行在HTTP模式下，无需处理证书和HTTPS逻辑。
• 集中式SSL管理： 所有证书管理（获取、更新、部署）都在Nginx层面进行，便于统一维护。
• 性能优化： Nginx在处理静态文件和高并发连接方面表现优异，能有效卸载后端应用的压力。
• 灵活的路由： 可以根据域名、路径等灵活配置请求转发规则。

3. 前提条件

在开始配置之前，请确保您已具备以下条件：

• 一个或多个已注册的域名或子域名（例如 mysite.ru 和 back.mysite.ru）。
• 已安装Docker和Docker Compose。
• 已通过Certbot或其他方式获取了SSL证书文件（fullchain.pem、privkey.pem、chain.pem），并知道它们的存储路径（通常在 /etc/letsencrypt/live/your_domain/）。

4. 核心配置步骤

本教程将以一个包含FastAPI后端、React前端和PostgreSQL数据库的Docker Compose项目为例进行说明。

4.1 初始Docker Compose文件结构

假设您的项目结构如下，并且 docker-compose.yml 中已定义了后端、前端和数据库服务：

# docker-compose.yml (初始部分)
version: '3.7'
services:
  frontend:
    container_name: "frontend"
    build:
      context: ./frontend
    stop_signal: SIGTERM
    ports:
      - "80:80" # 前端应用内部监听80端口，外部也暴露80端口（将被Nginx代理）
    volumes:
      - ./uploads:/app/uploads
    networks:
      - good_network
    depends_on:
      - backend

  backend:
    container_name: "backend"
    build:
      context: ./backend
    stop_signal: SIGTERM
    ports:
      - "8000:8000" # 后端应用内部监听8000端口，外部也暴露8000端口（将被Nginx代理）
    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

networks:
  good_network:

volumes:
  postgres_data:

注意： 这里的 ports 配置是服务内部监听的端口，Nginx将通过内部网络访问这些端口。对于前端，我们让它监听80端口；对于后端，监听8000端口。

4.2 Nginx配置文件 (nginx.conf)

创建 nginx/nginx.conf 文件，用于配置Nginx的反向代理和SSL。我们将为前端和后端分别配置HTTP（端口80）和HTTPS（端口443）访问。

# nginx/nginx.conf
events {
  worker_connections 1024; # 定义Nginx worker进程可以同时处理的最大连接数
}

http {
    # 后端服务定义
    upstream back {
        # 'backend' 是docker-compose中后端服务的名称，Nginx将通过这个名称在内部网络中解析到后端容器
        # '8000' 是后端FastAPI应用监听的端口
        server backend:8000;
    }

    # 前端服务定义
    upstream front {
        # 'frontend' 是docker-compose中前端服务的名称
        # '80' 是前端React应用（例如由serve或类似的HTTP服务器提供）监听的端口
        server frontend:80;
    }

    # =======================================================
    # 后端API服务的Nginx配置 (back.mysite.ru)
    # =======================================================

    # HTTP (端口80) 配置 - 将所有HTTP请求重定向到HTTPS (可选，但推荐)
    server {
        listen 80;
        server_name back.mysite.ru; # 替换为你的后端子域名

        location / {
            # 将HTTP请求代理到后端服务
            proxy_pass http://back;
            # 设置必要的HTTP头，以便后端应用获取真实的客户端IP等信息
            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 http; # 原始协议是HTTP
            # 如果需要强制HTTPS重定向，可以添加：
            # return 301 https://$host$request_uri;
        }
    }

    # HTTPS (端口443) 配置 - 处理加密请求并转发到后端
    server {
        listen 443 ssl;
        server_name back.mysite.ru; # 替换为你的后端子域名

        # SSL证书路径，这些路径将通过Docker卷挂载到Nginx容器中
        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; # 信任链（可选，但推荐）

        # 推荐的SSL配置，增强安全性
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
        ssl_prefer_server_ciphers on;
        ssl_session_cache shared:SSL:10m;
        ssl_session_timeout 10m;
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; # HSTS

        location / {
            # 将HTTPS请求代理到后端服务
            proxy_pass http://back; # 注意这里依然是http://back，因为Nginx已经处理了SSL
            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; # 告诉后端原始协议是HTTPS
        }
    }

    # =======================================================
    # 前端Web服务的Nginx配置 (mysite.ru)
    # =======================================================

    # HTTP (端口80) 配置 - 将所有HTTP请求重定向到HTTPS
    server {
        listen 80;
        server_name mysite.ru; # 替换为你的主域名

        location / {
            # 强制重定向到HTTPS
            return 301 https://$host$request_uri;
            # 如果不重定向，直接代理：
            # 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 http;
        }
    }

    # HTTPS (端口443) 配置 - 处理加密请求并转发到前端
    server {
        listen 443 ssl;
        server_name mysite.ru; # 替换为你的主域名

        # SSL证书路径
        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;

        # 推荐的SSL配置
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
        ssl_prefer_server_ciphers on;
        ssl_session_cache shared:SSL:10m;
        ssl_session_timeout 10m;
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

        location / {
            # 将HTTPS请求代理到前端服务
            proxy_pass http://front; # 注意这里依然是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; # 告诉前端原始协议是HTTPS
        }
    }
}

4.3 Nginx Dockerfile (nginx/Dockerfile)

创建一个简单的 nginx/Dockerfile 来构建Nginx镜像，并将自定义的 nginx.conf 复制进去。

# nginx/Dockerfile
FROM nginx:latest # 基于官方Nginx镜像

# 将自定义的nginx.conf复制到容器的Nginx配置目录
COPY nginx.conf /etc/nginx/nginx.conf

4.4 更新Docker Compose文件

最后，将Nginx服务添加到您的 docker-compose.yml 文件中。

# docker-compose.yml (完整版)
version: '3.7'
services:
  frontend:
    container_name: "frontend"
    build:
      context: ./frontend
    stop_signal: SIGTERM
    # 注意：这里不再直接暴露80端口到宿主机，而是通过Nginx代理
    # ports:
    #   - "80:80"
    volumes:
      - ./uploads:/app/uploads
    networks:
      - good_network
    depends_on:
      - backend

  backend:
    container_name: "backend"
    build:
      context: ./backend
    stop_signal: SIGTERM
    # 注意：这里不再直接暴露8000端口到宿主机，而是通过Nginx代理
    # ports:
    #   - "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 # 指定Nginx Dockerfile的构建上下文
    ports:
      - "80:80"   # Nginx监听宿主机的80端口
      - "443:443" # Nginx监听宿主机的443端口，用于HTTPS
    volumes:
      # 挂载宿主机的Certbot证书目录到Nginx容器内部，以便Nginx能访问证书文件
      - /etc/letsencrypt:/etc/letsencrypt:ro # 只读挂载
    networks:
      - good_network
    depends_on: # 确保Nginx在前端和后端服务启动后再启动
      - frontend
      - backend

networks:
  good_network:

volumes:
  postgres_data:

重要说明：

• 在Nginx服务中，ports: - "443:443" 将宿主机的443端口映射到Nginx容器的443端口，使得外部请求可以通过HTTPS访问。
• volumes: - /etc/letsencrypt:/etc/letsencrypt:ro 是关键一步，它将您的Certbot证书目录（通常位于 /etc/letsencrypt）以只读方式挂载到Nginx容器内部的相同路径，确保Nginx可以找到并使用证书。请确保您的宿主机上已通过Certbot获取了相应的证书。
• depends_on: - frontend - backend 确保Nginx服务在前端和后端服务启动并可用之后才启动，避免Nginx尝试代理一个尚未运行的服务。

5. 启动与测试

完成上述配置后，在项目根目录运行：

docker-compose up --build -d

这将构建并启动所有服务。之后，您应该能够通过 https://mysite.ru 访问您的前端应用，并通过 https://back.mysite.ru 访问您的FastAPI后端API。

6. 注意事项与最佳实践

• DNS解析： 确保您的域名 mysite.ru 和子域名 back.mysite.ru 都已正确配置DNS A记录，指向您的服务器IP地址。

• 防火墙： 确保服务器的防火墙（如ufw或firewalld）允许80和443端口的入站连接。

• CORS配置： 由于Nginx处理了SSL，FastAPI应用接收到的请求是HTTP。如果您的FastAPI应用需要处理CORS，请确保在FastAPI应用中配置CORS中间件，允许来自您前端域名的请求。例如：

  # main.py (FastAPI CORS配置示例)
  from fastapi import FastAPI
  from fastapi.middleware.cors import CORSMiddleware
  
  app = FastAPI()
  
  origins = [
      "http://localhost", # 开发环境
      "http://localhost:3000", # 开发环境
      "https://mysite.ru", # 您的前端域名
      # 如果需要，可以添加更多允许的源
  ]
  
  app.add_middleware(
      CORSMiddleware,
      allow_origins=origins,
      allow_credentials=True,
      allow_methods=["*"],
      allow_headers=["*"],
  )
  
  @app.get("/")
  async def read_root():
      return {"message": "Hello from FastAPI backend!"}

• 证书自动续期： Certbot通常会设置cron作业或systemd timer来自动续期证书。确保此机制在您的宿主机上正常工作，以避免证书过期导致服务中断。

• 日志： 监控Nginx和应用容器的日志，以便及时发现和解决问题。

• 安全性： Nginx配置中的 ssl_protocols 和 ssl_ciphers 示例提供了较强的安全配置，您可以根据最新的安全建议进行调整。Strict-Transport-Security (HSTS) 头强制浏览器只通过HTTPS访问您的站点，进一步增强安全性。

7. 总结

通过将Nginx作为反向代理，我们成功地为FastAPI后端和React前端应用实现了SSL加密。这种架构不仅简化了应用层面的SSL管理，还提供了更高的性能、更好的可扩展性和更灵活的配置。遵循本教程的步骤，您可以在Docker容器化环境中安全、高效地部署您的Web应用。