返回技能市场
开发运维 安全

阿里云 Tair 开发工具

@aliyun/alibabacloud-tair-devtoolset

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

云Skills门户 热度 101v0.0.3

Tair DevToolset——Tair 全生命周期开发助手

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

注意： 此 Skill 通过阿里云 CLI 执行真实的云上操作。恢复操作属于高风险操作，会覆盖当前数据。使用前，请确保 RAM 账号具备[所需权限](references/ram-policies.md)。

支持的能力

| 能力 | 描述 | |------------|-------------| | 架构选型 | 选择合适的 Tair 架构（标准架构或集群架构）和版本类型（内存优化型、持久内存型、磁盘型） | | 数据结构设计 | 根据您的使用场景选择最优的 Redis 和 Tair 扩展数据结构 | | 实例创建 | 通过阿里云 CLI 创建并配置 Tair 实例 | | 连接管理 | 使用单机/代理/集群模式连接，并支持 TLS | | 性能监控 | 通过 alibabacloud-tair-ai-assistant skill 进行智能诊断 | | 错误排查 | 诊断并解决常见的 Tair 连接、集群、内存和客户端错误 | | 备份与恢复 | 配置备份策略、执行 PITR 并恢复数据 |

---

第一部分——通用事项

1. 前提条件

1.1 CLI 安装与版本

必须使用阿里云 CLI 3.3.3 或更高版本。 运行 aliyun version 进行验证。如果尚未安装或版本过低，请参阅 [references/cli-installation-guide.md](references/cli-installation-guide.md) 中的安装说明。

# Enable automatic plugin installation (required for r-kvstore plugin)
aliyun configure set --auto-plugin-install true

# Update existing plugins to latest version
aliyun plugin update

# Verify jq is installed (required for JSON parsing in scripts)
jq --version

1.2 身份认证

所有凭据配置均沿用现有的阿里云 CLI 设置。

安全规则：

  • 严禁读取、回显或打印 AK/SK 的值（例如，严禁执行 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
  • 严禁要求用户直接在对话或命令行中输入 AK/SK
  • 严禁在 aliyun configure set 中使用字面量形式的凭据值
  • 仅可使用 aliyun configure list 检查凭据状态
aliyun configure list

如果不存在有效的配置文件，请在此处停止。 请在本会话之外配置凭据，然后返回。

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](references/ram-policies.md)。

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

3. 参数确认规则

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

---

第 II 部分——能力

4. 架构选型

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

适用场景

  • 在标准架构和集群架构之间进行选择
  • 确定是否需要读写分离
  • 选择版本类型（内存优化型、持久内存型、磁盘型）
  • 评估新项目应使用 Tair 还是开源 Redis

核心指南

核心概念：

| 组件 | 描述 | |-----------|-------------| | 节点 | 最小单元，运行与 Redis 兼容的进程 | | 分片 | 存储部分数据的一组节点 | | 主节点 | 处理写操作 | | 副本节点 | 主节点的副本，提供故障转移能力 | | 只读节点 | 仅处理读流量（读写分离） | | 代理节点 | 将请求路由到相应节点 |

架构对比：

| 维度 | 标准架构 | 集群架构 | |-----------|----------|---------| | 结构 | 一个主节点 + 多个副本节点 | 多个分片，每个分片包含一个主节点 + 多个副本节点 | | 数据分区 | 否（单分片） | 是（跨分片分布） | | 适用场景 | 数据量小、QPS 稳定 | 数据量大、QPS 高、吞吐量需求高 | | 读写分离 | 支持 | 支持 |

选型决策树：

Data volume > single-node capacity?
├── Yes → Cluster architecture
│   └── Read-heavy? → Enable read/write splitting
└── No → Standard architecture
    └── Read-heavy? → Enable read/write splitting

参考资料

  • [references/architecture-selection/arch-selection.md](references/architecture-selection/arch-selection.md)——架构选型决策指南
  • [references/architecture-selection/arch-compare-oss-redis.md](references/architecture-selection/arch-compare-oss-redis.md)——Tair 与开源 Redis 对比及版本选择

---

5. 数据结构设计

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

使用场景

  • 为新功能或应用选择数据结构
  • 在 Redis 原生数据结构与 Tair 扩展数据结构之间进行选择
  • 迁移数据模型并评估其他结构方案

核心指南

Redis 数据结构：

| 名称 | 应用场景 | |------|----------| | 字符串 | 缓存、计数器、分布式锁、会话存储、限流 | | 哈希 | 对象存储（用户资料、商品信息）、分组字段值对 | | 列表 | 消息队列、最新信息流、任务队列、栈/队列操作 | | 集合 | 无重复元素集合、标签、社交图谱（关注者/好友）、集合运算 | | 有序集合 | 排行榜、排名系统、优先队列、按分数进行范围查询 | | 流 | 事件溯源、日志流、支持消费者组的消息队列 | | 位图 | 功能开关、在线状态跟踪、日活跃用户计数 | | 位域 | 紧凑型计数器、定宽整数编码、原子递增 | | 地理空间 | 基于位置的服务、附近搜索、地理围栏 | | HyperLogLog | 独立访客计数、以极少内存进行基数估算 |

Tair 数据结构：

| 名称 | 应用场景 | |------|----------| | exString / TairString（字符串增强） | 支持版本控制的字符串、带边界限制的 INCRBY、用于分布式锁的 CAS/CAD | | exHash / TairHash（哈希增强） | 字段级 TTL、字段版本控制、多设备登录管理 | | exZset / TairZset（有序集合增强） | 多维评分（256 维）、多条件排名 | | GIS / TairGis（地理空间增强） | 点、线和多边形查询、空间关系检查 | | 文档 / TairDoc（JSON） | 采用二叉树索引的 JSON，可快速访问子元素 | | Search / TairSearch | 类似 ES 的全文搜索、多列索引、分词 | | TS / TairTs (TimeSeries) | 实时监控、IoT 数据、两级时间线聚合 | | Bloom / TairBloom | 概率型成员检测、去重、URL 过滤 | | Cpc / TairCpc | 压缩基数估计、流式分析 | | Roaring / TairRoaring（位图增强） | 用户分群、受众定向、多位图操作 | | Vector / TairVector | 向量相似性搜索、LLM 聊天机器人、多模态检索 |

参考资料

---

6. 实例创建

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

适用场景

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

6.1 选择实例规格

必填参数：

| 参数 | 描述 | 示例 | |-----------|-------------|---------| | VPC_ID | VPC ID | vpc-bp1xxx | | VSWITCH_ID | VSwitch ID | vsw-bp1xxx |

可选参数（含默认值）：

| 参数 | 默认值 | 描述 | |-----------|---------|-------------| | REGION_ID | cn-hangzhou | 地域 ID | | ZONE_ID | cn-hangzhou-h | 可用区 ID | | INSTANCE_TYPE | tair_rdb | 实例系列：tair_rdb（DRAM）、tair_scm（持久内存）、tair_essd（ESSD 磁盘） | | INSTANCE_CLASS | tair.rdb.1g | 实例规格（见下表） | | INSTANCE_NAME | tair-benchmark-<timestamp> | 实例名称 | | CHARGE_TYPE | PostPaid | 计费方式：PostPaid（按量付费）、PrePaid（包年包月） |

常用规格（标准架构）：

| InstanceClass | 内存 | 带宽 | 最大连接数 | QPS 参考值 | |---------------|--------|-----------|-----------------|---------------| | tair.rdb.1g | 1 GB | 768 Mbps | 30,000 | 300,000 | | tair.rdb.2g | 2 GB | 768 Mbps | 30,000 | 300,000 | | tair.rdb.4g | 4 GB | 768 Mbps | 40,000 | 300,000 | | tair.rdb.8g | 8 GB | 768 Mbps | 40,000 | 300,000 | | tair.rdb.16g | 16 GB | 768 Mbps | 40,000 | 300,000 | | tair.rdb.24g | 24 GB | 768 Mbps | 50,000 | 300,000 | | tair.rdb.32g | 32 GB | 768 Mbps | 50,000 | 300,000 | | tair.rdb.64g | 64 GB | 768 Mbps | 50,000 | 300,000 |

6.2 自动化工作流（脚本）

如需快速完成支持公网访问的端到端实例创建，请使用一体化脚本：

执行约束：
- 必须 在此工作流中使用 scripts/create-and-connect-test.sh——不得绕过该脚本，直接调用各个 aliyun r-kvstore 命令
- 不得 编写或拼接阿里云 CLI 命令来替代脚本功能
- 模型的职责：收集参数 → 设置环境变量 → 运行脚本
export VPC_ID="<user-confirmed VPC_ID>"
export VSWITCH_ID="<user-confirmed VSWITCH_ID>"

# Optional parameters
export REGION_ID="cn-hangzhou"
export ZONE_ID="cn-hangzhou-h"
export INSTANCE_TYPE="tair_rdb"
export INSTANCE_CLASS="tair.rdb.1g"
# For NAT environment, manually set public 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. 连接管理

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

适用场景

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

关键指南

连接模式：

| 模式 | 架构 | 描述 | |------|-------------|-------------| | 单机/代理 | 标准架构或集群架构（代理模式） | 通过代理节点连接；支持所有 Redis 命令，包括跨槽位多键命令 | | 集群直连 | 集群架构（直连模式） | 直接连接到数据节点；需要具备集群感知能力的客户端；不支持跨槽位多键命令 | | TLS | 任意架构（叠加模式） | 使用 TLS/SSL 加密连接；同时支持代理和直连模式 |

身份验证格式：

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

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

参考资料

  • [references/connection-management/connect-standalone-or-proxy.md](references/connection-management/connect-standalone-or-proxy.md)——Java、Python、PHP、.NET、Go、Spring Data Redis 的独立/代理连接示例
  • [references/connection-management/connect-cluster.md](references/connection-management/connect-cluster.md)——集群连接示例（JedisCluster、RedisCluster、LettuceCluster、go-redis 集群、redis-cli）
  • [references/connection-management/connect-with-tls.md](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](references/performance-monitoring/perf-monitoring.md)——性能监控参考资料
  • alibabacloud-tair-ai-assistant

---

9. 错误排查

诊断并解决 Tair 中涉及身份验证、连接、集群、内存、代理、Lua/事务以及特定客户端的常见错误。

适用场景

  • 遇到身份验证或连接错误
  • 解决集群相关错误（跨槽位、键已移动、只读）
  • 处理内存耗尽或命令错误
  • 调试特定客户端的问题（Jedis、Lettuce、Redisson、go-redis 等）

关键指南

常见错误类别：

| 类别 | 错误示例 | 典型原因 | |----------|---------------|---------------| | 身份验证 | NOAUTH Authentication required, WRONGPASS | 未提供密码、密码错误，或 Lettuce CLIENT SETINFO 缺陷 | | 连接 | ERR illegal address, max number of clients reached | 客户端 IP 不在白名单中、连接池泄漏、DNS 故障 | | 集群 | CROSSSLOT Keys in request don't hash to the same slot, MOVED | 多键命令跨槽位执行、键已移至其他节点 | | 内存/命令 | OOM command not allowed, WRONGTYPE, ERR unknown command | 内存超限、数据类型错误、命令不受支持 | | 代理模式 | client ip is not in whitelist, redis temporary failure | 代理白名单、子实例超时、请求队列溢出 | | Lua/事务 | BUSY Redis is busy running a script, NOSCRIPT | Lua 脚本长时间运行、脚本 SHA 不在缓存中 | | 客户端特定问题 | Jedis 报 Could not get a resource from the pool，Lettuce 使用正确密码时仍报 NOAUTH，go-redis 集群格式 panic | 连接池耗尽、版本不兼容、RESP2/RESP3 不匹配 |

参考资料

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

---

10. 备份与恢复

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

适用场景

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

关键指导

持久化策略：

| 策略 | 机制 | 关键特性 | |--------|-----------|-------------| | RDB | 定期快照 | 文件小，备份过程不阻塞 | | AOF | 记录所有写操作 | 默认每秒执行一次 Fsync，AOF 重写可减少磁盘占用 | | Tair-Binlog | 增量 AOF 归档（仅限企业版 DRAM） | 避免 AOF 重写导致性能下降，并支持精确到秒的 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](references/backup-and-recovery/backup-recovery.md)——包含 CLI 示例和数据保护详情的完整备份与恢复指南
  • 数据备份与恢复策略

---

参考资料索引

| 参考资料 | 描述 | 适用范围 | |-----------|-------------|-------| | [references/cli-installation-guide.md](references/cli-installation-guide.md) | 阿里云 CLI 安装与配置指南 | 通用 | | [references/ram-policies.md](references/ram-policies.md) | RAM 权限策略文档 | 通用 | | [references/acceptance-criteria.md](references/acceptance-criteria.md) | CLI 命令正确性标准 | 通用（QA） | | [references/related-commands.md](references/related-commands.md) | 完整的 CLI 命令和参数参考 | 实例创建 | | [references/verification-method.md](references/verification-method.md) | 成功验证步骤 | 实例创建 | | [references/architecture-selection/arch-selection.md](references/architecture-selection/arch-selection.md) | 架构选型决策指南 | 架构选型 | | [references/architecture-selection/arch-compare-oss-redis.md](references/architecture-selection/arch-compare-oss-redis.md) | Tair 与开源 Redis 对比 | 架构选型 | | [references/data-structure-design/data-structure-design.md](references/data-structure-design/data-structure-design.md) | 详细的数据结构用例 | 数据结构设计 | | [references/instance-creation/connect-create-instance.md](references/instance-creation/connect-create-instance.md) | 端到端实例创建与连接指南 | 实例创建 | | [references/connection-management/connect-standalone-or-proxy.md](references/connection-management/connect-standalone-or-proxy.md) | 单机/代理连接示例 | 连接管理 | | [references/connection-management/connect-cluster.md](references/connection-management/connect-cluster.md) | 集群连接示例 | 连接管理 | | [references/connection-management/connect-with-tls.md](references/connection-management/connect-with-tls.md) | TLS 连接示例（代理 + 直连） | 连接管理 | | [references/performance-monitoring/perf-monitoring.md](references/performance-monitoring/perf-monitoring.md) | 性能监控与诊断 | 性能监控 | | [references/error-troubleshooting/errors-troubleshooting.md](references/error-troubleshooting/errors-troubleshooting.md) | 包含原因和解决方案的完整错误表 | 错误排查 | | [references/backup-and-recovery/backup-recovery.md](references/backup-and-recovery/backup-recovery.md) | 包含 CLI 示例的备份与恢复策略 | 备份与恢复 |

qianwen skills install @aliyun/alibabacloud-tair-devtoolset