WiseCoderSam/rag-document-qa-system

# 企业日志监控与威胁检测平台 一个由 AI 驱动的 SOC 风格平台，可摄取应用程序、服务器和安全日志，通过基于规则的检测发现可疑活动，并支持使用检索增强生成 (RAG) 进行调查。 ## 仓库结构 - `frontend/` - Vite (React, TypeScript, Tailwind CSS, @base-ui/react) 应用程序。 - `backend/` - FastAPI (Python, SQLAlchemy, Alembic, FAISS, Google Gemini) 应用程序。 ## 前置条件 - [Node.js](https://nodejs.org/) (v18+) - [Python](https://www.python.org/) (v3.10+) - [Google Gemini API key](https://ai.google.dev/) — 用于 embeddings 和聊天/摘要。如果没有，应用程序仍可运行，但 AI 功能将返回“未配置”消息，且 embeddings 将回退为零向量。 - [Supabase 账户](https://supabase.com/)（用于 Auth 和 Storage；关系型数据库默认为本地 SQLite 文件 — 见下文） ## 快速开始 ### 1. 后端设置 1. 导航到 `backend/` 目录。 2. 创建虚拟环境：`python -m venv venv`。 3. 激活环境：`venv\Scripts\activate` (Windows) 或 `source venv/bin/activate` (Mac/Linux)。 4. 安装依赖：`pip install -r requirements.txt`。 5. 根据 `.env.example` 创建 `.env` 文件，并至少设置 `SUPABASE_URL`、`SUPABASE_KEY`、`SUPABASE_JWT_SECRET` 和 `GEMINI_API_KEY`。 6. 执行数据库迁移：`alembic upgrade head`。 7. 启动 FastAPI 服务器：`uvicorn app.main:app --reload`。 ### 2. 前端设置 1. 导航到 `frontend/` 目录。 2. 安装依赖：`npm install`。 3. 根据 `.env.example` 创建 `.env.local` 文件。 4. 启动开发服务器：`npm run dev`。 ## 运行测试 - 后端：`pip install -r backend/requirements-dev.txt`，然后运行 `pytest backend/test_parser_rules.py backend/test_rag.py`（其他 `backend/test_*.py` 文件是用于针对实时服务器运行的手动验证脚本，而不是 pytest 套件）。 - 前端：在 `frontend/` 目录下运行 `npm run test`。 - 两者均会在每次 push/PR 时在 CI 中自动运行 — 参见 `.github/workflows/ci.yml`。 ## 部署 前端和后端部署在不同类型的平台上，因为它们具有不同的 runtime 需求 — 前端是静态/无状态的，而后端需要常驻进程（用于日志/文档处理的进程内后台任务）以及真正的数据库。 - **前端 → [Vercel](https://vercel.com)。** 导入仓库，将项目根目录设置为 `frontend/`，并设置以下环境变量：`VITE_API_URL`（您部署的后端 URL）、`VITE_SUPABASE_URL`、`VITE_SUPABASE_ANON_KEY`。Vercel 会自动检测 Vite 构建；无需额外配置。 - **后端 → [Render](https://render.com)**（或 Railway/Fly.io — 任何可以运行长期 Docker container 的平台）。本仓库包含 `render.yaml`：将其作为 [Render Blueprint](https://dashboard.render.com/blueprints) 导入，它会自动从 `backend/Dockerfile` 配置服务。您仍需通过 Render 控制面板自行粘贴密钥（`DATABASE_URL`、`SUPABASE_URL`、`SUPABASE_KEY`、`SUPABASE_JWT_SECRET`、`GEMINI_API_KEY`、`ALLOWED_ORIGINS`）。 - **数据库 → Supabase Postgres**，而不是本地的 SQLite 回退方案。免费托管层级（包括 Render 的免费层）不保证在重新部署/重启后磁盘数据持久化，因此 SQLite 文件会悄无声息地丢失数据 — 请改用您 Supabase 项目的 Postgres 连接字符串（项目设置 → Database → Connection string → URI）作为 `DATABASE_URL`，并在首次使用前针对它运行一次 `alembic upgrade head`。 ## 演示模式 认证页面可以显示一键式 **“探索实时演示”** 按钮，以便访客（例如招聘人员）无需注册即可浏览预加载了事件数据的控制台。要启用此功能： 1. **创建演示账户**：在 Supabase 控制面板（Authentication → Users → Add user）中，创建例如 `demo@yourdomain.com` 并设置密码，勾选“Auto Confirm User” — 或者通过应用程序注册并确认电子邮件。 2. **使用示例数据填充**：`backend/sample_data/` 包含一个精心制作的安全日志（一个连贯的暴力破解 → 权限提升 → 凭据转储攻击，会触发每一条检测规则）以及一个用于文档问答的事件响应剧本。通过真实的 API 上传它们，命令如下： cd backend python seed_demo.py --email demo@yourdomain.com --password --api-url https://your-api.onrender.com （省略 `--api-url` 可填充本地运行的后端。）重新运行时会跳过已上传的文件。 3. **显示按钮**：在前端环境中设置 `VITE_DEMO_EMAIL` 和 `VITE_DEMO_PASSWORD`（Vercel 环境变量，或在本地使用 `.env.local`）。这些变量按设计会被构建到公共 bundle 中 — 演示账户是公开的。只有当两者都设置后，按钮才会显示。 注意：演示账户是一个普通账户 — 访客可以删除预置的文件或上传他们自己的文件。如果发生这种情况，只需重新运行填充脚本即可。 ## 当前架构 本节描述了实际实现的内容，与 `tech.md`/`prd.md` 中最初的挑战目标计划相对。 - **数据库**：通过 `DATABASE_URL` 使用 SQLAlchemy（默认使用本地 SQLite 文件以实现零配置的本地开发）。在生产环境中，它应指向 Supabase Postgres — 参见上文“部署” — 否则 Supabase 仅用于 Auth 和 Storage。 - **后台处理**：FastAPI `BackgroundTasks`（进程内），而不是单独的任务队列。没有 Celery/Redis 依赖。 - **向量搜索**：单个进程内的 FAISS `IndexFlatIP`，持久化到磁盘。这是一种单实例设计 — 它不支持针对共享索引运行多个后端副本。 - **AI**：Google Gemini（`gemini-embedding-001` 用于 embeddings，`gemini-2.5-flash` 用于聊天/摘要），而不是本地托管的模型。这意味着 AI 功能需要互联网连接和 Gemini API key。 - **监控**：未集成 Grafana/Prometheus/Sentry。日志记录通过 `print()`/stdout 进行。 ## 已知局限性 - FAISS 索引和 SQLite 数据库都是单进程/单文件 — 这是一个适用于开发/作品集规模的配置，不支持水平扩展。 - 检测规则目前涵盖暴力登录、SQL/XSS 注入特征、权限提升、可疑的 PowerShell 以及凭据转储关键字匹配。更广泛的覆盖范围（不可能的旅行、端口扫描、勒索软件模式、Sigma/YARA 集成）尚未实现。

标签：AMSI绕过, AV绕过, FAISS, FastAPI, RAG, React, Syscalls, 威胁检测, 安全运营中心, 测试用例, 网络映射, 逆向工具