alibabacloud-analyticdb-postgresql-supabase-ops

ADBPG Supabase 项目管理

管理基于 AnalyticDB PostgreSQL（ADBPG）的 Supabase 项目的完整生命周期。

架构：ADBPG (AnalyticDB PostgreSQL) + Supabase + VPC + VSwitch

范围 — 仅适用于阿里云 ADBPG（不适用于 Supabase CLI）

• 此技能通过 GPDB / aliyun gpdb API 管理在阿里云上配置的项目。
• 请勿使用独立的 supabase CLI（例如 supabase login、supabase projects list 等）在此处创建、列出、暂停或恢复项目——这些命令面向 Supabase Cloud 或自托管堆栈，不适用于由 ADBPG 管理的 Supabase 实例。
• 此技能中的所有生命周期和查询操作都使用 aliyun gpdb …，并带上 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops。

ProjectId 格式（spb-）

• 创建、列表和获取 API 返回的 ProjectId 使用前缀 spb-，后接字母数字后缀（例如 spb-2zen7c8752x12328）。请在 --project-id 中使用此准确值。
• 如果用户提供的字符串与任何实例都不匹配，请在正确的 --biz-region-id 中运行 list-supabase-projects，并匹配 ProjectName 或返回的 ProjectId。

前提条件

预检查：需要 Aliyun CLI >= 3.3.3 运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低， 请运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装或更新， 或参阅 references/cli-installation-guide.md 了解安装说明。 然后**[必须]运行 aliyun configure set --auto-plugin-install true，以启用自动安装插件。 然后[必须]**运行 aliyun plugin update，确保本地计算机上已有的所有插件始终保持最新。

[必须] CLI User-Agent — 每次调用 aliyun CLI 命令时都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

在核心工作流开始时（调用任何 CLI 命令之前）： [必须] 启用 AI-Mode — Agent 技能执行必须启用 AI-mode。 在调用任何 CLI 命令之前运行以下命令：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops"

[必须] 在每个退出点禁用 AI-Mode — 无论出于何种原因，在提交最终回复之前，都必须先禁用 AI-mode。这适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何其他不再执行 CLI 命令的情况。 AI-mode 仅用于 Agent 技能调用场景，技能停止运行后不得保持启用状态。

aliyun configure ai-mode disable

凭证验证

预检查：需要阿里云凭证

安全规则：

• 绝不读取、回显或打印 AK/SK 值（例如，禁止使用 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
• 绝不要求用户在对话或命令行中直接输入 AK/SK
• 绝不使用 aliyun configure set 配置明文凭证值
• 仅使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否存在有效配置文件（AK、STS 或 OAuth 身份）。

如果不存在有效配置文件，请在此处停止。

1. 从 Alibaba Cloud Console 获取凭证
2. 在此会话之外配置凭证（通过终端中的 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 返回并重新运行；此时 aliyun configure list 应显示有效配置文件

RAM 权限

执行操作前，请确保当前账号具有所需权限。详情请参阅 references/ram-policies.md。

权限预检查：使用 ram-permission-diagnose 技能检查当前用户权限，并与 references/ram-policies.md 进行比对；如果缺少任何权限，则中止并提示用户。

参数确认

重要：参数确认 — 执行任何命令或 API 调用前， 必须与用户确认所有可由用户自定义的参数（例如 RegionId、ProjectId、实例名称、CIDR 网段、 密码、VPC/VSwitch ID 等）。 对于创建操作，技能会提供建议默认值（以及可选的自动发现功能）。运行 create-supabase-project 前，必须向用户展示完整计划并获得明确批准（或确认用户替换的值）。

最终执行确认（只读与变更操作）

• 无需单独的最终“执行”步骤 — 仅适用于只读信息检索：aliyun gpdb list-supabase-projects、aliyun gpdb get-supabase-project、get-supabase-project-api-keys、get-supabase-project-dashboard-account，以及仅用于发现的调用，例如 aliyun vpc describe-vpcs、aliyun vpc describe-vswitches、aliyun gpdb describe-regions（与 list / describe 同类：不会改变资源状态）。
• 必须获得最终用户确认 — CLI 运行前，对每项变更操作都必须确认：创建、暂停、恢复、重置密码、修改安全 IP。说明将执行的操作及关键参数（例如 project-id、新密码提示（不得记录密钥）、新白名单），并获得明确批准。
• 创建后，通过 get-supabase-project 进行的配置状态轮询无需再次确认 — 用户已批准创建操作；轮询仅用于验证。

CreateSupabaseProject 定义见官方 API 参考。完整的 CLI 参数映射、VPC/VSwitch 发现、名称和密码规则见：references/create-supabase-project-parameters.md。

参数	必填/可选	描述	默认值 / 建议
ProjectId	必填（创建以外）	API/list 返回的实例 ID（spb- + 后缀）	—
BizRegionId	可选（创建）	地域 ID（API 中的 RegionId）	cn-beijing
ProjectName	必填（创建）	项目名称	根据用户场景生成；用户可替换
ZoneId	必填（创建）	可用区 ID	cn-beijing-i
VpcId	必填（创建）	VPC ID	用户输入或通过发现获取（参见“创建项目”）
VSwitchId	必填（创建）	VSwitch ID（必须与 ZoneId 匹配）	用户输入或建议使用该可用区内 AvailableIpAddressCount 最大的 ID
AccountPassword	必填（创建）/ 重置	数据库密码	用户输入或按 API 规则生成；用户可替换
SecurityIPList	必填（创建）/ 修改	IP 白名单	127.0.0.1；用户可提供 IP/CIDR
ProjectSpec	必填（创建）	实例规格	2C2G（技能默认建议值；用户可选择例如 1C1G）
StorageSize	可选（创建）	存储空间（GB）	20（技能默认建议值）
DiskPerformanceLevel	可选（创建）	PL0 / PL1	PL0
PayType / UsedTime / Period	可选（创建）	计费方式	默认采用 POSTPAY（后付费）；仅预付费/包年包月时设置 --period / --used-time
ClientToken	可选（创建）	幂等性	除非用户重试同一创建操作，否则省略

超时配置

超时设置

• CLI 的默认读取超时通常是每次 HTTP 读取约 60 秒——通常足以完成 create-supabase-project，因为创建操作是异步的：API 会接受请求并快速返回 ProjectId；它不会一直阻塞到实例就绪。
• 后台配置通常需要 3–5 分钟才能完成——这不是创建 HTTP 响应的持续时间。请使用成功验证（轮询 get-supabase-project，直到 Status 为 running）等待该阶段完成。
• 创建成功标准：create-supabase-project 返回 ProjectId 后，实例并未就绪；只有当 get-supabase-project 报告 Status = running（API 使用小写）时，才表示配置成功，项目可以使用。
• 如果实际执行时任何命令遇到读取超时，请提高该命令的 --read-timeout 值（例如 --read-timeout 120）。

核心工作流

所有命令均使用 aliyun gpdb <command> 格式，必须包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops。

根据**最终执行确认（只读操作与变更操作）：只读的 list / get / describe 操作可以在没有最终执行提示的情况下运行；create、pause、resume、reset password、modify IPs 则必须在调用前获得用户的明确最终确认**。

列出项目

aliyun gpdb list-supabase-projects \
  --biz-region-id cn-beijing \
  --max-results 20 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• 风险：低 | 只读——无需最终执行确认

获取项目详情

aliyun gpdb get-supabase-project \
  --project-id spb-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• 风险：低 | 只读——无需最终执行确认

获取 API 密钥

aliyun gpdb get-supabase-project-api-keys \
  --project-id spb-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• 风险：低 | 只读——无需最终执行确认
• 策略：通过这个阿里云官方 API（具备 RAM/账户访问权限）响应读取密钥的请求，与从无关代码库中抓取机密并不相同。只有在任务明确要求从代码仓库或第三方系统中窃取数据时才拒绝；否则运行 get-supabase-project-api-keys，以最少必要的方式返回密钥（不记录完整机密），并提醒用户如果密钥已暴露，应进行轮换。

获取控制台账户

aliyun gpdb get-supabase-project-dashboard-account \
  --project-id spb-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• 风险：低 | 只读——无需最终执行确认

创建项目

自动化工作流——当用户提出“帮我在北京 i 创建 ADBPG Supabase 项目”之类的需求时，执行以下步骤：

步骤 1：自动发现所有信息（暂时无需用户输入）

1. 地域 + 可用区——使用用户指定的值或默认值（cn-beijing、cn-beijing-i）。
2. ProjectName——运行 scripts/generate-project-name.sh，获取 1–3 个候选名称（基于时间戳）。
3. 密码——运行 scripts/generate-password.py，生成符合要求的密码。
4. VPC/VSwitch 发现——运行 scripts/discover-vswitch.sh --biz-region-id <region> --zone-id <zone>，获取可用 IP 数量最多的 VSwitch。
5. SecurityIPList——默认为 127.0.0.1。
6. 可选标志——使用默认值：2C2G、20 GB、POSTPAY、PL0。
7. ClientToken——生成一个 UUID。

步骤 2：展示创建计划（一次确认）

向用户展示完整的参数表，并提供以下选项：

=== Create Supabase Project Plan ===
Project Name:   <generated-or-user-confirmed>
Region:         <biz-region-id>
Zone:           <zone-id>
VPC:            <vpc-id from discovery>
VSwitch:        <vswitch-id from discovery> (Available IPs: <count>)
Instance Spec:  2C2G
Storage:        20 GB
Pay Type:       POSTPAY
Security IP:    127.0.0.1
Password:       <generated, shown once or masked>
=================================

Select an option:
1. Confirm and create (default)
2. Modify parameters
3. Cancel

Press Enter for [1], or type option number:

步骤 3：确认后执行

如果用户选择“1”或按 Enter（确认），运行：

aliyun gpdb create-supabase-project \
  --biz-region-id <BizRegionId> \
  --zone-id <ZoneId> \
  --project-name <ProjectName> \
  --account-password ‘<Password>’ \
  --security-ip-list "127.0.0.1" \
  --vpc-id <VpcId> \
  --vswitch-id <VSwitchId> \
  --project-spec 2C2G \
  --storage-size 20 \
  --disk-performance-level PL0 \
  --pay-type POSTPAY \
  --client-token "<ClientToken>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

然后按照下文所述继续进行成功验证（轮询）。

异步创建 — HTTP 重试（获取 ProjectId 之前）

• 目标：应对暂时性的 CLI／网络／API 错误，避免重复创建不同的资源。
• 在本次会话中，为此项目的每次创建尝试重用相同的 --client-token。
• 仅当响应中没有 ProjectId 且错误看起来是暂时性错误时，才重试创建（总共最多 3 次尝试，包括首次尝试）：例如限流、连接重置、读取超时、ServiceUnavailable。重试间隔：5 秒 → 15 秒 → 45 秒。
• 对于业务错误（例如 VSwitchIp.NotEnough、参数无效），不要盲目重试创建 — 停止操作，向用户说明并修正问题。
• 如果任何一次尝试返回了 ProjectId → 停止调用创建操作；改为轮询配置状态（成功验证）。
• 如果创建超时，但可能已在服务端成功 → 再次创建之前，先按名称／区域轮询 get-supabase-project（例如使用 ProjectName 筛选 list-supabase-projects）。

# CLIENT_TOKEN: generate once (e.g. uuidgen) before first attempt; reuse on safe create retries.
aliyun gpdb create-supabase-project \
  --biz-region-id cn-beijing \
  --zone-id cn-beijing-i \
  --project-name my_supabase \
  --account-password '<user-or-generated>' \
  --security-ip-list "127.0.0.1" \
  --vpc-id vpc-xxxxx \
  --vswitch-id vsw-xxxxx \
  --project-spec 2C2G \
  --storage-size 20 \
  --disk-performance-level PL0 \
  --pay-type POSTPAY \
  --client-token "$CLIENT_TOKEN" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• 风险：高 | 最终用户确认 — 执行前须批准完整参数计划
• 密码：大写字母、小写字母、数字、特殊字符 !@#$%^&*()_+-= 中至少包含 3 类；长度为 8–32（根据 API 要求）
• 项目名称：仅限字母／数字／连字符／下划线；必须以字母或 _ 开头；长度为 1–128

暂停项目

aliyun gpdb pause-supabase-project \
  --project-id spb-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• 风险：中 | 执行前须获得最终用户确认
• 暂停后服务不可用，但数据会保留

恢复项目

aliyun gpdb resume-supabase-project \
  --project-id spb-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• 风险：中 | 执行前须获得最终用户确认（会修改数据）

重置数据库密码

aliyun gpdb reset-supabase-project-password \
  --project-id spb-xxxxx \
  --account-password 'NewPass456!' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• 风险：中 | 执行前须获得最终用户确认
• 使用旧密码的现有连接将断开

修改安全 IP

aliyun gpdb modify-supabase-project-security-ips \
  --project-id spb-xxxxx \
  --security-ip-list "10.0.0.1,10.0.0.2/24" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• 风险：中 | 执行前须获得最终用户确认
• 多个 IP 以逗号分隔，支持 CIDR 格式

成功验证

请先使用以下步骤；扩展表格和边缘案例请参阅 references/verification-method.md。

创建后（create-supabase-project）

1. 从创建响应中获取 ProjectId（格式为 spb- + 后缀）。创建调用在请求被接受后即返回，而不是等到配置完成。如果创建失败或超时，请在再次创建之前列出或获取项目，确认项目是否已存在（若根据创建项目的说明重试创建，请使用相同的 --client-token）。

2. 轮询配置状态，直至状态为 running 或出现终止失败 — 异步工作通常会在 3–5 分钟内完成，但高负载时可能需要更长时间。采用两级等待策略：

   • A级 — 主要轮询：每 30 秒调用一次 get-supabase-project，最多 20 次（约 10 分钟）。
   • B级 — 延长等待（可选）：如果 Status 仍处于非终止配置状态（例如 creating／pending — 具体字符串取决于 API），请告知用户，并最多再尝试 10 次（约 5 分钟），然后再放弃。

3. 每次轮询的重试（暂时性错误）：对于每次计划中的轮询，如果 get 因网络／读取超时或限流失败，请在 5 秒后重试相同的 get，最多 3 次，然后继续外层循环（仍计为一个轮询周期）。

4. 解读 Status：

   • running → 创建／配置成功；实例已就绪 — 向用户报告成功。
   • 终止失败（如果 API 返回明确的失败／取消状态）→ 停止轮询；报告错误代码／消息；不要假定操作成功。
   • 空／未知／进行中 → 在 A级／B级限制内继续轮询。

PROJECT_ID="spb-xxxxx"
STATUS=""
MAX_PRIMARY=20
SLEEP=30
for attempt in $(seq 1 "$MAX_PRIMARY"); do
  RAW=""
  for inner in 1 2 3; do
    RAW=$(aliyun gpdb get-supabase-project \
      --project-id "$PROJECT_ID" \
      --read-timeout 90 \
      --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops \
      2>/dev/null) && break
    sleep 5
  done
  STATUS=$(echo "$RAW" | jq -r '.Status // empty')
  [ "$STATUS" = "running" ] && break
  sleep "$SLEEP"
done
# Optional: extend with user consent +10 polls if still provisioning
[ "$STATUS" = "running" ] || exit 1

如果 jq 不可用，请每次检查 get 输出中的 Status；重试和分级等待规则相同。

其他操作后

操作	验证方式	成功提示
列出	list-supabase-projects	JSON 中包含 Projects，且包含 RequestId
获取 / API 密钥 / 控制台	对应的 get-* 命令	JSON 中包含预期字段，且没有错误代码
暂停 / 恢复	get-supabase-project	Status 与 API 返回的 paused / running 状态一致
重置密码 / 修改 IP	get-supabase-project	根据情况返回白名单或成功响应；还需通过重新连接验证密码是否已更改（参见参考文档）

最佳实践

1. 只读的 list/get/describe 操作（参见最终执行确认）可以不经过最终执行提示直接运行；未经用户明确的最终确认，绝不运行 create/pause/resume/reset-password/modify-IPs
2. 如果用户没有 VPC/VSwitch ID，应先使用 vpc describe-vswitches（也可以使用 vpc describe-vpcs）进行查询，再创建
3. 暂停项目前必须发出警告（服务将变为不可用）
4. 出于安全风险考虑，不要建议将白名单设置为 0.0.0.0/0
5. ProjectId 始终为 spb-…——如果用户提供的 ID 错误或未知，请使用 list-supabase-projects 按名称或 ID 查询
6. 在此产品中，绝不能用 supabase CLI 替代 aliyun gpdb
7. 暂停项目可节省费用，同时保留数据
8. 所有命令都必须包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
9. 创建后，始终执行配置轮询（或确认终止失败）——不要将“创建返回了 ProjectId”视为“实例已就绪”

参考文档

文档	说明
references/cli-installation-guide.md	CLI 安装指南
references/ram-policies.md	RAM 权限要求
references/related-apis.md	相关 API 列表
references/verification-method.md	操作验证方法
references/acceptance-criteria.md	验收标准
references/create-supabase-project-parameters.md	创建 API 参数、默认值、VPC/VSwitch 查询