++

docs/07-阶段七-工程化部署与运维/02-部署与伸缩.md

@@ -0,0 +1,187 @@
+# 阶段七 · 小点 2：部署与伸缩
+
+> 所属：阶段七 工程化、部署与运维
+> 定位：怎么把 Agent 从「我本机能跑」一步步扩展到「团队共享」再到「生产可扩」。这一讲走一遍容器化 → 云原生 → 部署演进路线，并讲清任务队列与优雅停机两个关键机制。
+
+## 精简大纲
+
+1. 容器化：Docker / Compose 本地整套环境
+2. 云原生：K8s 部署、HPA、任务队列、优雅停机
+3. 部署演进路线（量力而行）
+4. 边缘轻量方案
+
+## 学习内容详情
+
+> 核心认知：部署的宗旨是「量力而行」。内部场景多数停在 Compose / 单机 Docker 就够，**别为 3 个用户上 K8s 集群**。
+
+### 1. 容器化（Compose 本地全家桶）
+
+`docker-compose.yml` 一键拉起「应用 + worker + Redis（队列 broker / 会话缓存）+ PostgreSQL（Checkpointer）+ Qdrant（向量库）」。
+
+```yaml
+# docker-compose.yml (最小全家桶: 应用 + worker + 三个存储)
+services:
+  api:                        # ① API 接入层
+    image: my-agent:1.0
+    command: uvicorn app.main:app --host 0.0.0.0 --port 8000
+    ports: ["8000:8000"]      # 仅 api 对外暴露
+    depends_on: [redis, pg, qdrant]
+    environment:
+      REDIS_URL: redis://redis:6379
+      DATABASE_URL: postgres://agent:agent@pg/agent
+  worker:                     # ② 长任务 worker: 同镜像不同入口
+    image: my-agent:1.0
+    command: arq app.worker.main.WorkerSettings   # 换 arq 入口即可
+    depends_on: [redis, pg, qdrant]
+    deploy:
+      replicas: 3             # 可水平加 worker 扩吞吐(普通 `docker compose` 会忽略 replicas, 需 swarm 或 --compatibility)
+  redis:
+    image: redis:7            # 队列 broker / 会话缓存
+  pg:
+    image: postgres:16        # Checkpointer 状态落库
+  qdrant:
+    image: qdrant/qdrant      # 向量库
+```
+
+> ⏳ **短期可不深究**：上面 worker 服务里的 `deploy.replicas: 3` 在**普通 `docker compose` 下会被忽略**（只有 swarm 模式或加 `--compatibility` 才生效）——第一遍只要知道"worker 想水平扩展需要 swarm/真正的集群工具"，不用纠结这个 yaml 字段在单机 compose 下的行为差异。
+
+> 🔬 **深度理解 · 容器化与环境隔离**：
+> 1. **本质**：把"应用 + 它运行所需的完整依赖"打包成一个可移植的标准镜像，从根本上把"环境差异"从部署问题里剥离——同一份镜像在本地、CI、与生产跑出的行为一致。
+> 2. **机制**：Docker 借助 Linux 内核的 namespace（进程/网络/文件系统隔离）与 cgroup（CPU/内存限额）做轻量虚拟化；Compose 再用一条 yaml 把"应用 + worker + 存储"声明成服务编排，容器间靠内部 DNS 名互相访问，只把对外端口暴露出去。
+> 3. **为什么重要**：Agent 服务依赖众多（模型密钥、PG、Redis、Qdrant、MinIO），不做环境隔离最容易犯"我本机能跑、别人不行"的系统性错误；容器化正好对应阶段七"状态机服务"的复杂度——依赖封闭后，搬家常驻环境都比裸进程简单。
+> 4. **易错点**：① 只容器化却不挂数据卷（volume），容器重建即丢数据（这里 PG/Redis/Qdrant 必须持久化）；② 用 `latest` 标签不锁版本，环境不可复现；③ 密钥写死在镜像里（应走环境变量 / Secret）；④ 误以为"容器化 = 生产就绪"，真正的隔离还有网络策略、资源限额与可观测三件事要补。
+
+- **worker 与 API 同镜像不同入口**（command 换 arq 入口），生产省略 ports（不对外暴露）。
+
+### 2. 云原生（K8s 生产部署）
+
+```mermaid
+graph LR
+    A[Deployment<br/>声明副本数] --> B[Service<br/>稳定访问入口]
+    B --> C[HPA<br/>自动扩缩容]
+    C --> D[按CPU/QPS<br/>增减 Pod]
+```
+
+#### 2.1 K8s 最小集
+
+- **Deployment**（声明副本数）+ **Service**（稳定访问入口）+ **HPA**（自动扩缩容）。
+- **Pod**：最小部署单元；需要本地模型时可「应用容器 + 模型 sidecar 容器」同 Pod 共享网络。
+
+> ⏳ **短期可不深究**：这个「应用容器 + 模型 sidecar 容器」共处一个 Pod 的做法，是**需要在本地跑私有/离线模型**时才用到的偏冷场景——大多数调用云端 API 的 Agent 用不到，第一遍知道有 sidecar 这个模式即可。
+
+- **HPA**：按指标（CPU / 自定义 QPS）自动增减 Pod。**注意：扩容解决「请求多」，解决不了「单请求慢」**（那要靠异步任务 + 队列）。
+
+> 🔬 **深度理解 · 无状态伸缩与存储粘性**：
+> 1. **本质**：**"能水平扩缩"的前提是服务无状态**——任意一个副本都必须能平等地接请求、处理完不依赖"我这台机器"上的私有记忆；一旦副本里存了只有自己知道的会话/进度，扩容出的新副本接不了活，缩容又可能丢状态。
+> 2. **机制**：HPA 按 CPU / 自定义 QPS 等指标增减 Pod，这就要求把**可变状态外置**到共享存储——会话历史进 Redis、Checkpointer 进 PG、向量切片进 Qdrant、文件进 MinIO，副本退化成"无脑执行"的计算单元。
+> 3. **为什么重要**：Agent 比普通服务更易踩"粘性"坑——若把会话上下文放**内存**，负载均衡随机转发，用户请求漂移到别的副本就会"追问丢了上文、上下文断了"；这在单机演示时完全看不出来，一上 K8s + HPA 就露馅。这正是 Compose 里把 Redis/PG/Qdrant 单独起成服务的本质原因。
+> 4. **易错点**：① 把"无状态的模型推理"误当有状态——它是可无限扩的，有状态的只是上下文/进度这类可变数据；② 会话缓存做在**内存级**且负载均衡无亲和性（sticky session），用户漂移即丢上下文，要用共享的 Redis 解决；③ 只给计算侧扩容、存储侧（Redis 单点 / PG 无主备）没跟上，照样成为新瓶颈——"计算可扩，存储要跟上"。
+
+#### 2.2 任务队列（Task Queue）
+
+```mermaid
+graph LR
+    A[API 入队<br/>立即返回 task_id] --> B[(队列)]
+    B --> C[worker 进程池消费执行]
+    C --> D[结果回调]
+```
+
+- **作用**：长耗时 Agent 任务的缓冲带——**API 只入队即返回 `task_id`**，worker 进程池消费执行（Celery / Arq / RQ）。
+- **价值**：
+  1. **削峰**：突发流量排队而非打垮服务；
+  2. **隔离**：慢任务不占 API 资源；
+  3. **可水平加 worker 扩吞吐**。
+
+```python
+# API 侧: 入队即返回, 不阻塞 (Arq 示意)
+async def submit_task(request, queue):
+    job_id = await queue.enqueue_job("run_agent", request.model.table_dump())
+    return {"task_id": job_id.id, "status": "queued"}   # 立即返回, 不等结果
+```
+
+#### 2.3 优雅停机（Graceful Shutdown）
+
+```mermaid
+graph TD
+    A[收到下线信号] --> B[停止接新请求]
+    B --> C[等存量请求处理完]
+    C --> D[状态已由 Checkpointer 落盘]
+    D --> E[再退出]
+```
+
+- 收到下线信号后**停止接新请求 → 等存量请求处理完 → 状态已由 Checkpointer 落盘 → 再退出**。没有它，每次发布都会切断在途 Agent 任务。
+
+> 🔬 **深度理解 · 优雅停机（Graceful Shutdown）**：
+> 1. **本质**：在进程/副本被终止前，给"在途请求"处理善后的机会——先停接新流量，把正在跑的 Agent 任务跑完或安全落盘再退出；否则每次发布、缩容、节点驱逐都会硬切断在途任务。
+> 2. **机制**：收到下线信号（SIGTERM）后：① 把自己从负载均衡/服务发现中摘除，不再接着新请求；② 在**宽限期**内等存量请求处理完（超过宽限期仍会强制终止，防止拖死）；③ 把 Agent 关键状态交给 Checkpointer 落盘（会话/任务进度写 PG / Redis）；④ 处理完毕再 exit。K8s 侧由 `preStop` hook、`terminationGracePeriodSeconds` 与 readiness/startup probe 配合完成。
+> 3. **为什么重要**：Agent 任务往往长耗时（一次对话几十秒到几分钟），发布又是常态；没有优雅停机，每次发布都批量打断在途 Agent 请求、丢进度——用户侧表现为"回答到一半断了"。这也是把 Agent 当"服务"而非"脚本"的关键差别之一。
+> 4. **易错点**：① 收到 SIGTERM 但不真正等待存量请求（等于没做）；② 宽限期设太短，长任务没跑完就被强杀；③ 只"等"却不落盘——停机后再拉起仍需靠 Checkpointer 恢复，光等也白等；④ 忽略强杀（KILL）之外的兜底，重负载下对已在途的操作仍需幂等重试。
+
+#### 2.4 其他要点
+
+- **滚动发布**：`rollingUpdate` 策略 + `readinessProbe`（就绪探针，没好不接流量）。
+- 镜像带版本号禁用 `latest`；密钥走 K8s Secret。
+
+### 3. 部署演进路线（量力而行）
+
+| 阶段 | 方案 |
+|-|-|
+| 阶段 0 本地 | `uvicorn --reload` 直接跑 |
+| 阶段 1 团队 | Compose 全家桶——一键起，环境一致 |
+| 阶段 2 小生产 | 单机 Docker + systemd 自启 + Nginx 反代（K8s 前不必上） |
+| 阶段 3 规模化 | K8s + HPA + worker 池 + Secret 管理密钥 |
+| 阶段 4 补充形态 | Serverless / 云函数——低并发、事件驱动、突发流量（如定时批处理、webhook 触发的 Agent 任务）；AWS Lambda / 阿里云函数计算 / Cloudflare Workers |
+
+```mermaid
+graph LR
+    A[本地 --reload] --> B[Compose 全家桶]
+    B --> C[单机 Docker+systemd+Nginx]
+    C --> D[K8s+HPA+worker池]
+```
+
+- **务实建议**：大多数内部 Agent 服务停在**阶段 2** 就够了——**别为 3 个用户上 K8s 集群**。
+- **Serverless / 云函数（补充形态，不替代常驻服务）**：适合低并发、事件驱动、突发流量的任务型 Agent（定时批处理、webhook 触发的报告生成 / 通知），零闲置按调用计费；主流平台 AWS Lambda / 阿里云函数计算 / Cloudflare Workers。
+  > ⚠️ **两个硬限制**：① **冷启动延迟**——实例按需拉起，首次调用多出秒级甚至更久的冷启，**不适合对话首响**这类延迟敏感链路；② **流式长连接支持受限**——Agent 的 SSE 流式输出需要平台支持响应流（部分函数平台不支持或不完整），不支持就得退化成「一次性返回 / 轮询」。
+
+### 4. 边缘轻量方案
+
+- 用 1~4B 小模型（Qwen2.5-1.5B 级）跑端侧（手机 / 盒子）原型：**隐私好、离线可用**。
+- 代价是**能力断崖**——只适合窄场景固定流程，别指望复杂工具调用。
+
+> ⏳ **短期可不深究**：端侧小模型（1~4B 跑在手机/盒子）属边缘/偏门场景，模型能力迭代又快——第一遍了解"有这条路：隐私好、离线可用、能力断崖"即可，真要做端侧原型时再按当时的最新小模型评估选型，不必现在深挖。
+
+## 本节自检
+
+- [ ] 能编写 Compose 全家桶并一键拉起整套环境
+- [ ] 能说清任务队列解决什么问题、优雅停机为什么必要
+- [ ] 能画出部署演进四个阶段并判断当前该停在哪
+
+---
+
+## 本节常见面试题（深度解析）
+
+> 针对本节核心知识的面试高频点，配合"本质+机制"式理解，能让你答得既有深度又有广度。
+
+### 面试题 1：为什么"扩容 / 加机器"解决不了"单请求慢"？任务队列怎么补上这一块？
+- **面试官想考察**：是否真正理解水平扩缩的本质与"异步化"的用途，而非只会搬 HPA 名词。
+- **专业作答（含深度）**：
+  1. **根本区别**：扩容提升的是**并发吞吐**（单请求内部的 LLM 调用延迟是固有的，加副本也改变不了单个请求要花几十秒）；"单请求慢"要靠**延迟优化**（缓存、小模型、精简 prompt）与**异步化**处理。
+  2. **任务队列的作用**：API 入队即返回 `task_id` → worker 池消费执行 → 结果回调；提供**削峰**（突发排队不把服务打垮）、**隔离**（慢任务不占 API 资源）、**可水平加 worker 扩吞吐**三条价值。
+  3. **两者配合**：把长耗时的 Agent 任务从同步请求里拆出去，用队列做缓冲带，再用加 worker 的方式扩消费；这样"并发高"与"单请求慢"两类问题分开解决。
+- **加分亮点 / 深度追问**：可主动点明"HPA 解决并发容量、队列解决长任务、缓存/小模型解决延迟，三者解决的是不同维度的问题"；被追问"为什么不让 API 直接同步做"时，答"长任务会占满 API 工作线程，把简单快请求也拖垮，且无超时兜底"。
+
+### 面试题 2：优雅停机（Graceful Shutdown）为什么必要？一个 Agent 服务如何做到？
+- **面试官想考察**：是否有服务化发布的成熟度，是否踩过"发布切流打断请求"的坑。
+- **专业作答（含深度）**：
+  1. **必要性**：Agent 任务长耗时，且常驻服务要频繁滚动发布；无优雅停机，每次发布/缩容都会硬切断在途 Agent 请求、丢进度。
+  2. **四步做法**：收到 SIGTERM → 摘除流量、不再接新请求 → 宽限期内等存量跑完 → Checkpointer 把关键状态落盘 → 再退出；K8s 用 `preStop` + `terminationGracePeriodSeconds` + readiness probe 配好。
+  3. **与 Checkpointer 的关系**：停机前必须把进行中的会话/进度落盘，否则重启无法恢复——"等存量"与"落盘"两者缺一不可。
+- **加分亮点 / 深度追问**：可补一句"滚动发布要配就绪探针，新副本 readiness 通过前不接流量"；被追问"宽限期设多少"时，答"参考 P95/P99 长尾定，超过宽限期强杀后依赖幂等重试兜底"。
+
+### 面试题 3：Agent 服务为什么必须"无状态"才能水平扩缩？Redis 会话缓存又为何会造成"粘性"？
+- **面试官想考察**：是否理解状态与伸缩的关系、分布式里的粘性问题，以及"共享存储外置"的动机。
+- **专业作答（含深度）**：
+  1. **无状态的前提**：任意副本都能平等接请求、不依赖本机私有记忆；一旦有私有状态，扩容新副本接不了活、缩容丢状态，水平扩缩就失去意义。
+  2. **外置原则**：会话历史进 Redis、Checkpointer 进 PG、向量进 Qdrant、文件进 MinIO，副本只做无脑计算。
+  3. **粘性怎么来**：若把会话缓存放**单实例内存**，负载均衡随机转发时用户请求漂移到别的副本就丢上下文（产生粘性依赖）；共享的 Redis 正是为了打破这种"状态长在某台机器上"。
+- **加分亮点 / 深度追问**：可主动补充"计算侧无状态解决了伸缩，但存储侧（Redis/PG 自身）的扩容与一致性是下一个瓶颈"；被追问"Redis 会话如何避免多副本写冲突"时，答"靠会话 ID 分片 / 单写多读或引入事务边界，需求不同权衡不同"。