rlwj-lab/opsxsql
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3c4895c5785bbcf7567a1f8624b50bf506354531
opsxsql/docs/ARCHITECTURE.md
T
logan 14e394fb09 feat: 5种专业登录页风格 + 外观设置 + 文档全面更新 
- 新增 5 种登录页组件: SplitView/CenteredCard/SidePanel/FullImage/MinimalDark
- 提取 useLogin hook 共享登录逻辑
- LoginPage 改为风格分发器, localStorage(login-style) 控制渲染
- SettingsPage 新增外观设置 tab: 主题切换 + 登录风格选择器(含缩略图预览)
- AppearanceSettings 组件: 5 种风格卡片式切换
- 文档全面更新为 Go/Gin 架构:
  - ARCHITECTURE.md: Go 项目结构/handler/GORM 模型/中间件/LDAP/驱动矩阵
  - FEATURES.md: v0.3.1 功能清单含登录主题系统
  - ROADMAP.md: Python→Go 迁移历史 + Sprint 计划
2026-05-26 21:16:36 +08:00

367 lines
19 KiB
Markdown
Raw Blame History

# 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 客户端，企业域集成 |
Reference in new issue View Git Blame Copy Permalink