m0hx65/The_Watcher3.0

# The Watcher [](https://python.org) [](https://fastapi.tiangolo.com) [](https://core.telegram.org/bots) [](https://postgresql.org) [](Dockerfile) [](LICENSE) **完全通过 Telegram 运作的 Instagram 资料情报平台。** 实时追踪公开账户——粉丝数、个人简介、头像、认证状态以及其他 10 多个字段。任何信息发生变化的瞬间即可获取 Telegram 通知。五分钟即可部署到 Render。 ## 工作原理 The Watcher 作为单个 Docker 容器运行。它会连接到你的 Telegram 机器人，按计划对一系列 Instagram 用户名进行轮询抓取，并在资料发生任何变动时向你的聊天窗口发送消息。所有操作——无论是添加账户、查看历史记录还是导出数据——都可以通过 Telegram 命令或内联菜单完成。 ``` Telegram Chat ──► Bot Commands ──► FastAPI + APScheduler │ ┌──────▼──────┐ │ Instagram │ HTTP/2 · TLS fingerprint impersonation └──────┬──────┘ │ profile data ┌──────▼──────┐ │ PostgreSQL │ snapshots · diffs · media hashes └──────┬──────┘ │ change detected ┌──────▼──────┐ │ Telegram │ formatted alert + panel bump └─────────────┘ ``` ## 功能特性 **监控** - 追踪 10 多个资料字段：粉丝数、关注数、帖子、Reels、精选、个人简介、全名、用户名、外部链接、认证徽章、商业标志、公开/私密状态 - 头像更改检测——对下载的每张图片计算 SHA-256 哈希值，并将其存储到磁盘中以供后续检索 - 可配置的轮询间隔，并在每次检查时加入随机抖动，以避免同步请求爆发 - 节流并发——每次轮询可配置最大并行抓取数 **Telegram 界面** - 完整的命令集：`/add`、`/remove`、`/list`、`/recheck`、`/status`、`/history`、`/photo`、`/export`、`/help` - 内联键盘菜单——无需记忆命令 - 面板置顶——在每次通知后，主菜单会重新发布在聊天窗口底部，使其始终保持可访问状态 - 通过 `TELEGRAM_ADMIN_IDS` 进行授权；留空则允许所有用户使用 **可靠性** - 通过 `curl_cffi` 模拟 Chrome TLS 指纹，以绕过 401/403 封锁 - 针对瞬时故障，使用 Tenacity 进行指数退避重试 - 防抖动的失败通知——显示 401/403/429 错误，而不会在每次重试时发送垃圾消息 - 在 `/status` 和 `/list` 中显示每个账户的连续失败计数 **数据与 API** - PostgreSQL 持久化：快照、媒体哈希、通知日志、运行时设置 - 可配置的快照、通知和原始 API 响应的保留期限 - HTTP API，包含存活/就绪探针以及兼容 cron 的 `/sweep` 端点 - Token 门控的变更端点 - 导出完整通知历史的 CSV 文件 ## 目录 - [快速开始](#quick-start-local) - [Docker](#docker) - [部署到 Render](#deploy-to-render) - [配置说明](#configuration) - [Telegram 命令](#telegram-commands) - [HTTP API](#http-api) - [数据模型](#data-model) - [项目结构](#project-layout) - [技术栈](#tech-stack) - [负责任地使用](#responsible-use) - [许可证](#license) ## 快速开始（本地） **前置条件：** Python 3.12+，一个 PostgreSQL 实例（本地或远程均可） ``` # 1. Clone git clone https://github.com/m0hx65/The_Watcher3.0.git cd The_Watcher3.0 # 2. Configure cp .env.example .env # 编辑 .env — 设置 TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, DATABASE_URL # 3. Install python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt # 4. Run uvicorn app.main:app --reload --port 8000 ``` 机器人将以长轮询模式启动（无需公共 URL）。向你的机器人发送 `/add ` 即可开始监控。 ## Docker ``` docker build -t the-watcher . docker run -d \ --name watcher \ --restart unless-stopped \ -p 8000:8000 \ -v watcher-media:/app/data/media \ --env-file .env \ the-watcher ``` 该容器暴露了一个 `/health` 端点，并包含一个内置的 `HEALTHCHECK`。 ## 部署到 Render `render.yaml` 蓝图会自动配置所有内容。 1. Fork 此仓库并将其推送到 GitHub。 2. 在 Render 中：**New +** → **Blueprint** → 选择你 Fork 的仓库。 3. Render 将配置： - 一个 Docker Web 服务 - 一个托管的 PostgreSQL 16 数据库 - 一个挂载在 `/app/data` 的 1 GB 持久磁盘，用于存储个人资料图片 4. 在 Render 控制台中设置以下三个必填密钥： | 变量 | 值 | |---|---| | `TELEGRAM_BOT_TOKEN` | 来自 [@BotFather](https://t.me/botfather) 的 Token | | `TELEGRAM_CHAT_ID` | 你的聊天或频道 ID | | `TELEGRAM_ADMIN_IDS` | 逗号分隔的 Telegram 用户 ID（可选） | `DATABASE_URL` 和 `WEB_API_TOKEN` 由 Render 自动生成。 5. 点击 **Deploy**。该服务将使用其公共 URL 注册一个 Telegram Webhook，并立即开始轮询抓取。 ### 可选：外部 Cron 触发器 Render 的免费套餐可能会在请求间隔期间暂停 Web 服务。使用 Render Cron Job 或任何外部调度器可以保持轮询任务的可靠触发： ``` curl -fsS -X POST https://.onrender.com/sweep \ -H "X-API-Token: $WEB_API_TOKEN" ``` ## 配置说明 所有设置均从环境变量中读取。本地开发时，请将 `.env.example` 复制为 `.env`。 ### 必填项 | 变量 | 描述 | |---|---| | `TELEGRAM_BOT_TOKEN` | 来自 [@BotFather](https://t.me/botfather) 的 Token | | `TELEGRAM_CHAT_ID` | 接收警报的聊天或频道 ID | | `DATABASE_URL` | PostgreSQL 连接字符串 — 接受 `postgres://`、`postgresql://` 和 `postgresql+asyncpg://` | ### Telegram | 变量 | 默认值 | 描述 | |---|---|---| | `TELEGRAM_ADMIN_IDS` | _(空)_ | 允许使用机器人的逗号分隔用户 ID。留空 = 允许所有人 | | `TELEGRAM_WEBHOOK_URL` | _(空)_ | 用于 Webhook 注册的公共基础 URL。在 Render 上会从 `RENDER_EXTERNAL_URL` 自动推断 | | `TELEGRAM_WEBHOOK_SECRET` | _(空)_ | 可选密钥，用于与 Telegram 的 `X-Telegram-Bot-Api-Secret-Token` 请求头进行验证 | | `TELEGRAM_WEBHOOK_PATH` | `/telegram/webhook` | 在 Telegram 注册并由 FastAPI 挂载的 Webhook 路径 | ### 调度器 | 变量 | 默认值 | 描述 | |---|---|---| | `CHECK_INTERVAL` | `1800` | 完整轮询之间的间隔秒数 | | `JITTER_SECONDS` | `120` | 每次间隔增加的最大随机秒数 | | `MAX_CONCURRENT_FETCHES` | `3` | 每次轮询的最大并行资料抓取数 | | `REQUEST_TIMEOUT` | `20` | 单次请求超时时间（秒） | ### 存储与保留 | 变量 | 默认值 | 描述 | |---|---|---| | `MEDIA_DIR` | `./data/media` | 下载的头像保存目录 | | `SNAPSHOT_RETENTION_DAYS` | `30` | 账户快照保留天数。`0` = 永久保留 | | `NOTIFICATION_RETENTION_DAYS` | `90` | 通知日志保留天数 | | `RAW_RESPONSE_RETENTION_DAYS` | `7` | Instagram 原始 API 响应保留天数 | ### Instagram | 变量 | 默认值 | 描述 | |---|---|---| | `IG_SESSION_COOKIE` | _(空)_ | 用于身份验证请求的可选 Instagram `sessionid` cookie 值 | | `IG_PROXY_URL` | _(空)_ | 专用于 Instagram 请求的可选代理 URL | ### 代理与网络 | 变量 | 默认值 | 描述 | |---|---|---| | `PROXY_URL` | _(空)_ | 用于所有请求的出站代理（`http://...` 或 `socks5://...`）。覆盖 `HTTP_PROXY`/`HTTPS_PROXY` | | `HTTP_PROXY` / `HTTPS_PROXY` | _(空)_ | 标准代理环境变量（在未设置 `PROXY_URL` 时使用） | ### Web API 与运行时 | 变量 | 默认值 | 描述 | |---|---|---| | `WEB_API_TOKEN` | _(空)_ | 设置后，访问 `/sweep` 和 `/accounts/*/recheck` 时需提供此 Token 作为 `X-API-Token` 请求头 | | `PORT` | `8000` | Web 服务器端口 | | `LOG_LEVEL` | `INFO` | 日志详细程度：`DEBUG`、`INFO`、`WARNING`、`ERROR` | ## Telegram 命令 | 命令 | 描述 | |---|---| | `/add ` | 开始监控一个账户；会立即运行一次基线抓取 | | `/remove ` | 停止监控并删除所有存储的历史记录 | | `/list` | 显示所有受监控的账户，包含上次检查状态和失败次数 | | `/recheck ` | 在正常计划之外强制立即执行一次检查 | | `/status` | 全局统计：账户数量、上次轮询时间、下次计划轮询时间 | | `/history ` | 某个账户最近检测到的 15 项变动 | | `/photo ` | 最新存储的头像及其 SHA-256 哈希值 | | `/export` | 以 CSV 文件格式下载完整的通知历史记录 | | `/help` | 命令参考 | ## HTTP API 所有响应均为 JSON。在配置了 `WEB_API_TOKEN` 时，变更端点需要提供 `X-API-Token`。 | 方法 | 路径 | 认证 | 描述 | |---|---|---|---| | `GET` | `/health` | 无 | 存活探针——返回 `{"status":"ok"}` | | `GET` | `/ready` | 无 | 就绪探针——检查监控器和调度器状态 | | `GET` | `/status` | 无 | 统计信息：账户数量、上次轮询时间、调度器信息 | | `GET` | `/accounts` | 无 | 列出所有受监控的账户 | | `POST` | `/accounts/{username}/recheck` | Token | 强制立即检查某个账户 | | `POST` | `/sweep` | Token | 触发对所有活跃账户的完整轮询 | **示例——触发轮询：** ``` curl -X POST https:///sweep \ -H "X-API-Token: your-token" ``` ## 数据模型 表结构会在首次启动时通过 SQLAlchemy `create_all` 自动创建。 | 表名 | 描述 | |---|---| | `monitored_accounts` | 每个目标账户对应一行。记录活跃标志、上次 HTTP 状态、连续失败次数 | | `account_snapshots` | 每次抓取对应一行。存储所有已解析的资料字段、原始 JSON 响应和 HTTP 状态 | | `profile_media_hashes` | 每张唯一的头像对应一行（SHA-256 + 本地磁盘路径）。用于跨账户去重 | | `notification_logs` | 每次派发的变更事件对应一行，包含变更类型、payload 和交付状态 | | `app_settings` | 用于运行时可调配置（检查间隔、面板消息 ID）的键值存储，在重启后持久保留 | ## 项目结构 ``` app/ ├── api/ HTTP API routes (FastAPI router) ├── bot/ Telegram command handlers, inline menus, notification dispatch ├── database/ SQLAlchemy models, async session, CRUD helpers ├── monitor/ Instagram client, media hasher, change detector, sweep orchestrator ├── utils/ Logging setup, user-agent rotation, formatting helpers ├── workers/ APScheduler-based sweep worker ├── config.py Pydantic Settings — environment-driven configuration └── main.py FastAPI app, lifespan wiring, service initialization Dockerfile Procfile render.yaml requirements.txt .env.example ``` ## 技术栈 | 组件 | 库 | 版本 | |---|---|---| | Web 框架 | FastAPI | 0.115 | | ASGI 服务器 | Uvicorn | 0.32 | | Instagram 客户端 | curl_cffi | 0.15 | | Telegram | python-telegram-bot | 21.9 | | 任务调度器 | APScheduler | 3.10 | | ORM | SQLAlchemy (异步) | 2.0 | | 数据库驱动 | asyncpg | 0.30 | | 配置 | pydantic-settings | 2.7 | | 重试 | Tenacity | 9.0 | | 日志 | Loguru | 0.7 | | 图像处理 | Pillow | 11.0 | ## 负责任地使用 - 所使用的 Instagram 端点（`/api/v1/users/web_profile_info/`）是未公开文档且受频率限制的。 - 仅监控你有合理理由追踪的账户：你自己的账户、品牌资产或经授权的 OSINT 研究。 - 对于大量账户列表，请增加 `CHECK_INTERVAL` 并降低 `MAX_CONCURRENT_FETCHES`。 - 该机器人会通过防抖机制向操作员显示 401、403 和 429 响应，让你能立即知晓是否受到了频率限制。 ## 许可证 [MIT](LICENSE)

标签：APScheduler, AV绕过, Docker, ESC4, FastAPI, HTTP/2, Instagram监控, OSINT, PostgreSQL, Python, Render部署, Telegram机器人, TLS指纹伪装, URL抓取, 二进制发布, 二进制模式, 全景监控, 安全防御评估, 实时处理, 实时通知, 开源工具, 情报分析, 数据抓取, 无后门, 测试用例, 目标追踪, 社交媒体监控, 粉丝追踪, 网络侦查, 网络诊断, 自托管, 请求拦截, 资料变更监控, 赛博侦查, 逆向工具