企业官网建设流程全解析

ttyd 终端共享连不上？4 步快速定位故障

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

ttyd 是一个能在网页上共享终端的命令行工具：一条命令，就能在任意带浏览器的设备上操作 shell。真正拿它做终端共享时，连不上、操作没反应、动不动就断线，都可能发生。这份指南按启动命令到浏览器端的路径带你看一遍 ttyd 的故障，帮你快速定位问题。

什么情况下容易出问题

远程管理。机器在机房或者防火墙后面，你靠 ttyd 把 shell 暴露到浏览器里，结果页面打不开，或者会话在最关键的时候断掉。现场没有本地屏幕可看，只能跟着日志线索走。

教学演示。讲师把自己的操作共享给全班，SSL 警告页、中文乱码、偶发断线都会被投屏放大。演示一停，课堂节奏就停了。

团队协作。几个人同时连上观察同一个 shell，有人要传文件，ZMODEM 传输出问题；有人操作半天发现终端只读，误以为是工具坏了。

按这个顺序查，别跳步

1. 看进程。在服务器上执行ps aux | grep ttyd，确认 ttyd 进程还活着。如果进程不存在，说明启动命令本身失败了，回终端读报错原文；如果进程在，进入第 2 步。
2. 看端口。ttyd 默认监听 7681 端口，用netstat -tulpn | grep 7681确认监听状态。如果日志里是Address already in use或端口被别的进程占着，用-p 8080换个端口再启动（该参数指定监听端口）；如果端口监听正常，继续查可达性。
3. 看页面，用本机测试。在跑 ttyd 的这台机器上用浏览器打开http://127.0.0.1:7681。本机页面能打开、远程打不开，多半是防火墙或安全组没放行；本机也是空白页，就打开浏览器控制台，读 WebSocket 相关的报错文本。
4. 看日志。启动命令后追加-d 0再跑一次，它用于设置日志级别，数字越小越详细，0 是最细的 DEBUG 输出。日志里出现证书、权限或连接类错误，可以直接跳到下面的对应坑位。

最容易被忽略的几个坑

证书和密钥不配对：SSL 握手失败的排查

浏览器提示不安全、连接直接失败时，常见原因不是证书过期，而是-C（证书文件路径）和-K（密钥文件路径）指错了文件，或者这两个文件根本不属于同一对密钥。先验证配对：

openssl x509 -noout -modulus -in server.crt | openssl md5 openssl rsa -noout -modulus -in server.key | openssl md5

两行输出的 md5 一致，证书对没问题，再检查有效期和域名是否匹配；不一致就重新生成。ttyd 手册里附了用 openssl 生成自签证书的完整流程，可以直接照做。

终端共享频繁掉线：先查 NAT 超时和反向代理

连接放一会儿就断、公网环境必断，往往不是 ttyd 本身的问题。它默认每 5 秒发一次心跳，通常足够；真正的元凶常常是中间设备（NAT、负载均衡）把空闲连接掐了，或者 nginx 这类反向代理没有转发 WebSocket 升级请求。可以先把-P 30（WebSocket 心跳间隔，单位秒）调大观察是否改善；走代理部署时，重点检查代理配置里有没有Upgrade和Connection "upgrade"这两个头部，缺了它们连接会在上游被直接丢弃。

文件传输不生效：两个前提都缺

浏览器端sz/rz没反应时，先确认两件事：服务器上装了 lrzsz（ZMODEM 协议的命令实现），以及启动 ttyd 时把客户端选项传给浏览器页面。只装 lrzsz 是不够的：

ttyd -W -t enableZmodem=true bash

-W开放写入权限（终端默认只读），-t把选项传给浏览器页面，加上enableZmodem=true后 ZMODEM 传文件才可用。

让它别再复发

• 用-m 10限制最大客户端数（默认不限），防止页面长期挂着拖垮机器。
• 暴露公网时加-c user:pass启用基本认证，别裸奔。
• 走反向代理时用真实证书代替自签证书，减少浏览器警告和误拦截。
• 把带全部参数的启动命令写成固定脚本，重启可复现。
• 定期ps看一眼进程内存，持续上涨就重启。

卡住时，手册源文件 里有完整参数表和 nginx 反向代理示例；服务端连接处理逻辑在 src/ 目录，可以对照代码确认行为。

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