phase 5 part 4: java-spring awareness, k8s basics with validated manifests, run_examples supports single-file Java

topics/backend/java-spring/01-java-spring-awareness.md

@@ -0,0 +1,110 @@
+---
+id: backend.java-spring.awareness
+title: Java / Spring Boot（了解级）：读懂项目结构、IoC 与依赖注入、分层、事务注解和与 Go / Python 的对照
+type: lesson
+domain: backend
+stack: [java-spring]
+tags: [Java, Spring Boot, IoC, 依赖注入, 注解, 事务, JPA, MyBatis, 虚拟线程]
+level: basic
+prerequisites: [backend.go.index]
+est_hours: 2
+related: [backend.java-spring.scenario.call-java-service, backend.java-spring.interview]
+week: [14]
+order: 1
+---
+
+# Java / Spring Boot（了解级）：读懂项目结构、IoC 与依赖注入、分层、事务注解和与 Go / Python 的对照
+
+> 定位：**能读懂、能对接、面试能聊概念**，不作为主线。BOSS直聘 2026-10-23 的调研中，有 AI 应用岗位写了“熟悉 Java / Go / Python 其中之一”，或者团队已有 Java 业务系统需要 Agent 去调用。示例只用 JDK，在 JDK 26（JDK 21+ 即可）上实际运行通过；Spring 代码为示意，未编译。以官方文档为准：https://docs.spring.io/spring-boot/ 。
+
+## 解释说明
+
+### 与你熟悉的技术对照
+
+| 概念 | Java / Spring Boot | Go | Python / FastAPI |
+| --- | --- | --- | --- |
+| 数据类 | `record` | struct | `dataclass` / Pydantic 模型 |
+| 路由 | `@RestController` + `@GetMapping` | Gin 路由 | `@app.get` |
+| 依赖注入 | IoC 容器 + 构造器注入 | 手动在 main 中组装 | `Depends` |
+| 参数校验 | `@Valid` + Bean Validation | binding 标签 | Pydantic |
+| 数据访问 | Spring Data JPA / MyBatis | database/sql、sqlc、GORM | SQLAlchemy |
+| 事务 | `@Transactional` | 手动 `tx.Begin/Commit` | `session.begin()` |
+| 并发 | 线程池、虚拟线程（JDK 21） | goroutine | asyncio |
+| 构建 | Maven / Gradle | go build | uv / pip |
+
+### Spring 的核心概念
+
+- **IoC 容器**：对象（Bean）由容器创建和管理，你声明依赖，容器注入。推荐**构造器注入**（依赖不可变、便于测试）。
+- **分层**：Controller（接收请求）→ Service（业务逻辑、事务）→ Repository（数据访问）。
+- **自动配置**：Spring Boot 根据依赖和配置自动创建常用组件（数据源、Web 服务器），配置在 `application.yml`。
+- **`@Transactional` 的坑**：基于代理实现，同一个类内部方法调用不经过代理，事务不生效；默认只对运行时异常回滚。
+- **AI 相关**：Spring AI、LangChain4j 等框架让 Java 项目也能接入大模型（版本变化快，以官方文档为准）。
+
+### 怎么快速读懂一个 Spring Boot 项目
+
+1. 看 `pom.xml` / `build.gradle`：依赖了什么。
+2. 找带 `@SpringBootApplication` 的启动类。
+3. 看 `application.yml`：数据库、端口、外部服务地址。
+4. 从 Controller 顺着调用链读到 Service 和 Repository。
+5. 看全局异常处理（`@RestControllerAdvice`）和拦截器 / 过滤器（鉴权）。
+
+## 案例
+
+你负责的 Python Agent 需要调用公司的 Java 订单服务：读懂它的接口定义（Controller 和 DTO）、错误码、鉴权方式、分页规则，把它封装成 Agent 的工具。
+
+## 代码示例
+
+只用 JDK 的对照示例 [examples/java-basics/OrderDemo.java](examples/java-basics/OrderDemo.java)（`java OrderDemo.java` 运行通过）：record、接口 + 构造器注入、Optional、Stream 分组汇总、BigDecimal 金额、虚拟线程。
+
+```text
+跨租户查询被拒绝: 订单不存在: B001
+t1 按状态汇总: {paid=20.00, refunded=5.00}
+用 double 计算金额的问题: 0.1 + 0.2 = 0.30000000000000004
+1000 个虚拟线程计数结果: 1000
+```
+
+对应的 Spring Boot 写法（示意，未编译）：
+
+```java
+@RestController
+@RequestMapping("/orders")
+class OrderController {
+    private final OrderService service;
+    OrderController(OrderService service) { this.service = service; }   // 构造器注入，无需 @Autowired
+
+    @GetMapping("/{id}")
+    OrderDto get(@PathVariable String id, @RequestHeader("X-Tenant-Id") String tenant) {
+        return OrderDto.from(service.get(tenant, id));
+    }
+}
+
+@Service
+class OrderService {
+    private final OrderRepository repo;
+    OrderService(OrderRepository repo) { this.repo = repo; }
+
+    @Transactional
+    public void refund(String tenant, String id) { /* 修改订单 + 写退款记录，在一个事务中 */ }
+}
+
+@RestControllerAdvice
+class GlobalErrors {
+    @ExceptionHandler(NotFoundException.class)
+    ResponseEntity<Map<String, String>> notFound(NotFoundException e) {
+        return ResponseEntity.status(404).body(Map.of("code", "NOT_FOUND", "message", e.getMessage()));
+    }
+}
+```
+
+## 易错点
+
+- 金额用 `double`。
+- 同类内部调用带 `@Transactional` 的方法，以为事务生效。
+- 受检异常被捕获后吞掉，事务没有回滚。
+- 在面试中把“了解”说成“精通”：如实说明能读懂并对接，主语言是 Go / Python。
+
+## 面试常问
+
+- 什么是 IoC 和依赖注入？
+- `@Transactional` 什么情况下会失效？
+- 你不会 Java，如何和 Java 团队协作？

topics/backend/java-spring/examples/java-basics/OrderDemo.java

@@ -0,0 +1,87 @@
+// Java 基础对照示例（不依赖 Spring，只用 JDK）：record、接口 + 构造器注入、Optional、Stream、异常、并发
+// 运行（JDK 21+）：java OrderDemo.java      —— 单文件源码直接运行，不需要先 javac
+import java.math.BigDecimal;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.stream.Collectors;
+
+public class OrderDemo {
+    // record：不可变数据类，自动生成构造器、getter、equals/hashCode/toString（类似 Go struct / Python dataclass(frozen)）
+    record Order(String id, String tenant, String status, BigDecimal amount) {}
+
+    // 接口 + 实现：Spring 中会用 @Repository 标注，由容器创建并注入
+    interface OrderRepository {
+        Optional<Order> findById(String id);
+        List<Order> findByTenant(String tenant);
+    }
+
+    static class InMemoryOrderRepository implements OrderRepository {
+        private final Map<String, Order> data = new ConcurrentHashMap<>();
+        InMemoryOrderRepository(List<Order> seed) { seed.forEach(o -> data.put(o.id(), o)); }
+        public Optional<Order> findById(String id) { return Optional.ofNullable(data.get(id)); }
+        public List<Order> findByTenant(String tenant) {
+            return data.values().stream().filter(o -> o.tenant().equals(tenant)).toList();
+        }
+    }
+
+    static class NotFoundException extends RuntimeException {
+        NotFoundException(String msg) { super(msg); }
+    }
+
+    // 构造器注入：Spring 推荐的方式（@Service），依赖是 final 的，测试时可以直接传入假实现
+    static class OrderService {
+        private final OrderRepository repo;
+        OrderService(OrderRepository repo) { this.repo = repo; }
+
+        Order get(String tenant, String id) {
+            return repo.findById(id)
+                    .filter(o -> o.tenant().equals(tenant))            // 租户隔离：别的租户的订单当作不存在
+                    .orElseThrow(() -> new NotFoundException("订单不存在: " + id));
+        }
+
+        Map<String, BigDecimal> sumByStatus(String tenant) {           // Stream 分组汇总；金额用 BigDecimal，不用 double
+            return repo.findByTenant(tenant).stream()
+                    .collect(Collectors.groupingBy(Order::status,
+                            Collectors.reducing(BigDecimal.ZERO, Order::amount, BigDecimal::add)));
+        }
+    }
+
+    public static void main(String[] args) throws Exception {
+        var repo = new InMemoryOrderRepository(List.of(
+                new Order("A001", "t1", "paid", new BigDecimal("19.90")),
+                new Order("A002", "t1", "paid", new BigDecimal("0.10")),
+                new Order("A003", "t1", "refunded", new BigDecimal("5.00")),
+                new Order("B001", "t2", "paid", new BigDecimal("99.00"))));
+        var service = new OrderService(repo);
+
+        check(service.get("t1", "A001").amount().equals(new BigDecimal("19.90")), "查询订单");
+        try {
+            service.get("t1", "B001");
+            check(false, "跨租户应当查不到");
+        } catch (NotFoundException e) {
+            System.out.println("跨租户查询被拒绝: " + e.getMessage());
+        }
+        var sums = service.sumByStatus("t1");
+        check(sums.get("paid").equals(new BigDecimal("20.00")), "BigDecimal 精确求和");
+        System.out.println("t1 按状态汇总: " + new java.util.TreeMap<>(sums));
+        System.out.println("用 double 计算金额的问题: 0.1 + 0.2 = " + (0.1 + 0.2));
+
+        // 并发：虚拟线程（JDK 21 正式特性）+ 原子计数，类比 Go 的 goroutine
+        var counter = new AtomicInteger();
+        try (ExecutorService pool = Executors.newVirtualThreadPerTaskExecutor()) {
+            for (int i = 0; i < 1000; i++) pool.submit(counter::incrementAndGet);
+        }                                                               // try-with-resources：等待全部任务完成
+        check(counter.get() == 1000, "虚拟线程并发计数");
+        System.out.println("1000 个虚拟线程计数结果: " + counter.get());
+        System.out.println("全部检查通过");
+    }
+
+    static void check(boolean ok, String name) {
+        if (!ok) throw new AssertionError("检查失败: " + name);
+    }
+}

topics/backend/java-spring/index.md

@@ -4,12 +4,32 @@ title: Java / Spring Boot（了解级）
 type: index
 domain: backend
 stack: [java-spring]
-tags: []
+tags: [Java, Spring Boot, 了解级]
 week: [14]
 ---
 
 # Java / Spring Boot（了解级）
 
-了解级：全栈岗位常见要求，能读懂代码、知道分层和常用注解。
+能读懂、能对接、面试能聊概念。BOSS直聘 2026-10-23 的调研中有岗位要求“Java / Go / Python 其中之一”或需要对接已有 Java 系统，不作为主线投入。
 
-> 本专题建设中：课程、企业场景、面试题和示例代码会陆续补充。
+## 学习路线
+
+| 顺序 | 课程 | 级别 | 预计 |
+| --- | --- | --- | --- |
+| 1 | [Java / Spring Boot（了解级）：读懂项目结构、IoC 与依赖注入、分层、事务注解和与 Go / Python 的对照](01-java-spring-awareness.md) | 基础 | 2 小时 |
+
+## 企业场景
+
+- [Python Agent 调用公司已有的 Java 业务系统：读接口、封装工具、错误映射和联调](scenarios/call-java-service.md)
+
+## 面试题
+
+- [Java / Spring Boot（了解级）面试题](interview.md)
+
+## 示例代码
+
+- [examples/java-basics](examples/java-basics/)：只用 JDK 的对照示例（`java OrderDemo.java`，JDK 21+；已运行通过）。Spring 代码为示意，未编译。
+
+## 在 16 周计划中
+
+- [第 14 周：后端扩展与部署](../../../plan/week14-backend-extend-deploy.md)

topics/backend/java-spring/interview.md

@@ -0,0 +1,67 @@
+---
+id: backend.java-spring.interview
+title: Java / Spring Boot（了解级）面试题
+type: interview
+domain: backend
+stack: [java-spring]
+tags: [Java, Spring Boot, IoC, 事务, 面试]
+level: basic
+related: [backend.java-spring.awareness]
+week: [14, 16]
+---
+
+# Java / Spring Boot（了解级）面试题
+
+## 基础
+
+### 【基础】什么是 IoC 和依赖注入？
+
+**参考答案**：控制反转：对象的创建和依赖组装由容器负责，而不是对象自己 `new`；依赖注入是实现方式，通过构造器、setter 或字段注入。好处是解耦、便于替换实现和测试。
+
+**追问**：为什么推荐构造器注入？→ 依赖可以声明为 final、不会出现未初始化的状态、单元测试时直接传入假实现。
+
+### 【基础】Spring Boot 项目通常怎么分层？
+
+**参考答案**：Controller 处理 HTTP 和参数校验，Service 写业务逻辑和事务边界，Repository 负责数据访问；DTO 与实体分开，全局异常处理统一返回格式。
+
+**追问**：和你写的 Go 项目怎么对应？→ handler / service / repository 三层，思路一致，只是 Go 中依赖在 main 中手动组装。
+
+### 【基础】Java 中金额用什么类型？
+
+**参考答案**：`BigDecimal`（或以分为单位的 `long`），不能用 `double`，二进制浮点数无法精确表示 0.1 等小数。
+
+**追问**：`BigDecimal` 比较相等要注意什么？→ `equals` 会比较精度（`2.0` 和 `2.00` 不相等），数值比较用 `compareTo`。
+
+## 进阶
+
+### 【进阶】`@Transactional` 在什么情况下会失效？
+
+**参考答案**：同类内部方法调用（不经过代理）、方法不是 public（取决于代理方式和版本）、异常被捕获没有抛出、抛出受检异常而未配置 `rollbackFor`、数据库引擎不支持事务。
+
+**追问**：Go 中怎么做类似的事？→ 显式开启事务并把 `tx` 传入各个仓储方法，或者封装一个 `WithTx(func(tx) error)` 帮助函数。
+
+### 【进阶】虚拟线程是什么？和 goroutine 有什么相似之处？
+
+**参考答案**：JDK 21 正式提供的轻量级线程，由 JVM 调度到少量平台线程上，阻塞 I/O 时让出载体线程，可以创建大量并发任务；与 goroutine 一样让“同步写法 + 高并发”成为可能。
+
+**追问**：有什么需要注意？→ 不适合 CPU 密集任务；某些同步块或本地调用会“钉住”载体线程（不同 JDK 版本有改进，以官方说明为准）；不要池化虚拟线程。
+
+### 【进阶】Java 团队说接口“已经幂等”，你怎么验证？
+
+**参考答案**：看实现：是否有唯一约束或幂等键表、状态机是否只允许合法转换；做测试：同一请求并发和重复发送，检查数据只产生一条、返回结果一致。
+
+**追问**：幂等键应该谁生成？→ 调用方生成并在重试时复用；服务端存储键和结果，设定过期时间。
+
+## 场景题
+
+### 【场景题】你的 Python Agent 需要调用公司的 Java 订单系统，怎么做？
+
+**参考答案**：读 Controller / DTO 明确契约；Python 侧封装工具，透传用户身份；错误码映射为可重试、告知用户、转人工；非幂等接口推动增加幂等键；契约测试和 request id 联调。详见[调用 Java 服务场景](scenarios/call-java-service.md)。
+
+**追问**：对方接口很慢怎么办？→ 设置超时，查询类接口加缓存，长操作改为异步（提交后轮询或回调），Agent 告诉用户“已提交，稍后通知”。
+
+### 【场景题】面试官问“你会 Java 吗”，你怎么回答？
+
+**参考答案**：如实说明：主语言是 Go / Python，能读懂 Spring Boot 项目的结构和代码，理解 IoC、分层、事务等核心概念，做过（或能做）与 Java 服务的对接；如果岗位需要，可以快速上手。不夸大。
+
+**追问**：举个例子说明你读懂过 Java 代码？→ 讲清一次具体的对接：从哪个 Controller 读出了什么契约、发现了什么问题（例如非幂等）、怎么解决。

topics/backend/java-spring/scenarios/call-java-service.md

@@ -0,0 +1,82 @@
+---
+id: backend.java-spring.scenario.call-java-service
+title: Python Agent 调用公司已有的 Java 业务系统：读接口、封装工具、错误映射和联调
+type: scenario
+domain: backend
+stack: [java-spring, function-calling, fastapi]
+tags: [系统对接, 工具封装, 错误码映射, OpenAPI, 联调, 幂等]
+level: intermediate
+prerequisites: [backend.java-spring.awareness, ai.function-calling.tool-loop]
+est_hours: 2
+related: [backend.java-spring.interview, ai.function-calling.scenario.safe-business-tools]
+week: [14]
+---
+
+# Python Agent 调用公司已有的 Java 业务系统：读接口、封装工具、错误映射和联调
+
+## 业务背景与问题
+
+公司的订单、售后系统是多年的 Spring Boot 服务。新做的 AI 客服 Agent（Python）需要“查订单、查物流、发起退款申请”。问题：
+
+1. 接口文档过期，字段含义要读代码才知道；
+2. Java 服务的错误码体系复杂，Agent 不知道哪些错误可以重试、哪些要告诉用户；
+3. 退款接口不是幂等的，Agent 重试导致重复申请；
+4. 联调时双方互相指责。
+
+## 约束
+
+- 不能大改 Java 服务，只能小范围加接口或参数。
+- Agent 不能拥有超过用户本人的权限。
+
+## 方案设计
+
+1. **读接口**：从 Controller 和 DTO 读出真实的字段、校验规则、错误码；如果服务集成了 OpenAPI（springdoc 一类工具），导出规范生成 Python 客户端；否则自己写 Pydantic 模型。
+2. **封装工具**：每个业务能力一个工具，入参严格校验；工具层负责鉴权透传（用户令牌或服务账号 + 用户 id）、超时、重试（只对查询类和幂等接口）。
+3. **错误映射**：把 Java 错误码分为三类——可重试（超时、限流）、需要告诉用户（订单不存在、超过退款期限）、需要转人工（系统异常）；返回给模型的是结构化的可读信息，而不是堆栈。
+4. **幂等**：和 Java 团队约定退款接口增加 `Idempotency-Key` 请求头（服务端用唯一约束实现），Agent 在一次会话中对同一操作使用同一个 key。
+5. **联调**：先写契约测试（请求 / 响应样例），双方各自对着样例开发；用 request id 串起两边日志。
+
+## 关键代码
+
+```python
+class JavaErrorKind(str, Enum):
+    RETRYABLE = "retryable"
+    USER_FACING = "user_facing"
+    HANDOFF = "handoff"
+
+ERROR_MAP = {
+    "ORDER_NOT_FOUND": (JavaErrorKind.USER_FACING, "没有找到这个订单，请核对订单号"),
+    "REFUND_EXPIRED": (JavaErrorKind.USER_FACING, "已超过可退款期限"),
+    "RATE_LIMITED": (JavaErrorKind.RETRYABLE, "系统繁忙"),
+}
+
+def call_refund(client: httpx.Client, user: User, order_id: str, reason: str, idem_key: str) -> dict:
+    r = client.post("/api/refunds", json={"orderId": order_id, "reason": reason},
+                    headers={"Authorization": f"Bearer {user.token}", "Idempotency-Key": idem_key}, timeout=5)
+    if r.is_success:
+        return {"ok": True, "refund_id": r.json()["data"]["refundId"]}
+    code = r.json().get("code", "UNKNOWN")
+    kind, msg = ERROR_MAP.get(code, (JavaErrorKind.HANDOFF, "系统异常，已为你转人工"))
+    return {"ok": False, "kind": kind, "message": msg}       # 给模型的是结构化结果，不是堆栈
+```
+
+工具调用安全的完整讨论见[安全的业务工具](../../../ai/function-calling/scenarios/safe-business-tools.md)。
+
+## 取舍
+
+| 选择 | 优点 | 缺点 |
+| --- | --- | --- |
+| **Python 工具层直接调用 Java 接口（本方案）** | 不改动 Java 服务主体 | 需要维护错误映射和模型定义 |
+| Java 团队提供专门给 Agent 的聚合接口 | 语义更清晰 | 依赖对方排期 |
+| 用 Spring AI 在 Java 侧实现 Agent | 技术栈统一 | 团队 AI 生态以 Python 为主 |
+
+## 易错点
+
+- Agent 使用高权限服务账号，绕过了用户级权限。
+- 对非幂等接口自动重试。
+- 把 Java 的异常堆栈直接交给模型，既泄露内部信息又让模型困惑。
+- 金额字段在 JSON 中是字符串还是数字没有约定，精度丢失。
+
+## 面试怎么讲
+
+> “我不是 Java 开发，但能读懂 Spring Boot 项目：从 Controller 和 DTO 读出真实的接口契约。对接时我在 Python 侧封装工具，鉴权透传用户身份；把 Java 的错误码分成可重试、告知用户、转人工三类，给模型结构化结果；和 Java 团队约定退款接口支持幂等键。联调前先写契约样例，用 request id 串联日志。”

topics/devops/k8s/01-core-objects.md

@@ -0,0 +1,118 @@
+---
+id: devops.k8s.core-objects
+title: Kubernetes 基础：Pod / Deployment / Service / Ingress、配置与密钥、探针、滚动更新和扩缩容
+type: lesson
+domain: devops
+stack: [k8s]
+tags: [Kubernetes, Pod, Deployment, Service, Ingress, ConfigMap, Secret, 探针, 滚动更新, HPA, PDB, kubectl]
+level: basic
+prerequisites: [devops.docker.image-dockerfile]
+est_hours: 3
+related: [devops.k8s.scenario.agent-rollout, devops.nginx.scenario.ai-gateway-sse-canary, devops.k8s.interview]
+week: [14]
+order: 1
+---
+
+# Kubernetes 基础：Pod / Deployment / Service / Ingress、配置与密钥、探针、滚动更新和扩缩容
+
+> 定位：**能读懂和修改清单、能用 kubectl 排查**，集群搭建和运维不在范围内。BOSS直聘 2026-10-23 的调研中有岗位把 K8s 列为要求或加分项。示例清单通过 kubeconform 结构校验（6 个资源全部有效）和团队规范测试（5 个测试通过），**没有在真实集群中部署**。以官方文档为准：https://kubernetes.io/zh-cn/docs/home/ 。
+
+## 解释说明
+
+### 核心对象
+
+| 对象 | 作用 | 类比 |
+| --- | --- | --- |
+| **Pod** | 最小调度单位，一个或几个容器共享网络和存储 | 一组 `docker run` |
+| **Deployment** | 声明“要几个什么样的 Pod”，负责滚动更新和回滚 | Compose 的 service + 副本数 |
+| **Service** | 给一组 Pod 一个稳定的虚拟 IP / DNS 名，做负载均衡 | 内部的负载均衡器 |
+| **Ingress** | 集群入口的 HTTP 路由（域名、路径、TLS） | Nginx 反向代理配置 |
+| **ConfigMap / Secret** | 配置 / 敏感信息，以环境变量或文件注入 | `.env` |
+| **HPA** | 按指标自动调整副本数 | — |
+| **PDB** | 主动驱逐（节点维护）时至少保留多少可用 Pod | — |
+| Namespace | 资源隔离和配额 | — |
+
+**声明式**：你提交“期望状态”（YAML），控制器不断把“实际状态”调整为期望状态。Pod 挂了会被重建，而不是由你手动重启。
+
+**标签和选择器**：Deployment、Service 通过标签选择 Pod，标签不一致是新手最常见的问题（Service 没有后端）。
+
+### 三种探针
+
+| 探针 | 失败的后果 | 检查什么 |
+| --- | --- | --- |
+| startupProbe | 启动阶段超时则重启 | 启动是否完成（给慢启动的应用留时间） |
+| readinessProbe | 从 Service 的后端中摘除，不重启 | 能否处理请求（可检查关键依赖） |
+| livenessProbe | 重启容器 | 进程是否卡死（**不要检查外部依赖**） |
+
+### 滚动更新和优雅退出
+
+- `maxSurge` / `maxUnavailable` 控制更新节奏；`kubectl rollout undo` 回滚。
+- Pod 终止流程：从 Service 端点中移除 + 执行 `preStop` → 发送 SIGTERM → 等待 `terminationGracePeriodSeconds` → SIGKILL。应用要处理 SIGTERM：停止接收新请求、完成进行中的请求（AI 流式回答可能持续几十秒）。
+
+### 常用排查命令
+
+```bash
+kubectl get pods -l app.kubernetes.io/name=agent-api -o wide
+kubectl describe pod <pod>              # 看事件：拉取镜像失败、探针失败、OOMKilled、调度失败
+kubectl logs <pod> --previous           # 看上一次崩溃前的日志
+kubectl get endpoints agent-api         # Service 是否有后端
+kubectl rollout status deploy/agent-api
+kubectl rollout undo deploy/agent-api
+```
+
+## 案例
+
+把 AI Agent API 部署到公司的 K8s 集群：3 副本、零不可用的滚动更新、启动慢时用 startupProbe 保护、密钥由 Secret 注入、Ingress 关闭缓冲以支持 SSE、HPA 按负载扩到 10 个、PDB 保证节点维护时至少 2 个可用。
+
+## 代码示例
+
+清单：[examples/agent-api](examples/agent-api/)（`deployment.yaml`、`service.yaml`、`ingress.yaml`、`configmap.yaml`、`hpa.yaml`），校验结果：
+
+```text
+$ kubeconform -strict -summary *.yaml
+Summary: 6 resources found in 5 files - Valid: 6, Invalid: 0, Errors: 0, Skipped: 0
+$ pytest -q test_manifests.py
+5 passed
+```
+
+Deployment 关键部分：
+
+```yaml
+strategy:
+  type: RollingUpdate
+  rollingUpdate: { maxSurge: 1, maxUnavailable: 0 }
+template:
+  spec:
+    terminationGracePeriodSeconds: 90
+    containers:
+      - name: api
+        image: registry.example.com/agent-api:1.4.2
+        env:
+          - name: LLM_API_KEY
+            valueFrom: { secretKeyRef: { name: agent-api-secrets, key: llm-api-key } }
+        resources:
+          requests: { cpu: "250m", memory: "256Mi" }
+          limits: { memory: "512Mi" }
+        startupProbe:   { httpGet: { path: /healthz, port: http }, periodSeconds: 5, failureThreshold: 24 }
+        readinessProbe: { httpGet: { path: /readyz,  port: http }, periodSeconds: 5 }
+        livenessProbe:  { httpGet: { path: /healthz, port: http }, periodSeconds: 10 }
+```
+
+团队规范测试（[test_manifests.py](examples/agent-api/test_manifests.py)）检查：选择器与标签一致、镜像固定版本、有资源和探针、密钥不明文、PDB 小于最小副本数、仓库中没有 Secret 对象。
+
+## 易错点
+
+- Service 选择器和 Pod 标签不一致。
+- 存活探针检查数据库，数据库抖动时所有 Pod 被重启，雪上加霜。
+- 没有 startupProbe，慢启动的应用被存活探针反复杀掉（CrashLoopBackOff）。
+- 镜像用 `latest`，无法确定线上跑的是哪个版本，回滚也不可靠。
+- 内存没有限制或限制过小（OOMKilled）。
+- 应用不处理 SIGTERM，滚动更新时正在进行的流式回答被切断。
+- 把 Secret 的 YAML（只是 base64，不是加密）提交到仓库。
+
+## 面试常问
+
+- Pod、Deployment、Service 的关系？
+- 三种探针的区别？
+- 滚动更新怎么做到不中断服务？
+- Pod 一直 CrashLoopBackOff 怎么排查？

topics/devops/k8s/examples/agent-api/configmap.yaml

@@ -0,0 +1,11 @@
+# 非敏感配置。敏感信息（模型 API Key、数据库密码）放 Secret，并且不要提交到仓库
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: agent-api-config
+  labels:
+    app.kubernetes.io/name: agent-api
+data:
+  LOG_LEVEL: "info"
+  MODEL_TIMEOUT_SECONDS: "60"
+  REDIS_URL: "redis://redis.default.svc.cluster.local:6379/0"

topics/devops/k8s/examples/agent-api/deployment.yaml

@@ -0,0 +1,75 @@
+# AI Agent API 的 Deployment：滚动更新、三种探针、资源限制、非 root 运行、优雅退出
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: agent-api
+  labels:
+    app.kubernetes.io/name: agent-api
+spec:
+  replicas: 3
+  revisionHistoryLimit: 5
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: agent-api
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 1          # 更新时最多多出 1 个 Pod
+      maxUnavailable: 0    # 更新过程中可用 Pod 数不减少
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: agent-api
+    spec:
+      terminationGracePeriodSeconds: 90     # 留时间让正在进行的流式回答结束
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 10001
+      containers:
+        - name: api
+          image: registry.example.com/agent-api:1.4.2    # 使用固定版本，不用 latest
+          ports:
+            - name: http
+              containerPort: 8000
+          envFrom:
+            - configMapRef:
+                name: agent-api-config
+          env:
+            - name: LLM_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: agent-api-secrets     # 由运维或密钥管理系统创建，不在仓库中
+                  key: llm-api-key
+          resources:
+            requests:
+              cpu: "250m"
+              memory: "256Mi"
+            limits:
+              memory: "512Mi"                 # 内存设上限防止拖垮节点；CPU 不设上限避免被限流（按团队规范）
+          startupProbe:                       # 启动慢（加载模型配置、预热连接）时，避免被存活探针误杀
+            httpGet:
+              path: /healthz
+              port: http
+            periodSeconds: 5
+            failureThreshold: 24
+          readinessProbe:                     # 未就绪时不接收流量（例如依赖的 Redis 不可用）
+            httpGet:
+              path: /readyz
+              port: http
+            periodSeconds: 5
+            failureThreshold: 3
+          livenessProbe:                      # 进程卡死时重启；不要检查外部依赖，否则依赖故障会引发全体重启
+            httpGet:
+              path: /healthz
+              port: http
+            periodSeconds: 10
+            failureThreshold: 3
+          lifecycle:
+            preStop:                          # 先等负载均衡摘除，再收到 SIGTERM。sleep 动作需要较新的 Kubernetes（1.30+，以官方文档为准），旧版本用 exec sleep
+              sleep:
+                seconds: 5
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]

topics/devops/k8s/examples/agent-api/hpa.yaml

@@ -0,0 +1,33 @@
+# 按 CPU 自动扩缩容。AI 服务多为 I/O 等待，CPU 不一定能反映负载，可改用自定义指标（并发请求数、队列长度）
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: agent-api
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: agent-api
+  minReplicas: 3
+  maxReplicas: 10
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+  behavior:
+    scaleDown:
+      stabilizationWindowSeconds: 300   # 缩容慢一点，避免抖动
+---
+# 节点维护（驱逐）时至少保留 2 个可用 Pod
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata:
+  name: agent-api
+spec:
+  minAvailable: 2
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: agent-api

topics/devops/k8s/examples/agent-api/ingress.yaml

@@ -0,0 +1,24 @@
+# 以 ingress-nginx 为例：SSE 流式接口要关闭缓冲、加长读超时。注解名称以所用 Ingress 控制器的文档为准
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: agent-api
+  annotations:
+    nginx.ingress.kubernetes.io/proxy-buffering: "off"
+    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
+spec:
+  ingressClassName: nginx
+  tls:
+    - hosts: ["agent.example.com"]
+      secretName: agent-example-tls
+  rules:
+    - host: agent.example.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: agent-api
+                port:
+                  name: http

topics/devops/k8s/examples/agent-api/service.yaml

@@ -0,0 +1,14 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: agent-api
+  labels:
+    app.kubernetes.io/name: agent-api
+spec:
+  type: ClusterIP
+  selector:
+    app.kubernetes.io/name: agent-api    # 必须和 Pod 的标签一致，否则 Service 没有后端
+  ports:
+    - name: http
+      port: 80
+      targetPort: http

topics/devops/k8s/examples/agent-api/test_manifests.py

@@ -0,0 +1,63 @@
+# requires: yaml
+"""对清单做团队规范检查（kubeconform 只校验结构，这里检查“写对了但不合规范”的问题）。
+
+运行：pytest -q test_manifests.py
+结构校验（可选）：kubeconform -strict -summary *.yaml
+"""
+from pathlib import Path
+
+import yaml
+
+HERE = Path(__file__).parent
+
+
+def load_all() -> list[dict]:
+    docs = []
+    for f in sorted(HERE.glob("*.yaml")):
+        docs += [d for d in yaml.safe_load_all(f.read_text(encoding="utf-8")) if d]
+    return docs
+
+
+DOCS = load_all()
+
+
+def by_kind(kind: str) -> list[dict]:
+    return [d for d in DOCS if d["kind"] == kind]
+
+
+def test_selector_matches_pod_labels():
+    for dep in by_kind("Deployment"):
+        sel = dep["spec"]["selector"]["matchLabels"]
+        labels = dep["spec"]["template"]["metadata"]["labels"]
+        assert sel.items() <= labels.items()
+        for svc in by_kind("Service"):
+            assert svc["spec"]["selector"].items() <= labels.items(), "Service 选择器和 Pod 标签不一致"
+
+
+def test_containers_follow_rules():
+    for dep in by_kind("Deployment"):
+        for c in dep["spec"]["template"]["spec"]["containers"]:
+            image = c["image"]
+            assert ":" in image.rsplit("/", 1)[-1] and not image.endswith(":latest"), "镜像必须固定版本"
+            assert "requests" in c["resources"] and "memory" in c["resources"].get("limits", {})
+            for probe in ("readinessProbe", "livenessProbe"):
+                assert probe in c, f"缺少 {probe}"
+            assert c["securityContext"]["allowPrivilegeEscalation"] is False
+            for e in c.get("env", []):
+                assert "value" not in e or "KEY" not in e["name"].upper(), "密钥不能明文写在清单中"
+
+
+def test_rolling_update_keeps_capacity():
+    for dep in by_kind("Deployment"):
+        ru = dep["spec"]["strategy"]["rollingUpdate"]
+        assert ru["maxUnavailable"] == 0
+
+
+def test_pdb_lower_than_min_replicas():
+    hpa_min = min(h["spec"]["minReplicas"] for h in by_kind("HorizontalPodAutoscaler"))
+    for pdb in by_kind("PodDisruptionBudget"):
+        assert pdb["spec"]["minAvailable"] < hpa_min, "PDB 要求的可用数不小于副本数会导致节点无法驱逐"
+
+
+def test_no_secret_objects_in_repo():
+    assert not by_kind("Secret"), "Secret 不应提交到仓库"

topics/devops/k8s/index.md

@@ -4,12 +4,37 @@ title: Kubernetes 基础
 type: index
 domain: devops
 stack: [k8s]
-tags: []
+tags: [Kubernetes, 部署, 探针, 滚动更新]
 week: [14]
 ---
 
 # Kubernetes 基础
 
-Pod、Deployment、Service、Ingress、配置与密钥、探针、滚动发布。
+能读懂、修改清单，能用 kubectl 排查；理解探针、滚动更新和优雅退出（AI 流式服务的关键）。BOSS直聘 2026-10-23 的调研中有岗位把 K8s 列为要求或加分项。
 
-> 本专题建设中：课程、企业场景、面试题和示例代码会陆续补充。
+## 学习路线
+
+| 顺序 | 课程 | 级别 | 预计 |
+| --- | --- | --- | --- |
+| 1 | [Kubernetes 基础：Pod / Deployment / Service / Ingress、配置与密钥、探针、滚动更新和扩缩容](01-core-objects.md) | 基础 | 3 小时 |
+
+## 企业场景
+
+- [AI Agent 服务上 K8s：发布时流式回答不中断、慢启动、密钥管理和按负载扩容](scenarios/agent-rollout.md)
+
+## 面试题
+
+- [Kubernetes 基础面试题](interview.md)
+
+## 示例代码
+
+- [examples/agent-api](examples/agent-api/)：Deployment / Service / Ingress / ConfigMap / HPA / PDB 清单（kubeconform 校验 6 个资源有效；规范测试 5 个通过；未在真实集群部署）
+
+## 在 16 周计划中
+
+- [第 14 周：后端扩展与部署](../../../plan/week14-backend-extend-deploy.md)
+
+## 官方资料
+
+- https://kubernetes.io/zh-cn/docs/home/
+- kubeconform：https://github.com/yannh/kubeconform

topics/devops/k8s/interview.md

@@ -0,0 +1,67 @@
+---
+id: devops.k8s.interview
+title: Kubernetes 基础面试题
+type: interview
+domain: devops
+stack: [k8s]
+tags: [Kubernetes, 探针, 滚动更新, 排查, 面试]
+level: basic
+related: [devops.k8s.core-objects]
+week: [14, 16]
+---
+
+# Kubernetes 基础面试题
+
+## 基础
+
+### 【基础】Pod、Deployment、Service 是什么关系？
+
+**参考答案**：Pod 运行容器；Deployment 管理一组相同的 Pod（副本数、滚动更新、回滚），通过 ReplicaSet 实现；Service 通过标签选择器找到这些 Pod，提供稳定的访问地址和负载均衡。
+
+**追问**：Pod 的 IP 能直接用吗？→ 不建议，Pod 重建后 IP 会变，应通过 Service 名访问。
+
+### 【基础】readinessProbe 和 livenessProbe 的区别？
+
+**参考答案**：就绪探针失败时 Pod 从 Service 端点中移除但不重启，用于“暂时不能处理请求”；存活探针失败时重启容器，用于“进程卡死”。慢启动应用再加 startupProbe。
+
+**追问**：存活探针为什么不能检查数据库？→ 数据库故障时所有 Pod 会被同时重启，问题不能解决反而扩大。
+
+### 【基础】ConfigMap 和 Secret 的区别？
+
+**参考答案**：都用于注入配置；Secret 用于敏感信息，有单独的权限控制，可以配置静态加密，但其 YAML 中的数据只是 base64 编码，不能提交到仓库。
+
+**追问**：生产环境密钥怎么管理？→ 使用外部密钥管理系统同步到集群，或平台提供的加密方案；做好轮换和访问审计。
+
+## 进阶
+
+### 【进阶】滚动更新如何做到不中断服务？
+
+**参考答案**：`maxUnavailable: 0` 保证可用数量；就绪探针确保新 Pod 准备好才接流量；旧 Pod 优雅退出：先摘除端点（preStop 等待），应用处理 SIGTERM 完成进行中的请求，宽限期足够长。
+
+**追问**：发布后发现问题怎么办？→ `kubectl rollout undo` 回滚到上个版本；更好的做法是灰度发布（金丝雀）观察指标后再全量。
+
+### 【进阶】Pod 一直 CrashLoopBackOff，怎么排查？
+
+**参考答案**：`kubectl describe pod` 看事件和退出码；`kubectl logs --previous` 看崩溃前日志；常见原因：配置或密钥缺失、启动命令错误、依赖连不上、存活探针过早失败、OOMKilled（退出码 137）。
+
+**追问**：镜像拉取失败显示什么状态？→ `ErrImagePull` / `ImagePullBackOff`，检查镜像名、标签和拉取凭证。
+
+### 【进阶】requests 和 limits 有什么区别？
+
+**参考答案**：requests 是调度依据（保证分配的资源），limits 是上限：超过内存上限会被 OOMKill，超过 CPU 上限会被限流。两者关系决定 QoS 等级。
+
+**追问**：CPU 一定要设 limits 吗？→ 有争议：设置后可能出现限流导致延迟抖动；很多团队只设 CPU requests 和内存 limits，按团队规范执行。
+
+## 场景题
+
+### 【场景题】AI 服务每次发布，用户的流式回答都会中断，怎么解决？
+
+**参考答案**：优雅退出：就绪探针在退出时立即失败、停止接新请求、等待流结束；preStop 留出摘除时间；宽限期大于最长回答时间；`maxUnavailable: 0`；Ingress 关闭缓冲。前端也可以实现断线提示和重试。详见 [Agent 上 K8s 场景](scenarios/agent-rollout.md)。
+
+**追问**：怎么验证改好了？→ 在测试环境持续发起长回答请求的同时执行滚动更新，统计中断数为 0。
+
+### 【场景题】HPA 配置了 CPU 70% 扩容，但高峰期 AI 服务很慢却没有扩容，为什么？
+
+**参考答案**：AI 服务大部分时间在等待模型响应（I/O），CPU 不高；应该用反映负载的指标：进行中请求数、队列长度、首 token 延迟，通过自定义指标扩容；同时检查是否被上游模型的限流卡住（扩容也没用）。
+
+**追问**：扩容太慢怎么办？→ 提高最小副本、缩短启动时间（镜像体积、预热）、根据可预期的高峰提前扩容。

topics/devops/k8s/scenarios/agent-rollout.md

@@ -0,0 +1,89 @@
+---
+id: devops.k8s.scenario.agent-rollout
+title: AI Agent 服务上 K8s：发布时流式回答不中断、慢启动、密钥管理和按负载扩容
+type: scenario
+domain: devops
+stack: [k8s, docker, nginx, cicd]
+tags: [滚动更新, 优雅退出, SSE, 探针, HPA, Secret, 回滚]
+level: intermediate
+prerequisites: [devops.k8s.core-objects, devops.docker.image-dockerfile]
+est_hours: 2.5
+related: [devops.k8s.interview, devops.cicd.release-rollback]
+week: [14]
+---
+
+# AI Agent 服务上 K8s：发布时流式回答不中断、慢启动、密钥管理和按负载扩容
+
+## 业务背景与问题
+
+Agent API 从虚拟机迁移到公司的 K8s 集群后：
+
+1. 每次发布，正在进行中的流式回答被切断，用户看到“网络错误”；
+2. 新版本启动需要预热（加载提示词模板、建立连接池），偶尔被重启循环；
+3. 有人把模型 API Key 直接写在 Deployment 的环境变量里提交到了仓库；
+4. 高峰期响应变慢，但 CPU 使用率并不高，HPA 没有扩容。
+
+## 约束
+
+- 集群由平台团队维护，应用团队只能修改自己的清单。
+- 回答可能持续 60 秒以上。
+
+## 方案设计
+
+1. **优雅退出**：
+   - 应用收到 SIGTERM 后：就绪检查立即返回失败、不再接受新请求、等待进行中的流结束（最长 80 秒）后退出；
+   - `preStop` 短暂等待，给 Ingress / Service 摘除端点的时间；
+   - `terminationGracePeriodSeconds: 90` 大于最长回答时间；
+   - 滚动更新 `maxUnavailable: 0`。
+2. **慢启动**：startupProbe 给足启动时间；就绪探针在预热完成后才返回成功。
+3. **密钥**：轮换已泄露的 Key；清单中只引用 Secret；Secret 由密钥管理系统同步（或平台提供的方案）；CI 中加密钥扫描。
+4. **扩容指标**：AI 服务主要在等待模型返回，CPU 低但并发连接数高。改用“每个 Pod 的进行中请求数”作为自定义指标（需要平台支持指标适配器），或者先按经验提高副本下限。
+5. **发布与回滚**：镜像固定版本；CI 中先 `kubeconform` + 规范测试；发布后观察错误率和首 token 延迟，异常时 `kubectl rollout undo`。
+
+## 关键代码
+
+FastAPI 应用的优雅退出（示意）：
+
+```python
+import asyncio, signal
+
+active_streams = 0
+shutting_down = False
+
+@app.get("/readyz")
+async def readyz():
+    if shutting_down:
+        raise HTTPException(503)                     # 让 K8s 尽快摘除这个 Pod
+    return {"ok": True}
+
+async def drain(timeout: float = 80):
+    global shutting_down
+    shutting_down = True
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout
+    while active_streams > 0 and loop.time() < deadline:
+        await asyncio.sleep(0.5)                     # 等待进行中的流式回答结束
+```
+
+（Uvicorn 自身也会在收到 SIGTERM 后停止接收新连接并等待请求完成，具体参数如 `--timeout-graceful-shutdown` 以官方文档为准。）
+
+完整清单：[examples/agent-api](../examples/agent-api/)。SSE 在 Nginx 层的配置见 [AI 网关场景](../../nginx/scenarios/ai-gateway-sse-canary.md)。
+
+## 取舍
+
+| 选择 | 优点 | 缺点 |
+| --- | --- | --- |
+| **优雅退出 + 长宽限期（本方案）** | 用户无感知 | 发布时间变长 |
+| 前端断线自动续传（从断点继续） | 对任何中断都有效 | 后端要保存生成进度，复杂 |
+| 发布时间放在低峰期 | 简单 | 治标不治本 |
+
+## 易错点
+
+- 宽限期比最长回答时间短，SIGKILL 依然切断。
+- 应用作为 shell 脚本的子进程启动，收不到 SIGTERM（使用 exec 形式的启动命令）。
+- 就绪探针在退出阶段仍然返回成功，新请求继续进来。
+- 以为 Secret 是加密的。
+
+## 面试怎么讲
+
+> “迁移到 K8s 后发布会切断流式回答。我做了优雅退出：收到 SIGTERM 后就绪探针立即失败，停止接新请求，等进行中的流结束；preStop 留出摘除端点的时间，宽限期设为 90 秒，大于最长回答；滚动更新不减少可用副本。慢启动用 startupProbe。泄露的 Key 立即轮换，清单只引用 Secret，CI 加密钥扫描。扩容方面，AI 服务 CPU 不高但并发高，改用进行中请求数作为指标。”