糖豆家

📌 一、项目概述

Ops Agent 是一个基于 LangGraph 的运维智能体项目，允许用户通过自然语言下达运维任务，由 AI Agent 通过 SSH 自动执行服务器操作。

属性	内容
项目名称	som-agent
核心定位	运维 AI Agent（脚手架/演示项目）
语言/框架	Python 3.12+ / FastAPI / LangGraph / SQLAlchemy
许可证	MIT
警告级别	⚠️ 不建议用于生产环境

🏗️ 二、架构设计

2.1 技术架构图

层级	技术	职责
1. 表现层	HTML/CSS/JS + SSE + WebSocket	用户界面、实时交互
2. 网关层	FastAPI + uvicorn + Pydantic	路由分发、请求验证、认证授权
3. Agent 编排层	LangGraph + LangChain	任务规划、命令生成、安全分级、审批门
4. LLM 集成层	LangChain OpenAI/Anthropic	模型调用、超时控制、错误处理
5. 工具层	asyncssh + MCP Adapters + LangChain Tools	SSH 执行、云服务调用、任务澄清
6. 数据层	SQLAlchemy + PostgreSQL/SQLite + Fernet	数据持久化、凭证加密、审计追踪
7. 基础设施层	Docker + Python 3.12 + uv	容器化部署、环境隔离

核心技术栈：Python 3.12 + LangGraph + LangChain + FastAPI + asyncssh + SQLAlchemy

2.2 应用架构图

┌─────────────────────────────────────────────────────────────────┐
│                        前端 (index.html)                         │
│         单文件 Web 控制台：对话 + 终端 + 配置 + 审计              │
└─────────────────────────────────────────────────────────────────┘
                                  │
                         FastAPI HTTP/WS
                                  │
┌─────────────────────────────────────────────────────────────────┐
│                       API 路由层 (app/api/)                      │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────────┐ │
│  │ auth.py │ │chat.py  │ │admin.py │ │terminal.py│ │deps.py    │ │
│  │ 登录认证 │ │对话/SSE │ │后台配置 │ │交互终端WS │ │ 依赖注入  │ │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────────────────────────────────────┐
│                    Agent 核心层 (app/agent/)                     │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐       │
│  │ graph.py  │ │ state.py  │ │guardrails.py│ │runtime.py │     │
│  │ LangGraph │ │ 状态定义   │ │ 命令分级   │ │ 流式运行   │       │
│  │ 主图编排   │ │ Plan+Exec │ │ 三级护栏   │ │ 审批续跑   │       │
│  └───────────┘ └───────────┘ └───────────┘ └───────────┘       │
│  ┌───────────┐                                                  │
│  │prompts.py │  系统提示词                                       │
│  └───────────┘                                                  │
└─────────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────────────────────────────────────┐
│                      工具层 (app/tools/)                         │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐               │
│  │   ssh.py    │ │mcp_manager.py│ │ clarify.py  │               │
│  │ SSH 执行    │ │ 云 MCP 接入  │ │ 任务澄清    │               │
│  └─────────────┘ └─────────────┘ └─────────────┘               │
└─────────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────────────────────────────────────┐
│              LLM 层 (app/llm/registry.py)                        │
│    OpenAI / Anthropic / Qwen / MiniMax / DeepSeek 统一封装       │
└─────────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────────────────────────────────────┐
│                     数据层 (app/db/)                             │
│  ┌─────────┐ ┌─────────┐ ┌─────────────┐                        │
│  │models.py│ │base.py  │ │ crypto.py   │                        │
│  │ ORM模型 │ │SQLAlch. │ │ Fernet加密  │                        │
│  └─────────┘ └─────────┘ └─────────────┘                        │
│                        │                                        │
│                   SQLite / PostgreSQL                            │
└─────────────────────────────────────────────────────────────────┘

2.3 Agent 执行流程（LangGraph 图）

START 
  │
  ▼
┌─────────┐  tool_calls?  ┌───────────┐ 审批通过/只读  ┌──────────────┐
│  Agent  │──────────────▶│ Guardrail │───────────────▶│execute_tools │
│  (LLM)  │               │  (护栏)   │               │  (执行工具)  │
└─────────┘               └───────────┘               └──────────────┘
     ▲                         │                            │
     │                         │ 危险命令 → interrupt()      │
     │                         │ 等用户审批                   │
     │                         ▼                            │
     │                   ┌───────────┐                      │
     └───────────────────┤   END     │◀─────────────────────┘
                         └───────────┘

📁 三、模块详解

3.1 Agent 编排 (`app/agent/`)

文件	职责	关键实现
graph.py	LangGraph 主图编排	`START → agent → guardrail → execute_tools → END` 循环；60秒 LLM 超时保护；错误分类处理（余额不足/认证失败/404）
state.py	状态定义	`AgentState` TypedDict：messages, plan, current_step, dry_run, notes, approved_ids, auto_approve_all, last_io
guardrails.py	命令分级护栏	三级分类（readonly/mutating/dangerous）；正则规则 + LLM 辅助判断；白名单持久化
runtime.py	Agent 运行时	SSE 流式输出；`astream_turn`/`astream_resume`/`astream_clarify`；全局 MemorySaver checkpointer
prompts.py	系统提示词	角色定位：SRE/运维工程师；工作原则；工具说明

3.2 命令分级护栏详解

python

# guardrails.py 中的危险命令正则模式
_DANGEROUS = [
    r"\brm\s+-[a-z]*[rf]",          # rm -rf
    r"\bmkfs\b", r"\bdd\b",
    r"\b(shutdown|reboot|halt|poweroff)\b",
    r"\b(drop|truncate)\s+(table|database)\b",
    r":\s*\(\)\s*\{",               # fork 炸弹
    ...
]

# LLM 辅助判断（用于 SSH 命令）
async def classify_command_llm(command: str, model) -> CommandLevel:
    # 使用 LLM 判断命令风险级别，失败时回退到正则规则

3.3 数据库模型 (`app/db/models.py`)

模型	用途	加密字段
ModelProvider	LLM 供应商配置	api_key_enc
SSHKey	可复用 SSH 私钥库	private_key_enc, passphrase_enc
Server	服务器 SSH 连接配置	password_enc, private_key_enc, passphrase_enc
CloudAccount	云账号 MCP 配置	secrets_enc
Conversation	会话记录	-
Message	消息历史	-
AutoApproveRule	自动审批白名单	-
AuditLog	审计日志	-

3.4 API 路由 (`app/api/`)

路由	方法	功能
`/auth/login`	POST	登录认证
`/auth/logout`	POST	登出
`/chat/stream`	POST	发起任务（SSE 流式）
`/chat/approve`	POST	审批续跑
`/chat/clarify`	POST	澄清回答
`/chat/conversations`	GET/DELETE	会话管理
`/chat/terminal/*`	WS/POST/DELETE	交互式终端
`/admin/models`	CRUD	模型配置
`/admin/servers`	CRUD	服务器配置
`/admin/ssh-keys`	CRUD	SSH 密钥库
`/admin/cloud-accounts`	CRUD	云账号配置
`/admin/audits`	GET	审计日志

3.5 交互式终端 (`app/api/terminal.py`)

基于 WebSocket 的持久会话
PTY Shell 保持常驻（刷新不丢失）
回放缓冲区（256KB）支持历史输出恢复
30分钟空闲超时自动回收

🔐 四、安全设计

4.1 凭证加密

python

# db/crypto.py
Fernet 对称加密（主密钥来自 SECRET_ENCRYPTION_KEY）
- SSH 私钥/密码
- 云账号密钥
- 登录会话令牌（带 TTL）

4.2 认证机制

单用户登录（用户名密码来自 .env）
Cookie + Fernet 签名验证
WebSocket 端点同步校验 Cookie

4.3 Human-in-the-loop

危险命令强制 interrupt() 暂停
变更命令需逐条审批
支持"本会话所有命令无需确认"开关

4.4 安全风险（README 明确警告）

风险项	现状	建议
鉴权	单用户，不支持多用户隔离	生产环境需 RBAC
SSH 主机指纹	`known_hosts=None`	应配置 known_hosts
密钥托管	本地 Fernet 主密钥	建议用 KMS/Vault
Checkpointer	内存版 MemorySaver	生产换 PostgresSaver

⚙️ 五、配置项

bash

# 必填
SECRET_ENCRYPTION_KEY    # Fernet 主密钥
AUTH_USERNAME            # 登录用户名
AUTH_PASSWORD            # 登录密码（留空则不启认证）

# 可选
DATABASE_URL             # 数据库路径（默认 SQLite）
CHECKPOINT_DB_URL        # LangGraph checkpointer
REQUIRE_APPROVAL_FOR_DANGEROUS   # 危险命令是否强制审批
REQUIRE_COMMAND_APPROVAL         # 是否逐条审批
DEFAULT_DRY_RUN          # 默认只展示不执行
APP_HOST / APP_PORT      # 监听地址/端口

📦 六、依赖分析

核心依赖：
├── langgraph==1.2.2           # Agent 编排框架
├── langchain-core>=0.3.0      # LangChain 核心
├── langchain-openai>=0.2.0    # OpenAI/Qwen/MiniMax/DeepSeek
├── langchain-anthropic>=0.3.0 # Anthropic
├── langchain-mcp-adapters>=0.1.0  # MCP 云资源接入
├── asyncssh>=2.14.0           # SSH 异步连接
├── fastapi>=0.115.0           # Web 框架
├── sqlalchemy>=2.0.0          # ORM
├── cryptography>=43.0.0       # Fernet 加密
└── pydantic>=2.8.0            # 数据验证

✅ 七、项目亮点

Human-in-the-loop 设计：基于 LangGraph interrupt() 实现审批门，审批前任务自动挂起
命令分级护栏：正则 + LLM 双层判断，危险命令强制人工审批
流式输出：SSE 实现实时流式响应，前端体验流畅
交互式终端：WebSocket + PTY Shell，刷新不丢会话
凭证安全：Fernet 加密所有敏感信息落库
全量审计：每次命令执行都有记录可追溯
多模型支持：OpenAI 兼容协议统一封装，切换灵活

⚠️ 八、待改进项（生产化 TODO）

类别	改进项
安全硬化	checkpointer 换 PostgresSaver
	正式鉴权 / RBAC / 多用户隔离
	SSH `known_hosts` 主机指纹校验
	密钥改用 KMS / Vault 托管
能力扩展	云资源管理（ECS/OSS/安全组）
	监控管理（Prometheus/Zabbix）
	网络设备管理（交换机/路由器/防火墙）

📊 九、代码质量评估

维度	评分	说明
架构设计	⭐⭐⭐⭐⭐	模块化清晰，分层合理
代码规范	⭐⭐⭐⭐	使用 ruff，风格统一
文档完整性	⭐⭐⭐⭐⭐	README 详细，代码注释充足
错误处理	⭐⭐⭐⭐	有超时保护和异常分类
安全性	⭐⭐⭐	演示项目，生产需加固
可维护性	⭐⭐⭐⭐	代码简洁，依赖清晰

以上就是对 Ops Agent 项目的完整分析。该项目是一个设计良好的运维 AI Agent 演示脚手架，核心功能完整，但在生产环境使用前需要进行安全加固。

📌 一、项目概述 ​

🏗️ 二、架构设计 ​

2.1 技术架构图 ​

2.2 应用架构图 ​

2.3 Agent 执行流程（LangGraph 图） ​

📁 三、模块详解 ​

3.1 Agent 编排 (app/agent/) ​

3.2 命令分级护栏详解 ​

3.3 数据库模型 (app/db/models.py) ​

3.4 API 路由 (app/api/) ​

3.5 交互式终端 (app/api/terminal.py) ​

🔐 四、安全设计 ​

4.1 凭证加密 ​

4.2 认证机制 ​

4.3 Human-in-the-loop ​

4.4 安全风险（README 明确警告） ​

⚙️ 五、配置项 ​

📦 六、依赖分析 ​

✅ 七、项目亮点 ​

⚠️ 八、待改进项（生产化 TODO） ​

📊 九、代码质量评估 ​