Ruby Serverless Runtime 镜像文档

1. 镜像概述和主要用途

Ruby Serverless Runtime 是一个专为 Ruby 应用设计的轻量级 Serverless 运行时环境。该镜像提供了 Ruby 代码在无服务器架构（Serverless）中执行所需的完整运行时支持，包括函数加载、事件处理、资源管理等核心能力。主要用途是作为 Ruby 语言 Serverless 函数（如 AWS Lambda、Azure Functions、Google Cloud Functions 等）的本地开发、测试及部署载体，简化 Serverless 应用的开发与运维流程。

2. 核心功能和特性

2.1 运行时支持

• 多 Ruby 版本兼容：支持 Ruby 2.7+ 主流版本（默认 3.2，可通过环境变量指定）。
• 轻量级设计：基于 Alpine Linux 构建，镜像体积小（约 200MB），启动速度快（冷启动时间 < 500ms）。

2.2 Serverless 功能集成

• 函数生命周期管理：自动加载函数代码、解析事件输入、执行 handler 方法并返回结果。
• 事件模型兼容：支持主流 Serverless 平台的事件格式（如 AWS Lambda 事件结构、HTTP 触发器请求格式）。
• 上下文与资源访问：内置 Serverless 上下文对象（含请求 ID、超时时间、环境信息等），支持云服务资源（如 S3、DynamoDB）访问。

2.3 开发与调试支持

• 热重载：开发模式下支持代码变更自动重载（无需重启容器）。
• 日志与监控：集成标准输出日志（JSON 格式），支持日志级别（DEBUG/INFO/WARN/ERROR）控制，兼容 CloudWatch、Stackdriver 等监控平台。
• 依赖管理：自动解析项目 Gemfile 并安装依赖（支持 bundle install 自动执行）。

3. 使用场景和适用范围

3.1 开发与测试

• 本地开发 Ruby Serverless 函数，模拟云端运行环境。
• 快速验证函数逻辑、事件处理及依赖兼容性。

3.2 云原生应用组件

• 作为微服务架构中的无状态函数组件，处理异步任务（如数据清洗、消息推送）或同步请求（如 API 接口）。

3.3 CI/CD 流程集成

• 在 CI/CD 管道中作为测试环境，自动执行函数单元测试、集成测试。

3.4 多平台兼容部署

• 统一本地开发与云端部署环境，减少“本地正常、云端异常”问题，支持跨平台（AWS/Azure/GCP）Serverless 应用移植。

4. 使用方法和配置说明

4.1 获取镜像

通过 Docker Hub 或私有仓库拉取镜像：

bash
docker pull ruby-serverless-runtime:latest  # 最新版本（默认 Ruby 3.2）
# 或指定 Ruby 版本（如 3.0）
docker pull ruby-serverless-runtime:3.0

4.2 基本使用（docker run 命令）

4.2.1 本地函数执行示例

假设本地函数代码目录为 ./my-ruby-function，结构如下：

my-ruby-function/
├── Gemfile          # 依赖定义
└── handler.rb       # 函数代码，含入口方法 `handler`

handler.rb 示例代码：

ruby
def handler(event:, context:)
  { statusCode: 200, body: "Hello from Ruby Serverless! Event: #{event.inspect}" }
end

启动容器执行函数：

bash
docker run -it --rm \
  -v $(pwd)/my-ruby-function:/task \  # 挂载本地代码到容器内 /task 目录
  -e FUNCTION_HANDLER=handler.handler \  # 指定函数入口（文件名.方法名）
  -e RUBY_VERSION=3.2 \  # 可选，指定 Ruby 版本（默认 3.2）
  -e LOG_LEVEL=INFO \  # 日志级别（默认 INFO）
  ruby-serverless-runtime:latest

4.2.2 HTTP 触发器模式

通过环境变量 TRIGGER=HTTP 启用 HTTP 触发器，暴露端口 8080 接收 HTTP 请求：

bash
docker run -it --rm \
  -v $(pwd)/my-ruby-function:/task \
  -e FUNCTION_HANDLER=handler.handler \
  -e TRIGGER=HTTP \
  -p 8080:8080 \  # 映射容器 8080 端口到本地
  ruby-serverless-runtime:latest

启动后可通过 curl http://localhost:8080 触发函数。

4.3 Docker Compose 配置示例

创建 docker-compose.yml：

yaml
version: '3.8'
services:
  ruby-serverless:
    image: ruby-serverless-runtime:3.2
    volumes:
      - ./my-ruby-function:/task  # 挂载本地代码
    environment:
      - FUNCTION_HANDLER=handler.handler  # 函数入口
      - TRIGGER=HTTP  # 启用 HTTP 触发器
      - LOG_LEVEL=DEBUG  # 调试模式日志
      - RUBYOPT=-W0  # Ruby 运行参数（禁用警告）
    ports:
      - "8080:8080"  # HTTP 端口映射
    restart: unless-stopped  # 开发环境自动重启

启动服务：

bash
docker-compose up -d

4.4 配置参数说明

4.4.1 核心环境变量

4.4.2 卷挂载

• 代码目录：推荐挂载本地函数代码到容器 /task 目录（运行时自动加载该目录下代码）。
• 依赖缓存：可选挂载 /.bundle 目录到本地（缓存 bundle install 结果，加速启动）：

  bash
  docker run -v $(pwd)/.bundle:/.bundle ...
  

4.4.3 网络配置

• HTTP 触发器需映射容器 8080 端口（如 -p 8080:8080）。
• 如需访问外部服务（如数据库），可通过 --network 加入现有网络：

  bash
  docker run --network my-network ...  # 加入名为 my-network 的网络
  

5. 注意事项

• 版本选择：生产环境建议使用具体版本标签（如 3.2.2），而非 latest，避免版本变更风险。
• 依赖管理：Gemfile 变更后需重启容器（开发模式下可启用 BUNDLE_AUTO_UPDATE=true 自动更新依赖）。
• 资源限制：本地测试时可通过 --memory 和 --cpus 限制资源（模拟云端函数资源配额）：

  bash
  docker run --memory=128m --cpus=0.5 ...  # 限制 128MB 内存、0.5 CPU 核心