TG-S3

Telegram-backed S3-compatible storage on Cloudflare Workers

English | 中文 | 日本語 | Français

TG-S3 turns Telegram into an S3-compatible object storage backend. Files are stored as Telegram messages, metadata lives in Cloudflare D1, and the whole thing runs on Cloudflare Workers with zero runtime dependencies.

Features

• S3-compatible API -- 27 operations including multipart upload, presigned URLs, and conditional requests
• Unlimited free storage -- Telegram provides the storage layer at no cost
• Three-tier caching -- CF CDN (L1) -> R2 (L2) -> Telegram (L3) for fast reads
• Telegram Bot -- Manage files, buckets, and shares directly from Telegram
• Mini App -- Full-featured web UI inside Telegram with file browser, uploads, and share management
• File sharing -- Password-protected share links with expiry, download limits, and inline preview
• Server-side encryption -- SSE-C (customer-provided keys) and SSE-S3 (server-managed keys) with AES-256-GCM
• Large file support -- Files up to 2GB via optional VPS proxy with Local Bot API
• Media processing -- Image conversion (HEIC/WebP), video transcoding, Live Photo handling via VPS
• Multi-credential auth -- D1-backed credential management with per-bucket and per-operation permissions
• Cloudflare Tunnel -- Secure VPS connectivity without exposing public ports
• Multi-language -- Mini App supports English, Chinese, Japanese, and French
• Zero cost entry -- Core functionality runs entirely on Cloudflare's free tier

Architecture

S3 Client ─────┐
                │
Telegram Bot ───┤
                ├──▶ Cloudflare Worker ──▶ D1 (metadata)
Mini App ───────┤         │                R2 (cache)
                │         │
Share Links ────┘         ▼
                     Telegram API ◀──▶ VPS Proxy (optional, >20MB)

Components:

Quick Start

Prerequisites

• Node.js 22+
• A Telegram Bot with token
• A Telegram group/supergroup (get chat ID via @userinfobot)
• A Cloudflare account

One-Command Deploy

git clone https://github.com/gps949/tg-s3.git
cd tg-s3
cp .env.example .env
# Edit .env: fill in TG_BOT_TOKEN, DEFAULT_CHAT_ID, CLOUDFLARE_API_TOKEN
# Optional but recommended: set TG_ADMIN_IDS to restrict bot access (comma-separated user IDs)
./deploy.sh

deploy.sh auto-detects the environment: with Docker it builds images, deploys the CF Worker, configures Cloudflare Tunnel, and starts all services; without Docker it uses local wrangler. S3 credentials can be created in the Telegram Mini App (Keys tab).

Verify

Configure any S3 client to point at your worker URL:

# Using AWS CLI
aws configure set aws_access_key_id YOUR_KEY
aws configure set aws_secret_access_key YOUR_SECRET
aws --endpoint-url https://your-worker.workers.dev s3 ls

# Using rclone
rclone config create tgs3 s3 \
  provider=Other \
  access_key_id=YOUR_KEY \
  secret_access_key=YOUR_SECRET \
  endpoint=https://your-worker.workers.dev \
  acl=private
rclone ls tgs3:default

S3 Compatibility

27 operations supported across object CRUD, multipart upload, bucket management, and authentication.

Not supported (by design): versioning, ACLs, cross-region replication. See docs/S3-COMPAT.md for details.

Telegram Bot Commands

Send any file to the bot to upload it to the default bucket.

Documentation

• Deployment Guide
• Configuration Reference
• Bot Commands
• S3 Compatibility
• Architecture Design

Tech Stack

• Runtime: Cloudflare Workers (zero runtime dependencies)
• Database: Cloudflare D1 (SQLite)
• Cache: Cloudflare R2 + CF Cache API
• Auth: AWS SigV4, presigned URLs, Bearer tokens
• Language: TypeScript (strict mode)
• Media Processing: Sharp + FFmpeg (VPS only)
• Build: wrangler v3

License

MIT