# 数据库自动化发布与智能运维平台 - 技术文档

## 一、技术选型

### 1.1 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                   前端（Bootstrap / SB Admin 2）              │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTPS / REST API
┌──────────────────────────▼──────────────────────────────────┐
│                后端服务（Django / Python）                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐  │
│  │ 工单模块  │ │ SQL审核  │ │ 权限管理  │ │  AI 智能运维   │  │
│  └──────────┘ └──────────┘ └──────────┘ └────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐    │
│  │         异步任务层（Celery + Redis 消息队列）           │    │
│  └──────────────────────────────────────────────────────┘    │
└──────────┬──────────────────────┬───────────────────────────┘
           │                      │
┌──────────▼──────┐    ┌──────────▼──────────┐
│   MySQL / MSSQL │    │   GoInception        │
│  （业务数据库）   │    │  （SQL 审核引擎）     │
└─────────────────┘    └─────────────────────┘
           │
┌──────────▼──────┐
│   Redis         │
│  （任务队列/缓存）│
└─────────────────┘
```

### 1.2 技术栈清单

| 层次 | 技术 | 用途 |
|------|------|------|
| 基础框架 | Python / Django | Web 服务框架，MVC 架构 |
| ORM | Django ORM | 数据库操作，模型管理 |
| 数据库 | MySQL / MSSQL | 业务数据存储，多引擎支持 |
| 缓存/消息队列 | Redis | Celery 消息代理，任务结果存储 |
| 异步任务 | Celery | 慢查询分析、定期备份等异步任务 |
| SQL 审核引擎 | GoInception | SQL 语法检查、风险扫描、执行计划分析 |
| SQL 分析插件 | SQLAdvisor / Soar | SQL 优化建议 |
| 认证 | LDAP / OIDC / 钉钉 / 2FA | 多因素认证体系 |
| 权限 | RBAC | 三级权限控制（认证/功能/数据） |
| AI 运维 | MCP 协议 / AI Agent / RAG | 智能 SQL 错误分析、配置查询 |
| 前端 | Bootstrap / SB Admin 2 | 响应式管理界面 |
| 监控 | ELK + Prometheus + Grafana | 日志监控与告警 |
| 通知 | 企业微信 | 工单执行结果推送 |

---

## 二、项目结构

```
cjops-dbs/
├── archery/                  # Django 项目配置
│   ├── settings.py           # 全局配置（认证、数据库、Celery）
│   └── urls.py               # 路由配置
├── sql/                      # 核心业务模块
│   ├── models.py             # 数据模型（工单、实例、慢查询等）
│   ├── instance.py           # 数据库实例管理
│   ├── slowlog.py            # 慢查询分析
│   ├── sql_tuning.py         # SQL 优化
│   ├── sql_analyze.py        # SQL 分析
│   ├── plugins/              # SQL 分析插件（SQLAdvisor、Soar）
│   └── utils/
│       ├── execute_sql.py    # SQL 执行引擎（工单状态机）
│       └── tasks.py          # Celery 异步任务
├── sql_api/                  # REST API 层
│   ├── api_workflow.py       # 工单相关 API
│   ├── api_user.py           # 用户相关 API
│   ├── api_backup.py         # 备份相关 API
│   ├── api_git.py            # Git 集成 API
│   └── permissions_helper.py # 权限辅助工具
├── common/
│   └── utils/
│       └── chart_dao.py      # 慢查询统计数据访问
└── src/script/
    └── analysis_slow_query.sh # 慢查询日志分析脚本
```

---

## 三、核心模块设计

### 3.1 认证体系设计

系统支持多因素认证，通过环境变量动态配置认证策略，优先级：**LDAP > 钉钉 > OIDC > 本地认证**。

```
认证请求
    │
    ├─ ENABLE_LDAP=true  ──► LDAP 认证
    ├─ ENABLE_DINGDING=true ► 钉钉认证
    ├─ ENABLE_OIDC=true  ──► OIDC 认证（OpenID Connect）
    └─ 默认              ──► 本地账号认证
                              │
                              └─ 2FA 双因素验证（SMS / TOTP）
```

**关键特性：**
- 双因素认证（2FA）作为基础安全层，支持短信（SMS）和时间型（TOTP）两种方式
- OIDC 集成通过 `mozilla_django_oidc` 实现，路由 `/oidc/`
- 通过 `SUPPORTED_AUTHENTICATION` 常量维护可用认证列表

---

### 3.2 权限控制设计

系统采用三级权限控制策略：

| 级别 | 类型 | 说明 |
|------|------|------|
| 第一级 | 基础认证 | `permissions.IsAuthenticated`，登录即可访问 |
| 第二级 | 功能权限 | 如 `sql.sql_submit`（提交工单）、`sql.sql_execute`（执行工单） |
| 第三级 | 数据权限 | 按资源组（Resource Group）过滤，用户只能操作所属资源组的数据库 |

**工单权限示例：**
- 管理员：可查看所有工单
- 普通用户：只能查看自己提交的工单，需 `sql.sql_submit` 权限才能提交

---

### 3.3 工单状态机设计

工单生命周期通过 `SQL_WORKFLOW_CHOICES` 定义的 9 种状态管理，核心状态流转：

```
[提交] ──► workflow_queuing（排队中）
                │
                ▼ execute 触发
         workflow_executing（执行中）
                │
        ┌───────┼───────┐
        ▼       ▼       ▼
   workflow_ workflow_ workflow_
   finish   exception  abort
  （已完成）（执行异常）（已中止）

workflow_timingtask（定时任务等待）──► workflow_executing
```

**`execute` 函数核心逻辑：**
1. `select_for_update` 锁定工单记录，防止并发执行
2. 校验工单状态（仅 `workflow_queuing` / `workflow_timingtask` 可执行）
3. 更新状态为 `workflow_executing`
4. 通过 `Audit` 类记录操作日志
5. 调用对应数据库引擎执行 SQL

---

### 3.4 SQL 审核流程设计

SQL 提交后经过双重校验机制：

```
用户输入 SQL
    │
    ▼
基础规范校验（空值检测、语法结构）
    │
    ▼
语法树解析（sqlanalyze 视图函数）
    │
    ▼
风险规则匹配（注入检测、高危操作拦截）
    │
    ▼
SQLAdvisor / Soar 优化建议
    │
    ▼
审核结果输出（通过 / 拒绝 + 优化建议）
```

**GoInception 集成：**
- SQL 语法检查：识别语法错误，提前拦截
- 风险扫描：检测全表扫描、无 WHERE 条件的 DELETE/UPDATE 等高危操作
- 执行计划分析：评估 SQL 执行效率，给出索引建议

---

### 3.5 慢查询分析设计

基于 `pt-query-digest` 工具实现全链路慢查询监控：

```
MySQL 慢查询日志文件
    │
    ▼ analysis_slow_query.sh（增量分析）
pt-query-digest 解析
    │
    ├──► mysql_slow_query_review（SQL 指纹表）
    └──► mysql_slow_query_review_history（历史统计表）
                │
                ▼
    slow_query_review_history_by_pct_95_time（95分位耗时趋势）
    slow_query_review_history_by_cnt（执行次数趋势）
                │
                ▼
    企业微信告警通知（execute_callback 回调）
```

**关键数据模型（`SlowQueryHistory`）：**

| 字段 | 说明 |
|------|------|
| `hostname_max` | 主机标识 |
| `checksum` | SQL 指纹（关联 SlowQuery） |
| `query_time_pct_95` | 95% 分位耗时 |
| `ts_min` | 首次出现时间 |
| `rows_examined_sum` | 扫描行数 |
| `tmp_table_cnt` | 临时表计数 |

**增量分析机制：** 通过 `last_analysis_time_{hostname}` 文件记录上次分析位置，避免重复分析。

---

### 3.6 异步任务设计

基于 **Celery + Redis** 实现异步任务调度：

```
API 请求 ──► Celery 任务队列（Redis Broker）
                    │
                    ▼
              Worker 执行节点
                    │
        ┌───────────┼───────────┐
        ▼           ▼           ▼
   慢查询分析    定期备份    SQL 工单执行
        │
        ▼
   结果持久化（MySQL）+ 企业微信通知
```

**定时任务示例（`TimingTaskWorkflow`）：**
- 任务命名规范：`sqlreview-timing-{workflow_id}`
- 通过 Django 事务保证状态更新与任务创建的原子性
- 完整审计追踪：通过 `Audit` 类记录定时任务创建事件

---

### 3.7 AI 智能运维设计

基于 **MCP 协议**构建 AI Agent，提供智能运维能力：

| 能力 | 实现方式 | 说明 |
|------|---------|------|
| SQL 错误分析 | MCP Tool | 分析 SQL 执行错误，给出修复建议，准确率 80%+ |
| 配置智能查询 | MCP Tool | 自然语言查询数据库配置信息 |
| 发布排障辅助 | AI Agent | 结合历史工单数据，辅助定位发布失败原因 |
| 知识库问答 | RAG 技术 | 基于运维文档构建向量知识库，提供精准建议 |

---

## 四、接口设计概览

### 4.1 认证接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/token/` | 获取 JWT 访问令牌 |
| GET | `/oidc/authenticate/` | OIDC 认证入口（302 重定向） |

### 4.2 工单接口

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| GET | `/api/workflow/` | 工单列表（支持多条件过滤） | `IsAuthenticated` |
| POST | `/api/workflow/` | 提交新工单 | `sql.sql_submit` |
| POST | `/api/workflow/execute/` | 执行工单 | `sql.sql_execute` |
| POST | `/api/workflow/timing/` | 设置定时执行 | `sql.sql_execute` |
| POST | `/api/workflow/approve/` | 审批工单 | 审批权限 |

### 4.3 SQL 分析接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/sql/analyze/` | SQL 分析（语法检查 + 优化建议） |
| GET | `/api/sql/describe/` | 获取表结构信息 |
| GET | `/api/sql/object_statistics/` | 获取表统计信息 |

### 4.4 慢查询接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/slowlog/review_history/` | 慢查询历史统计 |
| GET | `/api/slowlog/list/` | 慢查询列表 |

### 4.5 数据分析接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api2/data_analysis/get_sql_workflow_data/` | 工单数据分析（分页） |

---

## 五、数据库设计

### 5.1 核心数据模型

**工单模型（`SqlWorkflow`）：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `workflow_name` | CharField | 工单名称 |
| `engineer` | CharField | 提交人 |
| `status` | CharField | 工单状态（9种） |
| `db_name` | CharField | 目标数据库 |
| `sql_content` | TextField | SQL 内容 |
| `create_time` | DateTimeField | 创建时间 |

**慢查询模型（`SlowQuery`）：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `fingerprint` | TextField | 查询指纹（SQL 模板） |
| `sample` | TextField | 查询示例 |
| `first_seen` | DateTimeField | 首次出现时间 |
| `last_seen` | DateTimeField | 最近出现时间 |

---

## 六、部署说明

### 6.1 环境依赖

| 组件 | 版本要求 |
|------|---------|
| Python | 3.8+ |
| Django | 3.x+ |
| MySQL | 5.7+ / 8.0+ |
| Redis | 6.x+ |
| GoInception | Latest |
| Celery | 5.x+ |

### 6.2 认证配置

```python
# settings.py 关键配置
ENABLE_LDAP = os.getenv("ENABLE_LDAP", False)
ENABLE_DINGDING = os.getenv("ENABLE_DINGDING", False)
ENABLE_OIDC = os.getenv("ENABLE_OIDC", False)
DEBUG = os.getenv("DEBUG", False)  # 生产环境强制关闭

# URL 路由
urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/", include(("sql_api.urls", "sql_api"), namespace="sql_api")),
    path("oidc/", include("mozilla_django_oidc.urls")),
    path("", include(("sql.urls", "sql"), namespace="sql")),
]
```

### 6.3 Celery 配置

```bash
# 启动 Celery Worker
celery -A archery worker -l info

# 启动 Celery Beat（定时任务）
celery -A archery beat -l info
```