企业官网建设流程全解析

• 人工智能
• LLM 网关
• API网关
• 后端

Bifrost 是一款高性能 AI 网关，通过统一的 OpenAI 兼容 API 汇聚多家模型提供商，并提供负载均衡、故障转移等企业级能力。本文围绕仓库中的examples/configs/withnginxreverseproxy示例，完整讲解如何将 3 个 Bifrost 节点部署在 NGINX 反向代理之后，涵盖 Docker Compose 与 Kubernetes/Helm 两条落地路径。读完本文，你将掌握反向代理的关键配置（流式响应、WebSocket、超时、负载均衡策略）、共享配置与环境变量注入方式，以及用curl验证网关健康状态与推理链路的方法。

示例目录结构与文件职责

示例位于仓库的 examples/configs/withnginxreverseproxy 目录，包含 6 个文件，职责清晰：

整体拓扑为：客户端请求统一打到 NGINX（宿主机8080端口），NGINX 按负载均衡策略将请求分发到 3 个仅暴露容器内8080端口的 Bifrost 节点，3 个节点共享同一份config.json，从而形成水平扩展的多节点网关集群。

Docker Compose：三节点网关 + NGINX 反向代理

docker-compose.yml 定义了 4 个服务，结构如下：

services: nginx: image: nginx:alpine container_name: bifrost-nginx ports: - "8080:80" # 对外唯一入口 volumes: - ./nginx.conf:/etc/nginx/nginx.conf:ro depends_on: - bifrost-1 - bifrost-2 - bifrost-3 restart: unless-stopped bifrost-1: # bifrost-2 / bifrost-3 结构相同 image: maximhq/bifrost:latest container_name: bifrost-1 env_file: - .env # 环境变量注入 volumes: - ./config.json:/app/config.json:ro # 共享配置 - bifrost_data_1:/app/data # 节点独立数据卷 expose: - "8080" # 仅容器网络内部可见 restart: unless-stopped volumes: bifrost_data_1: bifrost_data_2: bifrost_data_3:

该编排有几个值得注意的设计要点：

• 端口隔离：3 个 Bifrost 节点使用expose: "8080"而不是ports，端口只暴露在 Compose 内部网络中，宿主机无法直接访问节点；对外唯一入口是 NGINX 的8080:80映射。这符合“反向代理前置、后端不对外”的安全惯例。
• 共享配置：./config.json:/app/config.json:ro以只读方式挂载同一份配置，保证 3 个节点行为一致。
• 数据卷隔离：每个节点使用独立的命名卷（bifrost_data_1/2/3）挂载/app/data，避免多节点同时写同一数据目录造成冲突。
• 镜像 tag：示例默认使用maximhq/bifrost:latest，生产环境建议像 helm-values.yaml 中那样固定具体版本（例如v1.4.18）。

环境变量：必须的 .env

README 中的启动流程要求先执行cp .env.example .env并填入真实值。注意：实际仓库目录中并不存在.env.example文件，需要读者自行创建。必需的变量可从两处反推得出：

1. docker-compose.yml中env_file: .env注入的全部变量；
2. config.json 中以env.前缀引用的变量——env.BIFROST_ENCRYPTION_KEY与env.OPENAI_API_KEY。

结合 helm-values.yaml 中env段的定义，.env至少应包含：

OPENAI_API_KEY=replace-with-real-key BIFROST_ENCRYPTION_KEY=replace-with-32-byte-random-string

其中BIFROST_ENCRYPTION_KEY是 Bifrost 用于加密敏感配置（如 API Key）的密钥，示例要求 32 字节随机字符串，请使用openssl rand -base64 32之类的工具生成并妥善保管。

共享 config.json 详解

config.json 是 3 个节点共享的核心配置，逐项说明如下：

{ "$schema": "https://www.getbifrost.ai/schema", "encryption_key": "env.BIFROST_ENCRYPTION_KEY", "config_store": { "enabled": false }, "logs_store": { "enabled": false }, "client": { "drop_excess_requests": false, "enable_logging": true, "allowed_origins": ["*"], "max_request_body_size_mb": 100 }, "providers": { "openai": { "keys": [ { "name": "openai-primary", "value": "env.OPENAI_API_KEY", "models": ["gpt-4o-mini", "gpt-4o"], "weight": 1 } ] } } }

• encryption_key：使用env.BIFROST_ENCRYPTION_KEY形式引用环境变量，而不是在配置文件中明文写入密钥。这是 Bifrost 推荐的安全做法——密钥通过环境变量或部署平台 Secret 注入，配置文件本身不含敏感信息。
• config_store/logs_store均enabled: false：表示不启用外部配置存储与日志存储，节点以本地模式运行。这与健康检查实现直接相关（见下文“验证”一节）：源码中的DisableDBPingsInHealth逻辑在无外部存储时会跳过数据库 Ping。
• client块：enable_logging: true开启请求日志；allowed_origins: ["*"]允许所有来源（如需要可收紧为具体域名）；max_request_body_size_mb: 100限制最大请求体为 100 MB，与后续 Helm/Ingress 中的proxy-body-size: "100m"遥相呼应。
• providers.openai：定义一个名为openai-primary的 API Key，值引用env.OPENAI_API_KEY，绑定模型gpt-4o-mini与gpt-4o，weight: 1表示该 Key 的负载均衡权重。当配置多个 Key 时，Bifrost 会按权重分配请求，实现 Key 级负载均衡与故障转移。

NGINX 反向代理配置解析

nginx.conf 是整个示例中技术含量最高的部分，它同时解决负载均衡、流式响应与 WebSocket 三大问题：

events { worker_connections 1024; } http { upstream bifrost_backend { least_conn; # 最少连接数负载均衡 server bifrost-1:8080; server bifrost-2:8080; server bifrost-3:8080; } server { listen 80; server_name _; location / { proxy_pass http://bifrost_backend; 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_http_version 1.1; proxy_buffering off; # 关闭响应缓冲，保障 SSE 流式 proxy_request_buffering off; # 关闭请求缓冲 proxy_read_timeout 300s; # 长流式响应场景加大超时 proxy_send_timeout 300s; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # WebSocket 升级 } } }

关键配置项逐一解读：

• 负载均衡策略least_conn：将请求分发到当前活跃连接数最少的节点，适合 LLM 推理这类单请求耗时差异大、长连接占比高的场景，比简单的 round-robin 更能避免个别节点积压。三个上游节点通过 Compose 服务名bifrost-1:8080、bifrost-2:8080、bifrost-3:8080寻址，由 Compose 内部 DNS 解析。
• 透传客户端信息：X-Real-IP、X-Forwarded-For、X-Forwarded-Proto三个 header 让后端节点感知真实客户端 IP 与协议，是网关做限流、审计、日志分析的前提。
• 流式响应（SSE）：proxy_buffering off与proxy_request_buffering off关闭 NGINX 的缓冲层，使stream: true的逐 token 输出能即时透传给客户端，避免首字延迟和缓冲等待；proxy_http_version 1.1是长连接与 WebSocket 的基础。
• 超时调大：proxy_read_timeout与proxy_send_timeout设为 300s。大模型推理经常出现数十秒的“思考时间”，默认 60s 的读超时很容易误杀正常请求。
• WebSocket 支持：Upgrade与Connection "upgrade"两行使 NGINX 能代理 WebSocket 升级请求，兼容 Bifrost 的流式/实时通道场景。

启动与验证

启动

cd examples/configs/withnginxreverseproxy cp .env.example .env # 若仓库未提供 .env.example，请按下文说明手动创建 # 编辑 .env 填入真实 OPENAI_API_KEY 与 BIFROST_ENCRYPTION_KEY docker compose config # 校验编排文件合法性 docker compose up -d # 后台启动全部服务 docker compose ps # 查看各容器状态

启动成功后，NGINX 将 Bifrost 网关暴露在http://localhost:8080。docker compose config会在真正启动前渲染并校验最终生效的配置，是排查 YAML 语法和变量问题的第一道防线。

验证健康状态

curl -i http://localhost:8080/health

该请求会经 NGINX 转发到某个 Bifrost 节点。健康检查端点的实现位于 transports/bifrost-http/handlers/health.go：HealthHandler注册GET /health路由，处理逻辑会并发 Ping 配置存储与日志存储（各带 10 秒超时），汇总错误后返回状态。

在本示例中，由于config.json将config_store与logs_store都设为enabled: false，两个存储均为空，健康检查实际无需 Ping 外部依赖——对应源码中DisableDBPingsInHealth分支返回{"status": "ok", "components": {"db_pings": "disabled"}}的行为，因此返回200 OK非常快。

验证非流式推理

curl -sS http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Say hello"}] }'

gpt-4o-mini正是 config.json 中为openai-primaryKey 绑定的模型。Bifrost 将请求转发给 OpenAI，并以 OpenAI 兼容的 chat completions 格式返回结果——这正是 Bifrost“统一接口”能力的体现：无论上游是哪个提供商，客户端看到的都是同一套 API。

验证流式输出

curl -N http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "stream": true, "messages": [{"role": "user", "content": "stream test"}] }'

-N参数禁用 curl 的缓冲，配合 NGINX 侧proxy_buffering off，能逐 chunk 看到 SSE 流式输出。如果在这一步遇到长时间无响应或中途断开，优先排查 NGINX 的缓冲与超时配置是否被覆盖。

停止

docker compose down

如需连同数据卷一并清理，可追加-v参数（注意：这也会删除 3 个节点写入的数据）。

Kubernetes / Helm 部署

示例同时提供了在 Kubernetes 上通过 NGINX Ingress 暴露网关的完整配置。

通过 Helm 安装

# 渲染清单并确认 Ingress 已包含 helm template bifrost ./helm-charts/bifrost \ -f examples/configs/withnginxreverseproxy/helm-values.yaml # 安装（或升级）该示例 helm upgrade --install bifrost ./helm-charts/bifrost \ -f examples/configs/withnginxreverseproxy/helm-values.yaml

helm-values.yaml 与 Docker Compose 场景保持同一套语义，核心参数如下：

image: tag: "v1.4.18" # 固定版本，生产环境建议明确指定 replicaCount: 3 # 与 Compose 的 3 节点一致 ingress: enabled: true className: nginx annotations: nginx.ingress.kubernetes.io/proxy-body-size: "100m" # 与 client.max_request_body_size_mb 对齐 nginx.ingress.kubernetes.io/proxy-read-timeout: "300" # 与 NGINX 300s 读超时对齐 nginx.ingress.kubernetes.io/proxy-send-timeout: "300" nginx.ingress.kubernetes.io/proxy-buffering: "off" # 保障 SSE 流式 nginx.ingress.kubernetes.io/ssl-redirect: "true" nginx.ingress.kubernetes.io/force-ssl-redirect: "true" hosts: - host: bifrost.example.com paths: - path: / pathType: Prefix tls: - secretName: bifrost-tls hosts: - bifrost.example.com bifrost: # 等价于 config.json 的映射 encryptionKey: "env.BIFROST_ENCRYPTION_KEY" client: enableLogging: true maxRequestBodySizeMb: 100 providers: openai: keys: - name: "openai-primary" value: "env.OPENAI_API_KEY" models: ["gpt-4o-mini", "gpt-4o"] weight: 1 env: # 向容器注入环境变量 - name: OPENAI_API_KEY value: "replace-with-real-key" - name: BIFROST_ENCRYPTION_KEY value: "replace-with-32-byte-random-string"

可以观察到三条部署路径刻意保持的参数一致性：

• 请求体上限：client.max_request_body_size_mb: 100↔ Ingress 注解proxy-body-size: "100m"；
• 超时：NGINX 的 300s 读/写超时 ↔ Ingress 注解proxy-read-timeout/proxy-send-timeout: "300"；
• 流式支持：proxy-buffering: "off"↔ Compose 场景 nginx.conf 中的proxy_buffering off。

生产环境务必把bifrost.example.com替换为真实域名，把env段中的占位值替换为真实密钥，并建议改用 Kubernetes Secret 注入。

独立 Ingress 清单

不依赖 Helm（或需要覆盖默认值）时，可直接使用 k8s-ingress.yaml：

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: bifrost annotations: cert-manager.io/cluster-issuer: letsencrypt-prod nginx.ingress.kubernetes.io/proxy-body-size: "100m" nginx.ingress.kubernetes.io/proxy-read-timeout: "300" nginx.ingress.kubernetes.io/proxy-send-timeout: "300" nginx.ingress.kubernetes.io/proxy-buffering: "off" spec: ingressClassName: nginx rules: - host: bifrost.example.com http: paths: - path: / pathType: Prefix backend: service: name: bifrost port: number: 8080 tls: - secretName: bifrost-tls hosts: - bifrost.example.com

该清单假设集群已安装 NGINX Ingress Controller 与 cert-manager（letsencrypt-prodClusterIssuer 负责自动签发证书）。校验方式：

kubectl apply --dry-run=client -f examples/configs/withnginxreverseproxy/k8s-ingress.yaml

--dry-run=client只做本地语法与 schema 校验，不会真正创建资源，适合作为 CI 中的人门检查。

部署要点总结

无论选择哪条路径，核心原则一致：对外只暴露代理入口，Bifrost 节点彼此隔离、共享同一配置、以多副本水平扩展；流式与长超时场景必须在代理层显式配置；密钥一律通过环境变量或 Secret 注入，配置文件与镜像中不落明文。这套模式既可用于单机 Docker 快速起一套高可用网关，也可无缝迁移到生产级 Kubernetes 集群。

更完整的配置语义（如 provider 多 Key 负载均衡权重、client 段更多选项、存储组件接入方式），可继续参考 examples/configs 下的其他场景目录（withconfigstore、withlogstore、withvirtualkeys等）以及 docker-compose.yml 根示例。

• 人工智能
• LLM 网关
• API网关
• 后端