rConfig 8.2.19 配置参数详解

目标：讲清 rConfig V8 Core 8.2.19 的两层配置体系（.env 文件态参数与数据库 settings 表态配置）、全部常用参数的含义与实测默认值、修改后的生效操作，并给出两档生产配置模板。文中参数值与命令回显均在 Ubuntu 22.04.5 LTS 实测环境（rConfig 8.2.19 + PHP 8.4.27 + MariaDB 11.2.6 + Redis 6.0.16）采集。

一、环境信息

本文写作基于以下实测环境，参数表中「实测值」列即来自该环境：

💡 说明：.env.example 中带 [EDIT]/[OPTIONAL]/[DO NOT EDIT] 三类标注——这是官方给出的修改指引，本文第五章按此口径组织：[EDIT] 建议按部署调整，[OPTIONAL] 启用相关功能才设置，[DO NOT EDIT] 保持默认（改错会破坏应用或升级流程）。

二、前置条件

1. 已按《rConfig 8.2.19 Ubuntu 22.04 安装指南》完成安装（本文所有路径、服务名、账号体系与该篇一致）；
2. 能以 root 或具备 sudo 权限的账号登录服务器；
3. 数据库专用账号 rconfig_user 可连 rconfig 库（用于查看 settings 表）；
4. 了解 Laravel 配置缓存机制的基本概念——rConfig 的 .env 修改必须配合缓存重建才生效，详见 3.3 节实测。

💡 技术拓展：Laravel 应用的「配置缓存」是把全部配置合并编译成一个 PHP 文件（bootstrap/cache/config.php），运行时直接加载它而不再逐个读取 .env，以此减少每次请求的文件读取开销。代价是 .env 的后续修改对已缓存的配置不可见，必须重建缓存。rConfig 官方把重建动作封装成 php artisan rconfig:clear-all（清空后立即重建，见 3.3 节实测输出）。

三、参数查看与修改方式

3.1 两层配置体系

rConfig 的运行配置分两层，修改入口不同：

两层有交叠（如时区、邮件），优先级关系在对应参数小节说明。

3.2 .env 查看与当前生效值核对

查看文件内容：

grep -vE "^#|^$" /var/www/html/rconfig/.env

实测回显（输出节选，实测首尾；APP_KEY 与 REDIS_PASSWORD 为安装时自动生成的随机值，此处脱敏）：

APP_NAME="rConfig V8 Core - Network Configuration Management"
APP_ENV=production
APP_KEY=base64:9Za3****（自动生成，脱敏）
APP_DEBUG=false
APP_URL="http://rconfig-lab"
APP_FORCE_HTTPS=false
APP_DIR_PATH=/var/www/html/rconfig
LOG_CHANNEL=daily
LOG_LEVEL=warning
DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=rconfig
DB_USERNAME=rconfig_user
DB_PASSWORD=q1w2e3r4
BROADCAST_DRIVER=log
CACHE_DRIVER=redis
CACHE_PREFIX=rConfigp
HORIZON_PREFIX=rConfig
HORIZON_LOCAL_TIMEOUT=120
HORIZON_PROD_TIMEOUT=120
HORIZON_MIN_PROCESS=1
HORIZON_MAX_PROCESS=10
HORIZON_DEFAULT_MAX_PROCESS=5
QUEUE_CONNECTION=redis
QUEUE_DRIVER=redis
SESSION_DRIVER=redis
SESSION_LIFETIME=120
REDIS_QUEUE_RETRY_AFTER=130
REDIS_HOST=localhost
REDIS_PASSWORD=44d7****（安装向导自动生成，脱敏）
REDIS_PORT=6379
RCONFIG_API_TOKEN=V8Core
RCONFIG_SUB_ID="V8Core"
RCONFIG_SUB_NAME="V8Core"
RCONFIG_SUB_STATUS="Active"
RCONFIG_SUB_EXPIRY="N/A"
TIMEZONE=Europe/Dublin
MASK_DEVICE_CREDENTIALS=false
MAIL_FROM_ADDRESS=
MAIL_FROM_NAME=rConfig

核对「当前实际生效值」比看文件更可靠（文件与生效值可能因缓存不一致，见 3.3 节）。Laravel 提供 config:show 命令：

cd /var/www/html/rconfig
php artisan config:show app

实测回显（输出节选，实测首尾）：

  app ........................................................................
  name .................... rConfig V8 Core - Network Configuration Management
  env ............................................................. production
  debug ................................................................ false
  url ..................................................... http://rconfig-lab
  timezone ..................................................... Europe/Dublin
  locale .................................................................. en
  cipher ......................................................... AES-256-CBC
  key .................... base64:9Za3****（脱敏）

数据库连接生效值：

php artisan config:show database

实测回显（输出节选，实测首部）：

  database ...................................................................
  default .............................................................. mysql
  connections ⇁ sqlite ⇁ driver ....................................... sqlite
  connections ⇁ sqlite ⇁ database .................................... rconfig

💡 说明：config:show database 会列出全部连接定义（含 sqlite 等未使用的默认连接），重点看 connections ⇁ mysql ⇁ 段的 host/port/database/username 是否与 .env 一致。

3.3 修改 .env 后的生效操作（实测）

修改 .env 后必须重建配置缓存。rConfig 官方把「清空 + 重建 + 队列重启」封装成一条命令：

cd /var/www/html/rconfig
php artisan rconfig:clear-all

实测回显（完整）：

  ------  Begin rConfig Laravel Clear Out!  ------
------  Config Cleared!  ------
------  Cache Cleared!  ------
------  Routes Cleared!  ------
------  Views Cleared!  ------
------  Config Cached!  ------
------  Routes Cached!  ------
------  Views Cached!  ------
------  Optimized!  ------
------  Queues Restarted!  ------
------  Horizon Restarted!  ------

输出顺序说明：先清空（Config/Cache/Routes/Views Cleared），再重建（Cached），最后重启队列与 Horizon——所以该命令执行完即全部生效，无需再手动重启队列。

以修改 APP_NAME 为例的完整实测流程：

cd /var/www/html/rconfig
# 1. 修改 .env
sed -i 's|APP_NAME="rConfig V8 Core - Network Configuration Management"|APP_NAME="rConfig V8 Core - CMDB Lab"|' .env
grep "^APP_NAME" .env
# 2. 重建缓存
php artisan rconfig:clear-all >/dev/null 2>&1
# 3. 核对生效值
php artisan config:show app | grep -w name

实测回显：

APP_NAME="rConfig V8 Core - CMDB Lab"
  name ............................................ rConfig V8 Core - CMDB Lab

恢复原值并再次重建后，config:show app 回到原值（实测验证，回显同上形态）。

⚠️ 注意：跳过第 2 步直接访问 Web 或观察队列，看到的仍是旧配置——因为 Web 进程与 Horizon 加载的是缓存。安装向导最后的 Optimize 步骤、每次 rconfig:clear-all 都会重建缓存；凡是在这之后手工改过 .env，都必须再执行一次 rconfig:clear-all。这个坑的典型事故（Redis 密码写入 .env 后未重建缓存导致队列 NOAUTH 报错）已在《rConfig 8.2.19 Ubuntu 22.04 安装指南》第九章 Q4 完整实录。

3.4 System Settings（数据库态）的查看与修改

Web 控制台依次进入 Settings 页面即可查看与修改数据库态配置（登录横幅、时区、邮件、默认设备凭据等），保存即写库，无需清缓存。

命令行查看底层存储（settings 表为单行记录，id=1）：

mysql -u rconfig_user -pq1w2e3r4 rconfig -e "SELECT * FROM settings\G" | head -40

实测回显（输出节选，实测首尾；部分字段有删节）：

                         id: 1
             login_banner: Authorization message - You must be an authorized user to login and use this system.
                 timezone: Europe/Dublin
                mail_host: devmailer.rconfig.com
                mail_port: 1025
          mail_from_email: admin@domain.com
            mail_to_email: user@domain.com
              mail_driver: smtp
        passwordEncryption: 1
           deviceDebugging: 0
              phpDebugging: 1
   config_compare_settings: {"context":3,"ignoreCase":false,"ignoreLineEnding":false,"ignoreWhitespace":false,"lengthLimit":20000}

字段含义要点：

• login_banner：登录页顶部横幅文字（默认就是上述授权声明）；
• timezone：与 .env 的 TIMEZONE 保持一致（建议两处同步修改）；
• mail_* 系列：发件服务器配置，运行时以这里为准（.env 中被注释的 MAIL_* 仅作参考，见 5.9 节）；
• passwordEncryption：设备凭据加密存储开关（实测为 1，启用）；
• config_compare_settings：配置比对参数（上下文行数 3、是否忽略大小写/行尾/空白、长度上限 20000），在 Web 端 Config Diff 设置中修改；
• config_compare_exclusion_file：比对时的全局排除正则清单（默认排除 Current configuration...、Last configuration change... 等每次下载都会变化的行）。

四、参数总览

.env.example 全量键按功能分组一览（「标注」列为官方 .env.example 给出的修改指引）：

⚠️ 注意：官方 .env.example 对 DB_HOST/DB_DATABASE 等键的默认值是占位词（DBHOST/DBNAME/DBUSER/DBPASS），首次安装时必须替换为真实值（安装指南 6.2 节已给出实测示例）；上表「默认值」列对这几个键写的是占位词本身。

五、核心参数分类详解

5.1 应用基础（APP_*）

APP_NAME：应用显示名，出现在浏览器标题、UI 与邮件中。改后需 rconfig:clear-all 生效（3.3 节已实测）。

APP_ENV：production / local 二选一。影响 Horizon 环境选择（config/horizon.php 按 production/local 两套定义队列），生产必须保持 production。

APP_KEY：base64: 前缀的 32 字节密钥，由安装向导生成。设备凭据、数据库中加密字段的解密都依赖它——一旦丢失，所有已存储的设备密码将无法解密。官方文档明确提供 System Encryption Key 备份机制，务必在 Settings 中导出保管。

APP_DEBUG：true 时浏览器直接显示异常堆栈。排障时可临时开启，看完立即改回 false（配合 rconfig:clear-all）。

APP_URL：对外访问地址，影响页面生成的所有链接与邮件中的链接。使用 HTTPS 证书时写成 https:// 形式。

APP_FORCE_HTTPS：部署在 TLS 卸载的代理后面时设 true，强制生成的 URL 用 https。rConfig 自带的 rconfig:ssl-self-signed 命令会自动把 APP_URL 更新为 https 形式。

5.2 日志（LOG_*）

LOG_CHANNEL=daily：按天写 storage/logs/laravel-YYYY-MM-DD.log（实测文件名 laravel-2026-10-28.log）。

LOG_LEVEL=warning：日志级别。排障时可临时改 info 甚至 debug（改后 rconfig:clear-all），排查完改回 warning，否则日志增长很快。

5.3 数据库（DB_*）

DB_HOST/DB_PORT/DB_DATABASE/DB_USERNAME/DB_PASSWORD 五键即安装时创建的库与账号（实测值 localhost/3306/rconfig/rconfig_user）。修改后除 rconfig:clear-all 外无需重启数据库。

⚠️ 注意：DB_PASSWORD 在 .env 中是明文。请确保该文件权限收紧（默认 root 属主 644 属可接受范围；更严格可设 600），且不要把 .env 提交到任何代码仓库。

5.4 缓存、队列与会话（CACHE_/QUEUE_/SESSION_/BROADCAST_）

rConfig 官方调优基线是 Redis 全家桶：CACHE_DRIVER=redis、QUEUE_CONNECTION=redis、SESSION_DRIVER=redis，三者不要改成 file/database 等其他驱动（改动会失去 Horizon 兼容与官方支持口径）。CACHE_PREFIX=rConfigp 是缓存键前缀，多实例共用一个 Redis 时用它隔离。SESSION_LIFETIME=120 是会话寿命（分钟），即 Web 登录后 2 小时无操作过期。REDIS_QUEUE_RETRY_AFTER=130 必须大于最长的单个任务执行时长（见 5.5 节 HorizonTwo 的 86400 秒长任务说明），否则长任务执行中会被当作失联重新入队。

5.5 Horizon 队列进程（HORIZON_*）

Horizon 是 Laravel 的队列管理器，rConfig 用 Supervisor 把它拉起为常驻进程（见安装指南 6.4 节）。队列拓扑在 config/horizon.php 中按环境定义，实测 production 环境有两个 supervisor：

两个 supervisor 的最小进程数都用 HORIZON_MIN_PROCESS（实测 1），balance 策略为 auto（按负载在 min~max 之间自动伸缩）。参数含义与调优建议：

• HORIZON_MIN_PROCESS=1：每队列常驻 1 个进程，空闲时最小资源占用；
• HORIZON_MAX_PROCESS=10：设备下载并发上限的调节旋钮——批量下载几百台设备时调大可缩短总时长，代价是同时打开更多设备连接与内存；建议 4vCPU/8GB 服务器不超过 10；
• HORIZON_DEFAULT_MAX_PROCESS=5：合规检查类任务的并发上限，CPU 密集度高于下载，保持 5 即可；
• HORIZON_PROD_TIMEOUT=120：HorizonOne 中单任务超时（秒），超时的任务标记失败；不要设得比 REDIS_QUEUE_RETRY_AFTER（130）更大；
• HORIZON_LOCAL_TIMEOUT=120：APP_ENV=local 时的对应超时，生产不生效；
• HORIZON_PREFIX=rConfig：Horizon 在 Redis 中的键前缀，同机多套 rConfig 共用一个 Redis 时必须区分。

修改任一 HORIZON_* 后：rconfig:clear-all（其输出已包含 Horizon Restarted，见 3.3 节）。

验证队列工作状态：

supervisorctl status rconfig-core-horizon

实测回显：

rconfig-core-horizon             RUNNING   pid 21675, uptime 0:17:30

5.6 Redis 连接（REDIS_*）

REDIS_HOST/REDIS_PORT：Redis 地址与端口，本机默认 localhost:6379。

REDIS_PASSWORD：Redis 访问密码，由安装向导的 Securing Redis 步骤自动生成（64 位十六进制随机串）并同步设置到 Redis 服务端，.env.example 中默认值为 null（表示未加固状态）。勿手工置空或随意改动；改动时必须同时改 Redis 服务端。最稳妥的方式是用官方命令重新生成并下发：

cd /var/www/html/rconfig
php artisan rconfig:redis-secure

核验服务端密码与 .env 一致（值处脱敏，实测两者相同）：

redis-cli -a "$(grep '^REDIS_PASSWORD=' .env | cut -d= -f2)" CONFIG GET requirepass

实测回显（输出节选，密码值脱敏）：

requirepass
44d7****（与 .env 中 REDIS_PASSWORD 相同的 64 位随机串）

5.7 凭据显示与配置文件权限（MASK_DEVICE_CREDENTIALS/RCONFIG_CONFIG_*）

MASK_DEVICE_CREDENTIALS=false：设为 true 后，非特权操作员在 Web 界面上看到的设备密码/enable 密码以掩码显示，防止低权限人员窥屏获得设备凭据。管理员仍可在明文查看。

RCONFIG_CONFIG_FILE_MODE=0440 与 RCONFIG_CONFIG_DIR_MODE=0750（默认注释，即默认生效值就是 0440/0750）：下载到本地的设备配置文件与存放目录的权限。官方注释明确说明设计意图——配置文件里含设备凭据，默认对「其他人」零授权；且强调目录权限同样重要（0440 的文件放在 0755 目录里仍可能被本地账号沿目录读到）。修改后只对新写入的文件生效，存量文件用以下命令刷新：

cd /var/www/html/rconfig
php artisan rconfig:set-config-permissions

实测验证（本机已下载的配置文件，权限 0440）：

find /var/www/html/rconfig/storage/app/rconfig/data -type f -name "*.txt" | head -3 | xargs stat -c "%a %n"

实测回显：

440 /var/www/html/rconfig/storage/app/rconfig/data/Routers/lab-router-01/2026/Oct/28/showrun_033.txt
440 /var/www/html/rconfig/storage/app/rconfig/data/Routers/lab-router-01/2026/Oct/28/showver_034.txt
440 /var/www/html/rconfig/storage/app/rconfig/data/Routers/lab-router-01/2026/Oct/28/showipintbrief_035.txt

5.8 健康检查 Ping（HEALTHCHECK_*）

rConfig 仪表盘内置健康检查，其中连通性检查默认会 ping 外部目标。四个可覆盖项（默认注释即默认行为）：

• HEALTHCHECK_PING_ENABLED=false：关闭全部连通性 ping 检查；
• HEALTHCHECK_OFFLINE_MODE=true：声明环境离线，自动跳过 ping 检查；
• HEALTHCHECK_AIR_GAPPED=true：声明物理隔离环境，效果同上；
• HEALTHCHECK_PING_TARGET=http://127.0.0.1 与 HEALTHCHECK_PING_TIMEOUT=5：把探测目标改为内网地址并设定超时秒数。

⚠️ 注意：隔离内网（无法出公网）部署 rConfig 时，仪表盘会持续出现外网连通性检查失败告警，按官方口径设置 HEALTHCHECK_OFFLINE_MODE=true 或指定内网 HEALTHCHECK_PING_TARGET 即可消除，改后 rconfig:clear-all 生效。

5.9 邮件（MAIL_*）

.env 中 MAIL_DRIVER 等 SMTP 参数在运行时不生效——官方 .env.example 注释明确写着「Mail settings are managed in the settings table (cached as mail_settings)，这些 .env 值仅供参考」。实际生效的是 Settings 页面（即 settings 表）中的邮件配置，实测默认值：mail_host=devmailer.rconfig.com、mail_port=1025、mail_driver=smtp（官方开发用默认值，生产必须改成自己的 SMTP 服务器）。

.env 中真正生效的只有发件人两项：MAIL_FROM_ADDRESS（备份通知的发件地址）与 MAIL_FROM_NAME=rConfig（发件人名）。健康检查告警邮件则走 Settings 邮件配置加每个用户的通知偏好（Health Check Failed / Recovered）。

5.10 单点登录 SSO（MICROSOFT_/OKTA_/SAML2_*）

三类企业 SSO 均为 [OPTIONAL]，不配置则只用本地账号密码登录（本文实测即本地登录形态）：

⚠️ 注意：SAML2_SP_PRIVATE_KEY 与 MICROSOFT_CLIENT_SECRET 属于真实密钥，写入 .env 时该文件已含数据库密码等敏感信息，务必收紧文件权限（见 5.3 节）。

5.11 订阅标识与内部参数（RCONFIG_/ENLIGHTN_）

RCONFIG_API_TOKEN=V8Core、RCONFIG_SUB_ID/RCONFIG_SUB_NAME/RCONFIG_SUB_STATUS/RCONFIG_SUB_EXPIRY 是开源 Core 版的订阅标识常量（状态 Active、有效期 N/A），全部 [DO NOT EDIT]——它们不是许可证密钥，Core 版本身免费，改了也不会变成 Pro。ENLIGHTN_SKIP_ENVIRONMENT_SPECIFIC=false 服务于 Enlightn 安全/性能扫描器，保持默认。

六、生产配置模板

以下模板基于参数语义给出（未经大规模基准测试，仅作部署起点），落地后均需执行 php artisan rconfig:clear-all 生效。

6.1 模板一：小规模部署（≤50 台设备，4GB 内存 / 2 vCPU / 40GB 磁盘）

在默认值基础上仅需确认/调整以下键，其余全部保持安装默认：

APP_URL="https://rconfig.example.com"
APP_DEBUG=false
LOG_LEVEL=warning
HORIZON_MIN_PROCESS=1
HORIZON_MAX_PROCESS=5
HORIZON_DEFAULT_MAX_PROCESS=3
MASK_DEVICE_CREDENTIALS=true
TIMEZONE=Asia/Shanghai

要点：50 台以内设备每半小时一轮全量下载，2 个下载进程足够（HORIZON_MAX_PROCESS=5 留余量）；MASK_DEVICE_CREDENTIALS=true 适合运维人员较多的团队。

6.2 模板二：中大规模部署（数百台设备，16GB 内存 / 4 vCPU / 100GB 磁盘）

APP_URL="https://rconfig.example.com"
APP_DEBUG=false
LOG_LEVEL=warning
HORIZON_MIN_PROCESS=1
HORIZON_MAX_PROCESS=10
HORIZON_DEFAULT_MAX_PROCESS=5
HORIZON_PROD_TIMEOUT=300
REDIS_QUEUE_RETRY_AFTER=360
SESSION_LIFETIME=240
MASK_DEVICE_CREDENTIALS=true
TIMEZONE=Asia/Shanghai

要点：HORIZON_MAX_PROCESS=10 已是官方默认上限，配合 balance=auto 在批量下载高峰自动扩满；把 HORIZON_PROD_TIMEOUT 提到 300 秒时必须同步把 REDIS_QUEUE_RETRY_AFTER 提到更大值（360），维持「重试等待 > 任务超时」的关系；磁盘按每台设备每次下载约 10~50KB 配置文件估算并保留版本历史余量。

七、常见问题（FAQ）

Q1：改了 .env 不生效，Web 和队列还在用旧值。 配置缓存未重建。执行 php artisan rconfig:clear-all，看到 Config Cached! 与 Horizon Restarted! 即完成（完整实测回显见 3.3 节）。凡向导 optimize、clear-all 之后手工改的 .env 都要重跑该命令。

Q2：队列报 Redis NOAUTH，Horizon 反复 BACKOFF。 .env 的 REDIS_PASSWORD 与 Redis 服务端 requirepass 不一致（典型场景：向导写入密码后未重建缓存的旧配置被队列进程加载）。先 rconfig:clear-all；仍不行则用 php artisan rconfig:redis-secure 重新生成并下发，再 supervisorctl restart rconfig-core-horizon。

Q3：报告与日志时间差了几个小时。 时区不一致。.env 的 TIMEZONE 与 Settings 页（settings 表 timezone 字段）两处都要改（实测默认均为 Europe/Dublin），改后 rconfig:clear-all。

Q4：邮件通知发不出来。 检查方向不对——.env 的 MAIL_HOST 等键不参与运行时，实际生效的是 Settings 页里的 SMTP 配置（实测默认指向官方开发服务器 devmailer.rconfig.com:1025，生产必须改）。改完用页面提供的测试发送功能验证。

Q5：下载的配置文件权限是 0440，运维脚本读不了怎么办。 这是有意的安全默认（配置含设备凭据）。推荐把读取脚本放到与 Web/队列相同的属主下运行，或建立共同用户组后用组权限（官方注释推荐）；确实需要放宽时改 RCONFIG_CONFIG_FILE_MODE/RCONFIG_CONFIG_DIR_MODE 并执行 php artisan rconfig:set-config-permissions 刷新存量文件。不要对 data 目录跑 chmod -R 755。

Q6：普通运维在界面上能看到设备密码，如何遮蔽。 .env 设 MASK_DEVICE_CREDENTIALS=true 后 rconfig:clear-all。管理员账号仍可查看明文。

Q7：设备凭据加密依赖什么？密钥丢了怎么办。 依赖 APP_KEY（应用加密密钥）加 settings.passwordEncryption 开关（实测为 1 启用）。APP_KEY 丢失或重置后，库里已加密的设备密码将无法解密，设备下载会全面失败——务必按官方文档在 Settings 中备份 System Encryption Key。

八、参考链接

• 官方 System Settings Reference：https://v8coredocs.rconfig.com/reference/system-settings
• 官方 System Encryption Key（APP_KEY 备份）：https://v8coredocs.rconfig.com/system-management/system-encryption-key
• 官方 Redis Authentication：https://v8coredocs.rconfig.com/authentication-security/redis-authentication
• 官方 Worker Privilege（队列运行用户）：https://v8coredocs.rconfig.com/authentication-security/worker-privilege
• GitHub 仓库 .env.example：https://github.com/rconfig/rconfig/blob/main/.env.example
• 本系列前置阅读：《rConfig 8.2.19 Ubuntu 22.04 安装指南》（安装流程与本文 .env 的对应关系）
• 本系列延伸阅读：《rConfig 8.2.19 常用 CLI 与运维命令详解》（rconfig: 命令族、rconfig:clear-all/set-config-permissions 等运维命令实测）