alibabacloud-analyticdb-postgresql-supabase-ops：云原生数据仓库AnalyticDB PostgreSQL版Supabase管理

ADBPG Supabase 项目管理

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

架构：ADBPG（AnalyticDB PostgreSQL） + Supabase + VPC + VSwitch

范围 —— 仅阿里云 ADBPG（非 Supabase CLI）

• 本 Skill 通过 GPDB / aliyun gpdb API 控制在阿里云上开通的项目。
• 不要使用独立的 supabase CLI（supabase login、supabase projects list 等）在此处创建/列出/暂停/恢复——它面向 Supabase Cloud 或自建栈，不是 ADBPG 管理的 Supabase 实例。
• 本 Skill 中所有生命周期和查询操作都是 aliyun gpdb …，带 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops。

ProjectId 格式（spb-）

• create/list/get 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 Skill 执行需要 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 Skill 调用场景，Skill 停止运行后绝不能保持启用状态。

aliyun configure ai-mode disable

凭证验证

预检查：需要阿里云凭证
安全规则：
- 绝不读取、回显或打印 AK/SK 值（例如 echo $ALIBABA_CLOUD_ACCESS_KEY_ID 是禁止的）
- 绝不要求用户在对话或命令行中直接输入 AK/SK
- 绝不使用带有明文凭证值的 aliyun configure set
- 只能使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。
如果不存在有效 profile，请在此停止。
1. 从 阿里云控制台 获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure 或 shell profile 中的环境变量）
3. 在 aliyun configure list 显示有效 profile 后返回并重新运行

RAM 权限

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

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

参数确认

重要：参数确认 —— 在执行任何命令或 API 调用之前，
所有用户可自定义参数（例如 RegionId、ProjectId、实例名、CIDR 块、
密码、VPC/VSwitch ID 等）都必须与用户确认。
对于 create，Skill 提供推荐默认值（以及可选自动发现）。你必须在运行 create-supabase-project 之前呈现完整方案并获得用户明确批准（或替换值）。

最终执行确认（只读 vs 变更）

• 无单独的最终“执行”步骤 —— 仅适用于只读信息获取：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 运行之前，对于每个变更操作：create、pause、resume、reset password、modify security IPs。展示将执行什么和关键参数（例如 project-id、不记录密钥的新密码提示、新白名单）。获得明确批准。
• create 之后，通过 get-supabase-project 的开通轮询不需要新的确认——用户已批准 create；轮询仅为验证。

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

超时配置

超时设置
- 默认 CLI 读取超时通常为每次 HTTP 读取 约 60 秒——对 create-supabase-project 通常足够，因为创建是异步的：API 接受请求并快速返回 ProjectId；它不会阻塞到实例就绪。
- 3-5 分钟是后台开通完成的典型时间——不是 create 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 Keys

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，最小化返回密钥（不记录完整密钥），并提醒用户如已暴露需轮换。

获取 Dashboard 账号

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. 可选 flag —— 使用默认：2C2G、20 GB、POSTPAY、PL0。
7. ClientToken —— 生成一个 UUID。

#### 步骤 2：呈现创建方案（单次确认）

向用户展示完整参数表及选项：

=== 创建 Supabase 项目方案 ===
项目名称:   <generated-or-user-confirmed>
地域:         <biz-region-id>
可用区:           <zone-id>
VPC:            <vpc-id from discovery>
VSwitch:        <vswitch-id from discovery> (可用 IP 数: <count>)
实例规格:  2C2G
存储:        20 GB
付费类型:       POSTPAY
安全 IP:    127.0.0.1
密码:       <generated, shown once or masked>
=================================

请选择：
1. 确认并创建（默认）
2. 修改参数
3. 取消

按 Enter 选择 [1]，或输入选项编号：

#### 步骤 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 错误，而不重复创建不同资源。
• 本次会话中为此预期项目的每次 create 尝试复用同一 --client-token。
• 重试 create（总共最多 3 次尝试，含首次）仅当响应没有 ProjectId 且错误看起来是瞬时的：例如限流、连接重置、读取超时、ServiceUnavailable。退避：尝试之间 5s → 15s → 45s。
• 不要对业务错误（例如 VSwitchIp.NotEnough、无效参数）盲目重试 create——停止、解释并与用户修复。
• 如果任何尝试返回 ProjectId → 停止调用 create；切换到开通轮询（成功验证）。
• 如果 create 超时但服务端可能已成功 → 在发出另一次同 token/name 的 create 之前，按 name/region 轮询 get-supabase-project（例如按 ProjectName 过滤 list-supabase-projects）。

CLIENT_TOKEN：首次尝试前生成一次（如 uuidgen）；安全 create 重试时复用。

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 之后（create-supabase-project）

1. 捕获 ProjectId 从 create 响应（格式 spb- + 后缀）。create 调用在请求被接受后返回，而非开通完成时。如果 create 失败或超时，在另一次 create 之前 list 或 get 查看项目是否已存在（按 Create Project 重试 create 时使用同一 --client-token）。

1. 开通轮询直到 running 或终态失败 —— 异步工作通常 3-5 分钟完成，但负载下可能更久。使用两级等待：

• Tier A —— 主要：每 30 秒调用 get-supabase-project，最多 20 次尝试（约 10 分钟）。
• Tier B —— 扩展（可选）：如果 Status 仍是非终态开通状态（例如 creating / pending——确切字符串取决于 API），告知用户并增加最多 10 次尝试（约 5 分钟）后再放弃。

1. 每次轮询重试（瞬时）：对于每次计划轮询，如果 get 因网络/读取超时或限流失败，同一 get 最多重试 3 次，每次间隔 5 秒，然后继续外层循环（仍算作一个轮询周期）。

1. 解读 Status：

• running → create / 开通成功；实例就绪——向用户报告成功。
• 终态失败（如果 API 返回显式 failure/cancelled 状态）→ 停止轮询；报告错误码/消息；不要假设成功。
• 空 / 未知 / 进行中 → 在 Tier 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

可选：如仍在开通，经用户同意 +10 次轮询

[ "$STATUS" = "running" ] || exit 1

如果 `jq` 不可用，每次检查 **get** 输出中的 `Status`；同样的重试和层级规则适用。

### 其他操作之后

| 操作 | 用此验证 | 成功提示 |
|-----------|-------------|--------------|
| List | `list-supabase-projects` | JSON 中出现 `Projects`，出现 `RequestId` |
| Get / API keys / dashboard | 对应 `get-*` 命令 | JSON 中出现预期字段，无错误码 |
| Pause / resume | `get-supabase-project` | `Status` 按 API 匹配 paused / running |
| Reset password / modify IPs | `get-supabase-project` | 白名单或适用时的成功响应；密码更改也可通过重连验证（见参考文档） |

最佳实践

1. 只读 list/get/describe（见最终执行确认）可无最终执行提示运行；绝不在未经明确最终用户确认的情况下运行 create/pause/resume/reset-password/modify-IPs
2. 如果用户缺少 VPC/VSwitch ID，create 前用 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. create 之后始终运行开通轮询（或确认终态失败）——不要将“create 返回 ProjectId”当作“实例就绪”

参考文档

文档 3 / 5：alibabacloud-cfw-exposure-detection