ttyd 终端共享：8 类常见故障一篇搞定

ttyd 终端共享：8 类常见故障一篇搞定

【免费下载链接】ttydShare your terminal over the web项目地址: https://gitcode.com/gh_mirrors/tt/ttyd

你刚在服务器上敲下ttyd bash，浏览器打开却是一片空白，或者启动直接报红。别慌，ttyd 终端共享的坑大多不深。这篇按"还没跑起来"和"跑着跑着不对劲"两个阶段，带你过一遍 8 类常见问题。

还没跑起来就卡住了：端口、权限、证书三关 🔧

启动报 Address already in use：7681 端口被占了

症状：ttyd 一启动就提示端口被占用，进程直接退出。

原因：默认端口 7681 已经被别的服务占了，相当于两个服务抢同一个门牌号。

修复：先用lsof -i :7681看看是谁占着；懒得排查就直接换个端口启动：

ttyd -p 8080 bash

报 Permission denied：换个身份运行

症状：提示 Permission denied，或命令明明能跑 ttyd 里却执行不了。

原因：ttyd 默认用启动者的身份跑命令，权限不够就会挡回来。

修复：加-u和-g指定运行时的用户 ID、组 ID，比如ttyd -u 1000 -g 1000 bash。装不上 ttyd 的话，安装方式见 README.md。

浏览器提示不安全：SSL 证书要成对给

症状：浏览器弹出不安全警告，或 SSL 握手失败。

原因：开了 SSL 但证书、密钥路径没给全，或路径本身写错了。

修复：-S必须和-C（证书）、-K（密钥）一起用，路径都要指向真实存在的文件：

ttyd -S -C /etc/ssl/cert.pem -K /etc/ssl/key.pem bash

加了认证却登不进去：-c 格式是 user:pass

症状：浏览器弹出登录框，输什么都提示认证失败。

原因：-c参数格式固定为username:password，中间用英文冒号，用户名或密码里带特殊字符时容易踩坑。

修复：按ttyd -c admin:123456 bash这样写，密码尽量别用冒号和空格。

跑了一段时间后开始不对劲 ⚡

连接频繁掉线：把 ping 间隔放宽

症状：终端用着用着就断开，隔一会儿又自动重连。

原因：ttyd 默认每 5 秒发一次心跳，网络不稳或中间有严格防火墙时，这个节奏容易被掐掉。

修复：把心跳间隔拉长到 30 秒试试：

ttyd -P 30 bash

文件传不上去：ZMODEM 默认是关的

症状：在网页端执行sz或拖文件，没任何反应。

原因：文件传输功能默认关闭，而且服务端要装 lrzsz 或 trzsz 才能真正收发。

修复：启动时加-t enableZmodem=true打开 ZMODEM，同时确认服务器上已安装 lrzsz 或 trzsz。

浏览器里显示错乱：换一种渲染器

症状：某个浏览器里中文错位、颜色花屏，换浏览器又正常。

原因：网页端默认用 WebGL 渲染，个别浏览器或显卡驱动不支持就会画崩。

修复：改用 canvas 渲染，加一个参数即可：-t rendererType=canvas。

客户端越连越多：给连接数上道闸

症状：长期运行后 ttyd 进程内存慢慢上涨。

原因：默认不限制客户端数量（-m为 0），人越多资源吃得越狠。

修复：按实际场景限个上限，比如只允许 10 个客户端：

ttyd -m 10 bash

怎么让这类问题少发生：四条日常动作 🛠

• 用ttyd -v记住当前版本，有新发布时升级，不少小坑在新版已修掉
• 把完整的启动命令存成脚本或文档，换机器时直接复用，别靠记忆
• 默认就加上-m限制客户端数，让内存占用可预期
• 排查时临时加-d 0打开调试日志，参数含义查 man/ttyd.man.md

回头看这 8 类问题，没有一类是 ttyd 本身坏了——绝大多数根源都在启动参数、网络环境或权限配置上。把启动命令当成一份配置来维护，终端共享这件事就会顺得多。

【免费下载链接】ttydShare your terminal over the web项目地址: https://gitcode.com/gh_mirrors/tt/ttyd