# SQL-Platform 系统架构文档

> 更新时间: 2026-05-26 | 版本: v0.3.1 | 后端: Go/Gin | Commit: f2e93a0

## 1. 系统定位

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

## 2. 技术栈

| 层级 | 技术 | 版本 |
|------|------|------|
| 后端语言 | Go | 1.26 |
| 后端框架 | Gin | v1.10.1 |
| ORM | GORM | v1.26.0 |
| 元数据库 | SQLite (GORM AutoMigrate) | gorm.io/driver/sqlite |
| 前端框架 | React 19 + TypeScript | Vite 7 |
| UI 组件 | shadcn/ui + Tailwind CSS 4 | Radix UI |
| 代码编辑器 | CodeMirror 6 | @codemirror/lang-sql |
| 图表 | Recharts | — |
| 认证 | JWT (HS256) + bcrypt (golang.org/x/crypto) | 默认 24h 过期 |
| DB 驱动 | go-sql-driver/mysql / jackc/pgx/v5 / go-redis/v9 / go-mongo-driver/v2 | — |
| LDAP | go-ldap/ldap/v3 | v3.4.13 |
| 部署 | run.sh PID 管理 | Go :9000, Frontend :5173 |

## 3. 系统架构图

```
┌──────────────────────────────────────────────────────────────────┐
│                    前端 (React 19 + Vite 7)                       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│  │ Dashboard │ │ Queries  │ │ Tickets  │ │ Instances│           │
│  └─────┬────┘ └─────┬────┘ └─────┬────┘ └─────┬────┘           │
│  ┌──────┴──────┐ ┌────┴─────┐ ┌───┴──────┐ ┌──┴───────┐       │
│  │ Appearance  │ │ SqlEditor│ │ Workflow  │ │Settings  │       │
│  │ Settings    │ │ (CM6)    │ │ Page      │ │Page      │       │
│  └─────────────┘ └──────────┘ └──────────┘ └──────────┘       │
│  ┌──────────────────────────────────────────────────────┐       │
│  │  Login (5 themes: SplitView/CenteredCard/SidePanel/  │       │
│  │        FullImage/MinimalDark) useLogin hook           │       │
│  └──────────────────────────────────────────────────────┘       │
│                    ↕ axios /api/v1                               │
├──────────────────────────────────────────────────────────────────┤
│                    后端 (Go 1.26 + Gin)                          │
│  ┌────────────────────────────────────────────────────┐         │
│  │            Router (router/router.go)                │         │
│  │  120+ routes: auth/ticket/instance/redis/workflow   │         │
│  └──────────────────────┬─────────────────────────────┘         │
│  ┌──────────────────────┴─────────────────────────────┐         │
│  │       Middleware Stack                               │         │
│  │  CORS → Auth JWT (HS256) → RequireRole (RBAC)       │         │
│  └──────────────────────┬─────────────────────────────┘         │
│  ┌──────────────────────┴─────────────────────────────┐         │
│  │       Handler Layer (internal/handler/)              │         │
│  │  auth | user | instance | instance_detail | redis    │         │
│  │  ticket | workflow | audit_log | notification        │         │
│  │  dashboard | ghost | ldap | scheduled_task | stubs   │         │
│  └──────────────────────┬─────────────────────────────┘         │
│  ┌──────────────────────┴─────────────────────────────┐         │
│  │       Service Layer (internal/service/)              │         │
│  │  auth_service | ticket_service | instance_service    │         │
│  └──────────────────────┬─────────────────────────────┘         │
│  ┌──────────────────────┴─────────────────────────────┐         │
│  │       GORM Model Layer (internal/model/model.go)     │         │
│  │  25+ models · AutoMigrate · SQLite metadata          │         │
│  └──────────────────────┬─────────────────────────────┘         │
│  ┌──────────────────────┴─────────────────────────────┐         │
│  │       Database Drivers (5 types)                     │         │
│  │  go-sql-driver/mysql | jackc/pgx/v5                 │         │
│  │  go-redis/v9 | go-mongo-driver/v2 | gorm/sqlite     │         │
│  └────────────────────────────────────────────────────┘          │
└──────────────────────────────────────────────────────────────────┘
```

## 4. Go 后端项目结构

```
backend/
├── cmd/
│   └── server/
│       └── main.go              # 入口: Gin 初始化、GORM 连接、AutoMigrate、路由注册
├── config/
│   └── config.go                # 配置管理 (PORT/DB_PATH/JWT_SECRET/GH_OST_PATH)
├── internal/
│   ├── handler/                 # API 处理器 (17 个文件)
│   │   ├── auth.go              # 登录、获取当前用户
│   │   ├── user.go              # (stub_handlers) 用户 CRUD、批量导入
│   │   ├── instance.go          # 实例 CRUD、连接测试
│   │   ├── instance_detail.go   # MySQL 详情: databases/tables/schema/processlist/status/users
│   │   ├── instance_extra.go    # 可访问实例、实例统计
│   │   ├── instance_group.go    # 权限组 CRUD、成员管理
│   │   ├── redis.go             # Redis: info/dbsize/keys/slowlog/clients/command
│   │   ├── ticket.go            # 工单: 创建/审批/执行/取消/回滚/时间线
│   │   ├── workflow.go          # 审批流: CRUD/克隆/设置默认
│   │   ├── audit_log.go         # 审计日志查询
│   │   ├── notification.go      # 通知渠道 CRUD + 测试发送
│   │   ├── dashboard.go         # 仪表盘统计
│   │   ├── ldap.go              # LDAP 配置/测试/导入/用户管理
│   │   ├── ghost.go             # gh-ost DDL 变更
│   │   ├── scheduled_task.go    # 定时任务管理
│   │   ├── crypto.go            # AES-256-GCM 加解密
│   │   ├── connection_tester.go # 数据库连接测试
│   │   └── stub_handlers.go     # SQL格式化/分析、数据字典、MongoDB 桩、审核规则、查询执行等
│   ├── model/
│   │   └── model.go             # GORM 模型定义 (25+ 模型)
│   ├── middleware/
│   │   ├── auth.go              # JWT 认证中间件 + RequireRole RBAC
│   │   └── cors.go              # CORS 跨域中间件
│   ├── service/
│   │   ├── auth_service.go      # 认证逻辑 (bcrypt 密码验证、种子用户)
│   │   ├── ticket_service.go    # 工单业务逻辑
│   │   └── instance_service.go  # 实例连接管理
│   └── ghost/
│       └── ghost.go             # gh-ost 集成逻辑
├── router/
│   └── router.go                # Gin 路由注册 (120+ 路由)
└── go.mod                       # 依赖管理 (module: sql-platform)
```

### 4.1 启动流程

```go
// cmd/server/main.go
config.Init()                    // 加载 .env 配置
db = gorm.Open(sqlite.Open(...)) // 连接 SQLite 元数据库
db.AutoMigrate(&model.User{}, …) // 自动迁移 25+ 模型
r = gin.Default()                // 创建 Gin 引擎
r.Use(CORSMiddleware())          // 全局 CORS
router.Setup(r)                  // 注册 120+ API 路由
r.Run(":9000")                   // 启动 HTTP 服务
```

### 4.2 编译与运行

```bash
cd backend && go build -o sql-platform ./cmd/server/   # 编译
bash run.sh restart                                      # Go :9000 + Frontend :5173
```

## 5. GORM 数据模型 (25+)

| 模型 | 表名 | 说明 |
|------|------|------|
| User | users | 用户 (admin/dba/developer/auditor/guest) |
| Instance | instances | 数据源实例 (mysql/postgresql/redis/mongodb) |
| InstanceGroup | instance_groups | 权限组 |
| InstanceGroupMember | instance_group_members | 权限组-实例关联 |
| UserGroup | user_groups | 用户-权限组关联 |
| Ticket | tickets | 工单 (10 种状态) |
| TicketApproval | ticket_approvals | 审批记录 (含转审/超时) |
| TicketSQLItem | ticket_sql_items | 工单 SQL 明细 |
| AuditRule | audit_rules | 审核规则 (127 条/6 组) |
| AuditLog | audit_logs | 审计日志 |
| QueryHistory | query_histories | 查询历史 (500/用户上限) |
| WorkflowDefinition | workflow_definitions | 审批流定义 |
| WorkflowStep | workflow_steps | 审批流步骤 |
| WorkflowVersion | workflow_versions | 审批流版本 |
| WorkflowExecutionLog | workflow_execution_logs | 审批流执行日志 |
| NotificationChannel | notification_channels | 通知渠道 (feishu/dingtalk/wechat/email) |
| NotificationTemplate | notification_templates | 通知模板 |
| Announcement | announcements | 系统公告 |
| SystemSetting | system_settings | 系统配置 |
| OperationLog | operation_logs | 操作日志 |
| LDAPConfig | ldap_config | LDAP 配置 |
| MaskingRule | masking_rules | 数据脱敏规则 |
| Backup | backups | 数据库备份记录 |
| SchemaRevision | schema_revisions | Schema 版本记录 |
| SlowLog | slow_logs | 慢查询日志 |
| ScheduledTask | scheduled_tasks | 定时任务 |
| ScheduledTaskLog | scheduled_task_logs | 定时任务日志 |

## 6. 中间件栈

### 6.1 CORS 中间件 (`middleware/cors.go`)
- 基于 `github.com/gin-contrib/cors`
- 开发环境允许所有来源

### 6.2 JWT 认证中间件 (`middleware/auth.go`)
- 从 `Authorization: Bearer <token>` 提取 JWT
- HS256 签名，密钥从配置加载
- 解析 Claims (user_id, username, role) 注入 Gin Context

### 6.3 RBAC 中间件 (`middleware/auth.go` — RequireRole)
- 按角色限制路由访问
- 实例管理: `RequireRole("admin", "dba")`
- 用户管理: `RequireRole("admin")`
- LDAP 管理: `RequireRole("admin")`
- gh-ost 操作: `RequireRole("admin", "dba")`

## 7. 认证流程

```
客户端 → POST /api/v1/auth/login {username, password}
  ├─ auth.go → auth_service.go
  │   ├─ GORM 查询 User by username
  │   ├─ bcrypt.CompareHashAndPassword 验证密码
  │   └─ GenerateToken(user) → JWT (HS256, 24h)
  ├─ 返回 {access_token, token_type, user}
  └─ 后续请求: Authorization: Bearer <token>
      └─ AuthMiddleware 解析 Claims → 注入 Context (user_id, username, role)
```

## 8. LDAP 集成

```
LDAP 服务器: 8.217.205.92:389
Base DN: dc=opsx,dc=vip
驱动: github.com/go-ldap/ldap/v3

API 端点:
  GET  /ldap-config              — 获取 LDAP 配置
  PUT  /ldap-config              — 更新 LDAP 配置
  POST /ldap-config/test         — 测试 LDAP 连接
  POST /ldap-config/ou-list      — 列出 OU
  POST /ldap-config/user-list    — 列出 LDAP 用户
  POST /ldap-config/create-ou    — 创建 OU
  POST /ldap-config/create-user  — 创建 LDAP 用户
  POST /ldap-config/batch-import-ldap — 批量导入
  POST /ldap-config/delete-user  — 删除 LDAP 用户
```

## 9. 数据库驱动支持矩阵

| 数据库 | Go 驱动 | 查询 | 执行 | 审核 | 详情浏览 |
|--------|---------|------|------|------|----------|
| MySQL | go-sql-driver/mysql v1.10.0 | ✅ | ✅ | ✅ (67规则) | ✅ (7 endpoints) |
| PostgreSQL | jackc/pgx/v5 v5.9.2 | ✅ | ✅ | ✅ (31规则) | ✅ |
| Redis | go-redis/v9 v9.19.0 | ✅ | ✅ | ✅ (25规则) | ✅ (9 handlers) |
| MongoDB | go-mongo-driver/v2 | ✅ (stub) | ✅ (stub) | ✅ (31规则) | ✅ (stub) |
| SQLite | gorm.io/driver/sqlite | ✅ (元数据) | — | — | — |

## 10. MySQL Instance Detail — 7 个端点

| 端点 | 路由 | 说明 |
|------|------|------|
| databases | GET /instances/:id/detail/databases | 数据库列表 |
| tables | GET /instances/:id/detail/tables | 表列表 |
| db-schema | GET /instances/:id/detail/db-schema | 库 Schema |
| table-detail | GET /instances/:id/detail/table-detail | 表详情 (列/索引) |
| processlist | GET /instances/:id/detail/processlist | 进程列表 (含 Kill) |
| status | GET /instances/:id/detail/status | 服务器状态 |
| users | GET /instances/:id/detail/users | 用户列表 |

## 11. Redis — 9 个 Handler

| Handler | 路由 | 说明 |
|---------|------|------|
| RedisInfo | GET /redis/:id/info | 服务器信息 |
| RedisDbsize | GET /redis/:id/dbsize | 数据库大小 |
| RedisScanKeys | GET /redis/:id/keys | Key 扫描 |
| RedisGetKeyDetail | GET /redis/:id/keys/:key | Key 详情 (type/TTL/value) |
| RedisSlowlog | GET /redis/:id/slowlog | 慢查询日志 |
| RedisClients | GET /redis/:id/clients | 客户端列表 |
| RedisExecuteCommand | POST /redis/:id/command | 执行命令 |
| RedisCreateKey | POST /redis/:id/keys | 创建 Key |
| RedisDeleteKey | DELETE /redis/:id/keys/:key | 删除 Key |

## 12. 前端架构

### 12.1 前端页面 (18+)

| 页面 | 路由 | 说明 |
|------|------|------|
| LoginPage | /login | 5 种主题: SplitView/CenteredCard/SidePanel/FullImage/MinimalDark |
| Dashboard | / | 首页仪表盘 |
| QueriesPage | /queries | 自助查询 (CodeMirror 6) |
| TicketsPage | /tickets | 工单列表 |
| TicketCreatePage | /tickets/create | 新建工单 |
| TicketDetailPage | /tickets/:id | 工单详情 |
| InstancePage | /instances | 数据源管理 |
| InstanceDetailPage | /instances/:id | MySQL 实例详情 |
| RedisDetailPage | /redis/:id | Redis 详情 |
| MongoDBDetailPage | /mongodb/:id | MongoDB 详情 |
| UsersPage | /users | 用户管理 |
| AuditLogsPage | /audit-logs | 审计日志 |
| AuditRulesPage | /audit-rules | 审核规则 (6 组) |
| WorkflowPage | /workflows | 审批流管理 |
| SettingsPage | /settings | 系统设置 (多 tab) |
| AppearanceSettings | /settings/appearance | 外观设置 (主题 + 登录页风格) |
| PlatformConfigPage | /settings/platform | 平台配置 |
| NotificationPage | /settings/notifications | 通知渠道管理 |
| AnnouncementPage | /settings/announcements | 公告管理 |
| LdapConfigPage | /settings/ldap | LDAP 配置 |
| InstanceGroupPage | /permissions | 权限管理 |
| AutoTaskPage | /auto-tasks | 定时任务管理 |
| DataDictionaryPage | /dictionary | 数据字典 |
| RolesPage | /roles | 角色管理 |

### 12.2 登录页主题系统 (v0.3.1 新增)

```
components/login/
├── SplitView.tsx       # 经典分屏 — 左侧特性展示 + 右侧表单
├── CenteredCard.tsx    # 居中卡片 — 渐变背景 + 居中表单
├── SidePanel.tsx       # 侧边面板 — 左侧品牌 + 右侧表单
├── FullImage.tsx       # 全屏背景 — 科技背景 + 毛玻璃卡片
└── MinimalDark.tsx     # 极简暗色 — 纯暗色极简风格

hooks/
└── useLogin.tsx        # 共享登录逻辑 (username/password/loading/error)

pages/
├── LoginPage.tsx       # 主题路由器 — 读取 localStorage 'login-style'
└── AppearanceSettings.tsx  # Settings → Appearance tab
                          # 主题切换 (dark/light)
                          # 登录页风格切换 (5 种预览 + 选择)
                          # localStorage key: 'login-style'
```

### 12.3 共享组件

| 组件 | 说明 |
|------|------|
| Layout | 侧边栏 + Header 布局 |
| SqlEditor | CodeMirror 6 编辑器 (SQL/Redis/Mongo 语法) |
| SchemaSidebar | 数据库导航树 (MySQL三级/Redis目录树/MongoDB集合) |
| EditInstanceDialog | 实例编辑弹框 (复用) |
| ConfirmDialog | 确认弹框 (useConfirm hook) |
| FormDialog | 表单弹框壳 |
| ToastContainer | 右下角通知 (3秒消失) |
| ui/* | shadcn/ui 基础组件 |

## 13. 权限体系（四角色模型）

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

**默认种子用户** (auth_service.go 自动创建):
- admin/admin123 → 超级管理员
- zhangsan/admin123 → 张三 (dba)
- laoliu/admin123 → 老六 (auditor)
- lurenjia/admin123 → 路人甲 (developer)

## 14. 运维部署

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

# 后端编译
cd backend && go build -o sql-platform ./cmd/server/

# 健康检查
curl http://localhost:9000/health
# → {"status":"ok","version":"0.3.1","backend":"go"}
```

## 15. 关键设计决策

| 决策 | 原因 |
|------|------|
| Go + Gin 替代 Python/FastAPI | 编译为单二进制，无运行时依赖，性能优异 |
| GORM AutoMigrate | 零配置 schema 管理，启动时自动同步 |
| SQLite 元数据库 | 零配置，单文件，便于开发部署 |
| JWT HS256 (24h) | 安全与便利平衡，配置可调 |
| 中间件分层 (Auth → RequireRole) | 细粒度 RBAC，路由级权限控制 |
| 5 种登录页主题 | 用户体验个性化，localStorage 持久化 |
| React.lazy 代码分割 | 首屏加载优化 |
| go-ldap/ldap/v3 | 原生 Go LDAP 客户端，企业域集成 |