@xuanqikai/one-click-upload/README.md

A CLI tool for one-click file upload to cloud storage services (OSS, TOS)

# One-Click Upload

一个强大的命令行工具，用于一键上传文件和文件夹到云存储服务（阿里云 OSS、字节跳动 TOS）。

## 特性

- 🚀 **一键上传** - 简单的命令即可上传文件或整个文件夹
- 🔧 **多服务支持** - 支持阿里云 OSS 和字节跳动 TOS（火山引擎）
- 📊 **进度显示** - 实时显示上传进度和速度
- 🔄 **断点续传** - 支持大文件的断点续传功能
- 🔁 **自动重试** - 网络异常时自动重试上传
- ⚙️ **配置管理** - 支持多个服务配置，轻松切换
- 📱 **交互式界面** - 友好的命令行交互体验
- 🎯 **批量上传** - 支持文件夹批量上传
- 📝 **详细日志** - 完整的上传日志记录

## 安装

### 全局安装

```bash
npm i -g @xuanqikai/one-click-upload
```

### 本地开发

```bash
git clone <repository-url>
cd one-click-upload
npm install
npm run build
npm link
```

## 快速开始

### 1. 添加服务配置

首次使用需要添加云存储服务配置：

```bash
# 交互式添加配置
one-upload config add

# 或使用简短命令
ou config add
```

支持的服务类型：
- **阿里云 OSS** - 需要提供 region、accessKeyId、accessKeySecret、bucket
- **字节跳动 TOS** - 需要提供 region、accessKeyId、accessKeySecret、bucket

### 2. 查看和管理配置

```bash
# 列出所有配置
one-upload config list

# 显示配置详情
one-upload config show <service-name>

# 测试配置是否有效
one-upload config test <service-name>

# 设置默认服务
one-upload config default <service-name>
```

### 3. 上传文件和文件夹

#### 基本上传方式

```bash
# 交互式上传（推荐新手使用）
one-upload

# 直接上传文件到指定目录（保持原文件名）
one-upload photo.jpg images/
# 结果：images/photo.jpg

# 上传文件到多级目录
one-upload document.pdf docs/2024/reports/
# 结果：docs/2024/reports/document.pdf

# 上传整个文件夹（保持完整目录结构）
one-upload ./my-project projects/
# 结果：projects/src/index.js, projects/package.json 等
```

#### 高级上传选项

```bash
# 使用指定服务
one-upload file.txt remote/path/ --service my-oss

# 覆盖已存在的文件
one-upload file.txt remote/path/ --overwrite

# 禁用断点续传
one-upload large-file.zip remote/ --no-resume

# 设置重试次数和分片大小
one-upload file.txt remote/ --max-retries 5 --chunk-size 5
```

## 命令详解

### 配置管理

```bash
# 添加新的服务配置
one-upload config add

# 列出所有配置
one-upload config list

# 显示配置详情
one-upload config show <service-name>

# 更新配置
one-upload config update <service-name>

# 删除配置
one-upload config remove <service-name>

# 设置默认服务
one-upload config default <service-name>

# 测试配置
one-upload config test <service-name>
```

### 上传命令

```bash
# 基本上传
one-upload <local-path> [remote-path] [options]

# 上传选项
--service, -s <name>     指定使用的服务名称
--overwrite, -o          覆盖已存在的文件
--resume, -r             启用断点续传（默认开启）
--max-retries <number>   最大重试次数（默认3次）
--chunk-size <size>      分片大小，单位MB（默认1MB）
--contents-only          只上传文件夹内容（不包含文件夹名）
--cache-control <value>  自定义缓存控制头（如 "no-cache"）
```

## 配置示例

### 阿里云 OSS 配置

```json
{
  "name": "my-oss",
  "type": "oss",
  "config": {
    "region": "oss-cn-hangzhou",
    "accessKeyId": "your-access-key-id",
    "accessKeySecret": "your-access-key-secret",
    "bucket": "your-bucket-name",
    "endpoint": "https://oss-cn-hangzhou.aliyuncs.com"
  },
  "isDefault": true
}
```

### 字节跳动 TOS 配置

```json
{
  "name": "my-tos",
  "type": "tos",
  "config": {
    "region": "cn-beijing",
    "accessKeyId": "your-access-key-id",
    "accessKeySecret": "your-access-key-secret",
    "bucket": "your-bucket-name",
    "endpoint": "https://tos-cn-beijing.volces.com"
  },
  "isDefault": false
}
```

## 详细使用指南

### 文件上传示例

#### 1. 上传单个文件

```bash
# 上传图片到 images 目录
one-upload photo.jpg images/
# 远程路径：images/photo.jpg

# 上传文档到指定子目录
one-upload report.pdf documents/2024/
# 远程路径：documents/2024/report.pdf

# 上传视频文件
one-upload movie.mp4 videos/movies/
# 远程路径：videos/movies/movie.mp4
```

#### 2. 上传文件夹（两种模式）

**模式1：上传整个文件夹（包含文件夹名）**
```bash
# 不带尾部斜杠 - 上传整个文件夹
one-upload my-website websites/
# 结果：
# websites/my-website/index.html
# websites/my-website/css/style.css
# websites/my-website/js/app.js
# websites/my-website/images/logo.png
```

**模式2：只上传文件夹内容（不包含文件夹名）**
```bash
# 带尾部斜杠 - 只上传文件夹内容
one-upload my-website/ websites/
# 结果：
# websites/index.html
# websites/css/style.css
# websites/js/app.js
# websites/images/logo.png
```

**实际应用示例**
```bash
# 上传项目到指定目录（保持项目名）
one-upload my-project backup/
# 结果：backup/my-project/...

# 直接部署网站内容（不要项目文件夹名）
one-upload dist/ websites/production/
# 结果：websites/production/index.html, websites/production/assets/...
```

#### 3. 智能缓存策略

工具会根据文件类型自动设置合适的缓存策略：

```bash
# 自动缓存策略
one-upload website/ production/
# 结果：
# index.html -> no-cache (不缓存，便于更新)
# *.html -> max-age=3600 (1小时缓存)
# *.js, *.css -> max-age=31536000 (1年缓存)
# 图片文件 -> max-age=31536000 (1年缓存)

# 自定义缓存策略
one-upload index.html production/ --cache-control "max-age=3600"
one-upload assets/ cdn/ --cache-control "max-age=86400"
```

#### 4. 批量上传不同类型文件

```bash
# 上传多媒体文件夹
one-upload ./media-files storage/
# 自动处理：
# storage/images/photo1.jpg
# storage/videos/clip1.mp4
# storage/documents/readme.txt
# storage/audio/music.mp3
```

### 实际使用场景

#### 1. 网站部署

```bash
# 构建并上传网站
npm run build
one-upload dist/ websites/my-site/ --overwrite
# 结果：网站文件上传到 websites/my-site/ 目录
```

#### 2. 备份文件

```bash
# 备份重要文档
one-upload ./important-docs backups/$(date +%Y%m%d)/
# 结果：backups/20240716/contract.pdf, backups/20240716/report.docx

# 备份代码项目
one-upload ./my-project backups/projects/my-project-$(date +%Y%m%d)/
```

#### 3. 内容管理

```bash
# 上传用户头像
one-upload avatar.jpg users/avatars/
# 结果：users/avatars/avatar.jpg

# 上传产品图片
one-upload product-images/ catalog/products/
# 结果：catalog/products/product1.jpg, catalog/products/product2.jpg

# 上传博客图片
one-upload blog-images/ blog/2024/07/
# 结果：blog/2024/07/image1.png, blog/2024/07/image2.jpg
```

#### 4. 开发工具集成

```bash
# CI/CD 脚本示例
#!/bin/bash
echo "构建项目..."
npm run build

echo "上传到 CDN..."
one-upload dist/ cdn/releases/v$(cat package.json | grep version | cut -d'"' -f4)/ --overwrite

echo "上传静态资源..."
one-upload assets/ static/assets/ --service cdn-oss

echo "部署完成！"
```

## 高级功能

### 断点续传

对于大文件（>1MB），工具会自动启用分片上传和断点续传：

```bash
# 启用断点续传（默认）
one-upload large-file.zip remote/large-file.zip --resume

# 禁用断点续传
one-upload large-file.zip remote/large-file.zip --no-resume
```

### 批量上传优化

```bash
# 调整分片大小以优化上传速度
one-upload folder/ remote/folder/ --chunk-size 5

# 增加重试次数以提高成功率
one-upload folder/ remote/folder/ --max-retries 5
```

## 最佳实践

### 1. 目录命名规范

```bash
# 推荐的目录结构
images/                 # 图片文件
  ├── avatars/         # 用户头像
  ├── products/        # 产品图片
  └── banners/         # 横幅图片

documents/             # 文档文件
  ├── contracts/       # 合同文件
  ├── reports/         # 报告文件
  └── manuals/         # 手册文件

backups/               # 备份文件
  ├── 2024/           # 按年份分类
  │   ├── 01/         # 按月份分类
  │   └── 02/
  └── projects/        # 项目备份
```

### 2. 文件上传策略

```bash
# 小文件直接上传
one-upload small-file.txt documents/

# 大文件启用断点续传
one-upload large-video.mp4 videos/ --resume --chunk-size 10

# 批量文件使用文件夹上传
one-upload ./photo-album gallery/2024/vacation/
```

### 3. 安全建议

- 定期轮换 AccessKey
- 使用最小权限原则配置 IAM 策略
- 不要在公共代码仓库中暴露配置信息
- 定期备份重要配置

## 故障排除

### 常见问题及解决方案

#### 1. 配置相关问题

```bash
# 问题：配置验证失败
# 解决：测试配置是否正确
one-upload config test <service-name>

# 问题：找不到默认服务
# 解决：设置默认服务
one-upload config default <service-name>

# 问题：配置文件损坏
# 解决：重新添加配置
rm ~/.one-upload-config.json
one-upload config add
```

#### 2. 上传相关问题

```bash
# 问题：上传失败
# 解决：增加重试次数
one-upload file.txt remote/ --max-retries 5

# 问题：大文件上传中断
# 解决：启用断点续传
one-upload large-file.zip remote/ --resume

# 问题：网络不稳定
# 解决：减小分片大小
one-upload file.txt remote/ --chunk-size 1
```

#### 3. 权限相关问题

- **AccessKey 权限不足**：确保 AccessKey 有对应 bucket 的写权限
- **Bucket 不存在**：检查 bucket 名称是否正确
- **Region 不匹配**：验证 region 设置是否与 bucket 所在区域匹配
- **网络访问限制**：检查防火墙和网络策略

### 调试和日志

```bash
# 查看配置文件
cat ~/.one-upload-config.json

# 查看上传历史日志
tail -f ~/.one-upload-history.log

# 清除配置重新开始
rm ~/.one-upload-config.json
rm ~/.one-upload-history.log
```

## 快速参考

### 命令速查表

#### 配置管理
```bash
one-upload config add                    # 添加新配置
one-upload config list                   # 列出所有配置
one-upload config show <name>            # 显示配置详情
one-upload config test <name>            # 测试配置
one-upload config default <name>         # 设置默认服务
one-upload config remove <name>          # 删除配置
```

#### 文件上传
```bash
one-upload                              # 交互式上传
one-upload <local> <remote>             # 直接上传
one-upload <local> <remote> -s <name>   # 指定服务上传
one-upload <local> <remote> --overwrite # 覆盖上传
one-upload <local> <remote> --resume    # 断点续传
```

#### 常用选项
```bash
-s, --service <name>        # 指定服务名称
-o, --overwrite            # 覆盖已存在文件
-r, --resume               # 启用断点续传
--max-retries <number>     # 最大重试次数
--chunk-size <size>        # 分片大小(MB)
--help                     # 显示帮助
--version                  # 显示版本
```

### 典型使用模式

```bash
# 1. 首次使用
one-upload config add
one-upload config test <service-name>

# 2. 日常上传
one-upload photo.jpg images/
one-upload my-project backup/          # 上传整个文件夹
one-upload my-project/ backup/         # 只上传文件夹内容

# 3. 批量部署
one-upload dist/ websites/production/ --overwrite  # 部署网站内容

# 4. 大文件上传
one-upload large-file.zip backups/ --resume --chunk-size 10
```

## 开发

### 本地开发

```bash
# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建
npm run build

# 运行测试
npm test

# 代码检查
npm run lint
```

### 项目结构

```
src/
├── commands/          # CLI 命令实现
├── config/           # 配置管理
├── uploaders/        # 上传器实现
├── utils/            # 工具函数
├── types/            # 类型定义
└── __tests__/        # 测试文件
```

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License

## 更新日志

## 完整使用示例

### 从零开始的完整流程

```bash
# 1. 全局安装
npm install -g one-click-upload

# 2. 添加 OSS 配置
one-upload config add
# 选择服务类型：Alibaba Cloud OSS
# 输入服务名称：my-oss
# 输入 Region：oss-cn-beijing
# 输入 Access Key ID：your-access-key-id
# 输入 Access Key Secret：your-access-key-secret
# 输入 Bucket Name：your-bucket-name
# 设为默认服务：Yes

# 3. 测试配置
one-upload config test my-oss
# ✓ Service 'my-oss' configuration is valid

# 4. 上传单个文件
one-upload photo.jpg images/
# ✓ Upload completed successfully
# File: photo.jpg
# Size: 2.5 MB
# URL: https://your-bucket.oss-cn-beijing.aliyuncs.com/images/photo.jpg

# 5. 上传文件夹
one-upload ./my-project projects/
# Upload Summary:
# ────────────────────────────────────────
# Total files: 15
# Successful: 15 (100.0%)
# Failed: 0
# Total size: 45.2 MB
# Duration: 12s

# 6. 查看所有配置
one-upload config list
# Configured Services:
# ────────────────────────────────────────────────────────────
# my-oss (default)
#   Type: Alibaba Cloud OSS
#   Bucket: your-bucket-name
#   Region: oss-cn-beijing
```

### 高级使用示例

```bash
# 添加 TOS 配置
one-upload config add
# 选择：ByteDance TOS (Volcano Engine)

# 使用特定服务上传
one-upload backup.zip backups/ --service my-tos

# 大文件上传（启用断点续传）
one-upload large-video.mp4 videos/ --resume --chunk-size 10

# 批量上传并覆盖
one-upload dist/ websites/production/ --overwrite --max-retries 3
```

## 更新日志
### v1.0.3
- 🌐 Tos 上传bug
  - Cache-Control 不存在则不填写
### v1.0.2
- 🎯 新增两种文件夹上传模式
  - `one-upload folder backup/` - 上传整个文件夹（包含文件夹名）
  - `one-upload folder/ backup/` - 只上传文件夹内容（不包含文件夹名）
- 🌐 修复 Windows 路径兼容性问题
  - 统一使用正斜杠作为远程路径分隔符
  - 确保多级子目录在 Windows 上正确创建
- 🚀 智能缓存策略
  - `index.html` 自动设置为不缓存（`no-cache`）
  - HTML 文件缓存1小时，JS/CSS/图片文件缓存1年
  - 支持 `--cache-control` 选项自定义缓存策略

### v1.0.1
- 🐛 修复文件存在性检查逻辑
- 🐛 修复 `--overwrite` 选项解析问题
- 📝 完善文档和使用示例

### v1.0.0
- 初始版本发布
- 支持阿里云 OSS 和字节跳动 TOS
- 实现断点续传和进度显示p;
- 完整的配置管理系统
- 支持文件和文件夹上传
- 保持原始文件名和目录结构