文档

telesh 使用手册

从安装到自托管服务端，这里是完整的配置与概念说明。命令行极简——只有一个数据目录开关，其余都在本地 UI 上完成。

概览

telesh 由两部分组成：常驻在你要发布服务的那台机器上的 agent（telesh），以及可自托管的 服务端（telesh-server）。agent 主动向服务端发起连接，因此位于 NAT 或防火墙后面的机器无需公网 IP。

发布本地端口

把 HTTP / TCP 服务暴露到公网域名或端口。

镜像远端端口

通过 P2P 把远端主机的端口映射到本地。

安装

两个程序都是无运行时依赖的单文件二进制。可以从源码用 cargo 安装，也可以从 Releases 下载对应平台的构建产物。

terminal

# 需要 Rust 1.91+
cargo install --git https://github.com/zeaphoo/telesh telesh
cargo install --git https://github.com/zeaphoo/telesh telesh-server

快速开始

写一行控制面地址，启动 agent，然后在本地 UI 上勾选要发布的端口即可。

terminal

# 1. 写入控制面地址（不存在会自动生成）
control_server = "tunnel.example.com:9009"

# 2. 启动常驻 agent
$ telesh
info agent starting ui=127.0.0.1:16345

# 3. 打开本地管理界面，勾选要发布的端口

本地管理界面默认固定在 http://127.0.0.1:16345，只监听回环地址，不会对外暴露。

数据目录

默认是 ~/.telesh，可以用 --dataroot 指定。身份、会话与发布配置都保存在这里。

目录结构

~/.telesh/
├── config.toml   # control_server 地址
├── state         # Ed25519 身份 + 缓存的 session
├── publish.json  # UI 上的发布配置（声明式）
└── traces/       # 请求日志（按通道持久化）

配置参考

配置文件的唯一必填项是控制面地址。文件不存在时会自动生成一份默认的（连本机 127.0.0.1:9009）；存在但缺少 control_server 才会报错退出。

~/.telesh/config.toml

# 唯一必填项：要连的 control server
control_server = "tunnel.example.com:9009"

# 只写 host 时端口默认 9009
# 粘贴 ws://host:port/api/tunnel 也认
control_server = "ws://tunnel.example.com:9009/api/tunnel"

发布模型

发布配置是一份声明式状态：进程持续把实际运行状态收敛到这份期望状态。同一条目运行时有四种状态：pending、live、error、target_gone（本地端口消失）。

~/.telesh/publish.json

[
  { "kind": "http",   "local_port": 8000, "sub_domain": "app" },
  { "kind": "tcp",    "local_port": 22,   "remote_port": null },
  { "kind": "p2p",    "local_port": 5432, "name": "db" },
  { "kind": "mirror", "local_port": 18000, "remote": "000012345/web" }
]

http 把本地端口发布为固定子域名（自动 HTTPS）。
tcp 把本地端口映射到服务端的公网 TCP 端口。
p2p 通过 iroh 直接暴露本地端口，供对端 P2P 访问。
mirror 把远端 account/name 镜像到本地监听端口。

服务端部署

服务端用一个 TOML 配置文件启动控制面、数据面与可选的内嵌 iroh relay。控制面同一端口也提供 dashboard 与 /api/*。

/etc/telesh/server.toml

# 数据根目录：数据库、ACME 缓存等
dataroot = "~/.telesh/server/"

# agent 连控制面（同端口也提供 dashboard）
control_addr = "0.0.0.0:9009"

# 公网 HTTP / TCP 边缘入口
ingress_addr = "0.0.0.0:8008"

# 数据面：agent 主动连这里
data_addr = "0.0.0.0:9008"

# 拼隧道 URL 用的公网后缀
public_host = "tunnel.example.com"

[relay]
# 进程内 iroh 中继（可选）；ACME 自动签发证书
serve = "0.0.0.0:8081"
acme = ["relay.example.com"]
acme_email = "admin@example.com"

terminal

# 命令行只有配置文件一个参数
$ telesh-server /etc/telesh/server.toml

架构

控制面

WebSocket（JSON）长连接，承载登录、子域名与 TCP 端口注册、P2P 目录、保活与计量。只有小消息，没有载荷。

数据面

agent 主动连入的独立 TCP 连接，用 yamux 多路复用：信令流走 CBOR，其余每条公网连接一条纯字节流。

P2P 数据面

基于 iroh（打洞 QUIC）。对端解析目录拿到地址后直连，载荷不经过服务端；无法直连时自动回退到加密中继。

安全

设备和账号使用 Ed25519 密钥对做挑战-应答登录，首次登录即建号（TOFU），会话令牌以 SHA-256 存储、固定 12 小时有效期。
访问服务时服务端签发短期、不透明的访问令牌，作用域限定在 account/name；agent 在线向服务端校验，数据面无需保管密钥。
P2P 连接是加密的 QUIC，对端身份由 EndpointId 认证；中继同样加密。

还想要更多？

源码、设计文档与问题跟踪都在 GitHub 上。

前往仓库