注意： 该项目正在积极开发中。它拥有稳定的核心能力和测试覆盖，我们持续在每个版本中改进文档、加固和特性深度。欢迎贡献、报告错误和提供反馈。
docker compose up| 图谱调查 | 实体丰富 |
|---|---|
 |  |
cd backend uv sync uv run uvicorn ogi.main:app --reload
API 将在 `http://localhost:8000` 可用。
对于本地转换执行，Redis 和转换工作进程也必须运行。仅 Redis 是不够的。
启动 Redis：```bash
docker run -d --name ogi-redis -p 6379:6379 redis:7-alpine
在第二个终端中启动转换工作器：```bash cd backend uv run python -m ogi.worker.run_worker
如果你看到 `Job queue not available` 或 `Redis not available`，请确认：
- `OGI_REDIS_URL` 指向 `redis://localhost:6379/0`（对于本地基于主机的运行）
- 在 Redis 启动后，后端已重新启动
- 独立的 worker 进程正在运行
- 你没有在 Docker Compose 之外使用仅限 Docker 的主机名 `redis`
如果你将后端与 PostgreSQL 一起运行（`OGI_USE_SQLITE=false`），启动时会自动应用 Alembic 迁移，然后再处理请求。Docker 部署在后端容器入口点中也执行相同操作。
AI Investigator 的运行由另一个独立的 worker 处理：```bash
cd backend
uv run python -m ogi.agent.run_worker
cd frontend pnpm install pnpm dev
打开 http://localhost:5173。就这样。
### AI 调查员
AI 调查员是一个可选的后台支持的工作流，可以规划转换序列、请求审批，并在工作区内汇总调查进度。
- 在项目内打开 `AI Investigator` 标签页
- 在调查员设置对话框中配置提供者和模型
- 将提供者 API 密钥存储到 `API Keys`
- 与后端一起运行独立的 `agent-worker` 进程
当前实现支持每个用户的提供者配置，以及一个专用的工作进程，独立于主 API 服务器执行调查步骤。
### CLI
运行 CLI 的两种支持方式：
**推荐**（无需激活）：```bash
cd backend
uv sync
uv run ogi --help
已激活的虚拟环境（普通 ogi 命令）：```bash
cd backend
uv venv
..venv\Scripts\Activate.ps1 uv pip install -e . ogi --help
## Docker
### 开发```bash
cp .env.example .env
docker compose up
使用预构建的GHCR镜像。
重要：docker-compose.prod.yml 需要外部的PostgreSQL数据库。它不包含 db 服务。
如果您想要包含内置Postgres和Redis的一体化本地Docker栈，请使用：```bash docker compose up -d
仅当你已经有一个可访问的PostgreSQL实例并已相应设置`OGI_DATABASE_URL`时，才使用生产compose文件：```bash
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
在 .env 中设置 OGI_IMAGE_TAG 以固定特定的发布镜像标签（例如 v0.2.6）。默认为 latest。
新 Hetzner 用户可以使用第一个链接注册并获得 Hetzner Cloud 积分。这是一个推荐链接，因此如果推荐符合条件，OGI 维护者也可能获得 Hetzner Cloud 积分。创建服务器后，使用上面的 Docker 部署命令来运行 OGI。
OGI 内置了合理的每次转换最大值，例如 max_results、max_links、max_urls 和 max_content_chars，但这些上限现在可以集中覆盖，因此云部署可以在不硬编码本地限制的情况下强制执行它们。
在 .env 中使用 OGI_TRANSFORM_SETTING_MAX_OVERRIDES：```env
OGI_TRANSFORM_SETTING_MAX_OVERRIDES=max_results=50,max_urls=25,max_links=40,max_content_chars=20000
在本地优先部署中移除特定限制：```env
OGI_TRANSFORM_SETTING_MAX_OVERRIDES=max_results=none,max_urls=none,max_links=none,max_content_chars=none
覆盖项由转换设置名称键控，适用于内置转换和使用 OGI 共享转换基础/运行时的社区插件。
托管云版本位于 ogi.khas.app，最初设计为让用户快速试用 OGI，再决定是否自行部署。如今它已成为该项目最受欢迎的使用方式，拥有超过 350 名活跃云用户。
使用量的增加也提高了这个副项目的基础设施成本。因此，仓库包含了一个云专属的支持者订阅（Supporter）和转换运行冷却系统。在公共云实例上，免费用户可能在转换运行之间受到超时限制，而支持者用户可以以象征性的每月 3 美元订阅，以帮助支付 Supabase 和 VPS 费用。
支持者订阅可以在个人资料计费控制或 Stripe 计费门户中取消。取消将停止未来计费，但已付费的订阅期不予退款或按比例折算。
此计费代码通过配置有意进行防护：仅当 OGI_DEPLOYMENT_MODE=cloud 且 OGI_CLOUD_BILLING_ENABLED=true 时才生效。自托管部署应保持计费禁用，并且不应看到任何计费或付费墙行为。
OGI 包含安装级别的产品遥测，旨在帮助我们了解实际使用情况，特别是在自托管部署中。
OGI_TELEMETRY_ENABLED=true 启用遥测收集OGI_TELEMETRY_LEVEL=full 是默认收集级别OGI_TELEMETRY_ENABLED=false 完全禁用遥测OGI_TELEMETRY_LEVEL=basic 减少发送内容basic 发送：
full 额外发送：
遥测设计为避免发送图内容、实体值、API 密钥、提示或其他调查数据。当前政策详情也已发布在隐私政策中。
如果您使用预构建镜像且插件需要额外的 Python 库，OGI 会在容器启动时从以下位置安装插件依赖：
plugins/requirements.txt（首选），或plugins/requirements.txt 缺失时，从 plugins/ogi-lock.json 自动生成依赖。环境变量：
OpenGraphIntel 内置了一个转换市场。从社区仓库浏览、安装和管理转换。
安全提示： 需要 API 密钥的插件应被视为特权代码。如果插件可以访问您的密钥并发出出站网络请求，它可能会滥用或泄露这些密钥。在安装或运行第三方插件之前，请审查信任层级、权限和所需服务。```bash
uv run ogi transform search dns
uv run ogi transform install shodan-host-lookup
### 内置转换类别
| 类别 | 示例 |
| -------- | --------------------------------------- |
| DNS | A, AAAA, MX, NS, CNAME 记录 |
| IP & ASN | GeoIP, 反向IP, ASN 信息 |
| SSL/TLS | 证书透明度, SSL Labs |
| 电子邮件 | 邮件服务器验证, 泄露检查 |
| Web | WHOIS, 域名信息, 网页提取 |
| 社交 | 用户名枚举, 社交资料 |
| 哈希 | MD5, SHA1, SHA256 查询 |
| 位置 | 地理编码, 天气, 附近ASN数据 |
### 支持的实体类型
`Person` • `Username` • `Domain` • `IPAddress` • `EmailAddress` • `PhoneNumber` • `Organization` • `URL` • `SocialMedia` • `Hash` • `Document` • `Location` • `ASNumber` • `Network` • `MXRecord` • `NSRecord` • `Nameserver` • `SSLCertificate` • `Subdomain` • `HTTPHeader`
### 构建您自己的转换
想要构建自己的？请参阅[贡献指南](https://github.com/opengraphintel/ogi-transforms/blob/main/CONTRIBUTING.md)。
如果您的转换需要外部服务凭据，请在 `api_keys_required` 中声明。不要将机密存储在转换设置中。OGI 在 `API Keys` 下管理这些凭据，使用机密的插件被视为特权代码。
如果您的转换暴露了有上限的设置，例如 `max_results` 或 `max_content_chars`，请尽可能使用稳定的设置名称，而不是自定义的一次性名称。OGI 可以通过 `OGI_TRANSFORM_SETTING_MAX_OVERRIDES` 集中覆盖最大值，这有助于云部署强制执行限制，而本地用户可以移除它们。
每个插件都是一个包含 `plugin.yaml` 清单的目录：```yaml
name: my-transform
version: "1.0.0"
display_name: My Transform
description: What it does
author: Your Name
license: MIT
category: dns
input_types: [Domain]
output_types: [IPAddress]
permissions:
network: true
filesystem: false
subprocess: false
ogi/ ├── backend/ │ └── ogi/ │ ├── api/ # REST API routes │ ├── cli/ # CLI tool (Typer) │ ├── db/ # Database layer (asyncpg + aiosqlite) │ ├── engine/ # Graph engine & transform engine │ ├── models/ # SQLModel definitions │ ├── store/ # Data stores │ ├── transforms/ # Built-in transforms │ │ ├── dns/ # DNS resolution transforms │ │ ├── cert/ # SSL certificate transforms │ │ ├── email/ # Email enrichment │ │ ├── hash/ # Hash lookups │ │ ├── ip/ # IP/ASN/geolocation │ │ ├── org/ # Organization info │ │ ├── social/ # Social media │ │ └── web/ # Web scraping/extraction │ ├── worker/ # Async job queue (RQ) │ ├── config.py # Pydantic settings │ └── main.py # FastAPI entry point ├── frontend/ │ └── src/ │ ├── api/ # API client │ ├── components/ # React components │ ├── hooks/ # Custom hooks (realtime sync, etc.) │ ├── stores/ # Zustand state management │ ├── types/ # TypeScript types │ └── App.tsx # Main application ├── plugins/ # Community plugins directory ├── docs/ # Documentation & images ├── docker-compose.yml # Development deployment ├── docker-compose.prod.yml # Production deployment └── .env.example # Environment template
### 配置
OGI 使用 [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) 并支持 `.env` 文件。运行时/后端变量以 `OGI_` 为前缀。
列表式设置可以接受：
- JSON 数组，例如 `["plugins","../plugins"]`
- 逗号分隔的字符串，例如 `plugins,../plugins`
<details>
<summary><strong>关键环境变量</strong></summary>
| 变量 | 描述 | 默认值 |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `OGI_APP_NAME` | 应用程序名称 | `OGI` |
| `OGI_HOST` | 后端绑定主机 | `0.0.0.0` |
| `OGI_PORT` | 后端端口 | `8000` |
| `OGI_CORS_ORIGINS` | 允许的前端来源 | `http://localhost:5173,http://localhost:3000` |
| `OGI_USE_SQLITE` | 使用 SQLite 而非 PostgreSQL | `true` |
| `OGI_DB_PATH` | SQLite 数据库文件路径 | `ogi.db` |
| `OGI_DATABASE_URL` | PostgreSQL 连接字符串 | `postgresql://postgres:postgres@localhost:5432/ogi` |
| `OGI_REDIS_URL` | 用于 RQ/任务的 Redis 连接字符串 | `redis://localhost:6379/0` |
| `OGI_RQ_QUEUE_NAME` | 转换任务的队列名称 | `transforms` |
| `OGI_TRANSFORM_TIMEOUT` | 每个转换任务的超时时间（秒） | `300` |
| `OGI_AGENT_WORKER_POLL_INTERVAL_SEC` | AI 调查员工作线程的轮询间隔 | `2.0` |
| `OGI_AGENT_CLAIM_TIMEOUT_SEC` | AI 调查员步骤恢复的过期声明超时 | `120` |
| `OGI_AUTO_RUN_MIGRATIONS` | 在本地非 SQLite 应用启动时自动运行 Alembic | `true` |
| `OGI_RUN_DB_MIGRATIONS` | 在容器入口点运行数据库迁移 | `false` |
| `OGI_DB_MIGRATION_RETRIES` | 入口点迁移重试次数 | `30` |
| `OGI_DB_MIGRATION_DELAY_SECONDS` | 入口点迁移重试之间的延迟 | `2` |
| `OGI_PLUGIN_DIRS` | 插件搜索目录 | `plugins,../plugins` |
| `OGI_DEPLOYMENT_MODE` | 部署模式（`self-hosted` 或 `cloud`） | `self-hosted` |
| `OGI_CLOUD_BILLING_ENABLED` | 启用仅限云的支持者计费和转换冷却强制执行 | `false` |
| `OGI_FREE_TRANSFORM_COOLDOWN_SECONDS` | 免费云用户转换器运行之间的冷却时间 | `1800` |
| `OGI_PAID_TRANSFORM_COOLDOWN_SECONDS` | 付费云用户转换器运行之间的冷却时间 | `0` |
| `OGI_STRIPE_SECRET_KEY` | 用于结账和门户会话的 Stripe 服务端密钥 | 未设置 |
| `OGI_STRIPE_WEBHOOK_SECRET` | Stripe webhook 签名密钥 | 未设置 |
| `OGI_STRIPE_SUPPORTER_PRICE_ID` | 支持者计划的 Stripe 周期性价格 ID | 未设置 |
| `OGI_STRIPE_SUPPORTER_AMOUNT_CENTS` | 支持者计划的显示金额 | `300` |
| `OGI_STRIPE_SUPPORTER_CURRENCY` | 支持者计划的显示货币 | `usd` |
| `OGI_BILLING_SUCCESS_URL` | 可选的 Stripe Checkout 成功重定向 | 从请求派生 |
| `OGI_BILLING_CANCEL_URL` | 可选的 Stripe Checkout 取消重定向 | 从请求派生 |
| `OGI_BILLING_PORTAL_RETURN_URL` | 可选的 Stripe 计费门户返回 URL | 从请求派生 |
| `OGI_REGISTRY_REPO` | 转换注册表 GitHub 仓库 | `opengraphintel/ogi-transforms` |
| `OGI_REGISTRY_CACHE_TTL` | 注册表缓存 TTL（秒） | `3600` |
| `OGI_TRANSFORM_SETTING_MAX_OVERRIDES` | 可选全局最大覆盖映射，用于转换设置 | 空 |
| `OGI_GITHUB_TOKEN` | 可选的 GitHub 令牌，用于注册表/API 速率限制 | 未设置 |
| `OGI_SUPABASE_URL` | Supabase 项目 URL | 未设置 |
| `OGI_SUPABASE_ANON_KEY` | Supabase 匿名/公钥 | 未设置 |
| `OGI_SUPABASE_SERVICE_ROLE_KEY` | Supabase 服务角色密钥 | 未设置 |
| `OGI_SUPABASE_JWT_SECRET` | Supabase JWT 密钥 | 未设置 |
| `OGI_SUPABASE_REDIRECT_URL` | 前端认证流程使用的重定向 URL | 未设置 |
| `OGI_ADMIN_EMAILS` | 用于注册表/插件管理的管理员用户 | 未设置 |
| `OGI_TELEMETRY_ENABLED` | 启用或禁用安装级遥测 | `true` |
| `OGI_TELEMETRY_LEVEL` | 遥测级别（`basic` 或 `full`） | `full` |
| `OGI_API_KEY_ENCRYPTION_KEY` | 用于加密 API 密钥存储的 Fernet 密钥 | 未设置，但强烈推荐 |
| `OGI_API_KEY_INJECTION_ALLOW_COMMUNITY_PLUGINS` | 允许社区插件接收存储的 API 密钥 | `true` |
| `OGI_API_KEY_INJECTION_TRUSTED_TIERS_ONLY` | 将存储的密钥注入限制为仅受信任层级 | `false` |
| `OGI_API_KEY_INJECTION_ALLOWED_TIERS` | 当仅受信任模式启用时允许的层级 | `official,verified` |
| `OGI_API_KEY_SERVICE_ALLOWLIST` | 用于存储密钥注入的可选允许服务 | 空 |
| `OGI_API_KEY_SERVICE_BLOCKLIST` | 用于存储密钥注入的可选阻止服务 | 空 |
| `OGI_LLM_PROVIDER` | 默认 AI 调查员提供程序回退 | `openai` |
| `OGI_LLM_MODEL` | 默认 AI 调查员模型回退 | `gpt-4.1-mini` |
| `OGI_EXPOSE_ERROR_DETAILS` | 在 500 响应中包含内部详细信息 | `false` |
| `OGI_SANDBOX_ENABLED` | 启用沙盒执行模式 | `false` |
| `OGI_SANDBOX_TIMEOUT` | 沙盒超时时间（秒） | `30` |
| `OGI_SANDBOX_MEMORY_MB` | 沙盒内存限制（MB） | `256` |
| `OGI_SANDBOX_ALLOWED_TIERS` | 云沙盒模式下允许的层级 | `official,verified` |
| `OGI_BOOT_REQUIREMENTS_ENABLE` | 启用启动时插件依赖安装 | `true` |
| `OGI_BOOT_REQUIREMENTS_FILE` | 启动依赖文件路径 | `/app/plugins/requirements.txt` |
| `OGI_BOOT_LOCK_FILE` | 启动锁定文件路径 | `/app/plugins/ogi-lock.json` |
| `OGI_BOOT_REQUIREMENTS_STRICT` | 如果缺少插件依赖则启动失败 | `false` |
| `OGI_BOOT_REQUIREMENTS_CACHE_DIR` | 启动依赖生成的临时/缓存目录 | `/tmp/ogi-boot` |
| `OGI_FRONTEND_PORT` | 本地 Docker 前端端口映射 | `3000` |
| `OGI_IMAGE_TAG` | 用于 compose/Coolify 风格部署的生产镜像标签 | `latest` |
| `OGI_BACKEND_IMAGE` | 可选的后端镜像覆盖 | `ghcr.io/khashashin/ogi-backend` |
| `OGI_WORKER_IMAGE` | 可选的工作线程镜像覆盖。默认为后端镜像，因为工作线程和后端共享相同的镜像构建。 | `ghcr.io/khashashin/ogi-backend` |
| `OGI_FRONTEND_IMAGE` | 可选的前端镜像覆盖 | `ghcr.io/khashashin/ogi-frontend` |
| `OGI_CLI_BEARER_TOKEN` | 可选的 CLI 持有者令牌，用于启用认证的后端 | 未设置 |
完整列表请参见 [`.env.example`](https://github.com/khashashin/ogi/blob/HEAD/.env.example)。
</details>
## 开发
### 运行测试```bash
# Backend
cd backend
OGI_DB_PATH=":memory:" OGI_USE_SQLITE=true uv run pytest
# Frontend
cd frontend
pnpm test
cd backend uv run ruff check # Linting uv run mypy # Type checking
cd frontend pnpm lint # ESLint
### CI 流水线
[CI 工作流](https://github.com/khashashin/ogi/blob/HEAD/.github/workflows/ci.yml) 在每个拉取请求上运行：
- **后端：** ruff 代码检查、mypy 类型检查、pytest 测试
- **前端：** vitest、eslint、vite 构建
## 贡献
欢迎提交 PR！如果你发现了 bug 或有想法，请[提交 issue](https://github.com/khashashin/ogi/issues)。
如需新增数据变换，请贡献至 [ogi-transforms](https://github.com/opengraphintel/ogi-transforms)。
### 快速开始
1. Fork 本仓库
2. 创建功能分支（`git checkout -b feature/my-feature`）
3. 进行你的修改
4. 运行测试和代码检查
5. 提交拉取请求
## 法律与负责任使用
OGI 是一款通用型 OSINT 与图谱分析工具。**你需自行承担使用它的全部责任。** 详细法律声明请参见 [LEGAL.md](https://github.com/khashashin/ogi/blob/HEAD/LEGAL.md)。
- **遵守第三方服务条款。** 查询外部服务（DNS、WHOIS、网页抓取、用户名查询等）的数据变换必须遵守相应服务的服务条款。对禁止自动化或批量查询的站点进行此类查询可能违反其条款。
- **尊重数据保护法律。** 如果你位于欧盟或处理欧盟居民的数据，作为数据控制者，你需遵守 GDPR。收集、存储或处理个人数据（姓名、电子邮件地址、IP 地址等）需要合法依据。OGI 本身除你的本地实例外不存储数据——你对你所收集和保留的数据负责。
- **仅用于合法目的。** OGI 旨在用于合法的安全研究、调查、威胁情报及教育用途。请勿将其用于骚扰他人、进行未授权访问或违反适用法律。
- **文件格式兼容性。** OGI 支持导入 MTGX 图谱交换格式。这仅为数据互操作性提供，并不暗示与使用该格式的其他工具存在关联或获得其认可。
> **免责声明：** OGI 按“原样”提供，不附带任何形式的担保。作者不对因使用本软件而产生的任何滥用或损害承担责任。
## 许可
本项目采用 [GNU Affero General Public License v3.0](https://github.com/khashashin/ogi/blob/HEAD/LICENSE) 许可。
---
<div align="center">
**[报告 Bug](https://github.com/khashashin/ogi/issues) • [请求功能](https://github.com/khashashin/ogi/issues) • [讨论](https://github.com/opengraphintel/ogi-transforms/discussions)**
由 OGI 社区用 💜 打造
</div>
| 转换中心 | 导出导入 |
|---|
 |  |
| latest |
| Node.js | 20+ |
| pnpm | latest |
| 服务 | 描述 | 端口 |
|---|
backend | FastAPI 应用服务器 | 8000 |
worker | RQ 异步任务工人 | - |
agent-worker | AI 调查员工人 | - |
frontend | 通过 nginx 提供的 React 应用 | 80 |
db | PostgreSQL 16 | 5432 |
redis | Redis 7（任务队列） | 6379 |
| 服务 | 描述 | 端口 |
|---|
backend | FastAPI 应用服务器 | 8000 |
worker | RQ 异步任务工人 | - |
agent-worker | AI 调查员工人 | - |
frontend | 通过 nginx 提供的 React 应用 | 80 |
redis | Redis 7（任务队列） | 6379 |
docker-compose.prod.yml 期望通过 OGI_DATABASE_URL 提供外部 PostgreSQL 数据库。
| 变量 | 默认值 | 描述 |
|---|
OGI_BOOT_REQUIREMENTS_ENABLE | true | 启用/禁用启动时安装 |
OGI_BOOT_REQUIREMENTS_FILE | /app/plugins/requirements.txt | 依赖文件路径 |
OGI_BOOT_LOCK_FILE | /app/plugins/ogi-lock.json | 锁定文件路径 |
OGI_BOOT_REQUIREMENTS_STRICT | false | 依赖缺失时启动失败 |
OGI_BOOT_REQUIREMENTS_CACHE_DIR | /tmp/ogi-boot | 生成的依赖的临时/缓存目录 |
| 层级 | 技术 |
|---|
| 后端 | Python 3.14+, FastAPI, SQLModel, asyncpg / aiosqlite |
| 前端 | React 19, TypeScript 5.9, Sigma.js (graphology), Zustand, Tailwind CSS 4 |
| 数据库 | PostgreSQL 16 (primary) / SQLite (local fallback) |
| 认证与实时 | Supabase Auth + JWT + Realtime (optional in local mode) |
| 任务队列 | Redis 7 + RQ (async transforms) |
| AI运行时 | Provider-backed AI Investigator worker with audited transform orchestration |
| 包管理器 | uv (backend), pnpm (frontend) |
| 部署 | Docker, nginx, GHCR |