基于微服务架构的服务治理 —— 大模型对话助手

「分布式计算环境」课程大作业项目：基于 Spring Cloud Alibaba 构建大模型对话助手微服务系统，演示限流、熔断、降级、灰度流量分隔四项服务治理能力带来的稳定性收益。

✅ 项目已完成：六模块 Maven 工程 clean verify 通过，三组对比实验（限流 / 熔断降级 / 90-10 灰度）均以三轮或双执行者独立复跑数据收口。完整报告见 report/report.md，实验结论速览见下表。

治理能力演示速览

每组能力都可在本机按 assets/demo-runbook.md 现场复跑（完整复现说明与坑位处理见 assets/t4.6-demo-runbook.md）；下表给出核心量化结论与已归档的运行态证据。

治理能力	核心结论（vs 无治理）	运行态证据	完整数据
入口限流（gateway QPS=10）	接纳吞吐钉在 9.3—9.7 RPS；响应 P95 中位 720ms → 151ms	Sentinel 通过/拒绝 QPS	`assets/exp1-rate-limiting.csv`
熔断 + 降级（慢调用/异常比例）	慢依赖故障段传输可用率 100% 全兜底（baseline 排队至 1.5s+）；故障清除后 ~17s 自动恢复	错误段运行态、恢复段运行态	`assets/exp2-circuit-degrade.csv`
线程占用传播隔离（B6）	慢依赖把 chat 线程池打满 50、健康探针 P95 恶化 34.4 倍；治理后 busy ≤3、探针 42/42 成功	B6 复跑记录	`assets/raw/m5-exp-20260828/b6y-*`
90/10 灰度流量分隔	v2 实例 100% 故障时 v1 流量成功率 100%（两组独立复跑 174/174、175/175）	Nacos v1/v2 版本元数据	`assets/exp3-traffic-split.csv`、C 组复跑

口径说明：降级响应按”传输可用”计入、与完整业务成功分开统计；429 为受控拒绝。详见报告 §7.1 指标定义。

仓库导航

目录	内容
`report/`	课程报告（分析 + 设计 + 实验验证）
`survey/`	文献与案例调研（同行评审证据分层综述 + 企业实践分析）
`design/`	系统设计（架构、治理方案、对比实验设计）
`code/`	微服务工程源码（Nacos compose + Windows 一键启停/自检脚本）
`assets/`	实验数据、运行态截图与演示 runbook（证据索引见 `assets/m5-evidence-inventory-20260829.md`）

快速开始

环境依赖（第一项最容易踩坑，Docker Desktop 未装/未启动时 Nacos 起不来）：

Docker Desktop for Windows（跑 Nacos 容器）
JDK 17+（编译目标锁定 17，见 design/tech-stack.md）
Maven 3.9+
PowerShell 5+（启停脚本）

一键启停（推荐）：

# 启动全套：默认 baseline（Feign Sentinel/fallback 关闭）
powershell -ExecutionPolicy Bypass -File tools/up.ps1 -Mode baseline
# 治理实验改用 governed；切换模式前须先 tools/down.ps1 停净旧 chat
powershell -ExecutionPolicy Bypass -File tools/up.ps1 -Mode governed
# 停净（反向）：powershell -ExecutionPolicy Bypass -File tools/down.ps1

baseline 与 governed 会在 chat 启动日志打印并校验；模式与 feign.sentinel.enabled 不一致时拒绝启动，防止实验组混淆。

手动逐步：

# 1. Nacos（docker-compose，仅中间件进容器；微服务本机 mvn spring-boot:run）
docker compose -f code/docker-compose.yml up -d
powershell -ExecutionPolicy Bypass -File tools/nacos-init.ps1   # 首次必跑，见下方实测说明

# 2. Sentinel Dashboard（本机 jar，不进 compose——官方无镜像，且 Dashboard 需回调各服务 transport 端口）
powershell -ExecutionPolicy Bypass -File tools/get-dashboard.ps1   # 首次下载 1.8.9 jar
# 注意 -Dcsp.sentinel.api.port：Dashboard 内嵌客户端默认占 8719，与 gateway 的 transport 冲突（实测，tech-stack §3）
java -Dcsp.sentinel.api.port=8730 -jar tools/sentinel-dashboard-1.8.9.jar --server.port=8858

# 3. 四服务（llm-provider 双实例）
mvn -f code/pom.xml -DskipTests install
mvn -f code/user/pom.xml spring-boot:run
mvn -f code/llm-provider/pom.xml spring-boot:run                          # 8102
mvn -f code/llm-provider/pom.xml spring-boot:run -Dspring-boot.run.arguments=--server.port=8103
mvn -f code/chat/pom.xml spring-boot:run
mvn -f code/gateway/pom.xml spring-boot:run

控制台地址与账号（Nacos 行为按 nacos/nacos-server:v3.0.3 镜像实测，2026-08-21）：

控制台	地址	账号	实测要点
Nacos	http://localhost:8081	nacos / nacos123	① 3.x 控制台是独立端口 8080（宿主机映射 8081）且路径无 `/nacos` 前缀；② 无默认密码，首次启动须初始化（`tools/nacos-init.ps1`，幂等）；③ 镜像强制鉴权：不设 `NACOS_AUTH_TOKEN` 容器直接退出——compose 已内置；④ derby 内嵌存储未挂卷，`docker compose down` 重建容器后需重跑 init 脚本
Sentinel Dashboard	http://localhost:8858	sentinel / sentinel	与客户端 1.8.9 同版本，避免协议不匹配；本机 `java -jar` 运行

技术栈

JDK 17 · Spring Boot 3.5.0 · Spring Cloud 2025.0.0 · Spring Cloud Alibaba 2025.0.0.0 · Nacos 3.0.3 · Sentinel 1.8.9

M1：全链路 API 速查（`tools/up.ps1` 启动后可用）

请求	说明
`curl -X POST localhost:8080/api/chat -d '{"userId":"u1","message":"hi"}' -H "Content-Type: application/json"`	主链路（gateway→chat→llm-provider+user）；响应含 `reply/degraded/backend/instanceId/costMs/user/reqId`，响应头回写 `X-Request-Id`
`curl localhost:8080/api/profile/u1`	健康对照路径（仅调 user；B6 雪崩实验探针）
`curl -X POST localhost:8102/admin/fault -d '{"delayMs":2000}' -H "Content-Type: application/json"`	mock 故障注入（每实例独立，8102/8103 要各打一遍；`errorRate∈[0,1]`；`timeoutMs>0` 优先于 `delayMs`）
`curl localhost:8102/admin/fault`	查回当前注入参数（清零 = POST `{}`）

契约细节（JSON 形状、访客降级口径）见 design/architecture.md §4「接口契约细化」。

自检（PR 合并前必跑，任一断言 FAIL 退出码 1）：

powershell -ExecutionPolicy Bypass -File tools/smoke.ps1 -Stage M3
# 断言：主链路字段齐 / 双实例轮换 / profile 正常 / reqId 贯穿三段日志 / delay 注入变慢清零恢复 / transport 端口无冲突
# M3 另断言：规则热切换 / gateway + provider 429 / chat 熔断降级；结束后自动清零 fault 和规则

完整的 M1 验收命令、测试计数、requestId 日志与重启恢复证据见 assets/m1-validation.md。

user 停机、访客降级与自动重启也可由脚本一次完成；M2 下重启会同时恢复 user 的 Sentinel transport 8723：

powershell -ExecutionPolicy Bypass -File tools/restart-recovery.ps1 -ConfirmRestart

M2：Sentinel 治理接入

五个进程分别使用 Sentinel transport 端口 8719-8723，并统一连接 localhost:8858。运行态配置可从每个进程的 /actuator/sentinel 核对；冻结后的资源名和 baseline/governed 对照结果见 assets/m2-validation.md。

M2 已接好 starter、fallback、gateway 429 回调和状态观察器；M3 在 gateway/chat/llm-provider 接通 Nacos datasource，规则启动加载、热更新和重启恢复均以 Nacos 为唯一来源。

Sentinel 规则集下发（M3 已接通 datasource；规则只在 Nacos 改，Dashboard 只看不动）：

powershell -ExecutionPolicy Bypass -File tools/rules.ps1 -Get                 # 回读三份 dataId
powershell -ExecutionPolicy Bypass -File tools/rules.ps1 -Set all-off         # 三份全 []（实验二 baseline）
powershell -ExecutionPolicy Bypass -File tools/rules.ps1 -Set exp1-rate-on    # 仅 gateway 限流（实验一）
powershell -ExecutionPolicy Bypass -File tools/rules.ps1 -Set exp2-cb-on      # chat 熔断规则（资源名已由 M2 T2.2 实测冻结）
powershell -ExecutionPolicy Bypass -File tools/rules.ps1 -Set provider-rate-on # 仅 provider 二级限流 smoke，不混入主实验

完整 G1（T3.2-T3.5）走查使用 PowerShell 5.1/7 兼容的 runspace 并发脚本。它会验证空/有规则无需重启即可切换、两个限流层的 429、B1-B4 及熔断状态日志，并在 finally 清理双实例故障与三份规则：

powershell -ExecutionPolicy Bypass -File tools/m3-acceptance.ps1 -Scope Full

本轮实际的限流计数、B1-B4 时延、状态转换、错误 dataId 与重启恢复证据见 assets/m3-validation.md。

reqId 贯穿演示：任一请求的 X-Request-Id 响应头即 reqId，可一行 grep 串起 gateway/chat/llm-provider 三段日志：

Select-String -Path code\*\logs\*.log -Pattern '<reqId>'

验收清单第 4 条手工演示（user 挂掉不拖垮 chat，重启自动恢复）：

# 1. 停 user（按端口杀进程树）
Get-NetTCPConnection -LocalPort 8104 -State Listen | ForEach-Object { taskkill /PID $_.OwningProcess /T /F }
# 2. chat 主链路仍 200，user 字段变为访客身份（source=guest，无 5xx）
curl -X POST localhost:8080/api/chat -d '{"userId":"u1","message":"hi"}' -H "Content-Type: application/json"
# 3. 重启 user（Nacos 心跳超时摘除旧实例约 10-20s，之后 chat 自动恢复真实身份）
mvn -f code/user/pom.xml spring-boot:run
# 4. 稍候 source 恢复 user；用 tools/down.ps1 + up.ps1 全量重启更省事