rlwj-lab/opsxsql
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0995abce08ad30f21a73de433323bd1fa9aabf4f
opsxsql/docs/ARCHITECTURE.md
T
logan 0995abce08 feat: 查询页面重构 — 去掉新建查询按钮, 默认直接显示编辑器 + 右侧历史抽屉 
1. QueriesPage 重构:
   - 去掉两段式切换（历史列表→新建查询面板）
   - 默认直接显示 SQL 编辑器，无需点'新建查询'
   - 实例+数据库选择器紧凑排列在顶栏
   - 执行按钮移到顶栏右侧，操作更便捷
   - 查询历史改为右侧可折叠抽屉（点击'历史'按钮展开）
   - 全高布局 h-[calc(100vh-3rem)]，编辑区和结果区更宽敞
   - Schema 导航侧边栏、快捷模板、CSV导出等保留

2. 文档更新:
   - FEATURES.md: 补充定时执行、SQL检测、日志清理、系统设置种子机制
   - ARCHITECTURE.md: 补充 APScheduler+SQLite 持久化调度、日志清理服务、Settings Seeds
   - ROADMAP.md: 标记已完成功能，更新P1-P3进度
   - AUDIT_REPORT.md: 更新服务/文件/测试数量统计
2026-05-25 00:35:57 +08:00

365 lines
17 KiB
Markdown
Raw Blame History

# 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 | 工单 | ticket_no, title, db_type, status, sql_content, audit_result, **scheduled_at** |
| 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
# 开发环境启动
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` 启动自动补全，保证配置完整性 |
|| 工单创建页单页化 | 简化三步向导为一键提交，提升操作效率 |
Reference in new issue View Git Blame Copy Permalink