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