Skip to main content
Version: 3.0.0

阿里云对象存储(OSS)

阿里云对象存储服务(Object Storage Service,简称 OSS),是阿里云提供的海量、安全、低成本、高可靠的云存储服务。其数据设计持久性不低于 99.999999999%,服务设计可用性不低于 99.99%。具有与平台无关的 RESTful API 接口,您可以在任何应用、任何时间、任何地点存储和访问任意类型的数据。

@midwayjs/oss 组件就是在 midway 体系下用于对接 OSS 服务的 sdk。

相关信息:

描述
可用于标准项目
可用于 Serverless
可用于一体化
包含独立主框架
包含独立日志

前置条件

使用 OSS 组件,你需要提前申请一个 OSS Bucket。Bucket 是 OSS 的存储库的概念,你的文件都将存储在这个库里。

安装依赖

@midwayjs/oss 是主要的功能包,@types/ali-oss 是 oss 的官方定义包。

$ npm i @midwayjs/oss@3 --save
$ npm i @types/ali-oss --save-dev // 安装到 dev 依赖

或者在 package.json 中增加如下依赖后,重新安装。

{
"dependencies": {
"@midwayjs/oss": "^3.0.0",
// ...
},
"devDependencies": {
"@types/ali-oss": "^6.16.0",
// ...
}
}
info

如果发现 OSSService 没有方法定义,请务必检查此项。

引入组件

首先,引入 组件,在 configuration.ts 中导入:

import { Configuration } from '@midwayjs/decorator';
import * as oss from '@midwayjs/oss';
import { join } from 'path'

@Configuration({
imports: [
// ...
oss // 导入 oss 组件
],
importConfigs: [
join(__dirname, 'config')
]
})
export class MainConfiguration {
}

配置 OSS

OSS 组件需要配置后才能使用。需要填写 OSS 的 bucket、accessKeyId、accessKeySecret 等必要信息。

支持普通 oss 客户端和 oss 集群客户端,基于 ali-oss 这个包。

比如:

普通的 oss bucket 配置

// src/config/config.default
export default {
// ...
oss: {
// normal oss bucket
client: {
accessKeyId: 'your access key',
accessKeySecret: 'your access secret',
bucket: 'your bucket name',
endpoint: 'oss-cn-hongkong.aliyuncs.com',
timeout: '60s',
},
},
}

集群(cluster) 模式的 oss bucket 配置,需要配置多个

// src/config/config.default
export default {
// ...
oss: {
// need to config all bucket information under cluster
client: {
clusters: [{
endpoint: 'host1',
accessKeyId: 'id1',
accessKeySecret: 'secret1',
}, {
endpoint: 'host2',
accessKeyId: 'id2',
accessKeySecret: 'secret2',
}],
schedule: 'masterSlave', //default is `roundRobin`
timeout: '60s',
},
},
}

sts 模式

// src/config/config.default
export default {
// ...
oss: {
// if config.sts == true, oss will create STS client
client: {
sts: true,
accessKeyId: 'your access key',
accessKeySecret: 'your access secret',
},
},
}

使用组件

可以直接获取 OSSService,然后调用接口,比如,保存文件。

import { OSSService } from '@midwayjs/oss';
import { join } from 'path';

@Provide()
export class UserService {

@Inject()
ossService: OSSService;

async saveFile() {


const localFile = join(__dirname, 'test.log');
const result = await this.ossService.put('/test/test.log', localFile);

// => result.url
}
}

如果配置的是 STS 模式,客户端可以使用 OSSSTSService

import { OSSSTSService } from '@midwayjs/oss';
import { join } from 'path';

@Provide()
export class UserService {

@Inject()
stsService: OSSSTSService;

async saveFile() {

const roleArn = '******'; // 这里是阿里云角色的 arn
const result = await this.stsService.assumeRole(roleArn);

// result.credentials.AccessKeyId
// result.credentials.AccessKeySecret;
// result.credentials.SecurityToken;
}
}

更多的 OSS 客户端 API,请查看 OSS 文档

使用多个 OSS Bucket

有些应用需要访问多个 oss bucket,那么就需要配置 oss.clients

// src/config/config.default
export default {
// ...
oss: {
clients: {
bucket1: {
bucket: 'bucket1',
// ...
},
bucket2: {
bucket: 'bucket2',
// ...
},
},
// client, clients,createInstance 方法共享的配置
default: {
endpoint: '',
accessKeyId: '',
accessKeySecret: '',
},
},
// other custom config
bucket3: {
bucket: 'bucket3',
// ...
},
}

可以使用 OSSServiceFactory 获取不同的实例。

import { OSSServiceFactory } from '@midwayjs/oss';
import { join } from 'path';

@Provide()
export class UserService {

@Inject()
ossServiceFactory: OSSServiceFactory;

@Config('bucket3')
bucket3Config;

async saveFile() {

// 默认获取的类型是 OSSService
const bucket1 = this.ossServiceFactory.get('bucket1');
const bucket2 = this.ossServiceFactory.get('bucket2');

// 如果是 STS,需要设置泛型联系
// const bucket1 = this.ossServiceFactory.get<OSSSTSService>('bucket1');

// 会合并 config.bucket3 和 config.oss.default
const bucket3 = await this.ossServiceFactory.createInstance(this.bucket3Config, 'bucket3');
// 传了名字之后也可以从 factory 中获取
bucket3 = this.ossServiceFactory.get('bucket3');

}
}