Tiny File Manager - 阿里云 OSS 版本

基于 Tiny File Manager v2.6 改造的阿里云 OSS 对象存储版本，支持通过 Web 界面管理 OSS 文件。

🌟 主要特性

• ✅ 插件式集成：在原版基础上添加 OSS 支持，保留本地文件系统功能
• ✅ 一键切换：通过配置开关在本地模式和 OSS 模式间切换
• ✅ 完整功能：支持浏览、上传、下载、创建、编辑、重命名、复制、删除等所有操作
• ✅ 自定义域名：支持使用绑定到 Bucket 的自定义域名
• ✅ 内网优化：ECS 内网访问自动使用内网 endpoint，节省流量费用
• ✅ 批量操作：优化的文件夹重命名和删除，支持大量文件处理

📋 系统要求

• PHP >= 7.2
• Composer（用于安装 OSS SDK）
• 阿里云 OSS 账号和 Bucket

🚀 快速开始

1. 安装依赖

使用提供的安装脚本自动安装 Composer 和 OSS SDK：

bash install_oss.sh

或手动安装：

# 安装 Composer（如果未安装）
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

# 安装阿里云 OSS SDK
composer require aliyuncs/oss-sdk-php

2. 配置 OSS

编辑 myfile.php 文件（约第 20-37 行），修改 OSS 配置：

// ========== 阿里云 OSS 配置 (插件式集成) ==========
$use_aliyun_oss = true;  // 启用 OSS 模式（设为 false 则使用本地文件系统）
$oss_config = array(
    'access_key_id' => 'YOUR_ACCESS_KEY_ID',           // 阿里云 AccessKey ID
    'access_key_secret' => 'YOUR_ACCESS_KEY_SECRET',   // 阿里云 AccessKey Secret
    'endpoint' => 'oss-cn-hangzhou.aliyuncs.com',      // OSS endpoint（根据你的地域修改）
    'bucket' => 'your-bucket-name',                     // OSS Bucket 名称
    'use_internal' => false,                            // 是否使用内网 endpoint（ECS 内网访问设为 true）
    'use_ssl' => true,                                  // 是否使用 HTTPS
    'prefix' => '',                                     // OSS 对象前缀（可选，如 'uploads/'）
    'custom_domain' => 'https://your-domain.com',       // 自定义域名（可选）
);

3. 访问管理界面

在浏览器中访问：http://your-domain.com/myfile.php

默认用户名和密码：

• 用户名：admin
• 密码：admin@123

⚠️ 安全提示：首次登录后请立即修改默认密码！

⚙️ 配置说明

OSS 配置项详解

配置项	类型	必填	说明
access_key_id	string	✅	阿里云 AccessKey ID
access_key_secret	string	✅	阿里云 AccessKey Secret
endpoint	string	✅	OSS endpoint，如 oss-cn-hangzhou.aliyuncs.com
bucket	string	✅	OSS Bucket 名称
use_internal	boolean	❌	是否使用内网 endpoint（ECS 建议开启）
use_ssl	boolean	❌	是否使用 HTTPS（默认 true）
prefix	string	❌	对象前缀，用于隔离不同应用的文件
custom_domain	string	❌	自定义域名（需先在 OSS 绑定）

Endpoint 地域列表

地域	公网 Endpoint	内网 Endpoint
华东1（杭州）	oss-cn-hangzhou.aliyuncs.com	oss-cn-hangzhou-internal.aliyuncs.com
华东2（上海）	oss-cn-shanghai.aliyuncs.com	oss-cn-shanghai-internal.aliyuncs.com
华北2（北京）	oss-cn-beijing.aliyuncs.com	oss-cn-beijing-internal.aliyuncs.com
华南1（深圳）	oss-cn-shenzhen.aliyuncs.com	oss-cn-shenzhen-internal.aliyuncs.com

更多地域请参考：阿里云 OSS 访问域名

内网访问优化

如果您的 Web 服务器是阿里云 ECS 实例，建议启用内网访问：

'use_internal' => true,

优势：

• ✅ 访问速度更快
• ✅ 节省外网流量费用
• ✅ 自动使用 HTTPS 协议

注意：程序会自动将 oss-cn-hangzhou.aliyuncs.com 转换为 https://oss-cn-hangzhou-internal.aliyuncs.com

自定义域名配置

如果您已经在 OSS 控制台绑定了自定义域名：

1. 在 OSS 控制台绑定域名（例如：files.example.com）
2. 配置 CNAME 解析
3. 在配置中设置：

'custom_domain' => 'https://files.example.com',

效果：文件访问链接将使用自定义域名而不是 OSS 默认域名。

📁 功能说明

支持的操作

• 📂 浏览文件夹：支持多级目录浏览
• ⬆️ 上传文件：支持拖拽上传、分块上传大文件
• ⬇️ 下载文件：直接下载或使用自定义域名
• ➕ 创建文件/文件夹：包括 0 字节文件
• ✏️ 编辑文件：在线文本编辑器，支持语法高亮
• 📝 查看文件：支持文本、图片、音频、视频预览
• 🔄 重命名：文件和文件夹重命名（支持大量文件的文件夹）
• 📋 复制：文件和文件夹复制
• 🗑️ 删除：文件和文件夹删除（批量删除优化）
• 🔍 搜索：在当前目录搜索文件

批量操作优化

对于包含大量文件的文件夹，系统进行了以下优化：

• 文件夹重命名：使用批量 API，每次处理 1000 个对象
• 文件夹删除：批量删除，避免逐个删除导致超时
• 防重复提交：操作完成前进程崩溃时，刷新页面会正确显示结果

🔧 技术架构

核心设计

1. 适配器模式：FM_OSS_Adapter 类封装所有 OSS 操作
2. 函数包装：通过 fm_* 系列包装函数透明路由
3. 路径转换：getOSSKey() 自动转换本地路径为 OSS 对象键
4. 目录模拟：使用前缀和分隔符模拟文件系统目录结构

包装函数列表

所有原生 PHP 文件系统函数都有对应的包装函数：

原生函数	包装函数	说明
is_file()	fm_is_file()	判断是否为文件
is_dir()	fm_is_dir()	判断是否为目录
file_exists()	fm_file_exists()	判断文件/目录是否存在
filesize()	fm_filesize()	获取文件大小
filemtime()	fm_filemtime()	获取修改时间
file_get_contents()	fm_file_get_contents()	读取文件内容
file_put_contents()	fm_file_put_contents()	写入文件内容
scandir()	fm_scandir()	列出目录内容
rename()	fm_rename()	重命名文件/目录
unlink()	fm_unlink()	删除文件
rmdir()	fm_rmdir()	删除目录

🐛 常见问题

1. 上传失败：failed to open output stream

原因：本地临时目录不可写

解决方法：

# 检查临时目录权限
ls -la /tmp

# 修改权限
chmod 777 /tmp

2. 图片无法显示

原因：未配置自定义域名或 Bucket 权限设置

解决方法：

• 配置自定义域名
• 或在 OSS 控制台设置 Bucket 为公共读

3. 删除/重命名文件夹时 502 错误

原因：文件夹包含大量文件，PHP 执行超时

解决方法：

• ✅ 已优化：使用批量 API 减少调用次数
• ✅ 已优化：即使超时，刷新后会显示正确结果
• 如仍有问题，可增加 PHP 超时时间：

// 在 myfile.php 顶部添加
set_time_limit(300); // 5分钟

4. 内网访问连接超时

原因：配置错误或网络问题

解决方法：

1. 确认 ECS 和 OSS 在同一地域
2. 检查配置：

'use_internal' => true,  // 必须为 true
'endpoint' => 'oss-cn-hangzhou.aliyuncs.com',  // 不要手动添加 -internal

3. 程序会自动转换为 https://oss-cn-hangzhou-internal.aliyuncs.com

5. 文件重命名提示"源文件不存在"

原因：表单重复提交

解决方法：

• ✅ 已修复：刷新页面会检查操作是否已完成
• 如果操作确实成功，忽略此错误即可

🔐 安全建议

1. 修改默认密码：首次登录后立即修改
2. 使用 HTTPS：启用 SSL 加密传输
3. 限制访问：使用 .htaccess 或 Nginx 配置限制 IP
4. 定期更新：关注安全更新
5. AccessKey 安全：
   • 使用 RAM 子账号，仅授予必要的 OSS 权限
   • 定期轮换 AccessKey
   • 不要将 AccessKey 提交到代码仓库

📝 更新日志

v2.6-OSS (2025-11-26)

新增功能：

• ✅ 阿里云 OSS 完整支持
• ✅ 自定义域名支持
• ✅ 内网访问自动优化
• ✅ 0 字节文件显示

性能优化：

• ✅ 文件夹重命名批量操作（最多 1000 个/批次）
• ✅ 文件夹删除批量操作
• ✅ 防重复提交机制

Bug 修复：

• ✅ 修复图片查看 getimagesize 错误
• ✅ 修复文件编辑保存失败
• ✅ 修复文件夹删除 502 错误
• ✅ 修复内网访问端口错误
• ✅ 修复 fileExists 无法识别目录

📞 技术支持

• 原版项目：Tiny File Manager
• 阿里云 OSS SDK：aliyuncs/oss-sdk-php
• OSS 文档：阿里云对象存储 OSS

📄 许可证

本项目基于 Tiny File Manager，遵循 GPL-3.0 许可证。

---

⚠️ 免责声明：请确保遵守阿里云服务条款，合理使用 OSS 资源。本项目仅供学习交流使用。