Hopp v1.0.33 配置参数详解

目标：逐一讲清 Hopp 自托管栈的全部配置参数——.env 部署变量、backend 运行时变量、LiveKit 配置文件与 Caddy 路由四层，给出每个参数的默认值、作用与生效验证方法。基于 v1.0.33（backend 镜像 2026-10-17 构建）实测核对，配合《Hopp Docker Compose 部署指南》使用。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• Hopp 版本：v1.0.33（backend 镜像 iparaskev/hopp-backend:v1.0.33）
• 部署形态：官方 selfhost Docker Compose 栈（backend + PostgreSQL 16 + Redis 7 + LiveKit v1.11 + Caddy 2）
• 配置文件：/opt/hopp/selfhost/ 下 .env、livekit.yaml（或 livekit.dev.yaml）、Caddyfile、compose.yml
• 实测项目：hopp-v033-stack，backend 映射 127.0.0.1:8147:1926，LiveKit host 网络 7880
• 仓库基线：commit 2390461f（2026-10-21）

二、前置条件

• 已按部署指南完成栈启动且 curl http://localhost:8147/api/health 返回 OK；
• 熟悉 .env 的修改与重建方式：Compose 部署形态下编辑 .env 后执行 docker compose up -d 重建受影响服务即可生效——Hopp 没有原生二进制形态，配置面即这套文件；
• 保存好首个管理员账号的 JWT（部分参数需调用 API 验证生效值），注册与调用方法见《Hopp v1.0.33 API 使用详解》。

三、参数查看与修改方式

Hopp 的配置分四层，修改入口各不相同：

生效值核验的三种实测手段：

1. 日志核对：backend 启动日志为结构化 JSON，直接打印配置告警，实测启动时可见 RESEND_API_KEY not configured, email notifications will be disabled——邮件参数未生效时这里最有信息量；
2. API 核对：LiveKit 地址下发链路是否正确，调用 GET /api/auth/livekit/server-url 看返回值（见 4.3 节实测）；
3. 行为核对：密码策略、重复注册 409 等参数约束直接用错误请求实测（见 4.1 节）。

四、.env 部署变量详解

4.1 核心部署参数（DOMAIN 与密钥组）

这 6 个键是唯一必填组，实测配置：

DOMAIN=localhost
SESSION_SECRET=XKkKWVGkraR3i18u84xtVwKwefZzENS+ilIy6UJB0rw=
LIVEKIT_API_KEY=457r6TsKLci8qj15fA2X8l6/38fWCGhtek8oe/BEQeE=
LIVEKIT_API_SECRET=H/g2JmUEVPU...（64 字节，此处省略）
POSTGRES_PASSWORD=uqvyHC95CPan6LDx3vcvzvmCRQdx7YTh
LIVEKIT_SERVER_URL=ws://localhost:7880

逐项说明：

LIVEKIT_SERVER_URL 生效链路实测——.env 值被 backend 透传给客户端下发接口：

curl -s http://localhost:8147/api/auth/livekit/server-url -H "Authorization: Bearer $TOKEN"

实测回显：

{"url":"ws://localhost:7880"}

HTTP 200

4.2 版本钉子（HOPP_VERSION）

实测验证（镜像 tag 与发行版同步）：

docker compose ps backend --format '{{.Image}}'

实测回显：

iparaskev/hopp-backend:latest

4.3 邮件参数（RESEND 组）

未配置时实测日志告警（这是确认邮件参数生效与否的权威信号）：

{"level":"WARN","prefix":"echo","file":"server.go","line":"354","message":"RESEND_API_KEY not configured, email notifications will be disabled"}

4.4 OAuth 登录参数（GOOGLE/SLACK/GITHUB 组）

三组均为"空即禁用"语义，自托管最小部署可全部留空，账号密码注册不受影响。OAuth 回调地址由 DOMAIN 派生，改域名时需同步到各 OAuth 应用后台。

4.5 可观测与集成参数（SENTRY/STRIPE/TELEGRAM/SLACK APP 组）

五、backend 运行时变量（compose.yml 注入，一般不改）

以下变量由 compose.yml 的 environment: 段注入 backend，多数由 .env 派生，列出以备排障：

💡 技术拓展：Web 应用后端的 TLS 终结位置常见三种部署取向——① 反代终结（Caddy/nginx 挂证书，后端明文，Hopp 官方栈即此形态）；② 后端自终结（应用直接挂证书，如 Hopp 本地开发模式可开 USE_TLS=true 配合 mkcert 证书）；③ 云 LB 终结（负载均衡器卸载 TLS）。Hopp 官方栈实际采用 ①：Caddy 在 80/443 终结并反代 backend:1926，backend 保持明文，USE_TLS=false。

六、LiveKit 配置文件详解

livekit.yaml（生产）与 livekit.dev.yaml（本地）逐参数对照：

API key 不写在配置文件里，由 compose 以环境变量 LIVEKIT_KEYS: "${LIVEKIT_API_KEY}: ${LIVEKIT_API_SECRET}" 注入。修改配置后 docker compose restart livekit 生效，实测重启后 curl http://localhost:7880/ 仍返回 OK。

💡 技术拓展：LiveKit 的网络连通模式不止"自建 SFU 直连"一种，常见选项对比——

模式	原理	适用场景
自建 SFU（本文形态）	房间媒体经自托管 LiveKit 转发	数据不出内网，可控性最高
LiveKit Cloud	官方托管 SFU，只改 LIVEKIT_SERVER_URL	免运维，跨地域质量好
P2P 直连	参会者互相直连	极小房间省服务器，但绕过 SFU 无录制/转推能力

Hopp 官方自托管栈实际采用"自建 SFU"：媒体面 UDP 50000-60000 直达服务器，信令面经 Caddy（生产）或直连 7880（本地）。

七、Caddyfile 路由详解

生产形态 Caddy 依据 Caddyfile 工作全部路由，实测源文件全文仅两组：

{$DOMAIN} {
    encode zstd gzip
    reverse_proxy backend:1926
}

livekit.{$DOMAIN} {
    reverse_proxy livekit:7880
}

逐行说明：

• {$DOMAIN}：从环境变量取域名（compose 注入），站点级默认路由——所有主域请求反代到 backend 的 1926，Web 前端与 REST API 同源；
• encode zstd gzip：响应压缩。官方注释说明 Web 端是单个大 HTML 文件（实测 GET / 返回 3016424 字节），压缩后下载体积约减半；
• livekit.{$DOMAIN}：LiveKit 信令子域，把 wss://livekit.<域名> 的 WebSocket 升级请求反代到 LiveKit 7880；
• TLS 证书：Caddy 对上述域名自动签发续期 Let's Encrypt 证书，数据存 caddy_data 卷，无任何手工证书步骤。

八、生产配置模板

场景 A：5 人以内小团队，单服务器 2 vCPU / 4GB 内存 / NVMe SSD（内网或小规模远程结对）：

DOMAIN=hopp.example.com
SESSION_SECRET=<openssl rand -base64 32 | tr -d '\n'>
LIVEKIT_API_KEY=<openssl rand -base64 32 | tr -d '\n'>
LIVEKIT_API_SECRET=<openssl rand -base64 64 | tr -d '\n'>
POSTGRES_PASSWORD=<openssl rand -base64 24 | tr -d '\n'>
HOPP_VERSION=v1.0.33

LIVEKIT_SERVER_URL 留空走默认（wss://livekit.<域名>）；邮件、OAuth 按需追加。此规模下全部服务单机混部即可满足 2-4 人同时结对（10 人房间为官方上限）。

场景 B：跨地域团队、追求媒体质量，4 vCPU / 8GB 内存：同上，另将 livekit.yaml 的 rtc 段保持 50000-60000 全段，确认防火墙全放行；仍不够时把 LIVEKIT_SERVER_URL 指向 LiveKit Cloud，服务器只承担业务面，媒体面交给托管 SFU。

两套模板共同点：密钥全部 openssl 生成、版本显式钉住；差异点只在媒体面归属与端口段策略。

九、常见问题（FAQ）

Q1：改了 .env 但行为没变化？ 环境变量只在新进程里生效，重建对应服务：docker compose up -d backend（或全部 docker compose up -d）。只 restart 不会重新读取 compose 配置中的变量替换——这是 .env 参数不生效最常见的原因。验证手段见第三节三种实测核对法。

Q2：DOMAIN 从 localhost 换成正式域名要改哪些地方？ 仅 .env 的 DOMAIN（必要时清空/改写 LIVEKIT_SERVER_URL），重建 db 之外的各服务即可；浏览器端 Cookie 与新会话会跟随新域名。已在 localhost 注册的账号数据不受影响（存于 db_data 卷）。

Q3：POSTGRES_PASSWORD 换了之后连不上数据库？ 口令进的是数据库初始化（首次建库），db_data 卷里旧口令已固化。要么恢复旧口令，要么接受数据重来：docker compose down -v 后用新口令全新初始化。

Q4：本地形态能开 TLS 吗？ 可以但没必要走 Caddy。官方本地开发路径是 backend 自终结 TLS（USE_TLS=true + mkcert 生成本地证书并挂载，task create-certs），本地验证 HTTP 明文即可；生产一律走 Caddy 终结。

Q5：怎么确认当前的 LiveKit 鉴权对是哪一把？ 对比 .env 与 docker compose exec livekit env | grep LIVEKIT_KEYS 的值是否同源一致；客户端侧以 GET /api/auth/livekit/server-url 返回 200 且 Web 端能进房为准。

十、参考链接

• 官方自托管文档：https://docs.gethopp.app/open-source/self-hosting/
• selfhost 编排与配置文件：https://github.com/gethopp/hopp/tree/main/selfhost
• LiveKit 官方文档：https://docs.livekit.io/
• 站内进阶：《Hopp Docker Compose 部署指南》、《Hopp v1.0.33 API 使用详解》、《Hopp 介绍与选型指南》