ITOps Agent Platform 开发助手

国内首个企业级 IT 运维多 Agent 自动化平台 — 基于大语言模型的智能运维解决方案。ITOps Agent Platform通过可视化工作流编排，将多个AI Agent组合成智能运维自动化流水线，实现服务器管理、告警处理、故障诊断、日志分析、脚本管理、定时运维任务的自动化执行，支持国内外主流大模型，旨在 Zabbix/Prometheus 告警自动修复闭环，Docker 一键部署，多平台兼容。

qinshihu 755 193 Updated 2w ago

Resources

GitHub

Install

npx skillscat add qinshihu/itops-agent-platform

Install via the SkillsCat registry.

SKILL.md

所有的开发从第一性原理出发，对于可参考的开源项目或代码不用非照搬。开发或实现某个能力和功能之前，先思考下，什么才是最优解最合理，最具前沿视角？不一定照搬别的项目的设计或实现。

name: "itops-agent-platform"
description: "ITOps Agent Platform 企业级 IT 运维多 Agent 自动化平台开发助手。当用户需要开发、调试、测试、部署此项目，或询问项目架构、代码结构、功能模块时使用。覆盖前后端开发、Docker 部署、CI/CD、数据库迁移等全流程。"

ITOps Agent Platform 开发助手

项目概述

企业级 IT 运维多 Agent 自动化平台。通过可视化工作流编排多个 AI Agent 协同工作，实现服务器巡检、告警处理、故障诊断、合规检查等运维任务自动化。

许可证: MPL-2.0（永久开源，禁止闭源商用）
仓库: https://github.com/qinshihu/itops-agent-platform

技术栈

层级	技术
前端	React 18 + TypeScript + Vite 5 + Tailwind CSS 3 + Zustand + @tanstack/react-query + @xyflow/react + socket.io-client + xterm.js
后端	Node.js 18+ + Express 4 + TypeScript + better-sqlite3 (WAL) + Socket.io 4 + ssh2 + Zod
部署	Docker 多阶段构建 + Docker Compose + Nginx (安全头 + SPA 路由 + API/WS 反代)
测试	Vitest + @testing-library/react + @vitest/coverage-v8
CI/CD	GitHub Actions (ci.yml: lint+test+build; release.yml: 质量门禁+镜像推送)

目录结构

itops-agent-platform/
├── backend/
│   ├── src/
│   │   ├── app.ts                    # 入口: Express + Socket.io 初始化, 中间件链, 路由注册, 优雅关闭
│   │   ├── constants/agentNames.ts   # Agent 名称常量 (SERVER_COMMAND, SYSTEM_INSPECTION 等 10 种)
│   │   ├── data/playbooks.ts         # 运维 Playbook 预设数据
│   │   ├── middleware/
│   │   │   ├── auth.ts               # JWT 认证 (authenticateToken) + 角色检查 (requireRole) + 强制改密 (requirePasswordChange), 含用户缓存 (10s TTL)
│   │   │   ├── rateLimiter.ts        # 内存速率限制 (按路由配置不同窗口/上限) + Webhook IP 白名单 (支持 CIDR)
│   │   │   ├── errorHandler.ts       # 统一错误处理: 区分 operational/unexpected 错误, 返回 {success,code,message,traceId}
│   │   │   ├── validation.ts         # Zod schema 请求体验证
│   │   │   ├── trace.ts              # 请求追踪 (traceId 注入)
│   │   │   └── commandFilter.ts      # SSH 命令安全检查: 7 类危险命令策略 (rm -rf, mkfs, iptables -F, kill -9 0 等), 按角色 block/warn
│   │   ├── models/
│   │   │   ├── database.ts           # SQLite 单例 (Proxy 模式), WAL 模式 + 16 项 pragma 优化, 定期维护 (每日 checkpoint/每周 analyze/每月 vacuum)
│   │   │   ├── migrations.ts         # 迁移入口: runMigrations(db)
│   │   │   ├── migrations/
│   │   │   │   ├── index.ts          # 注册所有迁移 (v001~v017, 跳过 v008/v011)
│   │   │   │   ├── migrationFramework.ts  # MigrationManager 类: schema_migrations 表, 版本控制, 顺序执行
│   │   │   │   └── v001~v017_*.ts    # 各版本迁移文件
│   │   │   └── presets/              # 预设数据初始化 (Agent/工作流/知识/脚本/告警映射/定时任务/修复策略)
│   │   ├── prompts/rcaPrompt.ts      # 根因分析 LLM 提示词模板
│   │   ├── routes/                   # 47 个路由模块, 每个对应一个服务
│   │   ├── schemas/apiValidation.ts  # Zod 验证 Schema
│   │   ├── services/                 # 50+ 业务服务 (详见"后端服务详解")
│   │   ├── types/
│   │   │   ├── index.ts              # 核心类型: WorkflowNode/Edge, NodeResult, ExecutionContext, ApprovalRequest, RemediationPolicy/Execution 等
│   │   │   └── errors.ts            # ErrorCode 枚举 (15 种) + AppError 接口 + createAppError 工厂
│   │   ├── utils/
│   │   │   ├── env.ts                # 环境变量验证 (EnvConfig 接口), 开发环境自动生成随机 JWT
│   │   │   ├── apiConfig.ts          # API Key 获取链: credentialService → 环境变量 → settings 表
│   │   │   ├── logger.ts             # 结构化日志 (debug/info/warn/error), 支持文件输出, 含 startTimer
│   │   │   ├── retry.ts              # 重试工具
│   │   │   ├── sensitiveMask.ts      # 敏感信息脱敏
│   │   │   └── passwordPolicy.ts     # 密码复杂度策略
│   │   └── websocket/handler.ts      # Socket.io: JWT 认证, task:subscribe/unsubscribe, alert:subscribe, terminal:open/data/resize/close
│   ├── vitest.config.ts              # Vitest: node 环境, src/**/*.test.ts
│   └── .eslintrc.json
├── frontend/
│   ├── src/
│   │   ├── App.tsx                   # 路由入口: lazy + Suspense 代码分割, 45+ 路由, AuthProvider > ToastProvider > ThemeProvider 嵌套
│   │   ├── main.tsx                  # React 挂载点
│   │   ├── components/
│   │   │   ├── layout/Layout.tsx     # 主布局: 侧边栏导航 (分组: 概览/主机/Agent/告警/修复/网络/系统), ChatWidget, 主题切换
│   │   │   ├── ProtectedRoute.tsx    # 路由守卫: 未登录重定向 /login, 检测 password_must_change
│   │   │   ├── WebTerminal.tsx       # xterm.js 终端组件: Socket.io 双向通信, 自动重连
│   │   │   ├── TopologyGraph.tsx     # Cytoscape 拓扑图
│   │   │   └── ...                   # 其他通用组件 (ErrorBoundary, ImpactChain, MarkdownOutput 等)
│   │   ├── contexts/
│   │   │   ├── AuthContext.tsx        # 认证状态: token/user 存 localStorage, login/logout/updateUser
│   │   │   ├── ThemeContext.tsx       # 深色/浅色主题切换, CSS 变量 + Tailwind
│   │   │   └── ToastContext.tsx       # Toast 通知: success/error/warn/info, 自动清除
│   │   ├── hooks/                    # useEscapeKey, useTheme
│   │   ├── lib/
│   │   │   ├── api.ts                # Axios 封装: 自动附加 Bearer Token, 401 自动 refresh (队列化), 失败跳转 /login
│   │   │   ├── date.ts               # 日期工具
│   │   │   └── xss.ts                # XSS 防护 (DOMPurify)
│   │   ├── pages/                    # 45+ 页面组件 (详见"前端页面索引")
│   │   └── test/                     # 前端测试 (components/contexts/lib/pages/utils)
│   ├── vite.config.ts                # 别名 @→src, 代理 /api→:3001 + /socket.io→:3001 (ws:true), 端口 3000
│   ├── tailwind.config.js            # CSS 变量颜色映射, 自定义动画
│   └── vitest.config.ts
├── docker/
│   ├── Dockerfile.backend            # 多阶段: node:20-slim 构建 → node:20-slim 运行 (非 root, appuser)
│   ├── Dockerfile.frontend           # 多阶段: node:20-alpine 构建 → nginx:alpine 运行 (安全头)
│   ├── nginx.conf                    # 安全头 (CSP/X-Frame/X-Content-Type) + SPA try_files + /api 反代 + /socket.io WS 升级 + 静态资源 1y 缓存
│   └── docker-entrypoint-backend.sh  # 确保 /app/data 目录权限, su-exec 切换到 appuser
├── local-dev/                        # 本地开发 Docker (热重载)
│   ├── docker-compose.yml            # 前端 vite dev (:5173) + 后端 tsx watch (:3001) + 数据卷持久化
│   ├── Dockerfile.backend.dev        # tsx watch 模式
│   ├── Dockerfile.frontend.dev       # vite dev 模式
│   └── start-dev.bat / stop-dev.bat
├── .github/workflows/
│   ├── ci.yml                        # push/PR: backend lint → frontend lint → backend test → frontend build → docker build
│   ├── release.yml                   # tag push: 质量门禁 → 构建推送 backend/frontend 镜像 (阿里云 ACR)
│   └── mirror.yml                    # 镜像同步
├── docker-compose.yml                # 生产: backend (:3001, 2CPU/2G) + frontend (:8080→80, 1CPU/512M), 健康检查, 日志限制
├── docker-compose.simple.yml         # 简化版
├── deploy.sh / deploy.ps1            # 一键部署: 从阿里云拉镜像 → 生成 docker-compose.yml + .env → 启动
├── .env.example                      # 环境变量模板
└── package.json                      # 根脚本: dev/build/install:all/docker:* (concurrently)

后端核心架构

请求处理链 (app.ts)

请求 → helmet → traceMiddleware → morgan → cors → bodyParser(50mb)
  → 公开路由 (无需认证):
    /api/auth      → rateLimiter + authRoutes
    /api/webhooks  → webhookIpFilter + rateLimiter + webhookRoutes
    /health        → healthService.checkHealth()
  → authenticateToken (JWT 验证 + 用户缓存 10s)
  → requirePasswordChange (首次登录强制改密)
  → 受保护路由 (每个都挂 rateLimiter):
    /api/agents, /api/workflows, /api/tasks, /api/alerts, ...
  → notFoundHandler → errorHandler

中间件详解

中间件	文件	核心逻辑
authenticateToken	middleware/auth.ts	Bearer Token → jwt.verify → 查 DB (带 10s 缓存) → req.user
requireRole	middleware/auth.ts	检查 req.user.role 是否在允许列表中
requirePasswordChange	middleware/auth.ts	password_must_change=1 时返回 403 + code:PASSWORD_MUST_CHANGE
rateLimiter	middleware/rateLimiter.ts	内存 Map 存储, 按路由配置: login(5/15min), copilot(30/min), webhooks(10/s)
webhookIpFilter	middleware/rateLimiter.ts	IP 白名单过滤, 支持 CIDR
traceMiddleware	middleware/trace.ts	生成 traceId 注入 req
errorHandler	middleware/errorHandler.ts	AppError → {success,code,message,traceId}, 非 operational 错误隐藏详情
commandFilter	middleware/commandFilter.ts	7 类危险命令正则匹配, 按角色 block/warn/allow

数据库层 (models/database.ts)

引擎: better-sqlite3 同步 API, WAL 模式
单例: Proxy 模式, import db from '../models/database' 即可使用
关键 pragma: WAL 模式, busy_timeout=10s, cache_size=128MB, mmap_size=2GB, synchronous=FULL
初始化流程: createDatabaseInstance → runMigrations → migrateOldConfigToAIModels → initializeDefaultData (用户/Agent/工作流/知识/脚本/告警映射/定时任务/修复策略)
定期维护: 每小时检查, 凌晨 3 点执行: 每日 WAL checkpoint, 每周 ANALYZE, 每月 VACUUM

数据库迁移框架

// 1. 新建迁移文件 backend/src/models/migrations/vXXX_描述.ts
export default {
  id: '20240101000XXX',
  version: XXX,
  name: '描述',
  description: '详细说明',
  up: async (db) => { db.exec('CREATE TABLE ...'); },
  down: async (db) => { db.exec('DROP TABLE ...'); }
}

// 2. 在 migrations/index.ts 中 import 并加入 ALL_MIGRATIONS 数组
// 3. 启动时 runMigrations(db) 自动执行待处理的迁移

迁移记录存储在 schema_migrations 表中, 按 version 排序顺序执行。

错误处理体系

// types/errors.ts: 15 种 ErrorCode 枚举
import { createAppError, ErrorCode } from '../types/errors';

// 在路由/服务中抛出 operational 错误:
throw createAppError(ErrorCode.VALIDATION_ERROR, '参数无效', 400, { field: 'name' });

// errorHandler 中间件自动处理:
// - operational 错误: 返回 message + details
// - 非 operational 错误: 返回通用消息, 开发环境附带 stack

加密体系 (encryptionService.ts)

AES-256-GCM, 密钥存储在 encryption_keys 表
格式: iv:authTag:encryptedData (Base64)
用于: 服务器密码、SSH 私钥、API 密钥等敏感字段

API Key 获取链 (apiConfig.ts)

getApiKey(db, keyName, envName):
  1. credentialService (加密存储) → 2. 环境变量 → 3. settings 表 (明文兼容) → 4. 备用 env

LLM 调用 (llmService.ts)

熔断器模式: CircuitBreaker 类, maxFailures=5, resetTimeout=60s, 半开探测 3 次
模型池: aiModelService 统一管理, 按优先级排序, 主备降级
支持: 豆包 (火山引擎), OpenAI 兼容接口, 本地模型 (Ollama/LM Studio/vLLM)

工作流执行引擎 (workflowExecutor.ts)

executeWorkflow(taskId, workflow, initialInput?, context?):
  1. 解析 nodes/edges → 拓扑排序得到 executionOrder
  2. 依次执行每个节点:
     - Agent 节点 → executeAgentNode() → 按 agentName 分发
     - 审批节点 → 创建 ApprovalRequest, 暂停执行, 持久化上下文到 tasks.context
  3. WebSocket 推送进度 (task:node:output)
  4. 审批通过后 resumeWorkflow() 从持久化状态恢复执行
  5. 最大执行深度 50, 防止死循环

Agent 执行 (agentExecutor.ts)

按 Agent 名称匹配分发:

服务器命令执行 → executeServerCommandAgent (SSH 连接所有服务器执行)
系统巡检/自动巡检 → executeAutoInspectionAgent (采集 CPU/内存/磁盘)
数据库运维 → executeDatabaseAdminAgent (dbskiter 执行数据库诊断)
其他 → executeAgentWithLLM (通用 LLM 调用, 5 分钟超时)

WebSocket 事件 (websocket/handler.ts)

事件	方向	说明
task:subscribe	C→S	订阅任务进度 (加入 room)
task:unsubscribe	C→S	取消订阅
alert:subscribe	C→S	订阅告警推送
terminal:open	C→S	创建 SSH 终端会话 (callback 返回 sessionId)
terminal:data	双向	终端 I/O 数据
terminal:resize	C→S	调整终端窗口大小
terminal:close	C→S	关闭终端会话

工具函数: emitToTask(io, taskId, event, data), emitToAlerts(io, event, data), broadcast(io, event, data)

后端服务速查表

服务	文件	职责
workflowExecutor	services/workflowExecutor.ts	工作流执行: 拓扑排序, 节点执行, 审批暂停/恢复
agentExecutor	services/agentExecutor.ts	Agent 节点执行: 按名称分发到 SSH/巡检/DB/LLM
llmService	services/llmService.ts	LLM 调用: 熔断器 + 重试 + 模型池降级
aiModelService	services/aiModelService.ts	AI 模型池管理: CRUD, 连通性测试, 优先级排序, 旧配置迁移
sshService	services/sshService.ts	SSH 连接池: 并发复用, 健康检查, 命令执行
terminalService	services/terminalService.ts	Web 终端: 会话管理 (30min TTL, 100 上限)
alertService	services/alertService.ts	告警 CRUD + 状态机 (new→acknowledged→resolved) + 通知触发
alertNoiseReductionService	services/alertNoiseReductionService.ts	告警降噪: 去重 + 抑制
alertCorrelationService	services/alertCorrelationService.ts	告警关联: 时间窗口内聚合
alertAutoAnalyzer	services/alertAutoAnalyzer.ts	AI 告警诊断: 定时轮询待处理告警
rootCauseAnalysisService	services/rootCauseAnalysisService.ts	AI 根因分析
remediationService	services/remediationService.ts	自动修复: 告警→策略匹配→工作流执行→验证→回滚
aiRemediationService	services/aiRemediationService.ts	AI 生成修复命令
notificationService	services/notificationService.ts	多渠道通知: WebSocket + 企业微信 + 钉钉 + 邮件
copilotService	services/copilotService.ts	AI Copilot: 规则快速响应 + LLM 深度分析, 注入系统状态
enhancedRAGService	services/enhancedRAGService.ts	RAG: 关键词匹配 + 语义评分 + 频率权重 + 时间衰减
schedulerService	services/schedulerService.ts	定时任务: node-schedule, 4 个预设 (健康检查/合规/日志/备份)
backupService	services/backupService.ts	备份恢复: gzip 压缩, 完整性校验, 恢复后优雅重启
encryptionService	services/encryptionService.ts	AES-256-GCM 加密/解密, 密钥轮换
credentialService	services/credentialService.ts	加密凭证存储, 旧明文迁移
queueService	services/queueService.ts	异步队列: 内存模式, 优先级 + 重试 + 超时
networkDeviceService	services/networkDeviceService.ts	网络设备 CRUD
networkInspectionService	services/networkInspectionService.ts	网络设备巡检
networkCommandGenerator	services/networkCommandGenerator.ts	多厂商命令生成 (华为/华三/思科/锐捷)
vendorAdapter	services/vendorAdapter.ts	厂商适配器
snmpService	services/snmpService.ts	SNMP 基础操作
snmpPollingService	services/snmpPollingService.ts	SNMP 定期轮询
snmpTrapService	services/snmpTrapService.ts	SNMP Trap 接收
networkDiscoveryService	services/networkDiscoveryService.ts	网络发现
lldpDiscoveryService	services/lldpDiscoveryService.ts	LLDP 邻居发现
topologyService	services/topologyService.ts	拓扑图数据
vncProxyService	services/vncProxyService.ts	VNC WebSocket 代理
healthService	services/healthService.ts	健康检查
selfMonitorService	services/selfMonitorService.ts	自监控: 定期自检 + 告警历史
auditService	services/auditService.ts	审计日志
importExportService	services/importExportService.ts	CSV/JSON 导入导出
changeService	services/changeService.ts	变更管理
reportService	services/reportService.ts	报告生成 (PDFKit)
tokenBlacklist	services/tokenBlacklist.ts	Token 黑名单 (登出失效)
loginThrottler	services/loginThrottler.ts	登录限流 (5 次失败锁定 30min)
restartService	services/restartService.ts	优雅重启

前端核心架构

应用结构 (App.tsx)

ErrorBoundary
  └─ ThemeProvider (深色/浅色)
      └─ AuthProvider (JWT 认证)
          └─ ToastProvider (通知)
              └─ QueryClientProvider (React Query, refetchOnWindowFocus:false, retry:1)
                  └─ BrowserRouter
                      └─ Routes:
                          /login → Login
                          /force-password-change → ProtectedRoute > ForcePasswordChange
                          / → ProtectedRoute > Layout > (所有业务页面)
                          /* → NotFound

所有页面使用 lazy(() => import(...)) + Suspense 代码分割, 加载时显示 PageLoader (旋转动画)。

API 调用模式 (lib/api.ts)

// 统一 Axios 实例, baseURL 为空 (同源), timeout 120s
// 请求拦截: 自动附加 Authorization: Bearer <token>
// 响应拦截: 401 时自动 refresh
//   - 使用 refreshApi (独立实例, timeout 30s) 调用 /api/auth/refresh
//   - 并发请求队列化 (failedQueue), 刷新成功后重放
//   - 刷新失败 → 清除 localStorage → 跳转 /login

状态管理

方式	用途	示例
React Query	服务端状态缓存	页面数据获取, 自动重试, 后台刷新
Context API	全局 UI 状态	AuthContext (token/user), ThemeContext, ToastContext
localStorage	持久化	token, refreshToken, user, 主题偏好
Zustand	组件状态	部分页面使用

前端页面索引

路由	组件	功能
/dashboard	Dashboard	概览: 服务器统计, Agent 列表, 告警, 任务
/big-screen	BigScreenDashboard	大屏仪表盘
/servers	Servers	服务器管理: CRUD, 分组, 批量导入, SSH 连接, 信息采集, 合规检查
/ssh-keys	SSHKeys	SSH 密钥管理
/db-connections	DbConnections	数据库连接管理
/network-devices	NetworkDevices	网络设备管理
/agents	Agents	Agent 管理: 9 预设 + 自定义
/workflows	Workflows	工作流列表
/workflows/:id	WorkflowEditor	工作流编辑器: @xyflow/react 拖拽, Agent 节点 + 审批节点
/tasks	Tasks	任务列表与进度
/alerts	Alerts	告警中心
/alert-mappings	AlertMappings	告警映射规则
/alert-noise	AlertNoiseManagement	告警降噪
/alert-auto-analysis	AlertAutoAnalysis	AI 告警自动分析
/alert-correlation-groups	AlertCorrelationGroups	告警关联组
/root-cause-analysis	RootCauseAnalysis	根因分析列表
/ai-root-cause	AIRootCause	AI 根因分析
/ai-root-cause/:id	RCADetail	根因分析详情
/knowledge	Knowledge	知识库管理
/scripts	Scripts	脚本管理
/scheduled-tasks	ScheduledTasks	定时任务
/terminal	TerminalPage	Web SSH 终端
/remote-desktop	RemoteDesktop	VNC 远程桌面
/remediation-policies	RemediationPolicies	修复策略列表
/remediation-policies/:id	RemediationPolicyEditor	修复策略编辑
/remediation-executions	RemediationExecutions	修复执行记录
/remediation-dashboard	RemediationDashboard	修复仪表盘
/remediation-workbench	RemediationWorkbench	修复工作台
/ai-remediations	AiRemediations	AI 修复管理
/ai-insights	AIInsights	AI 洞察
/topology	Topology	网络拓扑图
/snmp	SNMP	SNMP 管理
/network-discovery	NetworkDiscovery	网络发现
/approvals	Approvals	审批中心
/reports	Reports	报告管理
/audit	AuditLogs	审计日志
/notifications	Notifications	通知管理
/users	Users	用户管理
/settings	Settings	系统设置: AI 模型, 知识库, 通知, 数据库, 安全

侧边栏导航分组 (Layout.tsx)

导航按功能分组: 概览 (仪表盘/大屏), 主机管理 (服务器/SSH密钥/DB连接), Agent (Agent/工作流/任务), 告警中心 (告警/映射/降噪/自动分析/关联组), 智能修复 (策略/执行/仪表盘/工作台/AI修复), 网络 (设备/拓扑/发现/SNMP), 智能分析 (根因/AI根因/AI洞察), 系统 (知识库/脚本/定时任务/终端/远程桌面/审批/报告/审计/通知/用户/设置)。

开发命令

# === 安装 ===
npm run install:all                    # 安装根+后端+前端依赖

# === 开发 ===
npm run dev                            # 同时启动前后端 (concurrently)
cd backend && npm run dev              # 后端: tsx watch src/app.ts → :3001
cd frontend && npm run dev             # 前端: vite → :3000 (代理 /api→:3001, /socket.io→:3001)

# === Docker 本地开发 (热重载, 推荐) ===
cd local-dev && ./start-dev.bat        # Windows: 前端 :5173 + 后端 :3001
cd local-dev && ./start-dev.sh         # Linux/Mac

# === 构建 ===
npm run build                          # 构建全部
npm run build:backend                  # 后端: tsc
npm run build:frontend                 # 前端: tsc && vite build

# === 代码检查 ===
cd backend && npm run lint             # ESLint
cd frontend && npm run lint            # ESLint
cd backend && npx tsc --noEmit         # 类型检查
cd frontend && npx tsc --noEmit        # 类型检查

# === 测试 ===
cd backend && npm test                 # Vitest run
cd backend && npm run test:coverage    # Vitest + v8 coverage
cd frontend && npm test                # Vitest run

# === Docker 部署 ===
docker compose up -d                   # 生产部署
docker compose down                    # 停止
docker compose logs -f backend         # 查看后端日志

环境变量 (.env.example)

变量	默认值	说明
NODE_ENV	development	运行环境
PORT	3001	后端端口
DATABASE_PATH	./data/app.db	SQLite 文件路径
JWT_SECRET	(开发自动生成)	生产必须设置, `openssl rand -hex 32`
JWT_EXPIRES_IN	24h	Token 有效期
ADMIN_INITIAL_PASSWORD	admin	首次部署管理员密码
DOUBAO_API_KEY	-	豆包 API 密钥
OPENAI_API_KEY	-	OpenAI API 密钥
LOCAL_AI_API_BASE	-	本地模型地址 (Ollama: http://localhost:11434/v1)
WEBHOOK_VERIFY_ENABLED	false	Webhook 签名验证
ALLOWED_ORIGINS	http://localhost:3000	CORS 允许源 (逗号分隔)

AI 模型配置也可在 Web 页面 "设置 → AI 配置" 中设置, 保存到数据库加密存储。

部署架构

浏览器 → Nginx (:8080)
           ├── / → 前端静态文件 (SPA try_files, 1y 缓存)
           ├── /api → proxy_pass backend:3001 (60s 连接, 300s 读取)
           └── /socket.io → proxy_pass backend:3001 (WS 升级, 3600s 超时)

backend (:3001) → SQLite (WAL) + LLM API + SSH + Webhook

Docker Compose 生产配置:

backend: 2 CPU / 2G 内存, 健康检查 (/health, 30s), 日志 10m×5
frontend: 1 CPU / 512M, 健康检查 (wget :80, 30s), 日志 5m×3
数据卷: app-data (SQLite), app-backups

开发新功能指南

添加后端 API

创建服务: backend/src/services/myService.ts
创建路由: backend/src/routes/myRoutes.ts
注册路由: 在 app.ts 中 import myRoutes + app.use('/api/my-endpoint', rateLimiter, myRoutes)
如需新表: 在 migrations/ 新建 vXXX_*.ts, 在 migrations/index.ts 注册
如需请求体验: 在 schemas/apiValidation.ts 添加 Zod schema
编写测试: backend/src/services/myService.test.ts

添加前端页面

创建页面: frontend/src/pages/MyPage.tsx
添加路由: 在 App.tsx 中 const MyPage = lazy(() => import('./pages/MyPage')) + <Route path="my-page" ...>
添加导航: 在 components/layout/Layout.tsx 侧边栏对应分组中添加菜单项
API 调用: 在页面中使用 import api from '../lib/api' 调用后端

添加数据库迁移

新建 backend/src/models/migrations/vXXX_描述.ts:

import { Migration } from './migrationFramework';

const migration: Migration = {
  id: '20240101000XXX',
  version: XXX,
  name: '描述',
  description: '详细说明',
  up: async (db) => {
    db.exec(`CREATE TABLE IF NOT EXISTS my_table (
      id TEXT PRIMARY KEY,
      name TEXT NOT NULL,
      created_at DATETIME DEFAULT (datetime('now','localtime'))
    )`);
  },
  down: async (db) => {
    db.exec('DROP TABLE IF EXISTS my_table');
  }
};

export default migration;

在 migrations/index.ts 中 import 并加入 ALL_MIGRATIONS 数组

代码规范

TypeScript 严格模式
变量/函数: camelCase, 类/接口: PascalCase, 常量: UPPER_CASE
后端路由 → routes/, 业务逻辑 → services/, 中间件 → middleware/, 工具 → utils/
前端页面 → pages/, 通用组件 → components/, Hooks → hooks/, API → lib/api.ts

Git 提交规范

<type>(<scope>): <subject>

type: feat, fix, docs, style, refactor, test, chore
scope: frontend, backend, docker, deploy, ci, docs
subject: 50 字符以内

示例:

feat(backend): 添加服务器分组管理功能
fix(frontend): 修复工作流编辑器节点拖拽偏移问题
chore(deploy): 优化 Dockerfile 减小镜像体积

安全设计要点

JWT 认证 + Token 黑名单 (登出失效) + 用户缓存 (10s TTL)
首次登录强制改密, 密码复杂度 (8位+大小写+数字+特殊字符)
登录限流: 5 次失败锁定 30 分钟 (loginThrottler.ts)
AES-256-GCM 加密敏感数据, 密钥存储在 encryption_keys 表
API Key 三级获取: 加密凭证 → 环境变量 → settings 表
SSH 命令安全检查: 7 类危险命令策略, 按角色拦截/警告
Webhook IP 白名单 + HMAC-SHA256 签名验证
CORS 白名单 + 请求速率限制 (按路由差异化配置)
Nginx 安全头: CSP, X-Frame-Options, X-Content-Type-Options
Docker 非 root 运行 (appuser)
审计日志记录所有关键操作

重要文档索引

文档	路径
架构设计	docs/ARCHITECTURE.md
架构图	docs/ARCHITECTURE_DIAGRAM.md
API 文档	docs/API.md
开发指南	docs/DEVELOPMENT.md
部署手册	docs/DEPLOYMENT.md
测试指南	docs/TEST_GUIDE.md
工作流指南	docs/WORKFLOW_GUIDE.md
Web 终端	docs/WEB_TERMINAL.md
自动修复设计	docs/AUTO_REMEDIATION_DESIGN.md
HITL 审批设计	docs/HITL_APPROVAL_DESIGN.md
AI 模型管理	docs/AI_MODEL_POOL_DEVELOPMENT.md
网络设备巡检	docs/NETWORK_DEVICE_INSPECTION.md
技术规范	docs/SPEC.md
贡献指南	CONTRIBUTING.md

ITOps Agent Platform 开发助手

Resources

Install

ITOps Agent Platform 开发助手

项目概述

技术栈

目录结构

后端核心架构

请求处理链 (app.ts)

中间件详解

数据库层 (models/database.ts)

数据库迁移框架

错误处理体系

加密体系 (encryptionService.ts)

API Key 获取链 (apiConfig.ts)

LLM 调用 (llmService.ts)

工作流执行引擎 (workflowExecutor.ts)

Agent 执行 (agentExecutor.ts)

WebSocket 事件 (websocket/handler.ts)

后端服务速查表

前端核心架构

应用结构 (App.tsx)

API 调用模式 (lib/api.ts)

状态管理

前端页面索引

侧边栏导航分组 (Layout.tsx)

开发命令

环境变量 (.env.example)

部署架构

开发新功能指南

添加后端 API

添加前端页面

添加数据库迁移

代码规范

Git 提交规范

安全设计要点

重要文档索引

Categories

Install

Recommended Skills