配置参考
自建部署会读的每一个环境变量——它做什么、配错了会怎样、改了要不要重启。
一体机镜像会在首次启动时生成大部分凭据，并给 APP_URL 一个 http://localhost:3000 的默认值；Compose 部署由 init.sh 生成 .env，APP_URL 必须由你填写。两者的差异在下面分别标注。
最容易配错的是 APP_URL。它必须与浏览器地址栏里的地址逐字一致——协议、主机、端口都算。对不上时，登录请求会直接返回 403 Invalid origin，前端会明确显示 Invalid origin，而不是"登录看起来成功然后立刻弹回登录页"。
必填
| 变量 | 一体机默认 | Compose | 需重启 | 作用 |
|---|---|---|---|---|
BUSABASE_IMAGE | — | busabase/busabase-premium:latest | 是 | 用哪个镜像。公开的 :latest 就是同一份自托管构建，试用与正式都从它开始；签约后你也可以把它换成自己镜像源里的固定版本号。 |
APP_URL | http://localhost:3000 | 必填（init.sh 会询问） | 是 | 用户实际输入的地址，含协议和端口。也是登录 Origin 校验的基准。 |
APP_PORT | 3000 | 3000 | 是 | 对外发布的宿主机端口。 |
POSTGRES_USER | busabase | busabase | 是 | 数据库用户。 |
POSTGRES_PASSWORD | 首次启动生成 | 必填（init.sh 生成） | 是 | 数据库密码。要生成，不要自己想。 |
POSTGRES_DB | busabase | busabase | 是 | 数据库名。 |
S3_ACCESS_KEY | busabase | busabase | 是 | 对象存储 key，必须与 seaweed-s3.json 一致。 |
S3_SECRET_KEY | 首次启动生成 | 必填（init.sh 生成） | 是 | 对象存储 secret，必须与 seaweed-s3.json 一致。 |
S3_BUCKET | busabase | busabase | 是 | bucket 名，会自动创建。 |
BETTER_AUTH_SECRET | 首次启动生成 | 必填（init.sh 生成） | 是 | 签发会话 cookie。泄漏等同于任何人都能伪造登录态。 |
Origin 与反向代理
登录接口会用请求里的 Origin 头（协议 + 主机 + 端口必须完全匹配）去和受信任列表比对。受信任来源来自：
APP_URL/BETTER_AUTH_BASE_URL/NEXT_PUBLIC_APP_URL；BETTER_AUTH_ADDITIONAL_ORIGINS（逗号分隔的多个 Origin）；
反向代理场景下，APP_URL 必须等于浏览器实际访问的地址，而不是容器内部地址。反代还需要把原始 Host 与协议传给应用：proxy_set_header Host $host; 和 proxy_set_header X-Forwarded-Proto $scheme;。否则即使 APP_URL 配对了，后续回调与 cookie 仍可能错。
配置公网 Origin
一体机为了本机试用默认使用 http://localhost:3000。只要通过 IP、主机名、非默认端口或反向代理访问，就必须在启动容器前设置 APP_URL。Busabase 不会因为某个请求携带了 Origin 就自动信任它。
- 要同时信任 IP、域名或迁移期的新旧地址，使用
BETTER_AUTH_ADDITIONAL_ORIGINS。 - 更换域名前先配置新 Origin 并重启，再切换流量。
可选
| 变量 | 默认值 | 需重启 | 作用 |
|---|---|---|---|
BETTER_AUTH_ADDITIONAL_ORIGINS | 空 | 是 | 逗号分隔的额外受信任 Origin。唯一支持"同时信任多个地址"的开关。 |
IMAGE_REGISTRY | docker.io | 是 | 从内网镜像源拉 Postgres 与 SeaweedFS。 |
SYSTEM_ADMIN_EMAIL | admin@example.com | 是 | 哪个账号拥有系统管理后台。 |
EMAIL_VERIFICATION_REQUIRED | false（自托管） | 是 | 仅在邮件服务可用时设为 true。若发送失败，改回 false 并重启，原管理员账号即可登录。 |
EMAIL_PROVIDER | resend | 是 | 邮件服务：resend、postmark、sendgrid 或 ses。 |
| 邮件服务凭据 | 空 | 是 | 按服务设置 RESEND_API_KEY、POSTMARK_SERVER_TOKEN、SENDGRID_API_KEY 或 AWS 凭据。 |
EMAIL_FROM / EMAIL_LOGO_URL | 产品默认值 | 是 | 认证邮件的发件人和可选的绝对 Logo URL。 |
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET | 空 | 是 | 两项必须同时存在，否则禁用 GitHub provider 并隐藏按钮。 |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET | 空 | 是 | 两项必须同时存在，否则禁用 Google provider 并隐藏按钮。 |
ENABLE_SCHEDULER_AUTO_TICK | true（自托管） | 是 | 内置调度器，大约每分钟运行一次（SCHEDULER_TICK_INTERVAL_MS），负责让工作流的等待继续、启动排队中的运行、清理存储。只有在你用自己的 cron 调用 POST /api/scheduler/tick（带 Authorization: Bearer $CRON_SECRET）时才设为 false；两者都没有的话，等待永远不会继续。 |
SEAWEEDFS_VOLUME_LIMIT_MB | 1024 | 是 | SeaweedFS 切换到新卷文件的阈值。附件量大就调高。 |
SANDOCK_API_KEY | 空 | 是 | 启用 AirApp 的云端沙箱引擎。 |
已经替你设好的
这些由 Compose 文件或镜像注入。你一般不用改，但知道它们存在，能解释一些否则会让你困惑的行为。
| 变量 | 值 | 为什么 |
|---|---|---|
BUSABASE_EDITION | self-hosted | 移除计费、waitlist 和公开营销页。只在启动时读一次——故意不做成后台可切换的开关，因为切回去会把这些计费入口重新暴露出来。 |
PG_DATABASE_URL | 由 POSTGRES_* 拼出 | 想用外部数据库就改这个。 |
STORAGE_URL | 由 S3_* 拼出 | 一条 URL 而不是一组变量。minio:// 表示「S3、path-style、不走 TLS」——描述协议，不是厂商。 |
REDIS_URL | lmdb:///data/cache | 内嵌 LMDB 缓存 + 进程内 pub/sub。单副本规模下另起一个 Redis 没有收益，而且 Redis 7.4+ 是 RSALv2/SSPL，会带来我们不想转嫁给你的再分发约束。 |
上面每一个变量都要重启才生效。没有运行时热加载：值在启动时读取，这正是「一个运行中的实例，其配置可以完全从它的 .env 复现」的原因。
是生成的，不是配的
一体机镜像首次启动时自己生成 Postgres 密码、对象存储密钥和会话密钥，写进 /data/.credentials（权限 600）。它们不在镜像里，所以两个人拉同一个镜像不会共用密钥。
请备份那个文件。它是唯一副本。