# @flagsmith/serverless-plugin-canary-deployments 中文文档

规范地址：https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/

版本：2\.0\.1
npm 元数据更新时间：2026-09-29T08:41:07.368Z
中文译文更新时间：2026-11-14T21:15:31.899Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flagsmith/serverless-plugin-canary-deployments
原文对照：https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/?lang=original
项目主页：https://github.com/Flagsmith/serverless-plugin-canary-deployments#readme
源码仓库：https://github.com/Flagsmith/serverless-plugin-canary-deployments

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：78.3 kB，25 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.0
- 运行依赖：3 个
- peer 依赖：serverless \>= 1\.26\.0
- 首次发布：2024-01-08T17:51:12.859Z
- 最新版本发布：2026-09-29T08:41:06.955Z
- 近 30 天下载量：2250（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 4 个）

## 中文简介

一个执行 Lambda 函数的金丝雀部署的无服务器插件

## 安装

```sh
npm install @flagsmith/serverless-plugin-canary-deployments
```

也可以使用：`pnpm add @flagsmith/serverless-plugin-canary-deployments`、`yarn add @flagsmith/serverless-plugin-canary-deployments`、`bun add @flagsmith/serverless-plugin-canary-deployments`

## README

[![npm version](https://badge.fury.io/js/@flagsmith%2Fserverless-plugin-canary-deployments.svg)](https://badge.fury.io/js/@flagsmith%2Fserverless-plugin-canary-deployments)

# 无服务器插件 Canary 部署

一个无服务器插件,用于执行 Lambda 函数的金丝雀部署,同时使用 [交通换乘功能](https://docs.aws.amazon.com/lambda/latest/dg/lambda-traffic-shifting-using-aliases.html) 结合 [AWS 代码部署](https://docs.aws.amazon.com/lambda/latest/dg/automating-updates-to-serverless-apps.html)

## 目录

-   [安装](https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/#readme-installation)
-   [IAM 权限](https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/#readme-iam-permissions)
-   [使用量](https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/#readme-usage)
-   [配置](https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/#readme-configuration)
-   [加那利警报](https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/#readme-canary-alarms)
-   [如何运作](https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/#readme-how)
-   [限制](https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/#readme-limitations)
-   [许可证](https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/#readme-license)

## 安装

`npm i --save-dev @flagsmith/serverless-plugin-canary-deployments`

## IAM 权限

此插件创建并管理了多个 AWS 资源 。 IAM 用户或角色部署您的无服务器服务需要以下权限:

### 云阵

```
cloudformation:CreateStack
cloudformation:UpdateStack
cloudformation:DeleteStack
cloudformation:DescribeStacks
cloudformation:DescribeStackEvents
cloudformation:DescribeStackResource
cloudformation:GetTemplate
cloudformation:ValidateTemplate
```

### 代码部署

```
codedeploy:CreateApplication
codedeploy:DeleteApplication
codedeploy:GetApplication
codedeploy:CreateDeploymentGroup
codedeploy:DeleteDeploymentGroup
codedeploy:UpdateDeploymentGroup
codedeploy:GetDeploymentGroup
codedeploy:CreateDeployment
codedeploy:GetDeployment
codedeploy:StopDeployment
```

### 兰布达

```
lambda:CreateAlias
lambda:DeleteAlias
lambda:UpdateAlias
lambda:GetAlias
lambda:GetFunction
lambda:GetFunctionConfiguration
lambda:PublishVersion
lambda:ListVersionsByFunction
lambda:UpdateFunctionCode
lambda:UpdateFunctionConfiguration
lambda:AddPermission
lambda:RemovePermission
```

### 行政会议

```
iam:CreateRole
iam:DeleteRole
iam:GetRole
iam:PassRole
iam:AttachRolePolicy
iam:DetachRolePolicy
iam:PutRolePolicy
iam:DeleteRolePolicy
```

### 云表(用于警报)

```
cloudwatch:PutMetricAlarm
cloudwatch:DeleteAlarms
cloudwatch:DescribeAlarms
cloudwatch:PutCompositeAlarm
```

### 服务特定权限

根据触发您 Lambda 函数的事件源, 您可能需要:

| 事件来源 | 权限 |
| --- | --- |
| API 网关 | `apigateway:*` 您的 API 资源 |
| 简讯 | `sns:Subscribe`, (中文(简体) ), `sns:Unsubscribe` |
| 第3条 | `s3:PutBucketNotification` |
| 云层监视事件 | `events:PutRule`, (中文(简体) ), `events:PutTargets`, (中文(简体) ), `events:RemoveTargets`, (中文(简体) ), `events:DeleteRule` |
| 云表日志 | `logs:PutSubscriptionFilter`, (中文(简体) ), `logs:DeleteSubscriptionFilter` |
| 信息技术 | `iot:CreateTopicRule`, (中文(简体) ), `iot:ReplaceTopicRule`, (中文(简体) ), `iot:DeleteTopicRule` |
| 应用同步 | `appsync:UpdateDataSource` |
| ALB/北草坪会议大楼 | `elasticloadbalancing:RegisterTargets`, (中文(简体) ), `elasticloadbalancing:DeregisterTargets` |

### 代码调度服务角色

该插件创建了代码部署服务角色,并附有以下管理的政策:

-   `arn:aws:iam::aws:policy/service-role/AWSCodeDeployRoleForLambdaLimited`
-   `arn:aws:iam::aws:policy/AWSLambda_FullAccess`

如果你自己提供 `codeDeployRole`,确保它拥有同等的权限。 见 [例-代码-部署-政策. json](https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/example-code-deploy-policy.json) 供参考.

### Lambda 执行角色

对于前/后交通钩报告部署状态,插件将此权限添加到您的 Lambda 执行角色中 :

```
codedeploy:PutLifecycleEventHookExecutionStatus
```

## 使用量

为了能够逐步部署Lambda函数,您 `serverless.yml` 应该是这样的:

```yaml
service: canary-deployments
provider:
  name: aws
  runtime: nodejs6.10
  iamRoleStatements:
    - Effect: Allow
      Action:
        - codedeploy:*
      Resource:
        - "*"

plugins:
  - serverless-plugin-canary-deployments

functions:
  hello:
    handler: handler.hello
    events:
      - http: GET hello
    deploymentSettings:
      type: Linear10PercentEvery1Minute
      alias: Live
      preTrafficHook: preHook
      postTrafficHook: postHook
      alarms:
        - FooAlarm          # When a string is provided, it expects the alarm Logical ID
        - name: BarAlarm    # When an object is provided, it expects the alarm name in the name property

  preHook:
    handler: hooks.pre
  postHook:
    handler: hooks.post
```

您可以在 [示例文件夹](https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/example/)。 。 。 .

## 配置

-   `type`: (需要)定义了Lambda函数版本之间的流量会如何转移. 它必须是以下之一:
    -   `Canary10Percent5Minutes`:在第一次增量时转移10%的流量。 其余90%在五分钟后部署.
    -   `Canary10Percent10Minutes`:在第一次增量时转移10%的流量。 其余90%在十分钟后部署.
    -   `Canary10Percent15Minutes`:在第一次增量时转移10%的流量。 剩下的90%在15分钟后部署.
    -   `Canary10Percent30Minutes`:在第一次增量时转移10%的流量。 其余90%在30分钟后部署.
    -   `Linear10PercentEvery1Minute`:每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分每分.
    -   `Linear10PercentEvery2Minutes`:每两分钟调出10%的交通量,直到所有交通量转移为止.
    -   `Linear10PercentEvery3Minutes`:每3分钟换行10%的交通量,直到所有交通量转移.
    -   `Linear10PercentEvery10Minutes`:每10分钟调出10%的交通量,直到所有交通量转移.
    -   `AllAtOnce`:将所有流量转移到新版本,在只需要执行验证钩时有用.
-   `alias`: (需要)用于创建 Lambda 函数别名的名称.
-   `preTrafficHook`: (可选)在交通转移前运行的Lambda函数. 它必须使用代码部署 SDK来通知这一步骤的成败(更多信息) [这里](https://docs.aws.amazon.com/codedeploy/latest/userguide/reference-appspec-file-structure-hooks.html)) (中文(简体) ).
-   `postTrafficHook`: (可选)在交通转移后运行的Lambda功能验证. 它必须使用代码部署 SDK来通知这一步骤的成败(更多信息) [这里](https://docs.aws.amazon.com/codedeploy/latest/userguide/reference-appspec-file-structure-hooks.html)(中文(简体) )
-   `alarms`: (可选)云表警报列表. 如果在部署过程中触发了其中任何一个,相关的Lambda函数会自动回滚到上个版本.
-   `triggerConfigurations`: (可选) 代码部署触发器列表 。 详见 [代码配置 :](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-codedeploy-deploymentgroup-triggerconfig.html),或 [本代码部署通知指南](https://docs.aws.amazon.com/codedeploy/latest/userguide/monitoring-sns-event-notifications-create-trigger.html) 例如,使用

### 默认配置

您可以在自定义配置的顶层区域设置所有函数的默认值。 例如:

```yaml
custom:
  deploymentSettings:
    codeDeployRole: some_arn_value
    codeDeployRolePermissionsBoundary: some_arn_value
    stages:
      - dev
      - prod

functions:
  ...
```

一些值只能作为顶级配置提供. 它们是:

-   `codeDeployRole`: (可选)一个 ARN 为 CodeDepload 指定一个现有的 IAM 角色. 如果缺席,将为您创造一个。 见 [代码部署政策](https://npmcn.com/package/%40flagsmith/serverless-plugin-canary-deployments/example-code-deploy-policy.json) 以实例说明需要什么.
-   `codeDeployRolePermissionsBoundary`: (可选) 指定一个已有的 IAM 权限边界的 ARN, 此权限边界设置在代码Deplerole 未定义时正在创建的代码部署上 .
-   `stages`: (可选)您想要逐步部署功能的阶段列表。 如果不在场,它就假定这些就是全部.

## 加那利警报

加那利警报是特定版本的 Cloud Watch警报,只监视 **新兰布达版本** 在部署期间。 这解决了"先前存在的提醒"问题,因为之前版本的错误在ALARM状态中保留了提醒,所以部署失败了.

`canaryAlarms` 创建云表提醒 `ExecutedVersion` 维度,它只从正在部署的特定Lambda版本监测度量.

```yaml
functions:
  hello:
    handler: handler.hello
    deploymentSettings:
      type: Canary10Percent5Minutes
      alias: Live
      canaryAlarms:
        - preset: errors    # Use preset configuration
```

### 配置

-   `canaryAlarms`: (可选) 特定版本的 Cloud Watch 提醒列表要创建 。 每个警报可以是:

**使用预设 :**

```yaml
canaryAlarms:
  - preset: errors            # Use 'errors' preset
  - preset: errors            # Override preset values
    threshold: 5
```

**使用自定义配置 :**

```yaml
canaryAlarms:
  - metric: Duration
    threshold: 5000
    comparisonOperator: GreaterThanThreshold
    statistic: Average
```

### 预设 : `errors`

这个 `errors` 预设会用这些默认设置创建提醒 :

| 财产 | 数值 |
| --- | --- |
| 计量 | 错误 |
| 命名空间 | AWS/兰布达 |
| 统计 | 总计 |
| 期间 | 页:1 |
| 评价 | 1个 |
| 数据点到提醒 | 1个 |
| 阈值 | 1 000个 |
| 操作器 | 更大的Than风险 |
| 处理丢失数据 | 影响 |

### 提醒属性

每个提醒在 `canaryAlarms` 必须使用 **无论是** 预设或自定义参数配置:

**基于预设的提醒** (所需经费) `preset`:

| 财产 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `preset` | 字符串 | 对 | 预设名称( E)`errors`(中文(简体) ) |

下面的任何其他属性都可以被指定来推翻预设的默认.

**自定义度量提醒** (所需经费) `metric` 财务报告和审定财务报表 `threshold`:

| 财产 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `metric` | 字符串 | 对 | \- 说吧 | 云表参数名称 |
| `threshold` | 编号 | 对 | \- 说吧 | 提醒阈值 |
| `namespace` | 字符串 | 没有 | `AWS/Lambda` | 云表命名空间 |
| `comparisonOperator` | 字符串 | 没有 | `GreaterThanThreshold` | 比较运算符 |
| `statistic` | 字符串 | 没有 | `Sum` | 计量统计 |
| `period` | 编号 | 没有 | `60` | 周期( 秒) |
| `evaluationPeriods` | 编号 | 没有 | `1` | 评价期数 |
| `datapointsToAlarm` | 编号 | 没有 | `1` | 触发提醒的数据点 |
| `treatMissingData` | 字符串 | 没有 | `notBreaching` | 如何处理缺失数据 |

**计算数学提醒** (所需经费) `metrics`, (中文(简体) ), `expression`,以及 `threshold`:

使用 [云表量子数学](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html) 将多个度量衡合并到单个提醒中——例如,对错误率而不是绝对错误计数进行提醒:

```yaml
canaryAlarms:
  - name: errorrate
    metrics:
      - id: errors
        metric: Errors
        statistic: Sum
      - id: invocations
        metric: Invocations
        statistic: Sum
    expression: "errors / invocations"
    threshold: 0.05
    comparisonOperator: GreaterThanThreshold
```

| 财产 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `name` | 字符串 | 没有 | \- 说吧 | 逻辑名称( 在 CloudFormation 逻辑 ID 中使用) |
| `metrics` | 数组 | 对 | \- 说吧 | 用于表达式的度量衡列表 |
| `expression` | 字符串 | 对 | \- 说吧 | 计量数学表达式参考度量标识 |
| `threshold` | 编号 | 对 | \- 说吧 | 提醒阈值( 可以是浮点) |
| `namespace` | 字符串 | 没有 | `AWS/Lambda` | 所有度量衡的云表命名空间 |
| `comparisonOperator` | 字符串 | 没有 | `GreaterThanThreshold` | 比较运算符 |
| `period` | 编号 | 没有 | `60` | 所有度数以秒计 |
| `evaluationPeriods` | 编号 | 没有 | `1` | 评价期数 |
| `datapointsToAlarm` | 编号 | 没有 | `1` | 触发提醒的数据点 |
| `treatMissingData` | 字符串 | 没有 | `notBreaching` | 如何处理缺失数据 |

每个条目 `metrics` 拥有:

| 财产 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `id` | 字符串 | 对 | 表达式中唯一引用的 ID |
| `metric` | 字符串 | 对 | 云表参数名称 |
| `statistic` | 字符串 | 对 | 计量统计`Sum`, (中文(简体) ), `Average`页:1 |

### 生成资源

当配置时 `canaryAlarms`,插件生成:

1.  **每个功能的金丝雀警报器** 与 `ExecutedVersion` 维度
2.  **堆栈复合提醒** 如果任何功能的金丝雀警报起火

复合提醒使用可预测的名称: `${service}-${stage}-canary-composite`

### 使用标准提醒

你可以用两个 `alarms` 财务报告和审定财务报表 `canaryAlarms` 组合:

```yaml
functions:
  hello:
    deploymentSettings:
      type: Canary10Percent5Minutes
      alias: Live
      alarms:
        - name: my-existing-alarm
      canaryAlarms:
        - preset: errors                      # Version-specific alarm
```

## 如何运作

该插件依赖于 [AWS Lambda 交通换乘功能](https://docs.aws.amazon.com/lambda/latest/dg/lambda-traffic-shifting-using-aliases.html) 以平衡各版本和 [AWS 代码部署](https://docs.aws.amazon.com/lambda/latest/dg/automating-updates-to-serverless-apps.html) 自动更新其重量。 它修改了 `CloudFormation` 模板生成于 [无服务器](https://github.com/serverless/serverless),以便:

1.  它为每个有部署设置的功能创建了 Lambda 函数 Alians.

-   对于由于提供货币或SnapStart配置而已经具有目标别名的函数,对其应用了"代码部署"相关设置.

2.  它创建了代码部署应用程序并增加了一个 [代码部署组](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codedeploy-deploymentgroup.html) 根据指定的设置,每个Lambda函数.
3.  它修改了触发Lambda函数的事件,从而可以引用新创建的别名.

## 限制

目前, 插件只与 Lambda 函数工作

-   API 网关
-   基于流(如由Kinesis, DynamoDB流或SQS所触发)
-   基于SNS的活动
-   S3事件
-   云表监视排定的事件
-   云表日志
-   IOT 规则
-   AppSync 数据源
-   弹性LoadBalanceV2 目标组

[更多活动](https://serverless.com/framework/docs/providers/aws/events/) 将很快增加.

## 许可证

公务员制度委员会 [戴维·加西亚](https://github.com/davidgf)

## 常见问题

### @flagsmith/serverless-plugin-canary-deployments 是什么？

一个执行 Lambda 函数的金丝雀部署的无服务器插件

### 如何安装 @flagsmith/serverless-plugin-canary-deployments？

在项目目录运行 npm install @flagsmith/serverless-plugin-canary-deployments，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：serverless（\>= 1\.26\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @flagsmith/serverless-plugin-canary-deployments 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/flagsmith\_\_serverless-plugin-canary-deployments 是否存在。

### @flagsmith/serverless-plugin-canary-deployments 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @flagsmith/serverless-plugin-canary-deployments 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @flagsmith/serverless-plugin-canary-deployments 可以商用吗？

@flagsmith/serverless-plugin-canary-deployments 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @flagsmith/serverless-plugin-canary-deployments 的下载量有多少？

根据 npm 官方下载统计，@flagsmith/serverless-plugin-canary-deployments 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,250 次，日均约 75 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @flagsmith/serverless-plugin-canary-deployments 还在维护吗？

最新版本 2\.0\.1 发布于 2026/09/29（1 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 4 个；首次发布于 2024/01/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。