停止 UnifyPort 消息账号连接：避免被自动恢复程序重新启动

要临时停止 UnifyPort 消息账号的连接而不删除账号，可向 POST /v1/accounts/{account_id}/runtime/stop 提交 {}。确认 runtime_status: stopped 才表示停止完成；stopping 仍需继续核对。在调用前，应先让应用的自动恢复程序知道这是计划停机，否则它可能把连接重新启动。

要点

• 停止 runtime 会保留消息账号，不等于删除账号。
• 先持久化应用侧的停机意图，再停止连接。
• 实际 runtime_status 与是否允许恢复，是两个不同判断。
• 恢复连接不代表停机期间的消息已经补齐。

冲突从哪里来：恢复操作正确，执行时机却不对

设想一个维护场景：操作员停止某个消息账号，健康检查程序读到 stopped，随后按“保持在线”的规则调用 start。两个请求各自都可能符合 API 契约，却违背了操作员的停机意图。这是设计示例，不是已发生的客户事故。

解决方法不是再登录一次，而是在应用内明确该账号现在是否应该在线。消息账号运行状态恢复指南 解决的是应当在线却发生故障的连接；计划停机需要在该恢复逻辑前加一道控制。

这不是新增 API 设置。账号生命周期文档 将账号 status、认证状态和 runtime_status 分开。本文建议的停机记录属于应用自己的数据，不是 UnifyPort 新字段，也不能推断设置账号 status 就会提供相同行为。

先确定真正需要停止哪一层

目标	合适的控制层
暂停 CRM 写入或 AI 处理，但继续接收消息	暂停应用消费者
停止此消息账号的实时连接，保留账号	Stop runtime
永久退役消息账号资源	独立的账号删除流程

如果只是下游系统维护，先看 webhook 维护方案对比。停止连接不是可靠的消息缓冲方案。

只有确实要退役时，才进入 账号删除流程。停止 runtime 的契约不承诺退款、暂停订阅、删除原生平台账号或清除已存消息。

在停止请求之前，让所有工作程序看到停机意图

以下是应用设计建议：

1. 确认工作空间、account_id、渠道、操作员和原因；分别读取账号及认证状态。
2. 持久化该账号的本地停机决定，让自动恢复程序和定时发送程序在派发新请求前检查它。
3. 协调已经执行中的任务。刚写入的标记无法取消已经提交的 API 请求；使用应用自己的单账号协调机制，核对在途操作。
4. 保持 webhook 接收端可用，继续验证并存储仍然到达的事件。不要把 runtime stop 理解成 webhook 投递已全部排空。
5. 提交一次经过确认的停止请求，再检查结果。

最小控制规则如下。这是应用伪代码，不是 SDK 语法或新接口：

自动执行 start 或 reconnect 之前：
    读取该账号当前的本地运行意图
    如果操作员已要求暂停：
        不派发恢复请求
    否则：
        检查认证状态与 runtime 状态
        选择文档支持的恢复动作

所有恢复入口都应遵守相同控制，包括延迟任务和手动恢复按钮。协调暂停与恢复操作，避免旧的启动任务仅因之后一次界面操作就重新获得执行资格。

提交一次停止请求，再核对结果

Stop runtime 参考 规定请求体为空 JSON 对象。以下示例未实际执行；变量应来自后端已确认的账号选择和受保护的 API 密钥配置：

curl -X POST \
  "https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/runtime/stop" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{}'

API 密钥只放在服务端。保存 HTTP 状态和可取得的请求诊断信息，不记录密钥。

观察结果	含义与后续操作
runtime_status: stopped	连接层停止完成；保留本地停机标记
runtime_status: stopping	正在转换状态，继续核对
超时或响应无法读取	结果未知；再次修改前先读取状态
本地仍要求暂停，但 runtime 变成 running	排查竞争的 start 或 reconnect 路径，不宣告维护准备完成

通过 读取账号 或 刷新运行状态 核对。Refresh 是同步状态，不是重新启动。在应用内设置有界的检查和升级处理策略，不要假定固定完成时限。

不要等待不存在于公开目录中的 account.stopped 事件。生命周期文档明确指出，account.status.updated 不保证覆盖每次请求引发的状态变化。收件箱安静也不是停止成功的证据。

将恢复作为独立、经过确认的操作

恢复前继续限制发送任务，同时检查保留账号的当前认证状态。如果需要用户操作，继续相应的认证流程；认证成功通常会自动启动 runtime，因此维护期间不要无意中重新认证。

如果认证仍有效且 runtime 已停止，使用 Start runtime。将这次明确恢复与本地暂停控制协调起来，核对到实际 running，而不是把 starting 当作完成。

放行积压任务前，逐项检查是否仍有执行价值。发送一条受控测试消息，追踪新事件的验签和持久化，再恢复相应消费者及自动恢复策略。

UnifyPort 的非官方接口不保证重放错过的载荷，也不提供通用 REST 消息历史读取 API。将停机区间记为可能的采集缺口。新消息测试成功只能证明当前链路恢复，不能证明缺口已补齐。

常见问题

Stop 会删除消息账号吗？

不会。文档明确说明停止 runtime 会保留账号；再次启动是独立动作。

健康检查程序应该启动所有 stopped 账号吗？

不应该。先确认应用是否希望该账号在线，实际状态不能代替操作员意图。

停止成功会取消排队回复或 webhook 投递吗？

不能这样推断。应用任务需单独管理，公开停止契约不承诺取消已提交的工作或排空 webhook。

停止连接会暂停计费吗？

停止 runtime 的契约没有这一承诺，不要用连接状态作为财务变化的证据。

下一步与来源

围绕 Stop runtime 实现本地恢复控制。建议测试竞争的恢复程序、在途启动、停止响应丢失、stopping、明确恢复和过期的排队回复。这些是待执行的验收项，不是已通过的测试结果。

资料核对日期：2026-11-04。

• UnifyPort：Stop runtime
• UnifyPort：账号生命周期
• UnifyPort：Webhook 投递与恢复边界