ttyd Web终端安装指南（OpenCloudOS 9）

ttyd Web终端安装指南（OpenCloudOS 9）

基于实际踩坑经验总结，适用于 OpenCloudOS 9 / CentOS 9 Stream / RHEL 9 系列

一、环境信息

二、完整安装流程

步骤1：安装系统依赖

yuminstall-ytmux json-c-devel libuv-devel zlib-devel openssl-devel cmake gccmakegitvimwgetunzip

⚠️注意：libwebsockets-devel可以安装，但不要依赖它编译ttyd，因为系统包不包含CMake配置文件，详见下方踩坑说明。

步骤2：下载并编译 libwebsockets（从源码）

cd/tmpwget--timeout=120--tries=3https://github.com/warmcat/libwebsockets/archive/refs/tags/v4.3.2.tar.gz-Olibwebsockets-4.3.2.tar.gztarxzf libwebsockets-4.3.2.tar.gzcdlibwebsockets-4.3.2mkdir-pbuild&&cdbuild cmake-DLWS_WITHOUT_TESTAPPS=ON\-DLWS_WITHOUT_EXTENSIONS=OFF\-DLWS_WITH_SSL=ON\-DLWS_WITH_LIBUV=ON\..make-j$(nproc)makeinstallldconfig

⚠️关键参数：-DLWS_WITH_LIBUV=ON必须开启，否则ttyd编译会报错！

步骤3：下载并编译 ttyd

cd/tmpwget--timeout=60--tries=3https://github.com/tsl0922/ttyd/archive/refs/heads/master.zip-Ottyd-master.zipunzipttyd-master.zipcdttyd-mainmkdir-pbuild&&cdbuild cmake-DCMAKE_PREFIX_PATH=/usr/local..make-j$(nproc)cpttyd /usr/local/bin/chmod+x /usr/local/bin/ttyd

⚠️关键参数：-DCMAKE_PREFIX_PATH=/usr/local必须指定，否则CMake找不到libwebsockets的配置文件。

步骤4：开放防火墙端口

在腾讯云轻量应用服务器控制台，或使用API/CLI开放7681端口：

• 协议：TCP
• 端口：7681
• 来源：0.0.0.0/0（如需限制访问可改为指定IP）
• 策略：允许

步骤5：启动服务

# 创建tmux会话tmux new-session-d-sai-work# 后台启动ttydttyd-p7681-Wtmux attach-tai-work&

-W参数表示只读模式（浏览器端可观察但无法输入），如需可交互则去掉该参数。

步骤6：验证

浏览器访问：http://<服务器IP>:7681

三、踩坑记录与避坑指南

坑1：系统 libwebsockets-devel 不含 CMake 配置文件

现象：

CMake Error: Could not find a package configuration file provided by "Libwebsockets"

原因：OpenCloudOS 9 的libwebsockets-devel包只安装了头文件和库文件，没有安装LibwebsocketsConfig.cmake，CMake 的find_package无法定位。

解决：必须从源码编译 libwebsockets，源码编译后会自动生成并安装 CMake 配置文件到/usr/local/lib/cmake/libwebsockets/。

坑2：libwebsockets 未启用 libuv 支持

现象：

CMake Error: libwebsockets was not build with libuv support (-DLWS_WITH_LIBUV=ON)

原因：ttyd 依赖 libwebsockets 的 libuv 事件循环支持，默认编译 libwebsockets 时不会启用。

解决：编译 libwebsockets 时必须添加-DLWS_WITH_LIBUV=ON参数。

坑3：json-c 头文件路径不在默认搜索路径

现象：

fatal error: json.h: No such file or directory

原因：json-c 的头文件安装在/usr/include/json-c/子目录下，直接 gcc 编译时找不到。

解决：使用 CMake 编译 ttyd 时会自动处理头文件路径，不要尝试手动 gcc 编译。

坑4：GitHub 下载超时/zip文件损坏

现象：

• wget 下载超时
• unzip 报错End-of-central-directory signature not found

原因：国内服务器访问 GitHub 不稳定，下载可能中断导致文件损坏。

解决：

• 使用--timeout=120 --tries=3增加超时和重试次数
• 优先使用.tar.gz格式而非.zip（更容错）
• 如果下载失败，删除已下载文件后重试
• 下载后验证文件大小是否合理

坑5：CMAKE_PREFIX_PATH 未设置

现象：CMake 找不到源码安装的 libwebsockets。

原因：源码安装到/usr/local，但 CMake 默认搜索路径可能不包含该位置。

解决：编译 ttyd 时显式指定-DCMAKE_PREFIX_PATH=/usr/local。

四、一键安装脚本

适用于全新 OpenCloudOS 9 系统，网络可达 GitHub 的情况

#!/bin/bashset-e# 1. 安装系统依赖echo"[1/5] 安装系统依赖..."yuminstall-ytmux json-c-devel libuv-devel zlib-devel openssl-devel cmake gccmakewget# 2. 编译安装 libwebsocketsecho"[2/5] 编译安装 libwebsockets..."cd/tmpwget--timeout=120--tries=3https://github.com/warmcat/libwebsockets/archive/refs/tags/v4.3.2.tar.gz-Olibwebsockets-4.3.2.tar.gztarxzf libwebsockets-4.3.2.tar.gzcdlibwebsockets-4.3.2mkdir-pbuild&&cdbuild cmake-DLWS_WITHOUT_TESTAPPS=ON\-DLWS_WITHOUT_EXTENSIONS=OFF\-DLWS_WITH_SSL=ON\-DLWS_WITH_LIBUV=ON\..make-j$(nproc)makeinstallldconfig# 3. 编译安装 ttydecho"[3/5] 编译安装 ttyd..."cd/tmpwget--timeout=60--tries=3https://github.com/tsl0922/ttyd/archive/refs/heads/master.tar.gz-Ottyd-master.tar.gztarxzf ttyd-master.tar.gzcdttyd-mainmkdir-pbuild&&cdbuild cmake-DCMAKE_PREFIX_PATH=/usr/local..make-j$(nproc)cpttyd /usr/local/bin/chmod+x /usr/local/bin/ttyd# 4. 创建tmux会话echo"[4/5] 创建tmux会话..."tmux new-session-d-sai-work2>/dev/null||true# 5. 启动ttydecho"[5/5] 启动ttyd服务..."ttyd-p7681-Wtmux attach-tai-work&echo""echo"========================================"echo" ttyd 安装完成！"echo" 访问地址: http://$(hostname-I|awk'{print $1}'):7681"echo"========================================"

五、常用操作

# 查看ttyd进程psaux|grepttyd# 停止ttydkill$(pgrep-f"ttyd -p 7681")# 重启ttydttyd-p7681-Wtmux attach-tai-work&# 查看tmux会话tmuxls# 附加到tmux会话tmux attach-tai-work# 设置开机自启（可选）echo'ttyd -p 7681 -W tmux attach -t ai-work &'>>/etc/rc.localchmod+x /etc/rc.local

六、开通防火墙

腾讯云平台防火墙已放行 7681 端口，但服务器内部的 firewalld 也需要单独放行!

七、安全建议

1. 设置访问密码：ttyd -p 7681 -c <用户名>:<密码> tmux attach -t ai-work
2. 限制访问IP：防火墙规则中指定来源IP，而非 0.0.0.0/0
3. 启用HTTPS：ttyd -p 7681 -S -C cert.pem -K key.pem tmux attach -t ai-work
4. 使用只读模式：-W参数防止浏览器端误操作