环境变量

互客鱼从标准的 Laravel .env 读取其配置，某些键的 覆盖可通过平台管理的 App Settings 页面获得， 因此您可以交换 Stripe / 邮件 / LLM 凭证而无需重新部署。

必需

变量	原因
APP_KEY	加密主密钥。使用 php artisan key:generate 生成。如果没有重新加密迁移，永远不要轮换。
APP_URL	公共 URL，用于构建小部件代码片段、OAuth 回调、签名 URL。
DB_*	Postgres 连接。
REDIS_HOST	缓存、会话、队列、热路径检索缓存、对话历史缓存。
QUEUE_CONNECTION	在生产环境中设置为 redis。
SESSION_DRIVER	生产环境中为 redis。
CACHE_DRIVER	redis。
WIDGET_JWT_SECRET	访客 JWT 的 HS256 签名秘密。≥ 32 随机字节。

LLM 提供商

至少以下之一：

变量	提供商
CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN	Cloudflare Workers AI（首选）。自动绑定 Llama 3.3 70B + bge-base-en-v1.5。
OPENAI_API_KEY	OpenAI 直接。
OPENROUTER_API_KEY	OpenRouter（跨多个提供商的路由器）。

设置 LLM_PROVIDER 以强制绑定（cloudflare、 openai、openrouter）。未设置时，解析器根据 可用的密钥按上述优先级选择。

向量存储

变量	提供商
VECTORIZE_INDEX	Cloudflare Vectorize 索引名称。使用 CLOUDFLARE_ACCOUNT_ID + 令牌。
QDRANT_URL + QDRANT_API_KEY	Qdrant。

设置 VECTOR_PROVIDER 以强制。根据可用密钥自动绑定 （首选 Vectorize）。

爬虫

变量	策略
（使用 CLOUDFLARE_*）	Cloudflare Browser Rendering。首选。
BROWSERLESS_TOKEN + BROWSERLESS_URL	Browserless 备用。
（无）	纯 HTTP。免费；无 JS 渲染。

Stripe

变量	用途
STRIPE_KEY	Publishable key。
STRIPE_SECRET	Secret key。用于计划同步和 Cashier。
STRIPE_WEBHOOK_SECRET	传入 webhooks 的签名秘密（whsec_…）。
CASHIER_CURRENCY	默认 usd。

Reverb（实时）

变量	用途
REVERB_APP_KEY	公共应用密钥。嵌入小部件 init 负载中。
REVERB_APP_SECRET	秘密。仅服务器端。
REVERB_APP_ID	应用标识符。
REVERB_HOST	Reverb 服务器的公共主机名。
REVERB_PORT	默认 8080。
REVERB_SCHEME	生产环境中为 wss，本地为 ws。

邮件

变量	用途
MAIL_MAILER	smtp / postmark / resend / 等。
MAIL_FROM_ADDRESS	发件人地址。必需。
MAIL_FROM_NAME	显示名称。
MAIL_HOST / MAIL_PORT / MAIL_USERNAME / MAIL_PASSWORD	SMTP 凭证。

品牌

变量	用途
BRANDING_LABEL	默认“Powered by 互客鱼”标签。在 app_settings 中覆盖以进行白标。
BRANDING_URL	标签链接到哪里。
BRANDING_FOOTER_LOGO_PATH	页脚徽标图像的存储路径。

可观测性

变量	用途
SENTRY_DSN	错误报告。
OTEL_EXPORTER_OTLP_ENDPOINT	OpenTelemetry 收集器。Honeycomb / Grafana Cloud。
OTEL_SERVICE_NAME	跟踪中的服务名称。默认 hukeyu。

App Settings 覆盖

app_settings 单例行存储明文加密的覆盖：

• Stripe 秘密 + webhook 秘密 + publishable key。
• 邮件驱动程序设置。
• Cloudflare / OpenAI / OpenRouter 密钥。
• 品牌（标签、URL、徽标）。

AppSettingsOverrideServiceProvider 在启动时读取此内容并 合并到 config()。通过管理面板设置事物是生产环境的首选 — 密钥轮换时无需重新部署。