Hoppscotch 2026.9.0 配置参数详解

Hoppscotch 2026.9.0 社区版配置参数逐组实测：.env 三层加载机制（环境注入/VITE 烘焙/InfraConfig 入库）、数据库连接与 32 字节加密密钥校验、CORS 白名单三态、单端口子路径模式，附 ERR_CRYPTO_INVALID_KEYLEN、Prisma P1000、restart 不生效等错误面实录。

HoppscotchHoppscotchAPI2026/10/21

Hoppscotch 2026.9.0 配置参数详解

目标：逐组讲清 Hoppscotch 社区版（2026.9.0）自托管的配置体系——.env 环境文件各参数的取值与生效机制、管理台引导的实例级配置，以及配置改错时的真实报错形态。全部结论在 Ubuntu 22.04 + Docker Compose（部署步骤见《Hoppscotch Docker Compose 部署指南》）上实测取证，报错回显均逐行照抄。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • Hoppscotch：2026.9.0（AIO 发行形态，镜像 hoppscotch/hoppscotch:2026.9.0）
  • 数据库：PostgreSQL 15；编排：Docker Compose v2
  • 实验基线端口：8141（主应用 3000）、8142（管理台 3100）、8143（后端 API 3170）、8144（bundle server 3200）
  • 配置文件：/opt/data/ops/hoppscotch/.env（迁移与应用服务共用）

二、配置加载机制总览

Hoppscotch 社区版的配置分三层，生效时机各不相同，这是排查「改了配置不生效」问题的钥匙：

层载体代表参数生效时机
环境注入.env（compose env_file）DATABASE_URL、DATA_ENCRYPTION_KEY、ENABLE_SUBPATH_BASED_ACCESS、TRUST_PROXY服务创建时注入进程环境，docker compose up -d 重建后生效
前端烘焙.env 的 VITE_* 系列VITE_BASE_URL、VITE_ADMIN_URL、VITE_BACKEND_*_URL应用启动流程中烘焙进前端页面产物（见 5.2 实测），同样需重建
实例入库管理台引导写入数据库基础设施配置表SMTP（MAILER_）、OAuth、JWT_SECRET、SESSION_SECRET、RATE_LIMIT_管理台 onboarding 流程写入数据库，改后需重建应用服务重载（见 8.1）

💡 说明：官方将 SMTP、OAuth、JWT_SECRET 等实例参数放在数据库基础设施配置表而非 .env，由管理台引导流程（onboarding）统一写入并加密存储——这也是 DATA_ENCRYPTION_KEY 必须稳定的原因（3.2 实测）。

三、数据库与加密配置

3.1 DATABASE_URL（数据库连接串）

格式：postgresql://<用户>:<密码>@<主机>:5432/<库名>?connect_timeout=300。Compose 部署时主机名写 compose 服务名（内部 DNS 解析），实测基线值：

DATABASE_URL=postgresql://postgres:q1w2e3r4@hoppscotch-db:5432/hoppscotch?connect_timeout=300

错误面实测（密码错误）：把连接串密码改为错误值后 docker compose up -d，迁移服务先行失败并阻塞应用服务启动（依赖 service_completed_successfully）。迁移服务日志实测回显：

Error: P1000: Authentication failed against database server, the provided database credentials for `postgres` are not valid.

Please make sure to provide valid database credentials for the database server at the configured address.

编排侧同步报 service "hoppscotch-migrate" didn't complete successfully: exit 1。排障口诀：看到 P1000 先核密码，看到 exit 1 先看迁移服务日志。

3.2 DATA_ENCRYPTION_KEY（实例级加密密钥）

用于加解密数据库基础设施配置表中已入库的敏感配置（SMTP 口令、OAuth 密钥等），必须恰好 32 个字符。基线值（示例）：

DATA_ENCRYPTION_KEY=hoppscotch-demo-encryption-key32

错误面实测（长度不足）：改为 20 字符的值后重建服务，应用启动即报解密初始化错误，日志实测回显：

Backend Server | Error from loadInfraConfiguration RangeError: Invalid key length
Backend Server |     at Decipheriv.createCipherBase (node:internal/crypto/cipher:118:19)
Backend Server |     at Decipheriv.createCipherWithIV (node:internal/crypto/cipher:129:3)
Backend Server |     at new Decipheriv (node:internal/crypto/cipher:248:3)
Backend Server |     at Object.createDecipheriv (node:crypto:154:10)
Backend Server |   code: 'ERR_CRYPTO_INVALID_KEYLEN'

⚠️ 注意：报错来自 loadInfraConfiguration（读取已入库密文），说明该密钥与已加密的历史数据强绑定——实例一旦投产就不要再更换，否则已入库的 SMTP/OAuth 配置将无法解密。生成合规密钥可用 openssl rand -base64 24（产出 32 字符）或任意 32 字符随机串。

四、CORS 与代理安全

4.1 WHITELISTED_ORIGINS（后端 CORS 白名单）

逗号分隔的来源白名单，控制哪些站点可携带凭证跨域调用后端 API。多端口部署基线值：

WHITELISTED_ORIGINS=http://localhost:8143,http://localhost:8141,http://localhost:8142,app://localhost_3200,app://hoppscotch

三态实测（对 8143 后端发起带 Origin 的请求）：

白名单内来源——回显该来源并允许凭证：

curl -s -D- -o /dev/null -H 'Origin: http://localhost:8141' http://localhost:8143/ping | grep -i 'access-control\|HTTP/'

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: http://localhost:8141

白名单外来源——不下发 Allow-Origin 头（浏览器将拦截跨域响应）：

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true

预检请求——放行方法集合实测回显：

HTTP 204
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET,HEAD,PUT,PATCH,POST,DELETE
Access-Control-Allow-Origin: http://localhost:8141
Vary: Origin, Access-Control-Request-Headers

💡 说明：改端口部署时必须同步把三个入口（主应用/管理台/后端）的实际访问地址列全，漏列的症状是「页面能打开但请求全挂」——典型的 CORS 拦截。app:// 前缀供桌面客户端使用，保留即可。

4.2 TRUST_PROXY

是否信任反向代理头（X-Forwarded-*）。直连部署保持 false；置于 Nginx/Caddy 等反代之后并依赖其传递真实客户端 IP 时设 true。取值不当时的影响面是客户端 IP 识别（限流、日志），不影响核心功能。

4.3 PROXY_APP_URL

浏览器端受限请求的官方代理地址，默认指向官方公共服务：

PROXY_APP_URL="https://proxy.hoppscotch.io"

💡 说明：浏览器直连第三方 API 常被目标站 CORS 拦截，Hoppscotch 通过代理转发绕开。内网/离线环境可自建代理后改此值；不改也不影响实例核心调试功能，仅代理类请求走官方服务。

五、前端入口地址 VITE_* 系列

5.1 参数表（多端口模式基线值）

参数基线值指向
VITE_BASE_URLhttp://localhost:8141主应用入口（集合/请求工作台）
VITE_SHORTCODE_BASE_URLhttp://localhost:8141短链分享入口（与主应用同址）
VITE_ADMIN_URLhttp://localhost:8142管理台入口
VITE_BACKEND_GQL_URLhttp://localhost:8143/graphql后端 GraphQL 接口
VITE_BACKEND_WS_URLws://localhost:8143/graphql后端 WebSocket 订阅
VITE_BACKEND_API_URLhttp://localhost:8143/v1后端 REST 接口
VITE_APP_TOS_LINK / VITE_APP_PRIVACY_POLICY_LINK官方文档站链接服务条款/隐私政策外链

⚠️ 注意：这些值必须与用户浏览器实际访问地址一致（含端口），不是服务间互联地址。改端口映射时逐项核对，漏改的症状是「登录跳转/接口调用仍指向旧端口」。

5.2 烘焙机制实测

VITE_* 系列并非运行时读取，而是在应用启动时注入前端页面产物的 import_meta_env 全局对象。实测抓取主应用首页 HTML：

curl -s http://localhost:8141/ | grep -o 'globalThis.import_meta_env[^<]\{0,260\}' | head -1

globalThis.import_meta_env = JSON.parse('{"VITE_ADMIN_URL":"http:\u002F\u002Flocalhost:8142","VITE_APP_PRIVACY_POLICY_LINK":"https:\u002F\u002Fdocs.hoppscotch.io\u002Fsupport\u002Fprivacy","VITE_APP_TOS_LINK":"https:\u002F\u002Fdocs.hoppscotch.io\u002Fsupport\u002Fterms","VITE_BACKEND_

restart 与 up -d 差异实录：把 VITE_BASE_URL 改为 http://192.168.1.100:8141 后 docker compose up -d 重建，页面烘焙值随即变为新值：

VITE_BASE_URL":"http:\u002F\u002F192.168.1.100:8141"

随后把 .env 改回原值，仅执行 docker compose restart hoppscotch-aio，页面烘焙值仍是旧值：

VITE_BASE_URL":"http:\u002F\u002F192.168.1.100:8141"

再执行 docker compose up -d 重建后才恢复：

VITE_BASE_URL":"http:\u002F\u002Flocalhost:8141"

结论：环境变量在服务创建时注入，restart 不重读 .env——任何 .env 变更都用 docker compose up -d 应用，不要用 restart。

六、部署形态开关：ENABLE_SUBPATH_BASED_ACCESS

  • false（默认，多端口模式）：主应用/管理台/后端各占独立端口（3000/3100/3170）；
  • true（单端口子路径模式）：三者收口到 Caddy 的单一 80 端口，管理台挂 /admin 前缀、后端挂 /backend 前缀，bundle server 仍独立在 3200。

切换实测（开启后需同步改 VITE_* 为同址加前缀，并把端口映射切到 80）：

ENABLE_SUBPATH_BASED_ACCESS=true
VITE_ADMIN_URL=http://localhost:8141/admin
VITE_BACKEND_GQL_URL=http://localhost:8141/backend/graphql
VITE_BACKEND_WS_URL=ws://localhost:8141/backend/graphql
VITE_BACKEND_API_URL=http://localhost:8141/backend/v1

重建后逐项验证（8141 即映射到 80）：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8141/        # 主应用
curl -s http://localhost:8141/admin | grep -o '<title>[^<]*</title>'  # 管理台
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8141/backend/ping  # 后端健康检查

实测回显：

200
<title>Hoppscotch Admin</title>
200

同时确认旧端口已收口：原 3100/3170 映射端口（8142/8143）连接拒绝、不再监听；bundle server（8144/3200）保持原样（根路径 404 属正常，其只服务分包资源路径）。该模式适合反向代理统一入口、或不便开放多端口的场景——对外只暴露一个端口。

七、可选功能项

参数说明
VITE_SHORTCODE_BASE_URL短链分享功能的对外地址；不用分享功能可留默认（与主应用同址）
VITE_PROXYSCOTCH_ACCESS_TOKEN官方代理服务的访问令牌，走公共代理时按官方说明填，内网自建代理则无需
VITE_APP_TOS_LINK / VITE_APP_PRIVACY_POLICY_LINK界面底部服务条款/隐私政策外链，企业内网可改为内部合规页

八、.env 之外的实例级配置（InfraConfig）

8.1 管理台引导配置（SMTP/OAuth）

SMTP、OAuth 提供方等在管理台引导流程中写入数据库基础设施配置表（加密存储），不读 .env 中的同名项。引导未完成时也可直接调开放接口写入（部署指南第五章完整实测）：

curl -s -X POST http://localhost:8143/v1/onboarding/config \
  -H 'Content-Type: application/json' \
  -d '{"VITE_ALLOWED_AUTH_PROVIDERS":"EMAIL","MAILER_SMTP_ENABLE":"true","MAILER_SMTP_URL":"smtp://hoppscotch-mailpit:1025","MAILER_ADDRESS_FROM":"hoppscotch@localhost.local"}'

实测回显（返回引导恢复令牌）：

{"token":"7286b32c-7464-47cb-b611-906b64487b71"}

⚠️ 注意：写入后需 docker compose up -d --force-recreate hoppscotch-aio 重建应用服务，mailer 模块才会在启动时装载新 SMTP transport（重启进程不重读库内配置，与 .env 的 restart 限制同理）。恢复令牌丢失且未完成引导时，实例配置可依据官方文档用 ONBOARDING_RECOVERY_TOKEN 流程找回。

8.2 已入库配置的解密依赖

基础设施配置表中的敏感字段用 DATA_ENCRYPTION_KEY 加密，因此 3.2 的教训在此汇合：密钥丢失/变更 = 已配置的 SMTP/OAuth 全部失效，需重走引导流程。

九、常见配置错误速查

症状报错关键字根因解法
应用起不来，日志报解密错误ERR_CRYPTO_INVALID_KEYLEN / Invalid key lengthDATA_ENCRYPTION_KEY 非 32 字符改为 32 字符；注意与已入库密文绑定，投产勿换
迁移失败、栈起不来P1000: Authentication failedDATABASE_URL 凭证错误核对密码/主机名，修正后 up -d
页面能开但接口全挂浏览器 CORS 拦截WHITELISTED_ORIGINS 漏列实际端口补全三个入口地址后 up -d
改了地址但页面仍旧值烘焙值未变只 restart 未重建用 docker compose up -d 重建
登录收不到邮件日志无报错但无邮件MAILER_SMTP_ENABLE 未开（静默跳过）完成 onboarding SMTP 配置并重建
单端口模式旧端口还在映射连接拒绝形态切换后端口映射未同步端口映射改指 80，VITE_* 同步改子路径

十、参考链接

  1. 官方自托管前置条件（.env 参数官方说明）：https://docs.hoppscotch.io/documentation/self-host/community-edition/prerequisites
  2. 官方安装与构建（多端口/子路径两种形态）：https://docs.hoppscotch.io/documentation/self-host/community-edition/install-and-build
  3. 官方 .env.example：https://github.com/hoppscotch/hoppscotch
  4. 本专栏姊妹篇：《Hoppscotch Docker Compose 部署指南》《Hoppscotch 2026.9.0 介绍与选型指南》