Sshwifty 配置参数详解：sshwifty.conf 全项精讲

Sshwifty 0.4.12 配置详解：文件与环境变量双体系加载顺序、SharedKey 实测回显、Servers 超时全表、Presets 预设锁定实测、OnlyAllowPresetRemotes 行为实录与 SS...环境变量对照表。

SshwiftySSH远程控制终端工具网络工具自托管Golang2026/10/30

Sshwifty 配置参数详解：sshwifty.conf 全项精讲

本文是 Sshwifty 专栏第三篇。所有参数行为均基于 0.4.12-beta-release 的官方配置样例与源码，并经本地真实服务实测交叉验证（实测回显在文中以"实测"标注）。两套配置体系（配置文件与环境变量）的全部可调项一次讲清。

一、两套配置体系与加载顺序

Sshwifty 支持两种配置方式，加载优先级为：默认路径配置文件 → 环境变量兜底（来源：官方 README "Configuration" 节，2026-10-30 查询）。

配置文件按以下默认路径顺序查找，命中即停：

  1. 工作目录 sshwifty.conf.json
  2. /etc/sshwifty.conf.json
  3. ~/.sshwifty.conf.json

实测：将自定义配置文件放置于 /etc/sshwifty.conf.json 后重启服务，启动日志逐行回显：

[INF] Sshwifty: Initializing
[INF] Sshwifty > Configuration > Redundant: Loading configuration from one of the default configuration files ...
[INF] Sshwifty > Configuration > Redundant: Configuration file "/etc/sshwifty.conf.json" has been selected
[INF] Sshwifty > Server (0.0.0.0:8182): Serving

若三个默认路径均未命中，则回退读环境变量；若指定了 SSHWIFTY_CONFIG 环境变量，则只从该文件加载（跳过默认路径）。若日志只出现 "Loading configuration from one of the default configuration files ..." 而 has been selected 指向了别的文件或没有出现，说明你的文件路径或 JSON 语法有问题——这是配置不生效时的第一排查点。

二、全局配置项

HostName

  • 类型：字符串，默认 ""
  • HTTP Host 校验。留空接受任意 Host 头访问；设置后仅允许指定域名访问（可挡住按 IP 直扫）。若前面有反向代理，此值应与对外的 Host 一致。

SharedKey

  • 类型：字符串，默认 ""
  • Web 界面预共享口令。留空表示公网免认证直进（跳过认证页），生产环境必须设置。
  • 实测：口令错误时认证页回显：
AUTHENTICATION REQUIRED
Passphrase
Authentication has failed. Wrong passphrase?
Authenticate
  • 该口令同时是 WebSocket 通道的准入票据：实测在未认证状态下发起 WebSocket，服务端日志回显：
Request ended with error: "/sshwifty/socket/verify": HTTP Error (403): To use Websocket interface, a valid Auth Key must be provided

DialTimeout

  • 类型：整数（秒），默认 5
  • 服务端向远程主机发起连接（拨号）的超时。实测样例中设为 10。上限受 Servers[].ReadTimeout 约束。
  • 实测：目标主机关闭时连接向导报错回显（DialTimeout 内未建立连接即失败）：
Connection failed
dial tcp 10.89.60.3:2222: connect: connection refused

Socks5 / Socks5User / Socks5Password

  • 类型：字符串
  • 出站代理三件套。设置 Socks5 后，所有到远程主机的连接改经该代理（如 localhost:1080），另两项为代理认证凭据。适用于服务端与目标机之间有网络隔离、需经跳板出网的架构。

Hooks.before_connecting / HookTimeout

  • 类型：数组 / 整数（秒），默认 30
  • 连接前钩子：每项是一个 JSON 数组形式的命令（元素间映射为空格分隔的命令片段），在服务端按顺序执行；任一钩子非零退出即中止本次连接。钩子进程可读取注入的 SSHWIFTY_HOOK_REMOTE_TYPE（SSH/Telnet）与 SSHWIFTY_HOOK_REMOTE_ADDRESS（目标地址）环境变量，并可通过 SSHWIFTY_HOOK_DEADLINE（RFC3339 时间串）获知剩余执行时限。
  • 钩子的标准输出对用户可见，标准错误进服务端日志。
  • 官方两处安全警告（来源：官方配置样例注释，2026-10-30 查询）：钩子与服务进程同权限运行，务必防范命令注入；所有传入钩子的输入都应视为未净化的。
  • HookTimeout 是单个钩子的最长执行时间，超时即终止并视为失败。

三、Servers[] 监听实例配置

Servers 是数组，同一进程可并行开多个监听。各字段：

字段类型/默认说明
ListenInterface字符串，样例 0.0.0.0监听网卡。0.0.0.0 全部网卡；127.0.0.1 仅本机（配合反向代理）
ListenPort整数，样例 8182监听端口
InitialTimeout整数（秒），默认 10HTTP 初始握手必须在此时限内完成
ReadTimeout整数（秒），默认 120连接空闲多久后被服务端断开（心跳兜底之外的无活动上限）
WriteTimeout整数（秒），默认 120服务端等待客户端可接收数据的最长时间，超时断开
HeartbeatTimeout整数（秒），默认 15心跳间隔时限，维持长连接活性
ReadDelay整数，默认 10读缓冲延迟（毫秒级微调，默认即可）
WriteDelay整数，默认 10写缓冲延迟
TLSCertificateFile字符串X.509 证书路径；与下一项同时配置后该监听直接以 HTTPS 服务
TLSCertificateKeyFile字符串证书私钥路径
ServerMessage字符串页脚公告，展示在 Web 界面底部

实测：ServerMessage 设为 "Lab environment. Unauthorized access is prohibited." 后，首页底部原样回显：

Lab environment. Unauthorized access is prohibited.

实测：环境变量方式下 SSHWIFTY_READTIMEOUT=0 等归零值生效时服务正常启动——0 表示使用内部默认值，而不是"无超时"。超时参数建议保持官方默认，仅在长连接被中间设备（代理/防火墙）误切时调大。

四、Presets[] 连接预设

预设是管理员下发给用户的一键连接清单，用户在 "Known remotes" 页签中选择。完整字段：

字段说明
Title预设显示名（实测回显 "Lab SSH Target"）
TypeSSH 或 Telnet
Host目标地址，host:port 格式（如 10.20.30.40:2222）
TabColor标签页颜色，6 位十六进制（如 001100）
Meta.User预填登录用户名
Meta.Encoding预填字符编码（utf-8、ibm866 等）
Meta.Authentication预设认证方式：Password、Private Key、或逗号组合 "Private Key,Password,Keyboard Interactive"
Meta.Private Key预置私钥。官方样例明确警告会以明文下发客户端，禁止在预设存放私钥
Meta.Fingerprint预置主机指纹，命中后可跳过人工指纹确认

实测一：预设 Meta 中 "Authentication": "Password" 生效后，连接向导的认证复选框呈预设禁用态（用户不可改）：

box 0 ["[]Authentication",false,true]
box 1 ["[]Authentication",true,true]
box 2 ["[]Authentication",false,true]

第三个布尔值即 disabled=true——预设锁定了认证方式，用户无需（也不能）再选。

实测二：预设中的 User/Encoding 会直接预填进连接向导对应字段，TabColor 渲染为 "Known remotes" 条目左侧色标。

安全提醒：预设中不要写 Meta."Private Key"；Meta.Fingerprint 建议填写，可把"人工核对指纹"升级为"自动校验指纹"。

五、OnlyAllowPresetRemotes

  • 类型：布尔，默认 false
  • 最硬的访问收敛开关。设为 true 后，用户只能连接预设清单内的主机。
  • 实测：置 true 并重启服务后，点击加号的连接器菜单发生质变——New remote、Telnet、SSH 手动入口全部消失，仅剩预设清单，并回显提示：
ESTABLISH CONNECTION WITH
New remote
Known remotes 0
PRESETS
SSH
Lab SSH Target
The operator has restricted the outgoing connections. You can only connect to remotes from the pre-defined presets.

一行提示语精确表达了策略："操作者已限制出站连接，只能连接预定义预设中的远程主机"。做跳板入口、面向多人开放时建议开启，配合反向代理与 SharedKey 构成三层收敛（入口口令 → 出站白名单 → SSH 自身认证）。

六、环境变量对照表

以打包形态运行时，全部配置项均有对应环境变量（来源：官方交付物内置环境变量清单，2026-10-30 实测盘点）。配置文件命中时环境变量不生效；环境变量仅在文件缺失时兜底。

环境变量对应配置项实测盘点值
SSHWIFTY_CONFIG强制指定配置文件路径（可选）
SSHWIFTY_HOSTNAMEHostName空
SSHWIFTY_SHAREDKEYSharedKeyq1w2e3r4
SSHWIFTY_DIALTIMEOUTDialTimeout10
SSHWIFTY_SOCKS5 / _USER / _PASSWORDSocks5 三件套空
SSHWIFTY_HOOK_BEFORE_CONNECTINGHooks.before_connecting空
SSHWIFTY_HOOKTIMEOUTHookTimeout30
SSHWIFTY_LISTENINTERFACEServers[].ListenInterface0.0.0.0
SSHWIFTY_LISTENPORTServers[].ListenPort8182
SSHWIFTY_INITIALTIMEOUTServers[].InitialTimeout0（用内部默认）
SSHWIFTY_READTIMEOUTServers[].ReadTimeout0
SSHWIFTY_WRITETIMEOUTServers[].WriteTimeout0
SSHWIFTY_HEARTBEATTIMEOUTServers[].HeartbeatTimeout0
SSHWIFTY_READDELAYServers[].ReadDelay0
SSHWIFTY_WRITEELAYServers[].WriteDelay0（官方拼写即少一个 R，照用即可）
SSHWIFTY_TLSCERTIFICATEFILE / _KEYFILETLS 证书与私钥空
SSHWIFTY_DOCKER_TLSCERT / _TLSCERTKEY打包形态专用：直接注入证书/私钥 PEM 内容空
SSHWIFTY_PRESETSPresets（JSON 数组字符串）空
SSHWIFTY_SERVERMESSAGEServers[].ServerMessage空
SSHWIFTY_ONLYALLOWPRESETREMOTESOnlyAllowPresetRemotes空

三个实测结论值得单独强调：

  1. 环境变量是"全有或全无"的兜底：实测一份完整走环境变量的实例，SSHWIFTY_PRESETS 留空时界面 "Known remotes" 显示 0，与走文件配置且含预设的实例形成鲜明对比；
  2. SSHWIFTY_WRITEELAY 官方拼写即缺少字母 R（对照配置文件字段 WriteDelay），照官方拼写书写才能生效；
  3. SSHWIFTY_DOCKER_TLSCERT/SSHWIFTY_DOCKER_TLSCERTKEY 直接接收 PEM 全文，免去挂载证书文件，适合临时证书场景。

七、文件配置与环境变量配置怎么选

维度文件配置环境变量配置
表达能力完整（Presets、Hooks 嵌套结构自然表达）Presets 需压缩为 JSON 字符串，易错
变更方式改文件后重启服务改环境后重建服务
可审计性配置文件可入版本库，diff 清晰分散在启动环境中
推荐度生产首选最小部署/临时验证

两套体系不要混用：文件一旦命中，环境变量全部失效（SSHWIFTY_CONFIG 指定的文件同理），混用只会增加排障成本。

八、本篇小结

配置体系的记忆锚点：全局项管"谁能进来"（SharedKey/HostName/Hooks），Servers 管"从哪儿服务"（监听/超时/TLS/公告），Presets 管"能去哪儿"（目标清单与认证预填），OnlyAllowPresetRemotes 管"是不是只能去那儿"。部署动作见 《Sshwifty Docker Compose 部署指南：从零搭建 Web 终端网关》，产品定位见 《Sshwifty 介绍与选型指南：浏览器里的 SSH/Telnet 终端》；日常操作与排障实录见《Sshwifty 使用与运维详解：连接管理、安全加固与排障实录》。

专栏导航：

  1. 《Sshwifty 介绍与选型指南：浏览器里的 SSH/Telnet 终端》
  2. 《Sshwifty Docker Compose 部署指南：从零搭建 Web 终端网关》
  3. 《Sshwifty 配置参数详解：sshwifty.conf 全项精讲》（本篇）
  4. 《Sshwifty 使用与运维详解：连接管理、安全加固与排障实录》