Appearance
Graceful Shutdown 与可复现部署
1. 为什么这组知识要一起学
掌握 Harness 部署需要的 Linux 进程模型、容器、网络、Secret、健康检查和优雅退出。
这几个知识点处在同一条工程链上。如果只记单个名词，很容易在真实系统里把责任放错层：例如让模型管理程序事实、让数据库 transaction 承担外部 API 原子性，或把一个 provider SDK 的行为误认为 Agent 的通用规律。
2. Mental Model
部署目标是可重复启动、可观测、可优雅停止；Container 是进程/文件系统打包隔离手段，不等于强安全 sandbox。
text
Source + lockfile → Image Build → Config/Secrets → Container Process → Health → Signal → Graceful Shutdown → Logs3. 核心机制
Graceful Shutdown
liveness 判断进程需重启，readiness 判断能否接流量；shutdown 先停止新请求，再 checkpoint/cancel/flush trace。
Resource Limit
CPU/memory/pid/time limit 限制 blast radius；部署记录 image digest、config/version，能够从同一 commit/lockfile 重建。
Reproducible Deployment
CPU/memory/pid/time limit 限制 blast radius；部署记录 image digest、config/version，能够从同一 commit/lockfile 重建。
4. 最小实现 / 伪代码
下面代码只表达边界和生命周期，不要求照抄到项目中：
dockerfile
FROM python:3.14-slim
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --locked --no-dev
COPY src ./src
CMD ["uv", "run", "python", "-m", "shadow_harness"]真正实现时应把 I/O、状态持久化、错误翻译和策略注入拆成可测试组件，而不是把示例扩成一个巨型函数。
5. 在 Shadow Harness 中怎么落地
API/worker/runtime 使用相同配置模型；Dockerfile 固定 Python/依赖，health/readiness 与 run shutdown 分开。
建议为本章涉及的行为留下明确的 domain object、interface 和 trace event；只要一个关键行为只能通过读日志猜测，就说明 Runtime contract 仍不够清晰。
6. Production Engineering 检查项
- PID1/signal 正确传播
- CPU/memory limit
- 只读/最小镜像与非 root 视场景
- 日志走 stdout/stderr
- secret 不进 image
7. Failure Modes
7.1 latest tag 导致不可复现
当出现「latest tag 导致不可复现」时，从 image digest、config、process/signal、resource limit、volume/network/secret 和 checkpoint shutdown 顺序定位。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。
7.2 容器停止时 active run 直接丢
当出现「容器停止时 active run 直接丢」时，从 image digest、config、process/signal、resource limit、volume/network/secret 和 checkpoint shutdown 顺序定位。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。
7.3 把 volume 当备份
当出现「把 volume 当备份」时，从 image digest、config、process/signal、resource limit、volume/network/secret 和 checkpoint shutdown 顺序定位。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。
7.4 认为容器默认能防恶意代码
当出现「认为容器默认能防恶意代码」时，从 image digest、config、process/signal、resource limit、volume/network/secret 和 checkpoint shutdown 顺序定位。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。
8. Trade-offs
本机部署简单；容器可重复；更强 sandbox/VM 增加隔离与启动成本。
设计记录最好明确：当前约束是什么、备选方案有哪些、为什么现在选这个、未来什么条件出现时需要重构。 这样 ADR 才能随着模型和基础设施变化被重新审视。
9. Experiment / Evaluation
构建同一 commit 两次、发送 SIGTERM、限制 memory/CPU、重启 worker，验证 run/checkpoint 与日志。
实验应固定数据集、版本和环境，至少记录 success、latency、token/cost、attempt/step 数以及失败类型；涉及随机模型时需要重复运行而不是只看一次结果。
10. 常见问题
基础：Graceful Shutdown 最容易被误解的点是什么？
liveness 判断进程需重启，readiness 判断能否接流量；shutdown 先停止新请求，再 checkpoint/cancel/flush trace。
机制：这些能力在一次 Run 的哪个生命周期阶段生效？
沿着 Source + lockfile → Image Build → Config/Secrets → Container Process → Health → Signal → Graceful Shutdown → Logs 找位置，并明确它的输入、输出、持久化事实和失败传播。
工程：如果这一层失败，应该由谁恢复？
先区分 transient failure、invalid input、permission、semantic failure 与 irreversible side effect。恢复策略属于拥有该状态与副作用的 Runtime/adapter，而不是交给模型自由决定。
设计：规模扩大 10 倍后，哪个假设最先失效？
优先检查 context/token、并发/连接池、catalog 大小、持久化吞吐、trace 体积、身份与租户隔离。不要默认“多加机器”能解决语义和一致性问题。
11. Sources
12. 本文结论
掌握本文的标准不是能背定义，而是能画出数据流、写出最小 contract、解释失败恢复，并用测试或 benchmark 证明设计没有只停留在概念层。