05 · 如何部署和运维 Agent Platform？ - Deployment & Operations
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：04 · 如何开发、部署和维护 Agent Platform？ - Engineering & Practice
文档类型：专题研究 / 部署架构 / 运维实践参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：如何将 Agent Platform 从开发环境可靠地部署到生产环境，并通过可观测性、安全治理、发布控制、备份恢复、故障处置与成本管理，维持长时间运行的 Agent 任务和研究工作流？
专题导读
本篇属 Engineering & Practice。本篇承接 04/04/01 Platform Case Studies、04/04/02 Technology Selection、04/04/03 System Design 和 04/04/04 Development Roadmap。研究范围是系统部署与持续运营，不是重复定义 Agent 产品功能，也不将“容器成功启动”视为“平台可用”。对于 Studio 研究报告平台，部署成功必须包括：用户能提交任务；队列能够派发；Worker 能执行；任务和审批状态可恢复；产物可追溯；故障可发现、可控制、可复原。
证据标记：[官方/规范] 表示相关标准或产品官方资料可以直接支持的机制；[工程建议] 表示本文综合设计的实施方案；[待验证] 表示必须通过目标云环境、现有代码、实际负载、恢复演练或成本账单核实的内容。所有示例配置、SLO、容量参数、接口和测试项均为参考，未实际部署或测试 Studio。
研究结论
- 控制面、执行面与数据面应有清晰的故障边界：Web/API 故障、Worker 故障、数据库故障和模型供应商故障不能都表现为“任务失败”。[工程建议]
- 长任务的可靠性主要取决于持久化状态、租约、幂等、恢复与副作用控制，而非容器是否自动重启。[工程建议]
- 部署流水线必须兼顾代码版本、数据库迁移、Agent 定义版本和正在运行的 Run，不能只回滚镜像。[工程建议]
- 可观测性必须连接用户感知的业务结果：运行成功率、审核等待时间、合格产物率、任务成本、恢复成功率，需与基础设施指标共同使用。[工程建议]
- 备份不等于可恢复；只有定期执行恢复演练，验证 PostgreSQL、对象存储、密钥和配置之间的一致性，才能评价 RPO/RTO。[工程建议]
- 初期推荐模块化单体 API + 独立 Worker + PostgreSQL + 对象存储 + 托管监控作为候选起点；是否使用 Redis、独立编排引擎和 Kubernetes，应依据 PoC 与实际需求决定。[工程建议]
- 生产环境默认遵循最小权限、密钥隔离、数据最小化、可审计变更与受控成本；尤其不得将敏感 Prompt、用户资料和模型响应无差别写入日志。[工程建议]
01 · 运维对象、边界与职责
1.1 运营对象分层
| 层次 | 关键对象 | 主要责任 | 常见故障 |
|---|---|---|---|
| 接入与产品层 | 域名、CDN、Web、API、鉴权 | 用户访问与业务请求 | 5xx、登录失败、接口超时 |
| 控制与编排层 | Run、Workflow、审批、Outbox | 状态正确、调度可恢复 | 状态卡死、重复派发 |
| 执行层 | Queue、Worker、Agent Runtime、工具沙箱 | 任务执行与隔离 | Worker 崩溃、工具超时 |
| 数据层 | PostgreSQL、对象存储、缓存 | 事务、版本与持久化 | 数据不可用、存储损坏 |
| 外部依赖 | 模型 API、搜索、邮件、第三方连接器 | 依赖治理与降级 | 限流、供应商中断 |
| 治理与观测层 | Metrics、Logs、Traces、Audit、Budget | 发现、诊断、审计与控制 | 告警失效、日志泄漏 |
职责边界：平台维护人员负责服务可用性与恢复；安全负责人负责密钥和权限；业务负责人定义质量门槛与产物验收；Agent 设计者维护版本和提示词。小团队可以由同一人兼任，但系统权限仍应分离。[工程建议]
1.2 四种“健康”不可混为一谈
- 进程健康：进程是否存活；仅用于最基础的 liveness。
- 服务就绪：依赖是否满足接收新请求的条件；用于 readiness。
- 工作流健康：Run 是否能够从排队推进到终态，人工审批是否可恢复。
- 业务健康：用户是否得到符合质量门槛的成果，成本与时效是否可接受。
一个 API 返回 HTTP 200，不能证明 Worker 正常消费任务；一个 Run 标记 succeeded，不能证明报告引用已核验。
02 · 环境划分与配置治理
2.1 环境模型
| 环境 | 目的 | 数据原则 | 发布策略 |
|---|---|---|---|
| Local | 本地开发、单元测试 | 合成数据与临时凭证 | 开发者自行控制 |
| CI | 自动构建、契约测试 | 短期测试数据 | 每次变更自动运行 |
| Staging | 生产近似集成与恢复演练 | 脱敏数据、独立密钥 | 先于生产部署 |
| Production | 真实用户与任务 | 按租户隔离、备份与审计 | 审批、灰度、回滚 |
Staging 应尽量复现生产的数据库版本、队列行为、Worker 启动方式与对象存储权限；不必为了“环境一致”复制生产用户数据。[工程建议]
2.2 配置分层
配置至少区分：公开构建配置、服务运行配置、敏感密钥、租户策略、Agent 版本配置。禁止把 API Key 编入前端 bundle、容器镜像或 Git 历史。密钥通过受控 Secret Manager 注入，并按环境和角色限制访问。配置变更应记录操作者、审批、时间、目标范围和可回滚版本。[工程建议]
示例：配置分类，不是可直接上线的完整配置。
platform:
environment: production
public_base_url: https://studio.example.invalid
run_default_timeout_seconds: 1800
queue_visibility_timeout_seconds: 120
max_parallel_runs_per_workspace: 3
telemetry:
capture_prompt_bodies: false
capture_tool_payloads: false
retention_days: 14
# 数据库密码、模型密钥、签名密钥通过独立 Secret Manager 注入。注意：运行超时、消息可见性超时、心跳和租约续期必须一起设计；以上数字只是说明字段含义，不代表合理的生产阈值。
03 · 部署拓扑与组件边界
3.1 初期参考拓扑
flowchart TB
U[Browser / API Client] --> EDGE[HTTPS / WAF / Reverse Proxy]
EDGE --> WEB[Studio Web]
EDGE --> API[Platform API / Control Plane]
API --> PG[(PostgreSQL)]
API --> OBJ[(Object Storage)]
API --> Q[(Durable Queue)]
Q --> W1[Agent Worker A]
Q --> W2[Agent Worker B]
W1 --> PG
W2 --> PG
W1 --> OBJ
W2 --> OBJ
W1 --> G[Model / Tool Gateway]
W2 --> G
API --> OT[Telemetry Collector]
W1 --> OT
W2 --> OT
OT --> OBS[Logs / Metrics / Traces]
API --> AUD[(Audit Log)]这是逻辑拓扑，不强制所有组件独立部署。生产环境至少应明确每个组件的持久化位置、故障恢复策略、权限边界、扩容方式和负责人员。[工程建议]
3.2 部署选项与取舍
| 方案 | 优点 | 局限 | 适用条件 |
|---|---|---|---|
| 单主机 Docker Compose | 简单、成本可控、易排查 | 单机故障域、人工运维较多 | 原型/受控试运行 |
| 托管 Web/API + 托管数据库 + 独立 Worker | 减少数据库和接入层运维 | 供应商约束、网络与计费复杂 | 小团队生产 MVP |
| 容器平台/托管 Kubernetes | 部署控制与扩展能力强 | 平台复杂度、成本、维护负担 | 明确规模和隔离需求 |
| 托管工作流引擎 + Agent Worker | 长任务编排和恢复能力可复用 | 引擎语义与成本需要学习 | 审批、重试、长流程复杂 |
决策门槛：先验证数据库恢复、队列语义、任务幂等和密钥隔离；不要因为采用 Kubernetes 就假定系统具备业务层容错。[工程建议]
04 · 容器化、镜像与运行安全
4.1 镜像原则
采用可重复构建、固定依赖版本、最小运行权限、只读文件系统（适用时）、非 root 用户、镜像扫描、软件物料清单（SBOM）和来源可追溯的发布流程。Worker 需要执行外部工具或不可信代码时，必须单独设计沙箱，不应赋予通用 Worker 宿主机 Docker Socket 或广泛文件系统权限。[工程建议]
# 仅用于展示关键原则；须根据实际项目补齐构建与依赖锁定。
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
USER node
CMD ["node", "server.js"]该示例未包含多阶段构建、镜像 digest 固定、健康检查、漏洞扫描和构建产物复制，不可视为已通过安全审计的生产 Dockerfile。
4.2 进程与信号处理
Worker 收到终止信号时应停止领取新任务、尽可能完成或安全中断当前步骤、持久化检查点并释放租约。对于不可中断的外部副作用，应记录执行结果或待对账状态。容器终止宽限期必须覆盖允许的清理流程，但不应依赖无限延长进程存活来维持业务状态。[工程建议]
05 · 数据库、队列与对象存储
5.1 PostgreSQL 作为业务事实来源
建议持久化 Agent Version、Workflow Version、Run、Step Run、Attempt、Approval、Artifact Version、Delivery、Audit Event 和 Outbox。每个状态转移应包含操作者/来源、版本或乐观锁、时间戳及关联 ID。不能把 Redis 缓存或追踪系统当作唯一的业务记录。[工程建议]
5.2 事务 Outbox 与消息语义
sequenceDiagram
participant API as Platform API
participant DB as PostgreSQL
participant REL as Outbox Relay
participant Q as Queue
participant W as Worker
API->>DB: 同一事务写 Run + Outbox
DB-->>API: Commit
REL->>DB: 读取未发送事件
REL->>Q: 发布 RunRequested
Q-->>REL: Ack
REL->>DB: 标记已发布
Q->>W: 至少一次派发
W->>DB: CAS 获取租约/检查状态
W->>DB: 幂等提交结果与事件
W-->>Q: Ack至少一次派发意味着可能重复消费。Relay 可能在发布成功、标记已发布前崩溃；Worker 可能在完成数据库写入、确认队列消息前崩溃。因此必须用事件 ID、任务 ID、唯一约束、租约/版本校验和幂等副作用控制抵御重复，而不是假设消息恰好执行一次。[工程建议]
5.3 外部副作用
邮件发送、支付、文件覆盖、外部数据库写入等操作应具备独立的幂等键或“先记录意图、再执行、再对账”流程。对于无法幂等的第三方接口，重试前需要核对上次调用是否成功，必要时转人工处理；不要把所有异常统一设置为自动无限重试。[工程建议]
5.4 对象存储与产物一致性
Artifact Version 应保存不可变对象 Key、校验和、MIME 类型、字节大小、生成 Run/Step、审核状态与访问策略。数据库提交与对象存储写入通常不构成一个跨系统原子事务：可采用 staging object → 校验 → 数据库登记 → 异步清理孤儿对象的方案，并明确失败补偿。[工程建议]
06 · 发布流水线与变更管理
6.1 CI/CD 参考流程
flowchart LR
A[提交/PR] --> B[Lint + Unit Tests]
B --> C[依赖/密钥/镜像扫描]
C --> D[Build + SBOM]
D --> E[Contract / Integration Tests]
E --> F[Staging Deploy]
F --> G[迁移与恢复验证]
G --> H[人工批准/策略门禁]
H --> I[Production Canary]
I --> J[监测与扩大流量]
J --> K[发布记录与复盘]每次生产发布记录 commit、镜像 digest、数据库迁移版本、Agent/Workflow 定义版本、配置版本、操作人、审批人、回滚路径及观察窗口。[工程建议]
6.2 数据库迁移
优先使用 expand → migrate → contract：先添加向后兼容结构；新旧代码并存期间迁移数据；确认所有旧版本退出后再删除旧字段。应在 Staging 用接近生产的数据规模测试锁竞争、迁移耗时和回退策略。某些破坏性数据迁移不可简单回滚，必须提前准备恢复方案。[工程建议]
6.3 正在运行的任务与版本固定
Run 创建时固定 agent_version_id、workflow_version_id 和适用的工具/模型策略版本。新镜像上线不能默认改变进行中 Run 的解释语义；必要时让旧 Worker 池排空，或为旧 Run 保留兼容执行器。对于中断恢复，必须验证旧检查点能否被新代码读取。[工程建议]
6.4 回滚的真实边界
镜像回滚不等于数据库迁移回滚；工作流版本回退不等于撤销已发送邮件或已写入外部系统的操作。回滚计划需要区分流量切换、代码回退、数据恢复、任务补偿和用户沟通五种措施。[工程建议]
07 · 长任务、伸缩与容量规划
7.1 伸缩信号
除 CPU/内存外，应监控：队列积压、最老任务等待时间、Run 排队时长 P50/P95/P99、每 Worker 活跃执行数、模型 API 限流率、审批等待时长、任务恢复率、每任务成本。仅依据 CPU 自动扩容可能加剧模型供应商限流或预算超支。[工程建议]
7.2 并发控制的层次
- 平台级：全局最大运行数、外部模型供应商速率限制。
- 租户/工作空间级：公平调度、并发配额、预算限制。
- Agent/工具级：对特定工具的并发、隔离与超时。
- 单 Run 级：最大步骤数、最大重试、Token/费用预算、最长墙钟时间。
容量计算示例：若平均到达率为 λ 个任务/分钟，平均系统停留时间为 W 分钟，Little 定律在稳态且条件满足时给出平均在系统任务数 L = λW。该关系不是自动扩容公式，长尾任务、外部限流、非稳态负载与人工审批会影响估算。[官方/规范：排队论基本结果；应用需验证]
7.3 任务优先级与公平性
研究报告长任务和交互式短任务建议分队列或设公平调度，避免大型批处理占满全部 Worker。对于人工审批，暂停的 Run 不应长期占用执行 Worker，但必须保留持久化状态和唤醒事件。[工程建议]
08 · 可观测性与运行监控
8.1 三类遥测与业务事件
| 类型 | 用途 | 示例 | 重要边界 |
|---|---|---|---|
| Metrics | 聚合趋势、SLO、告警 | 失败率、队列等待 P95 | 标签基数控制 |
| Logs | 具体错误和运维事件 | worker restart、DB timeout | 敏感字段脱敏 |
| Traces | 跨服务因果路径诊断 | API → Queue → Worker → Model | 异步上下文传播 |
| Durable Events | 业务事实与状态恢复 | RunStarted、ApprovalGranted | 不可由采样 Trace 替代 |
OpenTelemetry 提供追踪、指标与日志的标准化框架；GenAI 语义约定仍应按具体规范版本检查，不要假定某一字段在所有 SDK 中一致。[官方/规范]
8.2 核心指标字典
| 指标 | 计算口径 | 主要用途 |
|---|---|---|
| Run completion rate | 指定时间窗口内终态完成 Run / 符合统计条件的 Run | 执行完成情况 |
| Technical success rate | succeeded Run / 终态 Run（排除/纳入取消需明确） | 技术稳定性 |
| Qualified artifact rate | 通过质量门禁的 Artifact Version / 已评估版本 | 业务结果质量 |
| Queue wait P95 | started_at - enqueued_at 的第 95 百分位 | 调度瓶颈 |
| Execution duration P95 | ended_at - started_at 的第 95 百分位 | 长尾执行 |
| Recovery success rate | 成功恢复的可恢复故障 Run / 触发恢复的 Run | 韧性 |
| Cost per accepted report | 指定窗口归属成本 / 获得最终批准的报告数 | 单位经济性 |
| Approval waiting P95 | 审批请求至决议的时长 P95 | 人工瓶颈 |
分母和时间窗必须固定并公开。尚未结束的 Run 不应被悄悄计为失败；取消、超时、人工拒绝与质量不合格应分别统计。[工程建议]
8.3 Trace 关联
统一传播 trace_id、run_id、workflow_run_id、step_run_id、attempt_id、agent_version_id 和受限的 tenant_id。队列消息携带 W3C Trace Context 时，异步消费需要正确创建 span link 或父子关系，具体实现遵循所用 SDK 语义；不可把用户原始输入放进 span attribute。[官方/规范 + 工程建议]
09 · SLI、SLO 与告警
9.1 SLO 设计原则
先定义用户可感知的服务承诺，再选择指标。示例：“在约定时间内，符合前置条件的研究 Run 能进入终态并返回可查询的状态”。具体目标值必须通过真实基线和业务要求决定，本文不虚构 99.9% 等承诺。[工程建议]
9.2 告警矩阵
| 场景 | 信号 | 初步动作 | 注意事项 |
|---|---|---|---|
| API 大量失败 | 5xx 比例/延迟突增 | 检查发布、依赖和数据库 | 关注用户影响范围 |
| 队列卡住 | oldest queued age 超阈值 | 检查 Worker、租约与限流 | 区分无任务与无法消费 |
| Run 长期无进展 | 心跳/事件时间超阈值 | 查询 Attempt 与外部调用 | 避免误杀合法长调用 |
| 模型供应商异常 | 429/5xx、超时集中 | 限流、熔断、降级 | 避免重试风暴 |
| 审批长期等待 | pending approval age 超阈值 | 通知负责人 | 不能自动代替批准 |
| 成本异常 | 费用增速、单 Run 预算 | 暂停新任务/限制并发 | 估算与账单区分 |
| 备份失败 | 备份任务失败或恢复点缺失 | 修复并重新验证 | 备份成功仍需演练 |
| 安全异常 | 异常密钥使用/跨租户拒绝 | 凭证轮换、隔离与调查 | 保全审计证据 |
告警应配置 owner、severity、去重键、抑制条件、升级策略、恢复条件与 Runbook 链接。应避免把每次单独的模型调用失败都直接升级为最高级别事故。[工程建议]
10 · 故障处置与 Runbook
10.1 标准事故流程
发现 → 分级 → 明确影响范围 → 稳定系统 → 定位 → 缓解/恢复 → 验证 → 复盘 → 跟踪整改。 事故期间优先保证数据完整性和租户隔离，再恢复吞吐量。用户沟通应区分已知事实、未知影响和下一次更新时间。[工程建议]
10.2 Runbook A：队列积压
- 确认
queuedRun 数量、最老等待时间和受影响租户。 - 核查 Worker 是否存活、是否能获取任务、是否遭遇外部限流。
- 检查消息重复投递、租约过期、死信队列和异常重试循环。
- 必要时限制新任务入队，保留已经提交的任务记录。
- 恢复 Worker 后按幂等键核对，防止重复执行副作用。
- 验证队列等待分位数、完成率和任务成本回归正常。
10.3 Runbook B：模型供应商中断
- 区分供应商区域故障、配额耗尽、凭证失效与请求参数错误。
- 对可重试错误采用有上限的指数退避和抖动；避免同步重试风暴。
- 如配置允许且满足数据驻留/质量约束，按预先批准策略切换模型。
- 不得静默更换已冻结的关键模型策略并继续声称结果可复现。
- 对中断的 Run 标记等待、失败或可恢复状态，并提供用户可见说明。
10.4 Runbook C：Worker 崩溃与恢复
- 检查最后一次持久化 checkpoint、lease owner、lease expiry、attempt 状态。
- 判断上次外部工具调用是否可能已产生副作用。
- 使用 CAS/唯一约束争夺任务所有权，禁止两个 Worker 同时提交结果。
- 从可恢复边界重启；不可确定外部副作用时先对账或转人工。
- 验证状态、事件、Artifact 版本和成本归属不重复。
10.5 Runbook D：疑似跨租户数据泄漏
- 暂停相关查询路径、令牌或连接器，避免扩大暴露。
- 保全审计与最小必要证据，限制调查访问权限。
- 确定泄漏对象、时间窗口、读取者与数据类别。
- 按适用法律、合同和内部制度执行通知及响应。
- 修复权限校验并运行跨租户回归测试；恢复前进行独立复核。
11 · 备份、灾难恢复与数据保留
11.1 RPO/RTO
- RPO：允许丢失的数据时间窗口；例如最近一次可恢复点距事故发生的时长。
- RTO：业务服务恢复到可接受状态的目标时长。
二者应按业务影响分析设定，不能凭云供应商的默认备份选项直接推定。审批、Run 事件、产物元数据、对象存储内容、密钥与配置需要相互匹配的恢复点。[工程建议]
11.2 备份策略
PostgreSQL 可评估基础备份 + WAL 归档/PITR；对象存储可评估版本化、跨区域复制和生命周期策略；密钥与配置应通过独立安全流程备份。备份应加密、权限隔离、监控失败并防止同一账号被攻击时备份同时删除。[官方/规范 + 工程建议]
11.3 恢复演练
每次演练至少验证：能否在隔离环境恢复数据库；Artifact 元数据能否定位对象；Run 状态和 Outbox 是否一致；旧签名链接是否失效；Worker 是否会重复消费恢复前任务；恢复后是否存在跨租户访问；关键用户旅程是否成功。演练记录实际 RPO/RTO，不能只记录“备份文件存在”。[工程建议]
11.4 保留与删除
分别定义业务记录、审计记录、追踪日志、模型输入输出、产物、备份和删除墓碑的保留周期。数据删除需处理对象存储版本、搜索索引、缓存、导出文件和备份过期策略；不要承诺无法验证的即时全域物理删除。[工程建议]
12 · 安全、合规与租户隔离
12.1 核心控制
| 风险 | 推荐控制 | 验证方式 |
|---|---|---|
| 凭证泄漏 | Secret Manager、短期凭证、轮换 | 扫描构建产物和日志 |
| 跨租户访问 | 所有资源访问进行 tenant/workspace 授权 | 越权负例测试 |
| 工具越权 | 工具级最小权限、审批与隔离 | 恶意输入与工具权限测试 |
| Prompt/PII 泄漏 | 默认不采集原文、脱敏、限时保留 | Trace/Log 检查 |
| 不可信代码执行 | 沙箱、网络与文件系统隔离 | 逃逸/权限测试 |
| 供应链风险 | 锁定依赖、镜像扫描、SBOM | CI 安全门禁 |
| Webhook 伪造 | 签名验证、时间窗、重放保护 | 重放/伪造测试 |
| 管理误操作 | 审批、影响分析、审计、回退 | 高风险操作演练 |
模型供应商和工具服务可能跨境处理数据；生产部署前需评估用户合同、适用法律、数据驻留、保留条款和供应商设置。本文不提供具体司法辖区的合规结论。[工程建议]
12.2 日志与追踪的权限
原始 Prompt、上传文件、模型响应和工具输出可能包含敏感数据。日志查看应独立授权，导出需要审计；不要因为是“内部运维”就默认可读取所有租户内容。异常排查优先使用结构化错误码、摘要、哈希、脱敏字段与受控临时访问。[工程建议]
13 · 成本管理与容量预算
13.1 成本分类
成本分为固定基础设施、弹性计算、模型输入/输出 Token、缓存/检索、外部搜索或工具、对象存储与流量、观测数据、人工审核。按 workspace_id、run_id、agent_version_id 和 provider 归因时应明确共享成本的分摊规则。[工程建议]
13.2 估算与账单对账
平台可以实时估算模型调用费用，但最终账单可能受到缓存、阶梯价格、折扣、汇率和供应商结算规则影响。UI 应标明 estimated_cost 与 billed_cost 的区别；价格表要有生效时间和版本。[工程建议]
13.3 成本护栏
建议建立单 Run 最大预算、工作空间月预算、模型调用限流、异常消耗告警和人工提额流程。触发预算时应区分：拒绝新任务、暂停可恢复任务、继续必要的收尾步骤，避免直接终止导致不一致。[工程建议]
14 · 运维数据模型与接口参考
14.1 关键对象
DeploymentRelease(release_id, image_digest, config_version, migration_version, status)
WorkerHeartbeat(worker_id, pool_id, last_seen_at, active_attempts, version)
RunLease(run_id, attempt_id, owner_id, expires_at, fencing_token)
Incident(incident_id, severity, status, owner_id, started_at, resolved_at)
AlertRule(rule_id, metric_query, threshold, window, owner_id, enabled)
AlertInstance(alert_id, rule_id, fingerprint, status, first_seen_at, last_seen_at)
BackupRecord(backup_id, scope, started_at, completed_at, checksum, status)
RestoreDrill(drill_id, backup_id, observed_rpo, observed_rto, result)
CostLedger(entry_id, run_id, provider, estimated_amount, billed_amount, currency)
AuditEvent(event_id, actor_id, action, target, outcome, created_at)14.2 参考 SQL：运行租约
CREATE TABLE run_leases (
run_id UUID PRIMARY KEY,
attempt_id UUID NOT NULL,
owner_id TEXT NOT NULL,
fencing_token BIGINT NOT NULL DEFAULT 1,
expires_at TIMESTAMPTZ NOT NULL,
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX run_leases_expiry_idx ON run_leases(expires_at);租约续期和结果提交需采用事务、条件更新与 fencing token 校验。此 DDL 仅表示最小字段，不包含完整的 tenant 隔离、权限、历史表和索引设计。[工程建议]
14.3 参考 API
GET /v1/ops/health
GET /v1/ops/readiness
GET /v1/ops/queues?workspace_id=...
GET /v1/ops/workers
GET /v1/ops/incidents
POST /v1/ops/incidents/{incident_id}/acknowledge
GET /v1/ops/releases
POST /v1/ops/releases/{release_id}/rollback-request
GET /v1/ops/backups
POST /v1/ops/restore-drills以上为拟议接口，不代表现有平台已经提供。健康检查接口不应暴露数据库凭证、内部网络信息或租户数据；运维管理接口必须强制身份与角色校验。[工程建议]
15 · Studio 贯穿案例：从开发到生产
15.1 目标业务流程
flowchart LR
U[用户创建研究任务] --> T[选题 Agent]
T --> R1[选题审核]
R1 -->|返工| T
R1 -->|通过| D[深度调研]
D --> A[深度分析]
A --> R2[质量与引用审核]
R2 -->|返工| D
R2 -->|通过| H[人工审批]
H -->|批准| P[固定 Artifact Version]
P --> E[导出与交付]15.2 上线前必须验证的关键场景
场景 A：审核暂停跨部署。 人工审批期间升级 Web/API/Worker，审批完成后原 Run 使用固定版本继续执行；不得丢失上下文或重复生成产物。
场景 B：调研 Worker 崩溃。 调研工具调用期间 Worker 退出，系统能区分可安全重试和需要人工核对的外部副作用，恢复后只登记一份最终 Artifact Version。
场景 C：模型供应商限流。 限流期间队列增长可见、重试有上限、预算可控、用户看到“等待/降级/失败”的准确状态。
场景 D：数据库恢复。 在隔离环境恢复数据库和对象存储，验证 Run、审核、版本、交付记录一致，并证明租户权限未被绕过。
场景 E：成本超限。 单项目触发预算阈值，系统阻止新的高成本任务，已进行中的步骤按照明示策略收尾或暂停，审计记录完整。
15.3 推荐的阶段性上线策略
| 阶段 | 上线目标 | 必备运维能力 | 放行条件 |
|---|---|---|---|
| D0 · 本地集成 | 开发者可重复启动完整链路 | 环境模板、合成数据、基础日志 | 单 Run 端到端成功 |
| D1 · 内部 Staging | 完整研究工作流可复现 | CI、迁移、持久化、恢复演练 | 审核暂停与重启通过 |
| D2 · 小规模试运行 | 少量真实用户与任务 | 监控、告警、备份、权限、成本护栏 | 故障与越权测试通过 |
| D3 · 正式生产 | 有明确服务责任和发布流程 | 值守、Runbook、变更控制、审计 | 业务 SLO 与恢复目标可验证 |
| D4 · 扩容优化 | 根据实际瓶颈扩容 | 容量预测、灰度、压测与费用分析 | 数据证明扩容必要性 |
这是一条参考路线，不代表 Studio 已达到任一阶段。实际推进应以现有代码审计与验收结果为准。[待验证]
16 · 常见失败模式与反例
| 反例 | 后果 | 改进 |
|---|---|---|
| 只部署 Web，不部署持续运行 Worker | 请求能提交但任务不执行 | 验证完整执行链路 |
| 用内存保存 Run 状态 | 重启后任务丢失 | 持久化状态与检查点 |
| 假定队列“只投递一次” | 重复工具调用或重复交付 | 幂等、租约与对账 |
| 直接回滚数据库结构 | 新旧代码不兼容或数据丢失 | expand/migrate/contract |
| 仅监控 CPU | 供应商限流、质量下降不可见 | 业务指标与外部依赖指标 |
| 日志保存完整 Prompt | 敏感数据泄漏 | 默认脱敏与最小采集 |
| 只做备份不做恢复 | 故障时无法恢复 | 定期隔离恢复演练 |
| 自动无限重试 | 成本失控、重试风暴 | 预算与重试上限 |
| 以执行成功代表报告合格 | 低质量成果被交付 | 独立质量门禁 |
| 审批暂停占用 Worker | 并发能力被耗尽 | 持久化暂停并释放资源 |
| Worker 任意执行不可信代码 | 主机或数据被攻击 | 沙箱与最小权限 |
| 将所有租户放进同一管理员日志 | 访问范围过大 | 权限隔离与审计 |
17 · 工程验证矩阵（设计用例，未执行）
下表为上线前建议验证的测试，不是已经通过的测试报告。
| 编号 | 测试目标 | 预期结果 |
|---|---|---|
| T01 | 开发环境启动 | 全链路可从干净环境重建 |
| T02 | 环境变量校验 | 缺少关键配置时明确失败 |
| T03 | Secret 扫描 | 镜像与前端产物无真实密钥 |
| T04 | 容器非 root | 默认运行权限最小化 |
| T05 | 健康检查 | 进程健康与服务就绪分开 |
| T06 | 数据库连接中断 | 请求失败可诊断且不污染状态 |
| T07 | 队列连接中断 | 已提交 Run 可恢复派发 |
| T08 | Worker 重启 | 持久化任务不丢失 |
| T09 | Worker SIGTERM | 停止领取新任务并安全释放租约 |
| T10 | 租约到期 | 仅合法新 owner 可接管 |
| T11 | 并发领取 | 同一 Attempt 不被双重提交 |
| T12 | Outbox 中途崩溃 | 事件最终可重发且不重复生效 |
| T13 | 消息重复投递 | 幂等消费保持唯一业务结果 |
| T14 | 模型 429 | 退避与限流有上限 |
| T15 | 模型 5xx | 可重试错误分类正确 |
| T16 | 模型长超时 | Run 状态与重试策略正确 |
| T17 | 工具不可逆副作用 | 重试前完成对账或转人工 |
| T18 | 审批暂停 | Worker 资源释放且状态保留 |
| T19 | 审批跨发布 | 固定版本与检查点可恢复 |
| T20 | 审核返工 | 返回指定节点且保留历史 |
| T21 | Agent 版本升级 | 既有 Run 版本不漂移 |
| T22 | Workflow 版本升级 | 既有 Run 执行语义稳定 |
| T23 | 数据库向后兼容迁移 | 新旧应用在过渡期兼容 |
| T24 | 破坏性迁移预演 | 有明确备份与恢复策略 |
| T25 | 灰度发布 | 错误率升高可停止扩大流量 |
| T26 | 代码回滚 | 识别并处理数据库兼容风险 |
| T27 | 对象写入中断 | 孤儿对象可回收 |
| T28 | 产物校验和 | 下载内容与登记哈希一致 |
| T29 | 备份完成 | 备份任务可监控 |
| T30 | 隔离恢复 | 数据与对象可重建 |
| T31 | 恢复后 Outbox | 不会重复产生外部副作用 |
| T32 | 跨租户 API 访问 | 未经授权请求拒绝 |
| T33 | 跨租户对象访问 | 签名 URL 与对象策略有效 |
| T34 | 运维 API 权限 | 非管理员不可执行高危操作 |
| T35 | 日志脱敏 | Prompt 与 PII 默认不泄漏 |
| T36 | Trace 关联 | Run 与跨服务调用可追踪 |
| T37 | 队列积压告警 | 超过阈值时正确触发和恢复 |
| T38 | Run 卡住告警 | 能区分长任务与异常停滞 |
| T39 | 审批超时提醒 | 通知正确负责人 |
| T40 | 告警去重 | 同一故障不会造成通知风暴 |
| T41 | 单 Run 成本上限 | 超限后按策略处理 |
| T42 | 月度工作空间预算 | 预算跨并发任务生效 |
| T43 | 费用对账 | 估算与实际账单差异可解释 |
| T44 | 高并发公平调度 | 单一租户不能独占资源 |
| T45 | Worker 扩缩容 | 不丢任务、不重复交付 |
| T46 | 供应商切换 | 遵守数据与质量策略 |
| T47 | 对象存储不可用 | 产物写入失败可恢复 |
| T48 | 审计日志 | 高风险操作可追溯 |
| T49 | 删除与保留 | 按策略清理缓存、索引、对象 |
| T50 | 事故 Runbook 演练 | 值守人员能按步骤恢复 |
| T51 | 发布记录 | 版本、审批、配置可追溯 |
| T52 | 端到端研究报告 | 产物质量、审核、交付状态分离 |
| T53 | 恢复时间测量 | 实际 RPO/RTO 有证据 |
| T54 | 安全事件隔离 | 异常令牌可及时撤销 |
18 · 最小可交付运维清单
对于准备让 Studio 从原型进入小规模真实使用的团队，建议至少具备以下条件，并将每项对应到可核验的证据：
- 有可重复的构建与部署流程；生产密钥与代码分离。
- API、Worker、数据库、队列和对象存储的故障边界明确。
- Run、Approval、Artifact Version 的状态持久化并可查询。
- 队列重复消费与 Worker 崩溃恢复通过测试。
- 有受控发布、数据库迁移和回滚预案。
- 有核心业务指标、告警负责人和事故处置 Runbook。
- 有备份、恢复演练及实际 RPO/RTO 记录。
- 有租户权限测试、日志脱敏和安全审计。
- 有模型用量统计、预算上限与异常成本处置。
- 有端到端真实工作流验收，明确质量审核和交付状态。
判断标准：完成清单的意思是能够出示代码、配置、测试结果、恢复演练记录或监控截图，而不是仅在设计文档中列出相关功能。[工程建议]
19 · 与本领域其他专题的衔接
| 相邻专题 | 与本篇的关系 |
|---|---|
| P1 Control Plane | 运维配置、权限与状态控制的技术基础 |
| P2 Execution Plane | Worker、队列、运行沙箱与恢复机制 |
| P5 Deployment & Runtime Management | Agent 部署实例与版本管理；本篇研究整个平台的部署运维 |
| P11 Multi-tenancy & Isolation | 租户隔离与资源边界 |
| P12 Platform Governance | 配额、预算、策略和审计 |
| F8 Agent Monitoring | 用户侧运行观测；本篇关注运维 SLI/SLO 和事故处理 |
| F12 Platform Administration | 管理员控制台；本篇研究其背后的运营流程与技术保障 |
| 04/04/03 System Design | 规定系统组件和边界，本篇落实部署拓扑与运维策略 |
| 04/04/04 Development Roadmap | 规定分阶段建设，本篇提供各阶段生产准备门槛 |
| 04/04/06 Testing & Optimization | 下一篇进一步建立工程测试、Agent 评估、压测与优化方法 |
20 · 待验证问题与后续研究
待验证的项目事实：Studio 当前真实部署位置、数据库与队列实现、现有 Worker、Agent Runtime、网络区域、目标用户量、月度预算、模型供应商、用户数据分类、团队值守能力、目标 RPO/RTO，均需通过代码审计或实际决策确认。不能根据 Phase 1 前端演示推断这些工程能力已具备。
建议的下一轮实证研究：在隔离 Staging 环境中完成一次真实研究 Run，记录 API/Worker/数据库/对象存储调用路径；注入 Worker 崩溃、队列重复投递、模型限流和审批跨发布四种故障；测量恢复时长、重复副作用、产物一致性与单位成本；将结果写入 ADR 和下一阶段验收基线。[待验证]
附录 A：参考文献与原始资料
以下为优先使用的官方标准、项目文档和经典工程资料。链接用于追溯机制与概念；具体产品版本、价格、兼容性与云服务配置应在实施时重新核验。本文未声称对所有链接在本次写作中完成在线逐页核查。
- OpenTelemetry, Documentation. opentelemetry.io/docs
- OpenTelemetry, Semantic Conventions for Generative AI Systems. opentelemetry.io/docs/specs/semconv/gen-ai
- W3C, Trace Context. www.w3.org/TR/trace-context
- Prometheus, Documentation. prometheus.io/docs/introduction/overview
- Grafana Labs, Documentation. grafana.com/docs
- Google, Site Reliability Engineering. sre.google/sre-book/table-of-contents
- Google, The Site Reliability Workbook. sre.google/workbook/table-of-contents
- Kubernetes, Liveness, Readiness, and Startup Probes. kubernetes.io/docs/concepts/configuration/liveness-readiness-startup-probes
- Kubernetes, Pod Lifecycle. kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle
- Docker, Dockerfile Best Practices. docs.docker.com/build/building/best-practices
- PostgreSQL, Backup and Restore. www.postgresql.org/docs/current/backup.html
- PostgreSQL, Continuous Archiving and Point-in-Time Recovery. www.postgresql.org/docs/current/continuous-archiving.html
- PostgreSQL, Explicit Locking. www.postgresql.org/docs/current/explicit-locking.html
- OWASP, Top 10 for Large Language Model Applications. genai.owasp.org/llm-top-10
- NIST, AI Risk Management Framework. www.nist.gov/itl/ai-risk-management-framework
- NIST, Cybersecurity Framework 2.0. www.nist.gov/cyberframework
- CloudEvents, Specification. github.com/cloudevents/spec
- OpenAPI Initiative, OpenAPI Specification. spec.openapis.org/oas/latest.html
- Temporal, Documentation. docs.temporal.io
- Redis, Documentation. redis.io/docs/latest
- OpenTelemetry, Collector. opentelemetry.io/docs/collector
- GitHub, Actions Documentation. docs.github.com/en/actions
- CNCF, Cloud Native Security Whitepaper. github.com/cncf/tag-security/tree/main/security-whitepaper
附录 B：研究证据、验证声明与适用边界
B.1 证据等级
- [官方/规范]：官方文档明确规定的概念、接口或机制；具体实施必须核对所用版本。
- [工程建议]：根据软件可靠性、分布式系统与 Agent 业务需求形成的参考设计，不等于唯一最佳实践。
- [待验证]：涉及 Studio 现有代码、具体供应商、真实负载、价格、恢复目标或运维能力，尚无实测证据。
B.2 未执行的验证
本文未进行 Studio 代码审计、真实云部署、容器扫描、数据库恢复演练、供应商故障注入、性能压测、成本对账或安全渗透测试。第 17 节为待执行验收用例，不能视为测试报告或合规认证。
B.3 适用范围
本篇适用于需要持续运行、长任务执行、人工审批、产物版本管理与外部模型/工具集成的 Agent Platform。对于纯本地单用户脚本，可删减多租户和正式值守流程；对于受监管、高敏感或高可用业务，需要额外的法规、数据驻留、冗余架构、第三方审计与安全设计。
B.4 结论的可证伪条件
如果目标工作负载证明单机方案不能满足恢复目标，应升级部署与存储架构；如果长任务实际无需恢复且可安全重算，可简化检查点设计；如果外部服务不支持幂等操作，必须调整重试与补偿策略；如果生产观测显示模型成本而非计算资源主导预算，应优先优化调用链和质量门禁，而非盲目扩容 Worker。
下一篇：06 · 如何验证和持续改进 Agent Platform？ - Testing & Optimization。