环境变量

部署必须的六个变量、少数可选变量,以及只有 Agent 服务和脚本才读取的变量。

网站运行只需要六个环境变量。其余的服务商凭据、登录方式、发件人和支付设置都在 /admin/config/* 里配置,保存在数据库中。.env.example 列出源码读取的每个变量,两者不一致时 pnpm validate:env-example 失败。

必须配置

变量默认值作用
APP_ENVdevelopmentdevelopment 或 production。只要不是 development 就启用生产守卫
BETTER_AUTH_SECRET模板密钥(仅开发环境)会话签名密钥。非开发环境下为空或仍是模板默认值时应用拒绝启动
SITE_URLhttps://kernlift.example.com元数据、站点地图、订阅源和绝对链接使用的规范域名
DATABASE_DIALECTsqlitesqlite、postgres 或 d1;同时决定使用哪条迁移链
DATABASE_URL./local.db(postgres 时为空)文件路径、postgresql:// 或 libsql:// 地址

可选

不需要对应功能时不用设置。

变量默认值作用
CONFIG_ENCRYPTION_KEY—(凭据以明文存储)至少 32 个字符。用 AES-256-GCM 对后台配置中分类为 secret 的值(支付、邮件、存储、AI 和 OAuth 凭据)做静态加密,存为 enc:v1:…。设置后保持不变:用一个密钥写入的值在另一个密钥下读作未配置。设置密钥前已保存的凭据,执行一次 pnpm db:encrypt-config-secrets 加密。见加密存储的凭据
JOBS_IN_PROCESStrueNode 服务在 Web 进程内每分钟执行一轮定时任务。设为 false 时改由外部 cron 调用 pnpm jobs:run。Cloudflare Worker 不读取它,用的是 wrangler.jsonc 里的 Cron Trigger
ADMIN_CONFIG_CACHE_TTL_MS30000后台配置的缓存时长;它是唯一无法从 /admin/config/cache 读取自身策略的缓存
DATABASE_ADAPTER与方言相同已注册的适配器 id:sqlite、postgres、turso、d1、hyperdrive(在 Worker 上连接 Postgres)或自定义适配器
DATABASE_AUTH_TOKEN—turso 适配器使用的 libSQL 认证令牌
AUTH_DEV_IMPERSONATE_USER_ID—把未登录请求视为该用户。仅在 APP_ENV=development 时生效,并输出警告

可选 Agent 服务

只有在 Web 应用旁边部署 Agent 服务时才需要设置这些变量,不部署 Agent 的站点一个都不用填。模型、沙箱和搜索在 /admin/config/* 中配置。本地运行 pnpm dev:agent 时,地址和两个密钥由它每次自动设置;部署时需要固定值。

变量默认值读取方作用
AGENT_SERVICE_URL—Web 应用Agent 服务的内部地址。Node 部署启用 Agent 时必填;Cloudflare 部署通过 AGENT_SERVICE 绑定访问容器,不读这个变量
AGENT_WEB_INTERNAL_URL—Agent 服务Web 应用的内部地址。必填
AGENT_INTERNAL_SIGNING_SECRET—两个进程两个进程之间的请求签名密钥,两端取值相同,不少于 32 字节。必填
AGENT_RESOURCE_GRANT_SECRET—Web 应用签发短期资源授权,不少于 32 字节。必填
AGENT_SERVICE_HOST、AGENT_SERVICE_PORT::、3001Agent 服务监听地址和端口
AGENT_SERVICE_REQUEST_TIMEOUT_MS120000Web 应用调用 Agent 服务的超时时间(毫秒)
AGENT_FLOW_LOG_LEVELinfo两个进程debug、info、warn、error 或 silent
AGENT_SANDBOX_ERROR_LOG_ENABLEDtrueAgent 服务是否记录沙箱错误详情

环境中带有 Web 认证或支付密钥时,Agent 服务拒绝启动。CONFIG_ENCRYPTION_KEY 要与 Web 应用设为相同的值,因为 Agent 服务读同一张配置表。Agent 的数据库必须支持事务,D1 不能存储 Agent 数据。见安装 Agent。

脚本与工具

只有命令行脚本和校验器读取,Web 应用不会读取。

变量读取方作用
SUPER_ADMIN_EMAIL、SUPER_ADMIN_PASSWORDpnpm db:bootstrap-super-admin必填。第一个管理员;密码(至少 8 位)仅在新建账号时使用
SUPER_ADMIN_NAMEpnpm db:bootstrap-super-admin可选,默认 Super Admin
EXTERNAL_VALIDATE_STRICTpnpm validate:external为 true 时把跳过的服务商检查判为失败
EXTERNAL_VALIDATE_EMAIL_TOpnpm validate:external真实邮件检查的收件人
EXTERNAL_VALIDATE_NEWSLETTER_EMAILpnpm validate:external通过订阅服务商订阅并退订的邮箱
EXTERNAL_VALIDATE_GOOGLE_OAUTH_CONFIRMEDpnpm validate:external确认已手动完成 Google OAuth 跳转验证
EXTERNAL_VALIDATE_BILLING_CUSTOMER_ID、EXTERNAL_VALIDATE_BILLING_PAYMENT_ID、EXTERNAL_VALIDATE_BILLING_SUBSCRIPTION_IDpnpm validate:external客户门户、退款和订阅检查使用的沙箱 id
KERNLIFT_REGISTRY_URL、KERNLIFT_PUBLISH_TOKENpnpm registry:publish发布目标 registry 及其发布密钥。克隆的项目用不到
KERNLIFT_TOKEN、KERNLIFT_CONFIG_DIRCLI 的包管理命令registry 令牌、配置目录覆盖。克隆的项目用不到
CHROME_PATHpnpm assets:screenshots截图使用的 Chrome 可执行文件
NODE_ENV数据库脚本由工具提供;决定加载哪些 .env 文件
AGENT_DEV_WEB_HOST、AGENT_DEV_WEB_PORTpnpm dev:agent本地开发的 Web 监听地址,默认 127.0.0.1:5173
AGENT_DEV_SERVICE_HOST、AGENT_DEV_SERVICE_PORTpnpm dev:agent本地开发的 Agent 服务监听地址,默认 127.0.0.1:3001
SKILL_PUBLISH_DRY_RUNpnpm agent:publish-skills设为任意非空值时只报告将要发布的内容,不写入
AGENT_SANDBOX_TEMPLATE_DIR沙箱镜像构建覆盖沙箱镜像模板目录

Cloudflare 绑定

这些绑定在 wrangler.jsonc 中声明,不写入 .env。

绑定类型作用
EDGE_DBD1 数据库d1 适配器使用的数据库
HYPERDRIVEHyperdrivehyperdrive 适配器使用的 Postgres 连接;默认注释掉,在 Worker 上使用 Postgres 时再启用
BUCKETR2 桶桶绑定驱动使用的存储
CACHEKV 命名空间kv 缓存后端
AIWorkers AI边缘推理
ASSETS静态资源提供 dist/client

wrangler.jsonc 还声明了 "triggers": { "crons": ["* * * * *"] },每分钟触发一轮定时任务。Agent 服务以 Cloudflare 容器运行时,它直连 Postgres 的地址是 Worker 密钥 AGENT_DATABASE_URL,用 wrangler secret put 设置。

不是环境变量的设置

RESEND_API_KEY、STRIPE_SECRET_KEY、GOOGLE_CLIENT_ID 这类服务商设置写在环境里不会生效,请在后台配置,见配置一个可运行的项目。/admin/config/ai 中的 AI 通道请求模板可以用 {{env.NAME}} 引用环境变量,密钥要用 {{secret.KEY}}。

下一步