ShellHub 配置参数详解

ShellHub v0.27.4 自托管配置体系全解：.env 配置链读取顺序、网络/TLS/代理/数据库/日志/功能与企业版变量逐项说明，锁出策略与日志级别等 7 项行为实测验证，密钥挂载与配置最佳实践。

ShellHubSSH远程接入2026/10/27

ShellHub 配置参数详解

目标：把 ShellHub v0.27.4 社区版自托管部署的全部配置项讲透——配置文件的读取链路、环境变量逐项含义与实测行为、密钥挂载与编排细节。逐项参数以官方 .env 注释与 docs.shellhub.io 环境变量清单为基准，行为结论全部来自本机实测（2026-10-27，部署过程见 《ShellHub Docker Compose 部署实战》，选型认知见 《ShellHub 介绍与选型指南》）。

一、环境信息

  • 实测版本：ShellHub v0.27.4 社区版（Apache-2.0，官方 Compose 编排）
  • 实测环境：Ubuntu 24.04.5 LTS / Docker 29.9.2 / Docker Compose v5.6.1（见部署篇）
  • 服务栈：gateway、server、ui、postgres:18.0、valkey(redis) 五服务
  • 实验地址：shellhub.lab（hosts 模拟），HTTP 8131 / SSH 8133
  • 溯源基准：仓库 .env（v0.27.4 标签）、docs.shellhub.io/selfhosted/environment-variables（2026-10-27 查询）

二、配置体系总览

ShellHub 自托管的配置分三层，只有环境变量链需要用户动手：

  1. 环境变量链：由官方包装器 ./bin/docker-compose 按固定顺序加载，后读的覆盖先读的：
    1. .env —— 默认值（官方明确警告：不要编辑，升级会被覆盖）；
    2. .env.enterprise —— 企业版默认（仅当 SHELLHUB_EDITION 非 community 时加载）；
    3. ../cloud/.env —— Cloud 部署专用（存在时）；
    4. .env.override —— 用户的配置文件，优先生效于以上一切。
  2. Docker secrets：三份密钥文件由 make keygen 生成（api_private_key、api_public_key、ssh_private_key），编排内以 secrets 机制挂进 server，不落环境变量；
  3. 编排文件：docker-compose.yml（主编排）+ docker-compose.postgres.yml（PostgreSQL 扩展层）+ 可选 docker-compose.override.yml（用户自定义编排扩展，如持久化卷）。包装器负责按 edition 拼装文件列表——因此任何手工编排操作必须走 ./bin/docker-compose，裸 docker compose 会漏掉 PostgreSQL 层（实测 server 无库可连，见部署篇 R5）。

所有变量统一 SHELLHUB_ 前缀。修改变量后执行 make restart 生效（官方文档的 Applying changes 原话）。

三、环境变量逐项详解

3.1 网络与端口

变量默认值说明（含实测）
SHELLHUB_BIND_ADDRESS0.0.0.0网关绑定地址。实测渲染进 gateway 配置
SHELLHUB_HTTP_PORT80Web/API/agent 回连端口。实测 8131 后 docker-compose config 渲染出 published: 8131 -> 80
SHELLHUB_HTTPS_PORT443HTTPS 端口，仅 SHELLHUB_AUTO_SSL=true 时才会绑定发布
SHELLHUB_SSH_PORT22SSH 网关入口。实测 8133 后渲染出 server 服务的 published: 8133 -> 2222——端口由 server 发布而非 gateway（前置负载均衡时关键）
SHELLHUB_DOMAINlocalhost服务公共域名。必须合法 hostname：实测填 IP 时 gateway 启动即报 Field validation for 'Domain' failed on the 'hostname' tag 并崩溃循环（部署篇 R2）
SHELLHUB_NETWORKshellhub_network实例网络名。实测覆盖为自建网络名并与 _EXTERNAL=true 配合
SHELLHUB_NETWORK_EXTERNALfalsetrue 时加入既存网络而不新建（网络须先存在；down 不删网络）。实测：自建 10.89.66.0/24 桥接网络并显式 --subnet，agent 与服务栈同网互通

3.2 TLS 与证书

变量默认值说明
SHELLHUB_AUTO_SSLfalse向 Let's Encrypt 自动签发证书。开启后 HTTPS 端口才生效，且要求 SHELLHUB_DOMAIN 是可公网解析的真实域名
SHELLHUB_TLS_CERT_FILE空自带证书路径（gateway 内路径）。官方注释：这是让内网主机名跑 HTTPS 的唯一方式；与 _TLS_KEY_FILE 必须成对设置，否则 gateway 拒绝启动
SHELLHUB_TLS_KEY_FILE空证书私钥路径
SHELLHUB_ACME_CA_SERVER空ACME 目录地址，空即 Let's Encrypt 生产环境；可指向 staging 端点做演练（staging 证书浏览器不信任，仅验证流程）

实验环境用 http:// 明文（AUTO_SSL 默认 false），生产建议 AUTO_SSL=true 或在前面负载均衡终结 TLS。

3.3 反向代理与公共地址

变量默认值说明（含实测）
SHELLHUB_PUBLIC_URL由 DOMAIN+AUTO_SSL 推导用户实际访问的 URL（仅 http/https + 主机 + 可选端口，不能带路径）。实测改它需 make restart；TLS 终结在外部入口时必须显式设置，否则 SSH 审批链接等会以错误协议开头
SHELLHUB_PROXYfalse网关接受四层负载均衡的 PROXY protocol
SHELLHUB_PROXY_TRUSTED_IPS"0.0.0.0/0 ::/0"允许声明客户端地址的 CIDR（作用于 HTTP/HTTPS，影响登录锁出与 GeoIP 的来源 IP 判定）。默认信任所有人对裸部署无意义，上了负载均衡应收窄到负载均衡网段
SHELLHUB_SSH_PROXY_TRUSTED_IPS空SSH 端口的 PROXY 头来源白名单（回环恒信任）。不要包含 Docker 桥接网段：userland 代理让所有外部客户端看起来都来自桥接网段，等于允许地址伪造。v0.27.2 新增
SHELLHUB_TUNNEL_PING_INTERVAL空（v1 30s/v2 35s 默认）服务端对设备隧道的 ping 间隔。路径上有短空闲超时的 NAT/负载均衡时调小；须为正的时长且小于 1 分钟，服务端拒绝非法值启动。设备距最后 ping 2 分钟判离线

3.4 数据库

变量默认值说明（含实测）
SHELLHUB_DATABASEpostgres存储引擎。实测确认 v0.27 已无 MongoDB 选项，填其他值仅告警并回退 postgres
SHELLHUB_POSTGRES_HOSTpostgres主机名（编排内服务名；外部库填可达地址）
SHELLHUB_POSTGRES_EXTERNALfalsetrue 时使用编排外 PostgreSQL，内置 postgres 服务不启动（需自备实例与备份）
SHELLHUB_POSTGRES_PORT5432端口
SHELLHUB_POSTGRES_USERNAMEadmin后缀是 _USERNAME 不是 _USER（官方特意强调）
SHELLHUB_POSTGRES_PASSWORDadmin必改。实测改为强口令后服务正常
SHELLHUB_POSTGRES_DATABASEmain库名，后缀是 _DATABASE 不是 _DB
SHELLHUB_POSTGRES_EXTRA_ARGS空附加到 postgres 启动命令的参数（如 -c shared_buffers=4GB），重启生效
SHELLHUB_POSTGRES_LOG_LEVEL / _LOG_VERBOSEINFO / false数据库侧日志

⚠️ 持久化注意：内置 postgres 服务官方默认不挂卷，实例删除即丢数据。必须自行在 docker-compose.override.yml 补命名卷，且 postgres:18 镜像的挂载点须为 /var/lib/postgresql（挂旧路径 /.../data 会被 18 版判定无用挂载拒启，实测见部署篇 R1）。

3.5 日志与可观测

变量默认值说明（含实测）
SHELLHUB_LOG_LEVELinfotrace/debug/info/warn/error/fatal。实测在 .env.override 写 debug 后 make restart，server 日志出现 debug 级输出，改回后恢复
SHELLHUB_LOG_FORMATtexttext 或 json（采集管道建议 json）
SHELLHUB_GATEWAY_ACCESS_LOGStrue网关访问日志开关
SHELLHUB_METRICSfalse指标端点开关
SHELLHUB_SENTRY_DSN空错误上报

3.6 功能与行为

变量默认值说明（含实测）
SHELLHUB_EDITIONcommunitycommunity/enterprise/cloud。社区版单命名空间：实测第二个命名空间创建被拒
SHELLHUB_VERSION所检出的 release全栈镜像版本统一驱动器，升级只改它
SHELLHUB_PAYWALLtrue社区版界面是否展示企业功能入口
SHELLHUB_MAXIMUM_ACCOUNT_LOCKOUT60反复登录失败后的最大锁出分钟数，0 关闭
SHELLHUB_ACCOUNT_LOCKOUT_BASE1m首次锁出时长（Go duration，≥1s），之后每次 4 倍递增、封顶于上一项。实测验证：连错 2 次密码返回 401，第 3 次起 429，且锁出期内正确密码也 429；约 1 分钟后（BASE 时长）自动解锁恢复 200
SHELLHUB_PERMIT_EMPTY_PASSWORDSfalseagent 侧：设备上是否允许空密码系统账号经 SSH 登录
SHELLHUB_WORKER_SCHEDULE@daily后台任务（Go cron 格式，如临时设备清理）
SHELLHUB_ASYNQ_UNIQUENESS_TIMEOUT24任务队列唯一锁时长（小时），≤0 关闭
SHELLHUB_REDIS_CACHE_POOL_SIZE00 即驱动默认值
SHELLHUB_ONBOARDING_URL官方问卷地址首账号向导问卷；置空禁用（内网环境实测置空后 /setup 直接进账号表单）
SHELLHUB_PROVISIONING_KEY_WEBHOOK_ALLOWED_CIDRS空预配密钥 webhook 模式可访问的网段；空=禁止全部私网/回环/元数据地址（SSRF 防线，放行私网集成器才改）
SHELLHUB_ALLOW_PUBLIC_KEY_ACCESS_BELLOW_0_6_0false允许 0.6.0 以下旧 agent 走公钥认证。变量名确实拼错为 BELLOW，官方文档明示照抄（实测按原样可渲染）
SHELLHUB_CONNECTORtrue连接器（容器会话）特性开关
SHELLHUB_NAMESPACE_REQUIRE_VERIFIED_DEVICE_KEYtrue新建命名空间默认开启「设备签名强制」（既有命名空间不受影响）

3.7 企业版变量（.env.enterprise）

SHELLHUB_ENTERPRISE_ADMIN_USERNAME/PASSWORD（企业管理控制台）、SHELLHUB_SAML_SECRET（SP 密钥加密）、SHELLHUB_WEB_ENDPOINTS*（Web 端点发布域与 DNS 提供商）、SHELLHUB_OBJECT_STORAGE_*（会话录制存储，默认 MinIO；_ACCESS_KEY/_SECRET_KEY 默认 username/password 必改）、SHELLHUB_MAXMIND_LICENSE（GeoIP）。社区版部署不加载这些值（edition 非 community 时由包装器自动带上 .env.enterprise）。

四、实测验证记录

配置行为的实测证据（全部可复现）：

  1. 锁出策略：{"username":"admin","password":"wrongpassN"} 连续提交——第 1/2 次 401，第 3 次起 429（响应体 too many requests），锁出期内正确密码同样 429；1 分钟后（SHELLHUB_ACCOUNT_LOCKOUT_BASE=1m）正确密码恢复 200。服务端日志同时记录了 429 的完整请求元数据（remote_ip、latency、uri）。
  2. 日志级别：.env.override 追加 SHELLHUB_LOG_LEVEL=debug → make restart → server 出现 debug 级日志；删除后重启恢复 info。
  3. 端口与发布者：SHELLHUB_HTTP_PORT=8131、SHELLHUB_SSH_PORT=8133 后 ./bin/docker-compose config 渲染：gateway 发布 8131->80、server 发布 8133->2222（SSH 在 server，验证官方「SSH 端口不是网关发布」的说明）。
  4. 域名校验：SHELLHUB_DOMAIN=192.168.146.128 时 gateway 崩溃循环（hostname 校验失败，部署篇 R2）；改为 shellhub.lab 后正常。
  5. Host 匹配兜底：域名未对齐时访问返回空 404——网关配置含显式兜底规则，官方注释称这是为防 agent 把错误 200 空响应当服务信息（部署篇 R3）。
  6. 外部网络：SHELLHUB_NETWORK=shellhub-v0.27.4-net + SHELLHUB_NETWORK_EXTERNAL=true，预建显式子网桥接网络，五服务与 agent 同网互达；down 后网络保留。
  7. Compose 项目名：项目名含点号（如 shellhub-v0.27.4-stack）被 Compose 拒绝（invalid project name），改用 shellhub-v0274-stack。多实例共存时注意项目名与网络名都要错开。

五、密钥与挂载

  • 三份 secrets（make keygen 产物）→ 编排以 Docker secrets 挂载：/run/secrets/api_private_key、/run/secrets/api_public_key、/run/secrets/ssh_private_key。API 密钥对签发与校验 JWT；SSH 主机密钥是 SSH 网关的 host key。重新生成 SSH 主机密钥 = 全网客户端指纹报警，务必先备份；
  • PostgreSQL 卷：官方默认无卷，按部署篇 4.4 节的 override 补命名卷（挂载点 /var/lib/postgresql）；
  • agent 侧挂载（由官方 install.sh 处理，手动等价时注意）：agent 镜像为极简构造，需特权 + 宿主根文件系统挂载（/:/host）+ Docker 套接字，缺任一即启动失败（部署篇 R4）；设备私钥路径由 agent 环境变量 SHELLHUB_PRIVATE_KEY 指定，默认生成于设备 /etc/shellhub.key。

六、配置最佳实践

  1. 一切自定义进 .env.override，永不改 .env（升级安全）；
  2. 上线前必改三项：SHELLHUB_POSTGRES_PASSWORD、SHELLHUB_DOMAIN（真实域名）、SHELLHUB_ONBOARDING_URL（内网置空）；
  3. 上了负载均衡/TLS 卸载：SHELLHUB_PUBLIC_URL 设为 https:// 入口、SHELLHUB_PROXY_TRUSTED_IPS 与 SHELLHUB_SSH_PROXY_TRUSTED_IPS 收窄到负载均衡网段（且不写 Docker 桥段）；
  4. NAT 空闲超时 < 35s 的链路：调低 SHELLHUB_TUNNEL_PING_INTERVAL；
  5. 多实例同机：错开 SHELLHUB_HTTP_PORT/SHELLHUB_SSH_PORT/SHELLHUB_NETWORK 与 Compose 项目名；
  6. 面向自动化管道：评估 SHELLHUB_MAXIMUM_ACCOUNT_LOCKOUT 对脚本重试的影响（429 会连带正确密码一起锁）；
  7. 变更后 make restart 生效；升级改 SHELLHUB_VERSION 后阅读官方 Upgrade 文档再动。

七、配置相关排障速查

症状根因与处置（均为实测）
gateway 秒级重启，日志 hostname 校验失败SHELLHUB_DOMAIN 填了 IP；改域名（部署篇 R2）
服务 healthy 但 API 全 404访问 Host 与 SHELLHUB_DOMAIN 不一致；统一域名访问（部署篇 R3）
postgres 起不来，日志提示 unused mount/volumepostgres:18 挂载点须为 /var/lib/postgresql（部署篇 R1）
server 连不上数据库用了裸 docker compose，漏了 PostgreSQL 编排层；改走 ./bin/docker-compose（部署篇 R5）
Compose 拒绝项目名项目名只允许字母数字与连字符，去掉点号（本文 4.7）
登录 429触发锁出（默认连错 2 次即锁 1 分钟，4 倍递增）；等期满或调 SHELLHUB_ACCOUNT_LOCKOUT_*
公钥注册 422 illegal base64 datav0.27 接口 data 字段要求 base64 编码的公钥文本（部署篇 R6）
/setup 出现外部问卷加载慢内网环境置空 SHELLHUB_ONBOARDING_URL

八、参考链接