ttyd Web终端安装指南OpenCloudOS 9基于实际踩坑经验总结适用于 OpenCloudOS 9 / CentOS 9 Stream / RHEL 9 系列一、环境信息项目说明操作系统OpenCloudOS 9 (x86_64)ttyd版本1.7.7libwebsockets版本4.3.2tmux版本3.4目标端口7681二、完整安装流程步骤1安装系统依赖yuminstall-ytmux json-c-devel libuv-devel zlib-devel openssl-devel cmake gccmakegitvimwgetunzip⚠️注意libwebsockets-devel可以安装但不要依赖它编译ttyd因为系统包不包含CMake配置文件详见下方踩坑说明。步骤2下载并编译 libwebsockets从源码cd/tmpwget--timeout120--tries3https://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-pbuildcdbuild cmake-DLWS_WITHOUT_TESTAPPSON\-DLWS_WITHOUT_EXTENSIONSOFF\-DLWS_WITH_SSLON\-DLWS_WITH_LIBUVON\..make-j$(nproc)makeinstallldconfig⚠️关键参数-DLWS_WITH_LIBUVON必须开启否则ttyd编译会报错步骤3下载并编译 ttydcd/tmpwget--timeout60--tries3https://github.com/tsl0922/ttyd/archive/refs/heads/master.zip-Ottyd-master.zipunzipttyd-master.zipcdttyd-mainmkdir-pbuildcdbuild cmake-DCMAKE_PREFIX_PATH/usr/local..make-j$(nproc)cpttyd /usr/local/bin/chmodx /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.cmakeCMake 的find_package无法定位。解决必须从源码编译 libwebsockets源码编译后会自动生成并安装 CMake 配置文件到/usr/local/lib/cmake/libwebsockets/。坑2libwebsockets 未启用 libuv 支持现象CMake Error: libwebsockets was not build with libuv support (-DLWS_WITH_LIBUVON)原因ttyd 依赖 libwebsockets 的 libuv 事件循环支持默认编译 libwebsockets 时不会启用。解决编译 libwebsockets 时必须添加-DLWS_WITH_LIBUVON参数。坑3json-c 头文件路径不在默认搜索路径现象fatal error: json.h: No such file or directory原因json-c 的头文件安装在/usr/include/json-c/子目录下直接 gcc 编译时找不到。解决使用 CMake 编译 ttyd 时会自动处理头文件路径不要尝试手动 gcc 编译。坑4GitHub 下载超时/zip文件损坏现象wget 下载超时unzip 报错End-of-central-directory signature not found原因国内服务器访问 GitHub 不稳定下载可能中断导致文件损坏。解决使用--timeout120 --tries3增加超时和重试次数优先使用.tar.gz格式而非.zip更容错如果下载失败删除已下载文件后重试下载后验证文件大小是否合理坑5CMAKE_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--timeout120--tries3https://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-pbuildcdbuild cmake-DLWS_WITHOUT_TESTAPPSON\-DLWS_WITHOUT_EXTENSIONSOFF\-DLWS_WITH_SSLON\-DLWS_WITH_LIBUVON\..make-j$(nproc)makeinstallldconfig# 3. 编译安装 ttydecho[3/5] 编译安装 ttyd...cd/tmpwget--timeout60--tries3https://github.com/tsl0922/ttyd/archive/refs/heads/master.tar.gz-Ottyd-master.tar.gztarxzf ttyd-master.tar.gzcdttyd-mainmkdir-pbuildcdbuild cmake-DCMAKE_PREFIX_PATH/usr/local..make-j$(nproc)cpttyd /usr/local/bin/chmodx /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-workechoechoecho ttyd 安装完成echo 访问地址: http://$(hostname-I|awk{print $1}):7681echo五、常用操作# 查看ttyd进程psaux|grepttyd# 停止ttydkill$(pgrep-fttyd -p 7681)# 重启ttydttyd-p7681-Wtmux attach-tai-work# 查看tmux会话tmuxls# 附加到tmux会话tmux attach-tai-work# 设置开机自启可选echottyd -p 7681 -W tmux attach -t ai-work /etc/rc.localchmodx /etc/rc.local六、开通防火墙腾讯云平台防火墙已放行 7681 端口但服务器内部的 firewalld 也需要单独放行!七、安全建议设置访问密码ttyd -p 7681 -c 用户名:密码 tmux attach -t ai-work限制访问IP防火墙规则中指定来源IP而非 0.0.0.0/0启用HTTPSttyd -p 7681 -S -C cert.pem -K key.pem tmux attach -t ai-work使用只读模式-W参数防止浏览器端误操作
ttyd Web终端安装指南（OpenCloudOS 9）
发布时间：2026/5/30 6:13:03
ttyd Web终端安装指南OpenCloudOS 9基于实际踩坑经验总结适用于 OpenCloudOS 9 / CentOS 9 Stream / RHEL 9 系列一、环境信息项目说明操作系统OpenCloudOS 9 (x86_64)ttyd版本1.7.7libwebsockets版本4.3.2tmux版本3.4目标端口7681二、完整安装流程步骤1安装系统依赖yuminstall-ytmux json-c-devel libuv-devel zlib-devel openssl-devel cmake gccmakegitvimwgetunzip⚠️注意libwebsockets-devel可以安装但不要依赖它编译ttyd因为系统包不包含CMake配置文件详见下方踩坑说明。步骤2下载并编译 libwebsockets从源码cd/tmpwget--timeout120--tries3https://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-pbuildcdbuild cmake-DLWS_WITHOUT_TESTAPPSON\-DLWS_WITHOUT_EXTENSIONSOFF\-DLWS_WITH_SSLON\-DLWS_WITH_LIBUVON\..make-j$(nproc)makeinstallldconfig⚠️关键参数-DLWS_WITH_LIBUVON必须开启否则ttyd编译会报错步骤3下载并编译 ttydcd/tmpwget--timeout60--tries3https://github.com/tsl0922/ttyd/archive/refs/heads/master.zip-Ottyd-master.zipunzipttyd-master.zipcdttyd-mainmkdir-pbuildcdbuild cmake-DCMAKE_PREFIX_PATH/usr/local..make-j$(nproc)cpttyd /usr/local/bin/chmodx /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.cmakeCMake 的find_package无法定位。解决必须从源码编译 libwebsockets源码编译后会自动生成并安装 CMake 配置文件到/usr/local/lib/cmake/libwebsockets/。坑2libwebsockets 未启用 libuv 支持现象CMake Error: libwebsockets was not build with libuv support (-DLWS_WITH_LIBUVON)原因ttyd 依赖 libwebsockets 的 libuv 事件循环支持默认编译 libwebsockets 时不会启用。解决编译 libwebsockets 时必须添加-DLWS_WITH_LIBUVON参数。坑3json-c 头文件路径不在默认搜索路径现象fatal error: json.h: No such file or directory原因json-c 的头文件安装在/usr/include/json-c/子目录下直接 gcc 编译时找不到。解决使用 CMake 编译 ttyd 时会自动处理头文件路径不要尝试手动 gcc 编译。坑4GitHub 下载超时/zip文件损坏现象wget 下载超时unzip 报错End-of-central-directory signature not found原因国内服务器访问 GitHub 不稳定下载可能中断导致文件损坏。解决使用--timeout120 --tries3增加超时和重试次数优先使用.tar.gz格式而非.zip更容错如果下载失败删除已下载文件后重试下载后验证文件大小是否合理坑5CMAKE_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--timeout120--tries3https://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-pbuildcdbuild cmake-DLWS_WITHOUT_TESTAPPSON\-DLWS_WITHOUT_EXTENSIONSOFF\-DLWS_WITH_SSLON\-DLWS_WITH_LIBUVON\..make-j$(nproc)makeinstallldconfig# 3. 编译安装 ttydecho[3/5] 编译安装 ttyd...cd/tmpwget--timeout60--tries3https://github.com/tsl0922/ttyd/archive/refs/heads/master.tar.gz-Ottyd-master.tar.gztarxzf ttyd-master.tar.gzcdttyd-mainmkdir-pbuildcdbuild cmake-DCMAKE_PREFIX_PATH/usr/local..make-j$(nproc)cpttyd /usr/local/bin/chmodx /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-workechoechoecho ttyd 安装完成echo 访问地址: http://$(hostname-I|awk{print $1}):7681echo五、常用操作# 查看ttyd进程psaux|grepttyd# 停止ttydkill$(pgrep-fttyd -p 7681)# 重启ttydttyd-p7681-Wtmux attach-tai-work# 查看tmux会话tmuxls# 附加到tmux会话tmux attach-tai-work# 设置开机自启可选echottyd -p 7681 -W tmux attach -t ai-work /etc/rc.localchmodx /etc/rc.local六、开通防火墙腾讯云平台防火墙已放行 7681 端口但服务器内部的 firewalld 也需要单独放行!七、安全建议设置访问密码ttyd -p 7681 -c 用户名:密码 tmux attach -t ai-work限制访问IP防火墙规则中指定来源IP而非 0.0.0.0/0启用HTTPSttyd -p 7681 -S -C cert.pem -K key.pem tmux attach -t ai-work使用只读模式-W参数防止浏览器端误操作
