企业官网建设流程全解析

Hoppscotch 自托管 Docker Compose 的 default、default-no-db 与 just-backend profile 怎么选

【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch

当你把 Hoppscotch 的仓库克隆下来准备自托管时，docker-compose.yml 根部的注释里列出了一组 Docker Compose profile：default、default-no-db、backend、app、admin、database、just-backend、deprecated。三者里最容易混淆的是标题中的三个：它们决定了一次docker compose up到底会拉起哪些容器、暴露哪些端口、以及是否需要你自己准备数据库。这篇文章只回答一个问题：你的部署目标属于哪一种，就选哪个 profile，并给出对应的启动命令和验证方式。

三个 profile 各自启动什么

以下事实全部来自 docker-compose.yml 中的服务定义与注释：

• default—— AIO 一体化容器 +postgres:15数据库 +hoppscotch-migrate自动迁移服务。文件注释明确写着 "recommended for most users"，也就是多数自托管用户的首选。
• default-no-db—— 只启动 AIO 一体化容器（注释标注 "purely developmental"，面向使用外部数据库的用户）。它没有depends_on数据库，也不会跑迁移服务。
• just-backend—— 注释为 "All services except webapp for local development"，实际拉起的组合是：hoppscotch-backend（独立后端服务）、hoppscotch-db、hoppscotch-migrate、hoppscotch-sh-admin（管理面板）。不包含hoppscotch-app主应用和 webapp server。

对应的启动命令（与文件注释中的 USAGE 一致）：

# 推荐默认部署：AIO + 数据库 + 自动迁移 docker compose --profile default up # 不启动数据库容器（外部数据库场景） docker compose --profile default-no-db up # 本地开发：除 webapp 外的全部服务 docker compose --profile just-backend up

按部署目标选择 profile

三个 profile 的适用条件可以直接按下面判断：

文件里有两条必须遵守的限制：

1. default与default-no-db不应与单个服务 profile（backend、app、admin等）混用，因为端口会冲突（原注释："should not be mixed with individual service profiles as they would conflict on ports"）。
2. deprecatedprofile 保留旧版服务仅为向后兼容，注释明确 "not recommended for new deployments"，新部署不要选它。

准备 .env 文件

三个 profile 的服务都通过env_file读取仓库根目录的./.env，启动前需要准备这个文件。仓库提供了 .env.example 作为模板，其中与本次部署直接相关的项：

• DATABASE_URL—— 示例值指向 compose 内置的 db 容器postgresql://postgres:testpass@hoppscotch-db:5432/hoppscotch。使用default时保持指向hoppscotch-db即可；使用default-no-db时必须改成你的外部数据库地址。
• DATA_ENCRYPTION_KEY—— 存储到数据库的敏感数据加密密钥，要求 32 个字符。
• VITE_BASE_URL/VITE_ADMIN_URL/VITE_BACKEND_GQL_URL等前端基础地址 —— 示例值均为localhost端口，按你的实际访问地址调整。
• ENABLE_SUBPATH_BASED_ACCESS—— 是否启用子路径访问，默认false。

另外注意docker-compose.yml中hoppscotch-db的POSTGRES_PASSWORD默认为testpass，文件注释直接写着 "NOTE: Please UPDATE THIS PASSWORD!"。如果你按注释去掉了内置 db、改用外部库，compose 注释同时提醒 "make sure to update the .env file as well"，即DATABASE_URL与.env要保持一致。

启动与端口验证

default（以及default-no-db）的hoppscotch-aio容器对宿主机暴露的端口：

3000 主应用 3100 自托管管理面板（sh-admin） 3170 后端 API 3200 webapp bundle server 3080 Caddy 80 端口映射

just-backend下没有hoppscotch-app，所以 3000/3200 不存在；hoppscotch-backend独立服务另暴露3180:80与3170:3170，hoppscotch-sh-admin暴露3280:80与3100:3100，db 容器占用5432。

验证方式仓库里有一份现成的 healthcheck.sh，它展示了各端点的健康检查逻辑：

• 非子路径模式（ENABLE_SUBPATH_BASED_ACCESS非true）时依次检查：http://localhost:3000、http://localhost:3100、http://localhost:3170/ping，判断响应行为HTTP/1.[01] [23]..（即 2xx/3xx）；
• 子路径模式（ENABLE_SUBPATH_BASED_ACCESS=true）时检查http://localhost:${HOPP_AIO_ALTERNATE_PORT:-80}/backend/ping。

你可以按同样的端点手动验证：

# default / default-no-db：AIO 模式下的三个入口 curl -I http://localhost:3000 curl -I http://localhost:3100 curl http://localhost:3170/ping

just-backend场景没有 3000 端点，只验证后端与管理面板：

curl http://localhost:3170/ping curl -I http://localhost:3100

数据库侧，hoppscotch-db配置了 healthcheck（pg_isready -U $POSTGRES_USER -d $POSTGRES_DB，间隔 5s、重试 10 次），default与just-backend中 backend/migrate 容器都声明了condition: service_healthy，即数据库通过健康检查之前后端不会启动。启动初期如果看到容器还在等待，可用docker compose ps查看 db 是否已变为 healthy。

另外default里hoppscotch-migrate是一次性容器，启动命令为sh -c "pnpm exec prisma migrate deploy"，它跑完迁移即退出属于正常现象，不是故障。

边界与注意事项

• default-no-db的注释标注为 "purely developmental"，仓库文档未承诺它是生产级的外部数据库方案；如果按这个路径部署遇到问题，优先核对DATABASE_URL（见 docker-compose.yml 第 43 行注释）与.env是否一致。
• 想换 TLS 或修改应用托管方式，注释指引去看 packages/hoppscotch-selfhost-web/Caddyfile 与 packages/hoppscotch-sh-admin/Caddyfile 中的 Caddyfile。
• 仓库根目录还有 docker-compose.deploy.yml，但它首行注释写明 "THIS IS NOT TO BE USED FOR PERSONAL DEPLOYMENTS!"（仅供内部测试部署使用），个人自托管不要拿它替代docker-compose.yml。

小结

选择逻辑只有一条：要不要内置数据库、要不要 Web 界面。要两者都要、且没有现成 Postgres，选default；已有外部 Postgres，选default-no-db并改DATABASE_URL；只关心后端链路、不启动 webapp，选just-backend。三者共用同一份.env（参照 .env.example）；启动后按上文端点逐一请求，2xx/3xx 即视为对应组件就绪。

【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch