alibabacloud-tair-devtoolset：为客户创建云原生 Tair 企业版实例，配置公网访问，方便客户使用 AI 助理无感快速搭建本地开发调试环境。

Tair 开发工具集 —— Tair 全生命周期开发助手

本 Skill 为阿里云 Tair（兼容 Redis OSS）数据库提供操作能力和开发指引，覆盖架构选型、数据结构设计、实例创建、连接管理、性能监控、错误排查和备份恢复。

注意： 本 Skill 通过 aliyun CLI 执行真实云操作。恢复操作属高风险，将覆盖当前数据。使用前请确保 RAM 账号具备所需权限。

支持的能力

第一部分 —— 跨领域关注点

1. 前置条件

1.1 CLI 安装与版本

需要 Aliyun CLI >= 3.3.3。 运行 aliyun version 确认。若未安装或版本过低，见 references/cli-installation-guide.md 获取安装说明。

启用插件自动安装（r-kvstore 插件必需）

aliyun configure set --auto-plugin-install true

更新已有插件到最新版本

aliyun plugin update

验证 jq 已安装（脚本 JSON 解析必需）

jq --version

### 1.2 鉴权

所有凭证配置沿用现有 aliyun CLI 设置。

**安全规则：**
- **绝不**读取、回显或打印 AK/SK 值（例如 `echo $ALIBABA_CLOUD_ACCESS_KEY_ID` 是禁止的）
- **绝不**要求用户在对话或命令行中直接输入 AK/SK
- **绝不**使用字面凭证值运行 `aliyun configure set`
- **只**使用 `aliyun configure list` 检查凭证状态

aliyun configure list

**如果不存在有效 profile，就此停止。** 在本会话之外配置凭证，然后返回。

### 1.3 AI-Mode 配置

> **[必须] 在任何工作流开始时启用 AI-Mode**（任何 CLI 调用之前）：
> ```bash
> aliyun configure ai-mode enable
> aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset"
> ```

> **[必须] 在每个退出点禁用 AI-Mode** —— 在因任何原因（成功、失败、错误、用户取消等）交付最终回复之前。Skill 停止运行后 AI-mode **不得**保持启用。
> ```bash
> aliyun configure ai-mode disable
> ```

2. 安全与合规

2.1 User-Agent 要求

每次 aliyun CLI 命令调用都必须包含：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

2.2 RAM 权限

本 Skill 需要 R-KVStore RAM 权限用于实例管理、备份和恢复操作。完整权限表和策略文档见 references/ram-policies.md。

[必须] 权限失败处理： 当任何命令因权限错误失败时：
1. 阅读 references/ram-policies.md 获取所需权限完整列表
2. 使用 ram-permission-diagnose skill 引导用户申请权限
3. 暂停并等待用户确认所需权限已授予

3. 参数确认规则

执行任何命令或 API 调用前，所有用户可自定义的参数（例如 RegionId、实例名、密码、资源规格）都必须与用户确认。未经用户明确批准，不要假设或使用默认值。

第二部分 —— 能力

4. 架构选型

根据数据量、吞吐要求和读写比选择正确的 Tair 架构。

使用时机

• 在标准版和集群版架构间决策
• 确定是否需要读写分离
• 选择版本类型（内存型、持久内存型、磁盘型）
• 为新项目评估 Tair vs 开源 Redis

关键指引

核心概念：

架构对比：

选型决策树：

数据量 > 单节点容量？
├── 是 → 集群版架构
│   └── 读多？ → 启用读写分离
└── 否 → 标准版架构
    └── 读多？ → 启用读写分离

参考

• references/architecture-selection/arch-selection.md —— 架构选型决策指南
• references/architecture-selection/arch-compare-oss-redis.md —— Tair vs 开源 Redis 对比和版本选型

5. 数据结构设计

根据你的访问模式和业务需求选择合适的数据结构。

使用时机

• 为新功能或应用选择数据结构
• 在 Redis 原生和 Tair 扩展数据结构间选择
• 迁移数据模型并评估结构替代方案

关键指引

Redis 数据结构：

Tair 数据结构：

参考

• references/data-structure-design/data-structure-design.md —— 详细数据结构用例说明
• Redis 数据类型
• Tair 扩展数据结构

6. 实例创建

在阿里云上创建和配置 Tair 实例，包括白名单配置和公网端点分配。

使用时机

• 为测试、开发或生产创建新的 Tair 实例
• 为实例配置网络访问（白名单、公网端点）
• 搭建 Tair 基准测试或 PoC 环境

6.1 选择实例规格

必需参数：

可选参数（含默认值）：

常用规格（标准架构）：

6.2 自动化工作流（脚本）

要快速端到端创建带公网访问的实例，使用一体化脚本：

执行约束：
- 必须使用 scripts/create-and-connect-test.sh 执行此工作流——不要绕过脚本直接调用单个 aliyun r-kvstore 命令
- 不要编写或拼接 aliyun CLI 命令来替代脚本功能
- 模型职责：收集参数 → 设置环境变量 → 运行脚本

export VPC_ID="<用户确认的 VPC_ID>"
export VSWITCH_ID="<用户确认的 VSWITCH_ID>"

可选参数

export REGION_ID="cn-hangzhou"

export ZONE_ID="cn-hangzhou-h"

export INSTANCE_TYPE="tair_rdb"

export INSTANCE_CLASS="tair.rdb.1g"

NAT 环境下手动设置公网 IP

export MY_PUBLIC_IP="your-public-ip"

bash scripts/create-and-connect-test.sh

脚本将自动完成：创建实例 → 等待就绪 → 配置白名单 → 分配公网端点 → 获取公网连接信息。

### 6.3 手动 CLI 步骤

对于自定义需求（PrePaid 包年包月、无公网端点、自定义安全组等），使用手动 CLI 步骤：

**步骤 1 —— 创建实例：**

aliyun r-kvstore create-tair-instance \

--biz-region-id "$REGION_ID" --zone-id "$ZONE_ID" \

--vpc-id "$VPC_ID" --vswitch-id "$VSWITCH_ID" \

--instance-type "$INSTANCE_TYPE" --instance-class "$INSTANCE_CLASS" \

--password "$PASSWORD" --charge-type "$CHARGE_TYPE" \

--shard-type "MASTER_SLAVE" \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

**步骤 2 —— 等待实例就绪**（轮询直到 `InstanceStatus` 为 `Normal`）：

aliyun r-kvstore describe-instance-attribute \

--instance-id "$INSTANCE_ID" \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

**步骤 3 —— 配置白名单：**

aliyun r-kvstore modify-security-ips \

--instance-id "$INSTANCE_ID" --security-ips "$MY_PUBLIC_IP" \

--security-ip-group-name "default" \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

**步骤 4 —— 分配公网端点：**

aliyun r-kvstore allocate-instance-public-connection \

--instance-id "$INSTANCE_ID" \

--connection-string-prefix "${INSTANCE_ID}pub" --port "6379" \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

### 6.4 成功验证

aliyun r-kvstore describe-instance-attribute \

--instance-id "$INSTANCE_ID" \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset

确认 `InstanceStatus` 为 `Normal` 且公网端点已分配。完整 3 步验证（实例状态、白名单、公网端点）见 [references/verification-method.md](references/verification-method.md)。

### 参考

- [references/instance-creation/connect-create-instance.md](references/instance-creation/connect-create-instance.md) —— 端到端实例创建和连接指南，含 redis-cli 示例
- [references/related-commands.md](references/related-commands.md) —— 完整 CLI 命令和参数参考
- [references/verification-method.md](references/verification-method.md) —— 详细成功验证步骤
- [references/acceptance-criteria.md](references/acceptance-criteria.md) —— CLI 命令正确性标准

---

7. 连接管理

以单机、代理、集群或 TLS 模式使用各种 Redis 兼容客户端连接 Tair 实例。

使用时机

• 从应用代码连接 Tair 实例
• 选择合适的客户端库和连接模式
• 为安全连接配置 TLS/SSL 加密
• 排查连接问题

关键指引

连接模式：

鉴权格式：

• 默认账号：仅密码
• 自定义账号：<user>:<password>
• redis-cli：使用 REDISCLI_AUTH 环境变量——export REDISCLI_AUTH='InstanceID:Password'

支持的客户端： Jedis、Lettuce、Redisson（Java）；redis-py（Python）；Predis、phpredis（PHP）；StackExchange.Redis（.NET）；go-redis（Go）；node-redis（Node.js）；Spring Data Redis

参考

• references/connection-management/connect-standalone-or-proxy.md —— Java、Python、PHP、.NET、Go、Spring Data Redis 的单机 / 代理连接示例
• references/connection-management/connect-cluster.md —— 集群连接示例（JedisCluster、RedisCluster、LettuceCluster、go-redis cluster、redis-cli）
• references/connection-management/connect-with-tls.md —— 所有客户端类型的 TLS/SSL 连接示例（代理 + 直连）

8. 性能监控

通过 Tair AI 助手（DAS API）进行智能性能监控和诊断。

使用时机

• 诊断慢查询或性能下降
• 分析内存使用，识别大 key / 热 key
• 调优实例参数和连接设置
• 监控实例健康和资源使用

关键指引

要使用智能诊断，安装并使用 alibabacloud-tair-ai-assistant skill：

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-tair-ai-assistant --agent <your-agent-platform>

AI 助手提供基于自然语言的诊断，覆盖：实例管理、性能分析、慢查询、内存分析、大 key / 热 key 检测、参数调优和连接排查。

参考

• references/performance-monitoring/perf-monitoring.md —— 性能监控参考
• alibabacloud-tair-ai-assistant

9. 错误排查

诊断并解决鉴权、连接、集群、内存、代理、Lua/事务和客户端特定等常见 Tair 错误。

使用时机

• 遇到鉴权或连接错误
• 解决集群相关错误（跨槽、moved、只读）
• 处理内存耗尽或命令错误
• 调试客户端特定问题（Jedis、Lettuce、Redisson、go-redis 等）

关键指引

常见错误类别：

参考

• references/error-troubleshooting/errors-troubleshooting.md —— 所有错误类别和客户端库的完整错误表，含原因和解决方案
• 常见错误与排查

10. 备份与恢复

配置备份策略、创建手动备份、从备份恢复数据，并执行按时间点恢复（PITR）。

使用时机

• 配置自动备份策略
• 在高风险操作前创建手动备份
• 从备份集恢复数据
• 执行按时间点恢复（PITR）或按键过滤恢复

关键指引

持久化策略：

关键 CLI 操作：

• modify-backup-policy —— 修改自动备份计划
• create-backup —— 创建手动备份
• describe-backups —— 查询可用备份集
• restore-instance —— 从备份集或时间点恢复
• 全量备份：--backup-id "$BACKUP_ID"
• PITR：--restore-type 1 --restore-time "2024-01-15T10:30:00Z"
• 按键过滤 PITR：加 --filter-key "session:*,user:*"

⚠️ 高风险操作 —— restore-instance 会覆盖当前数据且不可撤销。
执行任何恢复之前：
1. 验证当前写入流量 —— 检查实例是否有活跃写入；若有，通知用户
2. 创建最新备份 —— 运行 create-backup 保留当前数据作为回滚点
3. 与用户确认 —— 明确告知数据将被覆盖并获得确认

参考

• references/backup-and-recovery/backup-recovery.md —— 完整备份 / 恢复指南，含 CLI 示例和数据保护细节
• 数据备份与恢复策略

参考索引