Files

T

bot_dev2 22106526d9 Merge PR #121 (feat #91 用户手册/部署手册编写)

2026-08-05 08:20:54 +08:00

6.9 KiB

Raw Permalink Blame History

iAOP 部署手册（Deployment Guide）

对应 issue #91「[M5] 用户手册/部署手册编写」，父 Issue #15（EPIC 跟踪），里程碑 iAOP v1.0 · Template-Ti 一期。配套 PRD §5.6「⑥ 部署底座」与 deploy/k8s/helm/iaop/。本手册面向 运维/交付工程师（bot_dev、现场运维）。业务最终用户的日常使用请见《用户手册》。

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 后端）

# 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 后端

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 开启域名入口（可选）

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 覆盖，例如：

helm upgrade iaop deploy/k8s/helm/iaop -n iaop \
  -f deploy/k8s/helm/iaop/values.prod.yaml

5. 健康巡检（可用性 ≥ 99.8%）

部署底座提供可用性探针（EPIC #8 子任务 #61）：

# 轮询 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 灰度：

# 1) Chart 纳入 Git 仓库，ArgoCD Application 指向该仓库
# 2) 升级 = 改 values 并提交，ArgoCD 自动同步 + 滚动

6.2 Helm 回滚

helm history iaop -n iaop          # 查看修订历史
helm rollback iaop <REVISION> -n iaop   # 回滚到上一版本

模板资产包发布同样走「校验 → 灰度 → 回滚点」流程（PRD §5.7 模板配置台），配置台支持版本 diff 与一键回滚。

7. 升级流程

预演：在 dev 命名空间用 values.dev.yaml 部署，跑通探针与冒烟用例；
生产灰度：helm upgrade，观察 rollout status 与探针可用率；
质保观察：上线后进入 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。

6.9 KiB Raw Permalink Blame History Unescape Escape