配置一个可运行的项目
从启动变量开始,完成登录与邮件投递,再按实际使用的功能接入服务商并验证。
首次部署时,先让应用能启动、管理员能登录、系统能发送验证邮件。支付、文件、AI 等集成按产品需要逐项开启;页面存在并不代表服务商已就绪。
准备工作
1. 设置启动环境
以 .env.example 为清单,在本地 .env 或托管平台设置 APP_ENV、BETTER_AUTH_SECRET、SITE_URL 和数据库连接。生产环境的 BETTER_AUTH_SECRET 必须是新生成的随机值,不能留空或沿用模板值。可用以下命令生成:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"生产环境还要把 CONFIG_ENCRYPTION_KEY 设为至少 32 个字符的值(可用同一命令生成),这样接下来录入的服务商凭据会加密存库。设置后保持不变。若设置前已保存过凭据,执行一次 pnpm db:encrypt-config-secrets。见加密存储的凭据。
环境变量在进程启动时读取。保存后重启应用,运行 pnpm db:migrate,确认数据库迁移成功。数据库方言和 Workers 绑定的选择见数据库与部署。
2. 保留一种可用的登录方式
登录后台,打开 认证配置。邮箱密码登录默认开启;如果关闭它,先配置并测试 Google 或 GitHub 登录,否则用户会失去登录入口。按需要设置邮箱验证、注册和账号注销策略。社交登录前要在服务商侧登记页面显示的回调地址,再填入客户端 ID 与密钥。
保存后退出当前会话,分别测试登录和新账号注册。具体字段与 OAuth 回调流程见邮箱密码登录和社交登录。会话签名密钥 BETTER_AUTH_SECRET 仍在环境变量中,不在此页设置。
3. 让邮件实际送达
在 邮件配置 中选择 Resend、Cloudflare 或阿里云,填写服务商凭据和已验证的发件地址,启用并保存。域名验证要先在服务商控制台完成。接着到 邮件 → 测试发送 发一封邮件,并在投递记录中确认成功;再走一次注册验证或密码重置流程。
保存成功只说明设置已写入,不等于邮件已经送达。失败时先核对发件域名、凭据及投递记录中的服务商错误。字段和模板操作见邮件指南。
4. 按功能继续配置
只配置项目实际会用到的集成,每完成一项就做对应的端到端验证:
| 要启用的功能 | 配置重点 | 验证结果 |
|---|---|---|
| 收款与订阅 | 在支付配置中填写沙箱凭据、回跳地址和 Webhook 密钥,再在 套餐(/admin/plans)中创建至少一个上架的套餐 | 完成一次沙箱结账;订单状态由已签名 Webhook 或服务端确认更新。见支付服务商 |
| 文件上传或 Agent 产物 | 选择 S3 兼容存储或 R2 绑定,填写桶、访问密钥、大小和类型限制 | 上传一个允许的文件,并以该用户身份下载。见存储 |
| AI 任务或 Agent 模型 | 创建通道及服务商场景,配置密钥、模型、场景路由和定价 | 发起一项测试任务,确认返回真实服务商结果并记录用量。见AI 服务商和场景 |
| 分析与客服聊天 | 填写脚本 ID;需要报表时另配服务端访问令牌 | 在浏览器确认脚本加载并产生测试事件;报表拉取单独验证。见分析 |
| Agent 沙箱与网页检索 | 先安装 agent-starter,配置对象存储和 AI;再填写沙箱、SearXNG、crawl4ai 的连接与限额 | 分别测试搜索与抓取连接,并在工作台运行需要这些工具的任务。见Agent 模板 |
缓存默认可用。需要调整时,在 缓存配置 中逐域选择启用状态、TTL 和可用后端;关闭 启用 才会绕过缓存,TTL 不能设为 0。见缓存。订阅、通知、定价套餐和 API Key 限流在各自的业务页面配置,各自的位置见运行管理后台。
确认配置状态
打开 /setup。会话密钥、登录方式、邮件投递和定时任务是必需项;它还显示支付、存储、AI、订阅和分析的可选状态,以及 凭证加密;存储的凭据无法解密时该项变为必需。该清单不检查缓存、Agent 沙箱或搜索,因此还要执行上表中的功能测试。不要用页面是否能打开来判断服务商可用。
排查
- 无法启动或会话密钥报错:检查
APP_ENV和BETTER_AUTH_SECRET,修改后重启。生产环境拒绝空值和模板默认值。 - 设置已保存但功能未就绪:先看对应页面的配置状态和测试结果,再查服务商返回的错误。后台保存成功不代表服务商连接成功。
- AI 配置菜单可见但页面打不开:侧边栏按
config.read显示,页面读取实际需要ai.read,保存需要ai.write。 - 某个模块的页面或菜单不见了:检查 插件(
/admin/plugins);插件停用后入口会隐藏,页面返回 not found。 /setup提示定时任务没有运行:这需要在部署平台上修复。见排查项目问题。- 修改似乎未生效:后台保存通常清除对应缓存;若绕过后台直接改数据库,可能需等缓存 TTL 到期或手动清除。见缓存。