deploying-containers-to-amazon-lightsail

部署容器到 Amazon Lightsail

概述

Amazon Lightsail 容器服务会在托管的 HTTPS URL 后运行容器映像，按固定月费计价。URL、TLS 证书和负载均衡均已包含在内——无需设置集群、VPC、负载均衡器或注册表。

此技能可将任何来源的容器映像部署到 Lightsail，使其上线并提供服务，也可诊断无法提供服务的部署。创建服务需要做出两个选择：power，即每个节点的内存和 vCPU 数量；以及 scale，即运行的节点数量，每个节点都会运行一份完整的部署副本。容量不会自动变化——没有自动扩缩，也不能缩容至零——因此服务需要更多容量时，你需要自行提高 power 或 scale。

前提条件

创建任何资源之前：

• 确认映像来源、应用监听的端口以及区域。
• 在运行时查询选项——可用的规格和区域，而不是将其硬编码。
• **确认方案和价格。**说明固定月费（power × scale，即使没有流量也会收费），并在创建计费资源前征得确认——除非用户已告知你可以继续。绝不要悄悄创建资源。价格数据的查询位置请参阅下方的“定价”部分。
• **固定配额不可调整。**每个服务的节点数上限决定了 scale 的上限；每次部署的容器数和部署版本数也有上限。请查阅 Lightsail quotas 中的数值，不要提出申请提高配额。若账户是最近创建的，或使用较少，其实际配额可能低于公布的默认值。
• **权限。**调用身份需要具备下方“操作”表中的 Lightsail 操作权限；缺少权限时，首次调用会出现拒绝访问错误，而不是工具或配额问题。权限范围请参阅下方的“安全注意事项”部分。

工具：部署公共注册表中的映像只需 AWS CLI（v2）——其操作可通过 AWS MCP 工具（首选，见下文）或直接使用 CLI 执行。本地构建或推送还需要 docker（且必须正在运行）；使用 push-container-image 快捷方式时，还需要 lightsailctl 插件（不使用插件的推送方式则使用 docker + register-container-image）。

运行 AWS 操作：如果 AWS MCP 执行工具 aws___run_script 可用，优先使用它，并让每次调用都保持简短——执行一个能立即返回的操作，而不要执行长时间运行的操作（调用持续运行超过约 30 秒后会被中止，会话也会丢失）。这不是必需的：同样的操作也可通过本地 aws CLI 执行；没有可用 MCP 工具时，请使用 CLI。请注意，构建和推送本地映像属于 Docker/lightsailctl 操作，只能在你的机器上运行，不能通过 MCP 工具运行。

安装 lightsailctl：仅使用 push-container-image 快捷方式时才需要；此外还需要 AWS CLI v2 和正在运行的 Docker：

• macOS： brew install aws/tap/lightsailctl
• Linux： curl "https://s3.us-west-2.amazonaws.com/lightsailctl/latest/linux-amd64/lightsailctl" -o /usr/local/bin/lightsailctl && chmod +x /usr/local/bin/lightsailctl
• Windows： 下载 https://s3.us-west-2.amazonaws.com/lightsailctl/latest/windows-amd64/lightsailctl.exe，并将其添加到 PATH。

如果安装受阻，或仍无法找到插件，请参阅故障排除参考；也可以完全跳过插件，使用 references/local-image.md 中不依赖插件的推送方式。

参考资料

分步详细说明位于此技能附带的参考文件中。执行操作前，必须先阅读与映像来源或即将执行的步骤相对应的参考文件——其中列出了确切的顺序和要求（端口、映像架构、推送方法），这些细节很容易出错。

打开文件的方法：在 AWS MCP 服务上，使用该技能的内容检索工具获取；否则，从该技能自身的目录中读取（技能加载时已显示其位置），例如 <skill-dir>/references/NAME.md。 不要从裸路径 references/NAME.md 读取——它会相对于你的工作目录解析，并因找不到文件而失败；如果遇到这种情况，请在路径前加上技能目录后重试。

• references/public-image.md — 公共注册表映像（无需构建或推送）。
• references/local-image.md — 构建本地映像并将其推送到服务的注册表（docker；push-container-image 或不使用插件的操作序列）。
• references/github-source.md — 从 GitHub 仓库克隆并构建，然后按照本地映像的操作流程进行。
• references/deployment.md — 部署结构（containers + publicEndpoint + 健康检查）、如何轮询至 ACTIVE、回滚和拆除。
• references/troubleshooting.md — 找不到 lightsailctl、部署状态为 FAILED、502/503，以及 exec format error（CPU 架构不匹配）。

服务、部署、容器

• 容器服务 — 首先创建的长期资源。它负责容量（power × scale）、公共 HTTPS URL、私有域名，以及自身的映像注册表。计费从创建时开始，直到删除为止。
• 部署 — 要在该服务上运行的不可变、有版本的规范。任何时候只有一个部署处于活动状态；创建另一个部署会完全替换现有规范。
• 容器 — 部署中的条目（每个部署的上限见上方链接的 Lightsail 配额）。每个容器都有名称、映像和端口；其中恰好一个可以作为公共端点，其余容器只能通过 localhost 由同一部署中的其他容器访问。

定价

价格根据容量设定，并受传输配额限制。月费为 power 的价格 × scale，从创建时起计费，直到删除为止，无论是否收到请求。每项服务都包含一个月度数据传输配额——无论为服务选择何种 power 和 scale，配额都不变；超出配额的出站流量按 GB 计费，费率因区域而异。入站流量计入配额，但超额时不收费。

只有在刚从下方某个来源查阅价格后，才能报出价格——绝不能凭记忆，也不能对未查阅的费率使用 $0.00 之类的占位值。容量费用是确定的（power 价格 × scale）。出站流量费用无法确定，因为它取决于未知的流量，因此应给出每 GB 费率，而不是总额。

• power 价格 — get-container-service-powers 是唯一数据源。它会返回每种 power 的月度单节点价格，应直接引用该数值。
• 传输配额 — 使用 AWS 价格清单操作 get-products 并指定服务代码 AmazonLightsail，从 Lightsail Containers 记录的 dataTransferQuota 属性获取。
• 出站费率 — 在另一条 get-products 记录中查找，并使用 TERM_MATCH 筛选条件匹配 overageType = ContainerSvc:Data Transfer。使用 overageType，而不是 productFamily：Lightsail Networking 还包含 CDN、存储桶、实例和 DNS 的超额流量记录。应按 fromRegionCode 筛选，而不是 regionCode，因为这些记录中的区域指的是流量传出的位置。

工作流

1. 创建服务，选择功率和规模；轮询 get-container-services，直到其 state 为 READY。 get-container-service-powers 会返回每种功率的 name（nano）和 powerId（nano-1）——创建 服务时，将 name 传给 --power。
2. 获取镜像——这是唯一因来源而异的步骤；请参阅上方对应的参考。
3. 部署一个版本（包含其 containers 和一个带有运行状况检查的 publicEndpoint），然后轮询部署状态， 直到变为 ACTIVE——请参阅部署参考。
4. 验证并报告——仅当部署处于 ACTIVE 状态后，才从服务中读取生成的 URL（它带有随机 ID——读取现有 URL，不要自行构造），确认该 URL 可正常响应，并报告 URL、月费和拆除命令。

**轮询：**创建和部署会立即返回，并在后台异步完成——预计整个过程约需 5–10 分钟；状态仍为 PENDING/ACTIVATING 属于正常情况。轮询时，重复进行简短的状态检查，并在调用之间短暂暂停——每次检查都是一次快速调用，会立即返回，中间只需短暂 sleep。不要在一次长时间运行的调用中等待（例如在单个 run_script 中循环，或运行很长的 shell 循环）——这会触发执行超时（单次调用运行超过约 30 秒后可能会被终止，并导致会话中断）。 仅当部署处于 ACTIVE 状态后，才返回 URL。

应做 / 不应做

✅ 应做	❌ 不应做
创建前确认月费（除非已获准继续）	默默创建会产生费用的资源
通过 API 查询功率、区域、价格和镜像版本	将功率、规模、区域、价格或镜像版本写死
执行镜像步骤前阅读镜像来源参考	猜测构建/推送流程
通过多次简短调用轮询，并在调用间使用 sleep；仅当状态为 ACTIVE 后才返回 URL	在一次长时间运行的调用中等待（例如在 run_script 或 shell 中循环）；提前返回 URL
对于公共镜像，完全跳过构建和推送	当镜像已存在于镜像仓库中时仍要求本地构建
通过 get-container-log 查看日志以诊断故障	遇到 502 或部署状态为 FAILED 时盲目重新构建或部署
针对微服务/自动扩缩容场景推荐 ECS/EKS 或 ECS Express Mode	将 Lightsail 当作所有容器问题的答案
始终提供拆除命令	让用户无法停止产生费用

运维

操作（aws lightsail …）	用途	说明
get-container-service-powers	列出可用规格及其规格参数和价格	请读取这些信息，不要引用记忆中的规格或价格
create-container-service	创建服务	固定价格 = 规格 × 实例数
update-container-service	更改运行中服务的容量（规格/实例数）	自动重新部署当前部署，不会停机，并保留相同的部署版本
get-container-services	检查状态	部署前应为 READY；部署生效后应为 RUNNING
push-container-image	推送本地镜像	需要 lightsailctl 插件和正在运行的本地 Docker
create-container-service-registry-login	获取临时注册表凭证	无插件推送流程的第一步
register-container-image	按摘要注册已推送的镜像	push-container-image 的无插件替代方案
get-container-images	列出服务注册表中的镜像版本	Lightsail 会分配版本号，请在此读取，不要自行假定
create-container-service-deployment	部署镜像	containers{} + publicEndpoint{containerName, containerPort, healthCheck}
get-container-service-deployments	部署状态和历史记录	ACTIVATING → ACTIVE；重新部署之前的版本即可回滚
get-container-log	查看容器日志	诊断部署失败时的首要步骤；不要记录机密或客户数据
delete-container-service	拆除服务	停止计费

安全注意事项

• 最小权限 IAM — 将调用主体的权限范围限制为此工作流实际使用的 lightsail: 操作（见上方操作表），而不是 lightsail:* 或管理员策略。
• 机密信息 — environment 值会存储在部署规范中，并且可通过 get-container-service-deployments 读取；由于没有单独的机密注入机制，容器所需的凭证必须放在其中，因此只传入所需内容。当某个值看起来像凭证（密码、令牌、API 密钥或连接字符串）时，部署前必须警告用户，并由用户决定；一种选择是使用能自行解密该值的应用，这样部署规范中存放密文，而密钥随镜像一起发布。绝不要向用户或任何制品打印或记录这些值，也不要打印或记录包含这些值的 get-container-service-deployments 响应。
• 公共访问面 — 端点仅支持 HTTPS，并使用 AWS 托管证书；Shield Standard 会自动防护常见的网络层 DDoS 攻击；只有 publicEndpoint 中指定名称的容器可从互联网访问。容器服务不提供请求限流或 WAF，且 Lightsail 不会注入安全标头，因此输入验证、速率限制以及 CSP / HSTS / X-Content-Type-Options / X-Frame-Options 都由应用负责。
• 私有网络访问 — 容器可不受限制地访问同一账户和区域中的其他 Lightsail 资源，且没有 Lightsail 防火墙规则可以限制此访问。如果该区域已启用 VPC 对等连接，同样的访问权限也会延伸到自有 VPC。因此，镜像是唯一的控制手段，部署用户未构建的镜像前必须警告用户。
• 审计 — CloudTrail 会记录所有 Lightsail API 调用；事件历史记录默认启用，而跟踪可持续将日志传送到 S3。

故障排除

如果遇到任何问题——部署失败或 URL 无法提供服务——请阅读 references/troubleshooting.md；首先查看容器日志以找出根本原因。