如何使用 WeTTY 将终端直接转发到浏览器

想象一下这种场景：你急需从平板、别人的笔记本或一台安全策略严格的工作电脑访问家庭服务器或工作虚拟机，但端口 22 被完全封锁，也无法安装合适的 SSH 客户端。你打开浏览器，输入一个地址，就能获得一个功能完整的命令行界面，带有你熟悉的 shell 环境。

这正是 WeTTY 项目（Web + TTY）的设计初衷。

技术原理

Ajaxterm 或 Anyterm 等老旧解决方案因为依赖来回传输的常规 HTTP 请求，速度慢得令人痛苦。WeTTY 的工作方式不同。后端使用 TypeScript 和 Node.js 构建，与浏览器的通信通过 WebSockets 进行，渲染由 xterm.js 终端模拟器处理（正是驱动 VS Code 的那个）。

得益于 xterm.js 和 WebSocket 的结合，如果你有稳定的网络连接，输入延迟几乎察觉不到。伪图形工具在浏览器窗口中也能正常工作：htop、tmux、mc、vim 和 nano。鼠标支持、热键和终端颜色都按预期运行。

如何启动

你可以用两种快速方式部署该工具：通过 npm 或在 Docker 容器中运行。

方式一：通过 npm 安装

如果机器已安装 Node.js 20 或更高版本，以及构建工具（make、python、build-essential），可以用一条命令安装该工具：

npm -g i wetty

安装后，启动服务：

wetty --port 3000

现在导航到 http://localhost:3000 并用所需用户登录。如果 WeTTY 以普通用户身份运行，它会默认建立到 localhost 的 SSH 会话。以 root 身份运行则会调用 /bin/login。

方式二：在 Docker 中运行

我个人发现最简单的方式是将此类工具放在容器中运行，以避免在主机上安装不必要的全局 Node.js 包：

docker run --rm -p 3000:3000 wettyoss/wetty --ssh-host=192.168.1.50

将 192.168.1.50 替换为你要通过 SSH 连接的主机 IP 地址。

有用的启动参数

该工具通过命令行标志提供灵活的配置：

• --ssh-host 和 --ssh-port 将连接重定向到单独的远程服务器。
• --ssh-user 设置默认用户，这样就不必每次都输入登录名。
• --ssl-key 和 --ssl-cert 启用直接流量加密。
• --allow-iframe 允许将终端嵌入其他网站的 iframe 中（例如，在仪表板或监控面板中）。

如果你不想每次启动时都指定标志，可以将参数打包到配置文件中，然后通过 --conf 传递。

安全性和生产环境使用

绝对不建议将未受保护的 WeTTY HTTP 端口暴露到互联网。任何攻击者都可能尝试暴力破解密码或拦截未加密的流量。

在实践中，通常会在 WeTTY 前放置一个反向代理（NGINX、Traefik 或 Caddy）来处理多个职责：

1. 颁发和续期来自 Let's Encrypt 的免费 SSL 证书。
2. 代理 WebSocket 连接。
3. 通过 Basic Auth 或 Authelia 提供额外的授权层。
4. 基于 IP 地址白名单限制访问。

以下是典型的 NGINX 配置示例：

location /wetty/ {
    proxy_pass http://127.0.0.1:3000/wetty/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 43200000;

    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $http_host;
    proxy_set_header X-NginX-Proxy true;
}

不要忘记使用 --base /wetty/ 标志运行 WeTTY 本身，以使路由路径正确对齐。

这个项目适合谁

WeTTY 解决特定的实际需求：

• 直接从手机或 iPad 快速管理家庭服务器（Home Lab）和路由器。
• 设置演示环境和培训沙箱，学生需要 shell 访问但无需配置 SSH 客户端。
• 将终端窗口嵌入内部基于 Web 的基础设施管理面板。
• 从只有端口 80 和 443 开放的隔离企业网络访问服务器。

如果你需要一种轻量级方式在浏览器中启动终端，而不需要 Cockpit 或 Proxmox 等重型 Web 界面，WeTTY 可以在几分钟内完成。只需在反向代理后启动容器并添加身份验证即可。