UNIVERSAL UPLOADER

如视 realsee.cn 的多云部署存储上传工具。

安装

npm i @realsee/universal-uploader

browser example

import { Uploader, ProviderName, ProviderAdaptor } from '@realsee/universal-uploader';

const form = document.querySelector('form')!;
const status = document.querySelector('#status')!;

const ASYNC_ADAPTORS: Record<ProviderName, ProviderAdaptor> = {
  'cos': () => import('@realsee/universal-uploader/adaptors/cos'),
  'oss': () => import('@realsee/universal-uploader/adaptors/oss'),
  'aws': () => import('@realsee/universal-uploader/adaptors/aws'),
};

function log(...text: (string | number)[]) {
  status.innerHTML = text.join('<br/>');
}

async function submit(formData: FormData) {

  const provider = formData.get('provider') as ProviderName;
  const token = formData.get('token') as string;
  const key = formData.get('key') as string;
  const file = formData.get('file') as File;
  const parallel = formData.get('parallel') as string;
  const partSize = formData.get('part-size') as string;
  const retry = formData.get('retry') as string;

  if (!key || !file || !file.size || !token) {
    alert('Form Invalid');
    return;
  }

  const uploader = new Uploader(ASYNC_ADAPTORS[provider], {
    getToken: () => {
      const tokenObject = JSON.parse(token);
      console.log(tokenObject);
      return Promise.resolve(tokenObject);
    },
  });

  const result = await uploader.upload(key, file, {
    parallel: parseInt(parallel, 10) || Uploader.defaultUploadHandler.parallel,
    partSize: partSize || Uploader.defaultUploadHandler.partSize,
    retry: parseInt(retry, 10) || Uploader.defaultUploadHandler.retry,
    onProgress(event) {
      log(
        'progress',
        `event.percentage(${event.transferredParts}/${event.totalParts})`
      );
    },
    onSuccess(event) {
      log(
        'success',
        `download_url: ${event.download_url}`,
        `download_url_not_cached: ${event.download_url_not_cached}`,
        `etag: ${event.etag}`,
      );
    },
    onError(error) {
      console.log(error);
      log(
        'error',
        error.message,
      );
    }
  });
  console.log('result', result);
}

form.addEventListener('submit', event => {
  event.preventDefault();
  const formData = new FormData(form);
  submit(formData);
}, false);

node example

需要 node 支持 fetch API

import { Uploader, ProviderName, ProviderAdaptor } from '@realsee/universal-uploader';
import { openAsBlob } from '@realsee/universal-uploader/node';

const ASYNC_ADAPTORS: Record<ProviderName, ProviderAdaptor> = {
  'cos': () => import('@realsee/universal-uploader/adaptors/cos'),
  'oss': () => import('@realsee/universal-uploader/adaptors/oss'),
  'aws': () => import('@realsee/universal-uploader/adaptors/aws'),
};


async function main() {
  const provider: ProviderName = 'cos';
  const token = '<token>';
  const key = 'a-test-file-from-universal-uploader.txt';
  const file = await openAsBlob('./test.txt');
  let parallel: number | undefined;
  let partSize: number | undefined;
  let retry: number | undefined;

  const uploader = new Uploader(ASYNC_ADAPTORS[provider], {
    getToken: () => {
      const tokenObject = JSON.parse(token);
      console.log(provider, 'token', tokenObject);
      return Promise.resolve(tokenObject);
    },
  });

  const result = await uploader.upload(key, file, {
    parallel: parallel ?? Uploader.defaultUploadHandler.parallel,
    partSize: partSize ?? Uploader.defaultUploadHandler.partSize,
    retry: retry ?? Uploader.defaultUploadHandler.retry,
    onProgress(event) {
      console.log(
        provider,
        'progress',
        `event.percentage(${event.transferredParts}/${event.totalParts})`
      );
    },
    onSuccess(event) {
      console.log(
        provider,
        'success',
        `download_url: ${event.download_url}`,
        `download_url_not_cached: ${event.download_url_not_cached}`,
        `etag: ${event.etag}`,
      );
    },
    onError(error) {
      console.log(
        provider,
        'error',
        error.message,
      );
    }
  });
  console.log(provider, 'result', result);
}

main();

如何获取 token

CLI

安装后可通过命令行直接上传文件，无需编写代码。

# 基本用法
realsee-universal-uploader upload -p cos -t ./token.json -k "images/photo.jpg" --file ./photo.jpg

# 自定义分片参数
realsee-universal-uploader upload -p aws -t ./token.json -k "data/file.bin" --file ./large.bin --part-size 5mb --parallel 4 --retry 3

# JSON 输出（方便 CI/CD 集成）
realsee-universal-uploader upload -p oss -t ./token.json -k "assets/doc.pdf" --file ./doc.pdf --json

参数说明

| 参数 | 必填 | 说明 | 默认值 | |------|------|------|--------| | -p, --provider | ✅ | 云供应商: cos, oss, aws | - | | -t, --token | ✅ | 上传凭证 JSON 文件路径 | - | | -k, --key | ✅ | 上传目标路径 (key) | - | | --file | ✅ | 要上传的本地文件路径 | - | | --parallel | | 分片并发数 | 2 | | --part-size | | 分片大小，如 10mb, 5mb | 10mb | | --retry | | 失败重试次数 | 2 | | --json | | 以 JSON 格式输出结果 | false |

其他命令

# 查看版本
universal-uploader --version

# 查看支持的云供应商
universal-uploader providers

如何获取 token

参考 https://wiki.lianjia.com/pages/viewpage.action?pageId=542219308 中 “获取 cos token” 接口。

1. 数据字典的 idenname，ak，从数据云平台获取 http://vrdata-cloud.lianjia.com/#MyResourcePage
2. 将获取到的数据中的 data 字段作为 token 内容作为 getToken 回调函数的返回值。
3. 为何 getToken 是回调函数？ 数据分片上传，可能出现 token 过期的情况，此时会自动调用 getToken 获取最新token，继续上传行为。

如何获取上传的数据

1. 从数据云平台获取 http://vrdata-cloud.lianjia.com/#DownloadDataPage
2. 如果上传公用桶，可以直接在返回中的 download_url, download_url_not_cached 字段得到。