HTTPS 与回调

为什么需要

• 控制台登录和 Hub Key 走明文 HTTP 会被窃听，公网部署请放在 HTTPS 后面。
• AssemblyAI 回调需要一个它能访问到的地址（PUBLIC_BASE_URL）。没有回调时任务靠轮询更新，会有最多 POLL_INTERVAL 秒的延迟。

反向代理示例

Caddy

hub.example.com {
    reverse_proxy 127.0.0.1:18080
}

Caddy 会自动申请证书，WebSocket 无需额外配置。

Nginx

server {
    listen 443 ssl http2;
    server_name hub.example.com;
    # ssl_certificate / ssl_certificate_key ...

    client_max_body_size 2g;          # 与 MAX_UPLOAD_MB 保持一致
    proxy_read_timeout 600s;          # 大文件上传与实时中继
    proxy_send_timeout 600s;
    proxy_request_buffering off;      # 上传边收边转

    location / {
        proxy_pass http://127.0.0.1:18080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;     # /v3/ws 中继
        proxy_set_header Connection "upgrade";
    }
}

Hub 以 --proxy-headers 启动，会识别 X-Forwarded-* 头。

配置回调

PUBLIC_BASE_URL=https://hub.example.com
WEBHOOK_SECRET=<固定的随机字符串>

设置后：

1. Hub 提交转写时把 webhook_url 设为 https://hub.example.com/internal/aai-webhook，鉴权头为 X-Hub-Webhook: <WEBHOOK_SECRET>。
2. AssemblyAI 完成任务后回调 Hub，Hub 立即刷新任务状态并记录用量。
3. 如果客户端提交时带了自己的 webhook_url（以及可选的 webhook_auth_header_name / webhook_auth_header_value），任务完成或失败后 Hub 会转发给它，请求体与 AssemblyAI 的回调一致：{"transcript_id": "...", "status": "completed"}。遇到网络错误或 5xx 时每 10 秒重试，最多 5 次。

客户端回调不依赖 PUBLIC_BASE_URL：没有设置时，轮询发现任务结束后同样会转发。

/internal/aai-webhook 只接受带正确鉴权头的请求，不需要对外隐藏。