devsapp/oss

静态资源托管 oss 组件

阿里云静态资源 OSS 组件 ⎯⎯⎯ 通过使用 Serverless-Devs，基于云上 Serverless 的对象存储服务，实现“0”配置，便捷开发，极速上传您的静态资源托管到阿里云对象存储 OSS（Object Storage Service）。 静态资源 OSS 组件支持丰富的配置扩展，提供了目前最易用、低成本并且弹性伸缩的静态站点开发和托管能力。

快速开始

🙋 三步即可上手 对象存储（OSS）组件的使用：
❶ 安装 Serverless Devs 开发者工具 ：npm install -g @serverless-devs/s；

安装完成还需要配置密钥，可以参考密钥配置文档

❷ 初始化一个hexo静态博客项目：s init devsapp/website-hexo；

❸ 初始化完成之后， 只需要输入指令s deploy即可完成项目的部署；

Yaml 规范说明

完整配置

edition: 1.0.0 #  命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
name: website #  项目名称
access: default #  秘钥别名

vars:
  region: cn-hangzhou

services:
  website-start:
    component: oss # (必填) 引用 component 的名称
    props:
      region: ${vars.region}
      bucket: auto # OSS bucket 自动生成
      acl: public-read # 读写权限
      codeUri: ./build # 指定本地要上传目录文件地址
      subDir: subObject # 指定OSS Bucket 文件上传目录
      cors: # OSS 设置跨域资源共享规则
        - allowedOrigin: [https://oss.console.aliyun.com]
          allowedMethod: ['GET', 'PUT', 'DELETE', 'POST', 'HEAD']
        - allowedOrigin: ['https://www.aliyun.com']
          allowedMethod: ['GET']
      referer: # OSS 设置Referer防盗链
        allowEmpty: true
        referers: ['https://edasnext.console.aliyun.com']
      website: # OSS 静态网站配置
        index: index.html # 默认首页
        error: 404.html # 默认 404 页
        subDirType: redirect # 子目录首页 404 规则
      customDomains: # OSS 绑定域名
        - domainName: auto
          protocol: HTTP

字段解析

参数名	必填	类型	参数描述
region	True	Enum	地域
bucket	True	String	Struct
codeUri	True	String	指定本地要上传目录文件地址
acl	False	Enum	函数
subDir	True	String	指定OSS Bucket 文件上传目录
cors	True	List<Object>	跨域资源共享
referer	True	Object	Referer防盗链
website	True	Object	静态页面
customDomains	True	Object	域名绑定

bucket字段

bucket参数的简单配置可以是 auto,会自动创建阿里云全局唯一的bucket名。 当然也可以指定bucket名称，需要注意是的bucket名是全局唯一的，注意不要重名

acl字段

OSS ACL 提供 Bucket 级别的权限访问控制。Bucket目前有三种访问权限：public-read-write，public-read和private，它们的含义如下：

• public-read-write: 任何人（包括匿名访问者）都可以对该存储空间内文件进行读写操作
• public-read: 只有该存储空间的拥有者可以对该存储空间内的文件进行写操作，任何人（包括匿名访问者）都可以对该存储空间中的文件进行读操作。
• private: 只有该存储空间的拥有者可以对该存储空间内的文件进行读写操作，其他人无法访问该存储空间内的文件。

默认配置了website字段的情况下，acl默认属性为public-read

cors字段

cors跨域资源设置，解决 JavaScript 的跨域访问问题

参数名	必填	类型	参数描述
allowedOrigin	True	String	允许来源
allowedMethod	True	String	允许 Methods

参考案例：

cors: # OSS 设置跨域资源共享规则
  - allowedOrigin: [https://oss.console.aliyun.com]
    allowedMethod: ['GET', 'PUT', 'DELETE', 'POST', 'HEAD']
  - allowedOrigin: ['https://www.aliyun.com']
    allowedMethod: ['GET']

referer字段

防盗链功能通过设置Referer白名单以及是否允许空Referer，限制仅白名单中的域名可以访问您Bucket内的资源。OSS支持基于HTTP和HTTPS header中表头字段Referer的方法设置防盗链。

是否进行防盗链验证的具体场景如下：

• 仅当通过签名URL或者匿名访问Object时，进行防盗链验证。
• 当请求的Header中包含Authorization字段，不进行防盗链验证

参数名	必填	类型	参数描述
allowEmpty	False	Boolean	空 Refere
referers	True	List	referers列表

参考案例：

referer: # OSS 设置Referer防盗链
  allowEmpty: true
  referers: ['https://edasnext.console.aliyun.com']

website字段

website 静态网站是指所有的网页都由静态内容构成，包括客户端执行的脚本（例如JavaScript）。您可以通过静态网站托管功能将您的静态网站托管到OSS的存储空间（Bucket），并使用Bucket的访问域名访问这个网站。

参数名	必填	类型	参数描述
index	False	String	默认首页
error	True	String	默认 404 页
subDirType	False	String	子目录首页

customDomains字段

oss's Issues

添加.signore的规范

支持忽略某些文件

支持 .signore 的规范

【优化】增加了MD5校验工具，避免上传重复文件

OSS上传表现

let  ossClient = new OssClient({
  bucket:'alidankun',
  region: 'oss-cn-hangzhou',
  accessKeyId: 'xxx',
  accessKeySecret: 'xxx',
});
// 文件上传
ossClient.put('package-lock.json', './package-lock.json').then(console.log)

返回值如下：

{
  name: 'package-lock.json',
  url: 'http://alidankun.oss-cn-hangzhou.aliyuncs.com/package-lock.json',
  res: {
    status: 200,
    statusCode: 200,
    statusMessage: 'OK',
    headers: {
      server: 'AliyunOSS',
      date: 'Sun, 20 Feb 2022 15:22:14 GMT',
      'content-length': '0',
      connection: 'keep-alive',
      'x-oss-request-id': '62125CA566708532387C433F',
      etag: '"0D7B62C9784757D4119175FABA9FF009"',
      'x-oss-hash-crc64ecma': '4367586805770846289',
      'content-md5': 'DXtiyXhHV9QRkXX6up/wCQ==',
      'x-oss-version-id': 'CAEQKhiBgID95vPe.BciIGNhZTE3OWFhMDJiODRmMGVhZjc2Yjk2MzEzMTRiZDNl',
      'x-oss-server-time': '74'
    },
 }
}

注意headers中的content-md5 即是文件内容的md5值，如果文件内容没有变化，可以无需上传

方案：

实现方案

ossClient.put 文件之后将md5值存入**.serverless-devs-${uid}-${region}-md5.json文件中，每次部署前都看下本地文件生成的md5值和.serverless-devs-${uid}-${region}-md5.json**是否一致，如果一致则不上传

本地适配OSS服务端的MD5实现

https://help.aliyun.com/knowledge_detail/39533.html

nodejs实现如下：

const crypto = require('crypto');
const localPathName_MD5 = file => crypto.createHash('md5').update(fs.readFileSync(file, 'utf8')).digest('hex');

支持通过OSS SDK直接绑定域名

OSS 组件优化建议

• ## 关于代码结构
  在index.ts里面只是出现，功能相关的逻辑，bucketIsExisting以及upload不应该放在这里
  

  oss/src/index.ts

  Line 58 in a0a843f

  async upload(ossClient: OssClient, staticPath: string, ossObject: string) {

• ## 关于API设计
  ossObject 字段感觉非常难以理解是子目录的意思，在OSS的文档中都透出是 subDir ,是不是可以拿过来换成 subDir

• ## 是否需要用户设置 bucket
  bucket这个概念其实对很多用户其实不太能够理解。需要全局唯一，也比较容易困惑，可以这样是不是可以和FC组件保持一致，

  • 如果是 auto的时候，就默认的 bucket 值为 如下形式 serverless-devs-${region}-${serviceName}-${uid}
  • 如果是用户自己填写的，则按照原来的逻辑走下去

• ## 关于帮助信息
  s deploy -h 现在看不到任何相关的帮助信息,可以参考FC 组件 https://github.com/devsapp/fc/blob/266c55df7d3fb336a022a10001ec75ebb802c132/src/index.ts#L130

• ## 关于remove指令

  • 既然创建啦资源，意味着肯定可以删除资源。这里的资源包括 配置以及实际的 资源文件。OSS需要先删除资源文件才能删除整个配置以及bukect，这里可以参考下 s remove的设计，让用户选择是否要删除所有
  • 也可以删除某个目录，甚至某个目录下的资源文件
    

• ## 关于 deploy指令
  deploy 部署可以区分为部署文件资源以及部署配置。这里可以，设置为 s deploy --type config 以及 s deploy --type resouce,
  这样我就不会每次都需要部署我的配置啦

• 关于默认配置

  • 关于权限acl
    默认的权限是 private,这样对于网站类型的，肯定就走不下去啦， 所以默认的 acl 类型应该是public-read
  • 关于子目录
    默认开通子目录，同时(subDir)404的规则默认为index

• ## 关于 -y 可选参数
  需要提供-y 参数, 在CD流程中避免询问，比如提示资源不存在，是否自动创建

• ## 关于自定义域名

  • OSS新版本已经支持，通过SDK实现自定义域名的绑定， https://help.aliyun.com/document_detail/32076.html 。之前的 website组件需要通过CDN， 对于用户使用非常不友好。需要跟进。 通过设置 customDomains: auto https://github.com/devsapp/fc/blob/main/docs/zh/yaml.md#customDomains%E5%AD%97%E6%AE%B5
  • 也可以设置自定义的域名配置

关于自定义域名和CDN结合问题

增加CDN组件

在OSS的website配置CDN的具体能力
website:
index: index.html
404: 404.html
subDir: index
cdn:
- xx
- yy
- zz

关于自定义域名

• 如果是auto
  调用domain组件。 （暂时只和CDN绑定）
  https://github.com/devsapp/website/blob/778f38fe62c727fb71c7b2d0305e4f690a9e4af5/src/services/domain.service.ts#L149
• 如果是自定义的域名
  需要提示向导：
  

如果OSS的接口报错，并没有throw ERROR 导致CD无法catch，没有报错

https://github.com/Serverless-Devs/serverless-website/runs/5288435896?check_suite_focus=true#step:6:148