Shhh 3.2.4 配置参数详解

目标：讲透 Shhh 3.2.4 的全部配置面——10 个环境变量（6 必填 4 可选）的取值、默认值与实测行为，加上创建秘密时的校验参数（口令强度、有效期档位、尝试次数、长度上限），并给出参数缺失/非法时的诊断路径。全部行为结论均有 2026-10-26/27 实测回显支撑；部署前置见 《Shhh 3.2.4 Ubuntu 22.04 源码部署指南》，参数速查可配合 《Shhh 3.2.4 Docker Compose 部署指南》 使用。

一、环境信息

二、配置体系总览

Shhh 没有 YAML/TOML 配置文件，所有服务级配置都通过环境变量注入，启动时由 shhh/config.py 按 FLASK_ENV 的值加载对应配置类。理解三点即可掌握全貌：

1. FLASK_ENV 是总开关：决定加载哪套配置（合法值仅 5 个），缺失或拼错程序直接拒绝启动（实测见第七节排障）。
2. 数据库连接五件套必填：DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME / DB_ENGINE，其中 DB_PORT 有默认值 5432。
3. SHHH_* 前缀是行为微调：共 4 个可选变量，控制链接域名、秘密长度上限、数据库重试策略。

三、必填环境变量逐项详解

3.1 FLASK_ENV —— 运行环境选择

五个取值的实际差异（溯源自 shhh/config.py，2026-10-26）：production 与其余环境的差别主要在关闭 DEBUG 输出；dev-docker/dev-local 面向开发调试；heroku 额外支持从 DATABASE_URL 组装数据库连接（Heroku 一键部署形态专用）。自托管生产固定用 production。

3.2 数据库连接五件套

DB_ENGINE 的两种官方支持写法（README 原文示例）：

💡 POSTGRES_* / MYSQL_* 三件套不是 Shhh 本体读的，而是数据库服务自己的初始化变量（首次启动建库建用户用）。两边取值必须一致（README 特别注明 match DB_USER/DB_PASSWORD/DB_NAME），否则会出现「数据库初始化成 A，应用却连 B」的启动失败。

选型上 PostgreSQL 是官方主路径（官方在线形态与 Heroku 部署均固定 PostgreSQL），MySQL 为等价可选项；两者的 Shhh 侧行为无差别，差别只在运维生态。

四、可选环境变量逐项详解（附实测）

4.1 SHHH_HOST —— 自定义分享链接域名

实测：设置 SHHH_HOST=https://shhh.example.com 后创建一条秘密（有效期 1d），返回的 link 字段：

{"response":{"details":"Secret successfully created.","expires_on":"October 28, 2026 at 00:19 UTC","external_id":"cH8qfBWWsnebKcYv9AIJ","link":"https://shhh.example.com/secret/cH8qfBWWsnebKcYv9AIJ","status":"created"}}

HTTP_STATUS:201

链接前缀随 SHHH_HOST 变化，external_id 不受影响。不设该变量时，前缀跟随访问所用的 host（如 http://127.0.0.1:8081/secret/...）。

4.2 SHHH_SECRET_MAX_LENGTH —— 秘密长度上限

两段实测回显：

{"response":{"details":"The secret should not exceed 250 characters.","status":"error"}}

{"response":{"details":"The secret should not exceed 50 characters.","status":"error"}}

该变量是「一口调小以收紧业务边界」的典型入口：单位是字符（非字节），调大超过 250 属于放宽官方默认，需自行评估数据库字段容量与安全边界。

4.3 SHHH_DB_LIVENESS_RETRY_COUNT / SHHH_DB_LIVENESS_SLEEP_INTERVAL —— 数据库重试策略

设计动机：数据库短暂不可达或休眠时（README 举例 Heroku 免费套餐常见的休眠唤醒），应用先重试再放弃，避免偶发抖动直接变成用户可见报错。自托管持久数据库形态下保持默认即可；若数据库与 Shhh 跨网络且有抖动，可适当调大这两个值。

五、创建秘密时的校验参数（API 侧默认值）

严格说这组不是环境变量，而是每次创建秘密时提交的参数与内建校验规则，与 SHHH_SECRET_MAX_LENGTH 联动，归在本篇做总账（逐请求回显见姊妹篇 《Shhh 3.2.4 API 使用详解》）：

弱口令拒绝的完整实测回显（提交 q1w2e3r4，无大写）：

{"response":{"details":"Sorry, your passphrase is too weak. It needs minimum 8 characters, with 1 number and 1 uppercase.","status":"error"}}

两条选型提示：

• expire 上限 7 天是产品语义：Shhh 的定位是「临时信封」，没有长期保存选项；需要更久的分享场景请改用密码管理器共享。
• tries 是防暴力破解闸门：链接泄露后，攻击者最多只有 3/5/10 次机会猜口令，用尽即销毁——所以口令分发渠道本身也要可靠（链接与口令分渠道发送）。

六、参数速查表（可直接抄进部署清单）

# --- 必填 ---
FLASK_ENV=production
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=shhh
DB_PASSWORD=<强口令>
DB_NAME=shhh
DB_ENGINE=postgresql+psycopg2
# --- 可选 ---
# SHHH_HOST=https://shhh.example.com     # 自定义分享链接域名
# SHHH_SECRET_MAX_LENGTH=250             # 秘密长度上限（默认 250）
# SHHH_DB_LIVENESS_RETRY_COUNT=5         # 数据库重试次数（默认 5）
# SHHH_DB_LIVENESS_SLEEP_INTERVAL=1      # 数据库重试间隔秒数（默认 1）

七、排障速查：参数错了会怎样

八、参考链接

• 官方 README 环境变量章节：https://github.com/smallwat3r/shhh#environment-variables
• 配置源码：https://github.com/smallwat3r/shhh/blob/master/shhh/config.py
• 3.2.4 发布页：https://github.com/smallwat3r/shhh/releases/tag/3.2.4
• 本专栏姊妹篇：《Shhh 3.2.4 Ubuntu 22.04 源码部署指南》、《Shhh 3.2.4 Docker Compose 部署指南》、《Shhh 3.2.4 介绍与选型指南》、《Shhh 3.2.4 API 使用详解》