Telegram Desktop 被封锁或直连不稳时，用…

在无法直连 Telegram DC 或被网络层阻断时，通过本地 tg-ws-proxy 将 Telegram Desktop 的 SOCKS5 流量经 WSS 转发到 Telegram 数据中心。

适用场景

解决思路

1. 运行原理/内部流程：启动本地 SOCKS5 代理在 `127.0.0.1:1080`；拦截发往 Telegram IP 的连接；从 MTProto obfuscation init 包提取 DC ID；通过 Telegram 域名向匹配 DC 建立 WebSocket (TLS) 连接；如果 WebSocket 返回 302，则回退到直连 TCP。
2. 源码安装（全平台）：`git clone https://github.com/Flowseal/tg-ws-proxy.git`；`cd tg-ws-proxy`；`pip install -e .`。
3. 运行控制台代理（无 GUI）：`tg-ws-proxy`。
4. 运行带托盘 GUI：Windows 用 `tg-ws-proxy-tray-win`；macOS 用 `tg-ws-proxy-tray-macos`；Linux 用 `tg-ws-proxy-tray-linux`。
5. Linux AUR（Arch 系）：`paru -S tg-ws-proxy-bin`，或 `git clone https://aur.archlinux.org/tg-ws-proxy-bin.git`、`cd tg-ws-proxy-bin`、`makepkg -si`。
6. Linux systemd CLI：`sudo systemctl start tg-ws-proxy-cli@1080`。
7. Linux .deb：从 releases 下载 `TgWsProxy_linux_amd64.deb`，执行 `sudo dpkg -i TgWsProxy_linux_amd64.deb`。
8. Linux 二进制：`chmod +x TgWsProxy_linux_amd64`；`./TgWsProxy_linux_amd64`。
9. CLI 语法：`tg-ws-proxy [--port PORT] [--host HOST] [--dc-ip DC:IP ...] [-v]`。
10. CLI 参数：`--port` 默认 `1080`；`--host` 默认 `127.0.0.1`；`--dc-ip` 默认 `2:149.154.167.220`、`4:149.154.167.220`，可重复指定；`-v`/`--verbose` 开启 DEBUG 日志。
11. CLI 示例默认启动：`tg-ws-proxy`。
12. CLI 示例自定义端口：`tg-ws-proxy --port 9050`。
13. CLI 示例指定多个 DC 与 IP：`tg-ws-proxy --dc-ip 1:149.154.175.205 --dc-ip 2:149.154.167.220 --dc-ip 4:149.154.167.220`。
14. CLI 示例详细日志：`tg-ws-proxy -v`。
15. CLI 完整自定义示例：`tg-ws-proxy --host 0.0.0.0 --port 1080 --dc-ip 2:149.154.167.220 -v`。
16. 托盘应用配置文件位置：Windows `%APPDATA%/TgWsProxy/config.json`；macOS `~/Library/Application Support/TgWsProxy/config.json`；Linux `~/.config/TgWsProxy/config.json` 或 `$XDG_CONFIG_HOME/TgWsProxy/config.json`。
17. `config.json` 结构：包含 `port`（如 `1080`）、`dc_ip`（如 `2:149.154.167.220`、`4:149.154.167.220`）、`verbose`（如 `false`）。
18. 源码 CLI 入口注册：在 `pyproject.toml` 的 `[project.scripts]` 中声明 `tg-ws-proxy` 对应 `proxy.tg_ws_proxy:main`、`tg-ws-proxy-tray-win` 对应 `windows:main`、`tg-ws-proxy-tray-macos` 对应 `macos:main`、`tg-ws-proxy-tray-linux` 对应 `linux:main`。
19. 手动连接 Telegram Desktop：打开 Telegram Desktop；进入 Settings → Advanced → Connection type → Use custom proxy；点击 Add Proxy。
20. 手动代理参数：Type 选 SOCKS5；Server 填 `127.0.0.1`；Port 填 `1080`；Username/Password 留空；点击 Save 并启用代理。
21. 托盘 GUI 自动配置：右键托盘图标 → 选择 Открыть в Telegram，打开 `tg://socks` deep link 自动配置 Telegram Desktop。
22. 程序化启动代理：`from proxy.tg_ws_proxy import main`；用 `threading.Thread(target=main, daemon=True)` 创建线程并 `start()`。
23. 用 Python requests 经 PySocks 走代理：`pip install requests[socks]`；设置 `proxies` 为 `socks5h://127.0.0.1:1080` 的 http/https；请求 `https://api.telegram.org/botTOKEN/getMe` 并打印 JSON。
24. 用 Telethon 走代理：导入 `TelegramClient` 和 `socks`；从环境变量读取 `TG_API_ID`、`TG_API_HASH`；创建 `TelegramClient('session', api_id, api_hash, proxy=(socks.SOCKS5, '127.0.0.1', 1080))`；`await client.start()` 后 `get_me()` 并打印 username。
25. 自定义 DC IP 映射（Python）：定义 `dc_map`（1: `149.154.175.205`，2: `149.154.167.220`，3: `149.154.175.100`，4: `149.154.167.220`，5: `91.108.56.130`）；循环生成 `--dc-ip f'{dc_id}:{ip}'` 参数；用 `subprocess.Popen(['tg-ws-proxy', '--port', '1080'] + dc_args)` 启动。
26. 用 PyInstaller 构建二进制：Windows 运行 `pyinstaller packaging/windows.spec`；macOS 运行 `pyinstaller packaging/macos.spec`；Linux 运行 `pyinstaller packaging/linux.spec`。
27. 自动构建：GitHub Actions 在 `.github/workflows/build.yml` 中自动产出构建。
28. 选择二进制时检查最低系统支持：`TgWsProxy_windows.exe` 需 Windows 10+；`TgWsProxy_windows_7_64bit.exe` 需 Windows 7 x64；`TgWsProxy_windows_7_32bit.exe` 需 Windows 7 x32；`TgWsProxy_macos_universal.dmg` Intel 版需 macOS 10.15+，Apple Silicon 版需 macOS 11.0+；`TgWsProxy_linux_amd64` 需 Linux x86_64 + AppIndicator。
29. Telegram 仍不连接时：运行 `tg-ws-proxy -v` 并观察连接日志；确认 Telegram Desktop 设为 SOCKS5 而不是 HTTP/MTProxy；从托盘菜单执行 Перезапустить прокси 重启代理；检查防火墙或其他进程是否阻塞 `1080` 端口。
30. 端口被占用时：macOS/Linux 用 `lsof -i :1080` 查找；Windows 用 `netstat -ano | findstr :1080`；改用 `tg-ws-proxy --port 1081` 运行，并把 Telegram Desktop 代理端口更新为 `1081`。
31. Windows Defender 误报（Wacatac）时：下载 `win7` 变体（功能相同、检测率更低）；或临时关闭 Defender，下载后加入排除项，再重新启用；用文件 hash 在 VirusTotal 验证构建。
32. macOS 提示未验证开发者时：打开 System Settings → Privacy & Security；向下滚动并点击 TG WS Proxy 旁边的 Open Anyway。
33. Linux 托盘图标不可见时：安装 AppIndicator；Ubuntu/Debian 用 `sudo apt install gir1.2-appindicator3-0.1`；Fedora 用 `sudo dnf install libappindicator-gtk3`。
34. WebSocket 不可用并回退 TCP 时：这是预期行为；如果 WS 返回 302 重定向，代理会自动改用直连 TCP；无需操作，Telegram 仍可连接。
35. 详细调试日志：运行 `tg-ws-proxy -v`；或对托盘应用在 `config.json` 中设置 `verbose` 为 `true`。

适用边界 · 注意事项

• 不适用于非 Telegram Desktop 或非 MTProto 流量；它只处理发往 Telegram IP 的连接并按 DC ID 转发。
• 不适合需要 HTTP 代理或 MTProxy 的客户端配置；Telegram Desktop 必须设置为 SOCKS5。
• 如果运行环境完全阻断到 Telegram 域名的 WSS/TLS，或 1080 端口被占用且不能改端口/改客户端配置，则不能绕过。