Tiny File Manager 2.6 配置参数详解

目标：讲清 Tiny File Manager 2.6 的全部配置通道与参数——config.php 外部覆盖文件、$CONFIG 界面级 JSON、账号/只读组/根目录/上传限制/IP 白名单等 30+ 项变量的默认值与修改方法，并给出一份实测验证过的生产配置模板。参数默认值取自官方源码 2.6（master 分支）逐行核对，关键行为（改密、Settings 写回、只读账号、时区）于 2026-11-01 在 Ubuntu 22.04 实机实测验证。

一、环境信息

• 应用版本：Tiny File Manager 2.6（官方 GitHub Releases 最新稳定版；本文参数与 master 分支 2026-07-20 构建源码核对）
• 运行环境：Ubuntu 22.04（x86_64），官方镜像 tinyfilemanager/tinyfilemanager:master（内置 PHP 7.4.33）
• 部署形态：Docker Compose 部署、Web 端口 8134、数据目录 data/ 挂载为 /var/www/html/data（部署过程见 《Tiny File Manager Docker Compose 部署指南》）
• 实测演示账号：admin / q1w2e3r4（由官方默认 admin/admin@123 实测改为强密码）、只读账号 user / 12345
• 源码与语言包：官方仓库 master 分支（查询日期 2026-11-01）

二、前置条件

1. 已按 《Tiny File Manager Docker Compose 部署指南》完成部署并能登录；
2. 部署目录下已有挂载的 config.php（没有就新建空文件，写入下文示例）——它是本文全部修改动作的落点；
3. 修改 config.php 后需要重启应用生效：

docker compose restart

实测回显：

Container tiny-file-manager-2.6-web  Started

三、参数查看与修改方式

Tiny File Manager 的配置分三层，加载顺序为「源码默认 → config.php 覆盖 → Settings 面板写回」：

1. 源码默认值：index.php（即 tinyfilemanager.php）文件顶部逐项定义，如 $root_path = $_SERVER['DOCUMENT_ROOT'];；
2. config.php 外部覆盖文件：应用启动时检测同目录下的 config.php，存在则 include——在其中重新赋值任意变量即可覆盖默认值，不需要改源码文件本体。这是官方推荐的定制方式；
3. Web Settings 面板：界面右上角 Settings，改语言/主题/隐藏文件等界面选项后点 Save，应用会把新值以 JSON 形式写回 config.php 文件头部的 $CONFIG 行（实测写回结果见 3.2）。

💡 技术拓展：PHP 应用的配置覆盖机制常见三种流派对比——

流派	机制	代表	取舍
环境变量注入	容器 ENV → 应用读取	12-Factor 应用	适合容器编排，改配置要重建
外部文件覆盖	主文件 include 外部覆盖文件	Tiny File Manager 的 config.php	改完重启即生效，源码零侵入
数据库/管理台	配置入库或写回文件	WordPress 等	运行时可改，但配置与数据耦合

Tiny File Manager 采用「外部文件覆盖 + 界面选项写回文件」的组合：服务端参数改 config.php（重启生效），界面参数用 Settings 面板（保存即生效）。

3.1 config.php 覆盖验证（实测）

以「修改时区 + 改密」为例。在部署目录 config.php 写入：

<?php
$default_timezone = 'Asia/Shanghai';
$auth_users = array(
    'admin' => '$2y$10$n5JMHnEOnduSgdlN6.tgBebNrfDnrwUUFiS12hybD8X9NpKkyrmc2', //q1w2e3r4
    'user' => '$2y$10$Fg6Dz8oH9fPoZ2jJan5tZuv6Z4Kp7avtQ9bDfrdRntXtPeiMAZyGO' //12345
);

重启后验证：旧密码 admin@123 登录被拒，新密码 q1w2e3r4 登录成功（curl 实测回显）：

Login failed. Invalid username or password      ← 旧密码
You are logged in                               ← 新密码 q1w2e3r4

密码哈希的生成：可用官方在线生成页 https://tinyfilemanager.github.io/docs/pwd.html ；也可用应用自带的 AJAX 接口（登录态下，实测返回 bcrypt 哈希）：

curl -s -b <cookie> -d "ajax=1&type=pwdhash&inputPassword2=你的新密码&token=<页面token>" "http://localhost:8134/index.php?p="

实测回显（输入 q1w2e3r4）：

$2y$10$n5JMHnEOnduSgdlN6.tgBebNrfDnrwUUFiS12hybD8X9NpKkyrmc2

3.2 $CONFIG 界面级 JSON 与 Settings 写回（实测）

$CONFIG 是一个 JSON 字符串，控制界面级行为。源码顶部默认值：

$CONFIG = '{"lang":"en","error_reporting":false,"show_hidden":false,"hide_Cols":false,"theme":"light"}';

在 Settings 面板切换「简体中文 + 暗色主题 + 显示隐藏文件」并保存后，实测 config.php 文件头部被自动改写为：

$CONFIG = '{"lang":"zh-CN","error_reporting":false,"show_hidden":true,"hide_Cols":false,"theme":"dark"}';

写回机制（源码 FM_Config::save() 核对 + 实测）：重写文件头 3 行（<?php、//Default Configuration、$CONFIG=...），第 4 行起的原有内容原样保留——自己在 config.php 里加的 $root_path、$auth_users 等覆盖变量不会被冲掉。写回前提是文件可写（bind mount 挂载时不要加 :ro，实测只读挂载时保存静默失效）。

四、参数总览

按用途分七组，全部默认值逐项核对自官方源码 2.6（master 分支）：

关键差异解读：三层里真正常用的是 config.php 覆盖（服务端参数）与 $CONFIG（界面参数）；$external（CDN 地址表）与 FM_SESSION_ID（会话名）属于「源码级常量」，一般不动。

五、核心参数分类详解

5.1 界面级参数（$CONFIG JSON 内五个键）

• lang：界面语言代码。默认 en；挂载 translation.json 后可用 zh-CN 等约 30+ 语言。实测 zh-CN 下界面切换中文；
• error_reporting：PHP 错误是否显示。默认 false（隐藏错误，生产保持 false）；排障时可临时 true 看报错详情；
• show_hidden：是否显示点开头的隐藏文件。默认 false；实测 Settings 面板勾选后写回 true 生效；
• hide_Cols：隐藏列表的 Permissions/Owner 列。默认 false；
• theme：界面主题，light / dark 二选一。

💡 注意：这五项不写在 config.php 变量区，而是集中在 $CONFIG 这一个 JSON 字符串里（可以手工编辑，也可以让 Settings 面板代写）。

5.2 认证与用户参数

• $use_auth（默认 true）：登录开关。改成 false 则任何人无需登录即可管理——只适合纯内网一次性场景，生产严禁；
• $auth_users（默认 admin/user 两个账号）：账号表，键=用户名，值=bcrypt 哈希。登录校验用 password_verify，登录失败强制 sleep(1) 延迟（实测接口层可感知）——天然缓解爆破；
• $readonly_users（默认 array('user')）：只读组。实测 user 登录后界面写操作全部消失，仅剩「查看（view）」与「下载（dl）」两类链接，写接口（新建/删除/上传等）也被服务端拦截；
• $global_readonly（默认 false）：全局只读。改 true 后所有用户包括 admin 都变成只读——适合「纯分发下载目录」场景；
• $directories_users（默认空数组）：按用户指定各自的起始根目录，如 array('ops' => '/var/www/data/ops')；未列出的用户用公共 $root_path。

5.3 文件根目录与显示参数

• $root_path（默认 $_SERVER['DOCUMENT_ROOT']）：最重要的参数。文件管理根目录。官方镜像里默认值=应用所在 /var/www/html，文件操作会落在容器可写层（重建即丢）——Docker 部署必须改为挂载卷路径 /var/www/html/data（实测见部署指南 5.2 排障实录）。也支持指向任意宿主绝对路径（镜像内路径）；
• $root_url（默认 ''）：生成链接用的相对路径，根目录在 Web 站点子目录下时才需要改（如 'subfolder'）；
• $default_timezone（默认 Etc/UTC）：时区。国内环境 Asia/Shanghai，实测生效后列表时间与宿主 ls 一致；
• $datetime_format（默认 m/d/Y g:i A）：文件修改时间的显示格式（PHP date 格式），可改 Y-m-d H:i:s；
• $path_display_mode（默认 full）：文件信息弹窗的路径显示模式，可选 full（完整路径）/ relative（相对根）/ host（主机视角）；
• $favicon_path（默认 ''）：站点图标路径，可填 URL 或站点内相对路径；
• $sticky_navbar（默认 true）：导航栏吸顶。

5.4 编辑器与查看参数

• $edit_files（默认 true）：在线编辑开关（ace.js 编辑器）。关闭后文件只能查看不能改；
• $use_highlightjs（默认 true）：查看页代码高亮（highlight.js）开关；
• $highlightjs_style（默认 vs）：高亮主题样式（如 ir-black 适配暗色）；
• $ext_language：编辑器语言映射表（扩展名 → ace 语言），如 'md' => 'markdown'、'go' => 'golang'，自定义扩展名高亮时补充；
• $ace_fontsize / $ace_theme（默认 12 / textmate）：编辑器字号与主题；
• $online_viewer（默认 'google'）：Office 文档在线预览引擎，可选 'google' / 'microsoft' / false（关闭）。两个引擎都是外部公共服务，内网环境建议 false。

5.5 上传与下载限制参数

• $allowed_file_extensions（默认 ''）：新建/重命名文件允许的扩展名白名单（如 'txt,html,css,js'）；空=不限制；
• $allowed_upload_extensions（默认 ''）：上传文件的白名单；空=不限制。生产建议显式收敛（实测：白名单外的扩展名上传会被拒绝）；
• $exclude_items（默认空数组）：列表中隐藏的文件/目录，支持通配（如 array('*.php', 'personal-folder')）——纯视觉排除，不是权限控制；
• $max_upload_size_bytes（默认 5000000000 ≈ 5GB）：单文件上传上限声明（同时受 PHP upload_max_filesize/post_max_size 约束，需同步调大）；
• $upload_chunk_size_bytes（默认 2000000 ≈ 2MB）：上传分片大小。走 Nginx 反代遇到 413 时把此值调小（如 1MB）。

5.6 IP 访问控制参数

• $ip_ruleset（默认 'OFF'）：三种模式——
  • OFF：不检查 IP（默认）；
  • AND：必须在白名单且不在黑名单才放行；
  • OR：在白名单或不在黑名单即放行；
• $ip_silent（默认 true）：被黑名单拒绝时是否静默（true=直接白屏，false=提示 Access denied. IP restriction applicable，实测源码消息文本）；
• $ip_whitelist / $ip_blacklist（默认 127.0.0.1/::1 与 0.0.0.0/::）：IPv4/IPv6 数组，支持网段。

💡 技术拓展：IP 限制与认证的关系——两者相互独立（源码注释明确「IP 白黑名单独立于登录认证」）。常见组合：$ip_ruleset='AND' + 白名单内网网段 = 仅内网可访问；再叠加 $use_auth=true = 内网还要登录。公网暴露时建议反向代理层做 TLS 与频控，应用层收紧 $allowed_upload_extensions。

5.7 编码与其他

• $iconv_input_encoding（默认 UTF-8）：文件名转码输入编码，GBK 老文件系统场景改 GBK；
• $external（源码级）：Bootstrap/ace.js/highlight.js 等前端资源的 CDN 引用集中定义处，离线内网环境需替换为本地资源；
• FM_SESSION_ID（源码常量，默认 filemanager）：PHP 会话名，同域名部署多套实例时可区分。

六、生产配置模板

适用场景：4GB 内存、普通磁盘 VPS/内网服务器，10 人以内小团队，管理 /srv/files（容器内挂载为 /var/www/html/data），仅内网访问。实测可用的完整 config.php：

<?php
// ===== 界面级（Settings 面板会自动维护此行，也可手工编辑）=====
$CONFIG = '{"lang":"zh-CN","error_reporting":false,"show_hidden":false,"hide_Cols":false,"theme":"light"}';

// ===== 文件根目录与显示 =====
$root_path = '/var/www/html/data';        // 指向挂载卷，数据持久化的关键
$default_timezone = 'Asia/Shanghai';      // 时间按本地时区显示
$datetime_format = 'Y-m-d H:i:s';         // 修改时间显示格式
$path_display_mode = 'relative';          // 信息弹窗显示相对路径

// ===== 认证与用户 =====
$auth_users = array(
    'admin' => '$2y$10$n5JMHnEOnduSgdlN6.tgBebNrfDnrwUUFiS12hybD8X9NpKkyrmc2', //q1w2e3r4
    'user' => '$2y$10$Fg6Dz8oH9fPoZ2jJan5tZuv6Z4Kp7avtQ9bDfrdRntXtPeiMAZyGO' //12345
);
$readonly_users = array('user');          // user 只能浏览下载
$global_readonly = false;

// ===== 上传与下载 =====
$allowed_upload_extensions = 'zip,tar,gz,md,txt,pdf,png,jpg,docx,xlsx'; // 上传白名单
$upload_chunk_size_bytes = 1000000;       // 1MB 分片，反代 413 时再调小
$exclude_items = array('*.bak');          // 列表隐藏备份文件

// ===== 访问控制（内网限定）=====
$ip_ruleset = 'AND';
$ip_whitelist = array('127.0.0.1', '::1', '192.168.1.'); // 仅本机与内网网段
$ip_silent = true;                        // 被拒时静默

逐项说明：$root_path 保证数据落盘（见部署指南排障实录）；账号表首次部署即弃用官方默认密码；上传白名单按团队实际文件类型收敛；$ip_ruleset='AND' + 内网白名单实现「仅内网可达」，与登录认证双保险。资源开销上 Tiny File Manager 为单 PHP 进程常驻，实测空载内存约 10–20MB 量级，4GB 机器可轻松承载；无数据库、无定时任务，无额外磁盘开销。

七、常见问题

Q1：改了 config.php 不生效？ 确认三件事：文件挂载路径是 /var/www/html/config.php（应用同目录）；修改后执行了 docker compose restart；PHP 语法无误（写错会导致白屏，docker logs 看报错）。

Q2：Settings 面板保存后界面没变化？ config.php 挂载是否加了 :ro（只读挂载时应用无法写回 $CONFIG 行，保存静默失效，实测确认）；去掉 :ro 重启即可。

Q3：如何批量生成多个用户的密码哈希？ 每个用户用 https://tinyfilemanager.github.io/docs/pwd.html 或 pwdhash 接口（3.1）生成 bcrypt 哈希后追加进 $auth_users，重启生效。注意 $auth_users 是整体覆盖，新增用户要把原有条目一并保留。

Q4：中文文件名乱码？ 确认 $iconv_input_encoding 与文件系统实际编码一致（老 GBK 环境改 GBK）；同时 $CONFIG.lang=zh-CN 只影响界面语言，与文件名编码无关。

Q5：公网部署还需要注意什么？ 除本文参数外，务必：改掉官方默认密码、收紧上传白名单、$ip_ruleset 限制来源或前置反向代理认证；应用自身无 HTTPS，公网必须由反代终结 TLS。操作审计与回收站能力本应用不具备，重要目录依赖外部备份。

八、参考链接

• 官方仓库源码（参数出处）：https://github.com/prasathmani/tinyfilemanager/blob/master/tinyfilemanager.php
• 官方示例配置：https://tinyfilemanager.github.io/config-sample.txt
• 官方密码哈希生成页：https://tinyfilemanager.github.io/docs/pwd.html
• 本专栏选型参考：《Tiny File Manager 介绍与选型指南》
• 本专栏部署实战：《Tiny File Manager Docker Compose 部署指南》
• 本专栏操作手册：《Tiny File Manager 2.6 常用操作详解》