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

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

一、环境信息

项目	说明
操作系统	OpenCloudOS 9 (x86_64)
ttyd版本	1.7.7
libwebsockets版本	4.3.2
tmux版本	3.4
目标端口	7681

二、完整安装流程

步骤1：安装系统依赖

bash 复制代码

yum install -y tmux json-c-devel libuv-devel zlib-devel openssl-devel cmake gcc make git vim wget unzip

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

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

bash 复制代码

cd /tmp
wget --timeout=120 --tries=3 https://github.com/warmcat/libwebsockets/archive/refs/tags/v4.3.2.tar.gz -O libwebsockets-4.3.2.tar.gz
tar xzf libwebsockets-4.3.2.tar.gz
cd libwebsockets-4.3.2
mkdir -p build && cd build
cmake -DLWS_WITHOUT_TESTAPPS=ON \
      -DLWS_WITHOUT_EXTENSIONS=OFF \
      -DLWS_WITH_SSL=ON \
      -DLWS_WITH_LIBUV=ON \
      ..
make -j$(nproc)
make install
ldconfig

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

步骤3：下载并编译 ttyd

bash 复制代码

cd /tmp
wget --timeout=60 --tries=3 https://github.com/tsl0922/ttyd/archive/refs/heads/master.zip -O ttyd-master.zip
unzip ttyd-master.zip
cd ttyd-main
mkdir -p build && cd build
cmake -DCMAKE_PREFIX_PATH=/usr/local ..
make -j$(nproc)
cp ttyd /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：启动服务

bash 复制代码

# 创建tmux会话
tmux new-session -d -s ai-work

# 后台启动ttyd
ttyd -p 7681 -W tmux attach -t ai-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 的情况

bash 复制代码

#!/bin/bash
set -e

# 1. 安装系统依赖
echo "[1/5] 安装系统依赖..."
yum install -y tmux json-c-devel libuv-devel zlib-devel openssl-devel cmake gcc make wget

# 2. 编译安装 libwebsockets
echo "[2/5] 编译安装 libwebsockets..."
cd /tmp
wget --timeout=120 --tries=3 https://github.com/warmcat/libwebsockets/archive/refs/tags/v4.3.2.tar.gz -O libwebsockets-4.3.2.tar.gz
tar xzf libwebsockets-4.3.2.tar.gz
cd libwebsockets-4.3.2
mkdir -p build && cd build
cmake -DLWS_WITHOUT_TESTAPPS=ON \
      -DLWS_WITHOUT_EXTENSIONS=OFF \
      -DLWS_WITH_SSL=ON \
      -DLWS_WITH_LIBUV=ON \
      ..
make -j$(nproc)
make install
ldconfig

# 3. 编译安装 ttyd
echo "[3/5] 编译安装 ttyd..."
cd /tmp
wget --timeout=60 --tries=3 https://github.com/tsl0922/ttyd/archive/refs/heads/master.tar.gz -O ttyd-master.tar.gz
tar xzf ttyd-master.tar.gz
cd ttyd-main
mkdir -p build && cd build
cmake -DCMAKE_PREFIX_PATH=/usr/local ..
make -j$(nproc)
cp ttyd /usr/local/bin/
chmod +x /usr/local/bin/ttyd

# 4. 创建tmux会话
echo "[4/5] 创建tmux会话..."
tmux new-session -d -s ai-work 2>/dev/null || true

# 5. 启动ttyd
echo "[5/5] 启动ttyd服务..."
ttyd -p 7681 -W tmux attach -t ai-work &

echo ""
echo "========================================"
echo "  ttyd 安装完成！"
echo "  访问地址: http://$(hostname -I | awk '{print $1}'):7681"
echo "========================================"

五、常用操作

bash 复制代码

# 查看ttyd进程
ps aux | grep ttyd

# 停止ttyd
kill $(pgrep -f "ttyd -p 7681")

# 重启ttyd
ttyd -p 7681 -W tmux attach -t ai-work &

# 查看tmux会话
tmux ls

# 附加到tmux会话
tmux attach -t ai-work

# 设置开机自启（可选）
echo 'ttyd -p 7681 -W tmux attach -t ai-work &' >> /etc/rc.local
chmod +x /etc/rc.local

六、开通防火墙

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

七、安全建议

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