ttyd 网页刷不出终端?从端口到 SSL 的四层排查指南【免费下载链接】ttydShare your terminal over the web项目地址: https://gitcode.com/gh_mirrors/tt/ttyd你敲完ttyd bash,浏览器打开 7681 端口却一片白屏,终端里只有一行干巴巴的报错。ttyd 是把本机终端通过网页共享出去的工具,白屏、断连、权限报错,十有八九出在下面四层。30 秒快检:动手深挖之前先跑这几条lsof -i :7681— 端口到底被谁占着curl -i http://localhost:7681/— 返回 200 还是 401,一眼分出网络层和认证层ps aux | grep ttyd— 进程是否还活着,参数和你记的一致吗ttyd -v— 版本对不对得上文档端口没起来?Address already in use 大概率是旧进程占着ttyd 启动只做两件事:绑定端口、等浏览器连进来。网络层的问题几乎都卡在这第一步。如果启动就报Address already in use,先lsof -i :7681找出占端口的进程,kill掉再重启;懒得查的话,直接ttyd -p 8080 bash换端口。如果本机正常、远端机器Connection refused,先ss -tlnp | grep 7681看监听地址:显示127.0.0.1说明绑到了回环或指定网卡(-i参数),去掉这个限制。纯 IPv6 环境连不通,加-6打开双栈。401 和 Permission denied:认证与 uid 分两条线查ttyd 默认只读,还要过 Basic Auth 和系统用户两道关,任何一道对不上,客户端就被挡在门外。如果浏览器弹登录框,密码没错却还 401,八成是-c user:pass里的特殊字符被 shell 吃了,先换成简单密码验证。如果 401 都没有、连上后执行命令报Permission denied,那是进程身份问题:用-u和-g指定运行用的 uid 和 gid;走 unix socket 时,再看/var/run/ttyd.sock的属主,必要时加-U user:group。如果终端能连上、敲字却没反应,注意 ttyd 默认 readonly,加-W才放行写入。SSL 握手失败、连接频繁断开:证书与 ping 间隔一起看浏览器和 ttyd 之间隔着 WebSocket,证书、心跳、反向代理任何一项错位,表现都是连上了又掉。如果浏览器报 SSL 错误,先用openssl s_client -connect host:7681看证书链;-C和-K必须指向同一对证书和私钥,启用客户端证书校验再加-A指定 CA。如果连接每隔几分钟断一次,心跳默认-P 5秒,先把 nginx 的Upgrade、Connection头透传好,再考虑调 ping 间隔。挂在 nginx 下,还要给 ttyd 加-b /ttyd对齐代理路径,配置示例见 man 手册。认证交给前端网关做的话,用-H指定代理透传的头,让 ttyd 跳过 Basic Auth。浏览器白屏、传文件没反应:问题多半在客户端环境页面由 xterm.js 渲染,浏览器环境、client options、传输插件都在这一层。如果白屏且控制台报 WebGL 相关错误,换 canvas 渲染:ttyd -t rendererTypecanvas bash。如果 ZMODEM 传文件没反应,服务端装 lrzsz 还不够,客户端要显式加-t enableZmodemtrue,或者用-t enableTrzsztrue走 trzsz。老浏览器、手机浏览器表现怪,优先换 Chrome 或 Firefox,再看控制台的具体报错。一次完整排障实录:从白屏到终端跑起来上周帮同事排查一台服务器,浏览器打开 7681 就是白屏。我先跑lsof -i :7681,端口上躺着一个昨天的旧 ttyd 进程——新进程其实根本没起来,报错被日志刷过去了。kill掉旧进程,重启,页面终于有内容,但终端只能看不能敲。翻启动参数,漏了-W,补上再刷新,输入恢复正常。接着同事从另一台机器访问还是Connection refused,ss -tlnp一查,监听地址是127.0.0.1,启动命令里残留了一个-i lo。去掉再启动,curl从外部机器能通,浏览器再刷一次,终端已经跑起来了。复盘这条链,连着踩了三层:端口占用、只读默认值、回环绑定。按层往下捋,每一步都有明确信号,不用猜。日常体检清单定期lsof -i :7681看端口,清掉残留的旧进程启动参数(尤其-c、-W、-b)写进部署文档,重启不漂移用-m限制最大客户端数,长期运行定期看进程内存用了 SSL 的,记下证书到期时间,提前换反向代理改完配置,用curl验证 WebSocket upgrade 是否透传手头留一条调试命令:ttyd -d 0 bash,日志拉满再复现升级版本前,对照 man 手册 核对参数变化下次再碰上白屏,不用干瞪眼:四层顺序捋一遍,再刷一次,终端已经跑起来了。【免费下载链接】ttydShare your terminal over the web项目地址: https://gitcode.com/gh_mirrors/tt/ttyd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/11/3 18:58:25 · 阅读 1.2k ttyd 网页刷不出终端?从端口到 SSL 的四层排查指南
ttyd 网页刷不出终端?从端口到 SSL 的四层排查指南【免费下载链接】ttydShare your terminal over the web项目地址: https://gitcode.com/gh_mirrors/tt/ttyd你敲完ttyd bash,浏览器打开 7681 端口却一片白屏,终端里只有一行干巴巴的报错。ttyd 是把本机终端通过网页共享出去的工具,白屏、断连、权限报错,十有八九出在下面四层。30 秒快检:动手深挖之前先跑这几条lsof -i :7681— 端口到底被谁占着curl -i http://localhost:7681/— 返回 200 还是 401,一眼分出网络层和认证层ps aux | grep ttyd— 进程是否还活着,参数和你记的一致吗ttyd -v— 版本对不对得上文档端口没起来?Address already in use 大概率是旧进程占着ttyd 启动只做两件事:绑定端口、等浏览器连进来。网络层的问题几乎都卡在这第一步。如果启动就报Address already in use,先lsof -i :7681找出占端口的进程,kill掉再重启;懒得查的话,直接ttyd -p 8080 bash换端口。如果本机正常、远端机器Connection refused,先ss -tlnp | grep 7681看监听地址:显示127.0.0.1说明绑到了回环或指定网卡(-i参数),去掉这个限制。纯 IPv6 环境连不通,加-6打开双栈。401 和 Permission denied:认证与 uid 分两条线查ttyd 默认只读,还要过 Basic Auth 和系统用户两道关,任何一道对不上,客户端就被挡在门外。如果浏览器弹登录框,密码没错却还 401,八成是-c user:pass里的特殊字符被 shell 吃了,先换成简单密码验证。如果 401 都没有、连上后执行命令报Permission denied,那是进程身份问题:用-u和-g指定运行用的 uid 和 gid;走 unix socket 时,再看/var/run/ttyd.sock的属主,必要时加-U user:group。如果终端能连上、敲字却没反应,注意 ttyd 默认 readonly,加-W才放行写入。SSL 握手失败、连接频繁断开:证书与 ping 间隔一起看浏览器和 ttyd 之间隔着 WebSocket,证书、心跳、反向代理任何一项错位,表现都是连上了又掉。如果浏览器报 SSL 错误,先用openssl s_client -connect host:7681看证书链;-C和-K必须指向同一对证书和私钥,启用客户端证书校验再加-A指定 CA。如果连接每隔几分钟断一次,心跳默认-P 5秒,先把 nginx 的Upgrade、Connection头透传好,再考虑调 ping 间隔。挂在 nginx 下,还要给 ttyd 加-b /ttyd对齐代理路径,配置示例见 man 手册。认证交给前端网关做的话,用-H指定代理透传的头,让 ttyd 跳过 Basic Auth。浏览器白屏、传文件没反应:问题多半在客户端环境页面由 xterm.js 渲染,浏览器环境、client options、传输插件都在这一层。如果白屏且控制台报 WebGL 相关错误,换 canvas 渲染:ttyd -t rendererTypecanvas bash。如果 ZMODEM 传文件没反应,服务端装 lrzsz 还不够,客户端要显式加-t enableZmodemtrue,或者用-t enableTrzsztrue走 trzsz。老浏览器、手机浏览器表现怪,优先换 Chrome 或 Firefox,再看控制台的具体报错。一次完整排障实录:从白屏到终端跑起来上周帮同事排查一台服务器,浏览器打开 7681 就是白屏。我先跑lsof -i :7681,端口上躺着一个昨天的旧 ttyd 进程——新进程其实根本没起来,报错被日志刷过去了。kill掉旧进程,重启,页面终于有内容,但终端只能看不能敲。翻启动参数,漏了-W,补上再刷新,输入恢复正常。接着同事从另一台机器访问还是Connection refused,ss -tlnp一查,监听地址是127.0.0.1,启动命令里残留了一个-i lo。去掉再启动,curl从外部机器能通,浏览器再刷一次,终端已经跑起来了。复盘这条链,连着踩了三层:端口占用、只读默认值、回环绑定。按层往下捋,每一步都有明确信号,不用猜。日常体检清单定期lsof -i :7681看端口,清掉残留的旧进程启动参数(尤其-c、-W、-b)写进部署文档,重启不漂移用-m限制最大客户端数,长期运行定期看进程内存用了 SSL 的,记下证书到期时间,提前换反向代理改完配置,用curl验证 WebSocket upgrade 是否透传手头留一条调试命令:ttyd -d 0 bash,日志拉满再复现升级版本前,对照 man 手册 核对参数变化下次再碰上白屏,不用干瞪眼:四层顺序捋一遍,再刷一次,终端已经跑起来了。【免费下载链接】ttydShare your terminal over the web项目地址: https://gitcode.com/gh_mirrors/tt/ttyd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考