Serverless Framework：在自有 CI/CD 中部署服务并保留 Dashboard 功能

本文基于 Serverless Framework 官方文档《Deploy in your own CI/CD》（running-in-your-own-cicd.md）展开，讲解如何在不使用 Serverless 托管 CI/CD 的前提下，将服务部署流程放在自有 CI/CD 平台中运行，同时继续享受 Serverless Framework Dashboard 的能力（如 Provider 凭证、参数、可观测性等）。读完本篇后，你将掌握：如何为非交互式的 CI/CD 环境创建 Personal Access Key、通过 SERVERLESS_ACCESS_KEY 环境变量完成 CLI 认证，以及从源码层面理解该认证机制的工作原理与限制。

一、背景：为什么需要“自己的 CI/CD”

Serverless Dashboard 自带基于 Git 的托管 CI/CD（参见 CI/CD 文档），可将项目连接 GitHub 后自动测试和部署。但如果你已有 Jenkins、GitLab CI、GitHub Actions 等流水线，官方支持的做法是：继续用现有 CI/CD 触发部署，同时通过 Access Key 让 CLI 认证到 Dashboard，从而保留 Dashboard 的其他功能。

按官方文档的划分，配置工作分为两部分：

1. 环境配置（Configure the environment）：只需在所有服务部署中执行一次，负责安装 CLI 并配置认证；
2. 构建步骤配置（Configure the build step）：每次部署时都要运行，执行依赖安装与服务部署。

二、环境配置（一次性步骤）

2.1 安装 Node.js 和 NPM

CI/CD 环境必须预先安装 Node.js 与 NPM，它们是 Serverless Framework CLI 的前置依赖。原文档要求安装 Node.js 6.x 或更高版本（安装方式参考 Node.js 官网的包管理器指引）。需要注意的是，以当前仓库实际内容为准，CLI 包的 package.json 中声明的运行环境约束为 node >=18.0，因此在配置 CI 镜像时应使用 Node.js 18 及以上版本。

2.2 安装 Serverless Framework 开源 CLI

在 CI/CD 环境中全局安装 CLI，后续部署步骤将直接调用它：

npm install -g serverless

当前仓库中该 CLI 对应的 npm 包名为 @serverless/framework（packages/serverless/package.json，当前版本 4.0.0）。

2.3 在 Dashboard 中创建 Personal Access Key

本地交互式使用时，CLI 通过 serverless login 打开浏览器完成用户名/密码认证；而 CI/CD 环境是非交互的，无法弹出浏览器，因此必须改用 Access Token 认证。创建步骤如下：

1. 登录 Dashboard（app.serverless.com）；
2. 打开右上角的用户名下拉菜单；
3. 在下拉菜单中选择 “personal access keys”；
4. 点击 “+ add” 按钮；
5. 填写名称（name）并点击 “Create”；
6. 在新页面上即可看到生成的 access key。

注意：Access Token 拥有对所在 Org 的权限，但它是与你的个人账户绑定的——如果你的账户被删除，该 Access Token 也会被吊销。因此应妥善保存、定期轮换，并只在可信的 CI 凭据库（Secrets Manager / CI Variables）中存储。

2.4 配置环境变量

将上一步获得的 access key 设置为 CI/CD 环境变量：

• SERVERLESS_ACCESS_KEY：你的 Serverless Framework Dashboard access token。

2.5 源码验证：CLI 如何读取 SERVERLESS_ACCESS_KEY

环境变量 SERVERLESS_ACCESS_KEY 并非约定俗成，而是 CLI 认证入口明确解析的输入。在核心认证模块 packages/sf-core/src/lib/auth/index.js 中，getAuthenticatedData 方法会按如下优先级读取环境变量：

• Access Key V1（用户级，即 Personal Access Key）：SERVERLESS_ACCESS_KEY，兼容旧名 SERVERLESS_USER_ACCESS_KEY；
• Access Key V2（License Key / 组织级）：SERVERLESS_LICENSE_KEY，兼容旧名 SERVERLESS_ORG_ACCESS_KEY。

源码中对两条认证路径的意图注释非常直白（auth/index.js）：

• accessKeyV1 分支注释为 “If an Access Key is provided, this is likely a CI/CD environment”，调用 callerIdentity 校验密钥并解析出 Org ID、Org 名称、用户 ID 等信息，且不会将该密钥写入本地 ~/.serverlessrc 文件——这正符合 CI 场景“只认证、不落盘”的安全要求；
• accessKeyV2（License Key）分支同样注明 likely a CI/CD environment，且同样不写入 rc 文件。

此外，这也从代码层面解释了为什么 CI 环境必须设置该变量：当所有认证来源（环境变量、~/.serverlessrc 用户会话、SSM 参数）都拿不到密钥时，代码首先检查是否为交互式终端，非交互环境下会直接抛出错误（auth/index.js）：

You must sign in or use a license key with Serverless Framework V.4 and later versions. Please use "serverless login".

即：在 CI 中不配置 SERVERLESS_ACCESS_KEY（或 License Key），部署会在认证阶段直接失败，而不是等待人工输入。

SERVERLESS_ORG_NAME、org/app 等认证入参的完整来源优先级，可参见 Runner 文档 runners/README.md。

三、构建步骤配置（每次部署执行）

环境准备完成后，只需在每次部署的流水线中添加两步命令（官方原文）：

npm install # installs all plugins and packages
serverless deploy # deploys your service

• npm install：在服务根目录安装所有插件与依赖包（serverless.yml 中 plugins 声明的插件也在此步就绪）；
• serverless deploy：执行打包、上传与 CloudFormation 部署，认证信息来自第二步配置的 SERVERLESS_ACCESS_KEY。

在真实流水线中，通常还会在 deploy 之前加入测试、lint 等步骤，并用 CI 的 stage 参数区分环境，例如 serverless deploy --stage <env>（stage 的解析优先级为 CLI 选项 > provider.stage > 默认值 dev，见 runners/README.md）。

四、仓库中的真实 CI 用法示例

仓库自身的集成测试就是“在 CI 环境用 Access Key 驱动部署”的活例子。simple-dashboard 集成测试 在 beforeAll 中构造了一个典型的非交互 CI 认证环境：

process.env = {
  ...originalEnv,
  SERVERLESS_PLATFORM_STAGE: 'dev',
  SERVERLESS_ACCESS_KEY: process.env.SERVERLESS_ACCESS_KEY_DEV, // 注入 Personal Access Key
}
// 删除本地 AWS 凭据，改用 Dashboard Provider 提供的短时效凭证
delete process.env.AWS_ACCESS_KEY_ID
delete process.env.AWS_SECRET_ACCESS_KEY
delete process.env.AWS_SESSION_TOKEN
// 删除 License Key，因为它不允许使用 Dashboard 功能
delete process.env.SERVERLESS_LICENSE_KEY

随后通过 runSfCore({ coreParams: { options: { stage, c: configFilePath }, command: ['deploy'] } }) 执行部署，再用 AWS SDK 校验 Lambda 函数已创建。该测试印证了本文方案的两个关键事实：

1. 仅注入 SERVERLESS_ACCESS_KEY（测试环境中以 SERVERLESS_ACCESS_KEY_DEV 提供）即可让 CLI 在非交互模式下完成认证并部署；
2. 配合 app/org 属性启用 Dashboard 后，AWS 凭据可以来自 Dashboard Provider（短时效凭证），CI 环境本身不需要长期 AWS 密钥——这与托管 CI/CD 的安全模型一致（参见 CI/CD 文档中 “Step 1: Link your AWS Account”）。

仓库中其他集成测试（如 domains 系列、deployment-bucket 系列）采用同样的注入模式，进一步说明 SERVERLESS_ACCESS_KEY 是官方推荐的 CI 认证手段。

五、Personal Access Key（V1）与 License Key（V2）的选择

源码中的认证优先级为：环境变量 > ~/.serverlessrc 用户会话 / License Key 记录 > SSM 参数，且 V1 与 V2 在 Dashboard 功能上并不等价。这一点在 auth/index.js 中有硬性约束：

如果 Service 配置了 app 属性（即启用了 Dashboard），但当前使用的凭据是 License Key（Access Key V2），CLI 会抛出错误——“Dashboard features are not available when using License Keys”，要求移除 app 等 Dashboard 功能后重试。

维度	Personal Access Key（SERVERLESS_ACCESS_KEY）	License Key（SERVERLESS_LICENSE_KEY）
绑定对象	个人用户账户（账户删除则吊销）	组织（Org）级
Dashboard 功能（app、Provider、参数等）	支持	不支持（源码明确报错）
典型场景	CI/CD 中继续使用 Dashboard	无 Dashboard、纯 CLI 部署
来源文档	本文 running-in-your-own-cicd.md	license-keys.md

因此，若你的目标是“用自有 CI/CD 同时保留 Dashboard 功能”，应选择本文的 Personal Access Key 方案；若团队不需要 Dashboard，License Key 是更轻量的替代（详见 License Keys 指南）。

六、完整清单与注意事项

一次性环境配置：

1. CI 环境安装 Node.js（≥18）与 NPM；
2. npm install -g serverless；
3. 在 Dashboard → 用户名下拉菜单 → personal access keys → “+ add” 创建密钥；
4. 将密钥设置为 CI 环境变量 SERVERLESS_ACCESS_KEY。

每次部署的构建步骤：

npm install
serverless deploy

注意事项：

• SERVERLESS_ACCESS_KEY 拥有 Org 级权限且绑定个人账户，务必存入 CI 的密文凭据存储，不要明文写入仓库；
• Access Key（V1）认证时不会在 CI 机器上写入 ~/.serverlessrc（auth/index.js），每次运行都依赖环境变量注入，容器化 CI 天然适配；
• 若服务启用了 Dashboard（配置了 app），请确保使用的是 Personal Access Key 而非 License Key，否则部署会在认证阶段失败；
• 部署目标为 AWS；结合 Dashboard Provider 后，CI 环境甚至可以不配置长期 AWS 凭据，由 Provider 提供短时效凭证。

按以上步骤配置后，你的自有 CI/CD 平台即可承担 Serverless Framework 服务的部署职责，同时保留 Dashboard 的参数管理、Provider 凭证、可观测性等能力，且整套认证流程与官方集成测试中验证的方式完全一致。