WeTTY 3.0.0 配置参数详解

WeTTY v3.0.0 全量 24 个配置参数实测详解：环境变量与 CLI 对照、SSH 连接五件套、v3 强制 CORS 与安全开关、按场景推荐配置组合与验证方法。

WeTTYSSH终端工具2026/10/30

WeTTY 3.0.0 配置参数详解

目标：把 WeTTY v3.0.0 的全部配置项讲透——环境变量、命令行参数两条配置途径的对应关系、每个参数的默认值与实测行为、以及按场景组合的推荐配置。本文全部参数均在 wettyoss/wetty v3.0.0 容器内以 wetty --help 与实际部署逐项核对，部署过程见 《WeTTY 3.0.0 Docker Compose 部署实战》，组件定位见 《WeTTY 3.0.0 介绍与选型指南》，排障应用见 《WeTTY 3.0.0 常用操作与排障详解》。

一、配置体系总览

WeTTY v3 有两条配置途径，语义一一对应：

  1. 环境变量（容器部署首选）：把命令行参数的 camelCase 形式去掉连字符转全大写，如 --ssh-host → SSHHOST、--allowed-origin → ALLOWEDORIGIN（多值复数形式为 ALLOWEDORIGINS）、--allow-missing-origin → ALLOWMISSINGORIGIN。官方 Compose 示例即用这种形式（SSHHOST/SSHPORT/ALLOWEDORIGINS）；
  2. 命令行参数（裸机/npm 部署或临时覆盖）：完整清单见下表，wetty --help 可随时查看。

v3 还保留了一个可选的 --conf <文件> 加载 JSON5 配置文件的方式，但官方镜像与文档的主推路径都是环境变量，本文以环境变量为主线。

实测核对的全量参数对照表（v3.0.0 共 24 个业务参数）：

环境变量命令行参数类型默认值作用
SSHHOST--ssh-hoststringlocalhostSSH 目标主机
SSHPORT--ssh-portnumber22SSH 目标端口
SSHUSER--ssh-userstring空预置登录用户名
SSHAUTH--ssh-authstringpassword认证方式：password/publickey/none
SSHPASS--ssh-passstring空预置 SSH 密码（配合 sshpass 自动认证）
SSHKEY--ssh-keystring空客户端私钥路径（密钥认证）
SSHCONFIG--ssh-configstring空ssh 客户端配置文件（ssh -F）
FORCESSH--force-sshbooleanfalseroot 运行时也强制走 ssh 而非本机 login
KNOWNHOSTS--known-hostsstring系统默认known_hosts 路径（设 /dev/null 跳过主机校验）
PORT--port, -pnumber3000WeTTY 监听端口
HOST--hoststring全部网卡WeTTY 监听地址
SOCKET--socketstring空改用 Unix socket 监听
BASE--base, -bstring/Web 界面挂载的子路径
TITLE--titlestringWeTTY - The Web Terminal Emulator页面标题
COMMAND--command, -cstringloginSSH 登录后在远端执行的命令
SSLKEY--ssl-keystring空TLS 私钥路径（内建 HTTPS）
SSLCERT--ssl-certstring空TLS 证书路径（内建 HTTPS）
ALLOWEDORIGINS--allowed-originstring[]无（必配）允许连接 Socket.IO 的浏览器来源
ALLOWMISSINGORIGIN--allow-missing-originbooleanfalse放行无 Origin 头的客户端
ALLOWIFRAME--allow-iframebooleanfalse允许被第三方页面 iframe 内嵌
PINGINTERVAL--ping-intervalnumber3000Socket.IO 心跳间隔（毫秒）
PINGTIMEOUT--ping-timeoutnumber7000心跳超时（毫秒）
ALLOWREMOTEHOSTS--allow-remote-hostsbooleanfalse允许 URL 参数指定 SSH 目标
ALLOWREMOTECOMMAND--allow-remote-commandbooleanfalse允许 URL 参数指定远端命令
LOGLEVEL--log-levelstringinfo服务日志级别

两组实测数据佐证默认值：Socket.IO 握手响应里 pingInterval:3000, pingTimeout:7000 与表中一致；启动日志 {"base":"/","label":"Wetty","level":"info","message":"Starting server","port":3000,"title":"WeTTY Lab"} 回显的 base/port/title 与配置一致（TITLE 改成 WeTTY Lab 后生效）。

💡 技术拓展：环境变量 vs 配置文件是容器化组件的两种主流配置形态。环境变量的优势是「改值即重建」，配合 Compose 的 environment 段直观且无挂载成本，十二因子应用（12-Factor App）方法论明确推荐；配置文件的优势是可注释、可结构化嵌套。WeTTY 的参数全是扁平的标量，没有嵌套结构，环境变量是更贴合的形态；v3 保留 --conf 主要服务于复杂部署（同一个镜像按不同 conf 启多实例）的场景。

二、SSH 连接参数组（核心五件套）

这组参数决定「浏览器连到哪、以什么身份认证」，是 WeTTY 的灵魂配置：

2.1 SSHHOST / SSHPORT / SSHUSER（目标三元组）

  • SSHHOST：目标主机。容器部署时最常见的是 Compose 服务名（如 sshd，走内网 DNS 解析）、内网 IP 或域名。不要配 localhost——那是 WeTTY 容器自己；如果真想连宿主机，用宿主内网 IP 或 host.docker.internal（需额外配置）。root 身份运行且目标为 localhost 时 WeTTY 会改走本机 /bin/login，容器场景下这个分支通常不是你想要的，必要时用 FORCESSH=true 强制走 ssh；
  • SSHPORT：目标 sshd 端口。linuxserver/openssh-server 镜像默认 2222（实测如此），原生 Linux 服务器一般是 22。这里曾实测踩坑：按习惯写 22 连 2222 的目标机，报 Connection refused；
  • SSHUSER：预置用户名。不配时浏览器终端会交互式提示 Enter your username:（实测回显），每个用户各自输入；配上则所有人默认连同一账号，并跳过用户名交互。多用户场景建议不配，配合 URL 路径 /ssh/<user> 使用。

2.2 SSHAUTH（认证方式，三种取值）

取值行为依赖适用场景
password（默认）终端里出现 xxx@host's password: 提示，人工输密目标 sshd 允许密码认证默认通用
publickey用 SSHKEY 指定的私钥认证，免密直达私钥挂进 WeTTY 容器自动化/共享账号
none不做客户端认证，完全依赖目标 sshd 侧策略服务器侧免密配置已有统一免密体系

v3 的一个实用增强：配置了 SSHPASS 时，WeTTY 会自动用 sshpass -p <pass> ssh ... 完成认证（实测源码核对），实现「打开页面即进 Shell」的免输密体验。但密码会出现在进程列表里（sshpass 的已知问题），且 SSHPASS 落在编排文件中，生产环境建议用 Docker secrets 或干脆不配、维持人工输密。

2.3 KNOWNHOSTS（主机指纹校验）

默认走 OpenSSH 标准流程，首次连接会在终端里出现 Warning: Permanently added '[sshd]:2222' (ED25519) to the list of known hosts.（本次实测原文）。企业内网固定目标可提前把目标机指纹放进 known_hosts 文件挂载进容器，并将 KNOWNHOSTS 指向该文件；实验环境可设 /dev/null 关闭校验（WeTTY 会同时把 StrictHostKeyChecking 切到 no）。

三、服务监听参数组

  • PORT（3000）/ HOST：容器内监听端口与地址。容器场景 PORT 不建议改（Compose 映射对准 3000），改对外端口用 ports 映射即可；
  • SOCKET：改用 Unix socket 监听，用于「WeTTY 与 Nginx 同机」时省掉 TCP 端口暴露，属进阶用法；
  • BASE：子路径部署。默认 /（v3 重大变化，v2 默认 /wetty，实测 v2 路径访问直接 404）。反代子路径场景配 BASE: /wetty 后，访问地址变为 https://host/wetty/；
  • TITLE：页面标题，实测配 WeTTY Lab 后页面 <title>WeTTY Lab</title>。多实例部署时用它区分环境（如「WeTTY-生产跳板」「WeTTY-实验区」）；
  • SSLKEY / SSLCERT：内建 HTTPS。两个都配才生效，WeTTY 直接对外提供 TLS，小规模无反代场景够用；有反代时不必配（TLS 由 Nginx 终结）。

四、v3 安全与传输参数组（重点，v2 没有的新闸门）

4.1 ALLOWEDORIGINS（必配）

允许建立 Socket.IO 连接的浏览器来源，v3 不配直接拒绝启动。实测错误日志：

{"err":"Configure at least one allowed origin with --allowed-origin, ALLOWEDORIGINS, or server.allowedOrigins","label":"Wetty","level":"error","message":"error in server"}

配好后，浏览器带允许 Origin 的握手返回 sid 正常建连；不带 Origin 的工具（curl 等）握手被拒：{"code":4,"message":"Origin not allowed"}（实测）。书写要点：

  • 值是完整的 协议://主机:端口，逗号分隔多值，如 "http://192.168.1.200:8152,http://localhost:8152"（实测值）；
  • 必须与用户浏览器地址栏所见完全一致——HTTPS 站点写 https，非标端口带上端口；
  • 反代改造后改成对外域名（如 https://terminal.example.com），与 BASE 联动时注意子路径不影响 Origin 判定（Origin 只到端口为止）。

4.2 ALLOWMISSINGORIGIN

放行没有 Origin 头的客户端（CLI 脚本、自研终端工具）。默认 false，即本次实测中 curl 握手被拒的原因。只在你确有程序化客户端需求时开启，且开启后等于放弃了 Origin 这一层「必须是浏览器」的约束。

4.3 ALLOWIFRAME

是否允许页面被 iframe 嵌入。默认 false（仅同源可嵌），防止点击劫持。确需嵌入到运维门户时再开。

4.4 PINGINTERVAL / PINGTIMEOUT

Socket.IO 心跳节奏，实测默认 3000/7000 毫秒（握手响应可核对）。跨广域网、移动网络接入时适当调大（如 10000/20000），避免弱网下被误判掉线触发 transport close 断连。

4.5 ALLOWREMOTEHOSTS / ALLOWREMOTECOMMAND

v3 新增的 URL 传参开关：开启后允许通过 ?host=xxx&port=22 甚至 ?command=xxx 在 URL 里指定连接目标与远端命令。灵活性极强也极危险（等于允许构造任意跳板），默认双 false，确有需求（如多环境跳板页）才开，且建议放在强认证的反代之后。

五、按场景的推荐配置组合

5.1 最小内网可用（本次实测基线）

environment:
  SSHHOST: sshd
  SSHPORT: "2222"
  TITLE: WeTTY Lab
  ALLOWEDORIGINS: "http://192.168.1.200:8152,http://localhost:8152"

5.2 生产域名 + HTTPS 反代

environment:
  SSHHOST: 10.0.0.31
  SSHPORT: "22"
  BASE: /wetty
  TITLE: WeTTY-生产跳板
  ALLOWEDORIGINS: "https://terminal.example.com"
  LOGLEVEL: warn

5.3 共享实验账号免输密（内网实验环境）

environment:
  SSHHOST: sshd
  SSHPORT: "2222"
  SSHUSER: admin
  SSHPASS: q1w2e3r4
  SSHAUTH: password
  ALLOWEDORIGINS: "http://192.168.1.200:8152"

三组组合的共同点：ALLOWEDORIGINS 永远显式配置，这是 v3 的生存底线。

六、配置验证方法

改配置后按「日志 → 握手 → 页面」三步验证：

# 1) 启动日志回显 base/port/title，确认监听配置生效
docker logs wetty-web 2>&1 | tail -2
# {"base":"/","label":"Wetty","level":"info","message":"Server started","port":3000,...,"title":"WeTTY Lab"}

# 2) 带 Origin 握手，确认 ALLOWEDORIGINS 生效（返回 sid 即通过）
curl -s -H "Origin: http://192.168.1.200:8152" \
  "http://localhost:8152/socket.io/?EIO=4&transport=polling" | head -c 80

# 3) 页面标题确认 TITLE 生效
curl -s http://localhost:8152/ | grep -oE '<title>[^<]*</title>'

配置类问题的完整排障路径（含崩溃循环、握手 403、认证失败三类典型）见 《WeTTY 3.0.0 常用操作与排障详解》。