alibabacloud-tair-devtoolset

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

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

注意： 此 Skill 通过 aliyun CLI 执行真实的云操作。恢复操作风险较高，会覆盖当前数据。使用前，请确保 RAM 账号拥有所需权限。

支持的能力

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

---

第一部分 — 跨领域事项

1. 先决条件

1.1 CLI 安装与版本

需要 Aliyun CLI >= 3.3.3。 运行 aliyun version 进行验证。如果尚未安装或版本过低，请参阅 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 身份验证

所有凭据配置均遵循现有 aliyun CLI 设置。

安全规则：

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

aliyun configure list

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

1.3 AI-Mode 配置

[MUST] 在任何工作流开始时启用 AI-Mode（在调用任何 CLI 之前）：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-tair-devtoolset"

[MUST] 在每个退出点禁用 AI-Mode——无论出于何种原因（成功、失败、错误、用户取消等），都必须在提供最终答复之前执行。Skill 停止运行后，AI-mode 不得保持启用状态。

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。

[MUST] 权限失败处理： 当任何命令因权限错误而失败时：

1. 阅读 references/ram-policies.md，获取所需权限的完整列表
2. 使用 ram-permission-diagnose skill 引导用户申请权限
3. 暂停操作并等待用户确认已授予所需权限

3. 参数确认规则

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

---

第二部分 — 能力

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-compare-oss-redis.md — Tair 与开源 Redis 对比及版本选择

---

5. 数据结构设计

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

使用时机

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

关键指南

Redis 数据结构：

名称	使用场景
String	缓存、计数器、分布式锁、会话存储、速率限制
Hash	对象存储（用户资料、产品信息）、分组的字段-值对
List	消息队列、最新动态流、任务队列、栈/队列操作
Set	唯一值集合、标签、社交关系图（关注者/好友）、集合操作
Sorted Set	排行榜、排名系统、优先级队列、按分值进行范围查询
Stream	事件溯源、日志流、带消费者组的消息队列
Bitmap	功能开关、在线状态跟踪、日活跃用户计数
Bitfield	紧凑计数器、定宽整数编码、原子递增
Geospatial	基于位置的服务、附近搜索、地理围栏
HyperLogLog	独立访客计数、以极少内存估算基数

Tair 数据结构：

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

参考资料

• references/data-structure-design/data-structure-design.md — 数据结构用例详细说明
• Redis Data Types
• Tair Extended Data Structures

---

6. 创建实例

在 Alibaba Cloud 上创建和配置 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 命令
• 不要编写或拼接 aliyun 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 步骤

如有自定义需求（包年包月、无公网终端节点、自定义安全组等），请使用手动 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/instance-creation/connect-create-instance.md — 实例创建与连接的端到端指南，包含 redis-cli 示例
• references/related-commands.md — 完整的 CLI 命令和参数参考
• references/verification-method.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'

支持的客户端： 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 集群、redis-cli）
• references/connection-management/connect-with-tls.md — 所有客户端类型的 TLS/SSL 连接示例（代理 + 直连）

---

8. 性能监控

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

适用场景

• 诊断慢查询或性能下降
• 分析内存使用情况并识别大键/热点键
• 调整实例参数和连接设置
• 监控实例健康状况和资源利用率

关键指南

如需智能诊断，请安装并使用 alibabacloud-tair-ai-assistant 技能：

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

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

参考资料

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

---

9. 错误排查

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

适用场景

• 遇到身份验证或连接错误
• 解决集群相关错误（跨槽、moved、只读）
• 处理内存耗尽或命令错误
• 调试特定客户端问题（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 — 所有错误类别和客户端库的完整错误表，包含原因和解决方案
• 常见错误和故障排除

---

10. 备份与恢复

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

适用场景

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

关键指南

持久化策略：

策略	机制	主要特性
RDB	定期快照	文件较小，备份不阻塞
AOF	记录所有写入操作	默认每秒执行一次 Fsync，AOF 重写可减少磁盘使用量
Tair-Binlog	增量 AOF 归档（仅限 Enterprise 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 — 完整的备份与恢复指南，包含 CLI 示例和数据保护详情
• 数据备份和恢复策略

---

参考资料索引

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