部署形态
OmniGate 是单进程、单二进制服务,管理台与代理共用一个端口(默认 17777)。
前台运行
适合调试和容器前台进程:
omnigate start --foreground
日志默认同时写 ~/.omnigate/omnigate.log,也可以 --log stdout 只输出到终端。Ctrl+C 停止。
后台守护
默认命令就是后台启动:
omnigate start
omnigate status
omnigate restart
omnigate stop
守护进程会写 PID 文件,status / stop / restart 按 PID 文件找到实例。需要长期运行建议再配 开机自启,而不是依赖手工 start。
监听地址
默认只监听 127.0.0.1。需要局域网、容器或反向代理访问时,在启动层配置里改:
server:
host: 0.0.0.0
port: 17777
改完需要重启。详见 启动层配置。
反向代理
Nginx / Caddy / Traefik 都可以放在前面。注意三点:
- SSE 不能缓冲:
/v1/*的流式响应要关闭代理缓冲,并放宽读超时 - 上传体积:
/v1/audio/transcriptions是 multipart,按 STT 上传上限配置client_max_body_size - 真实 IP:如果依赖访问日志,按代理设置转发
X-Forwarded-For
Nginx 关键片段:
location /v1/ {
proxy_pass http://127.0.0.1:17777;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_buffering off;
proxy_read_timeout 3600s;
client_max_body_size 32m;
}
location / {
proxy_pass http://127.0.0.1:17777;
proxy_set_header Host $host;
}
管理台和门户都在同一端口下,/manage 与 /portal 不需要单独的反向代理规则。
多入口与多实例
一个实例 = 一个数据库。需要多个入口共享配置、熔断、用量和日志时,把数据库换成 MySQL / PostgreSQL,见 数据库后端。
不要用 SQLite 文件放在共享盘上模拟共享:每个进程各持一份连接和 WAL,结果不可预期。
容器
官方不提供 Docker 镜像,但单二进制适合直接作为容器入口:
FROM gcr.io/distroless/static-debian12
COPY omnigate /omnigate
ENTRYPOINT ["/omnigate", "start", "--foreground", "--config", "/etc/omnigate/config.yaml"]
需要把数据库和配置目录挂载为卷;容器内通常把 server.host 设为 0.0.0.0。