安装部署
反向代理与 HTTPS
Nginx / Caddy 配置示例, 含 SSE 与超时建议
Imagic 后端默认监听 :8080, 同时承担前端静态文件 + /api/* + /data/*。
生产环境建议在前面挂反向代理 (Nginx / Caddy / Traefik 任意), 由代理负责 HTTPS 与域名路由。
关键约束
- 异步生图走 SSE (Server-Sent Events), 代理必须关闭响应缓冲
- 单次 SSE 连接可能持续 1-2 分钟, 代理
proxy_read_timeout要给足 - 单图上传上限 10 MB, body 大小上限要 ≥ 12 MB 留余量
- 后端不感知 HTTPS, cookie 的
Secure由后端读X-Forwarded-Proto决定; 反代必须 正确转发该 header
Nginx 配置示例
upstream imagic_backend {
server 127.0.0.1:8080;
keepalive 32;
}
server {
listen 80;
server_name imagic.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name imagic.example.com;
ssl_certificate /etc/letsencrypt/live/imagic.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/imagic.example.com/privkey.pem;
client_max_body_size 12m;
# SSE 路径单独配置: 关缓冲, 长超时
location ~ ^/(api/v1/(generations/[^/]+/stream|images/(generate|edit)/stream))$ {
proxy_pass http://imagic_backend;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 300s;
proxy_send_timeout 300s;
chunked_transfer_encoding on;
}
# 其它请求
location / {
proxy_pass http://imagic_backend;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 120s;
}
}要点:
proxy_buffering off必须写在 SSE location 里, 否则前端收不到 partial 帧, 看起来像生图卡住proxy_read_timeout 300s给文生图留足时间, 上游慢渠道可能需要 60-120s 出图client_max_body_size 12m配合后端MaxBytesReader上限X-Forwarded-Proto $scheme让后端正确判定是否设Securecookie
Caddy 配置示例
Caddy 默认会自动签 Let's Encrypt 证书, 配置极简:
imagic.example.com {
encode gzip
# SSE 路径关闭 flush 阈值
@sse path_regexp sse ^/api/v1/(generations/[^/]+/stream|images/(generate|edit)/stream)$
reverse_proxy @sse 127.0.0.1:8080 {
flush_interval -1
transport http {
read_timeout 300s
}
}
reverse_proxy 127.0.0.1:8080 {
transport http {
read_timeout 120s
}
}
}flush_interval -1 是 Caddy 关闭 SSE 缓冲的写法, 等价于 Nginx 的 proxy_buffering off。
Traefik (docker labels)
如果你用 Traefik + docker labels, 在 imagic 服务下加:
services:
imagic:
labels:
- "traefik.enable=true"
- "traefik.http.routers.imagic.rule=Host(`imagic.example.com`)"
- "traefik.http.routers.imagic.entrypoints=websecure"
- "traefik.http.routers.imagic.tls.certresolver=letsencrypt"
- "traefik.http.services.imagic.loadbalancer.server.port=8080"Traefik v2 默认不缓冲 SSE, 不需要额外配置; 但 serversTransport.forwardingTimeouts.responseHeaderTimeout
默认 0 (不限) 或 60s, 注意检查全局配置。
健康检查
反向代理可以挂在 /api/v1/health 上做存活探测:
curl https://imagic.example.com/api/v1/health
# 期望: {"code":200,"data":{"status":"ok"},"msg":"ok"}该接口不走 License 校验, 不计入限流, 任何状态下都应返回 200。