# Giới thiệu Công cụ

## Tổng quan

US3SYNC là một công cụ di chuyển dữ liệu đồng bộ hóa dữ liệu từ nhiều nguồn khác nhau sang S3. Bằng cách triển khai US3SYNC trên các thiết bị cục bộ hoặc máy chủ đám mây, bạn có thể dễ dàng di chuyển dữ liệu từ môi trường cục bộ hoặc các môi trường đám mây khác sang không gian lưu trữ S3. Công cụ US3SYNC có thể tạo các tác vụ ở hai chế độ:

- **Normal Mode (Chế độ Thường):** Tác vụ đồng bộ hóa thông thường có thể đồng bộ hóa hàng loạt các tệp với tiền tố được chỉ định hoặc từ một thư mục được chỉ định ở phía nguồn sang S3.
- **Fetch Mode (Chế độ Lấy dữ liệu):** Tác vụ đồng bộ hóa ở chế độ fetch đồng bộ hóa các tệp đến một vị trí được chỉ định thông qua yêu cầu POST (mô tả URL của tệp cần đồng bộ hóa và vị trí đích). Bạn có thể chỉ định các giao diện callback cho việc đồng bộ hóa tệp thành công và thất bại, và US3SYNC sẽ gửi các thông báo tương ứng sau khi tác vụ đồng bộ hóa hoàn thành.

### Nguyên lý Hoạt động của Tác vụ Thông thường

Trong chế độ thông thường, quy trình làm việc được chia thành một **master node (nút chính)** và các **worker nodes (nút hoạt động)**:

- **Master Node (Nút chính):**
> Được triển khai dưới dạng một phiên bản duy nhất (single instance), quản lý các tác vụ di chuyển dữ liệu. Nhiệm vụ chính của nó là lấy danh sách tệp từ nguồn và phân phối các tác vụ đến các worker node để thực hiện di chuyển.

- **Worker Nodes (Nút hoạt động):**
> Đây là các nút có thể mở rộng chịu trách nhiệm di chuyển tệp. Chúng tải xuống các tệp từ nguồn và tải chúng lên đích.

Các nút master và worker có thể được triển khai trên cùng một máy hoặc trên nhiều máy khác nhau. Người dùng có thể mở rộng số lượng worker node khi cần thiết. Chi tiết triển khai:

- **Triển khai trên Cùng một Máy:**
> Các nút master và worker giao tiếp thông qua một **địa chỉ giao tiếp** được cấu hình nội bộ. Hãy đảm bảo đường dẫn được cấu hình cho các worker node là duy nhất và không bị trùng lặp với master node hoặc các worker node khác.

- **Triển khai trên các Máy khác nhau:**
> Các nút master và worker giao tiếp thông qua một **địa chỉ giao tiếp** được cấu hình có thể truy cập được từ máy worker. Hãy đảm bảo đường dẫn được cấu hình cho mỗi worker node là duy nhất và không trùng lặp.

### Nguyên lý Hoạt động của Tác vụ Fetch

Các tác vụ fetch hoạt động tương tự như các tác vụ thông thường, ngoại trừ việc nguồn đồng bộ hóa được chỉ định thông qua một **yêu cầu POST**, thay vì được tự động lấy từ một nguồn đã được cấu hình trước.

#### Cú pháp Yêu cầu POST

```HTTP
POST /fetch/ HTTP 1.1
Authorization: Auth
Content-Type: application/json
```

##### Header Yêu cầu

- **Authorization**: Bắt buộc
- Các header khác như `content-type` và `date` là không bắt buộc.

Ví dụ:
`Authorization: VNPT Cloud xxxx-xxxx-xxxx-xxxx-xxxx:xxxxxxxxxxxxx`
Mã giả để tạo `Authorization`:

```go
method := "POST"
md5 := xxxxxx
contentType := xxxxxx
date := xxxxx
privateKey = xxxxx-xxxx-xxxxx-xxxx
publicKey = xxxx-xxxx-xxxx-xxxx
strToSign = method + "\n" + md5 + "\n" + contentType + "\n" + date + "\n"
signature = HmacSHA1(strToSign, privateKey)
signature = Base64(signature)
Authorization: "VNPT Cloud " + publicKey + ":" + signature
```

##### Body Yêu cầu

| Tên | Mô tả | Kiểu dữ liệu | Bắt buộc |
| ------------------- | ------------------------------------ | ------ | -------- |
| **Url**             | URL của tệp nguồn (phải được mã hóa) | String | Có      |
| **Key**             | Đường dẫn đích trong bucket | String | Có      |
| **Bucket**          | Tên bucket đích | String | Có      |
| **JobId**           | ID của tác vụ fetch | String | Có      |
| **SuccessCallbackUrl** | URL callback khi fetch thành công | String | Không       |
| **FailureCallbackUrl** | URL callback khi fetch thất bại | String | Không       |

Có thể lấy **JobId** từ giao diện.

###### Body Phản hồi

| Tên | Mô tả | Kiểu dữ liệu |
| -------- | ------------------------- | ------ |
| **RetCode** | Mã trạng thái | Int    |
| **ErrMsg**  | Thông báo lỗi | String |
| **TaskId**  | ID tác vụ duy nhất | String |

Ví dụ phản hồi:

```JSON
{
"RetCode": 0,
"ErrMsg": "Success",
"TaskId": "d4d62b79-b292-411a-a1f2-47369e2b532f"
}
```

##### Ví dụ Yêu cầu

```HTTP
POST /fetch/ HTTP/1.1
Authorization: VNPT Cloud this-is-my-public-key:AAAArandomsignature=
Content-Type: application/json
Content-Length: 159

{
"Url": "http://xxx.xxx.xxx/xxx/movie.mp4",
"Bucket": "example_bucket",
"Key": "movie.mp4",
"JobId": "xxxxxxxxxxxxxxxxxxxx",
"SuccessCallbackUrl": "http://xxx.xxx.xxx/success",
"FailureCallbackUrl": "http://xxx.xxx.xxx/failure"
}
```

##### Ví dụ Phản hồi

```HTTP
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 122
Connection: keep-alive

{
"RetCode": 0,
"ErrMsg": "Success",
"TaskId": "d4d62b79-b292-411a-a1f2-47369e2b532f"
}
```

#### Nội dung Callback

Bạn có thể chỉ định các URL callback khi hoàn thành tác vụ trong yêu cầu. US3SYNC sẽ gửi một yêu cầu POST đến URL được chỉ định dựa trên kết quả tác vụ. Ví dụ:

- **Callback khi Thất bại:**

```JSON
{
"Code": 1,
"TaskId": "d4d62b79-b292-411a-a1f2-47369e2b532f",
"Message": "We encountered an internal error.",
"Resource": "http://xxx.xxx.xxx/xxx/movie.mp4"
}
```

- **Callback khi Thành công:**

```JSON
{
"Code": 0,
"TaskId": "d4d62b79-b292-411a-a1f2-47369e2b532f",
"ETag": "xxxxxxxx",
"Key": "xxxxxxxxxxxxxxx.mp4",
"SHA1": "0bc51013e87869137a432200f57daf6affdd3d0c",
"Size": 638304718
}
```

## Các Tính năng Chính

1. Hỗ trợ di chuyển dữ liệu từ các kho lưu trữ đám mây S3, OSS, Qiniu, Youpai và S3 sang S3.
2. Hỗ trợ di chuyển dữ liệu từ lưu trữ NAS hoặc các thư mục cục bộ sang S3.
3. Cho phép di chuyển dữ liệu từ các danh sách tài nguyên URL được chỉ định sang S3.
4. Cung cấp quản lý dựa trên giao diện web cho các tác vụ và nút di chuyển dữ liệu.
5. Cho phép quản lý nguồn dữ liệu.
6. Hỗ trợ lên lịch cho các tác vụ để thực hiện định kỳ.
7. Cho phép xuất danh sách các tệp bị lỗi.

**Lưu ý:** Không hỗ trợ di chuyển từ các tệp nguồn ở chế độ lưu trữ (archive mode).

## Cấu trúc Thư mục

```
US3SYNC
├── bin
│   ├── master            # File thực thi Master
│   └── worker            # File thực thi Worker
├── conf
│   └── config.toml       # File cấu hình
├── cert                  # Chứng chỉ HTTPS
├── log                   # Thư mục tệp log của Master
├── pika                  # Gói phụ thuộc
└── console.sh            # Script khởi động
```

## Phiên bản và Môi trường

### Phiên bản Phần mềm

Phiên bản hiện tại: **1.10.4**

### Môi trường Hoạt động

- **Linux:**
- CentOS 7.0 trở lên (kiểm tra bằng lệnh `cat /etc/redhat-release`)
- Ubuntu 16.04 trở lên (kiểm tra bằng lệnh `cat /etc/issue`)