debugging-with-ably-cli

使用 Ably CLI 调试

Ably CLI（@ably/cli，通过 npm install -g @ably/cli 安装）可让你在终端中观察、测试和模拟 Ably 操作，比使用 console.log 或浏览器 DevTools 更快。

查找命令：运行 ably --help 查看命令组，运行 ably <command> --help 查看子命令、标志和示例。CLI 具备自助说明功能。本技能将介绍可以做什么，以及何时使用。

---

1. 诊断决策树

Messages not arriving
├── Is anyone on the channel?        → list channels with a prefix filter
├── Was anything published?          → check channel history (2 min only without persistence)
├── Can I see messages live?         → subscribe to the channel
├── Test round-trip                  → subscribe in background, publish from main terminal
└── Check channel lifecycle          → subscribe to channel lifecycle logs, or inspect the channel in the dashboard

Presence not working
├── Who is actually present?         → subscribe to presence on the channel
├── Simulate a client joining        → enter presence with custom client-id and data
├── Check presence member count      → get channel occupancy
│   (stale members? ungraceful disconnects take ~15s to be removed)
└── Watch all presence events        → subscribe to logs filtered by channel.presence, or inspect the channel in the dashboard

Connection problems
├── Can I connect at all?            → test connection (try ws and xhr separately)
├── Is Ably up?                      → check service status
├── Watch connection lifecycle       → subscribe to connection lifecycle logs
└── Connection count vs plan limit   → check app stats in live mode

Auth errors
├── Is the API key valid?            → test connection with the specific key
├── What capabilities does key have? → list auth keys
├── Using tokens (JWT or Ably)?      → issue a test token via CLI to verify the key can create valid tokens
│   (CLI token issuance tests the key, not your app's authUrl/authCallback)
├── Token expired (40142)?           → check TTL and renewal config (authUrl/authCallback)
└── Look up the error code           → ask the support agent or fetch help.ably.io/error/{code}

Channel state / lifecycle issues
├── Watch channel events             → subscribe to channel lifecycle logs
├── Watch all app meta events        → subscribe to all logs
├── Check channel occupancy          → get or subscribe to occupancy
└── Check channel rules/config       → list channel rules (persistence, TLS, push, etc.)

Push notifications not working
├── Watch push delivery logs         → subscribe to push logs (meta channel)
├── Check push log history           → get push log history
├── Is push enabled on namespace?    → list channel rules, check push-enabled
└── Check integration rules          → list integrations, check source type and channel filter

Integration rules not firing
├── List all integrations            → list integrations to see rules, source types, status
├── Check source type matches        → source can be channel.message, channel.presence,
│                                      channel.lifecycle, or presence.message
├── Check channel filter             → filter pattern must match the channel name
├── Is the rule enabled?             → check integration status (enabled/disabled)
└── Check for delivery errors        → check log history — the log metachannel captures
                                       errors sending on integrations

Queue issues
├── Are queues configured?           → list queues
├── Is the integration routing to it?→ list integrations, check AMQP rule target
└── Check message flow               → subscribe to the source channel to verify messages exist

Chat room issues (@ably/chat)
├── Are messages flowing?            → subscribe to room messages
│   (if CLI sees messages but app doesn't → room.attach() likely missing)
├── Check room presence              → subscribe to room presence
├── Check occupancy                  → get room occupancy
├── Check underlying channel events  → inspect the room's channels in the dashboard, or subscribe to channel lifecycle logs and look for the room's channel names
└── Send a test message              → send a message to the room from CLI

Spaces issues (@ably/spaces)
├── Who is in the space?             → subscribe to space members
├── Watch cursors                    → subscribe to space cursors
├── Watch locations                  → subscribe to space locations
└── Check locks                      → get all locks in the space

---

2. 重要调试事实

• **频道名称区分大小写。**发布者和订阅者的名称不匹配是常见错误。列出活跃频道，查看实际存在的频道。
• **历史记录默认保留 2 分钟。**未启用持久化时，历史记录仅涵盖 Ably 的连接恢复窗口。检查频道规则中的 persisted: true。如果未启用，请告知用户，并建议通过频道规则或控制面板启用。
• **Presence 需要 clientId 和 capability。**必须在连接时设置 clientId（不能在每次进入 Presence 时设置）。进入 Presence 需要 presence capability；订阅 Presence 事件需要 subscribe capability。客户端可以观察当前有哪些成员，而无需自己加入。缺少所需的 capability 时，Presence 操作会因 40160 失败。
• **频道名称上的 capability 范围。**拥有 publish:["chat:*"] 的密钥允许在以 chat: 开头的频道上发布（例如 chat:room-1），但不能在名称恰好为 chat 的频道上发布。冒号分隔符和通配符模式很重要，这是 40160 错误的常见原因。
• **Token 过期（40142）。**Token 有 TTL。如果客户端未配置 authUrl 或 authCallback 来续期，Token 就会过期；连接将失败，其他 API 请求也会被拒绝。通过 CLI 测试签发 Token，验证身份验证流程是否独立于应用正常工作。
• **Presence 移除延迟。**非正常断开连接的成员需要约 15 秒才会被 Ably 移除。
• **占用情况可揭示重复订阅。**如果订阅者数量远高于预期，请检查是否存在重复订阅（React StrictMode、缺少 useEffect 清理逻辑、多个 Ably 客户端实例）。
• **Token 与密钥的 capability。**密钥及由其签发的 Token 可以拥有不同的 capability；Token 的权限是密钥权限与 Token 中指定权限的交集。调试 40160 错误时，请同时检查密钥的 capability 和服务端的 Token 创建代码。
• **Metachannel 日志需要 [meta]* capability。**所有 ably logs 命令都会订阅日志 metachannel（[meta]log、[meta]channel.lifecycle 等）。范围为 * 的密钥不匹配 metachannel；密钥的 capability 资源列表中需要包含 [meta]* 或 [*]*。应用的根 API 密钥默认拥有 [*]*。如果 ably logs 命令因 40160 失败，请检查密钥的 capability 范围。若要深入检查单个频道（查看每个频道的统计数据、区域细分和已附加的集成），请使用 ably channels inspect <channel> 打开控制面板的频道检查器——该功能使用 CLI 当前不可用的特权检查 metachannel（[meta]inspect:*）。
• **传输回退。**如果 WebSocket 被阻止，SDK 会回退到 XHR 流式传输。分别测试两种传输方式，确认哪种可用。
• **非默认环境。**如果应用使用沙盒或自定义环境，请使用 ably accounts login --endpoint <host> 登录，以连接到正确的集群。
• **错误消息文本比错误代码更重要。**Ably 错误代码只是宽泛的类别（例如，40000 涵盖多种情况）。务必阅读错误消息文本，了解具体原因。每个错误代码都有对应的帮助页面：help.ably.io/error/{code}；也可以使用 ably support ask "error {code}"。

---

3. CLI 身份验证

CLI 需要凭据。有两种方式：

使用项目中的凭据（快捷，无需登录）： 将 ABLY_API_KEY 设置为环境变量。从项目的环境文件中找到密钥并导出（例如，export ABLY_API_KEY=...）。或者，如果你有令牌（例如，来自应用的身份验证服务器），则改用 ABLY_TOKEN。如果该密钥属于生产应用，请在使用前告知用户。

登录 CLI（用于更深入的调试或账户级命令）： ably login 会打开浏览器进行 OAuth 登录。登录后，使用 ably apps list 和 ably apps switch 选择目标应用，并使用 ably auth keys list 查看可用密钥及其权限。

如果没有可用凭据，请让用户检查是否已设置 Ably 环境变量（例如，ABLY_API_KEY），或运行 ably login 进行身份验证。

---

4. CLI 的功能

观察（只读）

实时订阅频道、在线状态、占用情况、日志和统计数据——你看到的内容与 Ably 看到的完全一致。

• 频道消息：订阅一个或多个频道。支持通配符和 rewind（附加时重放近期消息）。
• 在线状态：监视成员的加入和离开，以及他们的客户端 ID 和数据负载。
• 占用情况：快照或实时流，显示频道上的发布者、订阅者和在线状态成员。
• 日志（元频道）：频道生命周期、连接生命周期、在线状态事件和推送通知投递日志。可按类型筛选（channel.lifecycle、channel.occupancy、channel.presence、connection.lifecycle、push.publish），也可使用 rewind 捕获近期事件。
• 推送通知日志：专用推送日志流和历史记录——查看投递尝试、失败情况和设备目标。
• 历史记录：频道上的历史消息（未启用持久化时保留 2 分钟——请参阅“关键调试要点”）。
• 统计数据：应用或账户统计数据，支持实时轮询模式。可检查连接数是否达到计划限制。
• 频道列表：当前活跃的频道，支持按前缀筛选。
• 连接测试：验证通过各种传输方式（WebSocket、XHR）的连接情况，以定位网络或代理问题。

模拟

作为参与者进行操作——模拟对话的一端，以测试另一端（调试服务端时模拟客户端，调试客户端时模拟服务端）。

• 发布：发送带有事件名称、JSON 或纯文本的消息。可配置次数和延迟，重复发布以模拟流量。
• 批量发布：在单个请求中向多个频道发布消息。
• 加入在线状态：使用自定义客户端 ID 和数据加入频道（例如，{"role": "server"}）。
• 聊天：完整的聊天室模拟——消息、在线状态、输入状态、表情回应。
• Spaces：成员、光标、位置、锁定。
• 基准测试：可配置速率和消息大小的发布者/订阅者吞吐量及延迟测试。

管理

查询和修改应用配置，以诊断配置相关问题。

• 频道规则（命名空间）：检查并配置持久化、推送、仅 TLS、批处理、合并和频道注册表设置。
• API 密钥：列出权限、创建、撤销或切换活动密钥。
• 令牌签发：签发 JWT（如果应用使用 Ably 令牌，也可签发 Ably 令牌），以单独测试身份验证流程。也可撤销令牌。
• 应用：列出、创建、切换和配置应用。
• 集成：列出并检查集成规则——webhook、Lambda、Kafka、AMQP 等。检查来源类型（channel.message、channel.presence、channel.lifecycle、presence.message）、频道筛选条件以及启用/停用状态。
• 队列：列出、创建和删除 Ably 消息队列。

获取帮助

• AI 支持 Agent（由 Inkeep 提供支持）：ably support ask "your question" — 搜索 Ably 文档和常见问题。后续提问可使用 --continue。
• 服务状态：ably status 检查平台运行状况。

---

5. 长时间运行的命令

许多命令（subscribe、presence enter、stats --live、occupancy subscribe）会长时间运行——它们会持续流式输出，直到按下 Ctrl+C 或 --duration N 到期。请将这些命令作为后台任务运行，避免阻塞工作流。在后台启动订阅，重现问题，然后检查输出。

---

6. 连接和频道状态参考

连接状态

状态	含义	诊断
connecting	正在尝试连接	启动时正常；若卡住，请检查网络和身份验证
connected	WebSocket 处于活动状态	正常
disconnected	暂时断开，SDK 会重试	短暂断开属于正常；反复出现则表示网络问题 → 查看连接生命周期日志
suspended	离线超过 2 分钟，重试频率降低	测试连接以检查连通性
failed	永久失败，SDK 不会重试	几乎总是身份验证问题——使用指定的 API 密钥进行测试
closed	由代码显式关闭	搜索 .close() 调用

频道状态

状态	含义	诊断
initialized	已创建频道对象，但尚未附加	首次订阅或发布前属于正常状态
attaching	正在请求服务器附加	若卡住，请检查连接状态和身份验证权限
attached	处于活动状态——消息正在流动	正常
detaching	正在请求分离	清理期间属于正常状态
detached	未附加，没有消息流动	检查是否有意调用了 detach()
suspended	附加失败，将重试	通常发生在连接暂停之后——先检查连接状态
failed	频道永久失败	通常是权限被拒（40160）或频道名称无效

---

7. 特定环境的注意事项

环境	症状	根本原因	诊断
Next.js SSR	渲染期间连接失败	服务端渲染中没有 WebSocket	使用 typeof window 或 useEffect 进行保护
Serverless（Lambda、Edge）	连接过时或被冻结	调用之间连接被冻结	在服务端使用 Ably.Rest
React StrictMode	消息重复、presence 闪烁	双重渲染导致订阅重复	检查 occupancy——远高于预期即表示存在重复
CSP 标头	WebSocket 被阻止	Ably 域名未包含在 connect-src 中	测试连接——ws 失败而 xhr 正常，说明是 CSP 问题
企业代理	WebSocket 无声失败	代理阻止了协议升级	测试连接——ws 失败而 xhr 正常，说明是代理问题
移动设备后台运行	恢复后遗漏消息	操作系统终止了 WebSocket	检查频道历史记录，查看中断期间发送的消息