AWS Lambda Web Adapter

在 AWS Lambda 上运行 Web 应用程序的工具

AWS Lambda Web Adapter 允许开发者使用熟悉的框架（例如 Express.js、Next.js、Flask、SpringBoot、ASP.NET 和 Laravel，任何支持 HTTP 1.1/1.0）构建 Web 应用（http api），并在 AWS Lambda 上运行。相同的 Docker 镜像可以在 AWS Lambda、Amazon EC2、AWS Fargate 和本地计算机上运行。

功能

• 在 AWS Lambda 上运行 Web 应用程序
• 支持 Amazon API Gateway Rest API 和 Http API 端点、Lambda 函数 URL 和应用程序负载均衡器
• 支持 Lambda 管理的运行时、自定义运行时和 docker OCI 镜像
• 支持任何 Web 框架和语言，无需包含新的代码依赖
• 自动编码二进制响应
• 启用优雅关闭
• 支持响应负载压缩
• 支持响应流式传输
• 支持非 HTTP 事件触发器

用法

AWS Lambda Web Adapter 与作为 Docker 镜像和 Zip 打包的 Lambda 函数一起工作。

作为 Docker 镜像或 OCI 镜像打包的 Lambda 函数

要使用 Docker 镜像与 Lambda Web Adapter 一起使用，请将您的 Web 应用程序（http api）打包在一个 Dockerfile 中，并在容器内部将 Lambda Web Adapter 二进制文件复制到 /opt/extensions 中。默认情况下，Lambda Web Adapter 假设 Web 应用程序正在监听端口 8080。如果不是，您可以通过 配置 指定端口。

COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.7.2 /lambda-adapter /opt/extensions/lambda-adapter

预编译的 Lambda Web Adapter 二进制文件提供在 ECR 公共仓库中：public.ecr.aws/awsguru/aws-lambda-adapter。此仓库还提供了多架构镜像。它适用于 x86_64 和 arm64 CPU 架构。

下面是 一个示例 Node.js 应用程序 的 Dockerfile。

FROM public.ecr.aws/docker/library/node:20-slim
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.7.2 /lambda-adapter /opt/extensions/lambda-adapter
ENV PORT=7000
WORKDIR "/var/task"
ADD src/package.json /var/task/package.json
ADD src/package-lock.json /var/task/package-lock.json
RUN npm install --omit=dev
ADD src/ /var/task
CMD ["node", "index.js"]

本功能适用于任何基础镜像，除了AWS管理的基础镜像。要使用AWS管理的基础镜像，您需要覆盖ENTRYPOINT以启动您的Web应用。

为AWS管理运行时打包的Lambda函数作为Zip包

AWS Lambda Web适配器也适用于AWS管理的Lambda运行时。您需要做三件事

1. 将Lambda Web适配器层附加到您的函数上。

   AWS商业区域

   1. x86_64: arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerX86:18
   2. arm64: arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerArm64:18

   AWS中国区域

   1. cn-north-1 (北京)
      • x86_64: arn:aws-cn:lambda:cn-north-1:041581134020:layer:LambdaAdapterLayerX86:18
   2. cn-northwest-1 (宁夏)
      • x86_64: arn:aws-cn:lambda:cn-northwest-1:069767869989:layer:LambdaAdapterLayerX86:18

2. 配置Lambda环境变量 AWS_LAMBDA_EXEC_WRAPPER 为 /opt/bootstrap。

3. 将函数处理程序设置为您的Web应用启动脚本。例如 run.sh。

有关详细信息，请查看示例Node.js应用程序。

要了解有关新层的通知，请订阅以下SNS主题：arn:aws:sns:us-east-1:753240598075:notification。有关如何订阅的指导，请参阅SNS文档。

就绪检查

当新的Lambda执行环境启动时，Lambda Web适配器将作为Lambda扩展启动，然后是Web应用。

默认情况下，Lambda Web适配器将向位于 http://127.0.0.1:8080/ 的Web应用发送HTTP GET请求。端口和路径可以使用两个环境变量进行自定义： AWS_LWA_READINESS_CHECK_PORT 和 AWS_LWA_READINESS_CHECK_PATH。

Lambda Web适配器将每10毫秒重试此请求，直到Web应用返回HTTP响应（状态码 >= 100 且 < 500）或函数超时。

此外，您可以通过设置 AWS_LWA_READINESS_CHECK_PROTOCOL 为 tcp 来配置适配器，使其使用 TCP 连接进行就绪检查。

通过就绪检查后，Lambda Web 适配器将启动 Lambda 运行时并将调用转发到 Web 应用程序。

配置

就绪检查端口/路径和流量端口可以使用环境变量进行配置。这些环境变量可以在 Docker 文件内定义，也可以作为 Lambda 函数配置。

注意： 我们使用 "AWS_LWA_" 前缀来命名空间 Lambda Web 适配器使用的所有环境变量。原始变量将得到支持，直到我们达到 1.0 版本。

AWS_LWA_PORT / PORT - Lambda Web 适配器将向此端口发送流量。这是您的 Web 应用程序监听的端口。在 Lambda 执行环境中，Web 应用程序以非 root 用户身份运行，不允许监听低于 1024 的端口。请也避免使用端口 9001 和 3000。Lambda 运行时 API 在端口 9001 上。CloudWatch Lambda Insight 扩展使用端口 3000。

AWS_LWA_ASYNC_INIT / ASYNC_INIT - Lambda 管理运行时为函数初始化提供最多 10 秒的时间。在这段时间内，Lambda 函数有 CPU 峰值以加速初始化，这是免费的。如果 Lambda 函数在 10 秒内无法完成初始化，Lambda 将重新启动函数，并为此初始化收费。为了帮助函数使用这 10 秒的免费初始化时间并避免重启，Lambda Web 适配器支持异步初始化。当此功能启用时，Lambda Web 适配器进行最多 9.8 秒的就绪检查。如果那时 Web 应用程序尚未就绪，Lambda Web 适配器将向 Lambda 服务发出信号，表示初始化已完成，并在处理程序中继续就绪检查。默认情况下，此功能是禁用的。通过将环境变量 AWS_LWA_ASYNC_INIT 设置为 true 来启用它。

AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH - 此环境变量的值告诉适配器应用程序是否在基本路径下运行。例如，您可能已配置 API Gateway 以具有 /orders/{proxy+} 和 /catalog/{proxy+} 资源。每个资源由单独的 Lambda 函数处理。因此，Lambda 内部的应用程序可能不知道 /orders 路径存在。使用 REMOVE_BASE_PATH 在将请求路由到应用程序时删除 /orders 前缀。默认为空字符串。查看 SpringBoot 示例。

AWS_LWA_ENABLE_COMPRESSION - Lambda Web Adapter支持对响应体的gzip压缩。默认情况下此功能是禁用的。通过设置环境变量AWS_LWA_ENABLE_COMPRESSION为true来启用它。启用后，除非响应是以image开头的MIME类型或响应小于32字节（由内容类型确定），否则将压缩响应。这也会压缩HTTP/1.1分块流响应。

AWS_LWA_INVOKE_MODE - Lambda函数调用模式，这应该与函数URL调用模式匹配。默认是"buffered"。当配置为"response_stream"时，Lambda Web Adapter将响应流式传输到Lambda服务博客。请查看FastAPI与响应流示例。

AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS - 允许您自定义哪些HTTP状态码被认为是健康的，哪些不是

AWS_LWA_PASS_THROUGH_PATH - 接收从非HTTP事件触发器传递过来的事件负载的路径。默认是"/events"。

请求上下文

请求上下文是API Gateway在请求中发送给Lambda的元数据。它通常包含requestId、requestTime、apiId、identity和authorizer。Identity和authorizer对获取客户端身份进行授权很有用。API Gateway开发者指南中包含更多详细信息这里。

Lambda Web Adapter将此信息转发到名为"x-amzn-request-context"的Http Header中，供Web应用程序使用。在Web应用程序中，您可以检索此Http Header的值并将其反序列化为JSON对象。请查看Express.js in Zip以了解如何使用它。

Lambda上下文

Lambda上下文是一个Lambda传递给函数处理器的对象。该对象提供了有关调用、函数和执行环境的信息。您可以在这里找到可以通过Lambda上下文访问的完整属性列表。

Lambda Web Adapter将此信息转发到名为"x-amzn-lambda-context"的Http Header中，供Web应用程序使用。在Web应用程序中，您可以检索此Http Header的值并将其反序列化为JSON对象。请查看Express.js in Zip以了解如何使用它。

优雅关闭

对于已注册Lambda扩展的函数，Lambda为函数启用关闭阶段。当Lambda服务即将关闭Lambda执行环境时，它向运行时发送SIGTERM信号，然后向每个注册的外部扩展发送SHUTDOWN事件。开发人员可以在lambda函数中捕获SIGTERM信号并执行优雅关闭任务。《Express.js》提供了一个简单的示例。更多详细信息请查看此存储库。

本地调试

Lambda Web Adapter允许开发人员使用熟悉的工具和调试器在本地开发Web应用程序：只需在本地运行Web应用程序并对其进行测试即可。如果您想在本地模拟Lambda运行时环境，可以使用AWS SAM CLI。以下命令启动一个本地的API网关端点并模拟Lambda运行时执行环境。

sam local start-api

请注意，sam local 在端口 8080 上启动 Lambda 运行时接口模拟器。因此，如果您打算使用 sam local，您的 Web 应用程序应避免使用端口 8080。

非 HTTP 事件触发器

Lambda Web 适配器也支持所有非 HTTP 事件触发器，例如 SQS、SNS、S3、DynamoDB、Kinesis、Kafka、EventBridge 和 Bedrock Agents。适配器通过将事件有效负载转发到由 AWS_LWA_PASS_THROUGH_PATH 环境变量定义的路径的 http post，将事件有效负载发送到 Web 应用程序。默认情况下，此路径设置为 /events。当从请求体中接收到事件有效负载时，Web 应用程序应处理它并以 JSON 响应返回结果。请参考 SQS Express.js 了解如何使用它。

示例

• FastAPI
• 打包的 FastAPI
• 带有响应流式的 FastAPI
• 打包的带有响应流式的 FastAPI
• Flask
• 打包的 Flask
• Serverless Django by @efi-mk
• Express.js
• 打包的 Express.js
• Next.js
• 打包的 Next.js
• 带有响应流式的 Next.js
• SpringBoot
• 打包的 SpringBoot
• 带有响应流式的 SpringBoot
• Nginx
• PHP
• 打包的 Rust Actix Web
• 打包的 Rust Axum
• Golang Gin
• 打包的 Golang Gin
• 打包的 Deno Oak
• Lambda 上的 Laravel
• ASP.NET MVC
• 打包的 ASP.NET MVC
• 打包的 ASP.NET Web API
• SQS Express.js

致谢

本项目受到多个社区项目的启发。

• re:Web
• Serverlessish

类似项目

一些项目也提供了与特定语言包/框架类似的功能。

• Serverless Java Container
• Serverless Express
• Serverless Python - Zappa
• Serverless Rails - Lamby
• Serverless PHP - Bref

安全

有关更多信息，请参阅 CONTRIBUTING。

许可证

本项目采用 Apache-2.0 许可证。