在 Debian 上部署 ttyd Web 终端

背景

ttyd 是一个通过浏览器访问终端的工具，Debian 官方源没有收录，需要手动安装。

1. 下载安装

curl -L https://github.com/tsl0922/ttyd/releases/download/1.7.7/ttyd.x86_64 -o /tmp/ttyd
sudo mv /tmp/ttyd /usr/local/bin/ttyd
sudo chmod +x /usr/local/bin/ttyd
ttyd --version

2. 配置 systemd service

sudo tee /etc/systemd/system/ttyd.service << 'EOF'
[Unit]
Description=ttyd - Terminal over HTTP/HTTPS
After=network.target

[Service]
Type=simple
User=claw
ExecStart=/usr/local/bin/ttyd -d0 -W -t rendererType=canvas -t closeOnDisconnect=false -t disableLeaveAlert=true -t fontSize=15 -t fontFamily=monospace --port 7681 tmux new-session -A -s main
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

关键参数说明：

• User=claw — 以指定用户身份运行，不用 root
• -W — 开启可写模式（必须）
• -d0 — 关闭多余日志
• rendererType=canvas — 使用 canvas 渲染器，解决浏览器输入无反应的问题
• closeOnDisconnect=false — 断开后不关闭 session，重连回来还是原来的状态
• disableLeaveAlert=true — 关闭离开页面的警告弹窗
• --port 7681 — 监听端口
• tmux new-session -A -s main — 启动或接入名为 main 的 tmux session，网络断线重连后状态完全保留

3. 启动并设置开机自启

sudo systemctl daemon-reload
sudo systemctl enable ttyd
sudo systemctl start ttyd
sudo systemctl status ttyd

4. 访问

浏览器打开 http://<内网IP>:7681，点击终端区域即可输入。

常见问题

Q: 界面能显示但输入无反应？
A: 加 -t rendererType=canvas 参数，这是关键。默认的 WebGL 渲染器在某些浏览器 + HTTP 环境下会导致键盘事件无法捕获。

Q: apt install ttyd 找不到包？
A: Debian/Ubuntu 官方源未收录，从 GitHub Releases 下载预编译二进制即可，无需编译。

Q: 网络不稳定，断线后终端状态丢失？
A: 用 tmux 接管终端（tmux new-session -A -s main），配合 closeOnDisconnect=false，断线重连后自动恢复到原来的 session，正在运行的命令不会中断。