FileGator v7.16.8 配置参数详解

目标：逐域讲清 FileGator v7.16.8 唯一配置文件 configuration.php 的全部参数——顶层运行参数、frontend_config 前端参数与 services 服务装配域（Storage/Auth/Security/Router 等 10 个服务），给出默认值实查清单、修改方式与生产配置模板。所有默认值均于 2026-10-30 从官方镜像 filegator/filegator:v7.16.8 内的 configuration_sample.php（首启时复制为 configuration.php）实查照抄。

一、环境信息

• 组件版本：FileGator v7.16.8（官方最新稳定版，2026-10-30 实查 GitHub Releases）
• 配置文件版本基线：官方镜像 v7.16.8 内 /var/www/filegator/configuration_sample.php（126 行，return [...] 形态的 PHP 数组）
• 参考的部署形态：《FileGator v7.16.8 Docker Compose 部署指南》 中的 bind mount 单机栈
• 实查方式：docker run --rm filegator/filegator:v7.16.8 cat /var/www/filegator/configuration_sample.php 与运行中栈内 cat configuration.php 对照（两者一致，运行时文件为样例的复制）

二、前置条件

1. 已按部署指南拉起 FileGator 栈，并能访问 http://<服务器IP>:8149。
2. 理解 FileGator 配置的特殊性：它是 PHP 数组而非 YAML/ENV，改动即生效（无独立配置热加载，改完重启服务进程即可，容器形态下 docker compose restart）。
3. 配置内可执行 PHP（闭包函数用于装配适配器），因此编辑后建议先 php -l configuration.php 做语法检查（宿主机无 PHP 时可用 docker run --rm -v $PWD/configuration.php:/c.php filegator/filegator:v7.16.8 php -l /c.php）。

三、参数查看与修改方式

查看当前生效值的三条路：

1. 直接读配置文件（容器内路径 /var/www/filegator/configuration.php）：

   docker compose exec filegator cat /var/www/filegator/configuration.php
   

2. 前端参数可用 API 读到运行值（无需登录）：

   curl -s "http://127.0.0.1:8149/?r=/getconfig"
   

   实测回显（2026-10-30，节选）：

   {"data":{"app_name":"FileGator","app_version":"7.16.8","language":"english","logo":"https:\/\/filegator.io\/filegator_logo.svg","upload_max_size":104857600,"upload_chunk_size":1048576,"upload_simultaneous":3,"default_archive_name":"archive.zip","editable":[".txt",".css",".js",".ts",".html",".php",".json",".md"],"date_format":"YY\/MM\/DD hh:mm:ss","guest_redirection":"","search_simultaneous":5,"filter_entries":[],"pagination":["",5,10,15]}}
   

3. 登录后前端右上角 Settings 界面只读展示同源信息。

修改方式（推荐顺序）：

1. 标准做法：把容器内 configuration.php 拷出到宿主 → 编辑 → 挂载回容器（:ro 只读挂载更稳）：

   docker compose exec filegator cat /var/www/filegator/configuration.php > configuration.php
   # 编辑 configuration.php 后
   docker compose down && docker compose up -d
   

2. 样例重建：删除容器内 configuration.php 后首次访问会自动从 configuration_sample.php 复制（源码 dist/index.php 内置逻辑，实测确认），适合配置改坏时快速回位。

四、参数总览

configuration.php 分三层，参数全景如下（默认值均为镜像内实查）：

五、顶层与 frontend_config 参数详解

5.1 顶层运行参数

• overwrite_on_upload（false）：同名文件上传时是否直接覆盖。false 时自动改名（file (1).txt 风格，源码 upcountName 逻辑）。团队协作场景建议保持 false 防误覆盖；采集落地场景可开 true。
• timezone（'UTC'）：影响文件时间显示与日志时间戳。国内部署改 'Asia/Shanghai'（合法值见 PHP 官方时区表）。
• download_inline（['pdf']）：列表内这些扩展名点击时在浏览器内联预览而非下载。设 ['*'] 全部内联。⚠️ 官方注释明确警告：放开不可信文件类型内联渲染可能导致 XSS，按需最小化。
• lockout_attempts / lockout_timeout（5 次 / 15 秒）：按 IP 的登录失败锁定。公网部署建议收紧（如 3 次 / 300 秒）；失败锁定记录在 private/logs/app.log 可审计。

5.2 frontend_config 前端参数

这一层只影响 Vue 前端表现与上传策略，随 GET /?r=/getconfig 下发（上方 getconfig 回显即这些值的运行态）：

• upload_max_size（100MB）：单文件上限。调大时注意两处联动：PHP 运行时的 upload_max_filesize/post_max_size（镜像内默认 2M/8M，需同时以自定义 php.ini 调整），以及分块机制本身会绕开单请求限制——保持 1MB 分块时，PHP 层限制无需动，只调此值即可传大文件。
• upload_chunk_size（1MB）：分块粒度。越大单请求越大、请求数越少；弱网环境调小可降低整块重传成本。
• upload_simultaneous（3）：并发分块路数，弱网/高延迟可调 1-2 提升成功率。
• editable（8 个扩展名）：在线编辑白名单。追加 .ini、.conf、.log 等运维常用文本可提升文件台实用性；注意 .php 在默认列表中——纯静态托管场景建议移除以防误编辑源码。
• filter_entries（[]）：按名过滤隐藏条目（正则），如 ['^\.', '^\."] 隐藏点文件（默认前端已隐藏点文件，此参数用于更多自定义）。
• pagination（['', 5, 10, 15]）：分页器可选每页条数，空串表示「不分页」。大目录（万级文件）建议给有限档位避免渲染卡顿。
• app_name / logo / language / date_format：品牌化四件套；language 取值见官方仓库 frontend 语言包文件（english/中文等，2026-10-30 实查仓库 frontend/lang 目录）。

六、services 服务装配域详解（10 个服务）

services 键是接口全名 → {handler 适配器类, config 适配器配置} 的 DI 装配表，这是 FileGator「一切可换」的核心。默认装配（镜像内实查）逐个说明：

6.1 Logger（日志）

'Filegator\Services\Logger\LoggerInterface' => [
    'handler' => '\Filegator\Services\Logger\Adapters\MonoLogger',
    'config' => ['monolog_handlers' => [ /* 返回 StreamHandler 写 private/logs/app.log, DEBUG 级 */ ]],
],

默认写 private/logs/app.log。排障第一现场：CSRF 拒绝（Csrf token not valid）、登录失败锁定、PHP Warning/异常堆栈都落这里。

6.2 Session（会话）

'handler' => '\Filegator\Services\Session\Adapters\SessionStorage',
'config' => ['handler' => function () { /* NativeFileSessionHandler + NativeSessionStorage */ }],

默认 PHP 原生文件会话，Cookie 属性 cookie_samesite=Lax、cookie_httponly=true、cookie_secure=null。上 HTTPS 后建议把 cookie_secure 设 true。多实例部署时把 $save_path 指向共享存储或换 Redis 适配器。

6.3 Cors（跨域）

'handler' => '\Filegator\Services\Cors\Cors',
'config' => ['enabled' => APP_ENV == 'production' ? false : true],

生产环境（APP_ENV=production，容器内默认）CORS 关闭——API 仅同源可用。如需给第三方前端调用，改 true 并理解风险。

6.4 Tmpfs（临时区）

'handler' => '\Filegator\Services\Tmpfs\Adapters\Tmpfs',
'config' => ['path' => __DIR__.'/private/tmp/', 'gc_probability_perc' => 10, 'gc_older_than' => 60*60*24*2],

分块上传临时件与打包临时件落地处；每请求 10% 概率触发 GC，清理 2 天前的残留。磁盘规划点：大文件上传的瞬时占用 ≈ 文件体积（临时区+最终落盘双份），小盘机器要留意。

6.5 Security（安全）

'handler' => '\Filegator\Services\Security\Security',
'config' => [
    'csrf_protection' => true,
    'csrf_key' => "123456",   // randomize this（官方注释要求随机化）
    'ip_allowlist' => [],
    'ip_denylist' => [],
    'allow_insecure_overlays' => false,
],

• csrf_protection / csrf_key：POST 类请求的 CSRF 防护开关与 token 密钥。csrf_key 是官方注释里明确要求「randomize this」的值，生产部署务必改成随机串（改后所有客户端重新取 token 即可，无迁移成本）。
• ip_allowlist / ip_denylist：IP 黑白名单，匹配请求客户端 IP。白名单非空时仅名单内 IP 可访问（实测配置语义，源码 Security.php）。内网文件台可用 allowlist 收口。

6.6 View（视图）

'handler' => '\Filegator\Services\View\Adapters\Vuejs',
'config' => ['add_to_head' => '', 'add_to_body' => ''],

向 Vue 单页注入自定义 HTML 的两个插槽（如统计脚本、字体加载）。

6.7 Storage（存储，最核心）

'Filegator\Services\Storage\Filesystem' => [
    'handler' => '\Filegator\Services\Storage\Filesystem',
    'config' => [
        'separator' => '/',
        'config' => [],
        'adapter' => function () {
            return new \League\Flysystem\Adapter\Local(__DIR__ . '/repository');
        },
    ],
],

• separator：路径分隔符。
• adapter 闭包：返回 Flysystem 适配器实例。换 S3 即在此处 new S3Adapter（容器已预装 league/flysystem-aws-s3-v3，官方 Dockerfile 构建时显式 composer require，S3/FTP 适配器开箱即用——2026-10-30 Dockerfile 实查）；换 FTP 用 SftpAdapter（同已预装）。config 数组透传给 Filesystem 层（如 Flysystem 的额外选项）。

6.8 Archiver（压缩）

'handler' => '\Filegator\Services\Archiver\Adapters\ZipArchiver',
'config' => [],

ZipArchive 实现，负责 zipitems/unzipitem/batchdownload 三条链路。无独立配置项。

6.9 Auth（认证）

'handler' => '\Filegator\Services\Auth\Adapters\JsonFile',
'config' => ['file' => __DIR__ . '/private/users.json'],

默认 JSON 文件用户库（三字段加密细节：bcrypt password_hash）。官方内置 LDAP 与 mysqli 适配器（镜像已编译扩展），换适配器时 config 键结构随适配器变化（LDAP 需 base_dn/绑定账号等）。

6.10 Router（路由）

'handler' => '\Filegator\Services\Router\Router',
'config' => ['query_param' => 'r', 'routes_file' => __DIR__ . '/backend/Controllers/routes.php'],

• query_param（'r'）：API 路由形态 /?r=/端点。官方镜像未启用 URL 重写，保持默认即可（实测 /getconfig 直连 404、/?r=/getconfig 200）。
• routes_file：路由表文件，每条含 route（方法+路径+控制器）与 roles/permissions 两道门槛。需要裁剪能力时改此文件（自定义副本 + 修改此键指向）。

七、生产配置模板

内网团队文件台场景（改密后 admin 日常使用 + LDAP/名单收口二选一），可直接替换的模板（仅列改动项，其余保持样例默认）：

<?php
return [
    'public_path' => APP_PUBLIC_PATH,
    'public_dir' => APP_PUBLIC_DIR,
    'overwrite_on_upload' => false,
    'timezone' => 'Asia/Shanghai',
    'download_inline' => ['pdf'],
    'lockout_attempts' => 3,
    'lockout_timeout' => 300,

    'frontend_config' => [
        'app_name' => '团队文件台',
        'app_version' => APP_VERSION,
        'language' => 'english',
        'logo' => 'https://filegator.io/filegator_logo.svg',
        'upload_max_size' => 2 * 1024 * 1024 * 1024, // 2GB，分块上传天然绕开单请求限制
        'upload_chunk_size' => 5 * 1024 * 1024,      // 5MB 块，内网带宽好可调大
        'upload_simultaneous' => 5,
        'default_archive_name' => 'archive.zip',
        'editable' => ['.txt', '.css', '.js', '.ts', '.html', '.json', '.md', '.ini', '.conf', '.log'],
        'date_format' => 'YY/MM/DD hh:mm:ss',
        'guest_redirection' => '',
        'search_simultaneous' => 5,
        'filter_entries' => [],
        'pagination' => ['', 50, 100, 200],
    ],

    'services' => [
        // Logger/Session/View/Tmpfs/Archiver 保持样例默认
        'Filegator\Services\Security\Security' => [
            'handler' => '\Filegator\Services\Security\Security',
            'config' => [
                'csrf_protection' => true,
                'csrf_key' => '请替换为 openssl rand -hex 24 生成的随机串',
                'ip_allowlist' => [],
                'ip_denylist' => [],
                'allow_insecure_overlays' => false,
            ],
        ],
        'Filegator\Services\Storage\Filesystem' => [
            'handler' => '\Filegator\Services\Storage\Filesystem',
            'config' => [
                'separator' => '/',
                'config' => [],
                'adapter' => function () {
                    return new \League\Flysystem\Adapter\Local(__DIR__ . '/repository');
                },
            ],
        ],
        'Filegator\Services\Auth\AuthInterface' => [
            'handler' => '\Filegator\Services\Auth\Adapters\JsonFile',
            'config' => ['file' => __DIR__ . '/private/users.json'],
        ],
        'Filegator\Services\Router\Router' => [
            'handler' => '\Filegator\Services\Router\Router',
            'config' => [
                'query_param' => 'r',
                'routes_file' => __DIR__ . '/backend/Controllers/routes.php',
            ],
        ],
    ],
];

模板要点：上传上限 2GB 依赖分块机制（5MB×400 块），PHP 层无需调整；锁定收紧为 3 次/300 秒；csrf_key 必须替换（docker compose exec filegator php -r "echo bin2hex(random_bytes(24));" 现场生成）；editable 移除 .php（纯文件台不编辑源码）。

八、常见问题

1. 改了 configuration.php 没生效 未挂载或挂载路径不对。compose 里确认 - ./configuration.php:/var/www/filegator/configuration.php 存在，docker compose exec filegator head -5 /var/www/filegator/configuration.php 核对是宿主版本后重启。
2. 改配置后页面 500 PHP 语法错误（闭包逗号/引号）。php -l 检查；紧急回位：容器内删掉 configuration.php 重启，首启逻辑自动从样例复制。
3. upload_max_size 调到 2GB 仍传不了 前端 getconfig 显示的才是生效值；确认浏览器拿到的 upload_max_size 已更新（改配置后必须重启服务），并检查反向代理（如有 Nginx）的 client_max_body_size 是否同样放开（分块单请求 5MB 一般不受限，主要是直传大块场景）。
4. 换 S3 后 getdir 报错 Flysystem S3 适配器要求 composer 依赖完整——官方镜像已预装 S3/SFTP 适配器（Dockerfile 实证），报错多为凭证/桶名/前缀配置问题，先看 private/logs/app.log 的异常堆栈定位。
5. csrf_key 改了之后老页面报错 正常现象：旧会话 token 失效，刷新页面重新 GET 取新 token 即可。

九、参考链接

• 配置样例原文：https://github.com/filegator/filegator/blob/master/configuration_sample.php （查询日期 2026-10-30）
• 路由表（routes/roles/permissions 全集）：https://github.com/filegator/filegator/blob/master/backend/Controllers/routes.php （查询日期 2026-10-30）
• Flysystem 适配器目录：https://flysystem.thephpleague.com/v1/docs/adapter/local/ （查询日期 2026-10-30）
• 本专栏姊妹篇：《FileGator 介绍与选型指南》、《FileGator v7.16.8 Docker Compose 部署指南》、《FileGator v7.16.8 API 使用详解》