Apex/Up项目配置详解：从基础到高级配置指南

Apex/Up项目配置详解：从基础到高级配置指南

up Deploy infinitely scalable serverless apps, apis, and sites in seconds to AWS. 项目地址: https://gitcode.com/gh_mirrors/up/up

项目概述

Apex/Up是一个强大的无服务器部署工具，它简化了在AWS Lambda上部署应用程序的过程。通过up.json配置文件，开发者可以轻松定义应用程序的各种行为和特性。本文将全面解析up.json中的各项配置，帮助您更好地掌握Apex/Up的使用。

基础配置

应用名称配置

name字段是配置中最基本的元素，它定义了您的应用程序名称，并用于命名AWS资源如Lambda函数和API Gateway。

{
  "name": "my-awesome-app"
}

建议使用简洁、有意义的名称，避免特殊字符和空格，因为这将成为AWS资源名称的一部分。

AWS凭证配置

profile属性允许您指定AWS凭证配置文件，这比使用环境变量更安全可靠。

{
  "profile": "production-credentials"
}

这个配置对应于~/.aws/credentials文件中的配置节，避免了直接在配置文件中存储敏感信息。

区域部署配置

单区域部署

默认情况下，Apex/Up使用"us-west-2"（美国西部俄勒冈）区域，除非设置了AWS_REGION环境变量。您可以通过regions数组明确指定部署区域。

{
  "regions": ["ap-northeast-1"]
}

支持的区域列表

当前Apex/Up支持以下AWS区域：

• 北美地区：

  • us-east-2 (俄亥俄)
  • us-east-1 (弗吉尼亚北部)
  • us-west-1 (加利福尼亚北部)
  • us-west-2 (俄勒冈)
  • ca-central-1 (加拿大中部)

• 亚太地区：

  • ap-northeast-2 (首尔)
  • ap-south-1 (孟买)
  • ap-southeast-1 (新加坡)
  • ap-southeast-2 (悉尼)
  • ap-northeast-1 (东京)

• 欧洲地区：

  • eu-central-1 (法兰克福)
  • eu-west-1 (爱尔兰)
  • eu-west-2 (伦敦)
  • eu-west-3 (巴黎)
  • eu-north-1 (斯德哥尔摩)

• 南美地区：

  • sa-east-1 (圣保罗)

Lambda函数配置

基础参数配置

Lambda配置提供了对函数行为的精细控制：

{
  "lambda": {
    "memory": 1024,
    "runtime": "nodejs12.x",
    "timeout": 30
  }
}

• memory: 内存大小(MB)，范围128-3008，同时影响CPU分配
• runtime: 运行时环境，如nodejs12.x、python3.8等
• timeout: 函数超时时间(秒)，最大900

VPC网络配置

要在VPC中运行Lambda函数，需要配置子网和安全组：

{
  "lambda": {
    "vpc": {
      "subnets": ["subnet-aaaaaaa", "subnet-bbbbbbb"],
      "security_groups": ["sg-xxxxxxx"]
    }
  }
}

注意：在VPC中使用Up Pro需要访问AWS SSM参数存储API，否则可能导致环境变量加载超时。

IAM权限策略

通过policy数组可以添加自定义IAM权限：

{
  "lambda": {
    "policy": [
      {
        "Effect": "Allow",
        "Resource": "*",
        "Action": [
          "dynamodb:Get*",
          "dynamodb:PutItem"
        ]
      }
    ]
  }
}

这允许您精细控制Lambda函数对AWS服务的访问权限。

构建与部署钩子

Apex/Up提供了多种钩子脚本，用于自动化构建和部署流程：

{
  "hooks": {
    "prebuild": "npm install",
    "build": "webpack --mode production",
    "postbuild": "npm test",
    "clean": "rm -rf dist"
  }
}

钩子执行顺序：

1. prebuild → build → postbuild → 部署 → clean

静态文件服务

纯静态网站

对于纯静态网站，设置type为"static"：

{
  "type": "static",
  "static": {
    "dir": "public",
    "prefix": "/assets/"
  }
}

• dir: 静态文件根目录
• prefix: URL前缀，避免路由冲突

动态应用中的静态文件

动态应用也可以提供静态文件服务：

{
  "static": {
    "dir": "public"
  }
}

注意：静态文件大小限制为6MB（Lambda限制）。

环境管理

环境变量配置

{
  "environment": {
    "NODE_ENV": "production",
    "API_KEY": "non-secret-value"
  }
}

重要提示：不要在up.json中存储敏感信息，这些配置通常会被提交到版本控制系统。

HTTP头管理

可以基于路径模式注入自定义HTTP头：

{
  "headers": {
    "/*": {
      "X-Frame-Options": "DENY",
      "Content-Security-Policy": "default-src 'self'"
    },
    "/*.css": {
      "Cache-Control": "max-age=31536000"
    }
  }
}

错误页面定制

提供自定义错误页面提升用户体验：

{
  "error_pages": {
    "enable": true,
    "dir": "errors",
    "variables": {
      "support_email": "help@example.com",
      "brand_color": "#4a90e2"
    }
  }
}

支持按状态码（404.html）或类别（4xx.html）定制模板。

脚本注入

在HTML中自动注入脚本、样式等：

{
  "inject": {
    "head": [
      {
        "type": "google analytics",
        "value": "UA-XXXXX-Y"
      }
    ],
    "body": [
      {
        "type": "script",
        "value": "/app.js"
      }
    ]
  }
}

支持多种注入类型，包括内联脚本和外部资源。

重定向与URL重写

{
  "redirects": {
    "/old": {
      "location": "/new",
      "status": 301
    },
    "/blog/*": {
      "location": "/posts/:splat"
    }
  }
}

• status 301/302为重定向，200为URL重写
• 支持通配符(*)和命名参数(:splat)

CORS配置

跨域资源共享配置：

{
  "cors": {
    "enable": true,
    "allowed_origins": ["https://example.com"],
    "allowed_methods": ["GET", "POST", "PUT"],
    "allow_credentials": true
  }
}

代理与超时设置

{
  "proxy": {
    "command": "node server.js",
    "timeout": 20,
    "listen_timeout": 10
  }
}

• timeout: 请求超时时间
• listen_timeout: 应用启动超时时间

DNS管理

直接在配置中管理DNS记录：

{
  "dns": {
    "example.com": [
      {
        "name": "api.example.com",
        "type": "A",
        "value": ["192.0.2.1"]
      }
    ]
  }
}

多环境（Stage）管理

{
  "stages": {
    "production": {
      "lambda": {
        "memory": 1024
      }
    },
    "staging": {
      "lambda": {
        "memory": 512
      }
    }
  }
}

通过up deploy staging或up deploy production部署到不同环境。

最佳实践建议

1. 安全性：永远不要在up.json中存储敏感信息，使用AWS参数存储或密钥管理服务
2. 性能优化：根据应用需求调整Lambda内存大小，内存越大CPU资源越多
3. 版本控制：将up.json纳入版本控制，但确保排除敏感数据
4. 渐进式配置：从简单配置开始，逐步添加复杂功能
5. 环境分离：利用stage功能严格分离开发、测试和生产环境

通过合理配置up.json，您可以充分发挥Apex/Up的强大功能，构建高效、可靠的无服务器应用。

up Deploy infinitely scalable serverless apps, apis, and sites in seconds to AWS. 项目地址: https://gitcode.com/gh_mirrors/up/up