Rallly 4.16 配置参数详解

Rallly 4.16 应用层 24 项环境变量与官方安装器栈层变量逐项详解：必需项 zod 校验实测、OIDC/SMTP/存储/限流全表、废弃与改名对照（NEXT_PUBLIC_URL→NEXT_PUBLIC_BASE_URL 等），全部标注源码行号或实测来源。

Rallly自托管预约调度会议2026/10/24

Rallly 4.16 配置参数详解

适用版本：Rallly v4.16.2。参数定义全部以应用源码 apps/web/src/env.ts（405 行，v4.16.2 tag 实抓）与官方自托管文档 support.rallly.co/self-hosting/configuration（查询日期 2026-10-24）为据，逐项标注实测结果或源码行号；无法实测的项目明确标注"文档溯源"。

一、两层配置体系

Rallly 的配置分两层，混着排错会浪费时间：

层载体生效方式典型变量
应用层进程环境变量（源码 env.ts 用 zod 定义与校验）启动时强校验，缺必需项直接拒绝启动DATABASE_URL、SECRET_PASSWORD、NEXT_PUBLIC_BASE_URL、SMTP 全系
栈层官方安装器生成的 .env（/opt/rallly/.env）或自写 Compose 的 environment由 rallly.sh/Compose 读取后再注入应用DOMAIN、WEB_PORT、PROXY_MODE、POSTGRES_VERSION、GARAGE_RPC_SECRET

栈层变量不会进应用进程，应用层变量也不应写在栈层语义的位置上——下文每项都标注所属层。

二、应用层必需变量（缺一不启动）

2.1 DATABASE_URL（必需）

  • 定义：z.url()（env.ts:21）。PostgreSQL 连接串，唯一支持的数据库。
  • 形态：postgres://用户:密码@主机:5432/库名。
  • 实测：指向同栈 PostgreSQL 服务名时正常完成 166 个迁移并启动成功（HTTP 200）；不设置时启动即报 zod 校验错误（code: 'invalid_type', path: [ 'DATABASE_URL' ]，实录见《Rallly 4.16 Docker Compose 部署指南》 §7.1）。
  • 注意：使用外部数据库时账号需要对目标库有 DDL 权限（迁移会建表改表）。

2.2 SECRET_PASSWORD（必需）

  • 定义：z.string().min(32)（env.ts:25）——会话与敏感数据的加密密钥，最少 32 字符。
  • 实测①：设 8 字符启动被拒，报错实录精确落在该变量（minimum: 32，code: 'too_small'）：
❌ Invalid environment variables: [
  {
    origin: 'string',
    code: 'too_small',
    minimum: 32,
    inclusive: true,
    path: [ 'SECRET_PASSWORD' ],
    message: 'Invalid input'
  }
]
  • 实测②：设 32 字符后服务正常。启动日志会出现 Better Auth 的低熵提示，说明该值同时充当认证 secret（信息性警告，不影响运行）：
2026-10-24T03:10:41.560Z WARN [Better Auth]: [better-auth] Warning: your BETTER_AUTH_SECRET appears low-entropy. Use a randomly generated secret for production.
  • 追加职责（源码溯源）：Webhook 密钥与通知数据的加密也使用该值（features/notifications、features/webhook 中 secret: env.SECRET_PASSWORD），因此换库重装时不要随意更换，否则已存的加密数据将无法解密。

2.3 SUPPORT_EMAIL（必需）

  • 定义：z.email()（env.ts:79）。站点支持邮箱，页脚/出错提示等位置展示，也是无人回复邮件缺省时的发件地址兜底。
  • 实测：设 admin@example.com 通过；不给则列入启动校验失败清单。

2.4 NEXT_PUBLIC_BASE_URL（必需）

  • 定义：z.url()（env.ts:228）。站点对外访问地址，决定验证码邮件里的链接、OAuth 回调、分享链接的域名。
  • 旧名映射：4.0 之前的版本叫 NEXT_PUBLIC_URL。实测给 4.16.2 传 NEXT_PUBLIC_URL 会被静默忽略（服务 200 启动、无警告），链接仍按 NEXT_PUBLIC_BASE_URL 生成——从旧版升级必须改名。
  • 实测值示例：http://127.0.0.1:8133（本机验证）或 https://rallly.example.com（生产域名）。

三、认证与访问控制

变量默认说明
EMAIL_LOGIN_ENABLEDtrue是否允许邮箱验证码登录。false 时只留第三方登录入口（实测变量为枚举 "true"/"false"，env.ts:74）
REGISTRATION_ENABLEDtrue是否开放新用户注册（env.ts:75）。内网固定用户群可设 false 防止陌生人注册
ALLOWED_EMAILS空（不限制）邮箱白名单（env.ts:73），逗号分隔；配合 REGISTRATION_ENABLED 做准入控制
GOOGLE_LOGIN_ENABLED / MICROSOFT_LOGIN_ENABLED未定义v4.16.1 新增：关闭 Google/Microsoft 登录按钮（仅隐藏入口，不影响日历/会议集成，4.16.1 release notes 溯源）

OIDC 单点登录（8 项，均应用层）

变量默认说明
OIDC_NAMEOpenID Connect登录按钮显示名（env.ts:29）
OIDC_DISCOVERY_URL空IdP 发现端点（/.well-known/openid-configuration），配置 OIDC 的主开关（env.ts:30）
OIDC_CLIENT_ID / OIDC_CLIENT_SECRET空客户端凭证（env.ts:31-32）
OIDC_ISSUER_URL空签发者 URL 校验（env.ts:33）
OIDC_EMAIL_CLAIM_PATHemail从 id_token 取邮箱的 claim 路径（env.ts:34）
OIDC_NAME_CLAIM_PATHname显示名 claim 路径（env.ts:35）
OIDC_PICTURE_CLAIM_PATHpicture头像 claim 路径（env.ts:36）

文档溯源（官方 SSO 分册）：OIDC 配置后登录页出现对应按钮，首次登录自动建号。

四、SMTP 邮件（8 项 + 2 项废弃）

变量默认说明
SMTP_HOST空SMTP 服务器地址；不配置时应用照常启动（实测），但验证码邮件无法投递、等于无法登录
SMTP_PORT空端口，典型 587（STARTTLS）/465（隐式 TLS）/25（内网明文）（env.ts:50）
SMTP_SECURE空"true"=隐式 TLS（465），"false"=STARTTLS 或明文（env.ts:49）
SMTP_USER / SMTP_PWD空认证凭证（env.ts:47-48）
SMTP_REJECT_UNAUTHORIZED空"false" 时容忍自签证书（env.ts:51，内网自建 SMTP 常用）
SMTP_TLS_ENABLED空废弃：注释标记 @deprecated Use SMTP_REJECT_UNAUTHORIZED instead（env.ts:52-53）
SMTP_DEBUG空废弃：调试输出开关（env.ts:55），新版勿用

实测：SMTP_HOST=mailpit（内网 1025、SMTP_SECURE=false）时验证码邮件秒级送达，邮件正文含 6 位码与 15 分钟有效期说明；SMTP 配置错误时应用日志无显性报错、邮件静默丢失，排查时优先怀疑网络可达性而非参数名（实录见部署篇 §7.4）。

五、邮件地址与站点品牌

变量默认说明
NOREPLY_EMAIL空（回落 SUPPORT_EMAIL）系统邮件发件地址（env.ts:80）
NOREPLY_EMAIL_NAMERallly发件人显示名（env.ts:81），实测邮件头 From: Rallly <admin@example.com>
APP_NAMERallly站点名称（env.ts:144），浏览器标题与管理界面品牌位
HIDE_ATTRIBUTIONfalse隐藏页脚 "Powered by Rallly"（env.ts:167）。企业授权功能：无有效 license 时设置不生效（官方 licensing 分册溯源；源码 features/branding 读取该值）

注意：4.x 不再通过环境变量配置 Logo 与主题色（旧版 LOGO_URL/PRIMARY_COLOR 已移入管理控制面板的实例设置，配置在数据库中，源码 features/branding/loaders.ts 实查）。

六、存储与限流

变量默认说明
S3_ENDPOINT空S3 兼容端点（env.ts:87）。官方捆绑栈指向内部 Garage；也可用 MinIO/阿里云 OSS 等任何 S3 兼容服务
S3_BUCKET_NAME空桶名（env.ts:86）
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY空访问凭证（env.ts:88-89）
S3_REGION空区域（env.ts:90，多数 S3 兼容实现填 us-east-1）
RATE_LIMIT_ENABLEDtrue内置限流开关（env.ts:172）。实测源码：投票创建类操作限 20 次/天/IP（createRateLimitMiddleware("create_poll", 20, "1 d")），被限流返回 429
LICENSE_API_URL / LICENSE_API_AUTH_TOKEN空企业授权校验端点（env.ts:108-109，仅企业部署需要）

七、栈层变量（官方安装器 .env）

以下变量由 rallly.sh 与官方 Compose 文件消费（官方栈仓库 .env.example 溯源，查询日期 2026-10-24），不在应用 env.ts 中：

变量默认说明
DOMAIN空站点域名（bundled 反代模式的虚拟主机与证书域名）
ACME_EMAIL空Let's Encrypt 证书通知邮箱
WEB_PORT0.0.0.0:80应用监听端口。实测 external 反代模式设 0.0.0.0:8138 正常
PROXY_MODEbundled反代模式：bundled（内建 Traefik，占用 80/443）/ external（外部反代，仅暴露应用端口）。实测 external 下 Traefik 服务被跳过
POSTGRES_VERSION18（全新安装）捆绑 PostgreSQL 大版本；实测 rallly.sh start 输出 Provisioning PostgreSQL 18
GARAGE_RPC_SECRET安装器生成捆绑 Garage(S3) 的集群密钥，必须 32 字节随机十六进制（64 个 hex 字符）。实测填普通字符串触发重启循环，报错实录：Error: Invalid RPC secret key: expected 32 bytes of random hex, please check the documentation for requirements；openssl rand -hex 32 生成即可
POSTGRES_PASSWORD安装器自动生成捆绑数据库密码。手动照抄官方栈文件自建时漏配会触发 PostgreSQL 初始化失败（实录：Database is uninitialized and superuser password is not specified）
RALLLY_IMAGElukevella/rallly:4应用来源，升级大版本时改这里
CA_CERT_FILE空出网走自签 CA 时的信任证书路径（官方 corporate-networks 分册溯源）
INITIAL_ADMIN_EMAIL空认领管理控制面板管理员的邮箱。应用层实际读取（源码 features/instance-settings/utils.ts 比对登录邮箱小写一致），首次部署后可移除

八、废弃与改名对照（升级迁移必查）

旧变量（≤4.15 或更早）4.16 现状处置
NEXT_PUBLIC_URL改名 NEXT_PUBLIC_BASE_URL实测旧名被静默忽略，必须改名
SMTP_TLS_ENABLED废弃源码 @deprecated 注释，改用 SMTP_REJECT_UNAUTHORIZED
SMTP_DEBUG废弃源码 @deprecated 注释，新版无效果
LOGO_URL / PRIMARY_COLOR 等移除（迁移到管理面板）在 /admin-setup → 实例设置里配置，存数据库
GOOGLE_LOGIN_ENABLED / MICROSOFT_LOGIN_ENABLED新增（v4.16.1）控制登录按钮显隐，不影响集成功能

九、参数速查（应用层 24 项）

必需   : DATABASE_URL, SECRET_PASSWORD, SUPPORT_EMAIL, NEXT_PUBLIC_BASE_URL
认证   : EMAIL_LOGIN_ENABLED, REGISTRATION_ENABLED, ALLOWED_EMAILS,
         GOOGLE_LOGIN_ENABLED, MICROSOFT_LOGIN_ENABLED,
         OIDC_NAME, OIDC_DISCOVERY_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET,
         OIDC_ISSUER_URL, OIDC_EMAIL_CLAIM_PATH, OIDC_NAME_CLAIM_PATH, OIDC_PICTURE_CLAIM_PATH
邮件   : SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, SMTP_PWD,
         SMTP_REJECT_UNAUTHORIZED, NOREPLY_EMAIL, NOREPLY_EMAIL_NAME
品牌   : APP_NAME, HIDE_ATTRIBUTION
存储   : S3_ENDPOINT, S3_BUCKET_NAME, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_REGION
其他   : RATE_LIMIT_ENABLED, LICENSE_API_URL, LICENSE_API_AUTH_TOKEN

十、相关文档