Reactive Resume 6.0.8 配置参数详解

目标：把 Reactive Resume v6.0.8 服务端可读的每一个环境变量讲清——哪些必填、默认值是什么、改了之后如何观测是否真的生效。本文以 Ubuntu 22.04 + Reactive Resume 6.0.8 + PostgreSQL 18 的实测实例（应用监听 8150 端口，部署过程见《Reactive Resume 6.0.8 部署指南》）为基准，变量清单与默认值逐条对照官方 docs/self-hosting/environment-variables.mdx（查询日期 2026-10-29），「改参 → 重启 → 观测」回路的命令与回显均为实测照抄。

一、环境信息

Reactive Resume 的配置面是纯环境变量：服务端启动时从进程环境读取全部设置（源码部署形态才额外加载工作区根目录的 .env 文件，且环境变量优先于文件），没有任何管理后台配置页。这意味着所有配置变更都是「改文件 → 重启进程」一个动作链。

二、前置条件

1. 已按部署指南完成 v6.0.8 实例部署并能打开 GET /api/health（返回 healthy）；
2. 能编辑服务器上的 /opt/reactive-resume/.env 文件；
3. 会用 openssl rand -hex 32 生成随机密钥（Ubuntu 22.04 自带 openssl）；
4. 了解实例的访问地址（本文 http://localhost:8150，读者按自己的 APP_URL 替换）。

三、参数查看与修改方式

3.1 查看当前生效配置

Reactive Resume 没有「打印全部配置」的调试开关，但提供了一个公开的能力开关回显端点 GET /api/openapi/flags，它把关键配置的解析结果序列化为 JSON，是判断配置是否生效最直接的观测面。实测基线（未做任何可选配置的新实例）：

curl -s http://localhost:8150/api/openapi/flags

{"disableSignups":false,"disableEmailAuth":false,"allowGuestLogin":false,"smtpEnabled":false,"careerSchedulingEnabled":true,"appUrl":"http://localhost:8150","customDomains":false,"olacvSuggestion":false}

字段与配置的对应关系：disableSignups ← FLAG_DISABLE_SIGNUPS、disableEmailAuth ← FLAG_DISABLE_EMAIL_AUTH、allowGuestLogin ← FLAG_ENABLE_GUEST_LOGIN、smtpEnabled ← 四项 SMTP_* 是否配齐、appUrl ← APP_URL 原值回显、customDomains ← 自定义域名变量是否设置。健康端点则负责另一类观测——storage.type 会显示当前存储后端（实测 local），配置了 Redis 时会出现 redis 字段。

3.2 修改参数的标准动作

1. 编辑 /opt/reactive-resume/.env，新增或修改变量行；
2. 重启应用服务使新环境变量注入（命令见《Reactive Resume 6.0.8 部署指南》第十章；仅重启应用，数据库不动）；
3. 用 GET /api/openapi/flags 或 GET /api/health 观测新值是否生效。

下面用一次完整实测闭环演示（FLAG_ENABLE_GUEST_LOGIN，登录页显示「以来宾身份继续」按钮）：

echo 'FLAG_ENABLE_GUEST_LOGIN=true' >> /opt/reactive-resume/.env
# 重建应用服务后观测
curl -s http://localhost:8150/api/openapi/flags

{"disableSignups":false,"disableEmailAuth":false,"allowGuestLogin":true,"smtpEnabled":false,"careerSchedulingEnabled":true,"appUrl":"http://localhost:8150","customDomains":false,"olacvSuggestion":false}

allowGuestLogin 由 false 变 true，配置生效。删除该行、再次重建后实测回到 false——改配置排障时必须做「开与关」两个方向的验证，只测打开方向容易把中间态当最终态。

3.3 值解析规则（官方口径，决定怎么写才有效）

3.4 启动校验实测：短密钥会被拒绝

把 AUTH_SECRET 改成 8 字符的 short123 后重建服务，进程直接退出进入重启循环，日志明确点名变量（实测回显）：

❌ Invalid environment variables: [
    path: [ 'AUTH_SECRET' ],
    message: 'AUTH_SECRET must be at least 32 characters in production. Generate one with openssl rand -hex 32.'
Error: Invalid environment variables

恢复正确密钥后重建，服务回到 healthy。这条实测说明：生产模式下必填密钥的格式校验是硬门槛，配置错误不会「带病运行」，而是拒绝启动——排障时第一时间看应用日志而不是反复重启。

四、参数总览

按功能域分组的全量参数索引（默认值均为官方文档口径，查询日期 2026-10-29）：

💡 技术拓展：Web 应用的「配置承载方式」常见三种——环境变量（12-Factor 风格）、配置文件（YAML/TOML）、数据库存储（管理后台可改）。Reactive Resume 选择环境变量单轨制：优点是配置即部署产物、可随编排文件版本化、没有「后台改了配置忘了同步到代码库」的漂移问题；代价是每次改动都要重启进程、没有运行时热更新。与之相对，数据库型配置（如 GitLab 的管理区）适合多租户频繁变更的场景，环境变量型更适合自托管实例的低频运维节奏。

五、核心参数分类详解

5.1 必填参数（缺一拒绝启动）

三者是整个配置面的地基。APP_URL 与实际访问地址不符是最常见的自托管故障（登录回跳错位、Cookie 不生效、公开页链接错误都源于此）。

5.2 服务与监听

5.3 数据库

5.4 登录认证

邮箱密码注册默认开启。以下均为可选增强：

5.5 邮件

发送开关是四项同时配齐（SMTP_HOST、SMTP_USER、SMTP_PASS、SMTP_FROM）才触发；未配齐时验证/重置邮件不发送、内容写入应用日志。实测未配置 SMTP 的实例在 /api/openapi/flags 中回显 "smtpEnabled":false，注册后日志出现 SMTP not configured; skipping email send. { to: 'admin@example.com', subject: 'Verify your email' }。

5.6 存储后端

两个实测相关事实：本地存储形态下健康检查回显 "storage":{"type":"local","status":"healthy",...}；上传限制为普通文件 10 MB、助手附件 25 MB。切换存储后端不会自动迁移已有文件，需自行拷贝并保持对象键一致。

5.7 AI 与 Redis

服务端配置了共享 AI 供应商时优先于个人配置（设置页显示「由服务器提供」并拒绝个人改动）。Redis 未配置时单实例功能完整，仅三处降级：助手被刷新打断的回复不可恢复、限流/停止按钮/每小时公开访问去重落在单进程内存、实时更新回退 PostgreSQL LISTEN/NOTIFY。多实例部署必须配置 Redis。AI 供应商与助手会话存于 PostgreSQL，不依赖 Redis。

5.8 求职调度与网络访问

5.9 域名扩展

5.10 特性开关（8 项，默认全部 false）

⚠️ 两个 FLAG_ALLOW_UNSAFE_* 只应在全员可信的实例上开启：不安全的 AI base URL 会让用户诱导服务器访问内网地址，不安全的回调地址可用于钓鱼或窃取令牌。

六、生产配置模板

两档按规模划分的 .env 模板（变量值替换为自己的密钥与地址）：

单人/家庭实例（1 vCPU / 2 GB 内存 / 10 GB 磁盘，本栏为本文实测形态）：

APP_URL=https://resume.example.com
POSTGRES_PASSWORD=q1w2e3r4
DATABASE_URL=postgresql://postgres:q1w2e3r4@postgres:5432/postgres
AUTH_SECRET=<openssl rand -hex 32 生成>
ENCRYPTION_SECRET=<openssl rand -hex 32 生成>
FLAG_DISABLE_SIGNUPS=true

要点：单人自用建完自己的账号后关闭注册；存储用默认 local（数据卷），不配 Redis、SMTP 可后补。

小团队实例（2 vCPU / 4 GB 内存 / 40 GB 磁盘，启用邮件 + 共享存储 + 来宾模式）：

APP_URL=https://resume.example.com
POSTGRES_PASSWORD=q1w2e3r4
DATABASE_URL=postgresql://postgres:q1w2e3r4@postgres:5432/postgres
AUTH_SECRET=<openssl rand -hex 32 生成>
ENCRYPTION_SECRET=<openssl rand -hex 32 生成>
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASS=<SMTP 密码>
SMTP_FROM=Reactive Resume <noreply@example.com>
SMTP_SECURE=false
STORAGE_BACKEND=s3
S3_ACCESS_KEY_ID=<访问键>
S3_SECRET_ACCESS_KEY=<秘密键>
S3_BUCKET=reactive-resume
S3_ENDPOINT=http://<内网S3主机>:8333
S3_FORCE_PATH_STYLE=true
REDIS_URL=redis://<内网Redis主机>:6379
STRICT_SCHEMA_CHECK=true
DATABASE_POOL_MAX=20

要点：S3 自托管网关必须 S3_FORCE_PATH_STYLE=true；配了 Redis 才支持多实例与限流跨进程共享；STRICT_SCHEMA_CHECK=true 让版本升级后的 schema 漂移直接拦在启动阶段；团队实例保留注册开放，靠邮箱验证 + 限流管理。

七、常见问题（FAQ）

Q1：改了 .env 但行为没变化？ 按顺序核对：环境变量是否被进程环境中的同名变量覆盖（环境优先于文件）；布尔值是否用了非法写法（只认 true/false/1/0/yes/no/on/off）；是否漏了重建应用服务（改文件不重启不生效）。最后用 GET /api/openapi/flags 观测——实测 FLAG_ENABLE_GUEST_LOGIN 开与关两轮，allowGuestLogin 精确跟随（见 3.2 节）。

Q2：服务起不来，日志报 Invalid environment variables？ 启动校验拦截，报错会点名变量与原因。实测将 AUTH_SECRET 改为 8 字符即触发 AUTH_SECRET must be at least 32 characters in production. Generate one with openssl rand -hex 32.（3.4 节回显）。按报错修改变量后重建即可。

Q3：注册/重置密码的邮件收不到？ 四项 SMTP_HOST/SMTP_USER/SMTP_PASS/SMTP_FROM 必须全部设置才会真正发信。未配齐时邮件写日志（实测回显见 5.5 节），日志里 SMTP not configured; skipping email send 即此因。配齐后仍发不出，核对 SMTP_PORT/SMTP_SECURE 与供应商设置是否匹配（465 用 SMTP_SECURE=true，587 用 false）。

Q4：接自建 MinIO/SeaweedFS 后上传报 getaddrinfo ENOTFOUND bucket.endpoint？ 应用按虚拟主机风格寻址把桶名拼进了主机名。设置 S3_FORCE_PATH_STYLE=true（官方排障节同款结论），自托管 S3 网关一律需要。

Q5：/api/health 的 storage 显示 unhealthy？ 本地存储形态检查挂载目录是否可被 UID 1000 写入；S3 形态检查凭据、桶名与端点。检查超时可调 STORAGE_HEALTHCHECK_TIMEOUT_MS（默认 5000 毫秒）。实测正常实例回显 "storage":{"type":"local","status":"healthy"}。

Q6：想临时限制只允许已有人使用，但又想用来宾模式做演示？ 两者冲突：FLAG_DISABLE_SIGNUPS=true 会同时关闭来宾入口（官方明确「Has no effect while FLAG_DISABLE_SIGNUPS is true」指向来宾）。演示期先只开 FLAG_ENABLE_GUEST_LOGIN=true，演示结束再改关注册。

八、参考链接

• 官方环境变量参考（本文变量口径来源）：https://github.com/reactive-resume/reactive-resume/blob/main/docs/self-hosting/environment-variables.mdx
• GitHub 仓库：https://github.com/reactive-resume/reactive-resume
• 相关篇目：《Reactive Resume 介绍与选型指南》 · 《Reactive Resume 6.0.8 部署指南》 · 《Reactive Resume 6.0.8 API 使用详解》