opsxsql/docs/ARCHITECTURE.md

SQL-Platform-Pro 系统架构文档

生成时间: 2026-05-25 | 最新 Commit: 9813741+

1. 系统定位

自助查询 + 数据变更审批流 平台（对标 Yearning / Archery），支持 MySQL / PostgreSQL / Redis / MongoDB 四种数据库类型。

2. 技术栈

|| 层级 | 技术 | 版本 | ||------|------|------| || 后端框架 | FastAPI + SQLAlchemy 2 async | Python 3.11+ | || 数据库 | SQLite (开发) | aiomysql / asyncpg / redis.asyncio / pymongo | || 定时调度 | APScheduler 3.11.2 + SQLite 持久化 | apscheduler.db | || 前端框架 | React 19 + TypeScript | Vite 7 | || UI 组件 | shadcn/ui + Tailwind CSS 4 | Radix UI | || 代码编辑器 | CodeMirror 6 | @codemirror/lang-sql | || 图表 | Recharts | — | || 认证 | JWT (30min) + bcrypt 4.0 | — | || 部署 | Docker + docker-compose | run.sh PID 管理 |

3. 系统架构图

┌─────────────────────────────────────────────────────────────┐
│                     前端 (React + Vite)                       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ Dashboard │ │ Queries  │ │ Tickets  │ │ Instances│       │
│  └─────┬────┘ └─────┬────┘ └─────┬────┘ └─────┬────┘       │
│  ┌──────┴──────┐ ┌────┴─────┐ ┌───┴──────┐ ┌──┴───────┐   │
│  │ SchemaSide  │ │ SqlEditor│ │ Workflow  │ │AutoTask  │   │
│  │ bar(Redis树)│ │ (CM6)    │ │ Page      │ │Page      │   │
│  └─────────────┘ └──────────┘ └──────────┘ └──────────┘   │
│                    ↕ axios /api/v1                           │
├─────────────────────────────────────────────────────────────┤
│                     后端 (FastAPI)                            │
│  ┌────────────────────────────────────────────────────┐     │
│  │              API Layer (29+ endpoints)               │     │
│  │  auth | user | instance | ticket | query | audit    │     │
│  │  audit_rule | notification | workflow | settings    │     │
│  │  ticket_scheduler | log_cleanup                    │     │
│  └──────────────────────┬─────────────────────────────┘     │
│  ┌──────────────────────┴─────────────────────────────┐     │
│  │            Service Layer (33+ services)              │     │
│  │  query_service | audit_engine | ticket_executor     │     │
│  │  instance_service | notification_sender             │     │
│  │  approval_timeout | role_permissions                │     │
│  │  ticket_scheduler | log_cleanup | settings_seeds    │     │
│  └──────────────────────┬─────────────────────────────┘     │
│  ┌──────────────────────┴─────────────────────────────┐     │
│  │            Scheduler Layer (APScheduler)             │     │
│  │  定时工单执行 | 日志自动清理 (cron 03:00)             │     │
│  └──────────────────────┬─────────────────────────────┘     │
│  ┌──────────────────────┴─────────────────────────────┐     │
│  │            Connector Layer                          │     │
│  │  db_connector(MySQL/PG/SQLite)                     │     │
│  │  redis_connector | mongo_connector                  │     │
│  └──────────────────────┬─────────────────────────────┘     │
│  ┌──────────────────────┴─────────────────────────────┐     │
│  │  SQLite(metadata) | apscheduler.db | MySQL | PostgreSQL | Redis | MongoDB│
│  └────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘

4. 核心模块架构

4.1 权限体系（三层模型）

Tier 1: 实例可见性 (check_instance_access)
  → admin 看全部, 其他角色按权限组过滤
  → /instances/accessible?access_type=readonly|write

Tier 2: 操作权限 (check_instance_permission)
  → 7 个 action: query:select, query:export, ticket:create, ticket:approve,
    ticket:execute, ddl:execute, instance:manage
  → 用户级覆盖 > 组默认权限

Tier 3: 角色权限 (role_permissions.py)
  → admin: 全部权限
  → dba: 全部库 + 审批+拒绝+执行
  → auditor: 全部只读 + 审批+拒绝
  → developer: 按权限组 + 创建+撤销(未执行前)

4.2 审批流引擎

工单创建 → 查找默认审批流 → 创建 TicketApproval 记录
  ├─ 标准步骤 (step_type='standard')  → 单人审批
  ├─ 会签 (step_type='parallel')      → 所有人都通过
  ├─ 或签 (step_type='any_one')       → 一人通过即可
  └─ 条件 (step_type='condition')     → 按 SQL 类型/风险等级判断

审批推进:
  approve → 检查后续步骤
    ├─ 还有 pending 步骤 → status='reviewing'
    └─ 全部完成 → status='approved'
  reject → 拒绝所有剩余步骤 → status='rejected'

超时检查:
  POST /tickets/check-timeout → timeout_hours + auto_approve_on_timeout

4.3 SQL 审核引擎

输入 SQL → audit_engine.py
  ├─ sql_analyzer.py (AST 分析)
  │   ├─ SQL 类型识别 (DDL/DML/DQL/DCL)
  │   ├─ 风险等级评估 (5级)
  │   └─ 只读验证
  ├─ rule_templates.py (127 条规则)
  │   ├─ MySQL: 67 条 (含安全9条 SEC-001~009)
  │   ├─ PostgreSQL: 31 条
  │   ├─ Redis: 25 条 (去重优化后)
  │   └─ MongoDB: 31 条
  └─ 输出 AuditReport (score + violations)

4.4 多数据库查询路由

query_service.py → 按 instance.db_type 分发:
  ├─ mysql    → aiomysql (SELECT only, auto LIMIT)
  ├─ postgres → asyncpg
  ├─ redis    → redis.asyncio (GET/HGETALL/LRANGE/SMEMBERS/ZRANGE/KEYS)
  └─ mongodb  → pymongo (find/aggregate/count)

4.5 工单执行引擎

ticket_executor.py → 按 instance.db_type 执行:
  ├─ mysql    → aiomysql.execute() + affected_rows
  ├─ postgres → asyncpg.execute()
  ├─ redis    → redis.asyncio (SET/HSET/LPUSH/SADD/ZADD/DEL)
  └─ mongodb  → pymongo (insert/update/delete)
  → ExecutionReport (status/affected_rows/duration/warnings/errors)

4.6 定时调度器 (APScheduler)

ticket_scheduler.py:
  ├─ APScheduler BackgroundScheduler + SQLite 持久化 (apscheduler.db)
  ├─ 工单 scheduled_at 到期 → 自动触发执行
  ├─ 状态流转: approved → scheduled → executing → success/failed
  ├─ 支持取消定时: POST /tickets/{id}/cancel-schedule
  └─ 统计接口: GET /tickets/scheduled/stats

log_cleanup.py:
  ├─ APScheduler cron job → 每天 03:00 自动执行
  ├─ 读取 cleanup 分组配置 (6 项)
  ├─ 按保留天数清理:
  │   ├─ 工单 (只清理已完成/已拒绝, 0天=不清理)
  │   ├─ 审计日志
  │   ├─ 查询历史
  │   └─ 定时任务日志
  ├─ 手动触发: POST /settings/cleanup/run
  └─ 预览: GET /settings/cleanup/preview

4.7 系统设置种子机制

settings_seeds.py:
  ├─ SETTING_GROUPS: 分组元信息 (query_control / security / ticket / cleanup)
  ├─ _ensure_settings(): 启动时自动补缺失配置项
  ├─ SETTING_DEFINITIONS: 所有设置项定义 (key/value_type/default/group/label)
  └─ 新增 cleanup 分组 (6 项):
      ├─ cleanup_enabled (bool, false)
      ├─ cleanup_time (str, "03:00")
      ├─ cleanup_ticket_days (int, 90)
      ├─ cleanup_audit_days (int, 180)
      ├─ cleanup_query_history_days (int, 30)
      └─ cleanup_task_log_days (int, 30)

5. 数据模型

5.1 核心 ORM 模型 (22 个)

模型	说明	主要字段
User	用户	username, password_hash, role, display_name
Instance	数据源实例	name, host, port, db_type, access_mode, group_id
InstanceGroup	权限组	name, description, access_type, workflow_id
	Ticket	工单
TicketApproval	审批记录	ticket_id, step_number, approver_id, action, step_type
AuditLog	审计日志	user_id, action, resource_type, resource_id
AuditRule	审核规则	name, code, db_type, rule_type, severity
WorkflowDefinition	审批流定义	name, is_default, is_active
WorkflowStep	审批流步骤	workflow_id, step_number, step_type, timeout_hours
NotificationConfig	通知渠道	channel_type(webhook_url), channel_name
Announcement	公告	title, content(Markdown)
SystemSetting	系统配置	key, value, value_type, group
SlowLog	慢查询日志	instance_id, query_text, duration
QueryHistory	查询历史	user_id, sql_text, instance_id
SchemaSnapshot	Schema 快照	instance_id, database, snapshot_data
SchemaDrift	Schema 漂移	snapshot_id, drift_type, details
ScheduledTask	定时任务	name, task_sql_type, cron_expression
LdapConfig	LDAP 配置	server_url, bind_dn, base_dn
DataDictionary	数据字典	instance_id, database, table_name
DictionaryField	字典字段	dictionary_id, column_name, description

5.2 关联表

表	说明
user_groups	用户-权限组关联 (user_id, group_id, permissions)
instance_group_members	权限组-实例关联 (group_id, instance_id, access_type)
workflow_execution_log	审批流执行日志

6. 前端页面架构

6.1 页面清单 (26 个)

页面	路由	说明	行数
LoginPage	/login	登录	~180
Dashboard	/	首页仪表盘	~350
QueriesPage	/queries	自助查询	~780
TicketsPage	/tickets	工单列表	~1100
TicketCreatePage	/tickets/create	新建工单	~1000
InstancePage	/instances	数据源管理	~700
InstanceDetailPage	/instances/:id	实例详情(6 tab)	~600
RedisDetailPage	/redis/:id	Redis 详情(4 tab)	~500
MongoDBDetailPage	/mongodb/:id	MongoDB 详情	~400
UsersPage	/users	用户管理	~500
AuditLogsPage	/audit-logs	审计日志	~400
AuditRulesPage	/audit-rules	审核规则(6 组)	~600
SettingsPage	/settings	系统设置(多 tab)	~400
AnnouncementPage	/settings/announcements	公告管理	~300
NotificationPage	/settings/notifications	通知渠道	~350
InstanceGroupPage	/permissions	权限管理(Transfer 穿梭框)	~800
WorkflowPage	/workflows	审批流管理	~600
PlatformConfigPage	/settings/platform	平台配置	~350
DataDictionaryPage	/dictionary	数据字典	~300
SlowQueryPage	/slow-query	慢查询分析	~400
SchemaDriftPage	/schema-drift	Schema 漂移	~300

6.2 共享组件 (9 个)

组件	说明
Layout	侧边栏 + Header 布局
SqlEditor	CodeMirror 6 编辑器 (SQL/Redis/Mongo 语法)
SchemaSidebar	数据库导航树 (MySQL三级/Redis目录树/MongoDB集合)
PageHeader	页面标题 + 操作按钮 (权限控制)
EmptyState	空状态占位
ConfirmDialog	确认弹框 (useConfirm hook)
FormDialog	表单弹框壳
EditInstanceDialog	实例编辑弹框 (复用)
ui/*	shadcn/ui 基础组件 (Button, Dialog, Input, Select...)

6.3 SchemaSidebar Redis 树特性

Redis Keys 目录树:
  ├─ 按 ':' 分隔构建层级 (如 cache:homepage:banner)
  ├─ 文件夹节点: FolderOpen 琥珀色图标 + 子节点数
  ├─ 叶子节点: KeyRound 图标按类型着色
  │   ├─ string → emerald (绿)
  │   ├─ hash   → blue (蓝)
  │   ├─ list   → purple (紫)
  │   ├─ set    → orange (橙)
  │   └─ zset   → rose (红)
  ├─ 单列内嵌详情: 选中 key 下方展开 type/TTL/value
  ├─ border-l 左竖线层级指示
  ├─ 查询页: 点击 → 插入对应命令到编辑器
  │   (GET/HGETALL/LRANGE/SMEMBERS/ZRANGE)
  └─ 变更页: 同上 + hover 显示「插入」提示

7. 通知系统

通知渠道: DingTalk / Feishu / Email(SMTP)
通知模板:
  ├─ 工单创建通知 (申请人→审批人)
  ├─ 工单审批通过通知
  ├─ 工单审批拒绝通知
  └─ 工单执行完成通知

飞书: \n 换行
钉钉: \n\n 双换行 (markdown 特性)

8. 系统配置

18 项配置分 4 组：

查询控制 (7 项):

• query_require_approval (bool) - 查询是否需要审批
• query_max_limit (int, 10000) - 最大返回行数
• query_timeout (int, 30s) - 查询超时
• query_max_length (int, 10000) - SQL 最大长度
• query_auto_limit (bool) - 自动添加 LIMIT
• query_enable_masking (bool) - 数据脱敏
• query_save_history (bool) - 保存查询历史

安全配置 (3 项):

• security_max_login_attempts (int, 5) - 最大登录尝试
• security_password_min_length (int, 6) - 密码最小长度
• security_enable_audit_log (bool) - 审计日志开关

工单配置 (2 项):

• ticket_default_workflow (string, "standard") - 默认审批流
• ticket_allow_rollback (bool) - 允许回滚

清理配置 (6 项) 🆕:

• cleanup_enabled (bool, false) - 启用自动清理
• cleanup_time (string, "03:00") - 清理执行时间
• cleanup_ticket_days (int, 90) - 工单保留天数 (0=不清理)
• cleanup_audit_days (int, 180) - 审计日志保留天数
• cleanup_query_history_days (int, 30) - 查询历史保留天数
• cleanup_task_log_days (int, 30) - 定时任务日志保留天数

9. 四角色体系

角色	权限范围
admin (超级管理员)	全部功能 + 用户管理 + 系统设置
dba (DBA管理员)	全部库访问 + 审批/拒绝/执行工单
auditor (审计员)	全部只读 + 审批/拒绝工单
developer (开发者)	按权限组访问 + 创建/撤销自己的工单

默认用户: admin/admin123, zhangsan(张三)/admin123, laoliu(老六)/admin123, lurenjia(路人甲)/admin123

10. 运维部署

# 开发环境启动
bash run.sh start      # 启动前后端 (后端9000, 前端5173)
bash run.sh restart    # 重启
bash run.sh stop       # 停止
bash run.sh status     # 状态检查

# 测试
bash run.sh test       # 后端测试 (pytest)
cd frontend && npx tsc --noEmit  # 前端类型检查

# 生产构建
bash run.sh build      # Docker build
docker-compose up -d   # 部署

11. 关键设计决策

|| 决策 | 原因 | ||------|------| || SQLite 开发数据库 | 零配置，单文件，便于版本管理 | || AES-256-GCM 加密实例密码 | 安全存储，向后兼容明文 | || JWT 30分钟过期 | 安全与便利平衡 | || 暗色主题 CSS 变量体系 (--dg-) | 统一视觉风格 | || CodeMirror 6 | 现代化编辑器，SQL 自动补全 | || 权限组中间表设计 | 一组同时包含只读+写入实例 | || React.lazy 代码分割 | 首屏 -44% (2676KB→1438KB) | || 工单编号 20 位 | 时间戳+微秒+序号，全局唯一 | || APScheduler + SQLite 持久化 | 定时任务跨重启不丢失，轻量级方案 | || 设置种子数据机制 | _ensure_settings 启动自动补全，保证配置完整性 | || 工单创建页单页化 | 简化三步向导为一键提交，提升操作效率 |