# dw agent **Repository Path**: elfbobo_admin_admin/dw-agent ## Basic Information - **Project Name**: dw agent - **Description**: 数仓AI Agent 基于 AI Agent 技术的智能多数据源查询系统，支持使用自然语言查询 Hive/Doris/MySQL/PostgreSQL 等数据源，自动生成 SQL、数据洞察和可视化报告。 当前版本：v1.9 功能特性 自然语言查询：用中文描述查询需求，自动转换为目标数据源的 SQL 多数据源支持：支持 Hive、Doris、MySQL、PostgreSQL（独立数据源管理模块） - **Primary Language**: Unknown - **License**: MPL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-04-24 - **Last Updated**: 2026-04-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 数仓AI Agent 基于 AI Agent 技术的智能多数据源查询系统，支持使用自然语言查询 Hive/Doris/MySQL/PostgreSQL 等数据源，自动生成 SQL、数据洞察和可视化报告。 **当前版本**：v1.9 --- ## 功能特性 - **自然语言查询**：用中文描述查询需求，自动转换为目标数据源的 SQL - **多数据源支持**：支持 Hive、Doris、MySQL、PostgreSQL（独立数据源管理模块） - **智能 Schema 管理**：自动缓存表结构，LLM 自动生成字段注释 - **数据报告生成**：查询成功且开启报告选项后生成 HTML/Markdown 格式报告，支持导出 - **数据源级权限**：基于角色的权限控制，精确到数据源名称级别 - **系统主题配置**：已支持主题模式/主题色配置，深色模式覆盖仍在完善 - **RESTful API**：完整的 API 接口，支持前端和第三方集成 - **审计日志**：登录、操作、权限变更全程可追溯 --- ## 系统架构 ``` dw-agent/ ├── api/ # FastAPI 后端 │ ├── main.py # 应用入口（应用装配 / 中间件 / 路由注册） │ ├── deps.py # 依赖注入 │ └── routers/ # 路由模块 │ ├── auth.py # 认证（登录/注册/JWT） │ ├── users.py # 用户管理 │ ├── roles.py # 角色与权限（含权限矩阵） │ ├── assets.py # 资产概览 │ ├── datasources.py # 数据源管理（含Schema/注释/连接测试） │ ├── history.py # 查询历史（列表/详情/rerun/删除） │ ├── audit_logs.py # 审计日志 │ └── profile.py # 个人设置 ├── config/ # 配置管理 │ ├── settings.py # 全局设置（环境变量） │ ├── database.py # SQLite 配置库 │ ├── logger.py # 日志配置 │ └── validator.py # 配置校验 ├── core/ # 核心逻辑 │ ├── agent.py # 主 Agent（查询编排） │ ├── asset_service.py # 资产服务 │ └── error_analyzer.py # 错误分析 ├── database/ # 数据库连接 │ └── hive_client.py # Hive / 多数据源客户端 ├── agent/ # AI 能力 │ └── sql_generator.py # NL2SQL 生成器 ├── reports/ # 报告生成 │ └── report_generator.py ├── utils/ # 工具函数 │ ├── auth_helpers.py # 权限辅助（JWT 解析/管理员检查） │ ├── performance.py # 性能监控（装饰器） │ └── password.py # 密码加密（bcrypt） ├── vue/ # Vue 3 前端 │ └── src/ │ ├── views/ # 页面（Query / Reports / Assets / Config / ...） │ ├── components/ # 通用组件 │ ├── services/ # 前端 API 调用封装 │ └── router/ # 路由配置（含路由守卫） ├── tests/ # 测试套件 ├── config.db # SQLite 配置数据库 └── main.py # CLI 入口 ``` --- ## 安装配置 ### 1. 安装依赖 ```bash pip install -r requirements.txt ``` 数据源驱动依赖说明： - **Hive**：PyHive / thrift / thrift-sasl / pure-sasl - **Doris / MySQL**：PyMySQL - **PostgreSQL**：psycopg 如果你只使用部分数据源，也建议直接安装完整 `requirements.txt`，避免在切换数据源类型时缺少运行时依赖。 ### 2. 配置环境变量 ```bash cp .env.example .env ``` 编辑 `.env` 文件（生产环境必填，开发环境可使用默认的本地配置）： ```env # JWT 认证密钥（生产环境必须设置） JWT_SECRET=your-secret-key-here # 环境标识 ENVIRONMENT=development # CORS 允许的来源（逗号分隔） ALLOWED_ORIGINS=http://localhost:8080,http://127.0.0.1:8080 # Hive 数据源 HIVE_HOST=localhost HIVE_PORT=10000 HIVE_USERNAME=hive HIVE_PASSWORD= HIVE_DATABASE=default # LLM（豆包） DOUBAO_API_KEY=your_api_key_here DOUBAO_API_URL=https://ark.cn-beijing.volces.com/api/v3/chat/completions DOUBAO_MODEL=doubao-3.5-turbo DOUBAO_TEMPERATURE=0.1 # 报告输出目录 REPORT_OUTPUT_DIR=./reports ``` ### 3. 启动系统 ```bash # 初始化数据库并启动 API python -m api.main # 或使用 uvicorn uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload ``` 前端访问：http://localhost:8000 API 文档：http://localhost:8000/docs --- ## 核心 API 列表 | 端点 | 方法 | 说明 | 权限 | |------|------|------|------| | `/` | GET | 前端页面 | 公开 | | `/health` | GET | 健康检查 | 公开 | | `/api/health` | GET | 健康检查别名（前端 Dashboard 兼容） | 公开 | | `/api` | GET | API 信息概览 | 公开 | | **认证** | | | | | `/api/auth/login` | POST | 用户登录 | 公开 | | `/api/auth/register` | POST | 用户注册 | 公开 | | `/api/auth/logout` | POST | 用户登出 | 登录 | | `/api/auth/me` | GET | 当前用户信息（含权限列表） | 登录 | | `/api/auth/change-password` | POST | 修改密码 | 登录 | | **查询** | | | | | `/api/query` | POST | 自然语言查询（NL2SQL，可按选项生成报告） | 登录 | | **元数据 / Schema** | | | | | `/api/schema` | GET | 获取数据库 Schema | 登录 | | `/api/tables` | GET | 获取表列表（优先缓存） | 登录 | | `/api/tables/{table_name}` | GET | 获取表结构详情 | 登录 | | `/api/tables/{table_name}` | DELETE | 删除表结构和相关注释 | 登录 | | `/api/tables/{table_name}/columns/{column_name}` | DELETE | 删除字段注释 | 登录 | | `/api/refresh-schema` | POST | 手动刷新 Schema 缓存 | 登录 | | **注释管理** | | | | | `/api/comments/tables` | GET | 获取所有表注释 | 登录 | | `/api/comments/tables/{table_name}` | GET | 获取指定表注释 | 登录 | | `/api/comments/tables/{table_name}` | PUT | 更新表注释 | 登录 | | `/api/comments/columns` | GET | 获取所有字段注释 | 登录 | | `/api/comments/tables/{table_name}/columns/{column_name}` | GET | 获取指定字段注释 | 登录 | | `/api/comments/tables/{table_name}/columns/{column_name}` | PUT | 更新字段注释 | 登录 | | **资产** | | | | | `/api/assets/overview` | GET | 资产概览（表数量/字段统计） | 登录 | | **报告** | | | | | `/api/reports` | GET | 报告列表（支持分页/关键词/时间范围过滤） | 登录 | | `/api/reports/{report_id}` | GET | 报告详情 | 登录 | | `/api/reports/{report_id}` | DELETE | 删除报告 | 登录 | | `/api/reports/{report_id}/export` | GET | 导出报告（HTML/MD/CSV） | 登录 | | **数据源管理** | | | | | `/api/datasources` | GET | 数据源列表（可选包含停用） | 登录 | | `/api/datasources` | POST | 创建数据源 | admin | | `/api/datasources/test-connection` | POST | 不保存直接测试连接 | 登录 | | `/api/datasources/{id}` | GET | 获取数据源详情 | 登录 | | `/api/datasources/{id}` | PUT | 更新数据源 | admin | | `/api/datasources/{id}` | DELETE | 删除数据源 | admin | | `/api/datasources/{id}/test` | POST | 测试数据源连接 | 登录 | | `/api/datasources/{id}/set-default` | POST | 设置默认数据源 | admin | | `/api/datasources/{id}/schema` | GET | 获取数据源 Schema（缓存优先） | 登录 | | `/api/datasources/{id}/schema/{table_name}` | GET | 获取指定表结构详情 | 登录 | | `/api/datasources/{id}/comments/tables/{table_name}` | PUT | 保存表注释 | 登录 | | `/api/datasources/{id}/comments/tables/{table_name}/columns/{column_name}` | PUT | 保存字段注释 | 登录 | | **查询历史** | | | | | `/api/history` | GET | 查询历史列表（支持分页/过滤） | 登录 | | `/api/history/{id}` | GET | 查询历史详情 | 登录 | | `/api/history/{id}/rerun` | POST | 重新执行历史查询 | 登录 | | `/api/history/{id}` | DELETE | 删除查询历史 | 登录 | | **用户管理** | | | | | `/api/users` | GET | 用户列表（分页/关键词） | admin | | `/api/users` | POST | 创建用户 | admin | | `/api/users/{id}` | GET | 用户详情 | 登录 | | `/api/users/{id}` | PUT | 更新用户（角色/部门等） | admin | | `/api/users/{id}` | DELETE | 软删除用户 | admin | | `/api/users/{id}/reset-password` | POST | 使用显式强密码重置用户密码 | admin | | **角色管理** | | | | | `/api/roles` | GET | 角色列表 | admin | | `/api/roles` | POST | 创建角色 | admin | | `/api/roles/permissions` | GET | 所有权限列表 | admin | | `/api/roles/{id}` | GET | 角色详情 | admin | | `/api/roles/{id}` | PUT | 更新角色 | admin | | `/api/roles/{id}` | DELETE | 删除角色 | admin | | `/api/roles/{id}/permission-matrix` | GET | 权限矩阵 | admin | | `/api/roles/{id}/permission-matrix` | PUT | 更新权限矩阵 | admin | | **审计日志** | | | | | `/api/audit-logs` | GET | 审计日志（分页/操作类型过滤） | admin | | **系统配置** | | | | | `/api/config` | GET | 获取配置（含主题/模型配置） | admin | | `/api/config` | POST | 更新配置（保存到数据库） | admin | | `/api/config/test-connection` | POST | 测试数据源连接（配置页） | admin | | **个人设置** | | | | | `/api/profile` | GET | 个人设置信息 | 登录 | --- ## 数据源级权限说明 系统按"数据源名称"（而非数据源类型）进行权限隔离： - **admin**：默认拥有所有数据源访问权限 - **data_engineer / business_analyst / guest**：通过角色配置分配可访问的数据源名称列表 - **查询、报告、资产中心**：均通过数据源选择框进行过滤，未授权的数据源不可见 --- ## 预定义角色 | 角色 | Key | 默认权限范围 | |------|-----|------------| | 管理员 | admin | 全部页面 + 全部功能 + 全部数据源 | | 数据工程师 | data_engineer | Query / Assets / Reports + 资产编辑 + 指定数据源 | | 业务分析师 | business_analyst | Query / Reports / Assets（只读）+ 指定数据源 | | 访客 | guest | Dashboard / Assets（只读） | 默认管理员账号：`admin` / `admin123`（首次登录后请立即修改密码） --- ## 查询示例 ``` 请输入查询: 上周华东区销售额是多少 请输入查询: 统计每个部门的员工数量 请输入查询: 查询订单数量最多的前10个客户 ``` --- ## 技术栈 | 层级 | 技术 | |------|------| | 后端 | Python 3.8+ / FastAPI / SQLite | | 前端 | Vue 3 / Element Plus | | Hive 连接 | PyHive / thrift / thrift-sasl | | Doris / MySQL 连接 | PyMySQL | | PostgreSQL 连接 | psycopg | | LLM | 豆包（字节跳动）| | 认证 | JWT (PyJWT) / bcrypt | | 数据处理 | Pandas | --- ## 注意事项 1. **JWT_SECRET** 生产环境必须设置，否则拒绝启动 2. 首次查询会自动缓存 Schema，后续查询速度更快 3. 前端登录态当前保存在 `sessionStorage`，关闭浏览器会话后会失效 3. 建议为字段添加中文注释，可显著提升 NL2SQL 准确率 4. 大数据量查询建议增加 LIMIT 条件，避免超时 5. 报告输出目录需要有写权限 --- ## 故障排查 **连接 Hive 失败** - 检查 HIVE_HOST / HIVE_PORT / HIVE_USERNAME 配置 - 确认 Hive 服务端口可访问 **SQL 生成不准确** - 使用资产中心刷新 Schema 并补充字段注释 - 在查询中加入更具体的表名或条件描述 **报告生成失败** - 检查报告服务是否正常启动 - 确认报表输出目录权限 **权限问题** - 确认用户已分配正确角色 - 检查角色是否授权了对应数据源 --- ## License MIT License