279 lines
9.2 KiB
Markdown
279 lines
9.2 KiB
Markdown
# 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 资源。本项目仅供学习交流使用。
|