Carbon
English

环境变量

配置 Carbon 实例的全部变量，按用途分组。事实来源是 packages/env。

Carbon 从 packages/env 中注册的环境变量读取配置。使用 .env.example 作为模板。sst.config.ts 读取仅用于基础设施的变量。最小实例需要 Supabase、会话密钥和 Redis；其他变量用于启用可选功能。

核心

平台级行为和版本。

CARBON_EDITIONenumoptional
community、cloud、enterprise 或 test 之一。控制版本特定功能。
CONTROLLED_ENVIRONMENTbooleanoptional
启用 ITAR / 受控环境限制：美国人员认证关卡、ITAR 主机名和品牌、禁用 Slack 和分析，以及公司管理员无法关闭的强制双因素认证。
TENANT_TYPEenumoptional
当部署由单一客户拥有时（如自托管安装）为 single；Carbon Cloud 为 multi（默认）。single 时，公司可以通过服务器自己的邮件发送单据（服务器邮件）。
AUTH_PROVIDERSenum[]optional
允许的登录方式：email、google、azure、passkey、sso（单点登录，仅企业版）。
DOMAINstringoptional
应用所在的基础域名。
ERP_URLurloptional
ERP 应用的公开 URL。MES 需要它：车间过账（发料、完工、拣货）会发送到该地址。
MES_URLurloptional
MES 应用的公开 URL。
DOCS_URLurloptional
应用内帮助链接所指向的文档站点公开 URL。请设为本次部署的文档地址；开发环境未设置时回退到本地文档应用。应用内链接会带上读者的语言（?lang=zh|en），文档站默认使用中文（读者可切换，选择保存在 cookie 中）。
WEBSITE_URLurloptional
可选的公开网站。未设置时，应用内需要它的链接（价格、条款、联系）会被隐藏，而不是指向本次部署访问不到的主机。
LEARN_URLurloptional
可选的学习站点（Academy）。未设置时，培训面板与新手引导邮件中的学堂链接会被隐藏。
REPOSITORY_URLurloptional
可选的源码仓库。未设置时，文档中的“Edit on GitHub”链接会被隐藏。
STATUS_URLurloptional
可选的公开状态页。未设置时，文档页脚的状态链接会被隐藏。
DEFAULT_LANGUAGEstringoptional
默认界面语言。
RATE_LIMITnumberoptional
每个窗口允许的 API 请求数。

数据库——Supabase

Carbon 的单一 Postgres 数据库。前四个为必填，缺失会导致启动失败。

SUPABASE_URLurlrequired
Supabase 项目 URL。
SUPABASE_ANON_KEYstringrequired
公开 anon 密钥，可安全用于浏览器。
SUPABASE_SERVICE_ROLE_KEYstringrequired
Service-role 密钥，仅服务端使用，绝不暴露给客户端。
SUPABASE_DB_URLurlrequired
直接 Postgres 连接字符串。
SUPABASE_JWT_SECRETstringoptional
用于签名和验证会话 JWT 的密钥。应用可选，但 Supabase 数据平面需要它，因此自托管方案总会生成一个。

认证与会话

SESSION_SECRETstringrequired
签名会话 cookie。Carbon 还从它推导 Web Push 密钥，因此更改后每个用户的浏览器通知会在下次访问时重新订阅。
SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_IDstringoptional
Google OAuth 客户端 ID，当 AUTH_PROVIDERS 包含 google 时。
SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_SECRETstringoptional
Google OAuth 客户端密钥。
SUPABASE_AUTH_EXTERNAL_AZURE_CLIENT_IDstringoptional
Azure OAuth 客户端 ID，启用 azure 时。
SUPABASE_AUTH_EXTERNAL_AZURE_CLIENT_SECRETstringoptional
Azure OAuth 客户端密钥。
DEV_BYPASS_EMAILstringoptional
仅本地。以该邮箱登录，无需魔法链接。

企业版 SAML 单点登录增加两个：

SAML_ENABLEDbooleanoptional
开启认证服务中的 SAML 引擎。
SAML_PRIVATE_KEYstringoptional
SAML 签名密钥——base64 编码的 PKCS#1 DER RSA，至少 2048 位；生成命令见 .env.example。

在 Vercel 之外，同时设置 CLOUDFLARE_TURNSTILE_SITE_KEY 和 CLOUDFLARE_TURNSTILE_SECRET_KEY 以在登录表单启用 Cloudflare Turnstile。没有它们时，仅应用按 IP 限流和按账户锁定。把 BOT_PROTECTION 设为 turnstile，或设为 botid 使用 Vercel BotID 无感保护。BotID 仅在 Vercel 上运行。

任务与缓存

REDIS_URLurlrequired
用于权限缓存和队列的 Redis 连接（ioredis URL）。
INNGEST_SIGNING_KEYstringoptional
签名发往 Inngest 任务运行器的请求。生产环境必填。
INNGEST_EVENT_KEYstringoptional
向 Inngest 发送事件的密钥。生产环境必填。
INNGEST_BASE_URLurloptional
覆盖 Inngest 端点（自托管或开发）。
HEADS UP

生产环境必须提供 Inngest 密钥

只有在 INNGEST_DEV=1 时，INNGEST_SIGNING_KEY 和 INNGEST_EVENT_KEY 才是可选的。其他环境下缺少任一，应用不会启动。自托管 Inngest 服务器会提供两者；Docker + Caddy 方案会生成它们。

数据库还会直接向 Inngest 发送事件，用于事件队列、搜索嵌入和生产订单通知。每当 ERP 向 Inngest 注册其函数时（每次部署，以及每次长时间运行服务器启动时），它也会把地址存入数据库，地址由 INNGEST_EVENT_KEY 和 INNGEST_BASE_URL 构建，因此无需额外步骤。

如果数据库访问 Inngest 的地址与应用不同，请设置一次：

sql
SELECT public.set_inngest_event_url('https://inngest.example.com/e/<event key>');

ERP 会保留你设置的地址，只刷新其中的事件密钥，因此轮换后的密钥仍会在下次部署时到达数据库。

邮件与计费

SMTP_HOSTstringoptional
用于交易邮件的 SMTP 服务器。未设置则禁用邮件发送。
SMTP_PORTnumberoptional
SMTP 端口；465 使用隐式 TLS，587（默认）使用 STARTTLS。
SMTP_USERstringoptional
SMTP 用户名。
SMTP_PASSWORDstringoptional
SMTP 密码。
SMTP_FROMstringoptional
外发邮件的发件地址，例如 Carbon <no-reply@example.com>。
RESEND_API_KEYstringoptional
可选。Resend 营销联系人 API；当 SMTP_* 未设置时也作为旧版 SMTP 回退。
STRIPE_SECRET_KEYstringoptional
Stripe 密钥，用于 Cloud / Enterprise 计费。
STRIPE_WEBHOOK_SECRETstringoptional
验证传入的 Stripe Webhook。
STRIPE_CONNECT_WEBHOOK_SECRETstringoptional
验证传入的 Stripe Connect Webhook（已连接账户事件，使用单独密钥签名）。

AI 与分析

OPENAI_API_KEYstringoptional
支持 AI 功能（嵌入、辅助）。
ANTHROPIC_API_KEYstringoptional
用于 Claude 支持功能的 Anthropic 密钥。
POSTHOG_API_HOSTurloptional
产品分析的 PostHog 主机。
POSTHOG_PROJECT_PUBLIC_KEYstringoptional
PostHog 项目密钥。

集成

每个连接器的 OAuth 凭据，全部可选，只设置你使用的。

XERO_CLIENT_IDstringoptional
Xero OAuth 客户端 ID。
XERO_CLIENT_SECRETstringoptional
Xero OAuth 客户端密钥。
XERO_WEBHOOK_SECRETstringoptional
验证传入的 Xero Webhook。
QUICKBOOKS_CLIENT_IDstringoptional
QuickBooks OAuth 客户端 ID。
QUICKBOOKS_CLIENT_SECRETstringoptional
QuickBooks OAuth 客户端密钥。
JIRA_CLIENT_IDstringoptional
Jira OAuth 客户端 ID。
JIRA_CLIENT_SECRETstringoptional
Jira OAuth 客户端密钥。
SLACK_CLIENT_IDstringoptional
Slack OAuth 客户端 ID。
SLACK_CLIENT_SECRETstringoptional
Slack OAuth 客户端密钥。
ONSHAPE_CLIENT_IDstringoptional
拉取集成（onshape）所用 Onshape OAuth 应用的客户端 ID。缺少时 Onshape 卡片显示 Not Configured。
ONSHAPE_CLIENT_SECRETstringoptional
拉取集成的 Onshape OAuth 应用客户端密钥。
ONSHAPE_OAUTH_REDIRECT_URLurloptional
拉取集成的回调：https://<erp-host>/api/integrations/onshape/oauth。必须在拉取集成的 Onshape 应用上注册。
ONSHAPE_V2_CLIENT_IDstringoptional
面板集成（onshape-v2）所用 Onshape OAuth 应用的客户端 ID，与拉取集成是不同应用。缺少时 Onshape V2 卡片显示 Not Configured。
ONSHAPE_V2_CLIENT_SECRETstringoptional
面板集成的 Onshape OAuth 应用客户端密钥。
ONSHAPE_V2_OAUTH_REDIRECT_URLurloptional
面板集成的回调：https://<erp-host>/api/integrations/onshape-v2/oauth。必须在面板集成的 Onshape 应用上注册。缺少时 Onshape V2 Connect 按钮会报「Onshape isn't configured」。
EXCHANGE_RATES_API_KEYstringoptional
货币汇率数据源。
GOOGLE_PLACES_API_KEYstringoptional
地址自动补全。

Onshape 面板还需要在 Onshape 应用上注册扩展，并让面板用户订阅它——参见 CAD。面板会话和推送评审保存在 Redis 中，因此 REDIS_URL 是面板工作的必要条件。

基础设施——SST

由 sst.config.ts 在部署时读取，而不是应用。

AWS_REGIONstringrequired
部署区域。
AWS_ACCOUNT_IDstringrequired
目标 AWS 账户。
IMAGE_TAGstringrequired
要部署的 ECR 镜像标签。
CERT_ARN_ERPstringoptional
ERP 域名的 ACM 证书 ARN。
CERT_ARN_MESstringoptional
MES 域名的 ACM 证书 ARN。
URL_ERPurloptional
自定义 ERP 域名，覆盖默认值。
URL_MESurloptional
自定义 MES 域名，覆盖默认值。
HEADS UP

TRIGGER_* 和 UPSTASH_REDIS_* 变量已废弃。任务使用 Inngest，缓存使用 REDIS_URL。