|
|
|
@@ -0,0 +1,149 @@
|
|
|
|
|
---
|
|
|
|
|
name: telethon-proxy-docker
|
|
|
|
|
description: "Deploy Telethon-based Telegram bots/forwarders behind a SOCKS5 proxy (Mihomo/Clash) on a server with no direct Telegram access. Covers Docker networking, proxy injection, and phone verification workflow."
|
|
|
|
|
tags: [telethon, telegram, proxy, docker, mihomo, socks5, forwarder]
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# Telethon + Proxy + Docker Deployment
|
|
|
|
|
|
|
|
|
|
Deploy Telethon-based Telegram bots/forwarders on a server that requires a proxy (Mihomo/Clash) to reach Telegram API servers.
|
|
|
|
|
|
|
|
|
|
## When to Use
|
|
|
|
|
|
|
|
|
|
- User asks to deploy a Telegram bot/forwarder that uses Telethon
|
|
|
|
|
- Server has no direct route to Telegram (Mihomo proxy required)
|
|
|
|
|
- Telethon-based app needs to run in Docker behind a proxy
|
|
|
|
|
- Keywords: "Telegram 转发器", "Telethon proxy", "消息转发", "Telegram forwarder"
|
|
|
|
|
|
|
|
|
|
## Core Problem
|
|
|
|
|
|
|
|
|
|
Telethon uses MTProto (raw TCP), NOT HTTP. Standard `HTTP_PROXY` / `HTTPS_PROXY` environment variables do **NOT** work for Telethon connections. You must pass a `proxy` parameter explicitly to `TelegramClient()`.
|
|
|
|
|
|
|
|
|
|
## Step-by-Step Setup
|
|
|
|
|
|
|
|
|
|
### 1. Verify proxy is a mixed-port (supports SOCKS5)
|
|
|
|
|
|
|
|
|
|
Mihomo/Clash `mixed-port` supports both HTTP and SOCKS5 on the same port:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Check config
|
|
|
|
|
grep "mixed-port" /home/openclaw/clash/config/config.yaml
|
|
|
|
|
# Output: mixed-port: 7890
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 2. Patch Telethon client creation
|
|
|
|
|
|
|
|
|
|
Find where `TelegramClient()` is instantiated (usually `main.py`) and add proxy:
|
|
|
|
|
|
|
|
|
|
```python
|
|
|
|
|
import os
|
|
|
|
|
try:
|
|
|
|
|
import socks
|
|
|
|
|
HAS_SOCKS = True
|
|
|
|
|
except ImportError:
|
|
|
|
|
HAS_SOCKS = False
|
|
|
|
|
|
|
|
|
|
# Parse proxy from env
|
|
|
|
|
proxy_config = None
|
|
|
|
|
proxy_addr = os.getenv('HTTP_PROXY') or os.getenv('http_proxy')
|
|
|
|
|
if proxy_addr and HAS_SOCKS:
|
|
|
|
|
import re
|
|
|
|
|
m = re.match(r'https?://([\d.]+):(\d+)', proxy_addr)
|
|
|
|
|
if m:
|
|
|
|
|
proxy_config = (socks.SOCKS5, m.group(1), int(m.group(2)))
|
|
|
|
|
|
|
|
|
|
# Pass to TelegramClient
|
|
|
|
|
user_client = TelegramClient('./sessions/user', api_id, api_hash, proxy=proxy_config)
|
|
|
|
|
bot_client = TelegramClient('./sessions/bot', api_id, api_hash, proxy=proxy_config)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 3. Docker setup with network_mode: host
|
|
|
|
|
|
|
|
|
|
Docker containers can't reach `127.0.0.1:7890` on the host by default. Use `network_mode: host`:
|
|
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
|
# docker-compose.yml
|
|
|
|
|
services:
|
|
|
|
|
telegram-forwarder:
|
|
|
|
|
build:
|
|
|
|
|
context: .
|
|
|
|
|
dockerfile: Dockerfile.custom
|
|
|
|
|
container_name: telegram-forwarder
|
|
|
|
|
restart: unless-stopped
|
|
|
|
|
network_mode: host # Required for 127.0.0.1 proxy access
|
|
|
|
|
environment:
|
|
|
|
|
- HTTP_PROXY=http://127.0.0.1:7890
|
|
|
|
|
- HTTPS_PROXY=http://127.0.0.1:7890
|
|
|
|
|
- http_proxy=http://127.0.0.1:7890
|
|
|
|
|
- https_proxy=http://127.0.0.1:7890
|
|
|
|
|
- NO_PROXY=localhost,127.0.0.1
|
|
|
|
|
volumes:
|
|
|
|
|
- ./db:/app/db
|
|
|
|
|
- ./.env:/app/.env
|
|
|
|
|
- ./sessions:/app/sessions
|
|
|
|
|
# ... other volumes
|
|
|
|
|
stdin_open: true # Required for phone verification
|
|
|
|
|
tty: true # Required for phone verification
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 4. Custom Dockerfile (adds PySocks)
|
|
|
|
|
|
|
|
|
|
```dockerfile
|
|
|
|
|
FROM heavrnl/telegramforwarder:latest # or whatever base image
|
|
|
|
|
RUN pip install --no-cache-dir PySocks
|
|
|
|
|
COPY main.py /app/main.py # patched version with proxy support
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 5. Phone verification (first run)
|
|
|
|
|
|
|
|
|
|
First run requires interactive phone verification:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Run interactively for first-time auth
|
|
|
|
|
docker-compose run --rm telegram-forwarder
|
|
|
|
|
# → Enter phone code when prompted
|
|
|
|
|
# → Session saved to ./sessions/*.session
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Use `terminal(background=true, pty=true)` and `process(action='submit')` to handle verification code input.
|
|
|
|
|
|
|
|
|
|
**Pitfall**: Verification codes expire FAST (~30 seconds). Agent-based submission via `process(action='submit')` is unreliable due to latency — the code often expires before the agent can submit it. **Recommend user SSH directly** and run `docker-compose run --rm telegram-forwarder` themselves for the verification step.
|
|
|
|
|
|
|
|
|
|
**Pitfall**: If 2FA is enabled, Telethon will prompt for password AFTER the code. User needs to enter their Telegram two-step verification password (set in TG Settings → Privacy & Security → Two-Step Verification). If forgotten, it can be reset but requires a 7-day wait.
|
|
|
|
|
|
|
|
|
|
**Pitfall**: If code expires, clean session files and restart:
|
|
|
|
|
```bash
|
|
|
|
|
rm -f ./sessions/*.session ./sessions/*.session-journal
|
|
|
|
|
docker-compose run --rm telegram-forwarder
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 6. After verification, run as daemon
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
docker-compose up -d
|
|
|
|
|
docker-compose logs -f
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Pitfalls
|
|
|
|
|
|
|
|
|
|
- **`HTTP_PROXY` alone does NOT work for Telethon** — Telethon uses raw TCP (MTProto), not HTTP. Must pass `proxy=(socks.SOCKS5, host, port)` to `TelegramClient()`.
|
|
|
|
|
- **`PySocks` must be installed** — add to Dockerfile if not in base image's requirements.
|
|
|
|
|
- **`network_mode: host`** is required for `127.0.0.1` proxy access. Without it, the container can't reach the host's Mihomo. Alternative: use `extra_hosts: ["host.docker.internal:host-gateway"]` and change proxy to `host.docker.internal:7890`.
|
|
|
|
|
- **Session database lock** — if previous run crashed, `*.session` files may be locked. Delete them before retrying.
|
|
|
|
|
- **Don't use same bot token as Hermes** — the forwarder bot needs its own BotFather token. Using the same token causes conflicts.
|
|
|
|
|
- **Verification code timeout** — Telegram codes expire in ~30s. The interactive Docker session may time out if user is slow to respond. Have the code ready before starting.
|
|
|
|
|
|
|
|
|
|
## Reference: Heavrnl/TelegramForwarder
|
|
|
|
|
|
|
|
|
|
Best full-featured Telegram forwarder (1144+ stars):
|
|
|
|
|
- Repo: `https://github.com/Heavrnl/TelegramForwarder`
|
|
|
|
|
- Features: `/bind` command, keyword filtering, regex replace, AI processing, RSS, multi-platform push
|
|
|
|
|
- Commands: `/bind`, `/settings`, `/add`, `/replace`, `/list_keyword`, etc.
|
|
|
|
|
- Docker image: `heavrnl/telegramforwarder:latest`
|
|
|
|
|
|
|
|
|
|
## Server Context
|
|
|
|
|
|
|
|
|
|
- Server: Linux (NYC), no direct route to Telegram servers
|
|
|
|
|
- Proxy: Mihomo at `127.0.0.1:7890` (mixed-port, SOCKS5 + HTTP)
|
|
|
|
|
- Telegram API creds in `~/.bashrc`: `TG_API_ID`, `TG_API_HASH`
|
|
|
|
|
- User prefers Chinese UI/commands
|
Hermes Skills Manager