TG WS Proxy贡献者指南项目结构剖析与如何提交你的第一个PRTG 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 官方域名建立 WebSocketTLS连接若 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 TLSee-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⭐⭐⭐代码风格遵循 pyproject.toml 中的 Ruff lint 规则提交前本地跑一遍 lint能省去不少往返。写在最后TG WS Proxy 是一个小而完整的网络工程项目核心逻辑高度集中在proxy/目录从加密、桥接到 UI 分层清晰每个文件都能独立读懂。先按上面的步骤跑通本地环境再从任务表中挑一个 ⭐ 难度的小改动练手——你的第一个 PR 就会水到渠成。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考