merack/telegram-drive-bot repository overview

⁠Telegram Drive Bot

source code: https://github.com/Merack/telegram-drive-bot⁠

简体中文⁠ | English

A personal media metadata management and retrieval tool built on top of a Telegram Bot. Files, photos, videos and other media sent to the Bot are automatically indexed; the Bot offers browsing, keyword search, semantic search, random sampling, Telegraph article scraping, etc.

⁠Important Notice

⁠Table of Contents

• Features⁠
• Commands⁠
• Deployment⁠
  • Option 1: Docker Compose (recommended)⁠
  • Option 2: Pre-built binary⁠
  • Option 3: Build from source⁠
  • systemd service (optional)⁠
• Database⁠
• Storage Modes⁠
• Vector Search (optional)⁠
• Environment Variables⁠
• License⁠

⁠Features

• Automatic media ingestion: Receives 7 types of media (document / photo / video / audio / animation / voice / video_note) and indexes them for retrieval immediately;
• Two storage modes:
  • channel mode: Files are forwarded to the deployer's own storage channels/supergroups, supporting redundant writing to multiple channels. On retrieval, the bot tries each copy in sequence, falling back to direct file_id sending if all copies fail.
  • direct mode: Only the Telegram file_id is recorded. No storage channel is required, making the deployment extremely lightweight.
  • To prevent database loss caused by account bans, it is recommended to use channel mode, create each redundant storage channel using different Telegram accounts, and set the whitelisted users as administrators in those channels.
• Channel health tracking: If a single channel fails consecutively up to a threshold, it automatically enters a cooldown period during which it is skipped. It automatically recovers after the cooldown ends, and any successful operation resets the failure counter.
• Optional async channel I/O: Channel forward/delete operations are pushed to background goroutines so user responsiveness is not affected by channel latency.
• Three-tier permission model: Owner (Super Admin) → Admin → User. A global whitelist is enabled by default; non-whitelisted users are ignored.
• Retrieval capabilities:
  • /list - Paginated browsing (supports filtering by type)
  • /search - Full chain retrieval: Semantic vector search → Full-text search (FTS) → Fuzzy match (ILIKE), degrading step-by-step
  • /ss - Quick retrieval: Skips the vector layer, only runs FTS + ILIKE, suitable for precise keywords
• Random sampling: /rand, /randv, /randp for reviewing history media, default is 5 items, max 10 items.
• Optional vector search: Supports OpenAI-compatible APIs and Google Gemini native API. Embeddings are generated asynchronously after ingestion, and cosine distance retrieval is performed via pgvector.
• Telegraph scraping: /tph <url> scrapes a telegra.ph article into a Markdown file and saves it for later retrieval.
• Background maintenance:
  • cap_sync — Media group caption backfill, runs automatically on schedule or can be triggered manually.
  • emb_sync / emb_re — Incremental backfill / full rebuild of embedding indices.
• Auto schema migration: Columns are renamed, AutoMigrate is executed, and generated columns and indexes are created automatically on startup. No manual SQL execution is required.
• Proxy support: Supports SOCKS5 and HTTP/HTTPS proxies to connect to Telegram directly.

⁠Commands

⁠Regular Users

⁠Admin Commands

⁠Owner Commands

⁠Deployment

⁠Option 1: Docker Compose (recommended)

Prepare your Telegram Bot Token, your Telegram user_id (recommended to obtain via https://t.me/userinfobot⁠), and a PostgreSQL connection string (recommended to use Supabase⁠ free tier, which comes with pgvector).

# 1. Clone the repository or download docker-compose.yml + .env.example
git clone https://github.com/Merack/telegram-drive-bot.git
cd telegram-drive-bot

# 2. Copy and fill in the environment variables
cp .env.example .env
# Edit .env, fill in at least BOT_TOKEN / OWNER_ID / DATABASE_URL
# If using channel storage mode, also fill in STORAGE_CHAT_IDS

# 3. Start
docker compose up -d

# 4. View logs
docker compose logs -f bot

The image is pulled from ghcr.io/merack/telegram-drive-bot:latest by default. To use a Docker Hub mirror or build from local source, toggle the comments in docker-compose.yml.

When enabling channel storage mode, you need to create one or more Telegram channels/supergroups, add the Bot as an administrator (with send and delete message permissions), and then fill the corresponding chat_ids (starting with -100) into STORAGE_CHAT_IDS.

⁠Option 2: Pre-built binary

Download the corresponding platform's tar.gz from Releases⁠, extract it, and then:

cp .env.example .env
# Edit .env and fill in required fields
./telegram-drive-bot

⁠Option 3: Build from source

Requires Go 1.26+.

git clone https://github.com/Merack/telegram-drive-bot.git
cd telegram-drive-bot
go build -trimpath -ldflags="-s -w" -o telegram-drive-bot ./cmd/bot
cp .env.example .env
# Edit .env
./telegram-drive-bot

⁠systemd service (optional)

A tg-drive-bot.service template is provided in the repository root. After placing the binary and .env in a working directory, modify the WorkingDirectory and ExecStart paths in the service file, then install:

sudo cp tg-drive-bot.service /etc/systemd/system/
# Edit the paths in /etc/systemd/system/tg-drive-bot.service
sudo systemctl daemon-reload
sudo systemctl enable --now tg-drive-bot
sudo systemctl status tg-drive-bot

⁠Database

Supports any PostgreSQL-compatible database. Required tables and indexes are automatically created/migrated at startup — no manual SQL execution required.

• Recommended: Supabase. Zero ops, comes with pgvector, free tier supports ~15 concurrent connections (default connection pool is tuned for this). Simply enable the vector extension in the Database → Extensions console to use vector search.
• Local PostgreSQL: A pgvector/pgvector:pg17 service definition is reserved in docker-compose.yml. Uncomment the relevant lines to enable a local database in Docker, which has pgvector built-in and ready for vector search. Or connect to any other PostgreSQL-compatible database at any location using a standard PostgreSQL connection string.

⁠Storage Modes

Toggle via USE_CHANNEL_STORAGE:

Enhancements available for channel mode:

• Multi-channel redundancy: Fill multiple channel IDs into STORAGE_CHAT_IDS separated by commas. Each new file is written to all available channels simultaneously, and any single success is treated as saved.
• Health tracking: STORAGE_FAILURE_LIMIT / STORAGE_COOLDOWN_PERIOD control the cooldown strategy for failing channels.
• Async operations: With ASYNC_FORWARD / ASYNC_DELETE enabled, channel I/O is offloaded to background goroutines, making user response faster. Failures are only logged, at the cost of potential orphan copies (can be cleaned up manually later).
• Security Recommendation: To prevent account bans from causing database loss, it is recommended to use channel mode, create each redundant storage channel using different Telegram accounts, and set whitelisted users as administrators in those channels.

⁠Vector Search (optional)

Enable via VECTOR_SEARCH_ENABLED=true, and configure the Embedding API base URL, API key, model and dimensions.

• OpenAI-compatible API: EMBEDDING_API_TYPE=openai, using the dimensions parameter. Common model: text-embedding-3-small, recommended dimension 256.
• Google Gemini native API: EMBEDDING_API_TYPE=gemini, using the outputDimensionality parameter. Common model: gemini-embedding-2, recommended dimension 768.

After files are indexed, the Bot calls the Embedding API asynchronously to generate vectors, which does not affect user interaction latency. /search prioritizes semantic matching, and degrades to FTS / ILIKE on failure. EMBEDDING_THRESHOLD controls the upper limit of cosine distance — smaller values are stricter.

The database must have the pgvector extension installed (enable it in the Supabase console, or use the pgvector/pgvector:pg17 image for local PG).

⁠Environment Variables

⁠Required

⁠Storage mode

⁠Database connection pool

⁠Logging & proxy

⁠Vector search

⁠Background maintenance

⁠License

This project is subject to the LICENSE⁠ at the repository root. Please read and comply with the applicable terms before use.