Trawlr/App

# Trawlr Trawlr 是一个开源自托管的数据收集平台，用于 Telegram 数据存档与分析。通过单一 Web 应用，您可以监控多个 Telegram 账户、存档消息和媒体、追踪用户并生成报告。 ## 功能特性 - **多账户管理** — 连接并管理多个 Telegram 账户，支持 2FA、会话存储以及每个账户的下载并发限制 - **实时监控** — 长连接 Telegram 连接捕获消息、编辑和删除事件 - **消息归档** — 完整消息历史扫描，支持编辑追踪、删除检测和相册分组 - **实体提取** — 自动从消息中提取 URL、提及、标签、电子邮件、电话号码和代码块 - **实体通知** — 监控消息中检测到的实体（URL、域名、标签、@提及、电话等）并发送通知。可将通知发送至配置的 Webhook（HMAC 签名）或 RabbitMQ 队列 - **用户 OSINT** — 跨频道追踪用户，包含个人资料、群组成员身份、活跃度指标和用户名历史 - **下载队列** — 基于优先级的下载系统，支持并发槽位、进度追踪、自动重试，以及通过硬链接实现的 SHA256 去重 - **全文搜索** — 基于 PostgreSQL 的搜索，支持布尔运算符、字段过滤、日期范围、短语匹配和 CSV 导出 - **分析与报告** — 内容趋势、用户情报、来源分析和调查仪表板，支持导出 - **REST API** — 完整的 API，包含 OpenAPI/Swagger 文档、令牌认证和过滤 - **实时 UI** — 基于 WebSocket 的实时更新、下载进度流式传输以及 HTMX 驱动的动态页面 ## 架构 每个服务运行在独立的容器中。 | 服务 | 角色 | |---------|------| | **web** | Django + Daphne ASGI 服务器 | | **downloader** | 下载发送到队列处理的条目 | | **concierge** | 历史扫描和成员扫描（单线程） | | **processor** | 处理来自 listener 的传入 Telegram 事件 | | **notifier** | 将实体通知匹配结果投递到用户配置的 Webhook 或 RabbitMQ 队列 | | **listener** | 维护持久的 Telegram 连接，将事件发布到 RabbitMQ | | **scheduler** | APScheduler — 触发定时任务（同步、统计、恢复） | | **nginx** | 反向代理，用于通过文件管理器提供媒体服务。其他情况下可选 | | **db** | PostgreSQL 18 | | **rabbitmq** | 任务队列和事件发布/订阅的消息代理 | ## 技术栈 - **后端：** Django、Django REST Framework、Django Channels、Daphne - **任务队列：** Dramatiq + RabbitMQ - **Telegram：** Telethon - **数据库：** PostgreSQL（支持全文搜索和 GIN 索引） - **前端：** Django Templates、HTMX、Bootstrap - **基础设施：** Docker、Docker Compose、Nginx ## 安装说明 完整安装步骤请参见 **[INSTALL.md](INSTALL.md)**。支持两种方式： - **使用预构建容器** — 从 `ghcr.io/trawlr/trawlr` 拉取（推荐） - **从源码构建** — 克隆仓库并运行 `docker compose -f docker-compose-dev.yml up -d --build` ## 配置 所有配置通过环境变量完成。完整列表请参阅 [.env.example](.env.example)。 | 变量 | 描述 | |----------|-------------| | `SECRET_KEY` | Django 密钥 | | `POSTGRES_PASSWORD` | 数据库密码 | | `RABBITMQ_DEFAULT_USER` / `RABBITMQ_DEFAULT_PASS` | RabbitMQ 凭据 | | `RABBITMQ_URL` | AMQP 连接字符串 | | `TRAWLR_STORAGE_ROOT` | 下载媒体的存储路径（默认：`/data/trawlr`） | | `ALLOWED_HOSTS` | 允许的主机名列表（逗号分隔） | | `DEBUG` | 生产环境设置为 `False` | | `SECURE_SSL_REDIRECT` | 使用 HTTPS 时设置为 `True` | 调度间隔、事件处理设置、下载并发以及其他运行时选项可通过 Web UI 中的 **全局设置** 进行配置。 ## 部署 | 文件 | 用途 | |------|----------| | `docker-compose.prod.yml` | 使用预构建容器镜像的生产环境部署 | | `docker-compose-dev.yml` | 本地开发（从源码构建） | | `docker-compose.dokploy.yml` | 高级用户的 Dokploy 云部署 | 容器镜像会根据提交前缀（`fix:`、`feat:`、`major:`）自动构建并推送至 `ghcr.io/trawlr/trawlr`，并使用语义化版本号。 ## 快速开始 Trawlr 部署完毕并可在浏览器中访问后，请按以下步骤操作，以接入您的第一个数据源并开始数据收集。 ### 1. 创建管理员用户 如果在安装时未创建超级用户，请执行到 `web` 容器中并运行： ``` docker compose exec web python manage.py createsuperuser ``` 使用这些凭据在 `/` 登录。第一个用户也将作为后续连接 Telegram 账户的所有者。 ### 2. 连接 Telegram 账户 Trawlr 使用您自己的 Telegram 用户账户来读取频道，而不是使用机器人。 1. 在 → **API development tools** 生成 API ID 和 API Hash。 2. 在 Trawlr 中，进入 **Accounts → Add Account**，输入手机号码、API ID 和 API Hash。 3. 系统将提示您输入 Telegram 发送到该号码的登录代码，如果账户设置了 2FA 密码，还需输入该密码。 认证成功后，账户行将显示绿色状态。您可以连接多个账户；每个账户运行自己的 listener，并拥有独立的下载并发限制（在账户设置页面中配置）。 ### 3. 接入数据源 在 Trawlr 中，“source”（数据源）指您希望存档的任何频道、群组或超级群组。 - **已是成员？** 打开账户，点击 **Sync Channels**，Trawlr 将导入该账户能看到的全部会话。随后在 **Sources** 列表中，您可以启用对感兴趣的数据源的收集。 - **还不是成员？** 使用 **Join Channel**（可在单个账户页面或仪表板中操作）通过邀请链接、`t.me/...` URL 或 `@username` 加入。Trawlr 将加入频道、同步会话，并针对新数据源执行标准的上线任务。公开频道直接加入；私有邀请链接也会被正确处理。 数据源出现后，打开 **Source → Config** 选择要收集的内容： - **Archive messages** — 存储文本、编辑记录、删除记录以及提取的实体（URL、提及、标签等）。 - **Auto-download** — 按文件类型（照片、视频、文件）开关，并可为每种类型设置优先序，以及为数据源设置优先级（1–10），供队列调度器使用。 - **Thumbnails** — 即使未下载完整媒体，也下载轻量预览，以便在 UI 中浏览。 - **Deduplication** — SHA256 去重，通过硬链接避免重复文件存储。 - **Monitor / Pause / Bypass listener** — 切换为实时追踪数据源、暂停下载或跳过实时事件处理。 ### 4. 回填历史数据 Listener 仅捕获**新**消息。要获取历史内容，请打开数据源并点击 **Scan History**。`concierge` 服务将按顺序遍历频道，并根据数据源的配置将消息（如启用了自动下载，还包括下载任务）加入队列。对于群组/超级群组，您还可以使用 **Scan Members** 来填充用户 OSINT 图谱。 ### 5. 全局调整自动下载 **Settings → Global Settings** 控制实例级别的行为。新部署中最相关的字段如下： | 设置项 | 作用 | |---------|--------------| | `download_queue_interval` | 调度器清空下载队列的频率（默认 10 秒） | | `channel_sync_interval` | Trawlr 重新同步每个账户会话列表的频率 | | `channel_stats_interval` / `media_counts_interval` | 刷新成员计数和每个数据源的媒体总数 | | `availability_check_interval` | 检测已删除/被封禁的频道 | | `forum_topics_sync_interval` | 重新拉取论坛风格超级群组的主题列表 | | `member_sync_interval` | 定期刷新群组成员列表 | | `stuck_task_recovery_interval` | 重新入队长时间卡住的任务 | | `event_processing_enabled` | 总开关 — 关闭后可暂停 listener 管道而无需停止服务 | | `storage_root` / `filename_format` | 下载媒体存放位置和文件命名格式 | 每个账户的下载并发限制在 **Account** 页面设置，而非全局调整 — 请谨慎增加以避免触发 Telegram 频率限制。 ### 6. 设置实体通知（可选） 当特定 URL、域名、标签、提及、电话号码或电子邮件在受监控的数据源中出现时，您希望收到告警，可按如下步骤操作： 1. 进入 **Notifications → Watchlist → Add Entry**。 2. 选择 **entity type**（实体类型）和要监控的精确 **entity value**（实体值，例如标签 `#blackmarket`、域名 `example.com`）。 3. 选择 **mode**（模式）— `every` 每次匹配都触发，`new` 仅首次触发。 4. 配置接收端： - **Webhook** — 向您指定的 URL 发送 HMAC 签名的 POST 请求。设置 `secret` 用于签名验证。 - **RabbitMQ** — 发布到指定的队列/交换机/路由键。当您希望堆栈中的其他服务直接消费匹配结果时非常有用。 5. 可选择设置 **cooldown**（冷却时间，秒），以抑制重复匹配。 投递失败时会自动重试；失败投递记录会出现在 **Deliveries** 标签页中，可在此重新入队或查看详情。 ### 7. 排除噪音用户（可选） 如果某些用户（如机器人、垃圾信息发送者）正在淹没您的数据源，请在 **Settings → Exclusions** 中添加排除规则。排除可以是全局的（所有数据源）或针对特定数据源的，listener 会在处理前静默丢弃这些用户的消息 — 有助于保持存储和通知的聚焦。 ### 8. 验证管道运行健康 第一个数据源开始收集后，建议检查以下内容： - **Dashboard** — 应显示近期活动、排队/激活中的下载任务，以及每个账户的 listener 状态。 - **Tasks** 页面 — 显示排队中、运行中和失败的任务运行。如果扫描或下载似乎卡住，请先查看此处。 - **Ops → Queues** — 每个 worker 的 RabbitMQ 队列深度。持续积压通常意味着某个 worker 容器需要更高的并发量或已崩溃。 - **Settings → Dead Letters** — 任何到此处的消息均失败所有重试；可从此页面重新入队或清除。 至此，新消息、媒体和实体将随着 listener 的捕获而不断流入，您启动的任何历史扫描也将在后台陆续完成。 ## API Trawlr 提供带有令牌认证的 REST API。您可以在 Web UI 的账户设置中生成 API 令牌。 **端点：** - `/api/v1/accounts` — Telegram 账户管理 - `/api/v1/channels` — 频道和数据源数据 - `/api/v1/messages` — 已归档的消息，支持全文搜索 - `/api/v1/files` — 已下载的文件 - `/api/v1/users` — Telegram 用户数据 - `/api/v1/entities` — 提取的实体（URL、提及、标签等） - `/api/v1/tags` — 标签管理 - `/api/v1/resolve` — 将 Telegram 链接解析为实体元数据 - `/api/v1/settings` — 全局配置 - `/api/v1/stats` — 系统统计信息 Swagger UI 可在 `/api/v1/docs` 访问，ReDoc 在 `/api/v1/redoc`，原始 OpenAPI 模式在 `/api/v1/schema`。 ## 路线图 - **搜索改进** — 集成 Apache Solr 以加速全文内容搜索 - **Web UI 修复** — 持续的可用性和打磨改进（新 UI） - **简化设置流程** — 改善 Trawlr 设置和账户上线体验 ## 许可证 本项目是开源的。详情请参见 [LICENSE](LICENSE)。

标签：BSD, Daphne, Django, ESC4, HTMX, NIDS, OpenAPI, OSINT, PostgreSQL, RabbitMQ, REST API, SHA256, Swagger, Telegram, Token认证, Webhook, WebSocket, WSL, 下载进度, 下载队列, 依赖分析, 全文搜索, 分析报告, 力导向图, 历史扫描, 去重, 多账户管理, 字段过滤, 实体提取, 实体通知, 实时UI, 容器化, 布尔搜索, 开源, 情报平台, 数据挖掘, 日期范围, 架构, 活动指标, 测试用例, 消息归档, 用户OSINT, 用户名历史, 短语匹配, 社交媒体分析, 网络测绘, 群组成员, 自动化处理, 自托管, 请求拦截, 通知, 重试机制