Edgeworkers CLI 镜像文档

镜像概述

Edgeworkers CLI 镜像封装了 Akamai 官方提供的 cli-edgeworkers 工具，用于 EdgeWorkers 脚本的全生命周期管理。EdgeWorkers 是 Akamai 边缘计算平台的功能，允许开发者在 Akamai CDN 边缘节点运行轻量级 JavaScript 脚本，实现请求/响应处理、缓存逻辑自定义等功能。本镜像提供了免安装的命令行环境，简化 EdgeWorkers 脚本的开发、测试和部署流程。

核心功能和特性

• 项目初始化：快速创建符合 Akamai 规范的 EdgeWorkers 项目结构，包含必要的配置文件和示例代码。
• 本地测试：内置本地模拟器，可模拟 EdgeWorkers 在 Akamai 边缘节点的执行环境，支持请求/响应拦截测试。
• 打包构建：将脚本和依赖文件打包为符合 Akamai 部署要求的 .ewp 格式包。
• 部署管理：直接与 Akamai EdgeWorkers 平台交互，支持脚本部署、版本更新和环境切换（测试/生产）。
• 配置集成：支持通过 Akamai EdgeGrid 认证与 Akamai API 对接，管理 EdgeWorkers 版本和激活状态。

使用场景和适用范围

• 开发者本地开发：前端/全栈开发者开发 EdgeWorkers 脚本时，通过本镜像在本地环境进行编码、测试和调试。
• CI/CD 流程集成：在自动化流水线中集成打包和部署命令，实现代码提交后自动构建并部署到测试环境。
• 多环境隔离：通过命令行参数指定部署环境（如测试、预发、生产），避免环境配置冲突。

使用方法和配置说明

前提条件

• 已安装 Docker 环境（Docker Engine 20.10+ 或 Docker Desktop）。
• 已获取 Akamai EdgeGrid 认证凭证（包含 client_token、client_secret、access_token 和 host），需通过 Akamai Control Center 创建。

快速启动

通过 Docker 运行 Edgeworkers CLI 容器，执行基础命令：

# 查看 CLI 帮助信息
docker run --rm akamai/cli-edgeworkers edgeworkers --help

# 映射本地目录到容器（用于项目文件交互）
docker run --rm -v $(pwd):/app -w /app akamai/cli-edgeworkers edgeworkers [command]

常用命令示例

1. 初始化新项目

在本地创建新的 EdgeWorkers 项目：

# 在当前目录初始化项目（需映射本地目录）
docker run --rm -v $(pwd):/app -w /app akamai/cli-edgeworkers edgeworkers init my-edgeworker-project

执行后，当前目录下会生成 my-edgeworker-project 文件夹，包含以下结构：

my-edgeworker-project/
├── edgeworker.js       # 主脚本文件
├── bundle.json         # 项目配置
└── config.json         # 环境配置

2. 本地测试脚本

使用本地模拟器测试脚本逻辑：

# 在项目目录中运行本地测试
docker run --rm -v $(pwd):/app -w /app akamai/cli-edgeworkers edgeworkers test

测试结果将显示脚本执行日志、请求/响应处理结果，以及错误信息（如有）。

3. 打包项目

将项目打包为部署格式（.ewp 文件）：

# 打包当前项目，输出到 dist/ 目录
docker run --rm -v $(pwd):/app -w /app akamai/cli-edgeworkers edgeworkers bundle --output dist/

4. 部署到 Akamai 平台

通过 EdgeGrid 认证部署打包后的脚本到 Akamai EdgeWorkers 平台：

# 部署到测试环境（需传入 Akamai 认证凭证）
docker run --rm \
  -v $(pwd):/app -w /app \
  -e AKAMAI_EDGEGRID_CLIENT_TOKEN="your-client-token" \
  -e AKAMAI_EDGEGRID_CLIENT_SECRET="your-client-secret" \
  -e AKAMAI_EDGEGRID_ACCESS_TOKEN="your-access-token" \
  -e AKAMAI_EDGEGRID_HOST="your-api-host" \
  akamai/cli-edgeworkers edgeworkers deploy --env test dist/my-worker.ewp

环境变量配置

容器支持通过环境变量注入 Akamai 认证信息，避免每次命令输入：

持久化配置

可将 Akamai 认证信息保存到本地配置文件（如 ~/.edgerc），并通过容器映射该文件实现持久化：

# 映射本地 .edgerc 文件到容器
docker run --rm \
  -v $(pwd):/app -w /app \
  -v ~/.edgerc:/root/.edgerc \
  akamai/cli-edgeworkers edgeworkers deploy --section default dist/my-worker.ewp

其中 ~/.edgerc 文件格式示例：

[default]
client_token = your-client-token
client_secret = your-client-secret
access_token = your-access-token
host = your-api-host

常见问题

• 本地测试与实际边缘环境差异：本地模拟器仅模拟核心执行逻辑，部分 Akamai 特有 API（如 request.geo）可能返回模拟数据，建议部署到测试环境后进行全流程验证。
• 权限问题：容器内默认使用 root 用户，本地目录映射后可能出现文件权限问题，可通过 --user $(id -u):$(id -g) 参数指定用户 ID 解决。
• 网络代理：如需要通过代理访问 Akamai API，可通过 HTTP_PROXY/HTTPS_PROXY 环境变量配置代理服务器。