SQLAdmin 在 AWS ECS 负载均衡环境下 HTTPS 静态文件加载问题解决方案

在使用 SQLAdmin 项目部署到 AWS ECS 服务并通过负载均衡器(ALB)提供 HTTPS 访问时，许多开发者遇到了静态资源加载问题。本文将深入分析问题原因并提供完整的解决方案。

问题现象

当 SQLAdmin 应用部署在 AWS ECS 环境中，并通过 Application Load Balancer (ALB) 提供 HTTPS 访问时，前端页面会出现静态资源(CSS/JS等)加载失败的情况。具体表现为浏览器控制台报 CORS 错误，原因是静态资源尝试通过 HTTP 协议加载，而主页面是通过 HTTPS 协议加载的。

问题根源

这个问题本质上是一个反向代理环境下的协议识别问题。在 AWS 的典型架构中：

1. 用户通过 HTTPS 访问 ALB
2. ALB 解密 HTTPS 流量后，通过 HTTP 协议将请求转发给 ECS 容器
3. ECS 容器中运行的 Uvicorn 服务器默认情况下无法感知原始请求是通过 HTTPS 访问的

因此，当 SQLAdmin 生成静态资源 URL 时，错误地使用了 HTTP 协议而非 HTTPS。

解决方案

方案一：直接修改 Uvicorn 启动参数

在 Dockerfile 或 ECS 任务定义中，修改 Uvicorn 的启动命令，添加代理相关参数：

CMD ["uvicorn", "rest_api.api:app", "--host", "0.0.0.0", "--port", "8000", "--forwarded-allow-ips", "*", "--proxy-headers"]

关键点：

• --forwarded-allow-ips "*" 允许接收来自任何 IP 的代理头信息
• --proxy-headers 启用代理头处理
• 注意 * 不需要加引号

方案二：使用 Gunicorn + Uvicorn Worker

对于生产环境，推荐使用 Gunicorn 作为进程管理器配合 Uvicorn Worker：

# 自定义 Uvicorn Worker
from uvicorn.workers import UvicornWorker

class CustomUvicornWorker(UvicornWorker):
    CONFIG_KWARGS = {
        "proxy_headers": True,
        "forwarded_allow_ips": "*"
    }

然后在启动命令中：

CMD ["gunicorn", "app.main:app", "--workers=4", "--worker-class=app.uvicorn_worker.CustomUvicornWorker", "--bind=0.0.0.0:8000"]

原理分析

这两种方案的核心都是让 Uvicorn 正确处理 X-Forwarded-* 头部信息。AWS ALB 会自动添加这些头部，包括：

• X-Forwarded-Proto: 标识原始请求协议(https)
• X-Forwarded-For: 客户端原始 IP
• X-Forwarded-Port: 原始请求端口

通过正确配置 Uvicorn 的代理设置，应用可以识别出原始请求是通过 HTTPS 访问的，从而生成正确的静态资源 URL。

生产环境建议

1. 对于高可用场景，推荐使用方案二(Gunicorn + Uvicorn Worker)
2. 确保 ALB 的安全组设置允许来自互联网的 HTTPS 流量(443端口)
3. 在 ALB 监听器设置中，配置正确的 SSL 证书(可通过 ACM 获取)
4. 监控 ALB 和 ECS 的健康检查状态

通过以上配置，SQLAdmin 应用可以在 AWS ECS + ALB 环境下完美支持 HTTPS 访问，静态资源加载问题将得到彻底解决。