# AWSPush

**Repository Path**: bogegit/AWSPush

## Basic Information

- **Project Name**: AWSPush
- **Description**: aws push工具
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2020-09-23
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AWSPush - AWS S3 专业文件上传与管理工具

## 概述

AWSPush 是一个基于 Kotlin 开发的命令行工具，用于简化 AWS S3 存储桶的文件上传、桶创建、权限设置和缓存清理等操作。

## 开发文档

- [Amazon CloudFront 文档](https://docs.aws.amazon.com/zh_cn/AmazonCloudFront/latest/DeveloperGuide/example_cloudfront_CreateDistribution_section.html)
- [AWS SDK for Kotlin 开发指南](https://docs.aws.amazon.com/zh_cn/sdk-for-kotlin/latest/developer-guide/home.html)
- [AWS SDK for Java HTTP 配置](https://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/http-configuration-apache.html)
- [S3 PutObject 示例](https://docs.aws.amazon.com/zh_cn/code-library/latest/ug/s3_example_s3_PutObject_section.html)

## 功能特性

- **多云存储适配（Cloudflare R2）**：默认 S3 登录行为与 Cloudflare R2 全面同步，提供无缝的多云存储平台切换。
- **文件上传**：高并发批量上传文件到 S3/R2 存储桶，支持大文件及断点续传。
- **S3 存储桶管理**：自动化创建、删除、配置存储桶。
- **权限设置**：一键设置存储桶中对象的公共读取（Public Read）权限。
- **CloudFront 集成**：便捷创建 CloudFront 边缘分发，并支持全自动一键清除 CDN 缓存。
- **文件删除**：高性能批量从 S3/R2 存储桶中删除文件。
- **智能代理支持**：支持通过 `proxy.conf` 代理连接 AWS/R2 服务，支持高级行级注释过滤（如 `#` 开头的配置项将被智能忽略）。

## 系统要求

- Java 8 或更高版本
- AWS 账户及访问密钥
- AWS CLI 配置（可选）

## 认证配置

### 方式一：使用 AWS 配置文件

```bash
# 在 ~/.aws/credentials 文件中配置
[profile_name]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY
```

### 方式二：配置文件认证

在 JAR 文件同目录下创建 `.aws_user` 文件，包含以下内容：

```
aws_id=your_access_key_id
aws_psd=your_secret_access_key
```

### 方式三：命令行参数

直接在命令中提供访问密钥和密钥。

## Cloudflare R2 配置与多云兼容

AWSPush 采用 S3 标准协议无缝兼容 Cloudflare R2 对象存储，实现了默认 S3 登录行为与 R2 的同步与高度适配。连接 R2 时仅需额外指定自定义的端点（Endpoint）和 API 凭证。

### 1. 配置参数

连接 Cloudflare R2 所需的核心参数：
- **`id` / `accessKeyId`**：Cloudflare R2 的客户端访问密钥 ID（Access Key ID）。
- **`psd` / `accessKeySecret`**：Cloudflare R2 的客户端机密访问密钥（Secret Access Key）。
- **`-ep` / `endpointUrl`**：您的 Cloudflare R2 专属服务访问端点，格式一般为：`https://<your-account-id>.r2.cloudflarestorage.com`。
- **`-reg` / `region`**：推荐指定为 `auto`（或不传，则默认会使用兼容区域配置）。

### 2. 使用示例

#### 命令行直连 R2 并上传文件：
```bash
java -jar awspush.jar -t 1 id=your_r2_access_key_id psd=your_r2_secret_access_key -ep https://<your-account-id>.r2.cloudflarestorage.com -bname my-r2-bucket -add /path/to/file.txt
```

#### 使用配置文件运行 R2 传输：
您可以将所有 R2 参数整合至配置文件（如 `r2_upload.txt`）中，便于一键调用：
```text
-t 1 id=your_r2_access_key_id psd=your_r2_secret_access_key -ep https://<your-account-id>.r2.cloudflarestorage.com -bname my-r2-bucket -add /path/to/file.txt
```
执行配置：
```bash
java -jar awspush.jar -r r2_upload.txt
```

## 快速开始

### 基本用法

```bash
# 上传文件到 S3
java -jar awspush.jar -t 1 -n profile_name -bname bucket_name -add file1.txt,file2.txt

# 创建 S3 存储桶
java -jar awspush.jar -t 2 -n profile_name -bname new_bucket_name

# 设置存储桶权限
java -jar awspush.jar -t 3 -n profile_name -bname bucket_name

# 清理 CloudFront 缓存
java -jar awspush.jar -cls -n profile_name -bname bucket_name
```

### 使用别名 `aws`

```bash
# 上传文件到 S3
aws -t 1 bname my-bucket add file1.txt,file2.txt
# 删除 S3 文件
aws -t 1 bname my-bucket rm key1,key2
# 设置存储桶权限
aws -t 3 bname my-bucket
# 使用配置文件
aws -r upload_config.txt
```

## 命令行参数

### 主要参数

| 参数                                                                                                           | 别名 | 说明                       |
|--------------------------------------------------------------------------------------------------------------|----|--------------------------|
| `-help`                                                                                                      |    | 显示帮助信息并退出                |
| `-cls` `-clear`                                                                                              |    | 清理 CloudFront 缓存         |
| `-t` `-type`                                                                                                 |    | 操作类型：1-上传文件，2-创建桶，3-设置权限 |
| `-n` `-name`                                                                                                 |    | AWS 配置文件中的 profile 名称    |
| `id` [accessKeyId](file://D:\WorkSpace\Idea\Java\AWSPush\src\main\kotlin\com\entity\PackCmd.kt#L41-L43)      |    | AWS 访问密钥 ID              |
| `psd` [accessKeySecret](file://D:\WorkSpace\Idea\Java\AWSPush\src\main\kotlin\com\entity\PackCmd.kt#L46-L48) |    | AWS 访问密钥密码               |
| `bname` [bucketName](file://D:\WorkSpace\Idea\Java\AWSPush\src\main\kotlin\com\entity\PackCmd.kt#L51-L53)    |    | S3 存储桶名称                 |
| `rp` [rootPath](file://D:\WorkSpace\Idea\Java\AWSPush\src\main\kotlin\com\entity\PackCmd.kt#L56-L58)         |    | 上传到服务器的根路径               |
| `p` `parent`                                                                                                 |    | 本地文件缓存父路径                |
| `-ep` [endpointUrl](file://D:\WorkSpace\Idea\Java\AWSPush\src\main\kotlin\com\entity\PackCmd.kt#L51-L54)     |    | 自定义 S3/R2 服务端点 URL（对接多云存储，如 R2）|
| `-reg` [region](file://D:\WorkSpace\Idea\Java\AWSPush\src\main\kotlin\com\entity\PackCmd.kt#L56-L59)         |    | 服务区域（默认：`eu-central-1`，对接 R2 时通常设为 `auto`）|


### 文件操作参数

| 参数                                                                                                           | 别名               | 说明 |
|--------------------------------------------------------------------------------------------------------------|------------------|----|
| `-r` `-read`                                                                                                 | 上传文件配置表          |
| `-p` `-pack`                                                                                                 | 需要打包到指定目录的文件     |
| `add` `addFile`                                                                                              | 要上传的文件列表（逗号分隔）   |
| `rm` `deleteFile`                                                                                            | 要删除的文件列表（逗号分隔）   |
| `dbId` [distributionId](file://D:\WorkSpace\Idea\Java\AWSPush\src\main\kotlin\com\entity\PackCmd.kt#L94-L99) | CloudFront 分发 ID |

## 使用示例

### 上传文件

```bash
# 上传单个文件
java -jar awspush.jar -t 1 -n myprofile -bname mybucket -add /path/to/file.txt

# 上传多个文件
java -jar awspush.jar -t 1 -n myprofile -bname mybucket -add /path/to/file1.txt,/path/to/file2.txt

# 上传并设置根路径
java -jar awspush.jar -t 1 -n myprofile -bname mybucket -rp /public -add /path/to/files/*
```

### 删除文件

```bash
# 删除 S3 中的文件
java -jar awspush.jar -n myprofile -bname mybucket -rm file1.txt,file2.txt
```

### 创建存储桶

```bash
# 创建新的 S3 存储桶
java -jar awspush.jar -t 2 -n myprofile -bname newbucketname
```

### 设置权限

```bash
# 设置存储桶中所有对象为公共可读
java -jar awspush.jar -t 3 -n myprofile -bname mybucket
```

### 清理缓存

```bash
# 清理 CloudFront 缓存
java -jar awspush.jar -cls -n myprofile -bname mybucket

# 指定分发 ID 清理缓存
java -jar awspush.jar -cls -n myprofile -dbId E1234567890
```

## 配置文件

### 上传文件配置表

可以创建一个配置文件，包含所有上传参数：

```
-t 1 -n myprofile -bname mybucket -add /path/to/file1.txt,/path/to/file2.txt
```

使用配置文件：

```bash
java -jar awspush.jar -r /path/to/config.txt
```

## 代理配置

如果需要通过代理连接 AWS 或 Cloudflare R2 服务，可以在运行同级目录创建 [proxy.conf](proxy.conf) 配置文件。其解析器已支持**行级注释过滤**，凡是以 `#` 开头的配置行和空行都会被智能忽略：

```properties
# 这是一个有效的代理配置示例（# 开头的行会被忽略）
proxyHost=your.proxy.host

# 代理服务器端口
proxyPort=8080
```

## 依赖库

- AWS SDK for Kotlin
- Picocli (命令行解析)
- Log4j 2 (日志记录)
- Jackson (YAML 配置解析)

## 技术栈

- **Kotlin**: 主要开发语言
- **AWS SDK for Kotlin**: AWS 服务接口
- **Picocli**: 命令行界面
- **Log4j2**: 日志记录
- **Coroutines**: 异步处理和并发上传

## 开发

### 项目结构

```
src/main/kotlin/com/
├── entity/           # 数据类
├── handler/          # 业务逻辑处理器
├── interfaces/       # 接口定义
├── log4j/            # 日志配置
├── s3/transfer/      # S3 传输相关
├── AwsUtils.kt       # AWS 工具类
├── Config.kt         # 配置类
├── ConsoleProgressBar.kt  # 控制台进度条
├── Main.kt           # 主程序入口
├── Mimetypes.kt      # MIME 类型处理
├── TypeConverter.kt  # 类型转换器
└── VerificationUtils.kt  # 验证工具类
```

## 错误处理

- 工具会在出现错误时输出错误信息到控制台
- 日志信息会记录到日志文件中
- 上传失败时会显示失败的文件数量

## 许可证

请参阅项目中的许可证文件。