在Amazon ECS和Fargate添加Header API Key后IP链路异常求助

问题回顾 #

在Amazon ECS Fargate上部署FastAPI服务，未启用API Key验证时运行正常；添加请求Header携带API Key的验证逻辑后，出现以下异常：

1. 首次调用/test_api_key端点返回正常JSON，第二次调用报错，第三次请求长时间无响应，CloudWatch无有效日志
2. 关闭标签页重新打开外部IP链接，页面长时间加载无法显示API文档，CloudWatch无请求状态日志

可能原因分析 #

1. API Key验证逻辑的资源阻塞/重复加载 #

如果API Key的验证依赖项中存在重复加载.env文件、阻塞IO操作（比如每次请求都读取文件或调用外部服务），会导致请求处理线程被占用，后续请求堆积阻塞。比如在依赖函数内每次调用load_dotenv()，会重复读取文件，高并发下直接卡住进程。

2. S3加载.env的时机错误 #

如果是在FastAPI运行时（而非容器启动阶段）从S3拉取.env文件，会导致每次请求都发起S3网络请求：

• 网络延迟或S3限流会阻塞请求处理
• 若S3权限配置有问题，可能出现间歇性加载失败，导致验证逻辑异常

3. 容器资源不足或Uvicorn配置不合理 #

Fargate任务分配的CPU/内存资源过少，或Uvicorn的worker数量、连接超时参数配置不当，会导致：

• 并发请求时进程无法及时处理，请求堆积无响应
• 进程因资源耗尽挂起，无法输出日志到CloudWatch

4. 未捕获异常与日志采集配置缺失 #

FastAPI的API Key验证逻辑中存在未捕获的异常，导致请求处理崩溃，但容器的stdout/stderr未正确配置到CloudWatch，无法捕获错误日志；或日志输出未强制刷新，导致日志滞留在内存中无法上传。

对应解决方案 #

1. 优化API Key验证逻辑 #

将.env文件的加载移到应用启动阶段，避免每次请求重复加载：

# 放在文件开头，启动时仅加载一次
from dotenv import load_dotenv
load_dotenv()
import os

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import APIKeyHeader

api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)

async def get_api_key(api_key_header: str = Depends(api_key_header)):
    if api_key_header != os.getenv("API_KEY"):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid or missing API Key",
        )
    return api_key_header

2. 调整.env加载时机到容器启动阶段 #

修改ECS任务定义的启动命令，先从S3下载.env再启动FastAPI：

# 示例启动命令（可在任务定义的command字段配置）
aws s3 cp s3://your-bucket-path/.env ./ && uvicorn main:app --host 0.0.0.0 --port 8000 --workers 2

确保ECS任务的IAM角色拥有S3桶的GetObject权限，避免下载失败。

3. 调整容器资源与Uvicorn配置 #

• 临时调高Fargate任务的CPU/内存配置（比如1vCPU + 2GB内存），测试是否因资源不足导致问题
• 优化Uvicorn启动参数，增加worker数量并调整连接超时：

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 2 --timeout-keep-alive 60 --log-level info

（worker数量建议设置为CPU核心数的2倍，--log-level info确保输出更多运行日志）

4. 完善异常捕获与日志配置 #

• 添加全局异常捕获处理器，确保未捕获的异常能输出到stdout：

from fastapi import Request, status
from fastapi.responses import JSONResponse

@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    # flush=True强制立即输出日志，避免滞留在内存
    print(f"Unhandled exception at {request.url}: {str(exc)}", flush=True)
    return JSONResponse(
        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
        content={"detail": "Internal server error"},
    )

• 检查ECS任务定义的日志配置：确保日志驱动为awslogs，配置正确的日志组，且任务IAM角色拥有CloudWatch Logs的写入权限。

内容的提问来源于stack exchange，提问作者curiouz