ghol/tfm-oss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
tfm-oss/README.md
T
ghol 507f9d64dc 添加 README.md
2025-11-26 05:27:09 +00:00

9.2 KiB
Raw Permalink Blame History

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
  1. 程序会自动转换为 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，遵循 GPL-3.0 许可证。

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

Reference in New Issue View Git Blame Copy Permalink