01 / STAGES
快连批量部署的四个阶段职责划分
每个阶段都有独立的进入条件，任一阶段不通过则任务停在原地，不会继续扩散配置。
STAGE 1
预检
校验模板版本、设备在线状态与指纹冲突，耗时约 40 秒。
STAGE 2
灰度
按比例放出小批设备，观察 5 分钟，失败达到 3 台即中止。
STAGE 3
全量
并发推进剩余设备，单批并发不超过 200 台。
STAGE 4
复核
比对上报结果与预期清单，差异清单写入审计日志。
- 预检阶段的模板校验依据官方文档中的字段约束，不合规的模板在提交瞬间返回错误码，不占用设备配额。
- 灰度阶段默认比例为 10%，可由管理员调整为 5% 或 25%，观察窗口固定 5 分钟，不可延长到 10 分钟以上。
- 全量阶段的并发数由控制台按分组规模自动计算，任务达到 200 台时并发也停在 200 台，不再继续追加。
- 复核阶段输出差异清单，差异行数超过 2% 时任务标记为待确认，需要人工在控制台点一次确认才结单。
02 / TEMPLATE
快连配置模板的字段构成
模板是下发动作的唯一输入，模板字段与下发接口字段一一对应，修改模板不会自动影响已下发的设备。
配置模板字段
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| template_id | string | 是 | 模板唯一编号，新建后不可修改 |
| route_group | string | 是 | 引用的线路分组，取自 12 条专属线路 |
| protocol | enum | 是 | Hysteria2 / Trojan / VLESS / Shadowsocks |
| fallback_route | string | 否 | 主线路异常时的兜底线路编号 |
| dns_mode | enum | 否 | system / local，默认 system |
| bandwidth_cap_mbps | number | 否 | 单设备带宽上限，不填表示不限 |
| schedule_window | string | 否 | 允许下发的时间窗，形如 01:00-06:00 |
| remark | string | 否 | 模板备注，不参与下发逻辑 |
{
"batch_id": "bt-20261023-0917",
"template_id": "tpl-hq-eu-03",
"device_count": 200,
"concurrency": 200,
"rollout": "canary",
"canary_ratio": 10,
"policy": { "auto_rollback": true, "fail_threshold": 3 }
}curl -sS "https://api.kuialaian.com.cn/v1/batches/bt-20261023-0917" \ -H "Authorization: Bearer kl_e_9f2c7a41b6d84e0fa3c5" \ -H "X-KL-App: erp-batch"
频率提示：进度查询会计入接口调用统计，同一应用凭证的调用频率上限为 120 次每分钟，建议对同一个批次使用 30 秒一次的轮询间隔。
04 / STRATEGY
快连批量部署的分批策略与容量规划
当在网设备超过 200 台时，需要由管理员自行拆分批次，拆分依据通常来自台账中的部门归属。
分批建议
| 在网规模 | 批次拆分 | 单批并发 | 预计耗时 |
|---|---|---|---|
| 200 台 | 1 个批次 | 200 台 | 约 8 分钟 |
| 500 台 | 3 个批次 | 200 台 | 每批约 8 分钟 |
| 1000 台 | 5 个批次 | 200 台 | 每批约 8 分钟 |
| 2000 台 | 10 个批次 | 200 台 | 每批约 8 分钟 |
批次之间建议间隔 10 分钟以上，让客户端完成配置重载与链路探测，避免重连风暴影响同机房其他租户的实测延迟。
05 / ROLLBACK
快连配置回滚机制与生效条件
回滚指把设备恢复到此前的模板版本，回滚本身也是一次下发任务，同样受 200 台并发约束。
- 自动回滚触发条件为灰度窗口内失败设备达到 3 台，或复核阶段差异行数占比超过 2%。
- 手动回滚可由拥有「配置管理员」角色的成员发起，权限通过 SCIM 组信息同步，每 15 分钟刷新一次。
- 回滚任务在队列中优先于普通下发任务，同一时刻最多保留 2 个待执行的回滚任务。
- 回滚完成后会在审计日志中记录 3 条字段：触发人、回滚时间、涉及设备数，记录保留 180 天。
06 / LINK
快连批量部署相关页面继续阅读
下发成功之后需要核对台账，需要计费口径则查看账务页。