0 Fork 0

Files

T

Logan.Li 0b16488029 feat(deploy): single-image docker-compose and kubernetes install.sh

- multi-stage root Dockerfile (opsx-loki pattern): frontend dist +
  go binary + gh-ost in one alpine image, non-root user, HEALTHCHECK,
  entrypoint warning for missing SECRET_KEY; gin now serves the SPA
  from DIST_DIR (asset/db-logos/favicon passthrough, /api returns JSON
  404, SPA fallback to index.html) - one origin, no CORS surface
- docker-compose.yml rewritten: single service, named data volume,
  no-new-privileges + cap_drop ALL, /health healthcheck, resource
  limits, log rotation; SECRET_KEY required (openssl rand -hex 32),
  JWT_SECRET optional (auto-generated and persisted in prod)
- kubernetes/: install.sh one-command deploy (idempotent secret
  reuse, --nodeport/--ingress flags, rollout wait, backup tips) plus
  namespace/secret/pvc/deployment(single replica + Recreate, probes,
  resource limits, non-root)/service/nodeport/ingress manifests and
  README (sqlite single-writer constraints, snapshot backup)
- docs: README quick-start now has 3 deployment paths; ARCHITECTURE
  ch.14 expanded

single-image runtime verified locally (SPA/assets/api/login coexist
on :9002); full image build left to server (docker hub unreachable
from this machine)

2026-10-26 20:33:26 +08:00

20 KiB

Raw Permalink 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 启动流程

// 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 编译与运行

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. 运维部署

14.1 开发环境

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/

14.2 Docker Compose(单镜像,生产推荐)

多阶段构建:前端 dist + Go 二进制 + gh-ost 合并为一个 alpine 镜像,Gin 同时托管静态资源与 API(前后端同源,无 CORS 面);非 root、no-new-privileges、 cap_drop ALL、/health 健康检查、资源限额与日志轮转(参照 opsx-loki 基线)。

export SECRET_KEY=$(openssl rand -hex 32)   # AES 密钥,部署后不可更换
docker compose up -d --build                # http://localhost:9000

数据持久化在命名卷 opsxsql-data(SQLite + 持久化 JWT 密钥)。

14.3 Kubernetes

bash kubernetes/install.sh --nodeport       # 一键:命名空间/密钥/PVC/Deployment/Service

约束:SQLite 单写者 → Deployment 固定 replicas=1 + Recreate(防滚动更新双写)。备份:sqlite3 /app/data/sqlite3.db '.backup ...' 或 CSI VolumeSnapshot。详见 kubernetes/README.md。

14.4 健康检查

curl http://localhost:9000/health
# → {"status":"ok","version":"0.4.0","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 客户端，企业域集成

20 KiB Raw Permalink Blame History