## 10. 部署与上线

### 10.1 上线前检查清单

在将生产流量接入之前，合作伙伴必须完成以下事项：

- [ ] 在沙箱环境中通过全部集成测试
- [ ] 注册生产环境的 Webhook 端点
- [ ] 为 SyncBridge 相关指标配置监控与告警
- [ ] 完成日志记录配置，包含所有必需的上下文字段
- [ ] 实现凭证轮换自动化
- [ ] 编写 SyncBridge 故障响应的内部运维手册
- [ ] 完成 Webhook 签名验证的安全审查
- [ ] 按预期生产流量进行负载测试（建议使用 2 倍峰值）

### 10.2 上线流程

1. **预发布验证**：在预发布环境中执行完整的集成测试套件
2. **Schema 注册**：在生产环境中注册所有实体 Schema
3. **Webhook 激活**：启用生产环境 Webhook 端点
4. **影子模式（Shadow Mode）**：SyncBridge 将流量复制发送至合作伙伴端点，但不要求对方返回响应（持续 72 小时）
5. **灰度发布**：流量在 7 天内按 10% → 25% → 50% → 100% 逐步提升
6. **观察期**：为期 14 天的观察期，SyncBridge 支持团队全程待命

### 10.3 SLA 要求

| 指标 | 目标 | 衡量方式 |
|------|------|----------|
| 可用性 | 99.9% | 月度正常运行时间百分比 |
| 推送同步延迟 | p95 < 500ms | 从请求发出到收到响应的时间 |
| 拉取同步延迟 | p95 < 1s | 从请求发出到收到响应的时间 |
| Webhook 确认延迟 | p95 < 5s | 从 Webhook 投递到收到 2xx 响应的时间 |
| 错误率 | < 0.1% | 失败请求数 / 总请求数 |
| 数据新鲜度 | < 5 分钟 | 从数据源变更到同步完成的时间 |

---

## 11. 安全要求

### 11.1 传输安全

SyncBridge 与合作伙伴系统之间的所有通信必须使用 TLS 1.2 或更高版本。合作伙伴必须提供由受信任证书颁发机构签署的有效 SSL/TLS 证书。自签名证书在生产环境中不予接受，但可以在沙箱环境中用于测试。

**TLS 配置要求**：
- 最低版本：TLS 1.2
- 推荐版本：TLS 1.3
- 加密套件：必须支持 ECDHE-RSA-AES256-GCM-SHA384 或同等强度的套件
- 证书轮换：合作伙伴应在 TLS 证书到期前至少 30 天完成轮换
- HSTS：合作伙伴应启用 HTTP 严格传输安全（HTTP Strict Transport Security）响应头

### 11.2 数据保护

合作伙伴必须对所有同步数据采取适当的数据保护措施：

1. **静态加密**：所有实体数据必须使用 AES-256 或同等算法进行静态加密。数据库级加密（例如透明数据加密，Transparent Data Encryption）亦为可接受方案。

2. **PII（个人身份信息）处理**：电子邮件、电话号码、姓名等 PII 字段的处理必须符合适用的隐私法规（GDPR、CCPA、台湾个人资料保护法）。合作伙伴必须支持以下 PII 操作：
   - **数据主体访问请求**：在 72 小时内返回指定实体的全部数据
   - **删除权**：在收到请求后 30 天内永久删除实体数据
   - **数据可携权**：以机器可读的 JSON 格式导出实体数据

3. **审计日志**：对同步数据的所有读写操作必须记录足够详细的日志，以满足安全审计需求。日志必须至少保留 12 个月。

4. **访问控制**：合作伙伴必须对内部访问同步数据实施基于角色的访问控制（RBAC）。SyncBridge 服务账户应遵循最小权限原则——仅拥有对同步实体类型的读写权限，不得访问合作伙伴的内部数据。

### 11.3 安全事件响应

合作伙伴在发现任何可能影响同步数据的安全事件后，必须在 24 小时内通知 SyncBridge。通知内容必须包含：

- 事件的性质与范围
- 受影响的实体类型及大致数量
- 事件时间线（发现、遏制、解决）
- 已采取或计划采取的补救措施
- 合作伙伴安全团队的联系方式

SyncBridge 提供专用的安全事件端点，用于程序化通知：

```
POST /security/incidents
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "severity": "high",
  "category": "data_breach",
  "description": "Unauthorized access detected to entity sync database",
  "affected_entity_types": ["contact", "order"],
  "estimated_affected_count": 1500,
  "discovery_time": "2026-04-10T14:00:00Z",
  "containment_time": "2026-04-10T14:30:00Z",
  "contact": {
    "name": "Security Team Lead",
    "email": "security@partner.example.com",
    "phone": "+886-2-9876-5432"
  }
}
```

### 11.4 并发与冲突解决

当多个同步操作同时针对同一实体时，SyncBridge 通过版本戳（Version Stamp）实现乐观并发控制（Optimistic Concurrency Control）。每个实体携带一个 `_version` 字段，每次成功更新后该字段自动递增。合作伙伴在发送更新请求时必须包含当前版本号，并优雅地处理版本冲突错误。

**冲突检测流程**：
1. 合作伙伴收到 `_version: 5` 的实体
2. 合作伙伴在本地修改后，携带 `_version: 5` 发送更新请求
3. 若其他更新已将版本递增至 6，SyncBridge 返回 `409 CONFLICT`
4. 合作伙伴必须重新获取最新实体，合并变更后携带新版本号重试

**合并策略**：合作伙伴可按实体类型配置各自偏好的合并策略：

| 策略 | 行为 |
|------|------|
| `last_write_wins` | 以最新时间戳为准（默认策略） |
| `source_priority` | 始终采用上游系统的版本 |
| `partner_priority` | 始终采用合作伙伴的版本 |
| `manual_review` | 冲突在仪表盘中标记，等待人工处理 |
| `field_level_merge` | 无冲突的字段变更自动合并；冲突字段单独标记 |

对于高吞吐量场景，合作伙伴应在本地实现带去重功能的队列，以减少并发更新冲突。推荐的模式是：在一个短时间窗口内（例如 500 毫秒）将更新积攒于本地，按实体 ID 去重并仅保留最新状态，然后通过单次 API 调用将去重后的批次发送至 SyncBridge。

### 11.5 网络安全

合作伙伴应为其 SyncBridge 集成端点实施以下网络层安全控制：

- **IP 白名单（IP Allowlisting）**：SyncBridge 在 `https://api.syncbridge.io/.well-known/ip-ranges.json` 发布其出口 IP 段。合作伙伴应将集成端点的入站流量限制为这些 IP 段。
- **DDoS 防护**：合作伙伴应为 Webhook 端点部署 DDoS 缓解措施，因为故障恢复期间的 Webhook 重放可能产生流量峰值。
- **WAF 规则**：WAF（Web Application Firewall）规则应允许 SyncBridge 的 JSON 载荷通过，同时拦截常见攻击模式。需确保 WAF 规则不会干扰大型批量载荷（最大 1MB）。
- **mTLS（可选）**：对于企业级合作伙伴，SyncBridge 支持将 mTLS 双向认证作为额外的安全层。如需启用 mTLS，请联系您的集成经理。

---

## 附录 A：变更日志

| 版本 | 日期 | 变更内容 |
|------|------|----------|
| 2.4.0 | 2026-04-10 | 新增字段映射转换功能及上线影子模式 |
| 2.3.0 | 2026-03-15 | 新增 Schema 兼容性验证端点 |
| 2.2.0 | 2026-02-01 | 新增事件订阅管理及死信队列重放功能 |
| 2.1.0 | 2026-01-10 | 新增批次进度事件及指标端点 |
| 2.0.0 | 2025-11-01 | 主版本升级：全新身份验证流程、游标分页、Webhook 签名 |

## 附录 B：术语表

| 术语 | 定义 |
|------|------|
| 实体（Entity） | 在系统间同步的独立数据记录（例如联系人、订单、产品） |
| 批次（Batch） | 在单次 API 调用中作为一组一并处理的实体操作集合 |
| 游标（Cursor） | 一种不透明的分页令牌，用于编码当前在结果集中的位置 |
| 幂等键（Idempotency Key） | 唯一标识符，确保重试请求产生相同的处理结果 |
| 死信队列（Dead-Letter Queue） | 用于暂存所有投递尝试均失败的 Webhook 事件的缓冲区 |
| 影子模式（Shadow Mode） | 预生产阶段，流量被镜像发送至目标端点，但不要求其返回响应 |
| Schema 注册中心（Schema Registry） | 用于集中存储实体类型定义和字段映射配置的中央仓库 |
| 字段映射（Field Mapping） | 将合作伙伴字段名称与格式转换为 SyncBridge 标准 Schema 的配置 |
| Webhook 密钥（Webhook Secret） | 用于计算 Webhook 载荷 HMAC 签名以供验证的共享密钥 |
| 宽限期（Grace Period） | 凭证轮换过程中，旧密钥与新密钥同时有效的时间窗口 |
| 上游（Upstream） | 数据的源系统，数据从此处流经 SyncBridge 向下传递 |
| 下游（Downstream） | 接收 SyncBridge 同步数据的目标系统 |