目录
master
分支2
标签0
+ 疑修
Web IDE
HL
feat: allow reviewed ctas change requests
18天前256次提交
README.md

AIGC Agent

AIGC Agent 是一个可私有化部署的 AI 数据协作平台。业务人员可以用自然语言查询数据，也可以上传 CSV / Excel 提交数据变更需求；开发人员可以像审 PR 一样审阅 SQL、执行 dry-run、批准、拒绝、执行和追踪审计日志。

业务人员提出查询或变更需求
  -> AI 生成查询结果或变更方案
  -> 系统做 SQL 安全校验和 dry-run
  -> 形成 Change Request
  -> developer/admin 审阅并受控执行
  -> 审计日志记录全过程

核心能力

  • 自然语言问数：基于 LangChain Agent 将业务问题转为 SQL 查询，并返回结论、SQL 和结果表格。
  • 只读 SQL 安全执行：单条 SELECT / WITH / SHOW / DESC / DESCRIBE / EXPLAIN 可直接执行，DML / DDL 会被拦截。
  • Change Request：自然语言或文件生成数据库变更申请，所有 DML 必须经过审批。
  • CSV / Excel 到 CR：解析文件、推荐目标表和字段映射、执行 dry-run，确认后创建 CR。
  • 多数据源：支持 MySQL、PostgreSQL、SQLite、ClickHouse、Oracle、SQL Server、OceanBase、MongoDB、Redis、Elasticsearch。
  • 数据源连接方式：支持服务端直连、服务端 SSH 隧道和本地连接器。
  • 权限体系：developer/admin 管理数据源、模型、系统配置、CR 和审计；viewer 只能访问授权查询类能力。
  • 审计追踪：记录 CR 创建、审批、执行、失败、回滚标记和关键操作。
  • 数据看板：支持 Dashboard、Widget、图表渲染、结构化筛选器、公开看板、私有看板和告警。
  • 私有化部署：FastAPI 后端、Vue 3 前端、PostgreSQL 系统库、Docker Compose 一键启动。

当前状态

模块 状态 说明
认证与权限 已实现 公开注册为 developer；developer/admin 可创建 viewer 并分配数据源
业务问数 已实现 自然语言问数、只读 SQL 安全执行、schema 问题直读
Agent 任务状态 已实现 支持 SSE 状态推送和按用户隔离查询
数据源管理 已实现 多数据源、凭据加密、权限隔离、直连/SSH/本地连接器
文件分析 已实现 CSV / Excel 上传、预览、查询、对话和流式响应
Change Request 已实现 草稿、SQL 草案、dry-run、提交、审批、执行、回滚入口和审计
CSV / Excel 到 CR 已实现 文件解析、字段映射确认、重校验、确认创建
数据看板 已实现 看板、组件、图表、筛选、告警和私有看板注册
模型管理 已实现 developer/admin 管理 OpenAI-compatible 模型配置
系统配置 已实现 developer/admin 查看和更新非敏感运行配置
测试 后端已覆盖 使用 Python unittest 覆盖权限、SQL 安全、CR、文件、模型和问数任务

技术栈

层级 技术
后端 FastAPI, SQLAlchemy Async, Pydantic, LangChain
LLM OpenAI-compatible API
前端 Vue 3, Vite, Pinia, Vue Router, Chart.js
系统库 PostgreSQL 默认；SQLite 可用于 demo / 测试
部署 Docker, Docker Compose, Nginx
测试 Python unittest

目录结构

server/                    FastAPI 后端
server/api/v1/             API 路由
server/service/            业务服务层
server/dao/                数据访问层
server/db/                 数据库连接、SQL 安全、查询执行和变更执行
server/llm/                LangChain Agent 和模型调用
server/models/             ORM、请求模型、响应模型
frontend/aigc-frontend/    Vue 3 前端
local_connector/           用户本地数据库连接器
tests/                     后端自动化测试
scripts/                   初始化账号、demo 数据和 demo 问题
API接口文档.md             当前 API 参考
分工文档.md                模块分工和协作规则
项目介绍.md                面向新人的项目说明

快速开始

1. 准备环境

推荐使用 Docker Compose。

本地开发需要：

  • Python 3.11+
  • Node.js 18+
  • Docker 与 Docker Compose
  • 一个 OpenAI-compatible LLM 服务

2. 配置环境变量

复制模板：

cp .env.example .env

至少修改：

LLM_API_KEY=your-api-key-here
LLM_API_BASE=https://api.example.com/v1
LLM_PROVIDER=openai-compatible
LLM_MODEL=your-model-name
JWT_SECRET=replace-with-a-random-secret
DATASOURCE_SECRET_KEY=replace-with-fernet-key
CORS_ORIGINS=http://localhost

生产环境必须替换 JWT_SECRET 和 DATASOURCE_SECRET_KEY。

生成 Fernet 密钥：

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

系统库默认使用 PostgreSQL。Docker Compose 会启动内置 postgres 服务。单机 demo 或测试如需 SQLite，可显式设置：

DATABASE_URL=sqlite+aiosqlite:///./data/test.db

3. Docker Compose 启动

docker compose up -d --build

默认访问：

查看日志：

docker compose logs -f backend

停止服务：

docker compose down

4. 创建初始 developer 账号

Docker 环境：

docker compose exec backend python scripts/init_admin.py --username admin --password "change-me"

本地环境：

python scripts/init_admin.py --username admin --password "change-me"

该账号可管理数据源、创建 viewer 观察账号、审批 CR 和查看审计日志。

本地开发

后端

python -m venv .venv
. .venv/Scripts/activate
pip install -r requirements.txt
python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000

Windows PowerShell 如果 python 指向 WindowsApps 占位程序，可使用真实 Python 路径：

& 'C:\Users\HL\AppData\Local\Programs\Python\Python311\python.exe' -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000

前端

cd frontend/aigc-frontend
npm install
npm run dev

前端默认通过 /api/v1 访问后端。开发代理见 frontend/aigc-frontend/vite.config.js。

数据源连接方式

方式 适用场景
服务端直连 后端服务器可以直接访问数据库。此时 localhost 表示后端容器或后端服务器。
服务端 SSH 隧道 后端服务器先 SSH 到跳板机或用户机器，再访问数据库。
本地连接器 用户运行 local_connector，由连接器从用户电脑访问本机数据库。

本地连接器通过 WebSocket 主动连接后端。生产环境建议使用 HTTPS/WSS，避免登录 token 和数据库连接配置在明文网络中传输。

角色与权限

角色 能力
viewer 只能使用授权数据源进行查询、问数、文件分析和查看公开看板
developer 可管理数据源、模型、系统配置、用户、CR、审计和看板
admin 具备 developer 能力

后端始终执行权限校验。viewer 不能创建、提交、审批、执行或查看 Change Request，也不能管理数据源、模型、系统配置、观察账号或私有看板。

Change Request 流程

  1. developer/admin 进入数据变更申请。
  2. 选择自然语言或 CSV / Excel 文件。
  3. 自然语言申请生成 SQL 草案。
  4. 文件申请生成导入计划，用户确认字段映射和 dry-run 结果后创建 CR。
  5. 申请提交审批。
  6. developer/admin 审阅 SQL、执行 dry-run、批准或拒绝。
  7. 已批准申请才允许执行。
  8. 执行结果、失败原因、回滚标记和关键动作写入审计日志。

Agent 任务状态

自然语言问数和直接查询 SQL 都会生成一条任务记录。/chat/send 返回 task_id，/chat/send/stream 通过 event: task 持续推送状态。

任务状态包括：

  • queued
  • running
  • tool_calling
  • querying
  • succeeded
  • failed
  • cancelled

任务查询接口按当前用户隔离：

  • GET /api/v1/chat/tasks/{task_id}
  • GET /api/v1/chat/tasks?conversation_id=...

Demo 数据

仓库提供 demo 资源：

  • scripts/demo_business_schema.sql：业务示例库表。
  • scripts/demo_questions.md：自然语言问数与变更申请示例。
  • init_postgresql_schema.sql：PostgreSQL 初始化参考。

测试

后端测试：

python -m unittest discover -s tests -v

Windows PowerShell：

& 'C:\Users\HL\AppData\Local\Programs\Python\Python311\python.exe' -m unittest discover -s tests -v

前端构建检查：

cd frontend/aigc-frontend
npm install
npm run build

文档

安全说明

  • 不要提交真实 .env、数据库密码、LLM Key 或生产 JWT 密钥。
  • 生产环境必须使用强随机 JWT_SECRET。
  • 生产环境必须设置有效 DATASOURCE_SECRET_KEY。
  • 数据源密码通过 DATASOURCE_SECRET_KEY 加密保存。
  • 生产环境请将 CORS_ORIGINS 设置为实际前端域名。
  • 当前前端使用 localStorage 保存 JWT；生产环境应部署在可信私有边界内。
  • DML 变更必须进入 CR 审批流程，不能绕过审批直接执行。
  • 审计日志可能包含 SQL 文本，生产环境请限制 developer/admin 账号范围。

常见问题

登录后为什么看不到数据源管理？

你可能使用的是 viewer 账号。viewer 只显示查询类入口。请使用 developer/admin 账号管理数据源、观察账号和 Change Request。

业务问数为什么出现 401？

如果后端返回 {"code":401,"message":"未提供认证令牌"} 或 {"code":401,"message":"令牌无效或已过期"}，请重新登录。

如果错误来自模型网关，例如 Unauthorized，说明系统认证已通过，但 LLM 的 API Key、API Base、模型名或额外请求头配置不正确。请检查“模型管理”或 .env。

快速判断：如果 SELECT 1 可以执行，但自然语言问数失败，通常是模型配置问题。

CSV / Excel 导入会直接写数据库吗？

不会。文件导入先生成映射计划和 dry-run 结果，确认后创建 CR。必须由 developer/admin 批准后才可执行。

为什么 UPDATE / DELETE 被拒绝？

系统会阻断无 WHERE 的 UPDATE / DELETE、多语句 SQL 和危险 DDL。这是为了避免误操作造成大范围数据破坏。

审计日志在哪里看？

使用 developer/admin 登录后，进入审计日志页面，或调用：

GET /api/v1/change-requests/audit

可以不用 Docker 吗？

可以。按“本地开发”章节分别启动后端和前端。

还推荐 SQLite 作为系统库吗？

不推荐。系统库默认使用 PostgreSQL。SQLite 只建议用于单机 demo 或测试环境。

License

本项目使用 Apache License 2.0。

关于
README.md
4.2 MB
Apache-2.0
邀请码