第 20 章 · 集成与对接
适用对象：架构师、集成开发、备份管理员 · 阅读约 15 分钟 · 对应产品界面版本 v1.2.0
把备份平台接进 CMDB、统一监控、工单系统和日志平台，是中大型环境的常规需求。这一章讲的是对接之前要确认什么：有哪些可用通道、每条通道的边界在哪里、哪些做法是明令禁止的。它不是接口手册——接口手册要从产品侧单独取得。
读完这一章你会做：
- 判断当前该走接口对接还是替代通道，并据此给集成方案定节拍
- 列出向产品侧索取接口材料的清单，以及拿到之后要逐项验证什么
- 为 CMDB 同步、监控采集、工单触发恢复三个典型场景设计控制点
- 说清楚哪些集成做法不能用，以及不能用的原因
先看现状
管理页面可以证明业务入口存在，但页面路径不是对外 API 端点。对外 API 的版本、认证协议、请求结构、错误码与兼容性承诺，在拿到产品侧书面接口说明之前都不成立。在此之前不要按推测的路径开发，也不要把浏览器页面请求当成对外接口使用。
源文档给出了一份参考规格，可以用来做接口封装层的设计和排期，但它明确标注为「落地前须经产品侧以正式文档确认」，不能作为对接契约：
| 接口要素 | 参考规格（未经产品侧书面确认） |
|---|---|
| 提供方式 | RESTful / JSON over HTTPS，与 Web 控制台同源，不单独开放 API 端口 |
| 版本与基址 | 基址形如 https://<管理平台地址>/api/v1，版本号写在 URL 路径里 |
| 认证方式 | 登录换取会话令牌（Bearer Token）；服务账号场景使用 API Key + Secret Key |
| 权限模型 | 复用控制台的 RBAC 角色与数据范围 |
| 分页与过滤 | page / page_size 加 sort / filter，响应体含 total |
| 错误码 | HTTP 状态码 + 业务码，响应体含 code / message / request_id |
| 幂等与限流 | 创建类接口支持 Idempotency-Key 请求头，超过限流返回 429 并给 Retry-After |
| 文档形式 | 《API 参考手册》加 OpenAPI 描述文件 |
源文档给出的令牌有效期、密钥数量上限、分页默认值与上限、每分钟调用次数等具体取值，同样属于未经确认的参考值。把它们写进接口封装层的默认配置是可以的，写进验收标准不行。
两条路径
集成方案要同时准备两条路径，等产品侧给出书面结论后再收敛到其中一条。
| 路径 A：确认提供对外 API | 路径 B：确认不提供 | |
|---|---|---|
| 接口说明 | 索取接口说明书或 OpenAPI 文件，按真实取值替换全部待确认字段 | 把「提供对外 API」登记为需求项与验收风险项，写明需求编号、影响范围与期望交付时间 |
| 认证 | 令牌或长期密钥，配独立低权限服务账号 | 控制台账号加堡垒机二次认证，执行口令复杂度与定期改密要求 |
| CMDB 同步 | 接口增量同步 | 导出文件加人工确认，节拍由每日降为每周 |
| 工单触发恢复 | 接口受控触发 | 工单驱动人工在控制台执行，控制点不变 |
| 监控采集 | 接口或报表导出 | 报表导出加邮件解析 |
| 验证 | 按本章「验证清单」逐项执行 | 改为验证替代通道：导出文件的字段完整性、定时发送的到达时间与成功率、日志通道的断链处理 |
路径 B 下的集成收益从「自动执行」降级为「自动登记与留痕」，这一点要在方案里写明，不要让业务方以为功能等价。
开始之前
正式开发对接前要凑齐的材料：
| 前置项 | 说明 |
|---|---|
| 接口说明书或 OpenAPI 文件 | 含适用的产品版本，版本对不上的文档不能用 |
| 测试环境与测试账号 | 生产环境不做接口联调 |
| 服务账号与权限范围 | 独立低权限账号，建议只给「操作员 + 指定保护组」范围，不给超级管理员 |
| 网络放行 | 集成网段到管理平台的方向与端口，见附录 B |
| 变更与审批 | 接口纳入变更管理，订阅产品侧的接口变更与弃用公告 |
| 性能影响结论 | 接口调用对备份性能与并发的影响，须经产品侧确认后再上生产 |
在接口文档到位之前，可以先按参考规格设计接口封装层（基址、令牌获取、分页、错误码重试），这一层不依赖具体资源路径，文档到位后补齐路径映射即可。
接口边界
这些是集成方案里的禁止项，与是否提供 API 无关。
- 禁止直连平台内部数据库做常规集成。 平台内部确实有关系型数据库并监听服务端口，但那是供内部组件连接的，不是对外接口。
- 禁止抓取管理页面的请求当作集成手段。 页面接口没有兼容性承诺，产品升级后随时失效。
- 禁止用任何非正式通道执行变更类操作——恢复、删除、策略变更只能走控制台或产品侧确认的接口。
- 禁止把「邮件通知成功」当作任务成功的判据。 通知到达只证明通道通，结论以平台任务记录为准。
如果确有只读采集的需求，且产品侧书面许可，那么至少要满足下面这些条件：
| 项目 | 要求 |
|---|---|
| 账号 | 独立只读账号，仅授予 SELECT；禁止复用应用账号或管理员账号 |
| 连接方式 | 直连只读副本或从库，不建议直连承载写入的主库 |
| 访问范围 | 仅限只读视图或稳定表；禁止查询大字段、日志正文与凭据相关表 |
| 频率 | 低频定时（如 5 至 15 分钟一次），避免复杂聚合与全表扫描 |
| 结构稳定性 | 表结构可能随版本升级变化，无兼容性承诺，每次升级后重新验证字段与语义 |
| 熔断 | 采集脚本必须有超时与熔断，避免慢查询拖慢平台 |
| 结论口径 | 所有结论以平台任务记录为准，数据库取值只作辅助 |
优先级永远是：正式接口 > 报表导出 > 只读副本。
可用的对接通道
在接口结论明确之前，下面这几条是可以先推进的替代通道。
| 通道 | 实时性 | 主要用途 | 当前状态 |
|---|---|---|---|
| 报表导出与定时发送 | 低（按周期） | 监控展示、容量与成功率趋势 | 待确认格式与定时投递能力 |
| Syslog 外发 | 高 | 日志平台与 SIEM | 待确认是否支持及字段格式 |
| Webhook | 高 | 任务结果、告警、容量事件推送 | 待确认是否支持及事件模型 |
| CLI / 运维脚本 | 按需 | 巡检、导出、状态查询 | 待确认是否提供 |
| 数据库只读 | 中 | 兜底采集 | 需产品侧书面许可，不推荐常规使用 |
| 邮件解析 | 低 | 运维展示或工单线索 | 只读采集，不触发任何动作 |
报表导出与定时发送
缺少对外 API 时，这条是最实用的替代通道。
需要确认：报表包含哪些字段与统计口径、支持哪些导出格式（PDF 用于归档留痕，CSV 或 XLSX 才方便程序解析）、能否按周期自动投递到指定邮箱。
解析侧由集成方实现，有三点必须写进方案：
- 报表记录的是统计结果而不是明细，不能替代任务日志级别的对账。
- PDF 解析对版式敏感，产品升级后可能失效。「解析失败」要作为独立告警，不能静默丢弃。
- 报表到达不等于任务成功，展示和工单结论仍以平台任务记录为准。
去重按「报表周期 + 任务标识」，解析结果要能回溯到原始报表文件。到点未收到报表、字段缺失、数值为空，这三种情况都要有告警规则。
Syslog
日志平台与 SIEM 对接的主通道。对接前先定四件事：需要哪些事件类型、时间同步是否可靠、保留期限与合规要求、哪些字段属于敏感信息。
需要向产品侧确认的项：
| 约定项 | 要确认什么 |
|---|---|
| 标准与格式 | RFC 5424 还是 RFC 3164，结构化数据怎么放 |
| 传输与端口 | UDP 514、TCP 601、TLS 6514 中支持哪些 |
| 事件范围 | 登录登出、配置变更、任务成功失败、代理上下线、告警产生与恢复，各自是否覆盖 |
| 关键字段 | 时间（含时区）、主机、模块、严重级别、事件类型、用户、资源、任务、结果、消息 ID |
| 严重级别映射 | syslog severity 与日志平台等级的映射表 |
| 断链处理 | 是否本地缓存、链路恢复后是否补发、断链本身是否告警 |
外发通道一旦打通，日志正文里的任何敏感内容都会进入第三方系统。脱敏要求见第 19 章。
如果确认不支持外发，替代方案是由运维按周期导出日志包并归档，作为取证通道而不是实时通道。
Webhook
价值在于把任务结果、告警和容量事件实时推过去，避免轮询。需要确认的是事件类型清单、事件字段、鉴权方式（静态令牌还是 HMAC 签名）、超时与重试策略、投递失败时平台侧是否可见并告警。
接收端要按事件 ID 去重，重复投递按同一事件处理。
停掉接收端，确认平台侧能记录投递失败并告警；链路恢复后不产生重复工单。投递失败被静默丢弃是这条通道最典型的事故模式。
平台不提供 Webhook 时，可以用「Syslog 到日志平台再转发」或「邮件到网关再解析」组合替代，但实时性、字段完整性和可靠性都会下降，降级影响要写进方案。
CLI 与运维脚本
如果提供 CLI，通用约定是：凭据来自环境变量或受权限保护的凭据文件（禁止在命令行明文传口令）；支持结构化输出便于脚本解析；退出码 0 表示成功，非 0 给出可区分的错误码；与接口共用同一套角色与资源范围；每条命令记录执行人、时间、参数摘要与结果。
建议只把 CLI 用于巡检、导出和状态查询，不用于批量恢复等高风险操作。
邮件解析
只在确认没有正式接口时使用，而且只用于运维展示或工单线索。解析要校验发件身份、固定模板、时间、结果，并做去重和异常处理。这是只读采集，不触发恢复或删除。
集成场景
CMDB 主机同步
| 环节 | 做法 |
|---|---|
| 主数据方向 | CMDB 为源，备份平台为从，避免双向写入冲突 |
| 唯一键 | 优先资产编号，其次 IP 加 FQDN 组合；缺唯一键的主机进人工处理流程 |
| 同步字段 | 名称、IP、FQDN、操作系统与版本、架构、业务等级、责任人、标签 |
| 不同步字段 | 备份策略、还原点、保留期、授权——这些由备份平台自行管理 |
| 同步频率 | 每日一次增量，避开备份窗口 |
| 冲突处理 | 以 CMDB 为准更新描述性字段，备份平台的运维字段不被覆盖，冲突写审计日志 |
| 下线处理 | CMDB 中已下线的主机在备份平台标记为已下线而不自动删除 |
| 校验 | 每次同步输出新增、更新、未匹配三类清单，未匹配项须有人工结论 |
| 回退 | 保留同步前的字段快照，可按单主机回退，并与变更单绑定 |
CMDB 里主机下线的原因可能只是资产录入错误。如果同步逻辑会自动删除备份平台上的保护对象，就等于把误删保护对象和还原点的能力交给了一个外部系统。
验收标准建议三条：连续两周同步的新增与变更主机无遗漏（人工抽样为准）；未匹配清单每周清零或有明确处置结论；同步过程不产生任何备份策略或还原点的变更。
任何写操作前先做一次全量比对并输出差异清单，由运维确认后再执行。
统一监控：成功率与容量
采集之前先把口径定死，否则不同系统之间的数字无法比对：
- 作业成功率的分母是什么（计划任务数还是实际执行数）
- 统计周期与时区
- 重试怎么计数
- 离线资源怎么算
- 容量单位
时间统一用带时区的表示并落库记录时区。告警要保留原始告警 ID 与文本摘要，便于与邮件、Syslog 通道对账。采集责任人与权限要明确，采集失败和缺失值都要记录，不能静默跳过。
工单触发文件恢复
这个场景的核心不是「能不能自动触发」，而是「受控触发加可追溯」。
| 步骤 | 执行方 | 动作 | 强制控制点 |
|---|---|---|---|
| 1 申请 | 业务方 | 提交恢复申请：主机、还原点时间、文件或目录清单、目标路径、原因 | 必填项校验，缺目标路径不受理 |
| 2 审批 | 备份管理员与业务负责人 | 双人复核还原点与目标路径 | 审批通过才进入执行 |
| 3 校验 | 执行人 | 核对还原点可用性、目标剩余空间、目标路径是否为生产原路径 | 默认目标为隔离目录，覆盖生产路径需额外审批 |
| 4 执行 | 路径 A 调接口 / 路径 B 人工在控制台执行 | 创建恢复任务并记录工单号 | 幂等键取工单号，同一工单只执行一次 |
| 5 校验 | 业务方与执行人 | 核对数量、大小、抽样哈希、应用可读性 | 校验通过才回写成功 |
| 6 回写 | 工单系统 | 回写状态与证据链接 | 不允许出现无终态工单 |
| 7 归档 | 审计员 | 归档操作记录、恢复记录与校验结果 | 保存期满足审计要求 |
工单状态机：受理 → 审批中 → 已批准 → 执行中 → 校验中 → 成功；或受理 → 审批中 → 已驳回；或执行中 → 失败 → 已回滚。
执行失败时必须记录失败环节、错误码或日志摘要。恢复到隔离目录的失败通常无需回滚，覆盖式恢复的失败必须先评估目标数据状态再决定。
禁止把恢复目标默认设成生产原路径；禁止在业务高峰执行覆盖式恢复；禁止无审批的批量恢复；禁止在工单重试时重复提交同一恢复请求（先用幂等键查结果）。覆盖恢复会清除目标路径的既有数据，恢复操作本身的风险见第 12 章。
堡垒机与统一认证
| 对接项 | 要点 |
|---|---|
| 账号映射 | 目录账号与平台账号一对一，用唯一属性匹配 |
| 角色映射 | 目录用户组映射到平台角色，避免逐人授权；禁止用通配规则把所有域用户映射为管理员 |
| 本地账号 | 保留至少一个本地应急管理员，口令托管并定期轮换 |
| 堡垒机纳管 | 通过代理访问管理端，会话录屏与命令审计由堡垒机侧实现 |
| 会话与超时 | 空闲超时、单点登出、离职账号即时禁用 |
| 审计留痕 | 登录、授权变更、恢复操作写入平台日志并同步到日志平台 |
| 网络路径 | 管理端到目录服务与堡垒机方向的访问放通，见附录 B |
对接顺序：先评审账号与角色的映射表，再在测试环境联调，最后切换生产。切换时必须保留并验证本地应急账号，否则目录服务故障会导致管理端无法登录。三权分立要求应在映射表里体现，审计员角色不得同时拥有恢复与删除权限，见第 18 章。
邮件网关
确认 SMTP 地址、端口、认证方式、加密连接、发件人及接收范围，在批准的窗口内用「测试邮件服务」验证，再核对网关接收记录与目标邮箱。
之后要分别验证作业成功、警告、失败三类通知和日报，不要把一次连通测试当成全部通知都验证过了。
验证清单
拿到接口说明并具备测试环境之后，逐项执行并留存证据（截图、请求与响应原文、日志片段、执行人）。没有执行的项保持空白，不得以「页面可操作」代替接口验证。
| 编号 | 验证项 | 方法 | 期望结果 |
|---|---|---|---|
| V-01 | 接口连通性 | 从集成网段访问基址，验证 TLS 与端口 | 可建立 TLS 连接，返回鉴权错误而非连接失败 |
| V-02 | 认证与令牌过期 | 取令牌后等待超过有效期再调用 | 返回 401，重新取令牌后恢复 |
| V-03 | 最小权限校验 | 用只读账号调用写接口 | 返回 403，且不产生任何变更 |
| V-04 | 资源查询一致性 | 接口返回的主机数与页面资源数比对 | 数量与唯一键一致，差异可解释 |
| V-05 | 分页与总量 | 用分页参数遍历全量 | 无重复、无遗漏，总数一致 |
| V-06 | 错误码结构 | 构造参数错误、越权、不存在三类请求 | 返回约定的状态码与请求 ID |
| V-07 | 幂等键 | 同键同请求体重复提交创建类请求 | 只产生一个作业，第二次返回首次结果 |
| V-08 | 限流与重试 | 压测触发限流 | 按 Retry-After 退避后可恢复 |
| V-09 | 恢复接口 | 在隔离主机执行一次测试恢复 | 目标文件与源端校验一致，无越权写入 |
| V-10 | 审计留痕 | 完成上述调用后查询审计日志 | 可查到调用者、来源 IP、对象与结果 |
重试规则：只对限流、服务端错误和网络异常重试，最多 3 至 5 次，退避基数建议 1 秒并加随机抖动，总时长不超过业务窗口，重试过程中复用同一幂等键。批量接口的部分失败必须逐条返回明细，禁止「部分成功但整体返回成功且无明细」。
接口并发过高只影响管理端响应；作业并发过高会影响生产存储与网络。同一主机同一时刻只应有一个快照类作业，恢复作业与备份作业不应并发。自动化触发必须限流并错峰，容量与并发口径见第 3 章。
常见问题
现在能直接按 /api/v1/... 开发吗？
不能。源文档里的路径是通用形态的举例，不是 SupDRC 的已确认端点。可以先做不依赖具体路径的封装层，等接口文档到位再补映射。
页面上的请求我能抓下来用吗？ 不能作为集成手段。页面接口没有兼容性承诺，升级后随时失效，而且绕过了平台的权限模型，不符合审计与最小权限要求。
监控系统要算备份成功率，从哪里取数？ 接口结论明确前走报表导出。取数之前先定死分母、统计周期、时区和重试计数规则，否则和别的系统对不上账。
工单系统能不能自动发起恢复？ 在没有确认接口之前，第 4 步固定为人工在控制台执行，其余六个控制点不变。集成收益从自动执行降级为自动登记与留痕。
报表按时收到了，是不是说明昨晚的备份都成功了？ 不是。报表到达只说明投递通道正常；报表里的数字是统计结果，明细对账要看平台的任务记录。