Java Chassis接入CSE

前提条件

• 已基于Java Chassis开发好了微服务应用。

  Java Chass框架下的微服务应用开发，请参考https://servicecomb.apache.org/references/java-chassis/zh_CN/。

• 版本要求：请参见微服务开发框架版本要求。
• 本文假设您的项目使用了maven管理打包，您熟悉maven的依赖管理机制，能够正确的修改“pom.xml”文件中的dependency management和dependency。
• Java Chassis支持和不同的技术进行组合使用，配置文件的名称和实际使用的技术有关。如果您采用Spring方式使用Java Chassis，配置文件的名称一般为“microservice.yaml”，如果您采用Spring Boot方式使用Java Chassis， 配置文件名称一般为“application.yaml”。本文统一使用“microservice.yaml”表示配置文件，请结合实际项目进行区分。

操作步骤

1. 在项目的“pom.xml”文件中引入依赖。

   <dependency>
       <groupId>org.apache.servicecomb</groupId>
       <artifactId>solution-basic</artifactId>
   </dependency>
   <dependency>
       <groupId>org.apache.servicecomb</groupId>
       <artifactId>servicestage-environment</artifactId>
   </dependency>

   

   • 上述模块solution-basic包含常用的Java Chassis功能，例如配置中心模块和服务治理模块，方便一键式启用Java Chassis常见功能。

     <!--  配置中心模块  -->
     <dependency>
     <groupId>org.apache.servicecomb</groupId>
     <artifactId>config-cc</artifactId>
     </dependency>
     <!--  服务治理模块  -->
     <dependency>
     <groupId>org.apache.servicecomb</groupId>
     <artifactId>handler-governance</artifactId>
     </dependency>

   • 上述模块servicestage-environment包含以下依赖模块：

     <!--  注册发现模块  -->
     <dependency>
       <groupId>org.apache.servicecomb</groupId>
       <artifactId>registry-service-center</artifactId>
     </dependency>

   推荐使用Maven Dependency Management管理项目依赖的三方软件，在项目的“pom.xml”文件中引入：

   <dependencyManagement>
       <dependencies>
         <dependency>
           <groupId>org.apache.servicecomb</groupId>
           <artifactId>java-chassis-dependencies</artifactId>
           <version>${java-chassis.version}</version>
           <type>pom</type>
           <scope>import</scope>
         </dependency>
       </dependencies>  
   </dependencyManagement>

   如果您的项目中，已经包含了上述依赖，则不需要做任何处理。

   其中servicestage-environment软件包是可选的。这个软件包提供了环境变量映射的功能，依赖这个软件包以后，当您采用ServiceStage部署应用，不用手工修改注册中心地址、配置中心地址、项目名称等信息，会通过环境变量覆盖“microservice.yaml”中的默认配置，它包含“mapping.yaml”文件，在您自己的项目中增加“mapping.yaml”文件能够起到同样的效果。

   

   “mapping.yaml”在后续新版本可能会发生变化，以适配CSE最新的功能要求。如果期望后续升级新版本保持稳定而不是跟随CSE演进，您可以选择不依赖servicestage-environment，而是在您自己的项目中增加“mapping.yaml”。

   “microservice.yaml”和“mapping.yaml”文件，一般都存放于您当前项目根目录下的“/src/main/resources/”路径下。

   PAAS_CSE_ENDPOINT:
     - servicecomb.service.registry.address
     - servicecomb.config.client.serverUri
   PAAS_CSE_SC_ENDPOINT:
     - servicecomb.service.registry.address
   PAAS_CSE_CC_ENDPOINT:
     - servicecomb.config.client.serverUri
   PAAS_PROJECT_NAME:
     - servicecomb.credentials.project
   
   # CAS_APPLICATION_NAME:
   #  - servicecomb.service.application
   # CAS_COMPONENT_NAME:
   #  - servicecomb.service.name
   # CAS_INSTANCE_VERSION:
   #  - servicecomb.service.version

   solution-basic里面引入了常用的软件包，并且提供了默认的“microservice.yaml”文件。这个配置文件配置了常用的Handler和参数。其内容如下：

   # order of this configure file
   servicecomb-config-order: -100
   
   servicecomb:
   
   # handlers
     handler:
       chain:
         Provider:
           default: qps-flowcontrol-provider
         Consumer:
           default: qps-flowcontrol-consumer,loadbalance,fault-injection-consumer
   
   # loadbalance strategies
     references:
       version-rule: 0+
     loadbalance:
       retryEnabled: true
       retryOnNext: 1
       retryOnSame: 0
   
   # metrics and access log
     accesslog:
       enabled: true
     metrics:
       window_time: 60000
       invocation:
         latencyDistribution: 0,1,10,100,1000
       Consumer.invocation.slow:
         enabled: true
         msTime: 1000
       Provider.invocation.slow:
         enabled: true
         msTime: 1000
       publisher.defaultLog:
         enabled: true
         endpoints.client.detail.enabled: true

   “microservice.yaml”配置文件设置了servicecomb-config-order: -100 ， 表示配置文件的优先级很低（order越大，优先级越高，缺省为0），如果业务服务增加了同样的配置项，会覆盖这里的配置。

   

   “microservice.yaml”文件在后续新版本可能会发生变化，以适配CSE最新的功能要求。如果期望后续升级新版本保持稳定而不是跟随CSE演进，您可以考虑将配置项写到您自己的“microservice.yaml”文件中。

2. 配置微服务信息。

   在“microservice.yaml”增加微服务配置描述信息。如果项目中没有“microservice.yaml”，则创建一个新的文件。

   servicecomb:
     service:
       application: porter-application
       name: user-service
       version: 0.0.1
       registry:
         address: http://localhost:30100
         instance:
           watch: true
           properties:
             key: value
           initialStatus: UP
     config:
       client:
         serverUri: http://localhost:30103
         fileSource: provider.yaml
         firstPullRequired: false
         refresh_interval: 15000
         domainName: default
     kie: 
       serverUri: http://127.0.0.1:30110
       domainName: default
       enableLongPolling: true
       pollingWaitTime: 10
       firstPullRequired: false
       customLabel: public 
       customLabelValue: default
   

   其中，各个配置项说明见表1。

   表1 Java Chassis配置项

   配置项	含义	缺省值	是否必须配置	备注
   servicecomb.service.application	为当前微服务所属应用名称。	default	是	应用名称相同的微服务之间才可以相互发现。
   servicecomb.service.name	为当前微服务名称。	-	是	-
   servicecomb.service.version	服务版本号。	1.0.0.0	是	服务升级的时需要，防止契约注册失败。
   servicecomb.service.registry.address	注册地址。	-	是	-
   servicecomb.service.registry.instance.watch	是否监听微服务上下线变化。	true	否	集群地址使用“,”分隔。
   servicecomb.service.registry.instance.properties	微服务实例属性。	-	否	为map结构，支持设置多组数据。
   servicecomb.service.registry.instance.initialStatus	微服务注册时的状态。	UP	否	可设置UP(上线)、DOWN(下线)。
   servicecomb.config.client.serverUri	访问地址，格式为http(s)://{ip}:{port}，以“,”分隔多个地址。	-	是	此配置适用于配置中心为config-center。 当微服务引擎版本为1.x时，{port}取值为30103。 当微服务引擎版本为2.x时，{port}取值为30110。
   servicecomb.config.client.fileSource	内容为yaml的配置项列表，使用“,”分隔。	-	否	当配置中心类型为config-center时，如果配置中心以配置文件形式下发配置，必须填写fileSource予以解析配置，否则无法获取正确的配置内容。
   servicecomb.config.client.firstPullRequired	第一次拉取配置是否强制要求成功。如果为true，那么第一次连接配置中心失败后直接抛出异常，服务启动失败。默认为false。	-	否	此配置适用于配置中心为config-center。
   servicecomb.config.client.refresh_interval	配置中心config-center拉取配置循环时间，单位为毫秒。	15000	否	此配置适用于配置中心为config-center。
   servicecomb.config.client.domainName	项目名称。	default	否	此配置适用于配置中心为config-center。
   servicecomb.kie.serverUri	访问地址，格式为http(s)://{ip}:{port}，以“,”分隔多个地址。	-	是	此配置适用于配置中心为kie。 当微服务引擎版本为1.x时，{port}取值为30103。 当微服务引擎版本为2.x时，{port}取值为30110。
   servicecomb.kie.domainName	项目名称。	-	否	此配置适用于配置中心为kie。
   servicecomb.kie.enableLongPolling	是否开启长连接拉取配置。	true	否	此配置适用于配置中心为kie。
   servicecomb.kie.pollingWaitTime	长连接等待时长，单位为秒。	10	否	此配置适用于配置中心为kie。
   servicecomb.kie.firstPullRequired	第一次拉取配置是否强制要求成功。如果为true，那么第一次连接配置中心失败后直接抛出异常，服务启动失败。默认为false。	-	否	此配置适用于配置中心为kie。
   servicecomb.kie.customLabel	自定义配置标签键值。	-	否	使用kie配置中心时，如果使用自定义标签方式下发配置，需要配置customLabel、customLabelValue，微服务名、环境名、应用名标签仅支持单独适配。
   servicecomb.kie.customLabelValue	为自定义配置标签值	-	否	-

3. （可选）配置AK/SK。

   如果使用微服务引擎专业版，需要配置AK/SK；如果使用微服务引擎专享版，不需要配置AK/SK，可以跳过这个步骤。

   AK/SK在“microservice.yaml”中配置，ServiceComb默认提供明文配置，也支持用户自定义加密存储方案。AK/SK与项目名称获取方法，请参考获取AK/SK与项目名称。

   • 明文方法，在“microservice.yaml”文件中增加配置。

       servicecomb:  
         credentials:
           accessKey: AK #请输入已获取的AK值
           secretKey: SK #请输入已获取的SK值
           project: 项目名称 #请输入已获取的项目名称
           akskCustomCipher: default

   • 自定义实现，首先实现接口“org.apache.servicecomb.foundation.auth.Cipher”，里面有两个方法：
     • String name()

       这个是servicecomb.credentials.akskCustomCipher的名称定义，需要配置在配置文件中。

     • char[] decode(char[] encrypted)

       解密接口，对secretKey进行解密后使用。

     实现类需要声明为SPI，比如：

     package com.example
     public class MyCipher implements Cipher

     创建SPI配置文件，文件名称和路径为META-INF/service/org.apache.servicecomb.foundation.auth.Cipher，文件内容为：

     com.example.MyCipher

     然后在“microservice.yaml”文件中增加配置。

     servicecomb:
       credentials:
         accessKey: AK #请输入已获取的AK值 
         secretKey: SK  #请输入对应的加密后的SK
         project:  项目名称 #请输入已获取的项目名称
         akskCustomCipher: youciphername  #请输入实现类里面的name()方法返回的名称

   

   如果不想将AK/SK写入配置文件，也可以使用如下两种环境变量方法，具体操作请参考方法二。

   • 使用环境变量。操作系统环境变量名称不支持“.”，Java Chassis能够自动处理servicecomb_credentials_accessKey环境变量，将其映射到servicecomb.credentials.accessKey。
   • 增加“mapping.yaml”文件，自定义环境变量名称。在1介绍模块servicestage-environment的时候，已经用到了这个方法。

4. （可选）配置安全认证参数。

   使用微服务引擎专享版，并且启用了安全认证，需要配置，其他场景可以跳过这个步骤。

   微服务引擎开启了安全认证之后，所有调用的API都需要先获取token，才能调用，认证流程请参考服务中心RBAC说明。

   使用安全认证首先需要从微服务引擎获取用户名和密码，然后在配置文件中增加如下配置：

   servicecomb:
     credentials:
       rbac.enabled: true
       account:
         name: your account name # 从微服务引擎获取的用户名
         password: your password # 从微服务引擎获取的密码
         cipher: default #接口org.apache.servicecomb.foundation.auth.Cipher的实现类里面的name()方法返回的名称

   其中“cipher”指定了对“password”进行加密的算法名称，默认提供明文存储。通过自定义实现加密，如下所示：

   • 自定义实现，首先实现接口“org.apache.servicecomb.foundation.auth.Cipher”，里面的两个方法：
     • String name()

       这个是servicecomb.credentials.cipher的名称定义，需要配置在配置文件中。

     • char[] decode(char[] encrypted)

       解密接口，对secretKey进行解密后使用。

     实现类需要声明为SPI，比如：

     package com.example
     public class MyCipher implements Cipher

     创建SPI配置文件，文件名称和路径为META-INF/service/org.apache.servicecomb.foundation.auth.Cipher， 文件内容为：

     com.example.MyCipher

     然后在“microservice.yaml”文件中增加配置。

     servicecomb:
       credentials:
         rbac.enabled: true
         account:
           name: your account name 
           password: your password # 加密后的密码
           cipher: youciphername  #实现类里面的name()方法返回的名称

   

   • 明文存储无法保证安全， 建议您对密码进行加密存储。
   • 和配置AK/SK一样，也可以使用环境变量配置用户名和密码信息，请参考Java Chassis。
   • 使用微服务引擎专业版，不能使用watch功能，需要在配置文件里面关闭，否则会周期性打印错误日志。服务中心设置watch=false，配置中心设置refreshMode=1。

     servicecomb:
       service:
         application: porter-application
         name: user-service
         version: 0.0.1
         registry:
           address: http://localhost:30100
           instance:
             watch: false
       config:
         client:
           serverUri: http://localhost:30103
           refreshMode: 1