# aiproject **Repository Path**: ChangPaoZhe/aiproject ## Basic Information - **Project Name**: aiproject - **Description**: 用于一键拉起AI服务完成限流和开发等工作 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-28 - **Last Updated**: 2026-11-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Kubernetes 智能运维助手 > **一句话用途**:把「查集群」从背命令变成说人话——用自然语言提问,Agent 自动调用 MCP 工具拉取真实集群数据,只依据工具返回值给出可核对的运维结论。 面向 Kubernetes 的对话式运维(ChatOps)平台:以 **LangGraph Agent** 为编排内核,以 **MCP(Model Context Protocol)** 为工具接入标准,实现「自然语言 → 结构化工具调用 → 事实性运维结论」的闭环。 **三类刚需,一个入口:** | 刚需 | 过去怎么做 | 用本系统怎么做 | |---|---|---| | 快速查现状 | 背 `kubectl get / describe / logs / top`,复制命名空间与 Pod 名 | 一句话提问,Agent 自行选工具、补参数、回填结果 | | 定位故障 | 逐条打命令、翻错误关键字、拼资源用量 | 自动检索错误日志、requests/limits 与实时用量并归纳 | | 结论可追溯 | 人工整理贴到工单,容易漏项或写错 | 固定字段结构化输出,可写入文件归档(`write` 作用域) | 系统采用**控制面 / 工具面分离**的双服务架构:控制面负责身份认证、会话管理与 Agent 编排;工具面负责工具注册、作用域鉴权与 Kubernetes 操作执行。JWT 作用域(`read` / `write` / `admin`)在两侧双重校验,会话状态外置至 PostgreSQL,网关保持无状态,可水平扩展。 --- ## 1. 用途与定位 ### 1.1 它解决什么问题 Kubernetes 日常运维的摩擦成本,主要不在"操作"本身,而在"信息获取": - **命令门槛**:`get pods` / `describe` / `logs --tail` / `top` 组合繁多,命名空间与 Pod 名靠记忆和复制粘贴。 - **信息分散**:状态、镜像、重启次数、错误日志、资源申请与实测用量散落在多个命令与多个系统里。 - **结论不可信**:通用大模型能说出一堆"看着对"的 K8s 建议,但事实可能是编的,运维场景下不可接受。 本系统的用途,就是把这三件事收敛成一条链路:**用自然语言提问 → Agent 规划并调用工具 → 只依据工具返回值作答**。 ### 1.2 核心用途(按场景) | # | 用途 | 典型提问 | 系统实际动作 | 产出 | |---|---|---|---|---| | 1 | **集群巡检** | "集群里有哪些命名空间?`llm-d-qwen` 下有哪些 Pod?" | `get_namesapce` → `get_pod_info` | 命名空间清单;Pod 名称、状态、Node、Pod IP、镜像、重启次数、标签 | | 2 | **故障定位** | "`nginx-deployment-79fccd6848-nhd76` 一直在重启,帮我看日志" | `get_pod_log`(ERROR / Exception / OOM / timeout 等关键字过滤,尾行 1–10) | 错误日志归纳:出现次数、关键字、上下文 | | 3 | **资源与容量分析** | "查下 `llm-d-qwen` 里 `qwen-xxx` 的 CPU 和内存" | `get_pod_resouce_detail`(支持 `pod` / `deployment` 两种粒度) | requests、limits、实时用量及占 requests/limits 的百分比 | | 4 | **变更执行** | "重启 `llm-d-qwen` 下的 `xxx` Pod" | `restart_service`(需 `admin`) | 操作回执(当前为演示实现) | | 5 | **结论归档** | "把这次巡检结论写到 `/tmp/report`" | `write_file`(需 `write`) | 工具面服务器端文件,可作为工单附件或巡检留痕 | | 6 | **环境类问答** | "现在几点?""我这台机器在哪个城市?天气如何?" | `get_times`、`get_location_by_ip`、`get_weather`、`get_my_weather` | 时间戳 / IP 属地 / 天气;亦可用于给运维结论补充时间与环境上下文 | > 第 6 类中的天气、定位工具是**通用工具接入的样例**,用于验证 MCP 工具网关的通用性(鉴权、作用域、流式输出全链路可复用),并非平台的核心业务目标。 ### 1.3 谁在用、价值在哪 | 角色 | 关心的问题 | 本系统提供的价值 | |---|---|---| | 值班 SRE / 运维 | 告警来了先看什么、Pod 是不是真挂了 | 免记命令,30 秒内拿到状态 + 关键错误日志 | | 研发(非 K8s 专家) | 我的服务部署到哪了、为什么起不来 | 用业务语言提问,无需理解 kubectl 语义 | | 平台 / 架构负责人 | 权限够不够细、调用有没有留痕 | 令牌作用域 + 工具级二次校验 + `trace_id` 全链路审计 | | 巡检与交接 | 结论能否复用、能否归档 | 固定字段输出,可直接写文件留档 | ### 1.4 能力边界(明确不做什么) - **读取为主**:10 个工具中 8 个为 `read` 只读;写操作仅 `restart_service`(需 `admin`,演示实现)与 `write_file`(需 `write`)。 - **不做自动修复**:不替代控制器,无自愈、无 HPA/告警闭环,变更由人发起。 - **不虚构事实**:答案只能来自工具返回;工具失败则如实说明失败原因,不猜测。 - **会话有界**:历史超过 5000 tokens 触发摘要,仅保留最近 6 条原文,早期细节会丢失。 - **集群范围受限**:`kube-system` 禁止查询日志与资源详情;集群凭据绑定单一 kubeconfig。 ### 1.5 工程定位 | 维度 | 说明 | |---|---| | 目标场景 | 集群巡检、Pod 状态排查、日志检索、资源配置与用量分析 | | 交互形态 | REST 同步问答 + NDJSON 流式推理 | | 权限模型 | 基于 JWT `scopes` 的能力型授权(Capability-based Authorization) | | 部署形态 | 网关与工具服务独立进程、独立扩缩容 | | 事实来源 | 仅允许来自 MCP 工具的返回值,系统提示词明确约束模型输出 | ### 1.6 设计原则 - **关注点分离**:LLM 编排与工具执行解耦,工具面可单独灰度、限流与扩容。 - **最小权限**:令牌作用域贯穿网关与工具面,工具级 `require_scopes` 实施二次校验。 - **状态外置**:对话记忆落 PostgreSQL,网关无本地会话状态,天然支持多副本。 - **请求级隔离**:Agent 实例与 MCP 连接按请求构建,调用者令牌全程透传,保障多租户隔离。 --- ## 2. 架构总览 ### 2.1 组件拓扑 ```text ┌──────────────────────────────────┐ Client ──────────▶│ FastAPI Gateway :8888 │ (Bearer JWT) │ Auth → Trace → AccessLog │ │ LangGraph Agent Runtime │ └───────┬──────────────────┬───────┘ │ │ MCP over HTTP │ │ checkpoint (token 透传) │ ▼ │ PostgreSQL ▼ ┌──────────────────────────────────┐ │ FastMCP Server :8000/mcp │ │ TokenVerifier + require_scopes │ │ K8s / Weather / IP / FS Tools │ └───┬──────────┬──────────┬────────┘ ▼ ▼ ▼ K8s API MongoDB 外部 HTTP ``` ### 2.2 职责边界 | 平面 | 服务 | 端口 | 核心职责 | 状态 | |---|---|---|---|---| | 控制面 | FastAPI Gateway / Agent | `8888` | 认证、审计、Agent 编排、流式输出 | 无状态(状态外置) | | 工具面 | FastMCP Server | `8000` | 工具注册与发现、作用域鉴权、K8s 操作 | 无状态(用户库外置) | ### 2.3 关键设计决策 | 决策 | 实现方式 | 设计价值 | |---|---|---| | 请求级 Agent | 每次请求新建 `MCPAdapter` 与 `create_agent` | 工具集与令牌严格隔离,原生支持多租户 | | 状态外置 | `AsyncPostgresSaver`,`thread_id = conversation_id` | 网关无状态,可水平扩容 | | 能力型令牌 | JWT `scopes` → MCP `AccessToken.scopes` | 权限随令牌传播,工具面自治 | | 记忆压缩 | `SummarizationMiddleware`(阈值 5000 tokens,保留 6 条) | 控制上下文长度与推理成本 | | 工具事实约束 | 系统提示词 + `recursion_limit=12` | 约束模型输出并防止工具调用失控 | --- ## 3. 请求生命周期 1. **认证(AuthN/AuthZ)**:`AuthMiddleware` 依次校验 Bearer 令牌的签名、MongoDB 中的有效令牌、过期时间与非空作用域,并将 `user`、`token`、`allowed_scopes` 注入 `request.state`。 2. **链路追踪**:`TraceIdMiddleware` 读取或生成 `trace_id`,写入 `ContextVar`,并在响应头回传,供跨服务关联。 3. **访问审计**:`LogMiddleware` 记录方法、路径、状态码与耗时。 4. **工具装配**:路由层以调用者的 `Authorization` 构建 `MCPAdapter`,拉取该身份可见的工具集。 5. **Agent 执行**:LangGraph Agent 在 `recursion_limit=12` 约束下完成「推理 → 工具调用 → 结果回填」循环。 6. **结果输出**:同步接口返回最终答案;流式接口仅透出 `model` 节点的文本增量,工具节点内容不外泄。 > 中间件按「认证 → 追踪 → 审计」分层,职责清晰,便于独立扩展。 --- ## 4. 核心能力 ### 4.1 身份与访问控制 - **口令存储**:`bcrypt` 加盐哈希,仅存 `password_hash`。 - **令牌签发**:HS256 JWT,`sub` 为用户名、`scopes` 为权限集合,默认有效期 7 天。 - **令牌吊销**:登录时覆盖 `users.token`,旧令牌因数据库校验失败立即失效(单会话语义)。 - **网关校验**:签名 → 数据库令牌 → 过期时间 → 作用域非空(空作用域返回 `403`)。 - **工具面校验**:自定义 `TokenVerifier` 复现同一校验链,并将 `scopes` 映射为 MCP `AccessToken`,供 `require_scopes` 判定。 ### 4.2 Agent 编排 - **工具发现**:经 `MCPAdapter` 以 Streamable HTTP 接入 MCP Server,配置键 `k8s-tools`。 - **令牌透传**:原始 `Authorization` 头不做改写,直接下传工具面,避免二次换取凭证。 - **上下文治理**:`SummarizationMiddleware` 按近似 token 计数触发摘要(`count_tokens_approximately`)。 - **会话记忆**:`AsyncPostgresSaver` 按 `thread_id` 持久化消息状态,实现多轮上下文与会话隔离。 - **输出归一**:同步接口对多模态内容块做文本拼接,保证返回 `answer` 为纯字符串。 ### 4.3 流式推理 - 传输格式为 **NDJSON**(`application/x-ndjson`),每个文本增量独立输出。 - 响应头携带 `X-Conversation-ID`,并设置 `Cache-Control: no-cache`、`X-Accel-Buffering: no` 以禁用反向代理缓冲。 - 仅转发 `langgraph_node == "model"` 的增量,工具调用参数与工具返回不进入前端流。 - 流内异常通过错误事件表达,保证连接语义完整。 ### 4.4 工具治理 - **作用域门控**:每个工具声明 `require_scopes(...)`,未授权调用在工具面直接拒绝。 - **错误归一**:K8s `ApiException` 转换为 `NOT_FOUND` / `FORBIDDEN` / `UNAUTHENTICATED` 等结构化结果,避免内部细节外泄。 - **降级策略**:metrics-server 不可用时仅返回 requests/limits,查询链路保持可用。 - **命名空间保护**:`kube-system` 限制日志与资源详情查询,降低误操作面。 ### 4.5 可观测性 | 能力 | 实现 | |---|---| | 日志关联 | `trace_id` 经 `ContextVar` 注入每条 `LogRecord`,日志格式包含 `trace_id` | | 响应关联 | 响应头回传 `trace_id`,支持端到端串联 | | 访问日志 | 方法、路径、状态码、耗时 | | 工具日志 | 独立文件 `mcp_weather.log`,记录工具入参与结果 | --- ## 5. 目录结构 ```text aiproject/ ├── README.md ├── requirements.txt # 依赖锁定清单(Python 3.14.10 pip3 freeze) ├── Dockerfile # 单镜像双角色:网关 :8888 / 工具面 :8000 ├── docker-compose.yml # 编排:网关 + 工具面 + MongoDB + PostgreSQL ├── docker-compose.mount.yml # 可选覆盖层:挂载 config.ini 与日志目录 ├── .dockerignore # 构建上下文裁剪 ├── frontend/ # React 前端(Vite) │ ├── src/ # 认证页、对话页、接口封装、样式 │ ├── nginx.conf # 静态托管 + /auth、/api 反代网关 │ └── Dockerfile # 构建 + nginx 双阶段 └── backend/ ├── config.ini # LLM / MCP / PostgreSQL / MongoDB 配置 ├── logging.ini # 日志配置(控制台 + 文件) ├── main.py # FastAPI 入口:lifespan、路由、中间件、uvicorn ├── author.py # /auth/register、/auth/login 与 JWT 依赖 ├── jwt.py # JWT 签发与解析(HS256) ├── middlewares.py # 认证 / 追踪 / 访问日志中间件、Agent 辅助函数 ├── model.py # Pydantic 模型与 MongoDB UserRepository ├── api/ │ └── app.py # AgentRouter:Agent 装配、同步与流式问答 ├── mcp_server_dir/ │ ├── main.py # FastMCP 入口:TokenVerifier 与全部 @mcp.tool │ ├── get_kuberbernetes_detail.py # Kubernetes API 封装(CoreV1Api / CustomObjectsApi) │ ├── conn.py # MongoDBClient:构造 UserRepository │ └── log.py # MCP 工具持久化日志 ├── utils/ │ ├── containers.py # dependency-injector 容器、日志初始化 │ ├── vllm.py # LLMServce:ChatOpenAI 封装、系统与摘要提示词 │ ├── base.py # BaseService │ ├── trace.py # trace_id ContextVar │ ├── mcp_client.py # 独立 MCP 客户端(SSE / Streamable HTTP) │ └── logging.ini # 备用日志配置 └── logs/ # 运行时生成:aiproject.log ``` --- ## 6. 技术栈 | 层次 | 选型 | 用途 | |---|---|---| | Web 框架 | FastAPI / Uvicorn / Starlette | HTTP 服务、中间件、NDJSON 流式响应 | | Agent 运行时 | LangChain / LangGraph | `create_agent`、中间件、检查点、状态图 | | 模型接入 | `langchain-openai` | 对接 OpenAI 兼容的 vLLM 端点(Qwen) | | MCP | `fastmcp` / `mcp>=2.0.0` / `langchain[mcp]>=1.4.0` | 工具服务端、协议实现、客户端适配 | | 关系型存储 | PostgreSQL / `langgraph-checkpoint-postgres` / `psycopg[binary]` | 会话检查点持久化 | | 文档型存储 | MongoDB / `motor` | 用户、令牌与作用域 | | 认证 | `python-jose[cryptography]` / `bcrypt` | JWT 签发解析、口令哈希 | | 配置与 DI | `dependency-injector` / `configparser` | 配置装配、单例资源生命周期 | | Kubernetes | 官方 `kubernetes` SDK | 集群资源查询 | | 其他 | `httpx` / `pydantic v2` | 外部 API 调用、数据契约 | | 前端 | React 19 / Vite 8 / nginx | 登录注册、流式对话 UI、同源反代 | > 具体版本以根目录 `requirements.txt` 为准(Python 3.14.10 环境导出,全量锁定),Docker 构建直接安装该清单,避免环境漂移。 --- ## 7. 配置模型 配置文件:`backend/config.ini`。 | 段 | 关键项 | 说明 | |---|---|---| | `[llm]` | `base_url`、`api_key`、`model`、`temperature`、`max_tokens`、`timeout` | OpenAI 兼容端点参数 | | `[mcp]` | `server_url` | MCP 工具服务地址,形如 `http://127.0.0.1:8000/mcp` | | `[psycopg]` | `url` | PostgreSQL 连接串,`lifespan` 中用于 `AsyncPostgresSaver` | | `[mongodb]` | `host`、`username`、`password`、池与超时参数 | 用户库连接与连接池参数 | 配置约定: - 网关与工具面共享同一 `SECRET_KEY` 与 `auth_db.users`,部署时需保持一致。 - `Dependency Injector` 在启动阶段统一加载配置,按环境替换 `config.ini` 即可切换部署目标。 - 数据库连接池与超时参数可按并发规模调整。 ### 7.1 环境变量覆盖 `utils/containers.py` 的 `apply_env_overrides()` 在 `lifespan` 启动阶段、provider 实例化之前,用环境变量覆盖 `config.ini` 同名项(未设置或为空串则沿用 ini 值),命名约定 `SECTION__OPTION`。 | 环境变量 | 覆盖项 | 典型用途 | |---|---|---| | `MCP__SERVER_URL` | `[mcp] server_url` | 容器网络内改为 `http://mcp:8000/mcp` | | `PSYCOPG__URL` | `[psycopg] url` | 切换会话检查点数据库 | | `MONGODB__HOST` / `MONGODB__PORT` / `MONGODB__USERNAME` / `MONGODB__PASSWORD` / `MONGODB__DB` / `MONGODB__MAXPOOLSIZE` | `[mongodb]` 对应项 | 切换用户库 | | `LLM__BASE_URL` / `LLM__API_KEY` / `LLM__MODEL` / `LLM__TEMPERATURE` / `LLM__MAX_TOKENS` | `[llm]` 对应项 | 切换模型端点与推理参数 | > 两侧行为一致:网关由 `apply_env_overrides()` 统一处理;工具面 `mcp_server_dir/main.py` 启动时读同一份 `config.ini`(`_load_mongo_settings()`),并支持同名环境变量覆盖,因此编排内可直接把用户库指向随容器部署的 MongoDB。 --- ## 8. 快速开始 ### 8.1 前置条件 - Python 3.10+ - MongoDB(`27017`,认证库 `admin`) - PostgreSQL(会话检查点) - OpenAI 兼容 LLM 服务(如 Qwen / vLLM) - Kubernetes kubeconfig:`/tmp/qwen-user.kubeconfig` - 出网可达 `ip-api.com`、`api.open-meteo.com` ### 8.2 安装依赖 依赖以根目录 `requirements.txt` 为准(Python 3.14.10 环境 `pip3 freeze` 导出的全量锁定清单,共 125 个包): ```bash pip install -r requirements.txt ``` ### 8.3 启动服务 两个服务独立启动;网关需以 `backend/` 为工作目录,以匹配源码中的导入路径。 ```bash cd /home/ubuntu/jasonwork/aiproject/backend # 1) 工具面:FastMCP,HTTP transport,端点 /mcp python mcp_server_dir/main.py # 2) 控制面:FastAPI 网关 python main.py # 或:uvicorn main:app --host 0.0.0.0 --port 8888 ``` | 入口 | 地址 | |---|---| | 网关 Swagger | | | 网关 OpenAPI | | | MCP 端点 | | ### 8.4 容器化部署 镜像为**单镜像双角色**:默认 `CMD` 启动网关,覆盖命令即启动工具面。基础镜像由构建参数控制(默认 `3.14.10`,该 tag 未发布时改用 `3.14.9`);依赖按 `requirements.txt` 精确安装(与开发环境一致的 125 个包)。构建阶段 apt 与 pip 默认使用腾讯云镜像(`APT_MIRROR` / `PIP_INDEX_URL` 可覆盖)。 ```bash docker compose up -d --build # 启动网关、工具面、MongoDB、PostgreSQL docker compose ps docker compose logs -f gateway ``` | 服务 | 容器 | 端口 | 说明 | |---|---|---|---| | 控制面 | `agent-gateway` | `8888` | `uvicorn main:app`,等依赖服务健康后启动 | | 工具面 | `agent-mcp` | `8000` | `python mcp_server_dir/main.py`,启动即读 kubeconfig | | 前端 | `agent-web` | `3000` | React 构建产物由 nginx 托管,`/auth`、`/api` 反代网关 | | 用户库 | `agent-mongo` | 仅容器网络 | `mongo:8.0`,root 账号由 `MONGO_USERNAME` / `MONGO_PASSWORD` 决定 | | 检查点库 | `agent-postgres` | 仅容器网络 | `postgres:17-alpine`,账号由 `POSTGRES_*` 决定 | 启动依赖链:`mongo` / `postgres` → `mcp` → `gateway`,任一依赖不健康,后续服务不会启动。 **配置与日志:默认用镜像内置,挂载则用挂载的** | 场景 | 命令 | 行为 | |---|---|---| | 默认 | `docker compose up -d` | 用镜像内 `config.ini`;日志写容器内 `/app/backend/logs`,可 `docker compose logs` 或 `docker cp` 取 | | 挂载 | `docker compose -f docker-compose.yml -f docker-compose.mount.yml up -d` | 用宿主 `./backend/config.ini` 与 `./logs`,改配置免重建镜像 | 挂载前需给 uid `10001` 权限;单文件挂载要求宿主文件已存在(否则 Docker 会建同名目录导致启动失败): ```bash mkdir -p ./logs && touch ./logs/mcp_weather.log sudo chown -R 10001:10001 ./logs ``` `docker-compose.mount.yml` 支持 `CONFIG_FILE` / `LOG_DIR` / `MCP_LOG_FILE` 三个变量。 **首次部署需初始化用户库**:编排内的 MongoDB 是空库,而令牌校验依赖 `auth_db.users`,先注册账号再调用问答接口: ```bash curl -X POST http://localhost:8888/auth/register \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"","scopes":["read","write","admin"]}' ``` **改用外部依赖**:把 `PSYCOPG_URL`、`MONGODB_HOST`、`MONGO_USERNAME` / `MONGO_PASSWORD` 指向既有实例,并删除 `docker-compose.yml` 中的 `mongo` / `postgres` 服务及对应 `depends_on` 条目。 部署要点: - **必须挂载的输入**:工具面需把 kubeconfig 挂到容器内 `/tmp/qwen-user.kubeconfig`(代码内固定路径)。 - **服务发现**:通过 `MCP__SERVER_URL=http://mcp:8000/mcp` 让网关按服务名访问工具面,避免依赖宿主 IP。 - **运行用户与目录**:容器以 uid `10001` 运行,挂载文件需对其可读;`write_file` 工具建议写入 `/data`。 - **健康检查**:网关探测 `/openapi.json`(认证白名单内,免令牌);工具面与依赖服务用端口/`ping` 判定。 可覆盖变量(写入 `.env` 或直接 `export`): | 变量 | 默认值 | 说明 | |---|---|---| | `PYTHON_VERSION` | `3.14.10` | 构建用基础镜像版本 | | `APT_MIRROR` | `mirrors.cloud.tencent.com` | Debian 软件源域名(构建阶段替换 `deb.debian.org`) | | `PIP_INDEX_URL` | `https://mirrors.cloud.tencent.com/pypi/simple` | pip 索引源 | | `GATEWAY_PORT` / `MCP_PORT` / `WEB_PORT` | `8888` / `8000` / `3000` | 宿主映射端口 | | `NPM_REGISTRY` | `https://mirrors.cloud.tencent.com/npm/` | 前端构建 npm 源 | | `KUBECONFIG_PATH` | `/tmp/qwen-user.kubeconfig` | 宿主 kubeconfig 路径 | | `MONGODB_HOST` | `mongo` | 用户库地址(用外部实例时填具体 IP) | | `MONGO_USERNAME` / `MONGO_PASSWORD` | `admin` / `admin123` | MongoDB root 账号,同时注入网关与工具面 | | `MONGO_DB` | `auth_db` | 用户库名 | | `PSYCOPG_URL` | `postgresql://postgres:postgres@postgres:5432/postgres?sslmode=disable` | 会话检查点连接串 | | `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | `postgres` / `postgres` / `postgres` | 改密码时需同步 `PSYCOPG_URL` | | `MCP_SERVER_URL` | `http://mcp:8000/mcp` | 网关访问工具面地址 | | `LLM_BASE_URL` / `LLM_API_KEY` / `LLM_MODEL` | 空(沿用 ini) | 模型端点覆盖 | > 镜像内 `config.ini` 含明文密钥,生产环境建议改用环境变量注入(见 §7.1),或仅挂载不含密钥的配置。 ### 8.5 前端(React) `frontend/` 为 Vite + React 19 单页应用,不含 UI 框架依赖。接口一律用同源相对路径(`/auth`、`/api`):开发时由 Vite 代理、生产时由 nginx 反代,**浏览器不产生跨域请求,网关无需开启 CORS**。 ```bash cd frontend npm install npm run dev # http://localhost:5173,需先启动网关 :8888 npm run build # 产物输出到 dist/ ``` > **需要 Node `^20.19.0` 或 `>=22.12.0`**(Vite 8 要求)。版本过低时会在解析 `vite.js` 时报 `SyntaxError: Unexpected token '.'`,与代码无关;`predev` / `prebuild` 已内置版本检查。nvm 用户可直接 `nvm use`(`.nvmrc` 指定 `22.12.0`)。 > **用主机名 / 内网域名访问时会遇到 `Blocked request. This host "xxx" is not allowed`**:Vite 开发服务器默认只放行 localhost。`vite.config.js` 已默认放行 `node1`、`localhost`、`127.0.0.1`,追加其他主机用 `VITE_ALLOWED_HOSTS=node1,10.0.0.5 npm run dev`,`*` 表示全部放行(仅用于临时调试)。生产走 nginx,不受该限制。 开发代理目标可用 `VITE_PROXY_TARGET` 覆盖(默认 `http://127.0.0.1:8888`)。 | 页面 | 能力 | |---|---| | 登录 / 注册 | 注册时勾选作用域(`read` / `write` / `admin`);令牌存 `localStorage`;接口返回 `401` 自动回登录页 | | 对话 | 流式输出(NDJSON 增量渲染)、停止生成、新对话;会话 ID 由响应头 `X-Conversation-ID` 回填 | | 状态提示 | 空作用域 403 预警、工具失败原因回显、示例提问一键填充、`Enter` 发送 / `Shift+Enter` 换行 | 容器化部署时无需单独构建前端,`docker compose up -d --build` 会一并构建,访问 。nginx 将 `/api/` 反代到 `gateway:8888` 并关闭 `proxy_buffering`,保证流式响应不被缓冲。 --- ## 9. 接口契约 ### 9.1 REST 路由 | 方法 | 路径 | 认证 | 说明 | |---|---|---|---| | POST | `/auth/register` | 否 | 注册,请求体 `{username, password, scopes}` | | POST | `/auth/login` | 否 | 登录,返回 `access_token`、`token_type`、`allowed_scopes` | | POST | `/api/v1/agent/query` | 是 | 同步问答,返回 `{answer}` | | POST | `/api/v1/agent/query/stream` | 是 | 流式问答,返回 NDJSON 与 `X-Conversation-ID` | | GET | `/trace-test` | 是 | 追踪链路自检 | | GET | `/docs` / `/redoc` / `/openapi.json` | 否 | 接口文档 | ### 9.2 数据契约 ```json // AgentRequest { "question": "string, 1..500", "conversation_id": "string | null" } // AgentResponse { "answer": "string" } ``` ### 9.3 流式协议语义 | 项目 | 约定 | |---|---| | Media Type | `application/x-ndjson` | | 分片内容 | 模型 `model` 节点的文本增量 | | 会话标识 | 响应头 `X-Conversation-ID` | | 隔离键 | `conversation_id` 作为 LangGraph `thread_id` | | 异常表达 | 流内错误事件 | --- ## 10. MCP 工具目录 「对应用途」列对应 §1.2 的场景编号,用于快速判断某个业务问题该由哪个工具支撑。 | 工具 | 作用域 | 读写属性 | 幂等性 | 对应用途 | 说明 | |---|---|---|---|---|---| | `get_namesapce` | `read` | 只读 | 是 | ① 巡检入口 | 列出集群命名空间 | | `get_pod_info` | `read` | 只读 | 是 | ① 巡检 / 状态排查 | Pod 名称、状态、节点、IP、镜像、重启次数 | | `get_pod_log` | `read` | 只读 | 是 | ② 故障定位 | Pod 日志,按错误关键字过滤,`tail_lines` 1–10 | | `get_pod_resouce_detail` | `read` | 只读 | 是 | ③ 容量与资源分析 | Pod/Deployment 的 CPU、内存 requests/limits 与实时用量 | | `get_times` | `read` | 只读 | 是 | ⑥ 环境上下文 | 服务器当前时间,可用于给结论打时间戳 | | `get_location_by_ip` | `read` | 只读 | 是 | ⑥ 环境上下文 | IP 属地(ip-api.com) | | `get_weather` | `read` | 只读 | 是 | ⑥ 通用工具样例 | 按经纬度查天气,缺省自动定位(Open-Meteo) | | `get_my_weather` | `read` | 只读 | 是 | ⑥ 通用工具样例 | 当前所在地天气 | | `write_file` | `write` | 写 | 否 | ⑤ 结论归档 | 工具面本地文件写入 | | `restart_service` | `admin` | 写 | 否 | ④ 变更执行 | 按命名空间与 Pod 重启服务(演示实现) | --- ## 11. 安全模型 ### 11.1 信任边界 - **边界一:客户端 → 网关**。Bearer JWT 为唯一凭证,网关为策略执行点(PEP)。 - **边界二:网关 → 工具面**。同一 JWT 透传,工具面独立复验,遵循零信任原则。 - **共享信任域**:两端共用 `SECRET_KEY` 与 `auth_db.users`,部署时需统一密钥与用户库配置。 ### 11.2 校验链 | 环节 | 校验内容 | 失败响应 | |---|---|---| | `AuthMiddleware` | Bearer 格式、签名、数据库令牌、过期、作用域非空 | `401` / `403` | | `TokenVerifier` | 签名、`sub`、数据库令牌、过期 | 工具面拒绝(`AccessToken = None`) | | `require_scopes` | 工具级作用域 | 工具调用拒绝 | ### 11.3 安全实践 | 实践 | 实现 | |---|---| | 口令安全 | `bcrypt` 加盐哈希,仅存哈希值 | | 令牌吊销 | 登录覆盖 `token`,旧令牌立即失效 | | 最小权限 | JWT `scopes` + 工具级 `require_scopes` 双层校验 | | 边界复验 | 网关与工具面各自验签,零信任架构 | | 错误脱敏 | K8s 异常归一化,避免内部细节外泄 | | 命名空间保护 | `kube-system` 限制日志与资源详情查询 | | 审计追踪 | `trace_id` 贯穿日志与响应头 | --- ## 12. 数据与状态管理 ### 12.1 MongoDB `auth_db.users` | 字段 | 类型 | 说明 | |---|---|---| | `username` | string | 用户名,登录与令牌主体 | | `password_hash` | string | `bcrypt` 哈希 | | `token` | string / null | 最近一次签发的 JWT,用于吊销判定 | | `scopes` | string[] | `read` / `write` / `admin` | | `k8s_service_account` | string / null | 预留字段 | | `created_at` / `updated_at` | datetime | 审计时间戳 | > 编排内置的 MongoDB 首次启动为空库,必须先通过 `/auth/register` 建账号(见 §8.4),否则网关侧 `401 Token 无效或已被撤销`、工具面拒绝一切令牌。数据落在命名卷 `mongo-data`,`docker compose down -v` 会清空。 ### 12.2 PostgreSQL 会话状态 - 由 `AsyncPostgresSaver` 管理,启动时执行 `setup()` 建表。 - `thread_id = conversation_id`,未传时流式接口生成 UUID。 - 会话状态包含消息序列;`SummarizationMiddleware` 达阈值后以摘要替换早期消息。 --- ## 13. 可靠性与性能 ### 13.1 超时配置 | 环节 | 超时 | |---|---| | LLM 调用 | 180s(`LLMServce` 默认值) | | 外部 HTTP(天气/定位) | 8s | | MongoDB | 选主 5s、连接 10s、套接字 30s、等待队列 5s | ### 13.2 容错与降级 - **metrics-server 不可用**:跳过实时用量,仅返回 requests/limits。 - **MCP 工具失败**:结构化错误回填模型上下文,由模型向用户说明失败原因。 - **流式异常**:通过流内错误事件表达,保证连接可感知。 - **会话检查点**:PostgreSQL 承载对话状态,网关实例可无状态水平扩展。 ### 13.3 性能设计 - **无状态扩展**:网关不持有会话状态,可按 QPS 水平扩容。 - **按请求裁剪工具集**:每个请求仅加载当前身份可见的工具,降低模型上下文噪声。 - **上下文压缩**:`SummarizationMiddleware` 按 token 阈值压缩历史,控制上下文长度与推理成本。 - **连接池**:MongoDB 连接池与超时参数可配置,适配不同并发规模。 - **标准化工具接入**:MCP over HTTP,工具面可独立部署与扩容。 --- ## 14. 运维手册 ### 14.1 日志与追踪 | 产物 | 位置 | |---|---| | 网关应用日志(含 `trace_id`) | `backend/logs/aiproject.log` | | 工具面日志 | `mcp_weather.log`(相对启动目录;`backend/` 下启动即 `backend/mcp_weather.log`,容器内为 `/app/backend/mcp_weather.log`) | | 链路关联 | 请求/响应头 `trace_id` | ### 14.2 故障排查 | 症状 | 可能原因 | 处置 | |---|---|---| | `401 缺少认证信息` | 未携带 `Authorization` | 补充 `Bearer ` | | `401 Token 无效或已被撤销` | 重新登录导致旧令牌失效、密钥不一致 | 重新签发令牌,核对两侧 `SECRET_KEY` | | `403 该用户没有任何MCP接口权限` | 用户 `scopes` 为空 | 授予最小作用域 | | `502 Agent调用失败` | LLM 或 MCP 不可达、工具异常 | 检查 `[llm] base_url`、`[mcp] server_url` 与工具日志 | | `504 Agent 或工具调用超时` | 模型推理慢、工具阻塞 | 核查 LLM 负载与 K8s API 时延 | | MCP 工具列表为空 | 令牌被工具面拒绝、URL 错误 | 核对工具面 `TokenVerifier` 与网络连通性 | | 启动失败 | PostgreSQL 连接串错误、`sslmode` 不匹配 | 校验 `[psycopg] url` 与网络策略 | | 容器启动即退出(工具面) | kubeconfig 未挂载或路径不符;挂载文件对 uid `10001` 不可读 | 核对 `KUBECONFIG_PATH` 与 `/tmp/qwen-user.kubeconfig`,调整文件权限 | | 容器启动即退出(网关) | PostgreSQL 不可达,`lifespan` 建表失败 | 检查 `PSYCOPG__URL` 与容器网络策略 | | 容器内 MCP 工具列表为空 | `MCP__SERVER_URL` 仍指向宿主 IP | 容器网络内应使用服务名,默认 `http://mcp:8000/mcp` | | 编排部署后全部请求 401 | 内置 MongoDB 为空库,且网关/工具面令牌校验都查 `auth_db.users` | 先 `POST /auth/register` 建账号,再登录获取令牌 | | 两侧令牌校验结果不一致 | 网关与工具面指向了不同的 MongoDB | 确认 `MONGODB_HOST` 与 `MONGO_USERNAME` / `MONGO_PASSWORD` 对两个服务一致 | | 挂载日志后启动报权限错误 | 宿主目录属主不是 uid `10001`,或日志单文件挂载目标不存在 | `chown -R 10001:10001 ./logs`,并 `touch ./logs/mcp_weather.log` | --- ## 15. 测试与联调 ### 15.1 账号与作用域 | 账号 | 作用域 | |---|---| | `test` | `read` | | `jason` | `read`、`write` | | `admin` | `read`、`write`、`admin` | ### 15.2 获取令牌 ```bash curl -X POST http://localhost:8888/auth/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":""}' ``` ### 15.3 典型提问(按用途验证) | 用途 | 建议提问 | 期望工具 | |---|---|---| | 集群巡检 | "集群里有哪些命名空间?" | `get_namesapce` | | 集群巡检 | "帮我查下 namespace 为 `llm-d-qwen` 下的 Pod" | `get_pod_info` | | 故障定位 | "`nginx-deployment-79fccd6848-nhd76` 一直重启,看下日志" | `get_pod_log` | | 资源分析 | "查下 `llm-d-qwen` 里 `qwen-xxx` 的 CPU 和内存请求与上限" | `get_pod_resouce_detail` | | 变更执行 | "重启 `llm-d-qwen` 下的 `xxx` Pod"(需 `admin`) | `restart_service` | | 结论归档 | "把上面的巡检结论写到 `/tmp/report`"(需 `write`) | `write_file` | ### 15.4 流式调用 ```bash curl -Ni -X POST http://localhost:8888/api/v1/agent/query/stream \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{"question":"帮我查下 namespace 为 test 下的 Pod"}' ``` ### 15.5 独立调用 MCP 工具 ```bash cd /home/ubuntu/jasonwork/aiproject/backend python utils/mcp_client.py ``` --- ## 16. 能力规划 1. **多集群接入**:支持多 kubeconfig 与集群切换,覆盖多环境运维场景。 2. **权限细化**:扩展命名空间级 RBAC 与变更审批流。 3. **可观测性增强**:接入 Prometheus 指标(QPS、时延、工具成功率)与 OTLP 分布式追踪。 4. **工具生态扩展**:插件化工具注册、工具 schema 缓存与更丰富的运维能力。 5. **部署形态完善**:提供容器镜像与 Compose / Helm 编排,统一交付流程。