Tiny File Manager Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上，用官方镜像 tinyfilemanager/tinyfilemanager:master 从零部署 Tiny File Manager，完成首次登录、修改默认密码、文件根目录持久化与中文界面的全链路验证，并沉淀部署过程中实测踩到的三个坑（数据不落盘、Settings 保存失效、上传文件名异常）的定位与解决方案。全部命令与回显均在 2026-11-01 于 Ubuntu 22.04 实机实测通过。

一、环境信息

本文实测所用的服务器环境与软件版本如下（实测日期 2026-11-01）：

• 操作系统：Ubuntu 22.04（x86_64）
• Docker：24.x 与 Docker Compose v2（docker compose 子命令形态）
• 应用版本：Tiny File Manager 2.6（官方 GitHub Releases 最新稳定版为 2.6，发布于 2024-11-05；官方 master 标签镜像基于 master 分支 2.6 开发代码构建，页面页脚实测显示 Tiny File Manager 2.6）
• 镜像：tinyfilemanager/tinyfilemanager:master（Docker Hub 官方仓库 2026-07-20 构建更新，压缩后约 30MB）
• 运行时：镜像内置 PHP 7.4.33（启动日志实测回显 PHP 7.4.33 Development Server (http://0.0.0.0:80) started，以 PHP 内置服务器对外服务，无 Apache/Nginx/FPM）
• Web 对外端口：8134（映射到应用内置服务器的 80）
• 数据目录：部署目录下 data/（bind mount 到应用内 /var/www/html/data，作为文件管理根目录）
• 配置文件：config.php（覆盖默认配置）与 translation.json（中文语言包）两个挂载文件
• 默认账号：admin / admin@123（管理员）、user / 12345（只读）——首次登录后必须改密，本文演示改为 admin / q1w2e3r4
• 组件定位与版本背景见 《Tiny File Manager 介绍与选型指南》

二、镜像选型说明

官方唯一维护的镜像仓库是 Docker Hub 的 tinyfilemanager/tinyfilemanager（来源 Docker Hub API 实查，2026-11-01）。镜像 tag 共四条（按更新时间排序）：

⚠️ 注意：官方镜像没有 2.6 标签，latest 标签停留在 2023 年的 2.5.3 时代构建。因此「部署最新稳定版 2.6」的正确姿势是选 master 标签（2.6 版本号在 master 分支持续修复，页面页脚即显示 2.6），而不是想当然地找 latest 或 2.6。

镜像内部结构（来源官方 Dockerfile 与容器内实查，2026-11-01）：

• 基底 php:7.4-cli-alpine，额外安装 zip 扩展（docker-php-ext-install zip，打包/解压功能依赖它）与 libzip-dev、oniguruma-dev 两个系统库；
• 应用代码 tinyfilemanager.php 被 COPY 为 /var/www/html/index.php；
• 启动命令为 php -S 0.0.0.0:80——PHP 内置开发服务器，单进程模型，轻量但不适合高并发公网场景（官方定位就是轻量自用）。

三、前置条件

1. 服务器已安装 Docker 与 Docker Compose v2（docker compose version 可执行）。
2. 对外端口未被占用（本文用 8134）：

ss -ltn | grep ':8134' || echo "8134 空闲"

实测回显（2026-11-01）：

8134 空闲

3. 拉取镜像（Docker Hub 官方仓库，直连可拉取；如拉取缓慢可走代理）：

docker pull tinyfilemanager/tinyfilemanager:master

实测回显：

master: Pulling from tinyfilemanager/tinyfilemanager
Digest: sha256:76ff564e7e42b5ed6fb2161fb11bbf40a38c9dd88838d467235f6093dd5b74a1
Status: Downloaded newer image for tinyfilemanager/tinyfilemanager:master
docker.io/tinyfilemanager/tinyfilemanager:master

4. 规划部署目录与数据目录。本文把全部宿主侧产物收敛在一个部署目录中（compose 文件、data/、config.php、translation.json 同级）。

四、部署步骤

4.1 准备配置覆盖文件（推荐先于启动完成）

Tiny File Manager 支持与应用同目录放置 config.php 覆盖全部默认配置。强烈建议首次部署就带上它，原因有二：一是把文件管理根目录指向挂载卷（否则新建文件落在容器可写层，见 5.2 排障实录）；二是首登即改默认密码。

在部署目录创建 config.php（默认账号 admin 的密码哈希可用官方在线生成页 https://tinyfilemanager.github.io/docs/pwd.html 生成，本文实测 q1w2e3r4 的哈希如下）：

<?php
// Tiny File Manager 外部配置覆盖文件（与 index.php 同目录自动加载）
$root_path = '/var/www/html/data';
$default_timezone = 'Asia/Shanghai';
$auth_users = array(
    'admin' => '$2y$10$n5JMHnEOnduSgdlN6.tgBebNrfDnrwUUFiS12hybD8X9NpKkyrmc2', //q1w2e3r4
    'user' => '$2y$10$Fg6Dz8oH9fPoZ2jJan5tZuv6Z4Kp7avtQ9bDfrdRntXtPeiMAZyGO' //12345
);
$readonly_users = array('user');

文件要点：

• $root_path：文件管理根目录。指向 /var/www/html/data（即 compose 挂载卷）后，所有新建/上传/编辑的文件都真实落到宿主机 data/ 目录；
• $default_timezone：文件修改时间按本地时区显示（默认 UTC，差 8 小时）；
• $auth_users：账号表，值为 bcrypt 哈希（password_verify 校验），注释里写明文便于自查——admin 已改为 q1w2e3r4，user 保留官方默认只读账号 12345；
• $readonly_users：只读用户组，组内账号只能浏览/下载，不能写。

💡 若不想一上来就改密，可先只保留 $root_path 与 $default_timezone 两行，用默认 admin/admin@123 首登，改密方法见 4.5 与《配置参数详解》篇。

4.2 准备中文语言包（可选）

官方镜像只打包了 index.php 一个文件，translation.json 语言包不在镜像内——缺省时界面只有英文。从官方仓库取一份语言包放到部署目录（与 index.php 同目录挂载生效，仓库 Releases 源码包内也附带此文件）：

curl -sLO https://raw.githubusercontent.com/prasathmani/tinyfilemanager/master/translation.json
ls -la translation.json

实测回显：

-rw-r--r-- 1 root root 1034961 Nov  1 14:51 translation.json

4.3 Compose 全文件

在部署目录创建 docker-compose.yml（显式 name 项目名，避免与其他栈同名互删）：

name: tiny-file-manager-2.6-stack

services:
  web:
    image: tinyfilemanager/tinyfilemanager:master
    container_name: tiny-file-manager-2.6-web
    ports:
      - "8134:80"
    volumes:
      - ./data:/var/www/html/data
      - ./config.php:/var/www/html/config.php
      - ./translation.json:/var/www/html/translation.json:ro
    restart: unless-stopped

文件要点：

• 8134:80：宿主 8134 是对外入口，80 是镜像内 PHP 内置服务器固定监听口；
• ./data:/var/www/html/data：文件管理根目录的 bind mount（配合 4.1 的 $root_path 指向），这是数据持久化的关键；
• ./config.php：不加 :ro 只读标记——Web 界面的 Settings 面板保存时会写回这个文件的头部（见 5.3 排障实录），只读挂载会导致保存静默失效；
• ./translation.json:ro：语言包只读即可，应用只读取不修改；
• 官方镜像没有声明 volume 也没有环境变量配置项，全部定制走 config.php（见 6.1）。

4.4 启动与状态确认

docker compose up -d && docker compose ps

实测回显：

[+] Running 3/3
 ✔ Network tiny-file-manager-2.6-stack_default  Created
 ✔ Container tiny-file-manager-2.6-web          Created
 ✔ Container tiny-file-manager-2.6-web          Started
NAME                        IMAGE                                    COMMAND                  SERVICE   CREATED         STATUS         PORTS
tiny-file-manager-2.6-web   tinyfilemanager/tinyfilemanager:master   "docker-php-entrypoi…"   web       2 seconds ago   Up 2 seconds   0.0.0.0:8134->80/tcp, [::]:8134->80/tcp

查看应用启动日志，确认内置服务器已监听：

docker logs tiny-file-manager-2.6-web 2>&1 | head -3

实测回显：

[Sun Nov  1 06:51:43 2026] PHP 7.4.33 Development Server (http://0.0.0.0:80) started

用 curl 确认登录页可达：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8134/

实测回显：

200

4.5 首次登录与改密验证

浏览器访问 http://<服务器IP>:8134/，出现 Tiny File Manager 登录页。若按 4.1 已把 admin 密码改为 q1w2e3r4，直接用新密码登录；若未改密则用 admin / admin@123。两种改密途径：

• 改 config.php（本文采用）：替换 $auth_users['admin'] 的哈希后 docker compose restart，实测验证新旧密码——旧密码 admin@123 登录返回 Login failed. Invalid username or password，新密码 q1w2e3r4 登录成功（页面提示 You are logged in）；
• 用应用内置哈希接口生成：Settings 面板的 Set your password 输入新密码会调 pwdhash 接口返回 bcrypt 哈希（实测返回 $2y$10$n5JMHnEOnduSgdlN6.tgBebNrfDnrwUUFiS12hybD8X9NpKkyrmc2），把它填进 config.php 即可。

💡 说明：Tiny File Manager 没有网页端「修改密码」按钮，密码变更一律走 config.php 的账号表（或官方 pwd.html 在线生成页）。详见 《Tiny File Manager 2.6 配置参数详解》。

4.6 验证中文界面

登录后打开 Settings 面板（顶部导航 Settings），把 Language 切到 简体中文、Theme 切到暗色并保存——保存动作会把选项写回 config.php 头部的 $CONFIG 行，实测写回结果：

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

刷新后界面即切换为中文暗色主题（前提：4.2 的 translation.json 已挂载）。

五、数据持久化说明与排障实录

5.1 持久化原理

Tiny File Manager 的「文件管理根目录」由 $root_path 决定，默认取 PHP 的 $_SERVER['DOCUMENT_ROOT']——在官方镜像里就是应用代码所在的 /var/www/html。因此：

• 不挂 config.php 改 $root_path：界面里新建/上传的文件全部落在 /var/www/html（容器可写层）。容器 up -d 重建后全部丢失；
• 挂 config.php 且 $root_path = '/var/www/html/data'：文件全部落到 bind mount 的宿主 data/ 目录，docker compose down/up 后数据完好。

5.2 排障实录一：新建目录宿主侧看不见，重建后丢失

现象：部署初期（未挂 config.php），在 Web 界面新建目录 docs、文件 notes.md 均提示创建成功（页面回显 Folder <b>docs</b> Created），但宿主挂载目录 data/ 始终为空；随后一次 docker compose up -d（recreate）后文件全部消失。

定位：进应用内查看实际落盘位置——新建的 docs/、notes.md 出现在 /var/www/html/ 而非挂载的 /var/www/html/data/，确认根目录默认是应用目录（容器可写层）而非挂载卷。

解决：按 4.1 挂载 config.php 并设置 $root_path = '/var/www/html/data'，重启后再次新建目录 projects，宿主侧立即可见：

ls -la ./data/

实测回显：

drwxr-xr-x 3 root root 4096 Nov  1 14:56 .
drwxr-xr-x 2 root root 4096 Nov  1 14:56 projects

再执行 docker compose down && docker compose up -d 重建，projects 目录仍在——持久化闭环确认。

5.3 排障实录二：Settings 面板保存失效

现象：把 config.php 以 :ro 只读挂载后，在 Settings 面板改语言/主题点保存，界面无报错但刷新后不生效。

定位：应用保存 Settings 的实现（源码 FM_Config::save()）会把新的 $CONFIG JSON 行重写回 config.php 文件头部，重写前检查 is_writable()——只读挂载时该检查为假，保存被静默跳过。

解决：config.php 挂载去掉 :ro（本文 4.3 的写法）。重新保存后实测文件头部被正确改写为 $CONFIG = '{"lang":"zh-CN",...,"theme":"dark"}'，界面中文暗色生效。

⚠️ 注意：应用对 config.php 的写回是「重写文件头 3 行（<?php + //Default Configuration + $CONFIG=...）、保留第 4 行起的原有内容」，因此自己加的 $root_path 等覆盖变量不受影响，实测验证成立。

5.4 排障实录三：上传文件名变成时间戳

现象：用 curl 直传文件（multipart 表单）时，落盘文件名变成 _261101150003.zip 这样的「下划线+时间戳」。

定位：上传处理逻辑中，最终文件名取自表单的 fullpath 字段而不是 multipart 的 filename 字段；fullpath 为空时拼接出「空文件名+时间戳」。浏览器端由 dropzone 自动带上 fullpath，直连接口时必须手工传。

解决：multipart 表单必须包含 fullpath=<目标文件名>（以及分片字段 dzchunkindex=0、dztotalchunkcount=1），实测返回 {"status":"success","info":"file upload successful"} 且落盘文件名正确。接口级上传实测见 《Tiny File Manager 2.6 常用操作详解》。

六、配置参数说明

6.1 配置通道总览

官方镜像不提供任何环境变量配置项（Dockerfile 的 CMD 是固定字符串，无 ENV 注入点），全部配置走三条通道：

全部配置参数（$root_path、$auth_users、$allowed_upload_extensions、$ip_ruleset 等 30+ 项）逐项含义、默认值与修改方法见 《Tiny File Manager 2.6 配置参数详解》。

6.2 最小配置示例与逐项说明

见 4.1 的 config.php。逐项：

• $root_path：文件管理根目录，必须指向挂载卷路径，是数据持久化的开关；
• $default_timezone：界面时间显示时区，国内环境用 Asia/Shanghai；
• $auth_users：账号表（用户名 => bcrypt 哈希），首登必改 admin 默认密码；
• $readonly_users：只读组，生产建议把日常查看类账号放入。

七、等价 docker run

与本文 compose 等价的单命令形态（来源官方 README 推荐用法，挂载路径与端口按本文实测值）：

docker run -d \
  -v ./data:/var/www/html/data \
  -v ./config.php:/var/www/html/config.php \
  -v ./translation.json:/var/www/html/translation.json:ro \
  -p 8134:80 \
  --restart=unless-stopped \
  --name tiny-file-manager-2.6-web \
  tinyfilemanager/tinyfilemanager:master

与 compose 的对应关系：-v 三条挂载、-p 端口映射、--restart 重启策略一一对应；compose 版本 advantage 在于配置文件化、up/down 一键管理与后续扩展。

八、常用运维命令

以下命令均在部署目录内执行（2026-11-01 实测）：

# 查看运行状态
docker compose ps
# 实测回显：STATUS 列 Up，PORTS 列 0.0.0.0:8134->80/tcp

# 查看应用日志（内置服务器访问日志也在其中）
docker compose logs -f --tail 20
# 实测回显节选：
# [Sun Nov  1 06:51:43 2026] PHP 7.4.33 Development Server (http://0.0.0.0:80) started
# [Sun Nov  1 06:52:10 2026] [200]: GET /index.php

# 修改 config.php 后使其生效（重启应用）
docker compose restart
# 实测回显：Container tiny-file-manager-2.6-web  Started

# 升级镜像（master 标签跟随上游更新）
docker compose pull && docker compose up -d
# 实测回显节选：
# [+] Running 2/2
# ✔ Container tiny-file-manager-2.6-web  Recreated
# ✔ Container tiny-file-manager-2.6-web  Started

# 停止并删除应用（data/config.php 等宿主文件保留）
docker compose down
# 实测回显节选：
# ✔ Container tiny-file-manager-2.6-web  Removed
# ✔ Network tiny-file-manager-2.6-stack_default  Removed

💡 说明：升级（pull + up -d）会重建应用容器，容器可写层内容会丢失——只要按第五章把 $root_path 指向挂载卷，用户数据就不受影响；这也是生产使用必须做 5.1 持久化的原因。

九、常见问题

Q1：访问页面出现登录页但界面没有样式（纯 HTML）？ 应用的 Bootstrap/ace.js 等前端资源默认走 jsdelivr/cdnjs 公共 CDN。纯内网环境拿不到 CDN 资源时界面会退化成无样式 HTML。解决：浏览器可达外网即可；完全离线环境需自行本地化这些静态资源（源码 $external 数组集中定义了全部 CDN 引用）。

Q2：忘记 admin 密码怎么办？ config.php 里 $auth_users['admin'] 的哈希换成新密码的 bcrypt 哈希（用 https://tinyfilemanager.github.io/docs/pwd.html 生成），docker compose restart 生效。极端情况（config.php 也丢了）可直接删掉挂载的 config.php 恢复官方默认账号再重新配置。

Q3：用 curl 调接口时 POST 全部无效？ 应用对「没有 ?p= 查询参数且无文件上传」的请求会先 302 重定向到 ?p=，POST 表单数据在重定向中丢失。所有写操作必须 POST 到 /index.php?p= 形态的地址（实测排障确认）。接口级操作与回显见 《Tiny File Manager 2.6 常用操作详解》。

Q4：8134 端口被占用了？ 换一个空闲端口即可：改 compose 的 "8134:80" 左侧宿主端口，docker compose up -d 重建。查看占用的命令：ss -ltn | grep ':8134'。

Q5：上传大文件失败？ 上传分片大小由源码 $upload_chunk_size_bytes（默认约 2MB）控制，PHP 侧还受 upload_max_filesize/post_max_size/memory_limit 三个 php.ini 项约束。官方镜像用内置服务器，大文件建议调大 $max_upload_size_bytes 并确认 PHP 限制（见配置参数详解篇对应小节）。

十、参考链接

• GitHub 仓库：https://github.com/prasathmani/tinyfilemanager
• 官方 Docker Hub：https://hub.docker.com/r/tinyfilemanager/tinyfilemanager
• 官方 Dockerfile（镜像结构出处）：https://github.com/prasathmani/tinyfilemanager/blob/master/Dockerfile
• 官方密码哈希生成页：https://tinyfilemanager.github.io/docs/pwd.html
• 本专栏选型参考：《Tiny File Manager 介绍与选型指南》
• 本专栏配置参考：《Tiny File Manager 2.6 配置参数详解》
• 本专栏操作手册：《Tiny File Manager 2.6 常用操作详解》