One-Click Upload

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

特性

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

安装

全局安装

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

本地开发

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

快速开始

1. 添加服务配置

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

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

# 或使用简短命令
ou config add

支持的服务类型：

• 阿里云 OSS - 需要提供 region、accessKeyId、accessKeySecret、bucket
  • 可选：CDN 自动刷新功能（需要 CDN AccessKey 和域名）
• 字节跳动 TOS - 需要提供 region、accessKeyId、accessKeySecret、bucket
  • 可选：CDN 自动刷新功能（需要 CDN AccessKey 和域名）

2. CDN 自动刷新配置（可选）

如果使用阿里云 OSS 或字节跳动 TOS，可以配置 CDN 自动刷新功能：

# 在配置 OSS 或 TOS 服务时，会询问是否启用 CDN 自动刷新
one-upload config add

# 配置流程：
# 1. 选择服务类型：OSS 或 TOS
# 2. 输入基本配置：region、accessKeyId、accessKeySecret、bucket
# 3. 询问：Enable CDN auto refresh after upload for OSS/TOS? (y/n)
# 4. 如果选择 y，需要输入：
#    - CDN Access Key ID
#    - CDN Access Key Secret  
#    - CDN Domain (如：https://cdn.example.com)

CDN 功能说明：

• 🚀 文件上传成功后自动刷新 CDN 缓存
• 📱 用户通过 CDN 访问到的文件始终是最新版本
• ⚙️ 可选功能，不影响基本上传功能
• 🔧 需要对应云服务商的 CDN API 权限
• 🌍 支持 OSS（阿里云）和 TOS（字节跳动）两种服务

3. 查看和管理配置

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

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

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

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

4. 上传文件和文件夹

基本上传方式

# 交互式上传（推荐新手使用）
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 等

高级上传选项

# 使用指定服务
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

命令详解

配置管理

# 添加新的服务配置
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>

上传命令

# 基本上传
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"）
--preload                上传完成后自动预热 CDN 缓存
--preload-options <json> 预热选项（JSON 格式）

配置示例

阿里云 OSS 配置

{
  "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 配置

{
  "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",
    "cdn": {
      "accessKeyId": "your-cdn-access-key-id",
      "accessKeySecret": "your-cdn-access-key-secret",
      "cdnDomain": "https://cdn.example.com",
      "autoRefresh": true
    }
  },
  "isDefault": false
}

CDN 预热功能

功能说明

--preload 选项允许您在上传文件完成后自动预热 CDN 缓存，确保文件能够快速访问。

配置要求

要使用 CDN 预热功能，您需要在服务配置中添加 cdn 配置项：

{
  "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",
    "cdn": {
      "accessKeyId": "your-cdn-access-key-id",
      "accessKeySecret": "your-cdn-access-key-secret",
      "region": "cn-north-1"
    }
  }
}

使用方法

# 上传文件并预热 CDN
one-upload photo.jpg images/ --preload

# 上传文件夹并预热 CDN
one-upload my-website/ websites/ --preload

# 使用自定义预热选项
one-upload photo.jpg images/ --preload --preload-options '{"area":"domestic"}'

预热选项

• area: 预热区域，支持 domestic（国内）和 overseas（海外）
• l2Preload: 是否启用二级预热
• withHeader: 自定义请求头
• queryHashkey: 是否查询哈希键
• consistencyHash: 是否启用一致性哈希

详细使用指南

文件上传示例

1. 上传单个文件

# 上传图片到 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：上传整个文件夹（包含文件夹名）

# 不带尾部斜杠 - 上传整个文件夹
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：只上传文件夹内容（不包含文件夹名）

# 带尾部斜杠 - 只上传文件夹内容
one-upload my-website/ websites/
# 结果：
# websites/index.html
# websites/css/style.css
# websites/js/app.js
# websites/images/logo.png

实际应用示例

# 上传项目到指定目录（保持项目名）
one-upload my-project backup/
# 结果：backup/my-project/...

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

3. 智能缓存策略

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

# 自动缓存策略
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. 批量上传不同类型文件

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

5. CDN 预热功能

基本预热

# 上传文件并自动预热 CDN 缓存
one-upload index.html / --preload

# 上传目录并预热所有文件
one-upload dist/ /website/ --preload

# 覆盖上传并预热
one-upload new-image.jpg /images/ --overwrite --preload

高级预热选项

# 预热到 L2 节点，仅中国内地
one-upload index.html / --preload --preload-options '{"l2Preload":true,"area":"domestic"}'

# 预热到全球，包含自定义头部
one-upload app.js /js/ --preload --preload-options '{"area":"overseas","withHeader":{"Accept-Encoding":["gzip, deflate, br"]}}'

# 开启 HASH 预热（仅中国大陆有效）
one-upload large-file.zip /files/ --preload --preload-options '{"l2Preload":true,"consistencyHash":true}'

预热工作流程

文件上传 → CDN 缓存刷新 → 自动预热 → 用户访问命中缓存

预热选项说明

• area: 预热区域（domestic 中国内地，overseas 全球）
• l2Preload: 是否预热到 L2 节点（true 推荐重要文件，false 普通文件）
• withHeader: 自定义预热请求头部
• queryHashkey: 是否开启 hashkey 查询模式
• consistencyHash: 是否开启 HASH 预热（仅中国大陆有效）

实际使用场景

1. 网站部署

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

2. 备份文件

# 备份重要文档
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. 内容管理

# 上传用户头像
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. 开发工具集成

# 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），工具会自动启用分片上传和断点续传：

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

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

批量上传优化

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

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

最佳实践

1. 目录命名规范

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

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

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

2. 文件上传策略

# 小文件直接上传
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. 配置相关问题

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

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

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

2. 上传相关问题

# 问题：上传失败
# 解决：增加重试次数
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 所在区域匹配
• 网络访问限制：检查防火墙和网络策略

调试和日志

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

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

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

快速参考

命令速查表

配置管理

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>          # 删除配置

文件上传

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

常用选项

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

典型使用模式

# 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

开发

本地开发

# 安装依赖
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

更新日志

完整使用示例

从零开始的完整流程

# 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

高级使用示例

# 添加 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;
• 完整的配置管理系统
• 支持文件和文件夹上传
• 保持原始文件名和目录结构