Hang Zhengyang
English ↗

mini-infra 指令说明手册

本文档解释本次学习过程中用到的核心命令：Docker/Compose、Kubernetes、Terraform、监控验证、常见排障。

1. 环境与版本检查

docker version

  • 作用：查看 Docker Client/Server 版本，确认 Docker Desktop 是否正常运行。

docker compose version

  • 作用：确认 Compose 子命令可用。

kubectl version --client

  • 作用：检查 kubectl 客户端是否安装成功。

kind version

  • 作用：检查 kind 是否安装成功。

terraform -version

  • 作用：检查 Terraform 版本。

helm version

  • 作用：检查 Helm 版本（可选组件）。

2. Docker / Compose 相关

docker build -t serving-lab-app-service:latest ./serving-lab/app-service

  • 作用：手动构建 app-service 镜像，并打上标签。
  • 使用场景：给 kind 加载本地镜像前，或者排查构建问题时。

docker compose up --build

  • 作用：构建并启动 serving-lab 全部服务（app/nginx/prometheus/grafana）。

docker compose up -d --build

  • 作用：后台启动全部服务，终端可继续输入其它命令。

docker compose ps

  • 作用：查看 compose 管理的容器状态（Up/Exited/端口映射）。

docker compose logs app-service

  • 作用：查看 app-service 启动日志。
  • 典型用途：定位 ModuleNotFoundError、依赖缺失、启动失败。

docker compose -f docker-compose.yml config

  • 作用：检查 compose 文件是否能被正确解析（语法+合并后的最终配置）。

3. HTTP 验证命令（curl）

curl http://localhost:8080/health

  • 作用：检查服务健康状态，预期返回 ok。

curl http://localhost:8080/metrics 或 curl http://localhost:8080/metrics/

  • 作用：查看 Prometheus 文本指标。
  • 说明：/metrics 可能被重定向到 /metrics/（307），正常。

curl -X POST http://localhost:8080/api/chat -H "Content-Type: application/json" -d '{"question":"...","model":"mock-1"}'

  • 作用：验证聊天接口主流程（orchestrator + retriever + llm_adapter + sqlite 写入）是否正常。

4. Kubernetes（kind + kubectl）

kind create cluster --name serving-lab

  • 作用：创建本地 Kubernetes 集群。

kubectl cluster-info

  • 作用：查看当前集群控制面地址，确认 context 正确。

kubectl get nodes

  • 作用：查看节点状态（初期 NotReady 短暂出现是正常现象）。

kubectl apply -f <file>

  • 作用：应用单个 YAML 资源到集群。
  • 你用到的主要文件：
    • k8s/nginx-configmap.yaml
    • k8s/app-deployment.yaml
    • k8s/app-service.yaml
    • k8s/nginx-deployment.yaml
    • k8s/nginx-service.yaml
    • k8s/ingress.yaml

kubectl get pods

  • 作用：查看 Pod 状态（Running / ImagePullBackOff / CrashLoopBackOff 等）。

kubectl get svc

  • 作用：查看 Service 暴露端口和集群 IP。

kubectl get ingress

  • 作用：查看 Ingress 规则是否创建成功。

kubectl get pods -A

  • 作用：查看所有命名空间 Pod（排查系统组件和业务组件时常用）。

kubectl describe node serving-lab-control-plane

  • 作用：查看节点资源、条件、事件，排查节点级问题。

kubectl logs deploy/app-service

  • 作用：查看 deployment 下容器日志。

kubectl get pods -w

  • 作用：持续观察 Pod 状态变化（滚动更新、恢复过程很有用）。

kind load docker-image serving-lab-app-service:latest --name serving-lab

  • 作用：把本地 Docker 镜像导入 kind 节点。
  • 使用场景：解决 ImagePullBackOff（本地镜像没在 kind 节点内）。

kubectl port-forward svc/edge-proxy 8081:80

  • 作用：把集群内服务临时转发到本地端口，便于调试。
  • 注意：该命令需要前台持续运行，按 Ctrl+C 会中断转发。

5. Terraform 闭环命令

在目录 terraform/ 下执行。

terraform init

  • 作用：初始化 provider、下载依赖、创建本地工作目录。

terraform fmt

  • 作用：格式化 Terraform 文件。

terraform validate

  • 作用：校验 Terraform 语法与配置合法性。

terraform plan -out tfplan

  • 作用：生成执行计划并保存为文件（可审阅后再 apply）。

terraform apply tfplan

  • 作用：按已保存计划执行资源创建/变更。

terraform output

  • 作用：查看 outputs 输出值（如 generated_file_path）。

terraform destroy -auto-approve

  • 作用：销毁资源，完成学习闭环并避免资源遗留。

cd terraform-k8s && terraform plan -var-file=dev.tfvars -out tfplan

  • 作用：使用统一部署栈（K8s + Helm）生成计划。
  • 说明：这是“工业化路径”，会管理 app/nginx/ingress/prometheus/grafana。

cd terraform-k8s && terraform apply tfplan

  • 作用：执行统一部署计划，在集群内创建资源。

cd terraform-k8s && terraform destroy -var-file=dev.tfvars -auto-approve

  • 作用：回收统一部署栈创建的资源。

6. 监控页面访问

http://localhost:9090

  • Prometheus UI：查看 target、执行 PromQL 查询。

http://localhost:3001

  • Grafana UI：查看 dashboard。
  • 默认登录：admin/admin（首次会提示修改密码）。

7. 本次常见问题与对应命令

问题 A：Nginx 502（Host is unreachable）

  • 含义：网关能收到请求，但上游 app-service 不可达。
  • 排查命令：
    • docker compose ps
    • docker compose logs app-service

问题 B：K8s ImagePullBackOff

  • 含义：集群拉不到镜像。
  • 修复命令：
    • docker build -t serving-lab-app-service:latest ./serving-lab/app-service
    • kind load docker-image serving-lab-app-service:latest --name serving-lab
    • kubectl apply -f k8s/app-deployment.yaml

问题 C：curl localhost:8081 连接失败

  • 常见原因：kubectl port-forward 已被 Ctrl+C 终止。
  • 处理：重新执行 kubectl port-forward svc/edge-proxy 8081:80 并保持终端运行。

8. 推荐执行顺序（复习版）

  1. 启动本地 compose 栈并验证 /health、/api/chat、/metrics
  2. 创建 kind 集群并 apply k8s 清单
  3. 通过 kind load docker-image 处理本地镜像问题
  4. 使用 port-forward 验证 K8s 内服务
  5. 跑 Terraform 的 init -> plan -> apply -> output -> destroy

9. 清理与回收指令（停止全部运行并删除）

下面这组命令用于“收工清理”，确保运行中的内容都停掉，并删除测试资源。

9.1 停止本地 Compose 服务

cd /Users/hang/github_repo/mini-infra/serving-lab
docker compose down

说明：

  • 停止并删除 compose 创建的容器和网络。
  • 若要连同卷一起删除（会清空 sqlite / grafana 本地数据）：
docker compose down -v

9.2 停止 kubectl port-forward

如果 port-forward 正在前台运行，直接在对应终端按：

Ctrl + C

如果你不确定是否还有后台进程，可执行：

pkill -f "kubectl port-forward svc/edge-proxy 8081:80"

9.3 删除 Kubernetes 业务资源

cd /Users/hang/github_repo/mini-infra
kubectl delete -f k8s/ingress.yaml --ignore-not-found
kubectl delete -f k8s/nginx-service.yaml --ignore-not-found
kubectl delete -f k8s/nginx-deployment.yaml --ignore-not-found
kubectl delete -f k8s/app-service.yaml --ignore-not-found
kubectl delete -f k8s/app-deployment.yaml --ignore-not-found
kubectl delete -f k8s/nginx-configmap.yaml --ignore-not-found

9.4 删除 kind 集群

kind delete cluster --name serving-lab

9.5 回收 Terraform 资源

cd /Users/hang/github_repo/mini-infra/terraform
terraform destroy -auto-approve

如果你使用的是统一部署栈（terraform-k8s）：

cd /Users/hang/github_repo/mini-infra/terraform-k8s
terraform destroy -var-file=dev.tfvars -auto-approve

9.6 可选：清理本地镜像与卷（谨慎）

删除项目镜像：

docker image rm serving-lab-app-service:latest

删除无主镜像和无用资源（谨慎执行）：

docker system prune -f

如果还想额外删除无主卷（会影响其它项目，谨慎）：

docker volume prune -f