# oss-browser-app

**Repository Path**: wstv/oss-browser-app

## Basic Information

- **Project Name**: oss-browser-app
- **Description**: oss-browser-app  oss 阿里云app相册同步助手
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 阿里云 OSS 管理器（直接阿里云oss sdk 无其他网络接口调用，所有缓存信息均存储到客户端app）

一款简洁高效的阿里云 OSS 文件管理 Android 应用，支持文件浏览、上传、预览和相册同步功能。

## ✨ 功能特性

### 📁 文件管理
- **目录浏览**: 支持多级目录导航，可新建文件夹
- **文件预览**: 
  - 图片预览：支持缩放、拖动
  - 视频预览：支持在线播放
- **文件操作**: 
  - 复制文件链接
  - 删除文件/文件夹
  - 下载文件到本地
- **智能识别**: 自动识别文件类型，显示对应图标

### 📸 相册同步
- **相册管理**: 查看所有本地相册，快速切换
- **批量选择**: 支持多选文件，批量上传
- **智能检测**: 自动检测已上传文件，避免重复
- **上传队列**: 
  - 显示上传进度
  - 已存在文件可选择覆盖
  - 失败自动重试

### 🎨 现代化设计
- **Material Design 3**: 采用最新设计规范
- **简约风格**: 清爽的界面，流畅的动画
- **卡片布局**: 信息层次分明，易于阅读
- **响应式交互**: 按钮点击效果，提升用户体验

## 📱 截图预览

### 主界面 - OSS配置
配置阿里云 OSS 的基本信息：
- Endpoint (地域节点)
- Bucket 名称
- Access Key ID / Secret
- 自定义域名(可选)

### 文件浏览器
- 树形目录结构
- 支持创建文件夹
- 长按显示操作菜单
- 下拉刷新

### 相册同步
- 横向相册选择器
- 网格照片展示
- 多选状态标记
- 上传进度提示

## 🚀 技术架构

### 核心技术栈
```
- Kotlin + Android 原生开发
- 协程 (Coroutines) 异步处理
- Material Design 3 UI组件
- 阿里云 OSS Android SDK
```

### 主要依赖
```kotlin
// OSS SDK
implementation("com.aliyun.dpa:oss-android-sdk:2.9.13")

// 图片加载
implementation("io.coil-kt:coil:2.5.0")
implementation("com.github.chrisbanes:PhotoView:2.3.0")

// 视频播放
implementation("androidx.media3:media3-exoplayer:1.2.1")
implementation("androidx.media3:media3-ui:1.2.1")

// Material Design 3
implementation("com.google.android.material:material:1.11.0")
```

## 📦 安装说明

### 1. 克隆项目
```bash
git clone https://gitee.com/wstv/oss-browser-app.git
cd oss-browser-app
```

### 2. 配置签名
将 `app.keystore` 文件放到项目根目录，编辑 `app/build.gradle.kts`:

```kotlin
signingConfigs {
    create("release") {
        storeFile = file("../app.keystore")
        storePassword = ""
        keyAlias = ""
        keyPassword = ""
    }
}
```

### 3. 编译打包
```bash
# Windows
gradlew.bat assembleRelease

# 生成的 APK 位于
app\build\outputs\apk\release\app-release.apk
```

## 🔧 使用指南

### 首次配置

1. **安装应用**到手机
2. **打开应用**，填写 OSS 配置信息：
   - Endpoint: `https://oss-cn-hangzhou.aliyuncs.com`
   - Bucket: 你的存储桶名称
   - Access Key ID: 从阿里云控制台获取
   - Access Key Secret: 从阿里云控制台获取
   - 自定义域名: (可选) 如果配置了CDN
3. **点击保存配置**

### 权限说明

应用需要以下权限：
- **存储权限**: 读取本地相册文件
- **网络权限**: 访问阿里云 OSS 服务
- **通知权限**: 显示上传进度通知

Android 13+ 需要授予：
- 读取图片权限 (READ_MEDIA_IMAGES)
- 读取视频权限 (READ_MEDIA_VIDEO)

### 文件浏览

1. 点击**"文件浏览"**进入文件管理器
2. 点击文件夹可进入子目录
3. 点击图片/视频可预览
4. 长按文件显示操作菜单：
   - 复制链接
   - 下载
   - 删除
5. 点击右下角 ➕ 按钮新建文件夹

### 相册同步

1. 点击**"相册同步"**进入同步页面
2. 顶部选择相册（默认显示全部）
3. 点击照片进行多选
4. 选择完成后点击**"上传"**按钮
5. 输入目标文件夹路径（如 `photos/2024/`）
6. 系统会自动检测已存在的文件
7. 确认后开始上传，可查看进度

## 📁 项目结构

```
app/src/main/java/com/bonsai/ossmanager/
├── OSSApplication.kt              # Application 入口
├── OSSConfig.kt                   # OSS 配置管理
├── model/                         # 数据模型
│   ├── OSSObject.kt              # OSS 对象模型
│   ├── LocalMedia.kt             # 本地媒体文件模型
│   └── FileType.kt               # 文件类型枚举
├── manager/                       # 业务管理器
│   ├── OSSManager.kt             # OSS 操作管理
│   └── AlbumManager.kt           # 相册管理
├── ui/                           # 界面
│   ├── MainActivity.kt           # 主界面
│   ├── OSSBrowserActivity.kt    # 文件浏览
│   ├── AlbumSyncActivity.kt     # 相册同步
│   ├── ImagePreviewActivity.kt   # 图片预览
│   └── VideoPreviewActivity.kt   # 视频预览
├── adapter/                      # 列表适配器
│   ├── OSSObjectAdapter.kt      # OSS 对象列表
│   ├── LocalMediaAdapter.kt     # 本地媒体列表
│   └── AlbumAdapter.kt          # 相册列表
└── service/                      # 后台服务
    └── UploadService.kt         # 上传服务
```

## 🔒 安全说明

- **敏感信息**: Access Key 等信息本地加密存储
- **HTTPS**: 所有网络请求使用 HTTPS
- **权限控制**: 最小化权限申请
- **个人使用**: 建议仅个人使用，不要分享 Access Key

## ⚠️ 注意事项

1. **网络流量**: 上传/下载会消耗流量，建议 WiFi 环境使用
2. **存储空间**: 下载文件会占用本地存储
3. **OSS 费用**: 使用阿里云 OSS 会产生存储和流量费用
4. **文件覆盖**: 上传同名文件会覆盖原文件
5. **删除操作**: 删除文件/文件夹不可恢复，请谨慎操作

## 🛠️ 开发环境

- Android Studio Hedgehog | 2023.1.1+
- Gradle 8.2+
- Kotlin 1.9.20
- Min SDK 24 (Android 7.0)
- Target SDK 34 (Android 14)

## 📝 更新日志

### v1.0.0 (2024-07-24)
- ✨ 初始版本发布
- ✨ 支持 OSS 文件浏览
- ✨ 支持图片/视频预览
- ✨ 支持相册批量上传
- ✨ 支持文件操作（复制链接、删除）
- ✨ Material Design 3 界面
- ✨ 智能检测重复文件

## 🤝 参考项目

本项目参考了 [oss-browser](https://github.com/aliyun/oss-browser) 的部分设计理念。

## 📄 License

个人使用项目，禁止商业用途。

## 👨‍💻 作者

- **开发者**: 汉源魂
- **联系方式**: - 
- **项目地址**: -

---

**免责声明**: 本应用为个人学习项目，使用者需自行承担使用风险。开发者不对因使用本应用造成的任何损失负责。