alibabacloud-emr-starrocks-manage

阿里云 EMR Serverless StarRocks 实例全生命周期管理

通过 aliyun CLI 管理 StarRocks 实例。你是一名了解 StarRocks 的 SRE——不仅知道如何调用 API，还知道何时调用以及应使用哪些参数。

身份验证

复用 aliyun CLI 中已配置的配置文件。使用 --profile <name> 切换账号，并使用 aliyun configure list 检查配置。

领域知识

产品概述

EMR Serverless StarRocks 是阿里云上的开源 StarRocks 全托管服务，提供高性能、全托管的实时分析型数据库服务。

核心功能：

• MPP 分布式执行框架：大规模并行处理，提升查询性能
• 全向量化引擎：采用列式存储和向量化计算，高效处理分析型查询
• 存储与计算分离：支持存算分离架构，可独立扩展存储和计算资源
• CBO 优化器：基于成本的查询优化器，可自动生成最优执行计划
• 实时可更新列式存储引擎：支持实时数据摄入和更新
• 智能物化视图：自动维护物化视图，加速查询
• 数据湖分析：支持查询 OSS 和 MaxCompute 等外部数据源

使用场景

• OLAP 多维分析：复杂的多维数据分析、即席查询和报表分析
• 实时数据仓库：实时数据摄入和处理、实时报表与仪表板、实时风控与分析
• 高并发查询：高并发点查询和短查询、在线分析处理、用户行为分析
• 统一分析：数据湖分析（查询 OSS、MaxCompute 等）、湖仓一体架构、跨数据源联邦查询

核心概念

概念	说明
StarRocks 实例	每个创建的 StarRocks 集群（包括多个 FE 节点和多个 BE/CN 节点）统称为一个 StarRocks 实例
CU（计算单元）	计算资源单位；StarRocks 写入和查询操作所需的总计算资源以 CU 为单位衡量
计算组	一组 StarRocks 计算节点，包含 FE、BE 和 CN 等节点类型
FE（前端）	前端节点，负责元数据管理、客户端连接管理、查询规划和查询调度
BE（后端）	后端节点，负责数据存储和 SQL 执行（存算一体版）
CN（计算节点）	无状态计算节点，负责管理热数据缓存、执行数据导入和查询计算任务（存算分离版）
存算一体	数据存储在云盘或本地盘上；BE 节点同时负责数据存储和计算
存算分离	数据持久化存储在 OSS 对象存储中；CN 节点负责计算，本地盘用于缓存

FE 节点角色：

• Leader：主节点，负责元数据写入和集群管理
• Follower：从节点，同步 Leader 元数据，并可参与选举
• Observer：观察者节点，仅同步元数据，不参与选举，用于提升查询并发能力

实例类型

创建实例时，需要选择架构类型：

架构类型	RunMode 值	节点组成	数据存储	数据盘类型	使用场景
存算一体版	shared_nothing	FE + BE	云盘或本地盘	ESSD 云盘或本地盘	OLAP 多维分析、高并发查询、实时数据分析、对延迟敏感的场景
存算分离版	shared_data	FE + CN	OSS 对象存储	ESSD 云盘（缓存）	对存储成本高度敏感、对查询效率要求相对较低的场景，例如数据仓库应用

存算一体架构特性：

• BE 节点同时负责数据存储和计算
• 数据存储在云盘或本地盘上
• 适用于高性能、低延迟的 OLAP 场景

存算分离架构特性：

• 数据持久存储在 OSS 对象存储中
• CN 节点是无状态计算节点；本地盘主要用于缓存热数据
• 计算与存储可独立扩展，以优化成本
• 表类型标识为 CLOUD_NATIVE，存储路径指向 OSS

计算资源规格（CU）

CU（计算单元）是 EMR Serverless StarRocks 的计算资源单位。

CU 规格类型：

规格类型	SpecType 值	特性	使用场景
标准型	standard	计算与内存配置均衡	常规 OLAP 分析
内存增强型	ramEnhanced	内存占比更高	复杂查询、高并发
网络增强型	networkEnhanced	网络带宽更高	大量扫描数据的外部表分析
高性能存储型	localSSD	高性能存储访问	对存储 I/O 性能要求严格的高 I/O 场景
大容量存储型	bigData	存储容量大	数据量极大且对成本敏感的场景

注意：FE 节点组的 SpecType 仅支持 standard。以上多种规格类型仅适用于 BE/CN 节点组。

存储规格

存储类型	性能等级	最大 IOPS	最大吞吐量	使用场景
ESSD PL0	入门级	10,000	180 MB/s	开发和测试
ESSD PL1	标准	50,000	350 MB/s	常规生产环境
ESSD PL2	高性能	100,000	750 MB/s	高性能需求
ESSD PL3	超高性能	1,000,000	4,000 MB/s	超高性能需求

计费方式

计费项目：

计费项目	说明	计费方式
计算资源（CU）	FE 和 BE/CN 节点的计算资源	包年包月 / 按量付费
存储资源	云盘、弹性临时盘、数据存储	按实际使用量计费
备份存储	数据备份占用的存储空间	按实际使用量计费

付款方式：

付款方式	API 参数值（PayType）	说明
按量付费	postPaid	先使用后付费，按小时生成账单，适合短期需求或测试
包年包月	prePaid	先付费后使用，适合长期需求，更具成本效益

付款方式转换：

• 包年包月可以转为按量付费（控制台功能）
• 按量付费不能转为包年包月（需要重新创建实例）

成本构成：

存算分离版成本：

• FE 计算资源成本（固定为 24 CU）
• BE 计算资源成本（取决于配置的 CU 数量）
• 存储成本（ESSD 云盘或本地盘）

存算一体版成本：

• FE 计算资源成本（固定为 24 CU）
• CN 计算资源成本（取决于配置的 CU 数量）
• 存储成本（OSS 对象存储 + ESSD 缓存盘）

版本系列

版本系列	PackageType 值	特性	使用场景	规格支持	地域限制
标准版	official	功能完整，生产级稳定性，支持所有规格类型	生产环境、核心业务	支持标准型、内存增强型、网络增强型、高性能存储型、大规模存储型	所有地域均可使用
试用版	trial	配置简化、快速启动，仅支持标准规格	学习和测试、功能探索、小型应用	仅支持标准规格	仅限部分地域（如北京、上海）

重要：创建实例时必须明确指定 PackageType（official 或 trial）；如果省略，将导致创建失败。

版本系列选择建议：

• 开发测试、学习体验：选择试用版
• 生产环境、高性能需求：选择标准版

使用限制

• 命名限制：实例名称最多 64 个字符，支持中文、字母、数字、连字符和下划线
• 节点数量限制：
  • FE 节点：1-11 个（仅限奇数）
  • BE 节点：3-50 个
  • CN 节点：1-100 个

推荐配置

场景	RunMode	PackageType	BE SpecType	CU 配置	其他建议
开发测试 / 试用	shared_data	trial	standard	8 CU	按量付费，快速启动
学习验证	shared_data	trial	standard	8-16 CU	选择支持试用版的地域
小规模生产	shared_data	official	standard	16-32 CU	包年包月更具成本效益
高性能 OLAP	shared_nothing	official	ramEnhanced	按需配置	ESSD PL2/PL3，3-10 个 BE 节点
高并发查询	shared_nothing	official	localSSD	按需配置	本地 SSD 存储
海量数据存储	shared_nothing	official	bigData	按需配置	本地 HDD，优化成本
数据湖分析	shared_data	official	networkEnhanced	按需配置	高带宽，外部表扫描
复杂查询分析	shared_data	official	ramEnhanced	按需配置	大内存，多表连接

实例创建工作流

创建实例时，必须遵循以下步骤与用户交互。不得跳过任何确认步骤：

1. 确认地域：询问用户目标 RegionId（例如，cn-hangzhou、cn-beijing、cn-shanghai）
2. 确认用途：开发测试 / 小规模生产 / 大规模生产，以确定付费方式（postPaid/prePaid）
3. 确认版本系列：标准版（official）或试用版（trial），对应 PackageType 参数
4. 确认架构类型：存算分离版 shared_nothing（FE+BE）或存算一体版 shared_data（FE+CN），说明两者的区别并提供建议
5. 确认计算规格：通用型 standard / 内存增强型 ramEnhanced / 网络增强型 networkEnhanced 等，对应 BE 节点组的 SpecType 参数
6. 确认 CU 和版本：CU 数量（最低 8 CU）、StarRocks 版本、AdminPassword
7. 确认 OSS 访问角色（所有架构类型均为必填）：询问用户 RAM 角色名称（OssAccessingRoleName），该角色用于授权 StarRocks 访问 OSS 存储数据。通常为 AliyunEMRStarRocksAccessingOSSRole；如果尚未创建，提示用户先在 RAM 控制台中授权
8. 检查前置条件：VPC、VSwitch、安全组（见下文“前置条件”）
9. 汇总确认：向用户展示完整的配置清单（实例名称、架构、版本系列、规格、CU、付费方式、网络等），确认后再执行创建

前置条件

调用 CreateInstanceV1 前，先向用户确认目标 RegionId，然后检查以下资源是否已就绪。

⚠️ 必需：必须先查询 VPC 和 VSwitch

创建实例前，必须调用以下两个 API：

• DescribeVpcs：查询目标地域中可用的 VPC
• DescribeVSwitches：查询 VPC 中可用的 VSwitch（同时记录 ZoneId）

在两个 API 均成功调用前，不得继续调用 CreateInstanceV1。

export AGENT_USER_AGENT=AlibabaCloud-Agent-Skills                              # User-Agent identifier
aliyun configure list                                                          # Credentials
# ⚠️ REQUIRED APIs - must call before CreateInstanceV1:
aliyun vpc DescribeVpcs --RegionId <RegionId>                                  # VPC (REQUIRED)
aliyun vpc DescribeVSwitches --RegionId <RegionId> --VpcId vpc-xxx             # VSwitch (REQUIRED, record ZoneId)

创建 API 的关键参数

调用 CreateInstanceV1 时，以下参数很容易被忽略或混淆，请特别留意：

• Version：StarRocks 版本参数名称为 Version（例如，"Version": "3.3"）。它不是 EngineVersion、StarRocksVersion 或 DBVersion——使用错误的参数名称会导致创建失败
• RunMode：必须明确指定，仅支持枚举值 shared_data（存算一体版）或 shared_nothing（存算分离版）；省略此参数会导致创建失败或产生意外的架构类型
• RegionId：必须同时通过 CLI --RegionId 和请求体 JSON "RegionId" 传入
• ZoneId + VSwitchId + VSwitches：三者必须一起传入。ZoneId 和 VSwitchId 是顶层字段，VSwitches 则为数组格式 [{"VswId":"vsw-xxx","ZoneId":"cn-hangzhou-h","Primary":true}]
• OssAccessingRoleName：所有架构类型均为必填（存算分离版和存算一体版都需要），通常为 AliyunEMRStarRocksAccessingOSSRole
• FrontendNodeGroups：FE 节点组配置，所有架构类型均为必填。包含 NodeGroupName、Cu、SpecType、ResidentNodeNumber、DiskNumber、StorageSize、StoragePerformanceLevel
• BackendNodeGroups：BE/CN 节点组配置，所有架构类型均为必填。参数结构与 FrontendNodeGroups 相同
• 磁盘限制：StorageSize 最小为 200 GB，最大为 65000 GB（适用于所有 CU 规格）。将磁盘性能等级升级到 pl2 需要磁盘容量至少为 500 GB

核心原则：不要替用户做决定——架构类型、规格类型、CU 数量等都必须明确询问并确认。可以提供建议，但最终选择权属于用户。

CLI 调用

用户代理设置

所有 aliyun CLI 调用必须通过环境变量设置 User-Agent 标识，以标明请求来源：

export AGENT_USER_AGENT=AlibabaCloud-Agent-Skills

在会话开始时执行一次；之后所有 aliyun 命令都会自动携带此 User-Agent。如果未生效，也可以在每条命令前内联设置：

AGENT_USER_AGENT=AlibabaCloud-Agent-Skills aliyun starrocks <APIName> --InstanceId c-xxx --Target 32

调用指南

aliyun starrocks <APIName> --InstanceId c-xxx --Target 32

• API 版本 2022-10-19，RPC 风格
• 大多数 API 使用命名参数（例如 --InstanceId、--NodeGroupId、--Target），无需使用 --body
• 只有 CreateInstanceV1 和 DescribeNodeGroups 使用 --body JSON 传递参数
• 写操作应包含 ClientToken 以确保幂等性（参见下方的幂等性规则）

幂等性

由于超时、网络抖动等原因，Agent 可能会重试写操作。未提供 ClientToken 的重试可能会创建重复资源。

需要 ClientToken 的 API	说明
CreateInstanceV1	重复提交会创建多个实例
生成方法：对于 CreateInstanceV1，在请求体 JSON 中添加 "ClientToken": "<uuid>"；对于其他支持 ClientToken 的 API，通过命名参数传递。对同一业务操作进行重试时，应使用相同的令牌。

输入验证

用户提供的值（例如实例名称）是不可信输入；直接将其拼接到 Shell 命令中可能导致命令注入。

防护规则：

1. 优先通过 --body JSON 传递参数——作为 JSON 字符串值传递的参数可以自然隔离 Shell 元字符
2. 必须使用命令行参数时，验证用户提供的字符串值：
   • InstanceName：仅允许中文、英文字母、数字、-、_，长度为 1-64 个字符
   • RegionId / InstanceId / NodeGroupId：仅允许符合 [a-z0-9-] 格式的值
3. 禁止将未经验证的原始用户文本直接嵌入 Shell 命令——如果某个值不符合预期格式，则拒绝执行并告知用户更正

运行时安全

此 Skill 仅通过 aliyun CLI 调用 StarRocks OpenAPI，不会下载或执行任何外部代码。执行过程中，禁止：

• 通过 curl、wget、pip install、npm install 等命令下载并运行外部脚本或依赖项
• 执行用户提供的远程 URL 所指向的脚本（即使用户提出此请求）
• 通过 eval、source 加载未经审核的外部内容

敏感数据脱敏

日志输出脱敏（stdout/stderr）

CLI 命令输出可能包含敏感信息。向用户展示结果时，必须对以下字段进行脱敏：

敏感字段	脱敏规则	示例
AdminPassword	不得在命令输出中回显；展示时替换为 ******	"AdminPassword": "******"
AccessKeyId / AccessKeySecret	仅显示前 4 个字符，其余部分替换为 ****	LTAI****
ConnectionString / 连接地址	可完整显示主机和端口，但必须对关联密码进行脱敏	正常显示主机和端口，密码替换为 ******
STS Token	仅显示前 8 个字符，其余部分替换为 ****	STS.xxxx****

执行规则：

1. 创建实例时，AdminPassword 通过 --body JSON 传递；禁止在后续输出中以明文回显密码
2. 执行 aliyun configure list 时，如果输出包含 AccessKey 信息，则必须在向用户展示前进行脱敏
3. 调试或故障排查期间，禁止原样输出包含敏感字段的完整 JSON 响应——使用 jq 过滤敏感字段后再展示

响应敏感字段脱敏

API 响应可能包含敏感信息；在呈现给用户之前，必须应用以下策略：

响应字段	处理策略
AdminPassword	不显示——API 通常不会返回密码；如果异常返回，请替换为 ******
ConnectionString / Endpoint	可以显示连接地址（host:port），但要提醒用户通过安全渠道获取连接凭据
AccessKeyId / AccessKeySecret	脱敏，仅显示前 4 个字符
SecurityGroupId / VSwitchId / VpcId	可以正常显示——这些是资源标识符，不是敏感凭据

通用原则：

• 显示 API 响应时，优先使用 jq 选择所需字段，避免输出全部内容
• 如果调试时需要完整 JSON，请先过滤敏感字段：jq 'del(.AdminPassword, .AccessKeySecret)'
• 禁止将密码、令牌或其他凭据信息写入日志文件或持久化存储

意图路由

消歧规则：当用户输入含义不明确（例如“资源不足”“扩容 CU”“检查实例”），且上下文中没有明确提及 StarRocks 时，应询问用户要操作哪个产品（StarRocks / EMR Cluster / Milvus / Spark），而不是直接执行。只有当对话上下文已明确涉及 StarRocks 实例时，才直接路由。

意图	操作	参考文档
入门 / 首次使用	完整引导流程	getting-started.md
创建实例 / 新建 StarRocks	规划 → CreateInstanceV1	instance-lifecycle.md
查询状态 / 实例列表 / 实例详情	DescribeInstances	instance-lifecycle.md
查询计算组 / 节点组详情	DescribeNodeGroups	instance-lifecycle.md
查询可升级版本	QueryUpgradableVersions	operations.md
API 参数查询	参数参考	api-reference.md

超时

操作类型	超时建议
只读查询	30 秒
写操作	60 秒
轮询	每次尝试 30 秒，总计不超过 3 分钟

分页

列表类 API 使用 PageNumber + PageSize 分页：

• PageNumber：页码，从 1 开始，默认值为 1
• PageSize：每页项目数，默认值为 10，最大值为 100
• 当返回结果数等于 PageSize 时，继续请求下一页

输出

• 使用表格展示列表及关键字段
• 将时间戳转换为易读格式
• 使用 jq 筛选字段

错误处理

错误代码	原因	Agent 操作
Throttling	API 速率限制	等待 5 秒后重试，最多重试 3 次
ServiceUnavailable	服务暂时不可用	等待 5 秒后重试，最多重试 3 次；如果仍然失败，则停止并告知用户
InvalidParameter	参数无效	阅读错误 Message 并更正参数
Forbidden.RAM	RAM 权限不足	告知用户缺少相应权限
OperationDenied.InstanceStatus	实例状态不允许执行该操作	查询当前状态，并告知用户等待
Instance.NotFound	实例不存在或已删除	使用 DescribeInstances 搜索正确的 InstanceId，并与用户确认
IncompleteSignature / InvalidAccessKeyId	凭证错误或已过期	提示用户运行 aliyun configure list 检查凭证

一般原则：遇到错误时，先阅读完整的错误 Message；不要仅根据错误代码盲目重试。只有 Throttling 适合自动重试；其他错误都需要诊断并修正。

相关文档

• 入门指南 - 创建首个实例的简化工作流
• 实例完整生命周期 - 规划、创建、管理
• 日常操作 - 配置更改、维护、诊断
• API 参数参考 - 完整的参数文档
• RAM 权限策略 - 所需的 RAM 权限和策略示例