配置模型
为什么少数设置放在环境变量里,而其他一切都保存在数据库中、在管理后台编辑。
Kernlift 把设置放在两个地方。少量环境变量用于启动应用并连接数据库。其余设置,包括所有服务商凭据,都保存在数据库中,在管理后台编辑。修改设置见管理配置。
规则
| 设置 | 放在哪里 | 原因 |
|---|---|---|
| 应用环境、会话密钥、数据库连接、站点 URL | .env 或主机的环境变量 | 应用读取数据库之前就需要 |
| 登录方式、邮件、支付、存储、AI、分析、缓存 | 管理后台 /admin/config/* | 保存在数据库中,修改无需重新部署 |
| 产品、方案与授权 | 管理后台 /admin/products 与 /admin/licences | 业务数据,不是配置 |
划分依据是启动顺序。进程在打开数据库之前需要的设置来自环境变量。其余设置保存在数据库中,由运营者管理。
为什么服务商设置不是环境变量
- 更换服务商无需重新部署。 轮换密钥、切换当前邮件服务商或开启 Google 登录,只需在管理后台保存一次。
- 单一事实来源。
/setup清单、后台页面和运行时读取的是同一批数据行,所以页面显示的就是服务端实际使用的配置。 - 便于 fork 的模板。 基于模板构建的项目把服务商设置加到后台界面,不新增环境变量。功能代码不读取
process.env。
环境变量
本地项目只需要 BETTER_AUTH_SECRET,在快速开始里已经设置。生产环境需要设置:
| 变量 | 作用 |
|---|---|
APP_ENV | development 或 production。生产环境会启用更严格的检查 |
BETTER_AUTH_SECRET | 签名会话。生产环境使用模板默认值时拒绝启动 |
CONFIG_ENCRYPTION_KEY | 可选,生产环境强烈建议设置。加密存在数据库里的凭据,见加密存储的凭据 |
DATABASE_DIALECT | sqlite、postgres 或 d1 |
DATABASE_ADAPTER | 可选的适配器 id,例如 turso 或自定义适配器。默认等于方言 |
DATABASE_URL | 文件路径或连接串 |
SITE_URL | 元数据、站点地图、订阅源和邮件链接使用的规范源地址 |
.env.example 列出源代码读取的每个变量,pnpm validate:env-example 确保两者保持一致。每个变量的说明见环境变量。
后台设置页面
| 页面 | 内容 |
|---|---|
/admin/config/auth | 邮箱密码规则、Google 与 GitHub OAuth、Google One Tap、注册奖励 |
/admin/config/email | Resend、Cloudflare Email 或阿里云邮件推送,以及通知 Webhook |
/admin/config/payment | Stripe、Creem、PayPal、DodoPayments、微信支付、支付宝或 Waffo,成功与取消 URL,优惠码 |
/admin/config/storage | S3 兼容存储与允许的上传类型 |
/admin/config/ai | AI 服务商、服务商场景、场景与积分定价 |
/admin/config/analytics | 分析服务商 |
/admin/config/cache | 每个缓存域的启用状态、TTL 与后端 |
/admin/config/sandbox | Agent 沙箱服务商、镜像与资源上限;安装 agent-starter 后出现 |
/admin/config/search | Agent 搜索与抓取服务;安装 agent-starter 后出现 |
订阅、通知渠道和限流规则各有独立的后台页面。完整路由与权限见管理配置。
「未配置」是一种状态,不是错误
没有凭据的服务商会报告「未配置」,并且不运行。模板从不伪造服务商响应、模拟支付或编造用量数据。/setup 把这些状态汇总成清单:每一项显示已就绪或未就绪,去配置链接到修复它的页面。只有会话密钥、登录方式和邮件投递是必需的。
加密存储的凭据
凭据存在数据库里,数据库备份、只读副本或数据库控制台一旦泄露就会暴露它们。在每个读取配置表的进程(Web 应用,以及部署了的 Agent 服务)的环境中设置 CONFIG_ENCRYPTION_KEY(至少 32 个字符),所有分类为 secret 的设置就会静态加密:
- 加密什么:分类为
secret的值,即支付、邮件、存储、AI 和 OAuth 凭据。写入格式为enc:v1:<iv>:<密文>,算法 AES-256-GCM,密钥经 HKDF-SHA-256 派生,配置键作为附加数据参与加密,密文无法挪到其它行使用。public和internal保持明文。 - 已有凭据:设置密钥之前保存的凭据在再次保存前仍是明文。执行一次
pnpm db:encrypt-config-secrets全部加密;D1 加--remote处理线上数据库。重复执行不会改动任何行。 - 密钥错误或缺失:解不开的值读作未配置,绝不返回密文;写入默认值时也不会覆盖它,换回正确的密钥即可恢复。
- 缓存:持有解密后凭据的缓存域固定使用进程内存,在
/admin/config/cache不能为它们选择 KV 或 Redis。 - 就绪检查:
/setup有一项 凭证加密,会报告密钥缺失或过短、遗留的明文凭据以及解不开的凭据;只有最后一种会让它成为必需项。
不设置密钥时凭据以明文存储,其余行为不变,适合本地开发。kernlift deploy-target 会把密钥生成到 .env.production。密钥要保持不变:目前不支持轮换,更换或丢失密钥就需要重新录入所有凭据。
设置如何读取
多数配置读取经过缓存。通过后台保存时会清除对应缓存域。若直接修改数据库,变更可能要等到 TTL 到期才被读取。引导域 admin_config 不能从自己缓存的表中读取策略,因此其 TTL 来自 ADMIN_CONFIG_CACHE_TTL_MS。/admin/config/cache 将该域标记为不可编辑。
应用之外的变量
.env.example 末尾的 KERNLIFT_* 变量只由 registry 发布脚本和 CLI 的包管理命令读取。应用本身从不读取它们,从 GitHub 克隆的项目不用设置。
相关文件
这些页面共用后台界面模式,但存储方式并不相同:一般服务商设置使用带分类的 config_settings 行,AI 通道与定价使用专用数据表,Agent 搜索使用分类为 secret 的 JSON 行。