FileRise 3.38 配置参数详解

目标：逐层逐项讲清 FileRise v3.38.0 的配置体系——应用常量（config/config.php）、环境变量（FR_* 系列）、运行时管理配置（adminConfig.json / siteConfig.json）三层的查看与修改方式、默认值与实测生效值，并给出小团队生产配置模板。全部参数值实查自 v3.38.0 官方发布件源码与运行实例的管理接口回显（部署形态见《FileRise 3.38 Docker Compose 部署指南》）。

一、环境信息

本文参数实查环境：

二、前置条件

1. 已按部署篇完成 FileRise 部署并能访问站点（或已解压同版本发布件可读源码）；
2. 具备管理员会话（浏览器登录，或脚本侧持有登录 Cookie），用于读取/修改运行时管理配置；
3. 修改部署期配置（config.php、环境变量）需要对应用服务有文件/编排层的变更权限。

三、参数查看与修改方式

FileRise 无统一配置文件向导，配置分布在三层，各层查看与修改方式不同：

第 1 层：应用常量（config/config.php，部署期）

PHP 常量在启动时定义，覆盖路径、时区、上传上限、校验正则、OnlyOffice/OIDC 缺省等。查看方式为直接读文件（发布件自带），修改后需重启 PHP 服务才生效（Compose 栈 docker compose restart php 实测生效）。典型常量实查：

define('UPLOAD_DIR', '/var/www/uploads/');     // 数据三目录之一
define('TIMEZONE', 'America/New_York');        // 默认时区，中文环境建议改 Asia/Shanghai
define('TOTAL_UPLOAD_SIZE', '5G');             // 单次上传总量上限

第 2 层：环境变量（FR_ 系列，进程级）*

应用通过 getenv() 实时读取约 40 个 FR_*/功能环境变量（反代、OIDC、缩略图、WebDAV 限额、病毒扫描、worker 模式等），Compose 栈经 environment: 注入，改后重启对应服务生效。v3.38.0 发布件源码实查的全部环境变量名：

FR_BASE_PATH  FR_ENCRYPTION_MASTER_KEY  FR_FFMPEG_PATH  FR_IGNORE_REGEX  FR_IP_HEADER
FR_OIDC_ADMIN_GROUP  FR_OIDC_ALLOW_DEMOTE  FR_OIDC_AUTO_CREATE  FR_OIDC_DEBUG
FR_OIDC_EXTRA_SCOPES  FR_OIDC_GROUP_CLAIM  FR_OIDC_PRO_GROUP_PREFIX
FR_PDF_THUMB_BINARY  FR_PDF_THUMB_MAX_H  FR_PDF_THUMB_MAX_MB  FR_PDF_THUMB_MAX_W
FR_PRO_BUNDLE_DIR  FR_PRO_LICENSE  FR_PRO_LICENSE_FILE  FR_PRO_SEARCH_ENABLED
FR_PUBLISHED_URL  FR_RESUMABLE_TTL_HOURS  FR_TRUSTED_PROXIES
FR_VIDEO_THUMB_MAX_H  FR_VIDEO_THUMB_MAX_W  FR_WEBDAV_MAX_UPLOAD_BYTES  FR_WORKER_MODE
ONLYOFFICE_ALLOW_UNSIGNED_CALLBACKS  ONLYOFFICE_DEBUG  ONLYOFFICE_DOCS_ORIGIN
PERSISTENT_TOKENS_KEY  PERSISTENT_TOKENS_KEY_SOURCE  SECURE  SHARE_URL
VIRUS_SCAN_CMD  VIRUS_SCAN_ENABLED  VIRUS_SCAN_EXCLUDE_DIRS

（另有 FR_TEST_UPLOAD_DIR/FR_TEST_USERS_DIR/FR_TEST_META_DIR 三个测试期目录重定向变量与 FR_SHIM_WARN，生产不使用。）

第 3 层：运行时管理配置（管理员界面 / 管理 API）

站点标题、登录方式、WebDAV 开关、分享上限、缩略图阈值、OnlyOffice、ClamAV、OIDC 等「改完即生效」的运营配置，落盘在 users 目录：adminConfig.json（加密存储，站点运营主配置）与 siteConfig.json（明文，品牌外观）。查看走管理接口（实测回显，键名与默认值见下章）：

curl -sS -b cookies.txt 'http://localhost:8152/api/admin/getConfig.php'

修改同样走管理接口（或管理员界面的设置页），实测以开启 WebDAV 为例：

curl -sS -b cookies.txt -X POST 'http://localhost:8152/api/admin/updateConfig.php' \
  -H "X-CSRF-Token: $T" -H 'Content-Type: application/json' \
  -d '{"enableWebDAV":true}' -w ' [HTTP %{http_code}]\n'

实测回显：

{"success":"Configuration updated successfully."} [HTTP 200]

⚠️ 注意：adminConfig.json 在磁盘上是密文（v3.38.0 实测读文件为 Base64 密文），手工改无效且可能损坏配置；该层一律走管理接口/管理界面修改。明文的 siteConfig.json 与加密的 adminConfig.json 键名结构一致，是排障时核对「当前生效值」的只读依据。

💡 技术拓展：三类配置的生效链路对比——

层级	存储	生效方式	适合改什么
config.php 常量	源码文件	重启 PHP 服务	路径、时区、校验正则等「装机即定」项
环境变量	容器/进程环境	重启服务	反代、OIDC、扫描、缩略图等运行环境项
管理配置	users/ 目录 JSON	保存即生效	登录方式、开关类、阈值类运营项

FileRise 的分层意图：装机层用常量防呆，环境层交给编排系统，运营层全部可视化。同键冲突时优先级为「环境变量 > 常量默认值」（源码中常量定义处均先读 getenv），运行时管理层独立。

四、参数总览

按「层级 / 参数 / 实查默认值 / 作用」汇总高频参数（默认值均实查自 v3.38.0 发布件或运行实例）：

五、核心参数分类详解

5.1 路径与存储常量

三目录是 FileRise 的一切（备份/迁移的边界）：

define('UPLOAD_DIR', '/var/www/uploads/');   // 上传根：文件、子目录、trash/
define('USERS_DIR',  '/var/www/users/');     // 用户与配置：users.txt、adminConfig.json、siteConfig.json
define('META_DIR',   '/var/www/metadata/');  // 元数据：root_metadata.json、folder_acl.json、persistent_tokens.key
define('TRASH_DIR',  UPLOAD_DIR . 'trash/'); // 回收站随上传根
define('USERS_FILE', 'users.txt');           // 用户清单文件名
define('META_FILE',  'file_metadata.json');  // 元数据文件名

重定向：三个路径可分别经环境变量 FR_TEST_UPLOAD_DIR、FR_TEST_USERS_DIR、FR_TEST_META_DIR 覆盖（源码 config.php 第 25-46 行实查）；生产改路径推荐直接改 config.php 三行 + 迁移目录属主（www-data）。实测部署篇将三目录 bind mount 到宿主机并 chown www-data，应用无需任何额外配置即读写正常。

5.2 站点基础常量：时区、时间格式、上传上限

define('TIMEZONE', 'America/New_York');        // 实查默认值
define('DATE_TIME_FORMAT','m/d/y  h:iA');      // 实查默认值
define('TOTAL_UPLOAD_SIZE', '5G');             // 实查默认值

• TIMEZONE：中文环境建议改 Asia/Shanghai，改后文件列表时间、日志时间随之一致（需重启 PHP 服务）；
• DATE_TIME_FORMAT：PHP date 格式串，实测列表回显 10/30/26 02:36AM 即此格式；国内习惯可用 Y-m-d H:i；
• TOTAL_UPLOAD_SIZE：单次上传请求的总量闸门（与 PHP 层 post_max_size、nginx 层 client_max_body_size 构成三层限制，必须同量级对齐，见部署篇 FAQ）。

5.3 命名校验与上传名安全策略

define('REGEX_FOLDER_NAME', '/^(?!^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$)(?!\.{1,2}(?:[\/\\\\]|$))(?!.*[\/\\\\]\.{1,2}(?:[\/\\\\]|$))(?!.*[. ]$)(?:[^<>:"\/\\\\|?*\x00-\x1F]{1,255})(?:[\/\\\\][^<>:"\/\\\\|?*\x00-\x1F]{1,255})*$/xu'); // 实查默认：拒绝 Windows 保留名、路径穿越
define('REGEX_FILE_NAME',  '/^[^\x00-\x1F\/\\\\]{1,255}$/u');   // 文件名禁控制符与斜杠，≤255 字节
define('REGEX_USER',       '/^(?!\.{1,2}$)[\p{L}\p{N}_\- .@]+$/u'); // 用户名：字母数字下划线短横点空格@
define('PATTERN_FOLDER_NAME', '[\p{L}\p{N}_\-\s\/\\\\]+');       // 文件夹匹配模式

配套的运行时项 safeUploadPolicy（实测值 strict）：上传名规范化策略，strict 下拒绝可疑扩展名/控制字符并自动改名。实测中文名「演示文档.txt」上传、改名、下载全部正常（部署篇 5.3-5.5），Unicode 文件名开箱可用。正则默认值已覆盖 Windows 保留设备名（CON/NUL/COM1 等）与 .. 穿越，不建议放宽。

5.4 用户默认权限与 ACL

define('DEFAULT_BYPASS_OWNERSHIP', false);  // 属主绕过：默认关
define('DEFAULT_CAN_SHARE', true);          // 默认可创建分享
define('DEFAULT_CAN_ZIP', true);            // 默认可打包下载
define('DEFAULT_VIEW_OWN_ONLY', false);     // 默认可见全部授权目录（非仅自己的文件）
define('ACL_INHERIT_ON_CREATE', true);      // 新建目录继承父 ACL

逐项解读：以上是「新建用户」的出厂默认，已存在用户以各自权限记录为准（users.txt 与 folder_acl.json）。逐文件夹 ACL 的实际授权数据落 metadata/folder_acl.json（部署实例实测生成）；团队场景若要「各自只见自己的目录」，将 DEFAULT_VIEW_OWN_ONLY 改 true 并配合 ACL 继承。

5.5 反向代理与真实 IP

实测验证：本文部署为直连 HTTP（SECURE=false、无反代），站点功能完整；上述参数在 nginx 反代/子路径场景按表设置即可。

5.6 认证、会话与「记住登录」

• PERSISTENT_TOKENS_KEY：「记住登录」的持久化令牌密钥。实测留空时首启自动生成强随机值并落 metadata/persistent_tokens.key（0600 权限，部署篇已见该文件）；官方 start.sh 对历史占位值（default_please_change_this_key 等）会打告警。密钥丢失/更换会使全部已记住的登录失效——备份必须带上该文件；
• 登录方式运行时项 loginOptions（实测回显三个键）：disableFormLogin（false）、disableBasicAuth（true，默认关闭 HTTP Basic 的 API 登录）、disableOIDCLogin（true，默认关 OIDC）；
• TOTP 两步验证：用户级开关（profile 域接口 totp_setup/totp_verify 等），管理员可配 globalOtpauthUrl；
• OIDC 环境变量组：FR_OIDC_AUTO_CREATE（默认 true，无匹配用户时自动建号）、FR_OIDC_GROUP_CLAIM、FR_OIDC_ADMIN_GROUP（默认 filerise-admins）、FR_OIDC_EXTRA_SCOPES、FR_OIDC_ALLOW_DEMOTE、FR_OIDC_DEBUG；OIDC 提供商地址/客户端凭据在管理配置 oidc 键下（实测回显含 providerUrl/redirectUri/hasClientId 等）；
• 登录失败限速：失败过多返回 HTTP 429（OpenAPI 规范明示 429 Too many failed login attempts）。

5.7 上传与分块续传

• 单请求上限：TOTAL_UPLOAD_SIZE（5G，常量）+ PHP upload_max_filesize/post_max_size + nginx client_max_body_size，三层对齐见部署篇；
• 每请求文件数：PHP max_file_uploads（官方 custom-php.ini 取 20）；
• 分块续传：运行时项 resumableChunkMb（分块大小）与 resumableTtlHours（未完成分块保留时长），另有环境变量 FR_RESUMABLE_TTL_HOURS 可全局覆盖（源码 UploadModel 实查：env 优先于常量）；过期分块由内置清理 worker 回收；
• 分享上传上限：运行时项 sharedMaxUploadSize（实测 52428800 字节 = 50 MB），控制外部投递链接的单文件上限；
• 去重检查：上传前可调用 checkExisting 接口比对同名/同内容。

5.8 WebDAV

WebDAV 走 public/webdav.php 入口（内置 SabreDAV），路径即上传目录结构，实测根目录与 reports/ 子目录均正常列出。

5.9 缩略图、预览与媒体

5.10 病毒扫描（ClamAV）

define('VIRUS_SCAN_ENABLED', ...);   // 环境变量 VIRUS_SCAN_ENABLED，默认 false
define('VIRUS_SCAN_CMD', getenv('VIRUS_SCAN_CMD') ?: 'clamscan');  // 默认命令
define('VIRUS_SCAN_TIMEOUT', 60);    // 实查：单文件扫描超时 60 秒

配套运行时项 clamav.scanUploads（是否扫描上传件）与 clamav.excludeDirs（排除目录，实测回显均存在）。启用路径：服务器安装 clamscan → 置 VIRUS_SCAN_ENABLED=true → 运行时开启 scanUploads；管理接口另有 clamavTest/virusLog 调试端点。

5.11 OnlyOffice 集成

define('ONLYOFFICE_ENABLED', false);              // 实查默认关
define('ONLYOFFICE_DOCS_ORIGIN', 'http://192.168.1.61'); // 文档服务地址（示例值）
define('ONLYOFFICE_JWT_SECRET', 'test123456');    // JWT 密钥（生产必须改）
define('OFFICE_SNIPPET_MAX_BYTES', 5 * 1024 * 1024); // 在线编辑片段上限 5 MiB

运行时键 onlyoffice.enabled/docsOrigin/publicOrigin/hasJwtSecret/callbackJwtRequired/unsignedCallbacksAllowed（实测回显存在）。启用步骤：部署 OnlyOffice Document Server → 管理界面或 updateConfig 填 docsOrigin → config.php 置 ONLYOFFICE_ENABLED=true 并改 JWT 密钥 → 重启。在线编辑的文本片段上限由 OFFICE_SNIPPET_MAX_BYTES 控制（5 MiB）。

5.12 文件夹级静态加密

环境变量 FR_ENCRYPTION_MASTER_KEY：文件夹加密主密钥。设置后可对指定文件夹开启静态加密（管理界面/接口 setFolderEncryption，加密作业由 encryptionJobStart 等端点驱动）。实测本实例未启用该变量（保持明文存储）；启用后密钥必须与数据一同备份，丢失即不可解。

5.13 后台 worker 与内置脚本

config.php 实查 FR_WORKER_MODE（worker 进程模式标记）；发布件 src/cli/ 实查内置 4 个后台脚本：transfer_worker.php（传输队列）、zip_worker.php（打包队列）、disk_usage_scan.php（磁盘用量扫描）、resumable_cleanup.php（过期分块清理）。nginx+PHP-FPM 栈下这些队列由请求触发推进（官方镜像由 start.sh/调度拉起）；大流量打包/磁盘统计场景可用计划任务周期执行对应脚本。

5.14 Pro 扩展相关参数

FR_PRO_LICENSE / FR_PRO_LICENSE_FILE / FR_PRO_BUNDLE_DIR / FR_PRO_SEARCH_ENABLED 与运行时键 proSearch、storageSources（实测回显存在，Pro 未安装时 proSearch.enabled=false）。边界说明：审计日志、全局搜索、S3/SMB/远端 WebDAV 存储源、门户表单为 Pro 能力；核心版 MIT 开源功能不含这些项，本实例均保持默认关闭。

六、生产配置模板（小团队场景）

适用场景：2 核 4 GB 内存、NVMe SSD、≤30 人团队、上传区 500 GB 以内、nginx TLS 反代。基于默认值的最小改动集：

config.php（三处必改）：

define('TIMEZONE', 'Asia/Shanghai');              // 时区改为本地
define('TOTAL_UPLOAD_SIZE', '2G');                // 按业务收紧单请求上限
define('DATE_TIME_FORMAT', 'Y-m-d H:i');          // 时间格式本地化

环境变量（compose environment，配合 TLS 反代）：

environment:
  SECURE: "true"                        # TLS 反代后必须
  FR_TRUSTED_PROXIES: "10.89.58.0/24"   # 信任反代网段
  FR_PUBLISHED_URL: "https://files.example.com"   # 对外域名
  VIRUS_SCAN_ENABLED: "true"            # 已装 clamscan 时开启
  VIRUS_SCAN_CMD: "clamscan"

对齐层（防 413/中断）：nginx client_max_body_size 2G;、PHP upload_max_filesize=2G、post_max_size=2G，与应用 TOTAL_UPLOAD_SIZE=2G 同值。PHP memory_limit=512M、max_execution_time=300 沿用官方 custom-php.ini 取值即可满足 30 人量级；磁盘占用主要由上传区与回收站构成，建议对 data/uploads/trash/ 建立定期清理（清空回收站接口 deleteTrashFiles 或直接删 trash 目录内容）。

七、常见问题

Q1：改了 config.php 不生效 常量在进程启动时定义，需重启 PHP 服务（Compose 栈 docker compose restart php，实测生效）；管理配置层（enableWebDAV 等）则是保存即生效，两者生效链路不同。

Q2：想手工改 adminConfig.json 但打开是乱码 它是加密落盘（实测读文件为密文），手工修改无效甚至损坏；一律走管理接口 /api/admin/updateConfig.php 或管理员界面。明文的 siteConfig.json 只作只读核对用。

Q3：上传大小到底谁说了算 三层闸门取最小值：nginx client_max_body_size、PHP post_max_size/upload_max_filesize、应用 TOTAL_UPLOAD_SIZE（分块续传另受分块大小约束）。排查顺序：先看 nginx 是否 413，再看 PHP 层报错，最后对应用层配置。

Q4：时区显示不对 TIMEZONE 默认 America/New_York（实查值），改为 Asia/Shanghai 并重启；已上传文件的列表时间是元数据记录时刻，改时区只影响之后的展示口径。

Q5：persistent_tokens.key 能删吗 不要删。它是「记住登录」令牌的加密密钥（0600），删除后全员已记住的登录失效；换密钥同理。备份三目录时必须包含 metadata/。

Q6：WebDAV 开了还是 403 按部署篇 5.7 两步核对：管理配置 enableWebDAV 是否已置 true；nginx 是否透传 fastcgi_param HTTP_AUTHORIZATION $http_authorization;（漏配时 Basic 认证头到不了 PHP）。

八、参考链接

• FileRise 官方文档（Installation & Setup / FAQ）：https://filerise.net/docs/?page=installation-setup
• FileRise GitHub 仓库（config/config.php）：https://github.com/error311/FileRise
• 站内延伸阅读：《FileRise 介绍与选型指南》（定位与对比）、《FileRise 3.38 Docker Compose 部署指南》（本配置体系的实测部署载体）、《FileRise 3.38 API 使用详解》（getConfig/updateConfig 等接口实测）