TSM Travel Tunnel · Session Multiplexer
Deployment

服务端三步，客户端三步

中间不需要写任何配置文件。需要 Python 3.11 及以上（Debian 12 / Ubuntu 22.04 自带即为 3.11）。

Install

先把它装起来

Linux 用 deploy.sh 一条命令走完全流程；Windows 上双击脚本即可，或用 package.bat 打出免安装发行版。

Linux · 源码部署 deploy.sh 
# 公网机：装成服务端
$ bash deploy.sh --role server

# 内网机：带上服务端地址与 token
$ bash deploy.sh --role client \
    --server-addr 1.2.3.4 --token <服务端 token>

# 常用选项
# --venv /opt/venvs/tsmtravel   指定虚拟环境
# --mirror https://pypi.tuna... 国内镜像
# --offline                     从 wheelhouse 离线装
# --recreate                    重建虚拟环境
# --tune                        顺带系统调优（需 root）
# --service                     装成 systemd 服务
$ bash deploy.sh --help
Windows · 一键脚本 desktop\ 
# desktop\ 下只有两个入口
$ desktop\启动桌面控制台.bat    双击即启动图形控制台
$ desktop\package.bat           一键打出免安装发行版
$ desktop\package.bat onefile   主程序打成单个 exe

# 打包产物固定在 dist\tsmtravel\
  tsmtravel-desktop.exe   桌面控制台（推荐双击这个）
  tsmtravel.exe           主程序：内核 + Web 面板
  启动管理面板.bat         只启面板，浏览器自动打开
  使用说明.txt

# 整个文件夹拷到任意 x64 机器即可运行，
# 数据默认写在同级 data\，换机器整包带走即迁移。
Server

服务端（公网机）三步

服务端跑在有公网 IP 的机器上，负责把流量送到外面。

01

放行端口

云厂商安全组 + 本机防火墙同时放行 1237、8000，以及每一个转发端口（900 / 901 / …，按需）。这是最容易漏的一步。

02

改为服务端角色

在「服务器配置」页把 token 复制出来；「接入信息」页可直接复制 token、控制端口与证书指纹，并下载 ca.crt。

03

建隧道

隧道管理 → 新建隧道，填隧道名、公网端口 remote_port、内网端口 local_port、绑定客户端 client_id（留空则允许客户端动态申请）。

Client

客户端（内网机）三步

客户端只主动出站，不在路由器或交换机上做任何端口映射。

01

同一份程序选角色

python -m tsmtravel，访问 http://客户端IP:1237，在初始化页面选「客户端」。

02

填服务端信息

「服务器配置」页填服务端地址、控制端口（8000）与 token；校验二选一：把服务端 ca.crt 拷到本机并在 ca_file 填路径，或直接把证书指纹填进 cert_fingerprint。

03

建对应的隧道

「隧道管理」新建隧道时，隧道名与 remote_port 必须与服务端一致，local_port 填本机要暴露的服务端口。

Troubleshooting

常见问题排查清单

多数「连不上」的原因都在这六条里，按顺序检查一遍基本就通了。

  • 01

    端口没放行

    安全组与本机防火墙是两套东西，只配一边等于没配。先确认 1237、8000 与转发端口在两边都放行。

  • 02

    证书指纹不匹配

    校验方式二选一即可：用 ca.crt 就不要同时填指纹；两者都填且不一致时握手会失败。

  • 03

    隧道名或端口不一致

    客户端隧道名与 remote_port 必须与服务端完全一致，否则服务端找不到对应隧道。

  • 04

    角色被锁定

    角色一旦写入，重复部署不会擅自切换，避免误操作把在跑的隧道断掉。换角色需显式加 --force-role。

  • 05

    内核残留

    同一份数据目录只允许一个转发内核。在面板点一次「停止内核」，即可清理本机所有残留内核与 pid 文件。

  • 06

    数据目录对不上

    源码方式直接跑 python -m tsmtravel 时数据会落到 ~/.tsmtravel；用 deploy.sh 部署则固定在项目根的 data/。迁移时把整个 data/ 带走。

Self Test

部署完先自测一遍

安装开发依赖后执行端到端用例：pip install -r requirements-dev.txt 之后跑 python -m pytest tests -q。用例覆盖反向转发、多客户端多隧道、错误 token 拒绝、断线重连、客户端离线后转发端口释放、动态申请端口白名单、TLS 1.3 协商与日志自动清理。

若本机没有装 pytest-asyncio，异步用例会报 async def functions are not natively supported；本项目用例都自带 asyncio.run，逐个文件跑不受影响，例如 python -m pytest tests/test_housekeeping.py -q。

压测脚本在 bench/bench.py，自带 echo 服务与双内核，可本机自测：python bench/bench.py --self-test --connections 5000 --hold 30 --report docs/bench_report.md。