Hoppscotch Docker Compose 部署指南

目标：从 0 到 1 完成开源 API 开发生态 Hoppscotch 社区版（2026.9.0）的 Docker Compose 自托管部署——编排文件编写、数据库迁移、管理员注册、集合/环境实操、数据持久化验证与常见报错排障。本文所有命令与回显均在 Ubuntu 22.04 服务器上实测运行，组件选型与产品定位见《Hoppscotch 2026.9.0 介绍与选型指南》。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Hoppscotch：2026.9.0（官方最新稳定版，2026-09-30 发布，镜像 hoppscotch/hoppscotch:2026.9.0）
数据库：PostgreSQL 15（官方 compose 示例所用版本）
编排工具：Docker + Docker Compose v2
部署目录：/opt/data/ops/hoppscotch（docker-compose.yml、.env、数据目录 data/ 均在此）
服务端口规划：8141（主应用 3000）、8142（管理台 3100）、8143（后端 API 3170）、8144（bundle server 3200）、8145（mailpit 收信台 8025）
演示账号：管理员邮箱 admin@example.com，数据库口令 q1w2e3r4

二、发行形态与版本选型

Hoppscotch 官方提供两种自托管打包形态（Docker Hub 官方源，2026-10-20 实查）：

形态	镜像	说明
AIO 单服务	`hoppscotch/hoppscotch`	一个服务内同时运行主应用（3000）、管理台（3100）、后端 API（3170）、bundle server（3200），官方 compose 默认形态
分立三服务	`hoppscotch/hoppscotch-frontend` / `-backend` / `-admin`	前端/后端/管理台各自独立扩缩，适合大规模部署

💡 说明：本指南采用官方默认的 AIO 形态——中小规模团队自托管运维面最小，一个服务即含全部应用进程；数据层单独使用 PostgreSQL 15。官方发行件同时内置一条独立的数据库迁移服务（prisma migrate deploy），每次启动先于应用执行、保证库表结构就绪。

另外引入一个可选用途组件 mailpit（axllent/mailpit）：本地 SMTP 收信台，用于在没有真实邮件服务器时承接 Hoppscotch 的登录验证邮件——社区版登录强依赖邮件（Magic Link），这是自托管首日的关键配套。生产环境应替换为真实 SMTP（在管理台引导流程中配置）。

三、前置条件

服务器已安装 Docker 与 Docker Compose v2；
端口规划：宿主机 8141-8145 五个端口空闲（可按需改映射，容器侧 3000/3100/3170/3200/8025 固定）；
数据库必配：Hoppscotch 将全部集合、环境、团队、用户数据存于 PostgreSQL，官方前置条件文档明确要求提供连接串；
邮件必配：社区版登录采用 Magic Link 邮件验证码模式，部署时需同步准备 SMTP（本指南用 mailpit 承接演示）。

⚠️ 注意：官方明确建议生产环境启用 HTTPS——登录凭证依赖安全 Cookie 传递，纯 HTTP 环境仅建议用于内网验证与学习。

四、部署步骤

4.1 创建部署目录

mkdir -p /opt/data/ops/hoppscotch/data/db
cd /opt/data/ops/hoppscotch

4.2 编写 docker-compose.yml

创建 docker-compose.yml，内容如下（已实测可用的完整编排文件）：

name: hoppscotch-2026-9-0-stack

services:
  hoppscotch-db:
    image: postgres:15
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: q1w2e3r4
      POSTGRES_DB: hoppscotch
    volumes:
      - ./data/db:/var/lib/postgresql/data
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "sh -c 'pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}'",
        ]
      interval: 5s
      timeout: 5s
      retries: 10
    networks:
      - hoppscotch-net

  hoppscotch-migrate:
    image: hoppscotch/hoppscotch:2026.9.0
    restart: "no"
    env_file:
      - ./.env
    depends_on:
      hoppscotch-db:
        condition: service_healthy
    command: sh -c "pnpm exec prisma migrate deploy"
    networks:
      - hoppscotch-net

  hoppscotch-aio:
    image: hoppscotch/hoppscotch:2026.9.0
    restart: unless-stopped
    env_file:
      - ./.env
    depends_on:
      hoppscotch-db:
        condition: service_healthy
      hoppscotch-migrate:
        condition: service_completed_successfully
    ports:
      - "8141:3000"
      - "8142:3100"
      - "8143:3170"
      - "8144:3200"
    networks:
      - hoppscotch-net

  hoppscotch-mailpit:
    image: axllent/mailpit:v1.31.6
    restart: unless-stopped
    ports:
      - "8145:8025"
    networks:
      - hoppscotch-net

networks:
  hoppscotch-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.57.0/24

编排设计要点：

显式项目名：name: hoppscotch-2026-9-0-stack——同一台服务器上多个 compose 项目同名会造成 down 误删他栈，必须显式唯一命名；
迁移服务一次跑：hoppscotch-migrate 复用 AIO 镜像、restart: "no"，只负责 prisma migrate deploy，通过 service_completed_successfully 让应用服务等它跑完再启动；
数据库不对外映射端口：PostgreSQL 仅在内部网络供应用访问，避免暴露到宿主机（需要外部管理时再临时加映射）；
mailpit 一物两用：SMTP 端口 1025 仅供内部网络使用，8025 映射到宿主机 8145 供浏览器查看收件箱。

4.3 编写 .env 环境配置

创建 .env（迁移与应用服务都会读取），内容如下：

DATABASE_URL=postgresql://postgres:q1w2e3r4@hoppscotch-db:5432/hoppscotch?connect_timeout=300
DATA_ENCRYPTION_KEY=hoppscotch-demo-encryption-key32
WHITELISTED_ORIGINS=http://localhost:8143,http://localhost:8141,http://localhost:8142,app://localhost_3200,app://hoppscotch
PROXY_APP_URL="https://proxy.hoppscotch.io"
TRUST_PROXY=false
VITE_BASE_URL=http://localhost:8141
VITE_SHORTCODE_BASE_URL=http://localhost:8141
VITE_ADMIN_URL=http://localhost:8142
VITE_BACKEND_GQL_URL=http://localhost:8143/graphql
VITE_BACKEND_WS_URL=ws://localhost:8143/graphql
VITE_BACKEND_API_URL=http://localhost:8143/v1
VITE_APP_TOS_LINK=https://docs.hoppscotch.io/support/terms
VITE_APP_PRIVACY_POLICY_LINK=https://docs.hoppscotch.io/support/privacy
VITE_PROXYSCOTCH_ACCESS_TOKEN=
ENABLE_SUBPATH_BASED_ACCESS=false

关键项解读：

DATABASE_URL：连接串中主机名 hoppscotch-db 即 compose 服务名（内部 DNS 解析），密码与 docker-compose.yml 中 POSTGRES_PASSWORD 保持一致；
DATA_ENCRYPTION_KEY：实例级加密密钥，必须恰好 32 个字符，用于加密库内 OAuth/SMTP 等敏感配置，设定后不要随意变更（否则已入库密文无法解密）；
WHITELISTED_ORIGINS：后端 API 的 CORS 白名单，按实际对外端口逐项列出；
VITE_* 系列：前端启动时烘焙进页面产物的各入口地址，与宿主机端口一一对应，改动后必须重建服务（见 8.4）；
ENABLE_SUBPATH_BASED_ACCESS=false：默认多端口模式；设为 true 时收口为单端口子路径模式（管理台挂 /admin、后端挂 /backend）。

4.4 首次启动

cd /opt/data/ops/hoppscotch
docker compose up -d

实测回显（全新空库首启，编排按「数据库健康 → 迁移执行完成 → 应用启动」的依赖链自动拉起）：

 Network hoppscotch-2026-9-0-stack_hoppscotch-net Creating
 Network hoppscotch-2026-9-0-stack_hoppscotch-net Created
 Container hoppscotch-2026-9-0-stack-hoppscotch-db-1 Creating
 Container hoppscotch-2026-9-0-stack-hoppscotch-mailpit-1 Creating
 Container hoppscotch-2026-9-0-stack-hoppscotch-mailpit-1 Created
 Container hoppscotch-2026-9-0-stack-hoppscotch-db-1 Created
 Container hoppscotch-2026-9-0-stack-hoppscotch-migrate-1 Creating
 Container hoppscotch-2026-9-0-stack-hoppscotch-migrate-1 Created
 Container hoppscotch-2026-9-0-stack-hoppscotch-aio-1 Creating
 Container hoppscotch-2026-9-0-stack-hoppscotch-aio-1 Created
 Container hoppscotch-2026-9-0-stack-hoppscotch-mailpit-1 Starting
 Container hoppscotch-2026-9-0-stack-hoppscotch-db-1 Starting
 Container hoppscotch-2026-9-0-stack-hoppscotch-mailpit-1 Started
 Container hoppscotch-2026-9-0-stack-hoppscotch-db-1 Started
 Container hoppscotch-2026-9-0-stack-hoppscotch-db-1 Waiting
 Container hoppscotch-2026-9-0-stack-hoppscotch-db-1 Healthy
 Container hoppscotch-2026-9-0-stack-hoppscotch-migrate-1 Starting
 Container hoppscotch-2026-9-0-stack-hoppscotch-migrate-1 Started
 Container hoppscotch-2026-9-0-stack-hoppscotch-db-1 Waiting
 Container hoppscotch-2026-9-0-stack-hoppscotch-migrate-1 Waiting
 Container hoppscotch-2026-9-0-stack-hoppscotch-db-1 Healthy
 Container hoppscotch-2026-9-0-stack-hoppscotch-migrate-1 Exited
 Container hoppscotch-2026-9-0-stack-hoppscotch-aio-1 Starting
 Container hoppscotch-2026-9-0-stack-hoppscotch-aio-1 Started

查看迁移服务日志（首启会逐条应用全部库表迁移）：

docker compose logs hoppscotch-migrate

实测回显（首启完整 Applying 列表，中间的已应用清单树与 Applying 列表重复，此处以 ⋯ 略去）：

Loaded Prisma config from prisma.config.ts.

Prisma schema loaded from prisma/schema.prisma.
Datasource "db": PostgreSQL database "hoppscotch", schema "public" at "hoppscotch-db:5432"

22 migrations found in prisma/migrations

Applying migration `20230406064219_init`
Applying migration `20231106120154_embeds_addition`
Applying migration `20231124104640_infra_config`
Applying migration `20231130082054_collection_headers`
Applying migration `20240226053141_full_text_search_additions`
Applying migration `20240519093155_add_last_logged_on_to_user`
Applying migration `20240520091033_personal_access_tokens`
Applying migration `20240621062554_user_last_active_on`
Applying migration `20240725043411_infra_config_encryption`
Applying migration `20240726121956_infra_token`
Applying migration `20241118054346_infra_config_sync_with_env_file`
Applying migration `20250306054346_team_access_role_enum`
Applying migration `20250725154928_timestamp_with_timezone`
Applying migration `20250818154928_fix_order_index`
Applying migration `20250822044741_order_index_unique_constraint`
Applying migration `20251016080714_mock_server`
Applying migration `20251110141554_api_doc`
Applying migration `20251202154928_fix_order_index`
Applying migration `20251203202452_cascade_delete`
Applying migration `20251207122817_add_slug_to_published_docs`
Applying migration `20260209063744_published_doc_environment`
Applying migration `20260713090000_mock_server_gql_examples`

⋯（中间为 22 条迁移的已应用清单树，内容与上表一一对应）

All migrations have been successfully applied.

确认各服务状态：

docker compose ps

实测回显（AIO 内置健康检查就绪后为 healthy）：

NAME                                             IMAGE                            COMMAND                   SERVICE              CREATED              STATUS                        PORTS
hoppscotch-2026-9-0-stack-hoppscotch-aio-1       hoppscotch/hoppscotch:2026.9.0   "tini -- node /usr/s…"   hoppscotch-aio       About a minute ago   Up 55 seconds (healthy)       80/tcp, 0.0.0.0:8141->3000/tcp, [::]:8141->3000/tcp, 0.0.0.0:8142->3100/tcp, [::]:8142->3100/tcp, 0.0.0.0:8143->3170/tcp, [::]:8143->3170/tcp, 0.0.0.0:8144->3200/tcp, [::]:8144->3200/tcp
hoppscotch-2026-9-0-stack-hoppscotch-db-1        postgres:15                      "docker-entrypoint.s…"   hoppscotch-db        About a minute ago   Up About a minute (healthy)   5432/tcp
hoppscotch-2026-9-0-stack-hoppscotch-mailpit-1   axllent/mailpit:v1.31.6          "/mailpit"                hoppscotch-mailpit   About a minute ago   Up About a minute (healthy)   1025/tcp, 1110/tcp, 0.0.0.0:8145->8025/tcp, [::]:8145->8025/tcp

💡 说明：迁移服务是幂等的一次性任务，二次启动会重跑但直接跳过——实测回显为 22 migrations found in prisma/migrations + No pending migrations to apply.，属正常现象。

4.5 验证部署

逐端口验证四个服务入口：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8141/   # 主应用
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8142/   # 管理台
curl -s http://localhost:8143/ping                                # 后端 API 健康检查

实测回显：

200
200
Success

浏览器打开 http://localhost:8141 应看到主应用标题 Hoppscotch • Open source API development ecosystem，打开 http://localhost:8142 应看到管理台标题 Hoppscotch Admin。8144（bundle server，3200 端口）只服务前端分包资源路径，直接访问根路径返回 404 属正常。

五、管理员注册与 SMTP 初始化

社区版登录为 Magic Link 邮件模式，首次使用前需完成两件事：配置 SMTP 投递通道、用首个邮箱注册管理员。

第 1 步：写入 SMTP 引导配置。 管理台尚未初始化时，后端开放引导接口可直接写入实例级 SMTP 配置（存入数据库基础设施配置表）：

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"}

字段说明：VITE_ALLOWED_AUTH_PROVIDERS 为认证提供方白名单（EMAIL/GITHUB/GOOGLE/MICROSOFT 可多选）；MAILER_SMTP_URL 指向 mailpit 的内部 SMTP 端口 1025（生产环境替换为真实 SMTP，如 smtps://user:pass@smtp.domain.com）；MAILER_ADDRESS_FROM 为发件人地址。

第 2 步：重启应用服务使邮件模块生效（mailer 模块在启动时装载 SMTP transport，改库配置后需重建）：

docker compose up -d --force-recreate hoppscotch-aio

第 3 步：请求登录邮件：

curl -s -X POST 'http://localhost:8143/v1/auth/signin?origin=admin' \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com"}'

实测回显（返回本次会话的设备标识，验证时需原样回传）：

{"deviceIdentifier":"$2b$10$Dg42FC/UCx.MXhbd6HEGO."}

第 4 步：查看收件箱并取出魔法链接。 浏览器打开 mailpit 收信台 http://localhost:8145，应看到主题为 Sign in to Hoppscotch 的邮件，正文含形如 http://localhost:8142/enter?token=<令牌> 的登录链接。也可用其 API 直接读取：

curl -s http://localhost:8145/api/v1/messages

实测回显（节选关键字段）：

"total": 1,
"messages": [
    {
        "ID": "1D9JA5ZuiKO1ZLjrO8RSPT",
        "From": { "Address": "hoppscotch@localhost.local" },
        "To": [ { "Address": "admin@example.com" } ],
        "Subject": "Sign in to Hoppscotch",
        ...

第 5 步：验证令牌换取登录态（用第 3 步的 deviceIdentifier 与邮件中的 token）：

curl -s -D headers.txt -X POST http://localhost:8143/v1/auth/verify \
  -H 'Content-Type: application/json' \
  -d '{"deviceIdentifier":"$2b$10$Dg42FC/UCx.MXhbd6HEGO.","token":"<邮件中的令牌>"}'

实测回显：HTTP 200，响应头下发 Set-Cookie: access_token=… 与 Set-Cookie: refresh_token=… 两枚 HttpOnly 会话凭证（有效期 7 天）。

第 6 步：首个用户自动提升管理员。 携带登录态访问管理台验证接口（或在管理台页面完成登录）：

curl -s -H "Cookie: <access_token=…; refresh_token=…>" http://localhost:8143/v1/auth/verify/admin

实测回显：

{"isAdmin":true}

💡 说明：官方约定「经管理台登录的首个用户自动成为管理员」——库里用户数为 1 时该接口即完成提权。等价的图形操作路径是：浏览器打开 http://localhost:8142，输入邮箱 → 从 mailpit 点开魔法链接 → 回到管理台即以管理员身份进入。后续用户经主应用 8141 注册，由管理员在管理台分配团队。

六、功能实操验证

登录后即可在主应用（8141）中使用 REST/GraphQL 调试工作台。本节用后端 GraphQL API 做一轮可复核的实操链路（个人集合 → 请求 → 环境 → 导出），验证实例功能完整；界面操作与 API 等价。

以下调用均携带第五章取得的登录态 Cookie。

6.1 创建个人集合与请求：

# 创建根集合
curl -s -X POST http://localhost:8143/graphql \
  -H 'Content-Type: application/json' -H "Cookie: $COOKIE" \
  -d '{"query":"mutation($t: String!) { createRESTRootUserCollection(title: $t) { id title } }","variables":{"t":"Demo API"}}'

实测回显：

{"createRESTRootUserCollection":{"id":"cmvh16hs200030qpf6p8bm6am","title":"Demo API"}}

# 向集合写入一个带测试脚本的请求（auth 必须为对象形态）
curl -s -X POST http://localhost:8143/graphql \
  -H 'Content-Type: application/json' -H "Cookie: $COOKIE" \
  -d '{"query":"mutation($c: ID!, $t: String!, $r: String!) { createRESTUserRequest(collectionID: $c, title: $t, request: $r) { id } }","variables":{"c":"cmvh16hs200030qpf6p8bm6am","t":"Health Check","r":"{\"v\":\"1\",\"name\":\"Health Check\",\"method\":\"GET\",\"endpoint\":\"<<baseUrl>>/ping\",\"params\":[],\"headers\":[{\"key\":\"Accept\",\"value\":\"application/json\",\"active\":true}],\"auth\":{\"authType\":\"none\",\"authActive\":true},\"body\":{\"contentType\":null,\"body\":null},\"testScript\":\"pw.expect(pw.response.status).toBe(200);\\npw.expect(pw.response.body.trim()).toBe('"'"'Success'"'"');\"}"}}'

实测回显：

{"createRESTUserRequest":{"id":"cmvh16hse00040qpf0fwazl8i"}}

6.2 创建个人环境（variables 为变量数组的 JSON 字符串）：

curl -s -X POST http://localhost:8143/graphql \
  -H 'Content-Type: application/json' -H "Cookie: $COOKIE" \
  -d '{"query":"mutation($n: String!, $v: String!) { createUserEnvironment(name: $n, variables: $v) { id name } }","variables":{"n":"Local Env","v":"[{\"key\":\"baseUrl\",\"value\":\"http://localhost:8143\",\"secret\":false}]"}}'

实测回显：

{"createUserEnvironment":{"id":"cmvh16v2w00050qpfetm2cx62","name":"Local Env"}}

6.3 导出集合 JSON（请求中 <<baseUrl>> 变量将解析为环境值）：

curl -s -X POST http://localhost:8143/graphql \
  -H 'Content-Type: application/json' -H "Cookie: $COOKIE" \
  -d '{"query":"query { exportUserCollectionsToJSON(collectionType: REST) { exportedCollection collectionType } }"}'

实测回显（exportedCollection 为 JSON 字符串，格式化后）：

[
  {
    "id": "cmvh16hs200030qpf6p8bm6am",
    "name": "Demo API",
    "folders": [],
    "requests": [
      {
        "v": "1",
        "name": "Health Check",
        "method": "GET",
        "endpoint": "<<baseUrl>>/ping",
        ...
      }
    ]
  }
]

💡 技术拓展：导出的集合 JSON 是标准交换格式，可直接交给官方 CLI hopp test 无头执行（CI 场景），详见《Hoppscotch 常用 CLI 命令与工具详解》。请求 JSON 中 auth 字段必须为对象形态（{"authType":"none","authActive":true}），写成旧版字符串 "none" 会被 CLI 校验拒绝。

七、数据持久化与日常运维

7.1 持久化设计

业务数据：全部存于 PostgreSQL，落盘路径为宿主机目录 ./data/db（bind mount），服务重建/升级不丢数据；
实例配置：SMTP/OAuth 等管理台引导配置存于数据库基础设施配置表，随库持久化；
邮件：mailpit 未挂数据卷，属演示用临时收件箱，重启后清空（生产环境使用真实 SMTP，不存在此问题）。

7.2 整栈重启持久化实测

执行完整下栈再拉起（down 会移除服务与网络但保留 bind mount 数据目录）：

docker compose down && docker compose up -d

等待健康后核验数据存活：

docker compose exec hoppscotch-db psql -U postgres -d hoppscotch \
  -c "SELECT (SELECT COUNT(*) FROM \"User\") AS users, (SELECT COUNT(*) FROM \"UserCollection\") AS collections, (SELECT COUNT(*) FROM \"UserEnvironment\") AS environments;"

实测回显（重启前后一致）：

 users | collections | environments
-------+-------------+--------------
     1 |           1 |            1
(1 row)

再走一遍登录流程（signin → 邮件魔法链接 → verify），实测 HTTP 200 正常发放新会话——账号、集合、环境全部存活，持久化闭环验证通过。

7.3 日常运维命令速查

docker compose ps                                # 各服务状态（healthy 为就绪）
docker compose logs -f hoppscotch-aio            # 跟踪应用日志
docker compose restart hoppscotch-aio            # 仅重启应用服务（不重读 .env）
docker compose up -d                             # 配置变更后应用（重建受影响服务）
docker compose down                              # 停栈并移除服务/网络（数据目录保留）
docker compose down -v                           # 连同匿名数据卷清除（bind mount 不受影响）

⚠️ 注意：docker compose restart 不会重读 .env——环境变量在服务创建时注入，改配置后必须用 docker compose up -d 重建。此差异在实测中对 VITE_* 前端地址类配置影响显著，详见 8.4。

八、常见问题（排障实录）

8.1 启动报「address already in use」（宿主机端口被占）

现象：docker compose up -d 时数据库服务启动失败，报错含：

Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint hoppscotch-...: Bind for 0.0.0.0:5432 failed: port is already allocated

定位：宿主机 5432 已被其他 PostgreSQL 实例占用（官方示例 compose 默认给数据库加了端口映射，撞上宿主已有服务）。

解决：删除 hoppscotch-db 的 ports 映射（如本指南 4.2 的编排），数据库只在内部网络供应用访问，无需对外暴露。同理，四个应用端口的映射值（8141-8144）都可改成宿主机任意空闲端口，容器侧端口不变。

8.2 数据库反复重启、日志报权限错误

现象：数据库服务 unhealthy，日志报 initdb 阶段对数据目录 chmod 失败（Operation not permitted）。

定位：官方示例 compose 为数据库服务配置了 user: postgres，而 bind mount 的宿主数据目录属主为 root，非 root 用户无权改属主。

解决：移除 user: postgres 配置，让数据库官方入口脚本自行处理降权逻辑，清空数据目录后重新 up -d 即可正常初始化。

8.3 登录时收不到验证邮件

现象：管理台/主应用输入邮箱后页面无报错，但收件箱始终没有邮件。

定位：邮件服务在 MAILER_SMTP_ENABLE 未开启时静默跳过投递——应用日志无错误、接口正常返回，令牌只随邮件发放，登录流程无法走通。这是社区版首次部署最常见的卡点。

解决：按第五章第 1 步先完成 SMTP 引导配置（或经管理台引导页配置），再 docker compose up -d --force-recreate hoppscotch-aio 重建应用服务，之后登录邮件正常送达。生产环境务必配置真实 SMTP 并保管好引导恢复令牌。

8.4 修改 .env 后配置不生效

现象：修改 .env（尤其是 VITE_* 前端地址系列）后执行 docker compose restart，页面仍显示旧地址。

定位：环境变量在服务创建时注入；VITE_* 系列更是在启动流程中烘焙进前端产物，restart 只重启进程、不重读环境。

解决：改完 .env 后执行 docker compose up -d（compose 会检测到配置变更并自动重建受影响服务），重建后新配置生效。

九、参考链接

官方自托管文档（Community Edition）：https://docs.hoppscotch.io/documentation/self-host/community-edition/getting-started
官方前置条件（PostgreSQL/SMTP/端口布局）：https://docs.hoppscotch.io/documentation/self-host/community-edition/prerequisites
官方安装与构建（三种部署形态）：https://docs.hoppscotch.io/documentation/self-host/community-edition/install-and-build
官方 compose 示例与 .env.example：https://github.com/hoppscotch/hoppscotch
AIO 镜像 tag 列表：https://hub.docker.com/r/hoppscotch/hoppscotch/tags
mailpit（本地 SMTP 收信台）：https://github.com/axllent/mailpit
本专栏姊妹篇：《Hoppscotch 2026.9.0 介绍与选型指南》《Hoppscotch 2026.9.0 配置参数详解》《Hoppscotch 常用 CLI 命令与工具详解》