From affe230a2ada511143e442ee0ff1453ad9cc2dec Mon Sep 17 00:00:00 2001 From: xiaolongzuo <150349407@qq.com> Date: Tue, 13 Nov 2018 17:47:04 +0800 Subject: [PATCH] Update ref doc. --- .../src/main/asciidoc-zh/acm.adoc | 2 +- .../src/main/asciidoc-zh/ans.adoc | 110 ++++++++++++ .../src/main/asciidoc-zh/oss.adoc | 156 ++++++++++++++++++ 3 files changed, 267 insertions(+), 1 deletion(-) diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/acm.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/acm.adoc index 143e764a..16ff206c 100644 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/acm.adoc +++ b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/acm.adoc @@ -1,6 +1,6 @@ = Spring Cloud AliCloud ACM -Spring Cloud Alibaba Config 提供了和阿里云上的ACM的集成。使得在项目中如果需要上云的用户可以非常方便无缝的对接阿里云，来享受云端提供的稳定服务。 +Spring Cloud AliCloud ACM 提供了和阿里云上的ACM的集成。使得在项目中如果需要上云的用户可以非常方便无缝的对接阿里云，来享受云端提供的稳定服务。 === 快速开始 diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/ans.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/ans.adoc index b9b34ce2..63c83976 100644 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/ans.adoc +++ b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/ans.adoc @@ -1 +1,111 @@ == Spring Cloud AliCloud ANS + +ANS（Application Naming Service） 是隶属于阿里云EDAS产品的组件， Spring Cloud AliCloud ANS 提供了Spring Cloud规范下商业版的服务注册与发现，可以让用户方便的在本地开发，同时也可以运行在云环境里。 + +=== 如何引入 Spring Cloud AliCloud ANS + +Spring Cloud Alibaba 已经发布了0.2.0版本，需要首先导入依赖管理POM。 + +[source,xml] +---- + + + + org.springframework.cloud + spring-cloud-alibaba-dependencies + 0.2.0.RELEASE + pom + import + + + +---- + +接下来引入 Spring Cloud AliCloud ANS Starter 即可。 + +[source,xml] +---- + + org.springframework.cloud + spring-cloud-starter-alicloud-ans + +---- + +=== 使用ANS进行服务注册 + +当客户端引入了 Spring Cloud AliCloud ANS Starter 以后，服务的元数据会被自动注册到注册中心，比如IP、端口、权重等信息。客户端会与服务端保持心跳，来证明自己可以正常提供服务。 + +以下是一个简单的应用示例。 + +[source,java] +---- +@SpringBootApplication +@EnableDiscoveryClient +@RestController +public class ProviderApplication { + + @RequestMapping("/") + public String home() { + return "Hello world"; + } + + public static void main(String[] args) { + SpringApplication.run(ProviderApplication.class, args); + } + +} +---- + +既然服务会被注册到注册中心，那么肯定需要配置注册中心的地址，在application.properties中，还需要配置上以下地址。 + +[source,properties] +---- +# 应用名会被作为服务名称使用，因此会必选 +spring.application.name=ans-provider +server.port=18081 +# 以下就是注册中心的IP和端口配置，因为默认就是127.0.0.1和8080，因此以下两行配置也可以省略 +spring.cloud.alicloud.ans.server.list=127.0.0.1 +spring.cloud.alicloud.ans.server.port=8080 +---- + +NOTE: 此时没有启动注册中心，启动应用会报错，因此在应用启动之前，应当首先启动注册中心。 + +=== 启动注册中心 + +ANS使用的注册中心有两种，一种是完全免费的轻量版配置中心，主要用于开发和本地调试，一种是云上注册中心，ANS依托于阿里云EDAS产品提供服务注册的功能。通常情况下，可以使用轻量版配置中心作为开发和测试环境，使用云上的EDAS作为灰度和生产环境。 + +==== 启动轻量版配置中心 + +轻量版配置中心的下载和启动方式可参考 https://help.aliyun.com/document_detail/44163.html?spm=a2c4g.11186623.6.677.5f206b82Z2mTCF[这里] + +NOTE: 只需要进行第1步（下载轻量配置中心）和第2步（启动轻量配置中心）即可，第3步（配置hosts）在与 ANS 结合使用时，不需要操作。 + +启动完轻量版配置中心以后，直接启动 ProviderApplication ，即可将服务注册到轻量版配置中心，由于轻量版配置中心的默认端口是8080，因此你可以打开 http://127.0.0.1:8080 ，点击左侧"服务列表"，查看注册上来的服务。 + +==== 使用云上注册中心 + +使用云上注册中心，可以省去服务端的维护工作，同时稳定性也会更有保障。当使用云上注册中心时，代码部分和使用轻量配置中心并没有区别，但是配置上会有一些区别。 + +以下是一个简单的使用云上配置中心的配置示例。 + +[source,properties] +---- +# 应用名会被作为服务名称使用，因此是必选 +spring.application.name=ans-provider +# 端口配置自由配置即可 +server.port=18081 +# 以下就是注册中心的IP和端口配置，因为默认就是127.0.0.1和8080，因此以下两行配置也可以省略 +spring.cloud.alicloud.ans.server-mode=EDAS +spring.cloud.alicloud.access-key=你的阿里云AK +spring.cloud.alicloud.secret-key=你的阿里云SK +spring.cloud.alicloud.edas.namespace=cn-xxxxx +---- + +server-mode 的默认值为 LOCAL ，如果要使用云上注册中心，则需要更改为 EDAS 。 + +access-key 和 secret-key 则是阿里云账号的AK/SK，需要首先注册阿里云账号，然后登陆 https://usercenter.console.aliyun.com/#/manage/ak[阿里云AK/SK管理页面] ，即可看到 AccessKey ID 和 Access Key Secret ，如果没有的话，需要点击"创建AccessKey"按钮创建。 + +namespace 是阿里云EDAS产品的概念，用于隔离不同的环境，比如测试环境和生产环境。要获取 namespace 需要 https://common-buy.aliyun.com/?spm=5176.11451019.0.0.6f5965c0Uq5tue&commodityCode=edaspostpay#/buy[开通EDAS服务]，按量计费模式下开通是免费的，开通以后进入 https://edas.console.aliyun.com/#/namespaces?regionNo=cn-hangzhou[EDAS控制台]，即可看到对应的namespace，比如cn-hangzhou。 + +NOTE: EDAS提供应用托管服务，如果你将应用托管到EDAS，那么EDAS将会自动为你填充所有配置。 + diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/oss.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/oss.adoc index 20b43f75..778a8560 100644 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/oss.adoc +++ b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/oss.adoc @@ -1 +1,157 @@ == Spring Cloud AliCloud OSS + +OSS（Object Storage Service）是阿里云的一款对象存储服务产品， Spring Cloud AliCloud OSS 提供了Spring Cloud规范下商业版的对象存储服务，提供简单易用的API，并且支持与 Spring 框架中 Resource 的整合。 + +=== 如何引入 Spring Cloud AliCloud OSS + +Spring Cloud Alibaba 已经发布了0.2.0版本，需要首先导入依赖管理POM。 + +[source,xml] +---- + + + + org.springframework.cloud + spring-cloud-alibaba-dependencies + 0.2.0.RELEASE + pom + import + + + +---- + +接下来引入 Spring Cloud AliCloud OSS Starter 即可。 + +[source,xml] +---- + + org.springframework.cloud + spring-cloud-starter-alicloud-oss + +---- + +=== 如何使用 OSS API + +==== 配置 OSS + +使用 Spring Cloud AliCloud OSS 之前，需要在 application.properties 中加入以下配置。 + +[source,properties] +---- +spring.cloud.alicloud.access-key=你的阿里云AK +spring.cloud.alicloud.secret-key=你的阿里云SK +spring.cloud.alicloud.oss.endpoint=***.aliyuncs.com +---- + +access-key 和 secret-key 是阿里云账号的AK/SK，需要首先注册阿里云账号，然后登陆 https://usercenter.console.aliyun.com/#/manage/ak[阿里云AK/SK管理页面] ，即可看到 AccessKey ID 和 Access Key Secret ，如果没有的话，需要点击"创建AccessKey"按钮创建。 + +endpoint可以到 OSS 的 https://help.aliyun.com/document_detail/31837.html?spm=a2c4g.11186623.2.9.7dc72841Z2hGqa#concept-zt4-cvy-5db[官方文档]中查看，根据所在的 region ，填写对应的 endpoint 即可。 + + +==== 引入 OSS API + +Spring Cloud Alicloud OSS 中的 OSS API 基于阿里云官方OSS SDK提供，具备上传、下载、查看等所有对象存储类操作API。 + +一个简单的使用 OSS API 的应用如下。 + +[source,java] +---- +@SpringBootApplication +public class OssApplication { + + @Autowired + private OSS ossClient; + + @RequestMapping("/") + public String home() { + ossClient.putObject("bucketName", "fileName", new FileInputStream("/your/local/file/path")); + return "upload success"; + } + + public static void main(String[] args) throws URISyntaxException { + SpringApplication.run(OssApplication.class, args); + } + +} +---- + +在上传文件之前，首先需要 https://account.aliyun.com/register/register.htm?spm=5176.8142029.388261.26.e9396d3eaYK2sG&oauth_callback=https%3A%2F%2Fwww.aliyun.com%2F[注册阿里云账号] ，如果已经有的话，请 https://common-buy.aliyun.com/?spm=5176.8465980.unusable.dopen.4cdf1450rg8Ujb&commodityCode=oss#/open[开通OSS服务]。 + +进入 https://oss.console.aliyun.com/overview[OSS控制台]，点击左侧"新建Bucket"，按照提示创建一个Bucket，然后将bucket名称替换掉上面代码中的"bucketName"，而"fileName"取任意文件名，"/your/local/file/path"取任意本地文件路径，然后 curl http://127.0.0.1:端口/ 即可上传文件，可以到 https://oss.console.aliyun.com/overview[OSS控制台]查看效果。 + +更多关于 OSS API 的操作，可以参考 https://help.aliyun.com/document_detail/32008.html[OSS官方SDK文档]。 + +=== 与 Spring 框架的 Resource 结合 + +Spring Cloud AliCloud OSS 整合了 Spring 框架的 Resource 规范，可以让用户很方便的引用 OSS 的资源。 + +一个简单的使用 Resource 的例子如下。 + +[source,java] +---- +@SpringBootApplication +public class OssApplication { + + @Value("oss://bucketName/fileName") + private Resource file; + + @GetMapping("/file") + public String fileResource() { + try { + return "get file resource success. content: " + StreamUtils.copyToString( + file.getInputStream(), Charset.forName(CharEncoding.UTF_8)); + } catch (Exception e) { + return "get resource fail: " + e.getMessage(); + } + } + + public static void main(String[] args) throws URISyntaxException { + SpringApplication.run(OssApplication.class, args); + } + +} +---- + +NOTE: 以上示例运行的前提是，在 OSS 上需要有名为"bucketName"的Bucket，同时在该Bucket下，存在名为"fileName"的文件。 + +=== 采用 STS 授权 + +Spring Cloud AliCloud OSS 除了 AccessKey/SecretKey 的授权方式以外，还支持 STS 授权方式。 STS 是临时访问令牌的方式，一般用于授权第三方，临时访问自己的资源。 + +作为第三方，也就是被授权者，只需要配置以下内容，就可以访问临时被授权的资源。 + +[source,properties] +---- +spring.cloud.alicloud.oss.authorization-mode=STS +spring.cloud.alicloud.oss.endpoint=***.aliyuncs.com +spring.cloud.alicloud.oss.sts.access-key=你被授权的AK +spring.cloud.alicloud.oss.sts.secret-key=你被授权的SK +spring.cloud.alicloud.oss.sts.security-token=你被授权的ST +---- + +其中 spring.cloud.alicloud.oss.authorization-mode 是枚举类型，此时填写 STS ，代表采用 STS 的方式授权。 endpoint可以到 OSS 的 https://help.aliyun.com/document_detail/31837.html?spm=a2c4g.11186623.2.9.7dc72841Z2hGqa#concept-zt4-cvy-5db[官方文档]中查看，根据所在的 region ，填写对应的 endpoint 即可。 + +access-key、secret-key和security-token需要由授权方颁发，如果对 STS 不了解的话，可以参考 https://help.aliyun.com/document_detail/31867.html[STS官方文档]。 + +=== 更多客户端配置 + +除了基本的配置项以外， Spring Cloud AliCloud OSS 还支持很多额外的配置，也是在 application.properties 文件中。 + +以下是一些简单的示例。 + +[source,properties] +---- +spring.cloud.alicloud.oss.authorization-mode=STS +spring.cloud.alicloud.oss.endpoint=***.aliyuncs.com +spring.cloud.alicloud.oss.sts.access-key=你被授权的AK +spring.cloud.alicloud.oss.sts.secret-key=你被授权的SK +spring.cloud.alicloud.oss.sts.security-token=你被授权的ST + +spring.cloud.alicloud.oss.config.connection-timeout=3000 +spring.cloud.alicloud.oss.config.max-connections=1000 +---- + +如果想了解更多的配置项，可以参考 https://help.aliyun.com/document_detail/32010.html?spm=a2c4g.11186623.6.703.50b25413nGsYHc[OSSClient配置项] 的末尾表格。 + +NOTE: 通常情况下，都需要将 https://help.aliyun.com/document_detail/32010.html?spm=a2c4g.11186623.6.703.50b25413nGsYHc[OSSClient配置项] 末尾表格中的参数名更换成"-"连接，且所有字母小写。例如 ConnectionTimeout，对应 connection-timeout。 \ No newline at end of file