WeTTY 3.0.0 常用操作与排障详解

WeTTY v3.0.0 日常运维与真实排障实录：8 条实测故障（强制 CORS 崩溃循环、Origin 拒绝、PASSWORD_ACCESS 语义、路径变更等）根因与修复。

WeTTYSSH终端工具2026/10/30

WeTTY 3.0.0 常用操作与排障详解

目标：沉淀 WeTTY v3.0.0 的日常运维操作与真实排障实录——本文全部 8 条故障均为 2026-10-30 在真实服务器上部署 WeTTY v3.0.0 + linuxserver/openssh-server 时实际触发并解决的问题，每条含原始报错、根因与修复动作。基础部署见 《WeTTY 3.0.0 Docker Compose 部署实战》，参数语义见 《WeTTY 3.0.0 配置参数详解》，选型背景见 《WeTTY 3.0.0 介绍与选型指南》。

一、日常运维操作

1.1 状态与日志

# 容器状态
docker compose ps
NAME         STATUS          PORTS
wetty-sshd   Up 2 minutes    0.0.0.0:2223->2222/tcp
wetty-web    Up 2 minutes    0.0.0.0:8152->3000/tcp

# 服务日志（JSON 行格式，一行一个事件）
docker logs -f wetty-web

日志关键行示例（实测）：

{"base":"/","label":"Wetty","level":"info","message":"Starting server","port":3000,"timestamp":"2026-10-30T00:35:12.069Z","title":"WeTTY Lab"}
{"connection":"http","label":"Wetty","level":"info","message":"Server started","port":3000,"timestamp":"2026-10-30T00:35:12.077Z"}
{"label":"Wetty","level":"info","message":"Connection accepted.","timestamp":"2026-10-30T00:38:49.150Z"}

解读：Starting server + Server started 成对出现才是健康启动；Connection accepted. 每次浏览器终端接入都会产生一条，可据此数活跃会话（docker logs wetty-web 2>&1 | grep -c "Connection accepted"）。日志里还回显了 base/port/title，是核对配置是否生效的第一现场。

1.2 资源与生命周期

# 资源占用（实测：wetty-web 32.59MiB / sshd 3.758MiB，CPU 常年近零）
docker stats --no-stream wetty-web wetty-sshd

# 修改配置后重建（WeTTY 无状态，重建零成本）
docker compose up -d --force-recreate wetty

# 升级镜像
docker compose pull wetty && docker compose up -d wetty

# 停止并清理整栈
docker compose down

1.3 终端使用操作（浏览器侧）

  • 访问入口：v3 直接打开 http://<host>:8152/（根路径）。带预设用户名用 http://<host>:8152/ssh/<user>；
  • 登录交互：未配 SSHUSER 时终端先提示 Enter your username:，再提示 xxx@host's password:；输入的密码不回显，属正常安全行为；
  • 会话关闭：浏览器关标签页或在终端里 exit，服务端会回收 PTY 与 ssh 子进程；
  • 复制粘贴：与本地终端一致（xterm.js 支持 Ctrl+Insert/V 及右键菜单，浏览器弹剪贴板授权）；
  • 首次连接主机指纹：出现 Warning: Permanently added '[sshd]:2222' (ED25519) to the list of known hosts. 属正常首连记录，不是告警。

二、排障实录（8 条真实案例）

以下每条都来自本次部署实操，按「现象 → 原始报错 → 根因 → 修复」组织。

2.1 容器无限重启循环：ALLOWEDORIGINS 缺失

  • 现象：docker compose ps 里 wetty 状态反复出现 Restarting (1)，页面无法访问；
  • 原始报错（docker logs 循环刷屏）：
{"base":"/","label":"Wetty","level":"info","message":"Starting server","port":3000,...}
{"err":"Configure at least one allowed origin with --allowed-origin, ALLOWEDORIGINS, or server.allowedOrigins","label":"Wetty","level":"error","message":"error in server"}
  • 根因：v3.0.0 把 Socket.IO 的 Origin 白名单设为强制配置，缺失即退出。这是 v2 升 v3 的头号破坏性变化；
  • 修复：environment 加 ALLOWEDORIGINS: "http://192.168.1.200:8152,http://localhost:8152"（与用户实际访问地址一致），docker compose up -d 后 Server started 正常。

2.2 握手被拒：Origin not allowed

  • 现象：页面能打开，但终端区一直转圈/显示连接断开；或用脚本测试 Socket.IO 握手失败；
  • 原始报错（curl 握手响应）：
$ curl -s "http://localhost:8152/socket.io/?EIO=4&transport=polling"
{"code":4,"message":"Origin not allowed"}
  • 根因：请求的 Origin 头不在 ALLOWEDORIGINS 列表（或不带 Origin——curl 默认不发，浏览器一定会发）；
  • 修复：浏览器场景核对地址栏与 ALLOWEDORIGINS 是否逐字符一致（协议/域名/端口）；程序化客户端（无 Origin）则显式开启 ALLOWMISSINGORIGIN=true。带上允许 Origin 复测，握手返回 0{"sid":...} 即通过。

2.3 SSH 密码认证全失败：PASSWORD_ACCESS 不是密码

  • 现象：WeTTY 终端里输入正确密码仍报 Permission denied；宿主机直连 sshd 亦失败；
  • 原始报错（paramiko 直连 2222→2223）：
BadAuthenticationType: Bad authentication type; allowed types: ['publickey', 'keyboard-interactive']

sshd 容器日志同时打印：

User/password ssh access is disabled.
PasswordAuthentication no
  • 根因（linuxserver/openssh-server 三连坑，全部实测验证）：
    1. PASSWORD_ACCESS 是布尔开关（取值 true），不是密码本身——真正的密码走 USER_PASSWORD；初版实验把 q1w2e3r4 填给 PASSWORD_ACCESS，开关从未打开；
    2. 该镜像初始 PasswordAuthentication no，只有 PASSWORD_ACCESS: "true" 才会被改成 yes；
    3. 日志行 User/password ssh access is disabled. 与 PUBLIC_KEY 相关：未提供任何公钥时打印此行，提供后打印 Public key from env variable added。密码开关仍由 PASSWORD_ACCESS 独立控制；
  • 修复：environment 三行齐配——USER_NAME: admin、USER_PASSWORD: q1w2e3r4、PASSWORD_ACCESS: "true"。修复后 paramiko 以 password 方式认证成功，WeTTY 终端登录成功。另注意：该镜像每次启动都会执行 chpasswd 重设密码，改 USER_PASSWORD 后 docker compose up -d 即生效。

2.4 访问 /wetty 返回 404：v3 路径变更

  • 现象：按 v2 习惯打开 http://host:8152/wetty，返回 404（HTML 标题为 Error）；
  • 原始报错：
$ curl -si http://localhost:8152/wetty | head -1
HTTP/1.1 404 Not Found
  • 根因：v3 默认 BASE=/，Web 界面挂在根路径；v2 的 /wetty 默认路径已不存在；
  • 修复：直接访问 http://host:8152/；需要子路径时显式配 BASE 环境变量（如 BASE: /wetty），并在反代侧同步 location。

2.5 连接目标 Connection refused：SSHPORT 惯性写错

  • 现象：终端输入用户名后提示输密码，随后连接失败/断开；
  • 根因：linuxserver/openssh-server 容器内监听 2222（非 22），编排里 SSHPORT 按惯性写 22 导致 ssh 子进程连不上；
  • 修复：SSHPORT: "2222"。定位技巧：进入 wetty 容器手动执行 ssh -p <port> <user>@<host> 复现报错，可区分「WeTTY 问题」与「网络/目标机问题」。密码错误场景的终端回显（实测）与网络不可达明显不同：admin@sshd's password: → Permission denied, please try again. 是凭据问题；瞬间断开无密码提示多是端口/网络问题。

2.6 反代之后终端连不上：缺 WebSocket 升级头

  • 现象：Nginx 反代后页面能打开，终端区始终断线；
  • 根因：Socket.IO 走 WebSocket 长连接，反代未转发 Upgrade/Connection 头；
  • 修复：location 段补齐：
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 21600;

同时把 ALLOWEDORIGINS 改为反代对外域名（如 https://terminal.example.com），两个配置必须同改，只改一边就会出现「页面开了终端 403」。

2.7 拉取镜像报 not found：镜像名已迁移

  • 现象：按旧教程拉取镜像失败；
  • 原始报错：
$ docker pull buttermilk/wetty:latest
Error response from daemon: ... not found
  • 根因：项目迁移后官方镜像名为 wettyoss/wetty（Docker Hub wettyoss 组织，1.8M+ 拉取），旧名 buttermilk/wetty 已从 Docker Hub 注销（API 返回 object not found，实测确认）；
  • 修复：改用 wettyoss/wetty:latest。锁定版本用 digest（如 @sha256:17a07724...，官方无语义化版本 tag）。

2.8 弱网频繁断线：心跳参数默认值偏激进

  • 现象：跨广域网访问时终端随机断开，日志/页面提示 transport close；
  • 根因：Socket.IO 默认 pingInterval=3000 / pingTimeout=7000（毫秒，实测握手响应可核对），高延迟抖动链路下易误判掉线；
  • 修复：PINGINTERVAL: "10000"、PINGTIMEOUT: "20000"，重建容器。

三、安全运维清单

  1. HTTPS 必开（反代终结或 SSLKEY/SSLCERT 内建），终端流过的是密码与完整 Shell；
  2. ALLOWEDORIGINS 精确到站点，不图省事写 *；ALLOWMISSINGORIGIN/ALLOWREMOTEHOSTS/ALLOWREMOTECOMMAND 三个放宽开关默认全关，非必要不开；
  3. 不用 SSHPASS 自动免密共享账号——密码进编排文件且出现在进程列表；多用户场景走各自的 SSH 账号认证；
  4. 目标侧权限收敛：WeTTY 复用 sshd 认证，给浏览器的账号在服务器侧配最小权限（禁 root、限目录、fail2ban 照常生效）；
  5. 日志治理：默认 info 级即可观测连接；公网入口建议 LOGLEVEL=warn 降噪，但仍保留审计所需的反向代理访问日志。

四、故障定位决策树

页面打不开 ──→ 容器状态？Restarting → 排障 2.1（ALLOWEDORIGINS）
   │              │Up → 端口/防火墙
   └ 页面开终端连不上 ──→ curl 握手测 Origin → code 4 → 排障 2.2
                              │ sid 正常 → 反代升级头 → 排障 2.6
   └ 提示输密码后失败 ──→ 回显 Permission denied → 凭据/目标机 → 排障 2.3
                              │ 无密码提示直接断 → SSHPORT/网络 → 排障 2.5

按树走一遍仍无解时，docker logs wetty-web --tail 50 的 JSON 日志 + 目标机 /var/log/auth.log（或容器 docker logs wetty-sshd）两处现场对照，基本能覆盖全部认证类问题。参数语义回查 《WeTTY 3.0.0 配置参数详解》，部署与验证全流程回查 《WeTTY 3.0.0 Docker Compose 部署实战》。