技术规格
带有AI视觉的现代RAG架构。
架构概览
ManualNinja是一个多租户RAG应用程序，具有Python后端、React SPA前端、PostgreSQL数据库和Qdrant向量存储。PDF被解析、分块、嵌入，并通过聊天界面作为引用答案提供。平台现在包括AI视觉图像分析、OAuth社交登录和Stripe订阅计费。
后端API
FastAPI + Uvicorn（Python 3.13）。用于认证、手册、聊天、计费和管理的REST端点。基于JWT的OAuth2认证。
前端
React 18 + Vite。具有聊天UI、管理面板、计费门户和超级管理仪表板的单页应用程序。
数据库
PostgreSQL 17。存储组织、用户、手册、聊天会话、使用量跟踪和可配置设置。
向量存储
Qdrant 1.19。具有组织范围过滤的手册块语义搜索。
嵌入
BAAI/bge-small-en-v1.5 (384 dimensions, CPU). Local inference — no external embedding API calls.
LLM（文本）
OpenAI兼容API。默认模型：deepseek/deepseek-v3-0324。可通过超级管理仪表板配置。
想要本地AI以保安全？没问题。 联系我们
LLM（视觉）
Novita AI vision model — google/gemma-3-27b-it. Analyzes uploaded images (device labels, error screens, nameplates) with OCR and structured extraction.
PDF提取
PyMuPDF（fitz）。保留元数据的页面级分块以实现准确引用。
Web URL ingestion
Add manuals by URL instead of uploading a PDF. ManualNinja fetches the page, follows pagination across all sub-pages, and extracts the full manual text. SSRF-protected (internal IPs blocked), 50 MB per page limit, up to 200 pages per manual.
认证
JWT令牌 + Google OAuth 2.0 + LinkedIn OAuth 2.0（OpenID Connect）。可配置SMTP的邮件验证。
支付
Stripe — recurring subscriptions via Checkout, customer portal for self-service management, webhook-driven lifecycle events.
反向代理
Caddy — automatic HTTPS via Let’s Encrypt, HTTP/2, HTTP/3 support.
多租户 & 隔离
每个客户组织获得完全隔离的工作空间：
- 组织范围的客户、手册和聊天会话
- Qdrant payloads include org_id — vector search is always filtered
- 基于套餐的限制：每月问题数、存储、问题长度、手册数量
- 所有集成密钥（Stripe、Google、LinkedIn、LLM、SMTP、reCAPTCHA）可通过管理UI按部署配置
安全 & 数据保护
ManualNinja以安全为首要优先级构建。堆栈的每一层都经过加固以保护您的数据和客户信任。
端到端加密
所有流量通过Caddy和自动Let’s Encrypt证书以TLS 1.2/1.3通过HTTPS提供。不接受明文连接。
安全认证
基于JWT的强密钥认证、bcrypt密码哈希、带CSRF保护的OAuth 2.0，以及使用短效交换码而非URL中的令牌。
暴力破解保护
登录速率限制（每IP每5分钟10次尝试）、注册速率限制（每IP每天3次）和公开注册时强制Google reCAPTCHA。
多租户隔离
Every database query and vector search is scoped by organization_id. No cross-tenant data leakage is possible — your manuals and chats are yours alone.
安全文件上传
PDF uploads are validated by magic bytes, content type, and a 50 MB hard size limit. Files are stored with UUID names — no path traversal possible.
已验证Webhook
Stripe payment webhooks are always signature-verified. No unauthenticated payment events are ever processed — the system fails closed if the secret is missing.
仅内部服务
The FastAPI backend and Qdrant vector database bind to 127.0.0.1 only. They are never directly accessible from the internet — all external traffic goes through the Caddy reverse proxy.
邮件验证
注册需要带有时效令牌（24小时过期）的邮件验证。未验证账户无法登录。
审计日志
All admin and superadmin actions — organization creation, user management, settings changes — are logged to a dedicated audit trail for accountability and compliance.