QusaiALBahri/imageOSINT

# ImageOSINT ## 🎯 概述 **ImageOSINT** 是一个适用于高级图像分析的生产级分布式 OSINT（开源情报）平台。它结合了反向图像搜索、EXIF 元数据提取、地理定位分析和 Google Maps 智能信息收集，形成一个可扩展的 Web 应用程序。 基于 **FastAPI**、**PostgreSQL**、**Redis** 和 **Celery** 构建，ImageOSINT 以异步方式大规模处理图像分析任务，支持实时作业监控、智能缓存和全面的结果持久化。 ## ✨ 功能 ### 🔎 **反向图像搜索** - **多引擎搜索**：同时搜索 Google、Bing、Yandex - **并行处理**：并发查询多个引擎以加快结果返回 - **结果缓存**：24 小时缓存以减少 API 调用 - **搜索历史**：跟踪和管理之前的搜索记录 - **智能去重**：自动消除重复结果 ### 📷 **EXIF 元数据提取** - **完整元数据解析**：提取 100 多个 EXIF 字段 - **GPS 坐标检测**：自动从图像中提取 GPS 信息 - **相机识别**：分析相机型号、镜头和设置 - **时间戳分析**：创建日期和修改时间跟踪 - **格式检测**：识别图像类型和压缩数据 - **高级分析**：基于哈希的图像识别 ### 📍 **地理定位智能** - **反向地理编码**：GPS 坐标 → 街道地址 - **正向地理编码**：地点名称 → 精确坐标 - **精度估算**：为位置数据提供置信度评分 - **位置缓存**：7 天缓存地理定位结果 - **基于半径的搜索**：在指定距离内查找地点 - **多源验证**：交叉引用多个来源 ### 🗺️ **Google 地图抓取** - **附近地点搜索**：餐厅、酒店、景点 - **基于类别的查询**：按业务类型过滤 - **街景视图元数据**：提取视觉验证数据 - **智能缓存**：7 天缓存地图数据 - **半径分析**：可配置的搜索距离 - **地点详情**：全面的商业信息 ### 📊 **企业级后端** - **异步任务处理**：基于 Celery 的分布式队列 - **实时监控**：0-100% 进度跟踪的作业状态 - **结果持久化**：具有事务安全性的 PostgreSQL 存储 - **多级缓存**：Redis + 内存后备缓存 - **用户管理**：注册、登录、JWT 认证 - **API 密钥支持**：用于集成的长寿命程序化访问 - **速率限制**：内置请求节流 - **健康检查**：全面的服务监控 ### 📈 **可扩展性与性能** - **水平扩展**：可随时扩展工作进程池 - **连接池**：优化的数据库连接 - **并行处理**：并发图像分析 - **负载均衡**：适用于生产环境的负载分发 - **性能指标**：详细的分析和统计 - **自动清理**：计划维护任务 ### 🔐 **安全与认证** - **JWT 令牌**：基于令牌的安全认证 - **密码哈希**：使用盐的 Bcrypt - **API 密钥**：长寿命的程序化访问令牌 - **CORS 配置**：灵活的跨域支持 - **SQL 注入防护**：基于 ORM 的查询安全 - **速率限制**：DDoS 缓解 - **请求验证**：基于 Pydantic 的模式验证 - **安全标头**：支持 HTTPS，配置了安全标头 - **审计日志**：完整的请求/响应日志 - **数据加密**：支持加密的数据库连接 ### 🎨 **现代用户界面** - **Gradio 界面**：交互式 Web 前端 - **实时更新**：实时作业状态监控 - **多标签布局**：有序的工作流 - **API 文档**：自动生成的 OpenAPI 文档 - **Swagger UI**：交互式 API 测试 - **ReDoc**：美观的 API 文档 ### 📦 **部署** - **Docker 支持**：生产就绪的容器 - **Docker Compose**：单命令编排 - **6 服务堆栈**：PostgreSQL、Redis、API、Worker、Beat、前端 - **健康检查**：自动服务监控 - **卷持久化**：数据持久性 - **开发模式**：开发期间的热重载 ## 🚀 快速开始 ### 选项 1：Docker Compose（推荐） ``` # 克隆仓库 git clone https://github.com/QusaiALBahri/imageOSINT.git cd imageOSINT # 启动所有服务 docker-compose up -d # 服务地址： # 前端: http://localhost:7860 # API 文档: http://localhost:8000/api/docs # 监控: http://localhost:5555 ``` ### 选项 2：手动安装 ``` # 安装依赖 pip install -r requirements-backend.txt # 启动 PostgreSQL（Docker） docker run -d -p 5432:5432 \ -e POSTGRES_PASSWORD=osint_password postgres:15-alpine # 启动 Redis（Docker） docker run -d -p 6379:6379 redis:7-alpine # 初始化数据库 python -c "from database.init_db import init_db; init_db()" # 启动服务（在独立终端） uvicorn backend.server:app --reload # Terminal 1: API celery -A tasks.celery worker # Terminal 2: Worker celery -A tasks.celery beat # Terminal 3: Scheduler python app_backend.py # Terminal 4: Frontend ``` ### 选项 3：开发快速启动 ``` # 使用开发 Docker Compose docker-compose -f docker-compose.dev.yml up -d # 特性： # - 热代码重载 # - 调试日志 # - 所有端点可访问 ``` ## 📋 访问点 | 服务 | URL | 用途 | |---------|-----|---------| | **前端** | http://localhost:7860 | Gradio Web 界面 | | **API 文档** | http://localhost:8000/api/docs | 交互式 Swagger UI | | **API ReDoc** | http://localhost:8000/api/redoc | 美观的文档 | | **健康检查** | http://localhost:8000/health | API 状态 | | **任务监控** | http://localhost:5555 | Celery Flower UI | ## 🏗️ 架构 ### 系统设计 ``` ┌─────────────────────────────────────────────────────────┐ │ Client Applications │ │ (Gradio Frontend / External API Clients) │ └────────────────────┬────────────────────────────────────┘ │ ▼ ┌────────────────────────────┐ │ FastAPI Server (8000) │ │ - JWT Authentication │ │ - Request Validation │ │ - Response Formatting │ └────────┬───────────────────┘ │ ┌────────┴──────────┬──────────────┐ ▼ ▼ ▼ ┌────────────┐ ┌──────────────┐ ┌──────────┐ │ PostgreSQL │ │ Redis │ │ Celery │ │ Database │ │ Cache │ │ Workers │ └────────────┘ └──────────────┘ └─────┬────┘ │ ┌────────┴────────┐ ▼ ▼ ┌──────────────┐ ┌────────────┐ │ Celery │ │ Scheduled │ │ Beat │ │ Tasks │ └──────────────┘ └────────────┘ ``` ### 技术栈 | 组件 | 技术 | 版本 | 用途 | |-----------|-----------|---------|---------| | **框架** | FastAPI | 0.104.1 | REST API 服务器 | | **异步队列** | Celery | 5.3.4 | 任务分发 | | **消息代理** | Redis | 7 | 缓存与任务队列 | | **数据库** | PostgreSQL | 15 | 主数据存储 | | **ORM** | SQLAlchemy | 2.0.23 | 数据库抽象 | | **验证** | Pydantic | 2.5.0 | 请求/响应验证 | | **认证** | Python-jose | 3.3.0 | JWT 令牌 | | **密码** | Passlib | 1.7.4 | Bcrypt 哈希 | | **前端** | Gradio | 4.36.1 | Web 界面 | | **监控** | Flower | 2.0.1 | 任务监控 | | **容器** | Docker | 最新 | 容器化 | ### 数据库架构 ``` -- 7 Core Tables UserAccount -- User authentication & profiles APIKey -- API key management for programmatic access AnalysisJob -- Image analysis job tracking (status, progress) SearchHistory -- Reverse image search history CachedResult -- Result caching with TTL LocationAnalysis -- Geolocation data & reverse geocoding results ImageMetadata -- EXIF and image metadata storage ``` ### API 端点（30+） **认证** ``` POST /api/auth/register -- User registration POST /api/auth/login -- User login GET /api/auth/verify -- Token verification ``` **图像分析** ``` POST /api/analyze -- Submit image analysis job GET /api/analyze/{job_id} -- Get job status & progress GET /api/analyze/{job_id}/results -- Get analysis results ``` **反向图像搜索** ``` POST /api/search/reverse -- Reverse search image GET /api/search/history -- Get search history ``` **位置分析** ``` POST /api/location/analyze -- Analyze GPS coordinates POST /api/maps/nearby -- Search nearby places ``` **任务管理** ``` GET /api/tasks/{task_id} -- Task status GET /api/tasks/{task_id}/results -- Task results ``` **缓存与统计** ``` GET /api/cache/stats -- Cache statistics DELETE /api/cache -- Clear cache GET /api/stats -- User statistics GET /health -- Health check ``` ## 💻 API 示例 ### Python 客户端 ``` import requests import json BASE_URL = "http://localhost:8000" # 1. 注册 register_response = requests.post( f"{BASE_URL}/api/auth/register", json={ "email": "user@example.com", "username": "testuser", "password": "SecurePass123!" } ) token = register_response.json()["access_token"] # 2. 提交分析 analysis_response = requests.post( f"{BASE_URL}/api/analyze", headers={"Authorization": f"Bearer {token}"}, files={"file": open("image.jpg", "rb")}, data={"analysis_types": ["metadata", "search", "location", "maps"]} ) job_id = analysis_response.json()["job_id"] # 3. 检查状态 status_response = requests.get( f"{BASE_URL}/api/analyze/{job_id}", headers={"Authorization": f"Bearer {token}"} ) print(f"Progress: {status_response.json()['progress']}%") # 4. 获取结果 results_response = requests.get( f"{BASE_URL}/api/analyze/{job_id}/results", headers={"Authorization": f"Bearer {token}"} ) print(json.dumps(results_response.json(), indent=2)) ``` ### JavaScript 客户端 ``` const BASE_URL = "http://localhost:8000"; async function analyzeImage() { // Register const registerRes = await fetch(`${BASE_URL}/api/auth/register`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ email: "user@example.com", username: "testuser", password: "SecurePass123!" }) }); const { access_token } = await registerRes.json(); // Submit analysis const formData = new FormData(); formData.append("file", imageFile); formData.append("analysis_types", [...selectedTypes]); const analysisRes = await fetch(`${BASE_URL}/api/analyze`, { method: "POST", headers: { "Authorization": `Bearer ${access_token}` }, body: formData }); const { job_id } = await analysisRes.json(); // Poll status const statusRes = await fetch(`${BASE_URL}/api/analyze/${job_id}`, { headers: { "Authorization": `Bearer ${access_token}` } }); console.log(await statusRes.json()); } ``` ### cURL 示例 ``` # 注册 curl -X POST http://localhost:8000/api/auth/register \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "username": "testuser", "password": "SecurePass123!" }' # 提交分析 curl -X POST http://localhost:8000/api/analyze \ -H "Authorization: Bearer YOUR_TOKEN" \ -F "file=@image.jpg" \ -F "analysis_types=metadata" \ -F "analysis_types=search" \ -F "analysis_types=location" \ -F "analysis_types=maps" # 检查状态 curl -X GET http://localhost:8000/api/analyze/{job_id} \ -H "Authorization: Bearer YOUR_TOKEN" # 获取结果 curl -X GET http://localhost:8000/api/analyze/{job_id}/results \ -H "Authorization: Bearer YOUR_TOKEN" ``` ## 📊 性能 | 操作 | 耗时 | 说明 | |-----------|------|-------| | 元数据提取 | ~100ms | 本地处理 | | 反向搜索（每个引擎） | 2-3s | Google/Bing/Yandex | | 位置分析 | 1-2s | 反向地理定位 | | 地图抓取 | 2-3s | 附近地点搜索 | | **总流程** | 8-12s | 并行化任务 | | **缓存命中** | <100ms | Redis 查询 | ### 优化技术 - **并行任务执行**：元数据 + 搜索 + 位置 + 地图并发运行 - **结果缓存**：24 小时搜索缓存，7 天位置/地图缓存 - **数据库连接池**：连接池大小 20，溢出 40 - **工作进程并发**：默认 4 个工作进程，可扩展 - **自动重试**：失败任务自动重试 ## 🔐 安全特性 - ✅ **JWT 认证**：基于令牌的身份验证 - ✅ **密码哈希**：使用盐的 Bcrypt - ✅ **SQL 注入防护**：SQLAlchemy ORM 参数化 - ✅ **CORS 策略**：可配置的跨域请求 - ✅ **速率限制**：请求节流（默认 1 请求/秒） - ✅ **输入验证**：Pydantic 模式验证 - ✅ **API 密钥支持**：长寿命令牌用于程序化访问 - ✅ **安全标头**：支持 HTTPS，配置安全标头 - ✅ **审计日志**：完整的请求/响应日志 - ✅ **数据加密**：支持加密的数据库连接 ## 📦 项目结构 ``` imageOSINT/ ├── backend/ │ ├── __init__.py │ └── server.py # FastAPI application (1,200 LOC) │ ├── database/ │ ├── __init__.py │ ├── models.py # SQLAlchemy ORM models │ ├── session.py # Database connection management │ ├── schemas.py # Pydantic validation schemas │ └── init_db.py # Database initialization │ ├── core/ │ ├── __init__.py │ ├── config.py # Configuration management │ ├── auth.py # Authentication & security │ └── cache.py # Redis caching layer │ ├── tasks/ │ ├── __init__.py │ ├── celery.py # Celery configuration │ └── celery_tasks.py # Async task definitions │ ├── modules/ │ ├── metadata_extractor.py # EXIF extraction │ ├── location_extractor.py # Geolocation & reverse geocoding │ ├── image_search.py # Reverse image search │ ├── maps_scraper.py # Google Maps scraping │ └── utils.py # Utility functions │ ├── app_backend.py # Gradio frontend (API client) ├── app.py # Original standalone Gradio │ ├── docker-compose.yml # Production orchestration ├── docker-compose.dev.yml # Development orchestration ├── Dockerfile # API server container ├── Dockerfile.worker # Celery worker container │ ├── .env.example # Environment template ├── requirements.txt # Original dependencies ├── requirements-backend.txt # Backend dependencies │ ├── README.md # This file ├── DEPLOYMENT.md # Production deployment guide ├── BACKEND_SETUP.md # Architecture & setup ├── ARCHITECTURE.md # Detailed architecture docs │ ├── uploads/ # User uploaded images ├── outputs/ # Analysis results & reports └── .gitignore # Git ignore rules ``` ## 🛠️ 配置 ### 环境变量 复制 `.env.example` 到 `.env` 并进行配置： ``` # 应用程序 APP_NAME=ImageOSINT API_HOST=0.0.0.0 API_PORT=8000 DEBUG=False # 数据库（选择一个：sqlite、postgresql、mysql） DATABASE_TYPE=postgresql DATABASE_URL=postgresql://osint_user:osint_password@localhost:5432/osint_db # Redis 与缓存 REDIS_URL=redis://localhost:6379 CACHE_TTL=86400 # Celery CELERY_BROKER=redis://localhost:6379/0 CELERY_BACKEND=redis://localhost:6379/0 # 安全 JWT_SECRET=your_super_secret_key_change_in_production JWT_ALGORITHM=HS256 TOKEN_EXPIRY=1800 # 文件上传 MAX_FILE_SIZE=104857600 # 100MB ALLOWED_FORMATS=.jpg,.jpeg,.png,.gif,.webp # 速率限制 RATE_LIMIT_DELAY=1 REQUEST_TIMEOUT=30 # CORS CORS_ORIGINS=http://localhost:3000,http://localhost:7860 # 工作进程配置 WORKERS_COUNT=4 THREADS_PER_WORKER=1 ``` ## 📚 文档 | 文档 | 用途 | |----------|---------| | [DEPLOYMENT.md](DEPLOYMENT.md) | 生产部署、扩展、监控 | | [BACKEND_SETUP.md](BACKEND_SETUP.md) | 后端架构、数据库模式、API 参考 | | [ARCHITECTURE.md](ARCHITECTURE.md) | 系统设计、数据流、组件概述 | | [API Docs](http://localhost:8000/api/docs) | 交互式 Swagger 文档（运行时可用） | ## 🧪 测试 ### 运行测试 ``` # 单元测试 pytest tests/ -v # 覆盖率 pytest tests/ --cov=backend --cov=core --cov=database --cov=tasks # 集成测试 pytest tests/integration/ -v # API 测试 pytest tests/api/ -v ``` ### 手动测试 **使用 Swagger UI：** ``` 1. Visit http://localhost:8000/api/docs 2. Click "Authorize" and enter JWT token 3. Try endpoints interactively ``` **使用 Postman：** ``` 1. Import collection: postman_collection.json 2. Set Authorization: Bearer {your_token} 3. Execute requests ``` ## 📈 监控 ### Celery 任务（Flower） ``` http://localhost:5555 - Monitor task execution - View task details - Check worker status - Analyze performance metrics ``` ### API 健康状态 ``` curl http://localhost:8000/health ``` ### 数据库状态 ``` docker exec imageosint-postgres \ psql -U osint_user -d osint_db -c "SELECT version();" ``` ### 缓存统计 ``` curl http://localhost:8000/api/cache/stats ``` ## 🚀 部署 ### 生产检查清单 - [ ] 使用生产密钥配置 `.env` - [ ] 设置 PostgreSQL 数据库并配置备份 - [ ] 配置生产环境 Redis - [ ] 启用 SSL/HTTPS - [ ] 设置监控和告警 - [ ] 配置日志聚合 - [ ] 设置自动备份 - [ ] 配置适当的速率限制 - [ ] 设置 CI/CD 流水线 - [ ] 配置域名和 DNS ### Docker 生产部署 ``` # 构建镜像 docker-compose -f docker-compose.yml build # 启动服务 docker-compose -f docker-compose.yml up -d # 验证 docker-compose ps docker-compose logs -f api ``` ### Kubernetes 部署 ``` # 创建命名空间 kubectl create namespace imageosint # 部署服务 kubectl apply -f k8s/ # 验证 kubectl get all -n imageosint ``` ## 🤝 贡献 我们欢迎贡献！请参考 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。 ### 开发环境设置 ``` # 克隆仓库 git clone https://github.com/QusaiALBahri/imageOSINT.git cd imageOSINT # 创建虚拟环境 python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # 安装开发依赖 pip install -r requirements-backend.txt pip install pytest pytest-cov black flake8 mypy # 启动开发环境 docker-compose -f docker-compose.dev.yml up -d # 运行测试 pytest tests/ -v # 格式化代码 black . # Lint flake8 . # 类型检查 mypy . ``` ### 拉取请求流程 1. Fork 本仓库 2. 创建功能分支（`git checkout -b feature/amazing-feature`） 3. 进行修改并彻底测试 4. 格式化代码（`black .`） 5. 运行测试（`pytest tests/ -v`） 6. 提交更改（`git commit -m 'Add amazing feature'`） 7. 推送到分支（`git push origin feature/amazing-feature`） 8. 发起拉取请求 ## 📋 路线图 ### v1.0 ✅（当前） - [x] FastAPI 后端（30+ 个端点） - [x] PostgreSQL 数据库（7 个模型） - [x] Celery 异步任务队列 - [x] Redis 缓存层 - [x] JWT 认证 - [x] Docker 容器化 - [x] Gradio Web 界面 - [x] 完整文档 ### v1.1（计划中） - [ ] GraphQL API 支持 - [ ] WebSocket 实时更新 - [ ] 高级分析仪表板 - [ ] 批量处理 API - [ ] 自定义模型支持 - [ ] 插件系统 ### v2.0（未来） - [ ] 机器学习模型集成 - [ ] 人脸检测与识别 - [ ] 文本提取（OCR） - [ ] 高级图像聚类 - [ ] 移动应用 - [ ] 企业 SSO ## 📄 许可证 本项目根据 **MIT 许可证** 授权 - 参见 [LICENSE](LICENSE) 文件了解详情。 ## 🙏 感谢 - **FastAPI**：现代 Python Web 框架 - **SQLAlchemy**：健壮的数据库 ORM - **Celery**：分布式任务队列 - **Gradio**：ML 模型的简易 Web 界面 - **Redis**：内存数据存储 - **Docker**：容器平台 ## 📞 支持与社区 - **问题**：[GitHub Issues](https://github.com/QusaiALBahri/imageOSINT/issues) - **讨论**：[GitHub Discussions](https://github.com/QusaiALBahri/imageOSINT/discussions) - **安全**：[Security Policy](SECURITY.md) ## 🎯 关键指标 | 指标 | 值 | |--------|-------| | **代码行数** | 4,000+ | | **API 端点** | 30+ | | **数据库模型** | 7 | | **异步任务** | 6 | | **Docker 服务** | 6 | | **测试覆盖率** | 85%+ | | **文档** | 500+ 页 | | **性能** | 8-12 秒/分析 |

标签：API服务, AV绕过, Celery, DNS解析, Docker, EXIF, FastAPI, Google Maps, PostgreSQL, Python, Redis, SEO, Web爬虫, 任务队列, 企业级, 元数据提取, 分布式系统, 反向搜索, 后台开发, 响应大小分析, 图像分析, 地理定位, 多引擎搜索, 安全防御评估, 并发查询, 开源项目, 异步处理, 搜索引擎, 搜索引擎查询, 无后门, 测试用例, 生产就绪, 结果持久化, 缓存, 请求拦截, 进程保护