企业官网建设流程全解析

big-AGI 环境变量完全指南：从.env配置到后端 LLM、数据库与前端功能的完整部署手册

【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI

导读

本文档系统讲解 big-AGI 中全部环境变量的作用、优先级规则与配置方法，覆盖数据库（Postgres/MongoDB）、二十余个 LLM 服务商接入、浏览/搜索/TTS 等功能模块，以及前端构建期变量与 HTTP Basic 认证。读完本文，你将能够独立编写一份可直接用于本地开发或 Docker 部署的.env文件，并理解每个变量在源码（src/server/env.server.ts）中是如何被解析和消费的。

变量总览与优先级规则

big-AGI 的环境变量体系遵循一个简单而重要的原则：所有变量都是可选的。同时存在三层配置来源，按优先级从高到低排列：

1. UI 选项（前端界面中的设置）—— 用户在 Web UI 中填写/选择的内容优先级最高；
2. 后端环境变量—— 服务端通过.env或容器环境注入的配置；
3. 内置默认值—— 代码中硬编码的兜底值（如默认 Host、默认 API 版本）。

也就是说，只要用户在界面上配置了某个 LLM 的 API Key 或自定义 Host，即使后端环境变量未设置，该配置依然生效；反之，后端环境变量为"零配置部署"提供了便利——运维人员无需让每个用户手动输入密钥。

这份清单与仓库中的唯一权威解析点 src/server/env.server.ts 保持同步。该文件基于createEnv（来自src/modules/3rdparty/t3-env，配合 zod v4 做类型校验）集中声明了全部服务端与客户端变量，所有变量均为z.string().optional()或z.url().optional()级别的可选声明。值得注意的细节是emptyStringAsUndefined: true（第 165 行），即空字符串会被当作"未设置"处理，避免部署时因空值产生误判。

另外，该文件第 5-7 行明确约定：env.server是纯服务端模块，如果在客户端被 import 会直接抛错（--turbopack构建会跳过客户端 mock），因此服务端密钥绝不会泄漏到浏览器端。

配置方式与示例.env

本地开发 / 云部署

在项目根目录创建.env文件即可被 Next.js 自动加载。以下是根据原文档整理的完整示例，可直接复制使用：

# Database (Postgres) POSTGRES_PRISMA_URL= POSTGRES_URL_NON_POOLING= # Database (MongoDB) MDB_URI= # LLMs OPENAI_API_KEY= OPENAI_API_HOST= OPENAI_API_ORG_ID= ALIBABA_API_HOST= ALIBABA_API_KEY= AZURE_OPENAI_API_ENDPOINT= AZURE_OPENAI_API_KEY= ANTHROPIC_API_KEY= ANTHROPIC_API_HOST= BEDROCK_BEARER_TOKEN= BEDROCK_ACCESS_KEY_ID= BEDROCK_SECRET_ACCESS_KEY= BEDROCK_SESSION_TOKEN= BEDROCK_REGION= DEEPSEEK_API_KEY= GEMINI_API_KEY= GROQ_API_KEY= LOCALAI_API_HOST= LOCALAI_API_KEY= METAAI_API_KEY= METAAI_API_HOST= MISTRAL_API_KEY= MOONSHOT_API_KEY= NVIDIANIM_API_KEY= NVIDIANIM_API_HOST= OLLAMA_API_HOST= OPENROUTER_API_KEY= PERPLEXITY_API_KEY= TOGETHERAI_API_KEY= XAI_API_KEY= # Browse PUPPETEER_WSS_ENDPOINT= # Search GOOGLE_CLOUD_API_KEY= GOOGLE_CSE_ID= # Text-To-Speech: ElevenLabs ELEVENLABS_API_KEY= ELEVENLABS_API_HOST= ELEVENLABS_VOICE_ID= # Backend HTTP Basic Authentication (see `deploy-authentication.md` for turning on authentication) HTTP_BASIC_AUTH_USERNAME= HTTP_BASIC_AUTH_PASSWORD= # Frontend variables NEXT_PUBLIC_MOTD= NEXT_PUBLIC_GA4_MEASUREMENT_ID= NEXT_PUBLIC_GOOGLE_DRIVE_CLIENT_ID= NEXT_PUBLIC_PLANTUML_SERVER_URL= NEXT_PUBLIC_POSTHOG_KEY=

Docker 部署

使用 Docker 时，官方 docker-compose.yaml 通过env_file: - .env自动读取项目根目录的.env文件：

services: big-agi: image: ghcr.io/enricoros/big-agi:latest ports: - "3000:3000" env_file: - .env

也可以不依赖.env文件，直接用docker run -e传入变量，或在 compose 文件中使用environment:块。

两类变量的关键差异

• 后端变量（如OPENAI_API_KEY）：只需在启动时定义。开发模式下启动 Next.js 本地服务器前设置即可，容器场景在启动容器时通过--env-file或-e传入；
• 前端变量（NEXT_PUBLIC_*前缀）：必须在构建时（build time）设置，这是 Next.js 将变量内联进前端 bundle 的硬性要求。构建完成后修改这些值不会对已构建产物生效，必须重新构建。NEXT_PUBLIC_前缀同时意味着这些值会被打进客户端代码，因此严禁在其中放入任何秘密。

数据库变量：为 Chat Link Sharing 等特性提供存储

要启用 Chat Link Sharing（链接分享）等功能，后端必须连接数据库。big-AGI 当前支持 Postgres 和 MongoDB 两种方案，完整接入步骤见 deploy-database.md。

从源码看，后端能力探测逻辑在 backend.router.ts 中：hasDB判定为MDB_URI存在，或POSTGRES_PRISMA_URL与POSTGRES_URL_NON_POOLING同时存在。也就是说 Postgres 方案要求两个变量成对配置。

若选用 MongoDB，还需按 deploy-database.md 修改 Prisma 数据源配置：src/server/prisma/schema.prisma 中将provider改为"mongodb"、url = env("MDB_URI")，随后执行npx prisma db push一次性创建/更新数据库表结构。

LLM 服务商变量：服务端预配置，用户免输密钥

以下变量一旦在服务端设置，对应 LLM 就会直接启用，用户无需再在 UI 中手动输入 API Key。它们全部在 src/server/env.server.ts 中有对应声明，并在服务端各厂商 access 模块中被消费。

说明：以上表格以原文档为准。源码中还额外声明了CEREBRAS_API_KEY、MODULAR_API_KEY、SAKANA_API_KEY/SAKANA_API_HOST等厂商变量（见 env.server.ts），原文档示例.env未列出不代表不可用，但请以文档表格为主进行配置。

源码级的变量消费方式

• OpenAI：openai.access.ts 中当用户未在 UI 配置时，oaiHost = env.OPENAI_API_HOST || DEFAULT_OPENAI_HOST，oaiKey = access.oaiKey || env.OPENAI_API_KEY，oaiOrg = access.oaiOrg || env.OPENAI_API_ORG_ID——清晰体现了"UI 选项 > 环境变量 > 默认值"的优先级链；
• Anthropic：anthropic.access.ts 中anthropicHost = access.anthropicHost || env.ANTHROPIC_API_HOST || DEFAULT_ANTHROPIC_HOST；
• Ollama：ollama.access.ts 中ollamaHost = access.ollamaHost || env.OLLAMA_API_HOST || DEFAULT_OLLAMA_HOST；
• Bedrock：bedrock.access.ts 中 region 直接取env.BEDROCK_REGION || DEFAULT_BEDROCK_REGION，注释明确说明"服务端提供的 region 出于安全原因忽略客户端传入值"；
• Azure OpenAI：openai.access.ts 中apiEnableV1: env.AZURE_OPENAI_DISABLE_V1 !== 'true'、versionAzureOpenAI: env.AZURE_OPENAI_API_VERSION || '2025-04-01-preview'、versionDeployments: env.AZURE_DEPLOYMENTS_API_VERSION || '2023-03-15-preview'，与文档中的默认值完全一致。

服务端能力自动探测

后端通过 backend.router.ts 的listCapabilities查询自动探测"哪些 LLM 已被服务端预配置"，并将结果下发前端。例如：

• hasLlmOpenAI = !!env.OPENAI_API_KEY || !!env.OPENAI_API_HOST
• hasLlmAzureOpenAI = !!env.AZURE_OPENAI_API_KEY && !!env.AZURE_OPENAI_API_ENDPOINT（要求成对）
• hasLlmBedrock = !!env.BEDROCK_BEARER_TOKEN || (!!env.BEDROCK_ACCESS_KEY_ID && !!env.BEDROCK_SECRET_ACCESS_KEY)
• hasLlmOllama = !!env.OLLAMA_API_HOST、hasLlmNvidiaNIM = !!env.NVIDIANIM_API_KEY || !!env.NVIDIANIM_API_HOST
• hasLlmMetaAI等其余厂商均以各自 API Key 是否设置为准

这套机制让部署者只需"填好.env即可"，前端模型列表中会自动出现对应厂商的模型，无需改代码。此外该文件还基于所有含_API_的环境变量生成配置哈希（generateLlmEnvConfigHash，第 23-35 行），用于触发下游配置变更识别。

功能模块变量：让应用会说话、能搜索、可浏览

文本转语音（Text-To-Speech）

big-AGI 支持 ElevenLabs、Inworld、OpenAI TTS、LocalAI 以及浏览器 Web Speech API 等多种方案：

注意：OpenAI TTS 与 LocalAI TTS 会直接复用你已配置的 LLM 服务凭据，无需单独的环境变量。服务端能力探测中hasVoiceElevenLabs = !!env.ELEVENLABS_API_KEY（见 backend.router.ts）。

Google Custom Search（/react命令）

从源码看，search.router.ts 中搜索请求会取input.cx || env.GOOGLE_CSE_ID与input.key || env.GOOGLE_CLOUD_API_KEY；同时hasGoogleCustomSearch要求两个变量同时存在（backend.router.ts）。

Browse（网页浏览）

browse.router.ts 中浏览请求使用access.wssEndpoint || env.PUPPETEER_WSS_ENDPOINT，hasBrowsing = !!env.PUPPETEER_WSS_ENDPOINT。若需要自带浏览服务的 compose 编排，可参考 docker-compose-browserless.yaml。

后端 HTTP Basic 认证

big-AGI 本身不内置认证体系，通过 HTTP Basic Authentication 即可为部署加上一层简单防护。启用步骤见 deploy-authentication.md：将仓库根目录的middleware_BASIC_AUTH.ts重命名为middleware.ts后重新构建即可。

中间件实现细节（middleware_BASIC_AUTH.ts）：

• 若两个变量未配置，直接返回401 Unauthorized/Unconfigured并输出警告（第 16-19 行）；
• 校验请求头Authorization: Basic ...中 Base64 解码后的用户名/密码是否与process.env完全匹配（第 27-35 行）；
• 拒绝时返回WWW-Authenticate: Basic realm="Secure big-AGI"（第 42-47 行）；
• 匹配规则覆盖根路径、主要页面（call|index|news|personas|link）与全部/api路由（第 49-58 行）。

其他服务端变量

• AIX_STRICT_PARSING：设为'true'时强制在生产环境开启 AIX 严格解析模式（默认开发环境严格、生产环境宽容，便于调试 API 漂移）；
• BIG_AGI_BUILD：构建期配置（standalone/static），正常部署无需关心。

前端（构建期）变量

以下变量会随 Next.js 构建内联到前端 bundle 中，因此必须构建时设置，且不能包含任何机密：

前端变量的源码消费点

• MOTD：OptimaMOTD.tsx 通过process.env.NEXT_PUBLIC_MOTD判断是否渲染横幅，并在第 33-45 行用Release.buildInfo('frontend')替换{{app_build_hash}}、{{app_build_pkgver}}、{{app_deployment_type}}等模板变量；{{app_build_time}}会被特殊渲染为 TimeAgo 相对时间组件；横幅支持按内容哈希记忆"已关闭"状态（MOTD_PREFIX + hash）；
• GA4 / PostHog：GoogleAnalytics.tsx 与 PostHogAnalytics.tsx 均以对应变量是否存在来决定是否初始化分析 SDK；PostHog 服务端侧也会复用同一 Key（posthog.server.ts）；
• PlantUML：RenderCodePlantUML.tsx 中渲染 UML 图时取process.env.NEXT_PUBLIC_PLANTUML_SERVER_URL || 'https://www.plantuml.com/plantuml/svg/'作为默认服务。

常见部署组合速查

延伸阅读

• customizations.md —— 后端代码与环境自定义的更高层概览
• deploy-database.md —— 数据库连接串与 Prisma 配置细节
• deploy-authentication.md —— 开启 HTTP Basic 认证的完整步骤
• deploy-analytics.md —— GA4 / PostHog 分析接入
• config-azure-openai.md —— Azure OpenAI 专项配置
• config-local-ollama.md —— 本地 Ollama 接入
• environment-variables.md —— 本文的原始权威清单（与 env.server.ts 保持同步）

最后再强调一次关键要点：全部变量可选；UI 选项优先于后端环境变量，后端环境变量优先于内置默认值；NEXT_PUBLIC_*变量必须在构建时设置且不可含机密；Postgres 需要两个 URL 成对配置，Azure OpenAI 端点与密钥成对，Bedrock 的 Bearer Token 与 IAM 凭据二选一即可。按照本文清单填写.env，即可逐步点亮 big-AGI 的数据库、多 LLM、浏览搜索与语音等全部能力。

【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI