## 快速开始 ### Docker ``` docker run -p 5000:5000 -it falkordb/queryweaver ``` 启动地址：http://localhost:5000 ### 使用 .env 文件（推荐） 通过复制 `.env.example` 创建本地 `.env` 文件，并将其传递给 Docker。这是提供所有必需配置的最简单方法： ``` cp .env.example .env # 编辑 .env 设置您的值，然后： docker run -p 5000:5000 --env-file .env falkordb/queryweaver ``` ### 替代方案：传递单个环境变量 如果你更喜欢在命令行中传递变量，请使用 `-e` 标志（对于多个变量来说不太方便）： ``` docker run -p 5000:5000 -it \ -e APP_ENV=production \ -e FASTAPI_SECRET_KEY=your_super_secret_key_here \ -e GOOGLE_CLIENT_ID=your_google_client_id \ -e GOOGLE_CLIENT_SECRET=your_google_client_secret \ -e GITHUB_CLIENT_ID=your_github_client_id \ -e GITHUB_CLIENT_SECRET=your_github_client_secret \ -e AZURE_API_KEY=your_azure_api_key \ falkordb/queryweaver ``` ## Memory TTL（可选） QueryWeaver 将每个用户的对话记忆存储在 FalkorDB 中。默认情况下，这些图会无限期保留。设置 `MEMORY_TTL_SECONDS` 以应用 Redis TTL（以秒为单位），以便自动清理空闲的记忆图。 ``` # 1 周不活动后使内存图过期 MEMORY_TTL_SECONDS=604800 ``` TTL 会在每次用户交互时刷新，因此活跃用户的记忆会保留。 ## MCP server：托管或连接（可选） QueryWeaver 包含对 Model Context Protocol (MCP) 的可选支持。你可以让 QueryWeaver 暴露一个兼容 MCP 的 HTTP 接口（以便其他服务可以将 QueryWeaver 作为 MCP 服务器调用），或者将 QueryWeaver 配置为调用外部 MCP 服务器以获取模型/上下文服务。 QueryWeaver 提供的功能 - 该应用注册了专注于 Text2SQL 流程的 MCP 操作： - `list_databases` - `connect_database` - `database_schema` - `query_database` - 要禁用内置 MCP 端点，请在 `.env` 或环境中设置 `DISABLE_MCP=true`（默认：启用 MCP）。 - 配置 - `DISABLE_MCP` — 禁用 QueryWeaver 的内置 MCP HTTP 接口。设置为 `true` 以禁用。默认值：`false`（启用 MCP）。 示例 使用 Docker 运行时禁用内置 MCP： ``` docker run -p 5000:5000 -it --env DISABLE_MCP=true falkordb/queryweaver ``` 调用内置 MCP 端点（示例） - MCP 接口作为 HTTP 端点暴露。 ### 服务器配置 以下是一个最小的 `mcp.json` 客户端配置示例，目标是暴露在 `/mcp` 的本地 QueryWeaver 实例的 MCP HTTP 接口。 ``` { "servers": { "queryweaver": { "type": "http", "url": "http://127.0.0.1:5000/mcp", "headers": { "Authorization": "Bearer your_token_here" } } }, "inputs": [] } ``` ## REST API ### API 文档 Swagger UI: https://app.queryweaver.ai/docs OpenAPI JSON: https://app.queryweaver.ai/openapi.json ### 概述 QueryWeaver 暴露了一个小型 REST API，用于管理图（数据库 schema）和运行 Text2SQL 查询。所有修改或访问用户范围数据的端点都需要通过 Bearer token 进行身份验证。在浏览器中，应用使用会话 cookie 和 OAuth 流程；对于 CLI 和脚本，你可以使用 API token（请参阅 `tokens` 路由或 Web UI 来创建一个）。 核心端点 - GET /graphs — 列出经过身份验证的用户可用的图 - GET /graphs/{graph_id}/data — 返回图的节点/链接（表、列、外键） - POST /graphs — 上传或创建图（JSON 负载或文件上传） - POST /graphs/{graph_id} — 对命名的图运行 Text2SQL 聊天查询（流式响应） 身份验证 - 添加 Authorization header：`Authorization: Bearer ` 示例 1. 列出图 (GET) curl 示例： ``` curl -s -H "Authorization: Bearer $TOKEN" \ https://app.queryweaver.ai/graphs ``` Python 示例： ``` import requests resp = requests.get('https://app.queryweaver.ai/graphs', headers={'Authorization': f'Bearer {TOKEN}'}) print(resp.json()) ``` 2. 获取图 schema (GET) curl 示例： ``` curl -s -H "Authorization: Bearer $TOKEN" \ https://app.queryweaver.ai/graphs/my_database/data ``` Python 示例： ``` resp = requests.get('https://app.queryweaver.ai/graphs/my_database/data', headers={'Authorization': f'Bearer {TOKEN}'}) print(resp.json()) ``` 3. 加载图 (POST) — JSON 负载 ``` curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"database": "my_database", "tables": [...]}' \ https://app.queryweaver.ai/graphs ``` 或上传文件： ``` curl -H "Authorization: Bearer $TOKEN" -F "file=@schema.json" \ https://app.queryweaver.ai/graphs ``` 4. 查询图 (POST) — 运行基于聊天的 Text2SQL 请求 `POST /graphs/{graph_id}` 端点接受一个至少包含 `chat` 字段（消息数组）的 JSON 正文。该端点流式传输处理步骤和最终的 SQL，作为前端使用的特殊边界分隔的服务器发送消息块返回。对于简单的脚本编写，你可以调用它并从流式消息中读取最终的 JSON 对象。 示例负载： ``` { "chat": ["How many users signed up last month?"], "result": [], "instructions": "Prefer PostgreSQL compatible SQL" } ``` curl 示例（简单，收集完整响应）： ``` curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"chat": ["Count orders last week"]}' \ https://app.queryweaver.ai/graphs/my_database ``` Python 示例（支持流式）： ``` import requests import json url = 'https://app.queryweaver.ai/graphs/my_database' headers = {'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json'} with requests.post(url, headers=headers, json={"chat": ["Count orders last week"]}, stream=True) as r: # The server yields JSON objects delimited by a message boundary string boundary = '|||FALKORDB_MESSAGE_BOUNDARY|||' buffer = '' for chunk in r.iter_content(decode_unicode=True, chunk_size=1024): buffer += chunk while boundary in buffer: part, buffer = buffer.split(boundary, 1) if not part.strip(): continue obj = json.loads(part) print('STREAM:', obj) Notes & tips - Graph IDs are namespaced per-user. When calling the API directly use the plain graph id (the server will namespace by the authenticated user). For uploaded files the `database` field determines the saved graph id. - The streaming response includes intermediate reasoning steps, follow-up questions (if the query is ambiguous or off-topic), and the final SQL. The frontend expects the boundary string `|||FALKORDB_MESSAGE_BOUNDARY|||` between messages. - For destructive SQL (INSERT/UPDATE/DELETE etc) the service will include a confirmation step in the stream; the frontend handles this flow. If you automate destructive operations, ensure you handle confirmation properly (see the `ConfirmRequest` model in the code). ## 开发 Follow these steps to run and develop QueryWeaver from source. ### 先决条件 - Python 3.12+ - pipenv - A FalkorDB instance (local or remote) - Node.js and npm (for the React frontend) ### 安装和配置 Quickstart (recommended for development): ```bash # 克隆 repo git clone https://github.com/FalkorDB/QueryWeaver.git cd QueryWeaver # 安装依赖项（backend + frontend）并启动 dev server make install make run-dev ``` 如果你更喜欢手动设置或需要自定义环境，请使用 Pipenv： ``` # 安装 Python (backend) 和 frontend 依赖项 pipenv sync --dev # 创建本地环境文件 cp .env.example .env # 使用您的值编辑 .env（本地开发设置 APP_ENV=development） ``` ### 在本地运行应用 ``` pipenv run uvicorn api.index:app --host 0.0.0.0 --port 5000 --reload ``` 服务器将在 http://localhost:5000 上可用 或者，仓库提供了用于运行应用的 Make 目标： ``` make run-dev # development server (reload, debug-friendly) make run-prod # production mode (ensure frontend build if needed) ``` ### 前端构建（如需） 前端是位于 `app/` 中的现代 React + Vite 应用。在生产运行之前或前端更改后进行构建： ``` make install # installs backend and frontend deps make build-prod # builds the frontend into app/dist/ # 或者手动 cd app npm ci npm run build ``` ### OAuth 配置 QueryWeaver 支持 Google 和 GitHub OAuth。为每个提供商创建 OAuth 凭证，并将客户端 ID/密钥粘贴到 `.env` 文件中。 - Google：设置授权来源和回调 `http://localhost:5000/login/google/authorized` - GitHub：设置主页和回调 `http://localhost:5000/login/github/authorized` #### 特定环境的 OAuth 设置 对于生产/预发布部署，在环境中设置 `APP_ENV=production` 或 `APP_ENV=staging` 以启用安全会话 cookie（仅限 HTTPS）。这可以防止 OAuth CSRF 状态不匹配错误。 ``` # 用于生产/预发布环境（启用仅 HTTPS 会话 cookies） APP_ENV=production # 用于开发环境（允许 HTTP 会话 cookies） APP_ENV=development ``` **重要**：如果你在预发布/生产环境中遇到 "mismatching_state: CSRF Warning!" 错误，请确保将 `APP_ENV` 设置为 `production` 或 `staging` 以启用安全会话处理。 ### AI/LLM 配置 QueryWeaver 使用 AI 模型进行 Text2SQL 转换，并同时支持 Azure OpenAI 和直接使用 OpenAI。 #### 默认：Azure OpenAI 默认情况下，QueryWeaver 配置为使用 Azure OpenAI。你需要设置所有三个 Azure 凭证： ``` AZURE_API_KEY=your_azure_api_key AZURE_API_BASE=https://your-resource.openai.azure.com/ AZURE_API_VERSION=2024-12-01-preview ``` #### 替代方案：直接使用 OpenAI 要直接使用 OpenAI 而不是 Azure，只需设置 `OPENAI_API_KEY` 环境变量： ``` OPENAI_API_KEY=your_openai_api_key ``` 当提供 `OPENAI_API_KEY` 时，QueryWeaver 会自动切换为使用 OpenAI 的模型： - Embedding 模型：`openai/text-embedding-ada-002` - Completion 模型：`openai/gpt-4.1` 此配置在 `api/config.py` 中自动处理 — 你只需提供相应的 API key。 #### 包含 AI 配置的 Docker 示例 使用 Azure OpenAI： ``` docker run -p 5000:5000 -it \ -e FASTAPI_SECRET_KEY=your_secret_key \ -e AZURE_API_KEY=your_azure_api_key \ -e AZURE_API_BASE=https://your-resource.openai.azure.com/ \ -e AZURE_API_VERSION=2024-12-01-preview \ falkordb/queryweaver ``` 直接使用 OpenAI： ``` docker run -p 5000:5000 -it \ -e FASTAPI_SECRET_KEY=your_secret_key \ -e OPENAI_API_KEY=your_openai_api_key \ falkordb/queryweaver ``` ## 测试 ### 前置条件 - 安装开发依赖：`pipenv sync --dev` - 启动 FalkorDB（参见 `make docker-falkordb`） - 安装 Playwright 浏览器：`pipenv run playwright install` ### 快速命令 推荐：使用 Make 辅助工具准备开发/测试环境（安装依赖和 Playwright 浏览器）： ``` # 准备开发/测试环境（安装 deps 和 Playwright browsers） make setup-dev ``` 或者，你可以运行 E2E 专用设置脚本，然后手动运行测试： ``` # 准备 E2E 测试环境（安装 browsers 及其他设置） ./setup_e2e_tests.sh # 运行所有测试 make test # 仅运行单元测试（更快） make test-unit # 运行 E2E 测试（headless） make test-e2e # 运行 E2E 测试并显示浏览器以便调试 make test-e2e-headed ``` ### 测试类型 - 单元测试：侧重于单个模块和实用程序。使用 `make test-unit` 或 `pipenv run pytest tests/ -k "not e2e"` 运行。 - 端到端 (E2E) 测试：通过 Playwright 运行，并演练 UI 流程、OAuth、文件上传、schema 处理、聊天查询和 API 端点。使用 `make test-e2e`。 有关完整的 E2E 测试说明，请参见 `tests/e2e/README.md`。 ### CI/CD GitHub Actions 会在推送和 Pull Request 时运行单元测试和 E2E 测试。失败时会捕获屏幕截图和构建产物以供调试。 ## 故障排除 - FalkorDB 连接问题：启动数据库辅助工具 `make docker-falkordb` 或检查网络/主机设置。 - Playwright/浏览器失败：使用 `pipenv run playwright install` 安装浏览器，并确保系统依赖项存在。 - 缺少环境变量：复制 `.env.example` 并填写必需的值。 - **OAuth "mismatching_state: CSRF Warning!" 错误**：对于 HTTPS 部署，在环境中设置 `APP_ENV=production`（或 `staging`），对于 HTTP 开发环境设置 `APP_ENV=development`。这可确保会话 cookie 针对你的部署类型正确配置。 ## 项目布局（高级） - `api/` – FastAPI 后端 - `app/` – React + Vite 前端 - `tests/` – 单元和 E2E 测试 ## 许可证 根据 GNU Affero General Public License (AGPL) 授权。详见 [LICENSE](LICENSE.txt)。 版权所有 FalkorDB Ltd. 2025

标签：AI辅助, AV绕过, DLL 劫持, Docker, FalkorDB, FastAPI, MCP, Python, RAG, REST API, Schema理解, SQL生成, Swagger, Text2SQL, Text-to-SQL, 低代码, 大语言模型, 安全防御评估, 开源, 数据库工具, 数据查询, 无后门, 查询构建器, 特征检测, 网络测绘, 自动化攻击, 自动化攻击, 语义理解, 请求拦截, 逆向工具