From 507f9d64dc24b869f1e1fa737a7d7bf8674da617 Mon Sep 17 00:00:00 2001 From: ghol Date: Wed, 26 Nov 2025 05:27:09 +0000 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 278 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 278 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4bd95fa --- /dev/null +++ b/README.md @@ -0,0 +1,278 @@ +# 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 +bash install_oss.sh +``` + +或手动安装： + +```bash +# 安装 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 配置： + +```php +// ========== 阿里云 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 访问域名](https://help.aliyun.com/document_detail/31837.html) + +### 内网访问优化 + +如果您的 Web 服务器是阿里云 ECS 实例，建议启用内网访问： + +```php +'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. 在配置中设置： + +```php +'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 + +**原因**：本地临时目录不可写 + +**解决方法**： +```bash +# 检查临时目录权限 +ls -la /tmp + +# 修改权限 +chmod 777 /tmp +``` + +### 2. 图片无法显示 + +**原因**：未配置自定义域名或 Bucket 权限设置 + +**解决方法**： +- 配置自定义域名 +- 或在 OSS 控制台设置 Bucket 为公共读 + +### 3. 删除/重命名文件夹时 502 错误 + +**原因**：文件夹包含大量文件，PHP 执行超时 + +**解决方法**： +- ✅ 已优化：使用批量 API 减少调用次数 +- ✅ 已优化：即使超时，刷新后会显示正确结果 +- 如仍有问题，可增加 PHP 超时时间： + +```php +// 在 myfile.php 顶部添加 +set_time_limit(300); // 5分钟 +``` + +### 4. 内网访问连接超时 + +**原因**：配置错误或网络问题 + +**解决方法**： +1. 确认 ECS 和 OSS 在同一地域 +2. 检查配置： +```php +'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](https://github.com/prasathmani/tinyfilemanager) +- **阿里云 OSS SDK**：[aliyuncs/oss-sdk-php](https://github.com/aliyun/aliyun-oss-php-sdk) +- **OSS 文档**：[阿里云对象存储 OSS](https://help.aliyun.com/product/31815.html) + +## 📄 许可证 + +本项目基于 Tiny File Manager，遵循 GPL-3.0 许可证。 + +--- + +**⚠️ 免责声明**：请确保遵守阿里云服务条款，合理使用 OSS 资源。本项目仅供学习交流使用。