TG WS Proxy贡献者指南：项目结构剖析与如何提交你的第一个PR-开发者社区

TG WS Proxy贡献者指南：项目结构剖析与如何提交你的第一个PR

TG WS Proxy 是一款免费的本地 MTProto 代理服务器，专为 Telegram Desktop 加速加载而设计。它将 Telegram 流量通过 WebSocket 连接重定向，数据全程保持加密传输，且无需任何第三方服务器——一切都运行在你本地。如果你想为这个开源项目贡献力量，本指南将带你看懂项目结构、跑通本地运行环境，并手把手教你提交第一个 PR。

先搞懂 TG WS Proxy 的工作原理

在动手改代码前，先理解数据流。一句话概括整个链路：

Telegram Desktop → MTProto 代理 (127.0.0.1:1443) → WebSocket → Telegram 数据中心

具体分为 5 步：

应用在127.0.0.1:1443启动本地 MTProto 代理
拦截 Telegram Desktop 的数据中心连接
从 MTProto 混淆初始包中提取 DC ID
通过 Telegram 官方域名建立 WebSocket（TLS）连接
若 WebSocket 不可用（遇到 302 重定向），自动降级到 Cloudflare 代理或直连 TCP

项目结构剖析：每个模块在哪里

仓库顶层结构非常清晰，一眼就能分清职责：

目录 / 文件	职责
proxy/	核心代理引擎（asyncio 异步实现）
ui/	基于 CustomTkinter 的系统托盘界面
utils/	配置、日志、更新检查等公共工具
packaging/	PyInstaller 打包规范
docs/	多语言文档（俄 / 英 / 中）
pyproject.toml	项目元数据与依赖声明

proxy/：核心代理引擎

这是改动频率最高、也是最值得新人阅读的目录：

proxy/tg_ws_proxy.py — 入口与主调度：监听端口、握手校验、连接分发
proxy/bridge.py — 数据双向桥接与 MTProto 层 1 重加密，包含 CF 代理 / TCP 回退策略
proxy/raw_websocket.py — 自研 WebSocket 客户端，手工实现握手与帧解析，零第三方依赖
proxy/pool.py — WebSocket 连接池：预分配、补充、轮换
proxy/fake_tls.py — Fake TLS（ee-secret）伪装支持
proxy/balancer.py — 数据中心域名负载均衡
proxy/_aes.py — AES-CTR 加解密核心
proxy/config.py — 端口、DC IP、CF 代理域名等配置解析

ui/：托盘界面与国际化

ui/ctk_tray_ui.py — 设置表单、连通性测试按钮等全部 UI 逻辑
ui/ctk_theme.py — 跨平台主题适配
ui/i18n/ — 多语言资源：en.json 与 ru.json

🌏想贡献翻译？从这里入手最友好——新增一个xx.json并在ui/i18n/注册语言即可，不涉及核心逻辑。

utils/ 与各平台入口

utils/tray_common.py — 配置读写、单实例锁、代理线程生命周期管理
utils/update_check.py — 版本更新检查
utils/logging_setup.py — 滚动日志文件配置
windows.py / macos.py / linux.py — 三大平台的托盘入口点

打包与入口命令

pyproject.toml 中注册了 4 个控制台命令：tg-ws-proxy（纯控制台代理）和tg-ws-proxy-tray-win / tray-macos / tray-linux（托盘版）。桌面端打包由 PyInstaller 规范驱动：packaging/windows.spec、packaging/macos.spec、packaging/linux.spec。

本地构建步骤：5 分钟跑起 TG WS Proxy

贡献的前提是先把项目跑起来。唯一硬性要求：Python ≥ 3.8。

第一步：克隆并安装

git clone https://gitcode.com/gh_mirrors/tg/tg-ws-proxy cd tg-ws-proxy pip install -e .

第二步：启动控制台模式（无托盘界面，适合调试）

tg-ws-proxy --port 1443 -v

第三步：按系统选择托盘版启动

tg-ws-proxy-tray-win # Windows tg-ws-proxy-tray-macos # macOS（需 Python 带 Tk 支持） tg-ws-proxy-tray-linux # Linux（需 AppIndicator）

完整参数表（--dc-ip、--fake-tls-domain、--cfproxy-domain等）见 docs/EN/BuildFromSource.md。

首次启动会看到这样一个引导窗口，包含连接信息和一键跳转到 Telegram 的选项：

💡调试小贴士：加-v输出 DEBUG 级日志是定位代理问题的第一手段；日志落盘参数--log-file配合--log-max-mb可长期留存现场。

如何提交你的第一个 PR

官方贡献指南是 docs/CONTRIBUTING.md，核心要求如下。

提 issue 之前

先查阅 docs/README.md 及相关平台文档
确认没有重复的 issue
按仓库标准 label 规范提交，方便维护者分诊

Bug 报告要包含的信息

应用版本号、操作系统
复现步骤
预期行为 vs 实际行为
日志文件或错误文本

描述越精确，修复越快——这是官方指南的原文态度。

PR 提交前的三项检查

依据 docs/CONTRIBUTING.md：

你的改动解决了具体问题（不夹带无关修改）
现有功能场景没有被破坏
若行为或配置有变化，同步更新了文档

⚡小步、聚焦的 PR 会被最快审核合并——这既是官方建议，也是经验之谈。

新手友好任务推荐

任务类型	入手位置	难度
翻译 / 本地化	ui/i18n/、docs/	⭐
文档勘误补充	docs/ 各平台 README	⭐
新增控制台参数	proxy/tg_ws_proxy.py 参数解析部分	⭐⭐
桥接 / 回退逻辑优化	proxy/bridge.py	⭐⭐⭐