Archery

SQL 审核查询平台 · Vue3 SPA 现代化分支

项目简介

本项目是基于开源项目 hhyo/Archery 的二次开发分支，在保留其核心多数据库引擎、SQL 审核工作流的基础上，对前端与接口层进行了大规模现代化重构：

前端：从 Django 服务端渲染页面（Bootstrap + jQuery + metisMenu / sb-admin-2）整体迁移到 Vue 3 + TypeScript + Vite + Element Plus 单页应用（SPA），位于 frontend/。
后端：新增 Django REST Framework 应用 sql_api/，将原有服务端渲染页面逐步改造为纯 JSON API，前端不再依赖 Django 模板。
AI 集成：基于 OpenAI，提供自然语言生成 SQL、SQL 智能分析、SQL 智能优化等能力。
认证：Django Session 认证 + 双因素（TOTP / 短信），登录全流程在 SPA 内完成；支持 OIDC / CAS / 钉钉 / LDAP 等多种企业认证。
可视化：仪表盘、慢查趋势等图表由 pyecharts 改为 ECharts 重写。

该分支为独立演进，不保证与上游 hhyo/Archery 可合并。核心 sql/engines/ 多数据库引擎与审核工作流逻辑保持不变。

功能清单

数据库	查询	审核	执行	备份	数据字典	慢日志	会话管理	账号管理	参数管理	数据归档
MySQL	√	√	√	√	√	√	√	√	√	√
MariaDB	√	√	√	√	√	√	√	√	√	√
MsSQL	√	×	√	×	√	×	×	×	×	×
Redis	√	×	√	×	×	×	×	×	×	×
PgSQL	√	×	√	×	×	×	×	×	×	×
Oracle	√	√	√	√	√	×	√	×	×	×
MongoDB	√	√	√	×	×	×	√	√	×	×
Phoenix	√	×	√	×	×	×	×	×	×	×
ODPS	√	×	×	×	×	×	×	×	×	×
ClickHouse	√	√	√	×	×	×	×	×	×	×
Cassandra	√	×	√	×	×	×	×	×	×	×
Doris	√	×	√	×	×	×	√	×	×	×
Elasticsearch	√	×	√	×	×	×	×	×	×	×
OpenSearch	√	×	√	×	×	×	×	×	×	×
Memcached	√	×	√	×	×	×	×	×	×	×
TDengine	√	√	√	×	×	×	√	×	×	×

系统架构

┌──────────────────────────────────────────────────────────┐
│  浏览器  →  Vue 3 SPA (Element Plus / ECharts / Pinia)     │
│            frontend/  (Vite 构建，nginx 托管 dist/)        │
└───────────────────────────┬──────────────────────────────┘
                            │  /api/v1/*  (DRF JSON)
┌───────────────────────────▼──────────────────────────────┐
│  Django 4.2 后端                                          │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐  │
│  │  sql_api/    │   │   sql/       │   │  common/     │  │
│  │  DRF 接口层   │←─→│  核心业务+引擎 │←─→│  通用工具/认证 │  │
│  └──────────────┘   └──────────────┘   └──────────────┘  │
│         │                   │                  │          │
│         └────── OpenAI ─────┴─── django-q 异步任务 ───────┘
└───────────────────────────┬──────────────────────────────┘
                            │
        MySQL / Redis / Oracle / MongoDB / PgSQL / ...

frontend/ — Vue 3 SPA。25 个菜单页全部迁入：仪表盘、SQL 上线、在线查询、数据导出、实例管理（会话/库/账号/参数）、权限管理、数据归档、My2SQL、慢查、SQL 分析 / 优化 / 数据字典 / SchemaSync、系统审计、配置项管理、资源组 / 用户 / 权限组管理、认证配置、相关文档等。
sql_api/ — DRF 接口层。api_workflow.py / api_sqlquery.py / api_instance.py / api_query_priv.py / api_archiver.py / api_config.py / api_dashboard.py / api_slowlog.py / api_misc.py 等模块，配合 drf-spectacular 自动生成 OpenAPI 文档。
sql/ — 上游核心：engines/ 多数据库引擎、审核工作流、查询/优化/分析逻辑，本分支保持不动。
common/utils/openai.py — OpenAI 客户端封装，供 NL→SQL 生成、AI 分析、AI 优化复用。

AI 能力

能力	接口	说明
自然语言生成 SQL	`POST /api/v1/query/generate_sql/`	结合所选表的 DDL 作为上下文，调用 OpenAI 生成查询语句
SQL 智能分析	`POST /api/v1/sql_analyze/ai/`	AI 解读 SQL 执行计划与统计信息
SQL 智能优化	`POST /api/v1/optimize/ai/`	AI 给出优化建议
OpenAI 配置探测	`GET /api/v1/query/check_openai/`	检查后端是否已配置可用 OpenAI

在「配置项管理」页配置 OPENAI 相关参数（API Key / 模型 / Base URL）后即可启用。

快速开始

Docker

多阶段构建：node:22-alpine 阶段执行 npm ci && npm run build 产出 SPA dist/，再与 Archery 基础镜像合并，由 nginx 托管前端、反代后端。

1. 构建镜像

docker build -f src/docker/Dockerfile -t archery-vue3:v1 .

2. 准备 .env 与挂载目录

cd src/docker-compose
cp .env .env            # 仓库自带示例，按需修改数据库密码、NGINX_PORT、CSRF_TRUSTED_ORIGINS

.env 同时承担两个职责（见下文「认证配置机制」），不要遗漏：

供 startup.sh 读取 NGINX_PORT 等 shell 变量（通过 docker-compose 的 env_file 注入）；
供 settings.py 的 environ.read_env() 与「认证配置」重载逻辑读写（通过 ./.env:/opt/archery/.env 文件挂载）。

3. 启动

docker compose up -d

初始化账号：docker exec -it archery /opt/venv4archery/bin/python3 /opt/archery/manage.py createsuperuser

更多细节可参考上游 docker 部署文档。

认证配置机制（重要）

本分支对认证（LDAP / OIDC / 钉钉 / CAS）做了改造，不再通过 local_settings.py 配置，而是改为「数据库 + 运行时重载」：

后台「认证配置」页面 ──写入──▶ DB（SysConfig / sql_config 表）
                                   │  点击「重载认证配置」
                                   ▼
        common/auth_settings_reload.py
          1. 把 DB 中的认证配置写回 .env 的「受管标记块」
             (# === auth config (managed by Archery) === … # === end managed ===)
          2. 同步 os.environ
          3. importlib.reload(settings 模块) → AUTHENTICATION_BACKENDS /
             AUTH_LDAP_* / ENABLE_LDAP 等重新求值
          4. 清 URL resolver 缓存，使 /oidc/ 等路由按新配置 include

因此 docker-compose 不再挂载 local_settings.py——它在 settings.py 末尾以 from local_settings import * 加载，优先级最高，会覆盖上述所有认证配置，导致后台修改 + 重载完全不生效（典型表现：LDAP/SSO 登录始终提示「用户名或密码不正确」）。

如需自定义非认证相关的 settings，请改 .env（推荐）或直接进容器修改，不要重新挂载 local_settings.py。

本地开发

后端与前端可分别独立运行，前端通过 Vite proxy 转发 /api、/authenticate 等到后端。

1. 后端（Django + DRF）

# 创建虚拟环境（Python 3.11）
python -m venv venv
source venv/Scripts/activate    # Windows (Git Bash)
# source venv/bin/activate      # Linux / macOS

# 安装依赖（Windows 本地开发用 requirements-local.txt，去掉了难编译的原生驱动）
pip install "setuptools<82" wheel
pip install -r requirements-local.txt --no-build-isolation

# 配置环境变量（复制 .env.list 为 .env 并按需修改）
#   DATABASE_URL    数据库连接（默认 MySQL）
#   CACHE_URL       Redis 缓存连接
#   ENABLED_ENGINES 启用的数据库引擎，逗号分隔，如 mysql,pgsql
#   CSRF_TRUSTED_ORIGINS  信任的源（需包含前端 dev 地址，如 http://localhost:5175）

# 初始化数据库
python manage.py makemigrations sql
python manage.py migrate

# 启动开发服务器
python manage.py runserver 0.0.0.0:8000

2. 前端（Vue 3 SPA）

cd frontend
npm ci
npm run dev          # 默认 http://localhost:5175，proxy → http://localhost:8000

常用脚本：

命令	说明
`npm run dev`	启动 Vite 开发服务器
`npm run build`	类型检查 + 生产构建到 `dist/`
`npm run type-check`	`vue-tsc` 类型检查
`npm run preview`	本地预览构建产物

3. 初始数据与账号

导入默认权限组与慢查表结构（也可直接执行 bash admin.sh migration）：

python manage.py dbshell < sql/fixtures/auth_group.sql                 # Default / RD / DBA / PM / QA 权限组
python manage.py dbshell < src/init_sql/mysql_slow_query_review.sql    # 慢查询评审表结构
python manage.py createsuperuser                                       # 创建管理员账号

运行测试

# 后端
pytest -q
# 按模块执行
pytest -q sql common sql_api

# 前端
cd frontend
npm run type-check

技术栈与依赖

前端（`frontend/`）

框架：Vue 3 · TypeScript · Vite
UI：Element Plus · @element-plus/icons-vue
状态 / 路由：Pinia · Vue Router
图表：ECharts
SQL 编辑器 / 格式化：ace-builds · sql-formatter
数据导出：xlsx · openpyxl
Markdown：marked · DOMPurify
HTTP：axios

后端框架

Django 4.2 · Django REST Framework
drf-spectacular（OpenAPI）· django-filter
队列任务 django-q2 · 配置 django-environ
数据加密 django-mirage-field · 对象存储 django-storages

认证

Session 认证 · 双因素 pyotp / qrcode
短信：阿里云 dysmsapi · 腾讯云 SMS
企业 SSO：mozilla-django-oidc · django-cas-ng · django-auth-dingding · LDAP（python-ldap / ldap3）

AI

OpenAI Python SDK — NL→SQL 生成、SQL 智能分析与优化

数据库连接器

MySQL mysqlclient / PyMySQL
MsSQL pyodbc
PostgreSQL psycopg2
Oracle cx_Oracle
MongoDB pymongo
Redis redis-py / Memcached pymemcache
ClickHouse clickhouse-driver
Cassandra cassandra-driver
Phoenix phoenixdb · ODPS pyodps
Elasticsearch elasticsearch-py · OpenSearch opensearch-py
TDengine taos-ws-py

功能依赖

MySQL 审核 / 执行 / 备份 goInception · inception
MySQL 索引优化 SQLAdvisor
SQL 优化 / 压缩 SOAR
Binlog 解析 / 回滚 my2sql · python-mysql-replication
表结构同步 SchemaSync
慢日志解析 pt-query-digest
大表 DDL gh-ost · pt-online-schema-change
MyBatis XML 解析 mybatis-mapper2sql
SQL 解析 / 切分 / 类型判断 sqlparse
RDS 管理 aliyun-openapi-python-sdk

目录结构

.
├── archery/          # Django 项目配置（settings / urls / wsgi）
├── sql/              # 核心业务：多数据库引擎、审核工作流、查询/优化/分析
├── sql_api/          # DRF 接口层（本分支新增）
├── common/           # 通用工具、认证、OpenAI 客户端封装
├── frontend/         # Vue 3 SPA（本分支新增）
│   └── src/{api,views,components,stores,router,layouts,composables,...}
├── src/
│   ├── docker/       # Dockerfile / nginx.conf / supervisord.conf / 启动脚本
│   ├── charts/       # Helm Chart
│   └── plugins/      # SQLAdvisor / SOAR / my2sql 等外部工具
├── docs/             # 文档（含 PHASE4-CLEANUP.md 迁移收尾清单）
├── requirements.txt          # 生产依赖
└── requirements-local.txt    # Windows 本地开发依赖（去掉难编译的原生驱动）

贡献代码

欢迎通过以下方式贡献：

Bug 修复、新功能、代码优化、测试用例完善
Wiki 文档（开放编辑）
提交 Issue 或 Pull Request

致谢

archer — Archery 项目基于 archer 二次开发而来
goInception — 集审核、执行、备份及生成回滚语句于一身的 MySQL 运维工具
JetBrains Open Source — 为项目提供免费的 IDE 授权

License

Apache License 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 2,147 Commits
.github		.github
.specify		.specify
archery		archery
common		common
docs		docs
downloads		downloads
frontend		frontend
logs		logs
scripts		scripts
specs		specs
sql		sql
sql_api		sql_api
src		src
.dockerignore		.dockerignore
.env.list		.env.list
.gitattributes		.gitattributes
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
admin.sh		admin.sh
conftest.py		conftest.py
debug.sh		debug.sh
dev-requirements.txt		dev-requirements.txt
manage.py		manage.py
masking.sh		masking.sh
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
startup.sh		startup.sh
supervisord.conf		supervisord.conf

Navigation Menu

Repository files navigation

Archery

SQL 审核查询平台 · Vue3 SPA 现代化分支

项目简介

功能清单

系统架构

AI 能力

快速开始

Docker

认证配置机制（重要）

本地开发

运行测试

技术栈与依赖

前端（`frontend/`）

后端框架

认证

AI

数据库连接器

功能依赖

目录结构

贡献代码

致谢

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Archery

SQL 审核查询平台 · Vue3 SPA 现代化分支

项目简介

功能清单

系统架构

AI 能力

快速开始

Docker

认证配置机制（重要）

本地开发

运行测试

技术栈与依赖

前端（frontend/）

后端框架

认证

AI

数据库连接器

功能依赖

目录结构

贡献代码

致谢

License

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

前端（`frontend/`）