sish 3.0.5 配置参数详解

目标：完整梳理 sish 3.0.5 的全部配置参数——查看方式、三种配置通道、全量参数分组表、核心参数的逐项「修改 → 验证」闭环与生产配置模板。所有参数清单与默认值取自发布件二进制的 sish --help 实测输出（131 行），逐项验证均在 Ubuntu 22.04 三机环境（sish 服务端 10.89.62.2 / 客户端 10.89.62.4 / 内网应用 10.89.62.3）完成。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• sish 版本：3.0.5（sish --version 实测：Version: 3.0.5 / Commit: ba752d0f804563dd5d57154d4d44b7393137b02e / Date: 2026-10-25T15:59:10Z）
• 服务端：主机名 sish-server，10.89.62.2，二进制位于 /opt/sish/sish，工作目录 /opt/sish（deploy/keys、deploy/pubkeys、deploy/ssl 就绪）
• 客户端：主机名 client-host，10.89.62.4，openssh-client 10.3_p1
• 内网应用：主机名 intranet-web，10.89.62.3，80 端口 Web 服务（隧道转发目标）
• 验证域名：sish.local（演示用根域名，生产替换为真实泛解析域名）

二、前置条件

1. sish 3.0.5 服务端已安装并可运行（安装过程见 《Ubuntu 22.04 安装 sish 3.0.5 指南》第四章）；
2. 客户端可 ssh 到服务端（本文大量验证依赖隧道建立，客户端命令细节见 《sish 3.0.5 常用 CLI 命令详解》）；
3. 服务端 /opt/sish 目录归属运行账户、deploy/keys 可写（host key 持久化前提，见安装指南 4.3/4.5 节）；
4. 组件背景与选型认知见 《sish 3.0.5 介绍与选型指南》。

三、参数查看与修改方式

3.1 查看全部参数与默认值

/opt/sish/sish --help

实测回显（首尾节选，完整输出 131 行，每个参数的默认值以此为准）：

sish is a command line utility that implements an SSH server that can handle HTTP(S)/WS(S)/TCP multiplexing, forwarding and load balancing.
It can handle multiple vhosting and reverse tunneling endpoints for a large number of clients.

Usage:
  sish [flags]

Flags:
      --admin-console                                           Enable the admin console accessible at http(s)://domain/_sish/console?x-authorization=admin-console-token
  -j, --admin-console-token string                              The token to use for admin console access if it's enabled
      --alias-load-balancer                                     Enable the alias load balancer (multiple clients can bind the same alias)
...
      --domain string                                           The root domain for HTTP(S) multiplexing that will be appended to subdomains (default "ssi.sh")
...
  -a, --ssh-address string                                      The address to listen for SSH connections (default "localhost:2222")
  -v, --version                                                 version for sish

⚠️ 注意：v3 的默认值与网上 v2 教程差异最大的一处是 --authentication——v3 默认 true（认证开启），未配置密码/公钥时客户端一律被拒（Permission denied (password,publickey)，实测回显见 5.4 节）。

3.2 修改方式：三种等价通道与优先级

环境变量通道实测：仅用环境变量启动（命令行不传任何参数）：

SISH_SSH_ADDRESS=0.0.0.0:2222 SISH_HTTP_ADDRESS=0.0.0.0:80 \
SISH_DOMAIN=envtest.local SISH_AUTHENTICATION_PASSWORD=q1w2e3r4 \
/opt/sish/sish

实测回显（域名按环境变量生效；客户端 -R 80:intranet-web:80 建隧道后服务端日志）：

2026/10/26 - 05:43:56 | Starting SSH service on address: 0.0.0.0:2222
2026/10/26 - 05:43:56 | Loading ssh_key as ssh-ed25519 host key
2026/10/26 - 05:44:00 | HTTP forwarding started: http://dz9.envtest.local -> /tmp/10.89.62.4_33350_802015951819 for client: 10.89.62.4:33350

config.yml 通道实测：工作目录放置配置文件后直接启动：

cat > /opt/sish/config.yml <<'EOF'
domain: cfgtest.local
ssh-address: 0.0.0.0:2222
http-address: 0.0.0.0:80
authentication-password: q1w2e3r4
bind-random-subdomains: false
EOF
/opt/sish/sish

实测回显（加载提示 + 自定义子域名按配置生效，客户端 -R myweb:80:intranet-web:80）：

2026/10/26 05:44:15 Using config file: /opt/sish/config.yml
2026/10/26 - 05:44:15 | Loading ssh_key as ssh-ed25519 host key
2026/10/26 - 05:44:18 | HTTP forwarding started: http://myweb.cfgtest.local -> /tmp/10.89.62.4_56290_80430453126 for client: 10.89.62.4:56290

⚠️ 注意：默认查找路径是工作目录下的 config.yml。systemd 部署时 WorkingDirectory=/opt/sish，则 /opt/sish/config.yml 会被自动加载——实测曾出现「明明没传 -c 却输出 Using config file: config.yml」的情况，根因即此。不想使用配置文件时，移走该文件或用 -c 显式指向空文件。

优先级实测：config.yml 写 domain: cfgtest.local，同时命令行传 --domain=sish.local，客户端建隧道后服务端日志：

2026/10/26 - 05:50:39 | HTTP forwarding started: http://fvt.sish.local -> /tmp/10.89.62.4_44634_80265337374 for client: 10.89.62.4:44634

子域名后缀是 sish.local（命令行的值）而非 cfgtest.local（配置文件的值）——命令行参数覆盖 config.yml。结论：排查配置不生效问题时，先 systemctl cat sish 看 ExecStart 是否传了同名参数。

四、参数总览（全量分组表）

以下全量参数按功能分组，默认值列为 sish --help 实测原文。缩写形式（如 -a、-d）在参数名列标注。

4.1 监听地址

4.2 域名与子域名策略

4.3 端口与别名策略（TCP）

4.4 认证与访问控制

4.5 HTTPS 与 TLS

4.6 负载均衡与 SNI

4.7 HTTP 行为

4.8 连接保活与超时

4.9 控制台、日志与杂项

选型解读：参数虽多，生产主链路只有八项——--ssh-address、--http-address、--domain、--authentication-password（或公钥目录）、--port-bind-range、--bind-random-ports、--bind-random-subdomains、--admin-console(-token)；其余按需叠加。

五、核心参数逐项验证

以下每项按「修改配置 → 验证命令 → 实测回显」闭环记录。验证方法统一为：改参数重启服务端 → 客户端建隧道 → 观察服务端日志或客户端行为。

5.1 --ssh-address 与 --http-address：监听地址

修改：--ssh-address=0.0.0.0:2222 --http-address=0.0.0.0:80。

验证（服务端启动日志）：

2026/10/26 - 05:32:52 | Starting SSH service on address: 0.0.0.0:2222

要点：默认 localhost:2222 只允许本机连入（本机测试可用），生产必须 0.0.0.0；--http-address 默认 80，若宿主机 80 被 nginx 占用改为其他端口并用 --http-port-override 修正展示 URL。

5.2 --domain：根域名

修改：分别用 --domain=sish.local（命令行）、SISH_DOMAIN=envtest.local（环境变量）、config.yml domain: cfgtest.local 启动。

验证：客户端分别建隧道，服务端日志的分配结果（三次实测回显）：

2026/10/26 - 05:35:47 | HTTP forwarding started: http://lz8.sish.local -> /tmp/10.89.62.4_55326_803552062333 for client: 10.89.62.4:55326
2026/10/26 - 05:44:00 | HTTP forwarding started: http://dz9.envtest.local -> /tmp/10.89.62.4_33350_802015951819 for client: 10.89.62.4:33350
2026/10/26 - 05:44:18 | HTTP forwarding started: http://myweb.cfgtest.local -> /tmp/10.89.62.4_56290_80430453126 for client: 10.89.62.4:56290

要点：三条通道都生效；子域名 = 请求别名（或随机值）+ . + domain。domain 必须与泛解析一致，否则 HTTP 路由的 Host 无法命中。

5.3 --bind-random-subdomains / --force-requested-subdomains：子域名分配策略

默认态（随机）：客户端请求 myweb，服务端忽略请求值（实测回显）：

2026/10/26 - 05:48:43 | HTTP forwarding started: http://omk.sish.local -> /tmp/10.89.62.4_45332_801374985359 for client: 10.89.62.4:45332

修改：--bind-random-subdomains=false 后同样请求 myapp：

2026/10/26 - 05:40:27 | HTTP forwarding started: http://myapp.sish.local -> /tmp/10.89.62.4_35784_801273864906 for client: 10.89.62.4:35784
2026/10/26 - 05:40:29 | myapp.sish.local | 200 |    1.016673ms |      10.89.62.4 | GET     /

（curl 访问 Host: myapp.sish.local 返回内网 Web 200，自定义子域名闭环成立。）

非强制模式下的静默回退：myapp 已被占用时再次绑定、以及请求保留字 localhost，都被静默换成随机子域名（实测两次回显）：

2026/10/26 - 05:40:36 | HTTP forwarding started: http://vxh.sish.local -> /tmp/10.89.62.4_33042_802884938422 for client: 10.89.62.4:33042
2026/10/26 - 05:40:39 | HTTP forwarding started: http://zol.sish.local -> /tmp/10.89.62.4_33058_802906890532 for client: 10.89.62.4:33058

强制模式（--force-requested-subdomains）：重启后重复绑定 myapp，客户端与服务端双双明确报错：

Warning: remote port forwarding failed for listen port 80        # 客户端
2026/10/26 - 05:42:28 | Error setting up HTTPListener: error assigning requested subdomain to tunnel   # 服务端

要点：生产给固定子域名（如 grafana.sish.example.com）必须 --bind-random-subdomains=false；要「占用即报错」的确定性语义再加 --force-requested-subdomains；保留字黑名单默认封 localhost。

5.4 --authentication 与 --authentication-password：认证

默认态（未配置任何凭据）：客户端被拒（实测回显）：

root@10.89.62.2: Permission denied (password,publickey).

修改：--authentication=true --authentication-password=q1w2e3r4。验证错误口令与正确口令（实测回显）：

root@10.89.62.2: Permission denied (password,publickey).    # sshpass -p wrongpass
Press Ctrl-C to close the session.                           # sshpass -p q1w2e3r4，进入隧道挂起态

要点：v3 认证默认开启；完全匿名须显式 --authentication=false（仅限内网试验）。密码外强烈建议公钥认证（见 5.5）。

5.5 --authentication-keys-directory：公钥目录动态加载

修改：客户端生成密钥对并把公钥文件放入服务端 deploy/pubkeys/（无需重启）：

scp /root/.ssh/id_ed25519.pub root@10.89.62.2:/opt/sish/deploy/pubkeys/tunneluser.pub

验证：客户端仅用公钥认证连入（-o PreferredAuthentications=publickey -o PasswordAuthentication=no），实测登录成功（服务端日志记录本次认证）：

2026/10/26 - 05:38:36 | Login attempt: 10.89.62.4:59942, user root key: ssh-ed25519 AAAAC3NzaC1lZDI1NTE1AAAAIOYISqzfKDHXOTjrS4i7j1bfYJhMRIUkvz9/IfyOzXMb

要点：目录轮询 200ms，放入即生效、移除即失效，适合 CI/临时授权的分钟级开关。

5.6 --port-bind-range / --bind-random-ports / --force-requested-ports：TCP 端口策略

修改：--port-bind-range=30000-30010 --bind-random-ports=false --force-requested-ports。

验证一（随机默认态）：-R 0:intranet-web:80，客户端拿到内核随机分配端口（实测回显）：

Allocated port 30009 for remote forward to intranet-web:80

服务端同步日志：

2026/10/26 - 05:38:38 | TCP forwarding started: sish.local:30009 -> /tmp/10.89.62.4_59942_01101499777 for client: 10.89.62.4:59942

访问验证（TCP 隧道闭环）：

curl -s http://10.89.62.2:30004/ | head -3
curl -sI http://10.89.62.2:30004/ | head -2

实测回显：

<!DOCTYPE html>
<html>
<head>
HTTP/1.1 200 OK
Server: nginx/1.31.8

验证二（默认态忽略请求端口）：请求 -R 30005:intranet-web:80，实测被随机替换为 30003：

2026/10/26 - 05:39:21 | TCP forwarding started: sish.local:30003 -> /tmp/10.89.62.4_58588_300053831978176 for client: 10.89.62.4:58588

验证三（force 生效）：加 --bind-random-ports=false --force-requested-ports 后请求 30005，访问 http://10.89.62.2:30005/ 返回 HTTP/1.1 200 OK（实测）。

验证四（冲突报错）：30005 已被占用时再次请求同端口，客户端回显：

Warning: remote port forwarding failed for listen port 30005

要点：--port-bind-range 既约束随机分配范围也约束手动请求合法性；生产固定端口服务（如对外 30005）必须关闭随机；放行防火墙时按 range 整段放行。

5.7 --tcp-aliases / --bind-random-aliases：TCP 私有别名

修改：--tcp-aliases，客户端绑定 -R myssh:22:intranet-web:22。

验证一（别名随机化默认态）：请求 myssh 被随机化为 w3m（服务端实测回显）：

2026/10/26 - 05:43:30 | TCP Alias forwarding started: w3m:22 -> /tmp/10.89.62.4_60410_222664791875 for client: 10.89.62.4:60410

验证二（跳板访问闭环）：另一会话经 sish 跳板连别名（-J 指定 sish 为跳板）：

ssh -o StrictHostKeyChecking=accept-new -J root@10.89.62.2:2222 root@w3m "hostname; echo ALIAS_OK"

实测回显（登录到的正是 intranet-web，别名闭环成立）：

Warning: Permanently added 'w3m' (ED25519) to the list of known hosts.
intranet-web
ALIAS_OK

要点：别名不占公网端口、只有能 ssh 到 sish 的人可用；要使用请求的别名须 --bind-random-aliases=false 或 --force-requested-aliases；访问白名单用 --tcp-aliases-allowed-users=<指纹列表> 收紧。

5.8 --admin-console：管理控制台

修改：--admin-console --admin-console-token=q1w2e3r4。

验证：

curl -s -H "Host: sish.local" "http://10.89.62.2/_sish/console?x-authorization=q1w2e3r4" -o /dev/null -w "%{http_code} %{size_download}\n"

实测回显（200，24332 字节 HTML 控制台页面）：

200 24332

⚠️ 注意：直连 IP 访问 console 会 404（curl "http://10.89.62.2/_sish/console?..." 实测返回 404 Not Found）——console 路由挂在域名 Host 之下，必须携带 Host: <domain>（或经真实域名访问）。这是排障高频点。

5.9 --redirect-root：根域名访问行为

默认态：--redirect-root=true，访问根域名（Host: sish.local）：

curl -sI -H "Host: sish.local" http://10.89.62.2/ | head -4

实测回显（302 到官方仓库，可用 -r 改为自己的落地页）：

HTTP/1.1 302 Found
Content-Type: text/html; charset=utf-8
Location: https://github.com/antoniomika/sish
Date: Mon, 26 Oct 2026 05:42:44 GMT

未知域名兜底：Host: evil.example（不在 --domain 域内）实测 HTTP/1.1 404 Not Found——非法 Host 不被路由，端口扫描式访问无隧道可落。

5.10 --append-user-to-subdomain：多租户用户名隔离

修改：--append-user-to-subdomain。

验证：用户 root 请求 myweb，实测分配：

2026/10/26 - 05:44:32 | HTTP forwarding started: http://myweb-root.sish.local -> /tmp/10.89.62.4_59602_802800220767 for client: 10.89.62.4:59602

要点：格式为 <别名>-<用户名>.<domain>（分隔符可改），不同 SSH 用户即使请求同名别名也互不冲突，是多租户平台的基础隔离手段。

5.11 --welcome-message 与日志类参数

验证：密码登录成功后的欢迎语（默认值实测回显）：

Press Ctrl-C to close the session.

HTTP 访问日志（默认输出，每请求一行，含子域名/状态码/耗时/来源/方法/路径）：

2026/10/26 - 05:36:03 | lz8.sish.local | 200 |    1.785524ms |      10.89.62.4 | GET     /

要点：生产建议 --log-to-file --log-to-file-path=/var/log/sish/sish.log（目录需 sish 账户可写），标准输出日志由 systemd 收进 journal。

六、生产配置模板

适用场景：4 核 16GB 云主机、对外提供团队级 HTTP+TCP 隧道服务、域名 sish.example.com 已泛解析、千兆带宽、Ubuntu 22.04。sish 为 Go 单二进制，空载内存约 12MB（实测 systemd status 回显 Memory: 12.5M），内存按并发连接线性增长，16GB 可支撑数千并发隧道。

/etc/systemd/system/sish.service（ExecStart 为生产推荐参数集）：

[Unit]
Description=sish SSH tunnel server (HTTP/TCP multiplexing)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=sish
Group=sish
WorkingDirectory=/opt/sish
Environment=SISH_ADMIN_CONSOLE_TOKEN=<强随机token>
ExecStart=/opt/sish/sish \
  --ssh-address=0.0.0.0:2222 \
  --http-address=0.0.0.0:80 \
  --https-address=0.0.0.0:443 \
  --domain=sish.example.com \
  --authentication=true \
  --authentication-keys-directory=/opt/sish/deploy/pubkeys \
  --port-bind-range=30000-30050 \
  --bind-random-ports=false \
  --force-requested-ports \
  --bind-random-subdomains=false \
  --force-requested-subdomains \
  --tcp-aliases \
  --bind-random-aliases=false \
  --force-requested-aliases \
  --admin-console \
  --redirect-root-location=https://wiki.example.com \
  --log-to-file \
  --log-to-file-path=/var/log/sish/sish.log \
  --ping-client \
  --ping-client-interval=10s \
  --proxy-protocol-listener \
  --proxy-protocol-policy=use
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

逐组说明：

• 认证：团队场景用公钥目录（每人一把公钥，动态增删），替代单密码；Environment= 注入的 console token 走 systemd 凭据管理，避免出现在命令行；
• 绑定策略：全 force 组合（ports/subdomains/aliases）换取确定性语义——占用了就报错，绝不静默换随机值，避免「隧道地址天天变」的排障成本；端口范围 30000-30050 与防火墙放行段一致；
• 保活：ping 间隔放宽到 10s，配合客户端 ServerAliveInterval 双向保活；
• 反代共存：上游有 nginx/负载均衡卸载 TLS 时，开 --proxy-protocol-listener 透传真实 IP，并按需 --http-port-override/--proxy-ssl-termination 修正展示 URL；
• 启用 HTTPS 时追加：--https --https-certificate-directory=/opt/sish/deploy/ssl（预置证书）或 --https-ondemand-certificate --https-ondemand-certificate-accept-terms（公网可验证环境按需签发）。

七、常见问题（FAQ）

Q1：改了参数但「没生效」？ 先查三通道叠加：systemctl cat sish 看 ExecStart 的命令行参数——命令行会覆盖 config.yml 同名键（3.2 节实测）；再看工作目录是否被自动加载了 config.yml（启动日志有 Using config file）；最后确认 systemctl daemon-reload + restart 已执行。

Q2：请求的端口/子域名被随机替换？ v3 默认随机策略（--bind-random-ports/--bind-random-subdomains/--bind-random-aliases 均默认 true），请求值只是意愿。关闭随机并按需加 force（5.3/5.6/5.7 节实测闭环）。注意：非 force 模式下冲突是静默回退，日志里只有随机值，容易被误判为「参数失效」。

Q3：客户端报 Permission denied (password,publickey)？ 认证默认开启且未配置凭据。配 --authentication-password 或放公钥到 pubkeys 目录（5.4/5.5 节）；匿名试验环境用 --authentication=false。

Q4：admin console 打不开（404）？ 两查：是否 --admin-console 已开启且 token 正确；请求是否带了合法的域名 Host——直连 IP 必 404（5.8 节实测）。正确形态 curl -H "Host: <domain>" "http://<host>/_sish/console?x-authorization=<token>"。

Q5：每次重启 host key 都变，客户端 known_hosts 告警？ WorkingDirectory 不固定或 deploy/keys 不可写导致密钥未持久化。检查 systemd 单元 WorkingDirectory=/opt/sish 与 sish 账户写权限；确认启动日志是 Loading ssh_key as ssh-ed25519 host key（已持久化）而非 Generated ED25519 Keypair（重新生成）。

Q6：80/443 与既有 nginx 冲突？ 方案一：sish 换端口（--http-address=0.0.0.0:8080）+ --http-port-override=80 让客户端看到的 URL 端口不变；方案二：nginx 做前置卸载 TLS 后反代到 sish，开 proxy-protocol 系列参数透传真实 IP（第六章模板）。

Q7：日志在哪、怎么轮转？ 默认 stdout（journalctl -u sish 查看）。开启 --log-to-file 后写 --log-to-file-path，内置按大小（默认 500MB）/份数（3）/天数（28）轮转，可选压缩（--log-to-file-compress）。

八、参考链接

• 官方仓库与 README：https://github.com/antoniomika/sish
• 官方文档站（CLI Reference）：https://docs.ssi.sh/cli
• 版本发布：https://github.com/antoniomika/sish/releases
• 本组件认知与选型：《sish 3.0.5 介绍与选型指南》
• 本组件安装部署：《Ubuntu 22.04 安装 sish 3.0.5 指南》
• 本组件客户端命令：《sish 3.0.5 常用 CLI 命令详解》