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

---

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

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

添加前端页面

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

添加数据库迁移

1. 新建 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;

2. 在 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 |