SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场debugging-with-ably-cli

debugging-with-ably-cli

编程与开发

查看项目

更新于 10-15 11:10

技能介绍

用途

本技能用于在终端中诊断 Ably 实时通信问题。Ably CLI（包名 @ably/cli，安装命令 npm install -g @ably/cli）可以观察、测试和模拟 Ably 操作，比 console.log 或浏览器 DevTools 更快。CLI 自带文档：运行 ably --help 查看命令组，运行 ably <command> --help 查看子命令、参数和示例。

主要能力

诊断决策树

技能提供按症状分类的排查路径：

  • 消息未到达：检查频道上是否有人、是否发布过内容（无持久化时历史仅 2 分钟）、实时订阅、往返测试、检查频道生命周期。
  • Presence 不工作：查看实际在线成员、模拟客户端加入、检查成员数（非正常断连约 15 秒后才移除）、订阅 presence 事件。
  • 连接问题：测试连接（分别尝试 ws 与 xhr）、检查服务状态、订阅连接生命周期日志、对比连接数与套餐上限。
  • 认证错误：验证 API key、查看 key 能力、用 CLI 签发测试 token、检查 token 过期（40142）与续期配置、查询错误码。
  • 频道状态/生命周期问题：订阅频道生命周期日志、订阅全部日志、检查占用、查看频道规则。
  • 推送通知不工作：订阅推送日志、查询推送日志历史、检查命名空间是否启用推送、检查集成规则。
  • 集成规则未触发：列出集成、核对 source type（channel.message、channel.presence、channel.lifecycle、presence.message）、核对频道过滤、检查启用状态、检查投递错误。
  • 队列问题：列出队列、检查集成是否路由到队列（AMQP 规则目标）、订阅源频道验证消息存在。
  • 聊天室问题（@ably/chat）：订阅房间消息（若 CLI 能看到而应用看不到，通常缺少 room.attach()）、检查房间 presence、检查占用、检查底层频道事件、发送测试消息。
  • Spaces 问题（@ably/spaces）：查看空间成员、订阅光标、订阅位置、检查锁。

关键调试事实

  • 频道名区分大小写，发布者与订阅者名称不一致是常见 bug。
  • 历史默认仅 2 分钟；无持久化时只覆盖连接恢复窗口，需检查频道规则中的 persisted: true。
  • Presence 需要 clientId 和 capability：clientId 必须在连接时设置；进入 presence 需要 presence 能力，订阅 presence 事件需要 subscribe 能力；能力不足会返回 40160。
  • 频道名上的能力作用域：publish:["chat:*"] 允许向以 chat: 开头的频道发布，但不允许向名为 chat 的频道发布，这是 40160 的常见原因。
  • Token 过期（40142）：若客户端未配置 authUrl 或 authCallback 续期，token 过期后连接与请求都会失败。
  • Presence 移除延迟：非正常断连约 15 秒后才被移除。
  • 占用可揭示重复订阅：订阅者数远高于预期时，检查 React StrictMode、缺少 useEffect 清理、多个 Ably 客户端实例。
  • Token 与 key 能力：token 权限是 key 权限与 token 中指定权限的交集，排查 40160 需同时检查 key 能力和服务端 token 创建代码。
  • 元频道日志需要 [meta]* 能力：ably logs 命令订阅日志元频道，作用域为 * 的 key 不匹配元频道，需要 [meta]* 或 []。应用根 API key 默认具有 []。若 ably logs 报 40160，检查 key 能力作用域。单频道深度检查可用 ably channels inspect <channel> 打开仪表盘频道检查器，它使用 CLI 目前不可用的特权检查元频道（[meta]inspect:*）。
  • 传输回退：WebSocket 被阻断时 SDK 回退到 XHR 流式传输，应分别测试两种传输。
  • 非默认环境：若应用使用沙箱或自定义环境，用 ably accounts login --endpoint <host> 登录目标集群。
  • 错误消息文本比错误码更重要：错误码是宽泛分类（如 40000 涵盖多种变体），应阅读具体错误消息。每个错误码有帮助页 help.ably.io/error/{code}，也可用 ably support ask "error {code}"。

使用方式

CLI 认证

两种方式：

  1. 从项目获取凭据（快速，无需登录）：设置 ABLY_API_KEY 环境变量，从项目环境文件导出（如 export ABLY_API_KEY=...）；若有 token（如来自应用认证服务器），改用 ABLY_TOKEN。若 key 属于生产应用，使用前应告知用户。
  2. 登录 CLI（用于扩展调试或账户级命令）：ably login 打开浏览器进行 OAuth。登录后用 ably apps list 和 ably apps switch 选择应用，用 ably auth keys list 查看可用 key 及其能力。

若无可用凭据，请用户检查 Ably 环境变量（如 ABLY_API_KEY）是否设置，或运行 ably login 认证。

CLI 能做什么

观察（只读）：实时订阅频道、presence、占用、日志和统计。包括频道消息（支持通配符和 rewind 重放）、presence、占用、日志元频道（可按 channel.lifecycle、channel.occupancy、channel.presence、connection.lifecycle、push.publish 过滤）、推送通知日志、历史、统计（含实时轮询模式）、频道列表（支持前缀过滤）、连接测试（WebSocket、XHR）。

模拟：作为参与者模拟对话一端。包括发布（事件名、JSON 或纯文本，可配置次数与延迟）、批量发布、presence enter（自定义 client ID 和数据）、Chat（消息、presence、输入状态、反应）、Spaces（成员、光标、位置、锁）、基准测试（发布/订阅吞吐量与延迟）。

管理：查询和修改应用配置。包括频道规则（命名空间，持久化、推送、仅 TLS、批处理、合并、频道注册表）、API key（列出能力、创建、撤销、切换）、token 签发（JWT 或 Ably token，也可撤销）、应用（列出、创建、切换、配置）、集成（webhook、Lambda、Kafka、AMQP 等，检查 source type、频道过滤、启用状态）、队列（列出、创建、删除）。

获取帮助：AI 支持代理（由 Inkeep 提供）ably support ask "your question"，可用 --continue 追问；服务状态 ably status。

长运行命令

许多命令（subscribe、presence enter、stats --live、occupancy subscribe）会持续输出直到 Ctrl+C 或 --duration N 到期。应作为后台任务运行，避免阻塞工作流：后台启动订阅，复现问题，再检查输出。

连接与频道状态参考

连接状态：connecting（尝试连接，启动时正常，卡住则检查网络/认证）、connected（WebSocket 活跃，健康）、disconnected（临时丢失，SDK 重试，偶发正常，反复出现为网络问题）、suspended（离线超 2 分钟，重试频率降低）、failed（永久失败，SDK 不再重试，几乎总是认证问题）、closed（代码显式关闭）。

频道状态：initialized（频道对象已创建但未附加）、attaching（请求附加，卡住则检查连接状态与认证能力）、attached（活跃，消息流动）、detaching（请求分离）、detached（未附加，无消息流动）、suspended（附加失败将重试，通常跟随连接挂起）、failed（永久失败，常为能力被拒 40160 或频道名无效）。

适用场景

适用于使用 Ably 实时通信的开发者排查消息、presence、连接、认证、频道生命周期、推送、集成、队列、Chat 和 Spaces 相关问题，也适用于在终端中模拟客户端或服务端进行联调与基准测试。

限制

  • 无持久化时频道历史仅 2 分钟。
  • CLI token 签发测试的是 key，而非应用的 authUrl/authCallback。
  • ably logs 需要 [meta]* 能力；单频道深度检查需通过 ably channels inspect 打开仪表盘，CLI 目前无法直接使用特权检查元频道。
  • 非正常断连的 presence 移除约需 15 秒。
  • 具体收费、价格、平台支持范围等资料未提供。