Smitvd22/ClustralAI

# 安全优先的RAG系统 一个加固安全的检索增强生成API。摄取PDF文档，用引文回答问题，并防御提示注入、数据泄露和PII泄露。 ## 部署平台变更 该项目最初是为部署在Azure（利用Azure Container Apps、Key Vault和Blob Storage）而设计的。然而，由于Azure订阅和账户限制，**它已完全迁移到Render**。 迁移保留了相同的网络安全目标和架构原则，同时适应Render的部署生态系统。 ## 架构 ``` graph LR U([User]) -->|HTTPS| RL[Rate Limiter] RL --> AUTH[API Key Auth] AUTH --> PG[Prompt Guard] PG --> EG[Exfil Guard] EG --> EMB[Embeddings
MiniLM-L6-v2] EMB --> RET[Retriever
ChromaDB Top-3] RET --> IIG[Indirect
Injection Check] IIG --> LLM[Gemini 2.0 Flash] LLM --> OF[Output Filter] OF --> U ``` **栈**：FastAPI · ChromaDB · sentence-transformers · Gemini Free API · Render Web Service ## 快速入门 ``` # 克隆并配置 cp .env.example .env # 编辑 .env：设置 GEMINI_API_KEY 和 APP_API_KEYS # 使用 Docker 运行 docker-compose -f docker/docker-compose.yml up --build # 生成示例 PDF 文件 pip install fpdf2 && python scripts/generate_sample_pdfs.py # 导入文档 curl -X POST http://localhost:8000/ingest \ -H "X-API-Key: YOUR_KEY" \ -F "files=@sample_pdfs/employee_handbook.pdf" # 查询 curl -X POST http://localhost:8000/query \ -H "X-API-Key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"question": "What is the refund policy?"}' ``` ## 安全功能 * **提示注入防御**：12+正则表达式模式，带加权评分阻止直接注入尝试。 * **越狱保护**：检测DAN/开发者模式激活。 * **数据泄露保护**：阻止批量请求模式和枚举尝试。 * **间接提示注入检查**：在发送到LLM之前分析文档内容，防止文档内嵌攻击。 * **PII屏蔽**：对电子邮件、电话、SSN和信用卡进行通用的NER替换。 * **速率限制**：API滥用预防（每分钟10次查询，每分钟5次摄取）。 * **身份验证**：API密钥身份验证，使用恒定时间比较以防止时间侧信道攻击。 * **输出过滤**：在返回给用户之前进行最终的正则表达式扫描，以捕获泄露的秘密/PII。 ## 密钥管理 密钥（如Gemini API密钥和内部App API密钥）使用**Render环境变量**进行管理。密钥在运行时安全地注入到应用程序容器中。密钥永远不会硬编码在代码库中，并且在所有日志输出中都会屏蔽敏感字段。 ## 日志和监控 应用程序使用标准的Python结构化日志，直接流到**Render日志**。在日志子系统应用全局PII屏蔽过滤器——确保即使在发生错误的情况下，原始PII或秘密值也永远不会记录到Render仪表板。 ## 存储策略 上传的PDF完全在内存中进行文本提取和分块处理。它们永远不会保存到公共或可访问的本地磁盘目录。 提取的嵌入保存到ChromaDB。ChromaDB持久性映射到本地文件系统（`./chroma_data`）。 ## 剩余限制 * **免费层上的短暂存储**：Render免费层Web服务不支持持久磁盘。因此，`chroma_data`目录是短暂的。任何摄取的数据在容器重启或部署后都会丢失。对于生产使用，需要付费的Render Starter计划来将持久磁盘附加到`/chroma_data`路径。 ## 威胁模型 | 威胁 | 风险 | 缓解措施 | |------|------|------------| | 提示注入 | 高 | 12+正则表达式模式，加权评分，加固的系统提示 | | 间接提示注入 | 高 | 文档扫描，安全分隔符，系统提示规则 | | 越狱 | 高 | DAN/开发者模式检测，输出过滤 | | 数据泄露 | 高 | 8+泄露模式，批量请求阻止 | | 秘密泄露 | 严重 | 输出过滤器中的9+秘密模式，完全响应阻止 | | 未授权访问 | 严重 | API密钥，恒定时间验证 | | 滥用 | 中 | 速率限制（每分钟10次查询，每分钟5次摄取），按IP | | PII泄露 | 高 | 全局日志屏蔽，输出擦除 | ### 剩余风险 **对抗性嵌入攻击**：具有上传访问权限的攻击者可以构建与目标查询具有高余弦相似度的内容，但包含错误信息。缓解需要跨文档验证和内容完整性哈希（未来工作）。 ## Azure到Render映射 | Azure组件 | Render等效 | 权衡 | |------------|-------------------|------------| | Azure App Service / Container Apps | Render Web Service | 通过Docker提供类似的部署便捷性。 | | Azure Key Vault | Render环境变量 | 环境变量更简单，但缺乏Key Vault的高级轮换和审计日志。 | | Azure Monitor | Render日志 | 标准的stdout流代替OpenTelemetry。 | | Azure Blob Storage | 内存中PDF处理 | 不保留长期原始文档存储，减少攻击面。 | | Managed Identity | 基于环境变量的访问 | 设置更简单，但需要手动环境变量同步。 | ## API端点 | 方法 | 路径 | 认证 | 描述 | |--------|------|------|-------------| | POST | `/ingest` | ✅ | 上传PDF，构建向量索引 | | POST | `/query` | ✅ | 提问，获取有引文的答案 | | GET | `/health` | ❌ | 组件健康检查 | | GET | `/security-status` | ❌ | 安全功能清单 | ## 测试 ``` pip install -r requirements.txt pytest tests/ -v ``` ## Render部署 要将应用程序部署到Render，您可以将此存储库连接到您的Render仪表板并创建一个新的**Web Service**。 或者，使用提供的`render.yaml`作为蓝图： 1. 在Render仪表板中，转到**蓝图**。 2. 连接您的存储库。 3. Render将自动检测`render.yaml`并配置Web Service。 4. 在仪表板中提供您的`GEMINI_API_KEY`和`APP_API_KEYS`环境变量。 有关完整架构细节，请参阅[docs/architecture.md](