Merge pull request #101 from zhytao/feat/cmdb-itop-sync

feat(cmdb): add iTop CMDB bidirectional sync module

Author: qinshihu

.gitignore

@@ -196,3 +196,4 @@ backend/backups/
 # 十八、Lint 输出转储（Lint output dumps）
 # =============================================================================
 eslint.txt
+.zcode/

backend/src/models/migrations/index.ts

@@ -116,6 +116,8 @@ import v058DcConstraints from './v058_dc_constraints';
 import v059DcPolymorphicFk from './v059_dc_polymorphic_fk';
 // === agent_executions 归档 v060 ===
 import v060AgentExecutionsArchive from './v060_agent_executions_archive';
+// === CMDB 同步表 v061 ===
+import v061CmdbSyncTables from './v061_cmdb_sync_tables';
 
 // Helper: wrap sync up/down into async
 function wrapAsync(fn: (db: any) => void): (db: any) => Promise<void> {
@@ -370,6 +372,8 @@ export const ALL_MIGRATIONS: Migration[] = [
   v059DcPolymorphicFk,
   // v060: agent_executions 归档表 + 复合索引
   v060AgentExecutionsArchive,
+  // v061: CMDB 同步状态与日志表
+  v061CmdbSyncTables,
 ];
 
 export function createMigrationManager(db: any): MigrationManager {

backend/src/models/migrations/v061_cmdb_sync_tables.ts

@@ -0,0 +1,71 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { Migration } from './migrationFramework';
+import { logger } from '../../utils/logger';
+
+/**
+ * Migration v061 — CMDB 同步状态与日志表
+ *
+ * 为 iTop CMDB 双向同步模块提供持久化支持：
+ *   - cmdb_sync_state: 记录每个 CI 类型的同步状态（最近同步时间、计数、错误）
+ *   - cmdb_sync_log: 每次同步操作的详细日志
+ */
+const v061CmdbSyncTables: Migration = {
+  id: '20250101000061',
+  version: 61,
+  name: 'cmdb_sync_tables',
+  description: 'CMDB sync state and log tables for iTop integration',
+
+  up: async (db: any) => {
+    logger.info('🔄 Creating CMDB sync tables...');
+
+    // 同步状态表 — 每个 CI 类型一行
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS cmdb_sync_state (
+        ci_type TEXT PRIMARY KEY,
+        direction TEXT DEFAULT 'pull',
+        last_sync_at TEXT,
+        last_sync_duration_ms INTEGER,
+        last_count INTEGER DEFAULT 0,
+        last_status TEXT DEFAULT 'pending',
+        last_error TEXT,
+        itop_id_map TEXT DEFAULT '{}',
+        updated_at TEXT DEFAULT (datetime('now','localtime'))
+      );
+    `);
+
+    // 同步日志表 — 每次同步的详细记录
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS cmdb_sync_log (
+        id TEXT PRIMARY KEY,
+        sync_batch_id TEXT NOT NULL,
+        timestamp TEXT DEFAULT (datetime('now','localtime')),
+        direction TEXT NOT NULL,
+        ci_type TEXT NOT NULL,
+        action TEXT NOT NULL,
+        itop_id TEXT,
+        itop_class TEXT,
+        platform_id TEXT,
+        platform_table TEXT,
+        success INTEGER DEFAULT 1,
+        message TEXT,
+        details TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_cmdb_sync_log_batch ON cmdb_sync_log(sync_batch_id);
+      CREATE INDEX IF NOT EXISTS idx_cmdb_sync_log_ci_type ON cmdb_sync_log(ci_type, timestamp DESC);
+      CREATE INDEX IF NOT EXISTS idx_cmdb_sync_log_timestamp ON cmdb_sync_log(timestamp DESC);
+    `);
+
+    logger.info('✅ CMDB sync tables created');
+  },
+
+  down: async (db: any) => {
+    db.exec(`DROP INDEX IF EXISTS idx_cmdb_sync_log_timestamp;`);
+    db.exec(`DROP INDEX IF EXISTS idx_cmdb_sync_log_ci_type;`);
+    db.exec(`DROP INDEX IF EXISTS idx_cmdb_sync_log_batch;`);
+    db.exec(`DROP TABLE IF EXISTS cmdb_sync_log;`);
+    db.exec(`DROP TABLE IF EXISTS cmdb_sync_state;`);
+  },
+};
+
+export default v061CmdbSyncTables;

backend/src/modules/_registry.ts

@@ -24,6 +24,7 @@ import containerRoutes from './containers/routes';
 import databaseRoutes from './database/routes';
 import dcRoutes from './dc/routes';
 import importExportRoutes from './import-export/routes';
+import cmdbSyncRoutes from './cmdb-sync/routes';
 import infraRoutes from './infra/routes';
 import kubernetesRoutes from './kubernetes/routes';
 import linkageRoutes from './linkage/routes';
@@ -66,6 +67,7 @@ const modules: ModuleConfig[] = [
   { path: '/api/v1', router: databaseRoutes },
   { path: '/api/v1', router: dcRoutes },
   { path: '/api/v1', router: importExportRoutes },
+  { path: '/api/v1', router: cmdbSyncRoutes },
   { path: '/api/v1', router: infraRoutes },
   { path: '/api/v1', router: kubernetesRoutes },
   { path: '/api/v1', router: linkageRoutes },

backend/src/modules/cmdb-sync/README.md

@@ -0,0 +1,78 @@
+# CMDB 同步模块 (`cmdb-sync/`)
+
+> **DDD 限界上下文**：与外部 CMDB 系统（当前支持 iTop）的双向资产同步
+> **聚合根**：`CmdbSyncState`、`CmdbSyncLog`
+> **最后刷新**：2026-08-07
+
+## 职责
+
+从 iTop CMDB 拉取配置项（CI）到平台资产表，支持定时同步和手动触发。当前实现 **Pull** 方向，字段映射如下：
+
+| iTop CI 类 | 平台表 | 说明 |
+|------------|--------|------|
+| `Location` | `dc_rooms` | 机房 |
+| `Rack` | `dc_racks` | 机柜（依赖 Location 先同步） |
+| `Server` | `servers` | 服务器（不同步 SSH 凭证，需手动配置） |
+| `DatacenterDevice` | `network_devices` / `dc_pdus` | 按 `finalclass` 分流：pdu/ups→dc_pdus，其余→network_devices |
+
+## 内部结构
+
+```
+cmdb-sync/
+├── routes/
+│   ├── config.ts            ← GET/PUT /cmdb-sync/config, POST /cmdb-sync/config/test
+│   ├── sync.ts              ← POST /cmdb-sync/trigger, GET /cmdb-sync/status, GET /cmdb-sync/logs
+│   └── index.ts             ← 路由聚合
+├── services/
+│   ├── itopClient.ts        ← iTop REST/JSON API 客户端（core/get、core/create、core/update、core/get_related）
+│   ├── itopConfigService.ts ← 配置管理（非密配置→settings 表，密钥→credentials 表）
+│   ├── itopSyncService.ts   ← 同步编排（策略模式 SyncStrategy<T> + db.transaction 保证原子性）
+│   └── cmdbSyncWriter.ts    ← 数据写入层（iTop CI → 平台表 upsert）
+├── routes.ts                # 模块路由入口
+├── index.ts
+└── README.md
+```
+
+## 路由端点（受保护）
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/cmdb-sync/config` | 已登录 | 获取当前配置（token 掩码） |
+| PUT | `/cmdb-sync/config` | admin | 保存配置（Zod 校验） |
+| POST | `/cmdb-sync/config/test` | admin | 测试连接（支持临时配置） |
+| POST | `/cmdb-sync/trigger` | admin/operator | 手动触发一次同步 |
+| GET | `/cmdb-sync/status` | 已登录 | 各 CI 类型的同步状态 |
+| GET | `/cmdb-sync/logs` | 已登录 | 同步日志（支持 ci_type/direction/batch_id/limit 过滤） |
+
+## 配置项
+
+存储在 `settings` 表（非密）和 `credentials` 表（密钥，AES-256-GCM 加密）：
+
+| Key | 存储 | 默认值 | 说明 |
+|-----|------|--------|------|
+| `ITOP_API_BASE` | settings | - | iTop rest.php 完整 URL |
+| `ITOP_AUTH_USER` | settings | `admin` | 认证用户名 |
+| `ITOP_SYNC_ENABLED` | settings | `false` | 是否启用定时同步 |
+| `ITOP_SYNC_INTERVAL_MINUTES` | settings | `30` | 同步间隔（1~1440 分钟） |
+| `ITOP_TIMEOUT_MS` | settings | `30000` | API 超时（毫秒） |
+| `itop` (provider) | credentials | - | iTop 登录密码或 Token（加密） |
+
+## 同步语义
+
+- **依赖顺序**：`Location → Rack → Server → DatacenterDevice`（Rack 需要关联到已同步的 Location）
+- **ID 映射**：`cmdb_sync_state.itop_id_map` 存储 `{ itopId: platformId }` 的 JSON，支持增量同步（已映射的走 UPDATE，未映射的走 INSERT）
+- **事务**：每个 CI 类型的「数据写入 + idMap 更新」在同一个 `db.transaction` 内，失败时整体回滚
+- **幂等**：重复同步不会创建重复记录（依赖 idMap）
+- **冲突处理**：
+  - `dc_racks.room_id` 为 NOT NULL，缺机房时记 error 跳过（不 INSERT null）
+  - `network_devices.ip_address` 为 UNIQUE，冲突时关联到已有设备
+  - `servers.ip_address` 无 UNIQUE 约束，直接写入
+- **日志**：每次同步生成 `batchId`，所有操作写入 `cmdb_sync_log`（保留 30 天）
+
+## 启动时机
+
+由 `serviceRegistry.ts` 在容器初始化时判断 `ITOP_SYNC_ENABLED === 'true'` 决定是否调用 `itopSyncService.startSync()`。启用后启动 10 秒先跑一次，之后按间隔定时执行。
+
+## 前端
+
+设置页 `frontend/src/modules/settings/pages/settings/ITopSyncSettings.tsx`，作为「系统设置」的一个 tab。

backend/src/modules/cmdb-sync/index.ts

@@ -0,0 +1,13 @@
+/**
+ * cmdb-sync 模块入口
+ *
+ * 对接 iTop CMDB，支持：
+ *   - 从 iTop 拉取 Location/Rack/Server/DatacenterDevice 到平台展示
+ *   - 双向同步机房、机柜、服务器、网络设备资产信息
+ *   - 定时同步（可配置间隔）+ 手动触发
+ */
+
+export { default as routes } from './routes';
+export { itopClient } from './services/itopClient';
+export { itopConfigService } from './services/itopConfigService';
+export { itopSyncService } from './services/itopSyncService';

backend/src/modules/cmdb-sync/routes.ts

@@ -0,0 +1,9 @@
+/**
+ * cmdb-sync 模块 — 默认路由导出
+ *
+ * 所有路由受 authenticateToken 保护（在 _registry.ts 中注册）。
+ */
+
+import cmdbSyncRoutes from './routes/index';
+
+export default cmdbSyncRoutes;

backend/src/modules/cmdb-sync/routes/config.ts

@@ -0,0 +1,81 @@
+/**
+ * iTop CMDB 同步 — 配置管理路由
+ * GET    /cmdb-sync/config        获取当前配置
+ * PUT    /cmdb-sync/config        保存配置（admin）
+ * POST   /cmdb-sync/config/test   测试 iTop 连接（admin）
+ */
+
+import { Router, type Request, type Response } from 'express';
+import { z } from 'zod';
+import { requireRole } from '../../../middleware/auth';
+import { validateBody } from '../../../middleware/validation';
+import { getErrorMessage } from '../../../utils/errorHelpers';
+import { logger } from '../../../utils/logger';
+import { itopConfigService } from '../services/itopConfigService';
+
+const router = Router();
+
+// PUT /cmdb-sync/config 入参校验
+const saveConfigSchema = z.object({
+  apiBase: z.string().url('API 地址格式不正确').optional().or(z.literal('')),
+  authUser: z.string().max(64).optional(),
+  authToken: z.string().max(512).optional(),
+  syncEnabled: z.boolean().optional(),
+  syncIntervalMinutes: z.number().int().min(1).max(1440).optional(),
+  timeoutMs: z.number().int().min(1000).max(300000).optional(),
+  sslVerify: z.boolean().optional(),
+});
+
+// POST /cmdb-sync/config/test 入参校验（全部可选，允许用已存配置测试）
+const testConnectionSchema = z.object({
+  apiBase: z.string().optional(),
+  authUser: z.string().optional(),
+  authToken: z.string().optional(),
+  sslVerify: z.boolean().optional(),
+});
+
+// GET /cmdb-sync/config — 获取当前 iTop 配置
+router.get('/config', (_req: Request, res: Response) => {
+  try {
+    const config = itopConfigService.getConfig();
+    res.json({ success: true, data: config });
+  } catch (error) {
+    logger.error('Failed to get iTop config:', error as Error);
+    res.status(500).json({ success: false, message: getErrorMessage(error) });
+  }
+});
+
+// PUT /cmdb-sync/config — 保存 iTop 配置
+router.put(
+  '/config',
+  requireRole('admin'),
+  validateBody(saveConfigSchema),
+  (req: Request, res: Response) => {
+    try {
+      const saved = itopConfigService.saveConfig(req.body);
+      res.json({ success: true, data: saved, message: '配置已保存' });
+    } catch (error) {
+      logger.error('Failed to save iTop config:', error as Error);
+      res.status(500).json({ success: false, message: getErrorMessage(error) });
+    }
+  },
+);
+
+// POST /cmdb-sync/config/test — 测试 iTop 连接
+router.post(
+  '/config/test',
+  requireRole('admin'),
+  validateBody(testConnectionSchema),
+  async (req: Request, res: Response) => {
+    try {
+      // 支持用 body 传入临时配置测试，也支持用已存储配置测试
+      const result = await itopConfigService.testConnection(req.body);
+      res.json({ success: result.success, data: result });
+    } catch (error) {
+      logger.error('Failed to test iTop connection:', error as Error);
+      res.status(500).json({ success: false, message: getErrorMessage(error) });
+    }
+  },
+);
+
+export default router;

backend/src/modules/cmdb-sync/routes/index.ts

@@ -0,0 +1,19 @@
+/**
+ * cmdb-sync 模块路由聚合
+ */
+
+import { Router } from 'express';
+import configRoutes from './config';
+import syncRoutes from './sync';
+
+const router = Router();
+
+router.use('/cmdb-sync', configRoutes);
+router.use('/cmdb-sync', syncRoutes);
+
+// 健康检查
+router.get('/cmdb-sync/health', (_req, res) => {
+  res.json({ success: true, message: 'CMDB sync routes OK' });
+});
+
+export default router;

backend/src/modules/cmdb-sync/routes/sync.ts

@@ -0,0 +1,66 @@
+/**
+ * iTop CMDB 同步 — 同步操作路由
+ * POST   /cmdb-sync/trigger   手动触发一次同步
+ * GET    /cmdb-sync/status    获取各 CI 类型的同步状态
+ * GET    /cmdb-sync/logs      查看同步日志
+ */
+
+import { Router, type Request, type Response } from 'express';
+import { z } from 'zod';
+import { requireRole } from '../../../middleware/auth';
+import { validateQuery } from '../../../middleware/validation';
+import { getErrorMessage } from '../../../utils/errorHelpers';
+import { logger } from '../../../utils/logger';
+import { cmdbSyncStateRepo, cmdbSyncLogRepo } from '../../../repositories';
+import { itopSyncService } from '../services/itopSyncService';
+
+const router = Router();
+
+// POST /cmdb-sync/trigger — 手动触发一次同步
+router.post('/trigger', requireRole('admin', 'operator'), async (_req: Request, res: Response) => {
+  try {
+    // 异步触发，不阻塞请求
+    const result = await itopSyncService.syncAll();
+    res.json({ success: result.success, data: result, message: result.message });
+  } catch (error) {
+    logger.error('CMDB sync trigger failed:', error as Error);
+    res.status(500).json({ success: false, message: getErrorMessage(error) });
+  }
+});
+
+// GET /cmdb-sync/status — 获取同步状态
+router.get('/status', (_req: Request, res: Response) => {
+  try {
+    const states = cmdbSyncStateRepo.listAll();
+    const syncing = itopSyncService.isSyncing();
+    res.json({ success: true, data: { states, syncing } });
+  } catch (error) {
+    logger.error('Failed to get CMDB sync status:', error as Error);
+    res.status(500).json({ success: false, message: getErrorMessage(error) });
+  }
+});
+
+// GET /cmdb-sync/logs — 查看同步日志
+const logsQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(500).optional(),
+  ci_type: z.string().max(64).optional(),
+  direction: z.enum(['pull', 'push']).optional(),
+  batch_id: z.string().max(64).optional(),
+});
+
+router.get('/logs', validateQuery(logsQuerySchema), (req: Request, res: Response) => {
+  try {
+    const limit = req.query.limit ? parseInt(String(req.query.limit), 10) : 50;
+    const ciType = req.query.ci_type as string | undefined;
+    const direction = req.query.direction as string | undefined;
+    const batchId = req.query.batch_id as string | undefined;
+
+    const logs = cmdbSyncLogRepo.list({ ci_type: ciType, direction, batch_id: batchId, limit });
+    res.json({ success: true, data: logs });
+  } catch (error) {
+    logger.error('Failed to get CMDB sync logs:', error as Error);
+    res.status(500).json({ success: false, message: getErrorMessage(error) });
+  }
+});
+
+export default router;