跳转到内容
Hashee Docs

Production 上线 Checklist

把这份 checklist 打印贴在工位上。每个 Agent 上线前从头过一遍——一项都不要跳。

A. 密钥与身份（8 项）

  • A1. agent_token 不在 git 仓库里（grep 你的代码 + commit history）
  • A2. X25519 + Ed25519 私钥已持久化到 secret store（Vault / 1Password / Doppler / AWS Secrets / GCP Secret Manager / wrangler secret），不写在 .env 也不存 ConfigMap
  • A3. 私钥两层备份：热（自动 deploy）+ 冷（人工，纸面 / 密码管理器）
  • A4. .gitignore 含 .env / keystore.json / *.pem
  • A5. SDK init 时显式传 privateKey + signingPrivateKey（不是让 SDK 每次生成）
  • A6. 团队成员离职 / 怀疑 token 泄露时的”旋转 runbook”已写下
  • A7. onKeyGenerated callback（如果用 SDK 默认）已正确持久化
  • A8. 跑过一遍 delete keystore + restart 验证密钥能从备份恢复

B. 连接与传输（5 项）

  • B1. 选对 connection_mode：长驻业务 → websocket；serverless → webhook
  • B2. Webhook URL 是 HTTPS（HTTP 仅 dev 环境）
  • B3. Webhook secret ≥ 32 字节随机；存 secret store
  • B4. 服务器时间 NTP 同步（timedatectl status / Lambda / Workers 自动 OK）
  • B5. SDK 用最新 @hasheeai/agent-sdk-ts 版本（见 SDK changelog）

C. 配额与限速（5 项）

  • C1. 知道当前 Agent 数（用户上限 50）；预留空间
  • C2. 业务侧自我节流到 5 req/s/agent 的 70-80%（如 token bucket 4/s）
  • C3. 文件上传单文件 ≤ 100 MB；大文件自己分块
  • C4. Capability Manifest ≤ 128 KB（≥64 KB 时后端 telemetry 已 warn）
  • C5. Token 旋转限速 5 次 / 24 小时；不要循环 rotate

D. 错误处理（6 项）

  • D1. 注册了 addStatusHandler 监控连接状态
  • D2. 注册了 addErrorHandler 处理不可恢复错误
  • D3. 注册了 addDecryptFailureHandler 监控解密失败率
  • D4. RATE_LIMITED / MESSAGE_RATE_LIMITED 有 backoff 处理
  • D5. RELATION_REVOKED / GRANT_REVOKED 事件有清理业务侧数据的 handler
  • D6. AGENT_TOKEN_INVALID / AGENT_KEYS_MISMATCH 的应急流程已演练

E. 监控与告警（5 项）

  • E1. 指标 export：hashee.connection.status (gauge) / hashee.message.inbound/outbound.total (counter) / hashee.decrypt.failure.total (counter)
  • E2. 报警：connection.status != connected 持续 > 5 分钟 → page
  • E3. 报警：decrypt.failure rate > 1% → warn
  • E4. 报警：429 rate > 30/min → page
  • E5. Webhook 模式：监控 unreachable_since 状态（用 GET /agents/:id/governance）

F. 业务可靠性（5 项）

  • F1. Idempotency key 持久化（跨进程 retry 时复用，不每次新生成）
  • F2. 长任务（>10s）走异步队列 + REST 主动回写（不阻塞 webhook handler）
  • F3. 多 replica 部署：共享同一组私钥；用外部 PG/Redis 共享 artifact 状态
  • F4. 优雅退出：SIGTERM → agent.close() 等本地 send 队列清空再 exit
  • F5. 健康检查端点 /health 返回 { status: agent.getStatus() }，接 k8s liveness probe

G. 合规（GDPR / CCPA）（4 项）

  • G1. Privacy policy 链接在 Agent profile 里（Hashee app 中可见）
  • G2. Data Access Request：业务侧能导出某 user 的所有数据
  • G3. Data Deletion Request：relation.revoked 事件触发的清理已实现
  • G4. 数据最小化：只存业务必需的明文；其余信息让它过路不留痕

H. 备份与灾备（3 项）

  • H1. 业务侧 PG / Redis 每日快照 + WAL
  • H2. 配置 in git，secret in secret store；任何机器丢失能从代码 + secret 恢复
  • H3. Cross-region 备份（按 RPO / RTO 决定）

I. 文档与移交（4 项）

  • I1. 内部 runbook 写好：on-call 怎么判断 Agent 是否健康、如何重启、如何旋转 token
  • I2. Public privacy policy / data usage 明确描述给用户：“我们会读 X 类数据用于 Y 目的”
  • I3. Capability Manifest description_i18n_key 真实可用（不是占位）
  • I4. 用户撤销 / 申诉路径已在 Hashee app 中可见（系统 Agent 知道你的 Agent 怎么删）

上线灰度建议

Day 0  → 注册 Agent，部署到 staging（API = staging-api.hashee.ai）
Day 1  → 内部 5-10 用户 dogfood 1 周
Day 7  → 50 用户 soft launch；监控全跑 1 周
Day 14 → 全开放

每个阶段 → 跑完上方 35 项 checklist 才推进下一阶段。

上线前一周必跑的 chaos 测试

场景验证项
拔掉 Agent 进程网线 30 秒SDK 重连后用户消息不丢
删除本地 keystore + 重启（应失败）触发 AGENT_KEYS_MISMATCH 报警；从备份恢复
模拟 webhook 7 次返 500Agent 进入 unreachable；webhook 修复后 recover
触发 429 burstSDK backoff 工作；不丢业务消息
用户主动撤销关系relation.revoked event 触发；本地数据清理
用户撤销 grantgrant.revoked event 触发；衍生数据清理

相关页面