feat(#91): [M5] 用户手册/部署手册编写（业务用户三类场景+Helm部署/后端切换/巡检/灰度回滚+一致性核对脚本）
This commit is contained in:
+178
@@ -0,0 +1,178 @@
|
||||
# iAOP 部署手册（Deployment Guide）
|
||||
|
||||
> 对应 issue #91「[M5] 用户手册/部署手册编写」，父 Issue #15（EPIC 跟踪），里程碑 iAOP v1.0 · Template-Ti 一期。
|
||||
> 配套 PRD §5.6「⑥ 部署底座」与 `deploy/k8s/helm/iaop/`。本手册面向 **运维/交付工程师（bot_dev、现场运维）**。
|
||||
> 业务最终用户的日常使用请见《[用户手册](./用户手册.md)》。
|
||||
|
||||
## 1. 部署目标与边界
|
||||
|
||||
iAOP 采用「内核 + 行业模板」分层架构，部署目标：
|
||||
|
||||
- **内核（iAOP-Core）**：6 大模块（采集总线 / 模型框架 / LLM 网关 / 配置化驾驶舱 / 部署底座 / 模板配置台）一次部署，多行业复用；
|
||||
- **行业模板（iAOP-Template）**：作为「模板资产包」随内核发布，切换行业仅改配置不改码。
|
||||
|
||||
**验收口径（PRD §5.6 / §10）**：内核 + 模板一键 Helm 部署；昇腾后端切换仅需适配层，不改业务代码；可用性 ≥ 99.8%。
|
||||
|
||||
**本手册覆盖范围**：生产 / 验收环境部署、推理后端切换、健康巡检、灰度与回滚。
|
||||
**不覆盖**：商务定价、第三方 License 采购、单厂实施方案（由交付阶段单独产出）。
|
||||
|
||||
## 2. 环境要求（前置条件）
|
||||
|
||||
### 2.1 软件依赖
|
||||
|
||||
| 组件 | 版本 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| Kubernetes | ≥ 1.26 | 生产集群（建议 3 控制面 + N 工作节点） |
|
||||
| Helm | ≥ 3.12 | 一键部署工具 |
|
||||
| kubectl | 与集群匹配 | 集群操作 |
|
||||
| ArgoCD（可选） | ≥ 2.7 | GitOps 灰度发布 |
|
||||
| Python | ≥ 3.10 | 探针 / 离线校验脚本运行时 |
|
||||
| 容器运行时 | containerd ≥ 1.7 | 集群默认即可 |
|
||||
|
||||
### 2.2 推理后端硬件（二选一，PRD §5.6）
|
||||
|
||||
| 后端 (`inference.backend`) | 设备 (`inference.device`) | 运行时 | 驱动要求 |
|
||||
| --- | --- | --- | --- |
|
||||
| `gpu` | `nvidia-5090` | vllm / triton | NVIDIA Driver + nvidia-container-toolkit |
|
||||
| `npu` | `ascend-910b` / `ascend-310p` | mindie / onnx-ascend | CANN 工具链（见 `inference.cannVersion`） |
|
||||
|
||||
> 切换后端 = 改 `values.yaml` 的 `inference.backend` / `inference.device`，业务代码零改动（差异收敛在 `core/inference-backend/` 适配层）。
|
||||
|
||||
### 2.3 资源配额基线（默认 values，可调）
|
||||
|
||||
| 资源 | requests | limits |
|
||||
| --- | --- | --- |
|
||||
| CPU | 2 core | 8 core |
|
||||
| 内存 | 8 Gi | 32 Gi |
|
||||
| 模型权重存储 | 100 Gi（PVC） | — |
|
||||
|
||||
> 生产环境建议启用 HPA（`autoscaling.enabled: true`，min 2 / max 8，CPU 70%）。
|
||||
|
||||
## 3. 一键部署（Quick Start）
|
||||
|
||||
### 3.1 部署内核 + 模板（默认 GPU 后端）
|
||||
|
||||
```bash
|
||||
# 1) 命名空间（一次性）
|
||||
kubectl create namespace iaop
|
||||
|
||||
# 2) Helm 一键部署（Chart 在仓库 deploy/k8s/helm/iaop/）
|
||||
helm install iaop deploy/k8s/helm/iaop \
|
||||
-n iaop \
|
||||
--set inference.backend=gpu \
|
||||
--set inference.device=nvidia-5090
|
||||
|
||||
# 3) 验证
|
||||
kubectl -n iaop rollout status deployment/iaop-inference
|
||||
kubectl -n iaop get svc iaop-inference # ClusterIP :8000
|
||||
```
|
||||
|
||||
部署成功标志：Deployment 就绪、`/health` 返回 200（见 §5 健康巡检）。
|
||||
|
||||
### 3.2 切换为华为昇腾 NPU 后端
|
||||
|
||||
```bash
|
||||
helm upgrade iaop deploy/k8s/helm/iaop -n iaop \
|
||||
--set inference.backend=npu \
|
||||
--set inference.device=ascend-910b \
|
||||
--set inference.cannVersion=8.0
|
||||
```
|
||||
|
||||
切换行为（模板自动处理，无需手工干预）：
|
||||
|
||||
- `backend-configmap.yaml` 渲染对应后端适配层配置（npu 追加 `cann_version`）；
|
||||
- `deployment.yaml` 的 nodeSelector 自动切到 `ascend.com/npu=true`（GPU 为 `nvidia.com/gpu=true`）；
|
||||
- Pod 标签标注 `iaop.ai/inference-backend`，便于灰度与监控分流。
|
||||
|
||||
### 3.3 开启域名入口（可选）
|
||||
|
||||
```bash
|
||||
helm upgrade iaop deploy/k8s/helm/iaop -n iaop \
|
||||
--set ingress.enabled=true \
|
||||
--set ingress.host=iaop.example.com \
|
||||
--set ingress.className=nginx
|
||||
```
|
||||
|
||||
## 4. 配置点速查（values.yaml）
|
||||
|
||||
完整配置见 `deploy/k8s/helm/iaop/values.yaml`，常用项：
|
||||
|
||||
| 配置点 | values 路径 | 默认 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| 推理后端 | `inference.backend` | `gpu` | `gpu` / `npu` |
|
||||
| 模型名 | `inference.model` | `iaop-ti-cl4-v1` | 随模板切换 |
|
||||
| 副本数 | `replicaCount` | `2` | 生产 ≥ 2 |
|
||||
| 滚动策略 | `rollingUpdate` | `maxUnavailable:0, maxSurge:1` | 灰度发布策略 |
|
||||
| HPA | `autoscaling.enabled` | `false` | 生产建议 `true` |
|
||||
| 资源配额 | `resources.requests/limits` | 见 §2.3 | CPU/内存 |
|
||||
| 存储 | `storage.size` | `100Gi` | 模型权重持久卷 |
|
||||
| 域名 | `ingress.host` | — | 可选 |
|
||||
|
||||
**多环境分离**：用 `values.dev.yaml` / `values.prod.yaml` 覆盖，例如：
|
||||
|
||||
```bash
|
||||
helm upgrade iaop deploy/k8s/helm/iaop -n iaop \
|
||||
-f deploy/k8s/helm/iaop/values.prod.yaml
|
||||
```
|
||||
|
||||
## 5. 健康巡检（可用性 ≥ 99.8%）
|
||||
|
||||
部署底座提供可用性探针（EPIC #8 子任务 #61）：
|
||||
|
||||
```bash
|
||||
# 轮询 60 轮（每 1s），目标可用率 99.8%
|
||||
python deploy/k8s/healthz/probe_availability.py \
|
||||
--endpoints http://<iaop-inference>:8000 \
|
||||
--rounds 60 --interval 1 --target 0.998
|
||||
```
|
||||
|
||||
- 退出码 `0` = 达标（PASS）；`1` = 低于目标（FAIL）；
|
||||
- 建议以 K8s CronJob 定时执行，FAIL 时触发告警（接 Prometheus / 企业微信）。
|
||||
|
||||
## 6. 灰度发布与回滚
|
||||
|
||||
### 6.1 ArgoCD 灰度（推荐）
|
||||
|
||||
Chart 已内置滚动策略（`maxUnavailable: 0, maxSurge: 1`），配合 ArgoCD 可实现 GitOps 灰度：
|
||||
|
||||
```bash
|
||||
# 1) Chart 纳入 Git 仓库，ArgoCD Application 指向该仓库
|
||||
# 2) 升级 = 改 values 并提交，ArgoCD 自动同步 + 滚动
|
||||
```
|
||||
|
||||
### 6.2 Helm 回滚
|
||||
|
||||
```bash
|
||||
helm history iaop -n iaop # 查看修订历史
|
||||
helm rollback iaop <REVISION> -n iaop # 回滚到上一版本
|
||||
```
|
||||
|
||||
> 模板资产包发布同样走「校验 → 灰度 → 回滚点」流程（PRD §5.7 模板配置台），配置台支持版本 diff 与一键回滚。
|
||||
|
||||
## 7. 升级流程
|
||||
|
||||
1. **预演**：在 dev 命名空间用 `values.dev.yaml` 部署，跑通探针与冒烟用例；
|
||||
2. **生产灰度**：`helm upgrade`，观察 `rollout status` 与探针可用率；
|
||||
3. **质保观察**：上线后进入 1 个月质保观察期（PRD §7.7），监控 NFR 指标（可用性 ≥ 99.8% / P99 ≤ 1.8s）。
|
||||
|
||||
## 8. 故障排查（SOP）
|
||||
|
||||
| 现象 | 排查步骤 |
|
||||
| --- | --- |
|
||||
| Deployment 不就绪 | `kubectl describe pod` 看 nodeSelector / 镜像 / 资源；GPU/NPU 驱动是否就绪 |
|
||||
| `/health` 不通 | `kubectl logs`；确认推理后端适配层加载（`core/inference-backend/`） |
|
||||
| 可用率 < 99.8% | 看探针 FAIL 轮次分布；HPA 是否触发；节点资源是否打满 |
|
||||
| 推理慢 | 确认 `inference.runtime` 与硬件匹配；检查 `maxTokens/temperature` |
|
||||
|
||||
## 9. 交付物清单（对应 PRD §7.7）
|
||||
|
||||
部署阶段交付：
|
||||
|
||||
- [ ] 内核 + 模板 Helm 一键部署通过（GPU / NPU 各验一次）；
|
||||
- [ ] 可用性探针连续达标（≥ 99.8%）；
|
||||
- [ ] 灰度 + 回滚演练通过；
|
||||
- [ ] 故障排查 SOP（本文 §8）就绪。
|
||||
|
||||
---
|
||||
|
||||
**维护**：本文档随部署底座（`deploy/`）演进，版本与 Chart `appVersion` 对齐。模板资产打包发布见 `templates/<行业>/version.yaml`。
|
||||
Reference in New Issue
Block a user