环境变量
部署必须的六个变量、少数可选变量,以及只有 Agent 服务和脚本才读取的变量。
网站运行只需要六个环境变量。其余的服务商凭据、登录方式、发件人和支付设置都在 /admin/config/* 里配置,保存在数据库中。.env.example 列出源码读取的每个变量,两者不一致时 pnpm validate:env-example 失败。
必须配置
| 变量 | 默认值 | 作用 |
|---|---|---|
APP_ENV | development | development 或 production。只要不是 development 就启用生产守卫 |
BETTER_AUTH_SECRET | 模板密钥(仅开发环境) | 会话签名密钥。非开发环境下为空或仍是模板默认值时应用拒绝启动 |
SITE_URL | https://kernlift.example.com | 元数据、站点地图、订阅源和绝对链接使用的规范域名 |
DATABASE_DIALECT | sqlite | sqlite、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_PROCESS | true | Node 服务在 Web 进程内每分钟执行一轮定时任务。设为 false 时改由外部 cron 调用 pnpm jobs:run。Cloudflare Worker 不读取它,用的是 wrangler.jsonc 里的 Cron Trigger |
ADMIN_CONFIG_CACHE_TTL_MS | 30000 | 后台配置的缓存时长;它是唯一无法从 /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 | ::、3001 | Agent 服务 | 监听地址和端口 |
AGENT_SERVICE_REQUEST_TIMEOUT_MS | 120000 | Web 应用 | 调用 Agent 服务的超时时间(毫秒) |
AGENT_FLOW_LOG_LEVEL | info | 两个进程 | debug、info、warn、error 或 silent |
AGENT_SANDBOX_ERROR_LOG_ENABLED | true | Agent 服务 | 是否记录沙箱错误详情 |
环境中带有 Web 认证或支付密钥时,Agent 服务拒绝启动。CONFIG_ENCRYPTION_KEY 要与 Web 应用设为相同的值,因为 Agent 服务读同一张配置表。Agent 的数据库必须支持事务,D1 不能存储 Agent 数据。见安装 Agent。
脚本与工具
只有命令行脚本和校验器读取,Web 应用不会读取。
| 变量 | 读取方 | 作用 |
|---|---|---|
SUPER_ADMIN_EMAIL、SUPER_ADMIN_PASSWORD | pnpm db:bootstrap-super-admin | 必填。第一个管理员;密码(至少 8 位)仅在新建账号时使用 |
SUPER_ADMIN_NAME | pnpm db:bootstrap-super-admin | 可选,默认 Super Admin |
EXTERNAL_VALIDATE_STRICT | pnpm validate:external | 为 true 时把跳过的服务商检查判为失败 |
EXTERNAL_VALIDATE_EMAIL_TO | pnpm validate:external | 真实邮件检查的收件人 |
EXTERNAL_VALIDATE_NEWSLETTER_EMAIL | pnpm validate:external | 通过订阅服务商订阅并退订的邮箱 |
EXTERNAL_VALIDATE_GOOGLE_OAUTH_CONFIRMED | pnpm validate:external | 确认已手动完成 Google OAuth 跳转验证 |
EXTERNAL_VALIDATE_BILLING_CUSTOMER_ID、EXTERNAL_VALIDATE_BILLING_PAYMENT_ID、EXTERNAL_VALIDATE_BILLING_SUBSCRIPTION_ID | pnpm validate:external | 客户门户、退款和订阅检查使用的沙箱 id |
KERNLIFT_REGISTRY_URL、KERNLIFT_PUBLISH_TOKEN | pnpm registry:publish | 发布目标 registry 及其发布密钥。克隆的项目用不到 |
KERNLIFT_TOKEN、KERNLIFT_CONFIG_DIR | CLI 的包管理命令 | registry 令牌、配置目录覆盖。克隆的项目用不到 |
CHROME_PATH | pnpm assets:screenshots | 截图使用的 Chrome 可执行文件 |
NODE_ENV | 数据库脚本 | 由工具提供;决定加载哪些 .env 文件 |
AGENT_DEV_WEB_HOST、AGENT_DEV_WEB_PORT | pnpm dev:agent | 本地开发的 Web 监听地址,默认 127.0.0.1:5173 |
AGENT_DEV_SERVICE_HOST、AGENT_DEV_SERVICE_PORT | pnpm dev:agent | 本地开发的 Agent 服务监听地址,默认 127.0.0.1:3001 |
SKILL_PUBLISH_DRY_RUN | pnpm agent:publish-skills | 设为任意非空值时只报告将要发布的内容,不写入 |
AGENT_SANDBOX_TEMPLATE_DIR | 沙箱镜像构建 | 覆盖沙箱镜像模板目录 |
Cloudflare 绑定
这些绑定在 wrangler.jsonc 中声明,不写入 .env。
| 绑定 | 类型 | 作用 |
|---|---|---|
EDGE_DB | D1 数据库 | d1 适配器使用的数据库 |
HYPERDRIVE | Hyperdrive | hyperdrive 适配器使用的 Postgres 连接;默认注释掉,在 Worker 上使用 Postgres 时再启用 |
BUCKET | R2 桶 | 桶绑定驱动使用的存储 |
CACHE | KV 命名空间 | kv 缓存后端 |
AI | Workers 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}}。