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