简单 App 现状说明（模块化单体 + 统一入口）

本文档仅描述当前仓库“已经落地”的状态，不再包含路线图或阶段计划。

1) 当前系统形态

项目是模块化单体应用，核心业务运行在一个 app-service 中，当前使用 mock LLM。

主要能力：

• Chat API（/api/chat）
• 健康检查（/health）
• 指标暴露（/metrics/）
• 内置前端页面（/）
• PostgreSQL 持久化（会话/消息/生成日志）

2) 代码结构（现状）

mini-infra/
  serving-lab/
    app-service/
      app.py
      orchestrator.py
      retriever.py
      llm_adapter.py
      repository.py
      frontend/
        index.html
        styles.css
        app.js
    nginx/
      default.conf
    docker-compose.yml
    observability/
      prometheus/prometheus.yml
      grafana/...
  k8s/
    *.yaml
  terraform/
    *.tf
  terraform-k8s/
    *.tf

模块职责：

• api（app.py）：HTTP 路由和请求入口
• orchestrator：编排问答主流程
• retriever：上下文检索（规则型）
• llm_adapter：模型调用抽象（当前 mock）
• repository：PostgreSQL 读写

3) 部署入口（现状）

当前仓库存在两种使用方式：

A. 开发/本地联调入口

• 使用 serving-lab/docker-compose.yml
• 启动：docker compose up --build

B. 统一部署入口（主线）

• 使用 terraform-k8s/
• 管理 K8s 资源 + Helm 组件（ingress-nginx, kube-prometheus-stack）
• 标准流程：
  1. 构建镜像
  2. kind load 到本地集群
  3. terraform apply

说明：

• k8s/ 与 terraform/ 保留为学习参考与对照样例
• 日常统一部署建议使用 terraform-k8s/

4) 运行组件（现状）

应用与网关：

• app-service（FastAPI）
• edge-proxy（Nginx）

可观测性：

• Prometheus
• Grafana（含预置 dashboard/alert 规则）

数据：

• PostgreSQL

5) Kubernetes 运行配置（现状）

app-service Deployment 已包含：

• readinessProbe（/health）
• livenessProbe（/health）
• resources.requests/limits

并包含：

• ConfigMap（Nginx 配置）
• Service（app + edge-proxy）
• Ingress（host: serving-lab.local）

6) Terraform 运行配置（现状）

terraform-k8s 已实现：

• kubernetes provider 管理 app/nginx/ingress
• helm provider 管理 ingress-nginx 与 kube-prometheus-stack
• dev/prod 环境变量化（镜像、上下文、namespace、host、密码等）

terraform/ 目录仍保留：

• 本地 local_file 练习闭环（init/plan/apply/destroy）

7) 当前已知边界

• app-service 仍使用 mock LLM，不是实际推理 runtime
• 本地 kind 环境依赖 kind load docker-image
• 生产级 CI/CD 与镜像仓库发布流程尚未接入

8) 快速验证（现状）

本地联调：

• http://localhost:8080/（前端）
• http://localhost:8080/api/status
• http://localhost:8080/health
• http://localhost:8080/metrics/
• http://localhost:9090（Prometheus）
• http://localhost:3001（Grafana）

统一部署验证：

• kubectl get pods -A
• kubectl get svc -A
• kubectl get ingress -A