微服务治理平台微服务接入开发指南
服务治理Agent接入开发指南
综述
Java 应用可以通过挂载服务治理无侵入 Agent ，接入微服务治理平台，使用注册发现、路由、熔断、限流等治理能力。
Agent 支持 HTTP、Dubbo、gRPC 协议，兼容 Spring Cloud、Dubbo、Spring MVC 等开发框架。请参照以下步骤，完成接入。
开发或部署人员可以从微服务控制台快速接入页面下载服务治理Agent，默认建议使用相同release下的最新稳定版本。
兼容性说明
请检查 JDK、对应的开发框架版本兼容性。
JDK
JDK：支持v1.6、v1.7、v1.8三个版本及OpenJDK8，暂不支持国产化JDK。
SpringBoot + SpringCloud
| SpringBoot | SpringCloud | 支持情况 |
|---|---|---|
| 1.5.0 ~ 1.5.7 | Edgware(RELEASE ~ SR6 ) | 不支持 |
| 1.5.8 ~ 1.5.22 | Edgware( RELEASE ~ SR6 ) | 支持 |
| 2.0.0 ~ 2.0.9 | Finchley( RELEASE ~ SR4 ) | 支持 |
| 2.1.0 ~ 2.1.18 | Greenwich( RELEASE ~ SR6 ) | 支持 |
| 2.2.0 ~ 2.2.12 | Hoxton( RELEASE ~ SR9 ) | 支持 |
| 2.3.0 ~ 2.3.6 | Hoxton( RELEASE ~ SR9 ) | 支持 |
| 2.4.0 | Hoxton( RELEASE ~ SR9 ) | 支持 |
Spring MVC
| 大版本 | 小版本 | 支持情况 |
|---|---|---|
| 5.3.x | 1 | 支持 |
| 5.2.x.RELEASE | 0 ~ 11 | 支持 |
| 5.1.x.RELEASE | 0 ~ 20 | 支持 |
| 5.0.x.RELEASE | 0 ~ 20 | 支持 |
| 4.3.x.RELEASE | 0 ~ 30 | 支持 |
| 4.2.x.RELEASE | 0 ~ 9 | 支持 |
| 4.1.x.RELEASE | 0 ~ 9 | 支持 |
| 4.0.x.RELEASE | 0 ~ 9 | 支持 |
| 3.2.x.RELEASE | 3 ~ 18 | 支持 |
| 3.1.x.RELEASE | 0 ~ 4 | 不支持 |
| 3.0.x.RELEASE | 0 ~ 7 | 不支持 |
Dubbo
| 大版本 | 小版本 | 支持情况 |
|---|---|---|
| 2.7.x | 2.7.0 ~ 2.7.4.1 | 支持 |
| 2.6.x | 0 ~ 11 | 支持 |
| 2.5.x | 0 ~ 20 | 支持 |
| 2.1.0 ~ 2.1.18 | Greenwich( RELEASE ~ SR6 ) | 支持 |
| 2.2.0 ~ 2.2.12 | Hoxton( RELEASE ~ SR9 ) | 支持 |
| 2.3.0 ~ 2.3.6 | Hoxton( RELEASE ~ SR9 ) | 支持 |
| 2.4.0 | Hoxton( RELEASE ~ SR9 ) | 支持 |
服务治理快速接入
接入准备
Host配置
本地开发接入需要在云桌面配置host：
打开本地hosts文件（Windows默认地址：C:\Windows\System32\drivers\etc\hosts）
编辑hosts文件，增加以下host
#微服务治理平台host配置
#开发测试网--测试环境
192.102.21.193 console.sgp-pre.chinapost.com.cn
192.102.21.193 skiff-downloads.sgp-pre.chinapost.com.cn
192.102.21.193 prometheus.sgp-pre.chinapost.com.cn
192.102.21.193 prometheus-platform.sgp-pre.chinapost.com.cn
192.102.21.193 prometheus-nsf.sgp-pre.chinapost.com.cn
192.102.21.193 prometheus-nms.sgp-pre.chinapost.com.cn
192.102.21.193 prometheus-logagent.sgp-pre.chinapost.com.cn
192.102.21.193 prometheus-grafana.console.sgp-pre.chinapost.com.cn
192.102.21.193 prometheus-apm.sgp-pre.chinapost.com.cn
192.102.21.193 prometheus-apigw.sgp-pre.chinapost.com.cn
192.102.21.193 thanos.sgp-pre.chinapost.com.cn
192.102.21.193 platform-user-auth.sgp-pre.chinapost.com.cn
192.102.21.193 platform-service-auth.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-turbine.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-turbine-1.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-turbine-0.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-tunnel-server.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-tunnel-server-1.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-tunnel-server-0.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-server.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-registry.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-registry-1.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-registry-0.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-meta.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-config-service.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-config-portal.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-config-admin.sgp-pre.chinapost.com.cn
192.102.21.193 logseer.sgp-pre.chinapost.com.cn
192.102.21.193 gtxs-server.sgp-pre.chinapost.com.cn
192.102.21.193 apm-webserver.sgp-pre.chinapost.com.cn
192.102.21.193 apm-otel-collector.sgp-pre.chinapost.com.cn
192.102.21.193 apm-collector.sgp-pre.chinapost.com.cn
192.102.21.193 apigw-gportal.sgp-pre.chinapost.com.cn
192.102.21.193 api-plane.sgp-pre.chinapost.com.cn
192.102.21.193 sm-api-plane.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-nacos.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-nacos-0.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-nacos-1.sgp-pre.chinapost.com.cn
192.102.21.193 nsf-nacos-2.sgp-pre.chinapost.com.cn
#开发测试网--信创测试环境
192.102.28.21 console.sgpxc-test.chinapost.com.cn
192.102.28.21 skiff-downloads.sgpxc-test.chinapost.com.cn
192.102.28.21 prometheus.sgpxc-test.chinapost.com.cn
192.102.28.21 prometheus-platform.sgpxc-test.chinapost.com.cn
192.102.28.21 prometheus-nsf.sgpxc-test.chinapost.com.cn
192.102.28.21 prometheus-nms.sgpxc-test.chinapost.com.cn
192.102.28.21 prometheus-logagent.sgpxc-test.chinapost.com.cn
192.102.28.21 prometheus-grafana.console.sgpxc-test.chinapost.com.cn
192.102.28.21 prometheus-apm.sgpxc-test.chinapost.com.cn
192.102.28.21 prometheus-apigw.sgpxc-test.chinapost.com.cn
192.102.28.21 platform-user-auth.sgpxc-test.chinapost.com.cn
192.102.28.21 platform-service-auth.sgpxc-test.chinapost.com.cn
192.102.28.21 platform-audit.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-turbine.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-turbine-1.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-turbine-0.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-tunnel-server.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-tunnel-server-1.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-tunnel-server-0.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-server.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-registry.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-registry-1.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-registry-0.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-meta.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-config-service.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-config-portal.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-config-admin.sgpxc-test.chinapost.com.cn
192.102.28.21 logseer.sgpxc-test.chinapost.com.cn
192.102.28.21 gtxs-server.sgpxc-test.chinapost.com.cn
192.102.28.21 apm-webserver.sgpxc-test.chinapost.com.cn
192.102.28.21 apm-otel-collector.sgpxc-test.chinapost.com.cn
192.102.28.21 apm-collector.sgpxc-test.chinapost.com.cn
192.102.28.21 apigw-gportal.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-nacos.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-nacos-0.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-nacos-1.sgpxc-test.chinapost.com.cn
192.102.28.21 nsf-nacos-2.sgpxc-test.chinapost.com.cn检查服务治理组件连通性
在应用部署环境中，检查如下域名（以实际环境配置的域名为准）是否可以正常解析：
| 域名 | 组件 | 说明 |
|---|---|---|
| nsf-server.sgp-xxx.chinapost.com.cn | NSF Server | |
| nsf-config-portal.sgp-xxx.chiapost.com.cn | 配置中心 | |
| nsf-trubine-sgp-xxx.chinapost.com.cn | Turbine | |
| platform-service-auth.sgp-xxx.chinapost.com.cn | 服务认证 | 可选组件 |
| nsf-tunnel-server.sgp-xxx.chinapost.com.cn | 应用诊断 | |
| nsf-nacos.sgp-xxx.chinapost.com.cn | 注册中心（nacos） | |
| nsf-registry.sgp-xxx.chinapost.com.cn | 注册中心（Eureka） | |
| gtxs-server.sgp-xxx.chinapost.com.cn | 分布式事务 | 可选组件 |
| apm-otel-collector.sgp-xxx.chinapost.com.cn | APM监控 | |
| apm-collector.sgp-xxx.chinapost.com.cn | APM监控 | |
| apm-webserver.sgp-xxx.chinapost.com.cn | APM监控 |
准备好最新版本的Agent文件
微服务治理平台基于字节码增强技术，业务微服务接入微服务治理平台依赖nsf-boot.jar及对应配置文件(nsf.yml)，配置文件在微服务治理平台微服务模块的快速接入页面生成对应Agent配置文件，不同环境的配置文件需在不同环境（开发测试环境、UAT环境、生产环境）的微服务治理平台生成对应配置文件。
注：推荐配置文件命名，测试：nsf-test.yml；uat：nsf-uat.yml；生产：nsf-prod.yml。
Agent接入
Http服务接入
HTTP默认使用Nacos作为注册中心。
本地开发接入
HTTP默认使用Nacos作为注册中心。
添加认证
登录微服务治理平台，点击NSF（微服务模块），点击“认证管理” ，添加接入认证。如已有认证，此步骤可跳过。
知识库创建服务并发布
请填写正确的服务名和服务类型，如有多个计算集群，发布服务时可以选择发布到其中一个或多个。
服务名称：必填，需要全局唯一。
负责人：从微服务治理平台的用户中进行选取，该服务负责人会接受该服务的所有告警信息，非必填。
描述：用于对服务进行描述，非必填。
目标环境：如果在创建时已经明确该服务将发布在哪些环境中，则可以直接添加环境，服务创建后将会自动发布到指定环境中，在指定环境的“服务管理”模块中将看到该服务。
协议类型：支持http，dubbo
可访问类型：如果在“认证管理”添加了新的认证，默认会添加第一条认证
生成Agent配置文件
服务治理agent需要一份启动配置来进行初始化配置，默认文件格式为yml文件。开发或部署人员可以从微服务控制台开发工具页面生成并下载配置文件，放置在resource目录下。
相关参数说明如下：
| 参数 | 描述 | 举例 |
|---|---|---|
| 服务名称 | 服务名称，一般与Spring Boot的应用名称一致。选择在知识库中创建的服务。 | consumer |
| 服务类型 | 服务的协议类型 | http |
| 服务版本 | 服务的版本号 | v1 |
| 区域 | 服务所属的区域名称，默认为default | default |
| 所属应用 | 服务所属的应用名称，默认为default | default |
| 标签 | 可为服务版本实例添加标签 | key/value |
| 治理范围 | 指定工程项目下的 Package，平台会自动获取 Package 下所有的方法列表。用于配置熔断、限流规则，查看方法级监控。 | com.cpbf.boot.service.bussiness |
选择服务名、填写版本信息后点击“生成配置文件”，示例如下图所示：
下载配置文件。
默认生成的yml配置文件仅包含实例的基本信息，支持的完整参数说明如下，可按需添加。以下仅为示例，参数值以实际环境的为准。
nsf:
#配置协议版本
version: 2.0
#NSF server地址
nsfServer: http://nsf-server.sgp-pre.chinapost.com.cn
#启动类型
type: http
#服务基本信息
application:
name: consumer
version: v1
zone: default
group: default
#项目和环境标识
projectCode: sgp-ys
projectEnv: prod
#标签信息
tags:
- key: k1
value: v2
#服务鉴权配置
authority:
accessKey: b8d796495c5048dba79e9faf63b4017e
secretKey: d709efd734bb4a06a381cee85b57a246
#治理方法配置
manager:
patterns:
- className: com.cpbf.boot.service.bussiness
methods:
- name: serial
log:（可选）
#日志输出模式,默认user. all -都输出 服务治理agent自己处理自己的日志 user -统一输出到用户日志下
mode: user
#日志存放目录
path: /root/logs
#日志等级 默认info
level: debug
#影响日志文件的命名。默认为 yyyy-MM-dd 即每天一个，yyyy-MM-dd_HH 为每小时
timePattern: yyyy-MM-dd
#单个日志文件大小，默认1GB
maxFileSize: 1GB
#最大的存放时间，默认 30. 单位与timePattern设置有关，timePattern为每天，则存放历史以天为单位
maxHistory: 15
#所有日志文件最大占用空间 默认10GB
totalSizeCap: 2GB
引入Agent依赖
开发或部署人员可以从微服务控制台开发工具页面下载服务治理Agent。下载后，将Agent Jar 包放置到部署环境，如应用启动目录。
添加Java启动参数
添加 nsf-boot.jar 和配置文件后，开发或部署人员需要从微服务控制台开发工具页面生成启动参数，在 Java 应用的启动命令中添加该启动参数。
在应用启动命令中添加上一步生成的启动参数，启动应用，参数含义如下：
| 参数 | 描述 | 举例 |
|---|---|---|
| 全路径 | Agent Jar 包所在目录的绝对路径地址 | /root/nsf-boot.jar |
| 标识 | 用于区分同一主机上不同的配置文件 | consumer |
按上述配置则启动命令即为：
#java -javaagent: /root/nsf-boot.jar= consumer -jar consumer.jar
开发工具编译启动命令，在vm添加Java启动参数
验证接入
服务启动后，在NSF（微服务）->服务管理页面，选择对应服务，选择
「服务实例」Tab页，查看注册实例
容器云接入
添加认证
登录微服务治理平台，点击NSF（微服务模块），点击“认证管理” ，添加接入认证。如已有认证，此步骤可跳过。
知识库创建服务并发布
请填写正确的服务名和服务类型，如有多个计算集群，发布服务时可以选择发布到其中一个或多个。
服务名称：必填，需要全局唯一。
负责人：从微服务治理平台的用户中进行选取，该服务负责人会接受该服务的所有告警信息，非必填。
描述：用于对服务进行描述，非必填。
目标环境：如果在创建时已经明确该服务将发布在哪些环境中，则可以直接添加环境，服务创建后将会自动发布到指定环境中，在指定环境的“服务管理”模块中将看到该服务。
协议类型：支持http，dubbo
可访问类型：如果在“认证管理”添加了新的认证，默认会添加第一条认证
生成Agent配置文件
服务治理agent需要一份启动配置来进行初始化配置，默认文件格式为yml文件。开发或部署人员可以从微服务控制台开发工具页面生成并下载配置文件，放置在resource目录下。
相关参数说明如下：
| 参数 | 描述 | 举例 |
|---|---|---|
| 服务名称 | 服务名称，一般与Spring Boot的应用名称一致。选择在知识库中创建的服务。 | consumer |
| 服务类型 | 服务的协议类型 | http |
| 服务版本 | 服务的版本号 | v1 |
| 区域 | 服务所属的区域名称，默认为default | default |
| 所属应用 | 服务所属的应用名称，默认为default | default |
| 标签 | 可为服务版本实例添加标签 | key/value |
| 治理范围 | 指定工程项目下的 Package，平台会自动获取 Package 下所有的方法列表。用于配置熔断、限流规则，查看方法级监控。 | com.cpbf.boot.service.bussiness |
选择服务名、填写版本信息后点击“生成配置文件”，示例如下图所示：
下载配置文件。
默认生成的yml配置文件仅包含实例的基本信息，支持的完整参数说明如下，可按需添加。以下仅为示例，参数值以实际环境的为准。
nsf:
#配置协议版本
version: 2.0
#NSF server地址
nsfServer: http://nsf-server.sgp-pre.chinapost.com.cn
#启动类型
type: http
#服务基本信息
application:
name: consumer
version: v1
zone: default
group: default
#项目和环境标识
projectCode: sgp-ys
projectEnv: prod
#标签信息
tags:
- key: k1
value: v2
#服务鉴权配置
authority:
accessKey: b8d796495c5048dba79e9faf63b4017e
secretKey: d709efd734bb4a06a381cee85b57a246
#治理方法配置
manager:
patterns:
- className: com.cpbf.boot.service.bussiness
methods:
- name: serial
log:（可选）
#日志输出模式,默认user. all -都输出 服务治理agent自己处理自己的日志 user -统一输出到用户日志下
mode: user
#日志存放目录
path: /root/logs
#日志等级 默认info
level: debug
#影响日志文件的命名。默认为 yyyy-MM-dd 即每天一个，yyyy-MM-dd_HH 为每小时
timePattern: yyyy-MM-dd
#单个日志文件大小，默认1GB
maxFileSize: 1GB
#最大的存放时间，默认 30. 单位与timePattern设置有关，timePattern为每天，则存放历史以天为单位
maxHistory: 15
#所有日志文件最大占用空间 默认10GB
totalSizeCap: 2GB
Dockerfile编写
基于微服务治理平台基础镜像构建，示例Dockerfile如下
基础镜像说明：
| 环境 | 镜像 | Tag |
|---|---|---|
| x86 | 192.102.22.244/nsf/nsf-sw | v1.19 |
| arm64 | 192.102.22.244/nsf/nsf-sw | v1.19-arm64 |
添加Java启动参数
Agent依赖及配置文件的指定在dockerfile中配置
验证接入
服务启动后，在NSF（微服务）->服务管理页面，选择对应服务，选择
「服务实例」Tab页，查看注册实例
Dubbo服务接入
Dubbo使用Zookeeper作为注册中心。
本地开发接入
添加认证
登录微服务治理平台，点击NSF（微服务模块），点击“认证管理” ，添加接入认证。如已有认证，此步骤可跳过。
知识库创建服务并发布
请填写正确的服务名和服务类型，如有多个计算集群，发布服务时可以选择发布到其中一个或多个。
服务名称：必填，需要全局唯一。
负责人：从微服务治理平台的用户中进行选取，该服务负责人会接受该服务的所有告警信息，非必填。
描述：用于对服务进行描述，非必填。
目标环境：如果在创建时已经明确该服务将发布在哪些环境中，则可以直接添加环境，服务创建后将会自动发布到指定环境中，在指定环境的“服务管理”模块中将看到该服务。
协议类型：支持http，dubbo
可访问类型：如果在“认证管理”添加了新的认证，默认会添加第一条认证
生成Agent配置文件
服务治理agent需要一份启动配置来进行初始化配置，默认文件格式为yml文件。开发或部署人员可以从微服务控制台开发工具页面生成并下载配置文件，放置在resource目录下。
相关参数说明如下：
| 参数 | 描述 | 举例 |
|---|---|---|
| 服务名称 | 服务名称，一般与Dubbo的应用名称一致。选择在知识库中创建的服务。 | dubbowall |
| 服务类型 | 服务的协议类型 | Dubbo |
| 服务版本 | 服务的版本号 | v1 |
| 区域 | 服务所属的区域名称，默认为default | default |
| 所属应用 | 服务所属的应用名称，默认为default | default |
| 标签 | 可为服务版本实例添加标签 | key/value |
| 治理范围 | 指定工程项目下的 Package，平台会自动获取 Package 下所有的方法列表。用于配置熔断、限流规则，查看方法级监控。 | com.nsf.demo.stock.dubbo.* |
选择服务名、填写版本信息后点击“生成配置文件”，示例如下图所示：
下载配置文件。
默认生成的yml配置文件仅包含实例的基本信息，支持的完整参数说明如下，可按需添加。以下仅为示例，参数值以实际环境的为准。
nsf:
#配置协议版本
version: 2.0
#NSF server地址
nsfServer: http://nsf-server.sgp-pre.chinapost.com.cn
#启动类型
type: dubbo
#启动类(选填，只有当上述类型为dubbo时需要填启动类)
boot: com.nsf.demo.stock.dubbo.WallProvider
#服务基本信息
application:
name: dubbowall
version: v1
zone: default
group: default
#项目和环境标识
projectCode: sgp-ys
projectEnv: prod
#标签信息
tags:
- key: k1
value: v2
#服务鉴权配置
authority:
accessKey: b8d796495c5048dba79e9faf63b4017e
secretKey: d709efd734bb4a06a381cee85b57a246
#治理方法配置
manager:
patterns:
- className: com.nsf.demo.stock.dubbo.*
methods:
- name: testA
log:（可选）
#日志输出模式,默认user. all -都输出 nsf -agent自己处理自己的日志 user -统一输出到用户日志下
mode: user
#日志存放目录
path: /root/logs
#日志等级 默认info
level: debug
#影响日志文件的命名。默认为 yyyy-MM-dd 即每天一个，yyyy-MM-dd_HH 为每小时
timePattern: yyyy-MM-dd
#单个日志文件大小，默认1GB
maxFileSize: 1GB
#最大的存放时间，默认 30. 单位与timePattern设置有关，timePattern为每天，则存放历史以天为单位
maxHistory: 15
#所有日志文件最大占用空间 默认10GB
totalSizeCap: 2GB
引入Agent依赖
开发或部署人员可以从微服务控制台开发工具页面下载服务治理Agent。下载后，将Agent Jar 包放置到部署环境，如应用启动目录。
添加Java启动参数
添加 nsf-boot.jar 和配置文件后，开发或部署人员需要从NSF控制台开发工具页面生成启动参数，在 Java 应用的启动命令中添加该启动参数。
在应用启动命令中添加上一步生成的启动参数，启动应用，参数含义如下：
| 参数 | 描述 | 举例 |
|---|---|---|
| 全路径 | Agent Jar 包所在目录的绝对路径地址 | /root/nsf-boot.jar |
| 标识 | 用于区分同一主机上不同的配置文件 | dubbowall |
按上述配置则启动命令即为：
#java -javaagent:/root/nsf-boot.jar=dubbowall -Dnsf.zk=zookeeper://[zkIp]:[zkPort] -jar dubbowall.jar
开发工具编译启动命令，在vm添加Java启动参数
验证接入
通过控制台实例列表，查看服务注册实例。服务实例注册通常需要 1-3 分钟。
备注：使用@Reference(version = "1.0.0",check = true, protocol = "dubbo,hessian", loadbalance = "random",cluster = "nsf")，注意添加cluster = "nsf"。
容器云接入
添加认证
登录微服务治理平台，点击NSF（微服务模块），点击“认证管理” ，添加接入认证。如已有认证，此步骤可跳过。
知识库创建服务并发布
请填写正确的服务名和服务类型，如有多个计算集群，发布服务时可以选择发布到其中一个或多个。
服务名称：必填，需要全局唯一。
负责人：从微服务治理平台的用户中进行选取，该服务负责人会接受该服务的所有告警信息，非必填。
描述：用于对服务进行描述，非必填。
目标环境：如果在创建时已经明确该服务将发布在哪些环境中，则可以直接添加环境，服务创建后将会自动发布到指定环境中，在指定环境的“服务管理”模块中将看到该服务。
协议类型：支持http，dubbo
可访问类型：如果在“认证管理”添加了新的认证，默认会添加第一条认证
生成Agent配置文件
服务治理agent需要一份启动配置来进行初始化配置，默认文件格式为yml文件。开发或部署人员可以从微服务控制台开发工具页面生成并下载配置文件，放置在resource目录下。
相关参数说明如下：
| 参数 | 描述 | 举例 |
|---|---|---|
| 服务名称 | 服务名称，一般与Dubbo的应用名称一致。选择在知识库中创建的服务。 | dubbowall |
| 服务类型 | 服务的协议类型 | Dubbo |
| 服务版本 | 服务的版本号 | v1 |
| 区域 | 服务所属的区域名称，默认为default | default |
| 所属应用 | 服务所属的应用名称，默认为default | default |
| 标签 | 可为服务版本实例添加标签 | key/value |
| 治理范围 | 指定工程项目下的 Package，平台会自动获取 Package 下所有的方法列表。用于配置熔断、限流规则，查看方法级监控。 | com.nsf.demo.stock.dubbo.* |
选择服务名、填写版本信息后点击“生成配置文件”，示例如下图所示：
下载配置文件。
默认生成的yml配置文件仅包含实例的基本信息，支持的完整参数说明如下，可按需添加。以下仅为示例，参数值以实际环境的为准。
nsf:
#配置协议版本
version: 2.0
#NSF server地址
nsfServer: http://nsf-server.sgp-pre.chinapost.com.cn
#启动类型
type: dubbo
#启动类(选填，只有当上述类型为dubbo时需要填启动类)
boot: com.nsf.demo.stock.dubbo.WallProvider
#服务基本信息
application:
name: dubbowall
version: v1
zone: default
group: default
#项目和环境标识
projectCode: sgp-ys
projectEnv: prod
#标签信息
tags:
- key: k1
value: v2
#服务鉴权配置
authority:
accessKey: b8d796495c5048dba79e9faf63b4017e
secretKey: d709efd734bb4a06a381cee85b57a246
#治理方法配置
manager:
patterns:
- className: com.nsf.demo.stock.dubbo.*
methods:
- name: testA
log:（可选）
#日志输出模式,默认user. all -都输出 nsf -agent自己处理自己的日志 user -统一输出到用户日志下
mode: user
#日志存放目录
path: /root/logs
#日志等级 默认info
level: debug
#影响日志文件的命名。默认为 yyyy-MM-dd 即每天一个，yyyy-MM-dd_HH 为每小时
timePattern: yyyy-MM-dd
#单个日志文件大小，默认1GB
maxFileSize: 1GB
#最大的存放时间，默认 30. 单位与timePattern设置有关，timePattern为每天，则存放历史以天为单位
maxHistory: 15
#所有日志文件最大占用空间 默认10GB
totalSizeCap: 2GB
Dockerfile编写
基于微服务治理平台基础镜像构建，示例Dockerfile如下
基础镜像说明：
| 环境 | 镜像 | Tag |
|---|---|---|
| x86 | 192.102.22.244/nsf/nsf-sw | v1.19 |
| arm64 | 192.102.22.244/nsf/nsf-sw | v1.19-arm64 |
添加Java启动参数
Agent依赖及配置文件的指定在dockerfile中配置
验证接入
通过控制台实例列表，查看服务注册实例。服务实例注册通常需要 1-3 分钟。
备注：使用@Reference(version = "1.0.0",check = true, protocol = "dubbo,hessian", loadbalance = "random",cluster = "nsf")，注意添加cluster = "nsf"。
如何使用RestTemplate客户端
通过服务治理Agent起来的应用里自带了一个RestTemplate客户端，该客户端进行了增强处理，提供了服务路由、参数分流、负载均衡、服务鉴权和认证等高级功能；
用户在实际的项目里可以通过如下方式进行定义和使用：
首先是定义一个RestTemplate的bean对象，该bean实际在应用启动会被服务治理定义的RestTemplate覆盖，主要是为了让代码正常运行（在不通过Agent启动的时候也能启动）：
@Configuration
public class RestTemplateConfiguration {
@Bean
public RestTemplate restTemplate() {
return new RestTemplate();
}
}
其次，在需要使用HTTP客户端的地方直接通过Autowired自动关联之前定义的RestTemplate使用即可：
@Autowired
RestTemplate nsfRestTemplate;
@RequestMapping(value = "/nsf-client", method = RequestMethod.GET, produces = "application/json")
public String tstNsfClient(@RequestParam(required = false) String name) {
return nsfRestTemplate.getForObject("http://test-dest-srv", String.class);
}
如果希望使用不被增强的RestTemplate客户端，比如需要访问一个外部网站，使用bean的@Qualifier注解方式，参考代码如下：
首先仍然是定义一个RestTemplate，但是需要预先定义好bean name：
@Configuration
public class UserRestTemplateConfiguration {
@Bean(name = "userClient") // <--- 关键代码
public RestTemplate restTemplate() {
return new RestTemplate();
}
}
其次在用的时候，通过@Qualifier注解进行区分即可：
@Qualifier("userClient") // <--- 关键代码
@Autowired
RestTemplate userRestTemplate;
@RequestMapping(value = "/user-client", method = RequestMethod.GET, produces = "application/json")
public String tstUserClient(@RequestParam(required = false) String name) {
return userRestTemplate.getForObject("http://www.baidu.com", String.class);
}
如何使用限流
对请求进⾏流控，防⽌请求激增导致服务提供方资源被过多消耗。
支持方法级别限流，根据 QPS (Queries Per Second，即查询量/秒) 、Thread设置限流阈值。
前置条件：
1．需要在服务的 Agent 配置文件中指定工程项目下的 Package，平台会自动获取 Package 下所有的方法列表。通过快速接入 > 生成配置文件 > Package 指定。
- 点击创建限流规则，填写参数。
| 参数 | 说明 |
|---|---|
| 规则名称 | 治理规则名称。 |
| 服务名称 | 选择某个提供方服务。 |
| 规则范围 | 选择当前治理规则所生效的服务版本、类、方法。 |
| 限流维度 | 可针对两种维度进行限流，QPS 或 Thread。 |
| 阈值 | 当限流维度选择QPS 时，需要填写时间单位和请求数阈值；一旦目标限流方法的被调用次数达到该阈值，即触发限流规则。 |
| 队列长度 | 达到限流阈值时，保留一个队列作为缓冲区。 |
| 超时时间 | 在队列中的服务超过超时时间没有被处理，按限流处理方式返回。 |
| 阻断返回 | 触发治理规则后，支持不同处理方式。返回异常、返回固定值、Fallback方法（调用用户自定义 Fallback 方法）。 |
创建完成后，治理规则默认是停用状态。可以手动设置停用或启用；停用时规则不生效。
支持修改/删除规则。
如何使用熔断
服务提供方因为某种原因导致服务不可用或响应过慢时，调用方服务为了保证自己整体服务的可用性，不再继续调用目标服务，直接返回。当目标服务恢复后，调用方服务会恢复调用。
支持对方法配置熔断，当方法的调用达到熔断阈值时，将触发熔断。触发熔断后，可以返回异常、固定返回值、或者调用 Fallback 方法。
前置条件：
1．需要在服务的 Agent 配置文件中指定工程项目下的 Package，平台会自动获取 Package 下所有的方法列表。通过快速接入 > 生成配置文件 > Package 指定。
| 参数 | 说明 |
|---|---|
| 规则名称 | 治理规则名称。 |
| 服务名称 | 选择某个提供方服务。 |
| 规则范围 | 选择当前治理规则所生效的服务版本、类、方法。 |
| 熔断方式 | 分为手工熔断和自动熔断。 |
| 熔断最小调用 | 当在指定的时间区间内，请求数量达到最小调用次数，才会进行熔断判断。 |
| 超时阈值 | 当请求响应时间超出该阈值，则计入熔断错误数统计。 |
| 错误率 | 超过超时阈值和异常都认为是调用错误，当统计窗口内，错误调用除以总调用数大于错误率时，将触发熔断。 |
| 熔断恢复窗口 | 熔断发生后，经过该窗口期，会进行恢复尝试。 |
| 阻断返回 | 触发熔断规则后，支持不同处理方式。返回异常、返回值、Fallback方法（调用用户自定义 Fallback 方法）。 |
- 点击创建熔断规则，填写参数。
创建完成后，治理规则默认是停用状态。可以手动设置停用或启用；停用时规则不生效。
支持修改/删除规则。
如何使用http类型的容错
为了保护服务消费方，调用外部服务失败后，进行错误重试处理。支持指定同实例、不同实例重试次数。
前置条件：
1．如果需要对指定版本的消费方实例配置容错，实例接入时需要在Agent 配置文件中指定版本。
- 点击创建容错规则，填写参数。
| 参数 | 说明 |
|---|---|
| 规则名称 | 治理规则名称。 |
| 当前服务 | 某个消费方服务。 |
| 服务版本 | 选择当前治理规则所生效的服务版本。 |
| 容错范围 | 选择容错规则针对的提供方服务。支持全部。 |
| 接口 | 提供方服务的某个接口 |
| 容错方式 | Failover：在不同提供方服务实例上重新尝试建立连接；需设置新实例重试次数。 Failfast：不再重新尝试建立连接，即请求失败时会立即返回失败结果。 Failback：在同一个提供方实例上重新尝试建立连接；需设置同实例重试次数。 自定义：在同一个提供方实例上重新尝试建立连接。失败后，尝试在不同提供方服务实例上重新尝试建立连接。 |
| 同实例重试次数 | 在同一个提供方服务实例进行重试的次数。 |
| 新实例重试次数 | 在不同提供方服务实例进行重试的次数。 |
创建完成后，治理规则默认是停用状态。可以手动设置停用或启用；停用时规则不生效。
支持修改/删除规则。
如何使用应用诊断
服务治理agent整合了arthas来实现应用诊断的能力，具体的诊断方式参考其命令文档 https://alibaba.github.io/arthas/advanced-use.html 在诊断结束时及时使用shutdown命令来关闭，减少arthas对运行中的程序的影响。
arthas能执行诊断少不了一些jdk提供的工具，所以用户程序在打包成镜像时务必保证镜像中包含了jdk提供的工具而不是一个简单的jre， 并且arthas需要使用lsof命令来检测相应端口是否开启，确保命令存在。
如何feign客户端
feign是一个声明式的http调用工具库，与spring整合需要加入如下依赖，引入注解@EnableFeignClients
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-openfeign</artifactId>
<version>2.1.3.RELEASE</version>
</dependency>
agent能根据classpath中是否有feign的依赖来动态支持 服务间调用使用服务名即可，即@FeignClient(name = "nsf-demo-stock-provider")
@FeignClient(name = "nsf-demo-stock-provider",fallbackFactory = RemoteCallFallBack.class)
public interface RemoteCallService {
@RequestMapping(method = RequestMethod.GET, value = "/hello")
String hello(@RequestParam("name") String name);
}
//如果要调用第三方服务，使用url参数，直接走域名调用
@FeignClient(name = "external-service", url = "http://www.netease.com/xxx",fallbackFactory = RemoteCallFallBack.class)
public interface ExternalCallService {
@RequestMapping(method = RequestMethod.GET, value = "/hello")
String hello(@RequestParam("name") String name);
}
常见问题
如何确认是否应用自身问题
如果出现带Agent导致应用本身无法正常启动，请先尝试去除Agent启动看应用是否能够正常启动；
参考“2.兼容性说明”中检查兼容信息；
检查启动参数。
Agent服务注册失败
搜索agent日志，发现project not found by projectCode, 问题为agent配置文件中项目标识错误。
搜索agent日志，发现project not found by ak and sk，检查认证管理中的ak,sk是否和agent配置文件中的一致。
搜索agent日志，发现projectCode doesn't match akey and skey，同上
搜索agent日志，发现micro service not found by service name. NSF 控制台中不存在实例对应的服务，同时NSF-server这里没有开启自动创建，开启服务自动创建重启注册即可。
搜索agent日志，发现Auto create failed，服务自动创建失败，此时需要检查NSF-server日志，一般错误为:
向配置中心创建App失败
向NSF-meta创建服务失败
向service-auth创建服务权限失败
代码中的依赖和agent冲突。
本地开发时nsf.yml文件修改后不生效
nsf-agent.jar所在目录下，应用启动后会生成properties 和 json缓存文件，本地开发时，会有同服务会有注册到不同项目的场景，这时直接修改nsf.yml的内容后，启动发现不生效，实际加载的还是缓存的数据。
解决办法：删除缓存文件。
Agent启动参数中，配置文件的优先级和默认启动顺序
优先级从高到低的顺序为：服务端下发-环境变量-配置文件-默认值。
如启动命令：
# java -javaagent:/Users/sample/Works/repo/builds/nsf-boot.jar=myconfig -jar demo.jar
以上myconfig指定的是对应的配置文件名称，agent在启动的时候首先会从agent所在的目录下寻找myconfig.yml配置文件，如果找到了则使用这个配置；
否则从目标应用的resource目录下寻找，如果找到了则使用；
否则使用resource目录下的nsf.yml文件，如果存在的话；
如果都找不到且nsf.yml文件不存在的话，则agent加载失败，但不影响目标应用程序启动。
服务拓扑显示异常问题排查
如果服务拓扑显示异常，可以从以下3点进行问题排查：
接口是否已经发生了调用。因为服务拓扑关系是动态生成，只要发生调用，服务管理中有依赖关系，就能生成拓扑关系，如果没有发生任何调用，拓扑关系将不会生成。
是否是使用了Httpclient来进行服务调用。 httpclient方式不支持生成拓扑调用。
服务中调用域名没有使用大写。
APM快速接入
本地开发接入
产品建立
登录微服务治理平台，点击APM模块，建立产品并关联项目
探针下载
登录微服务治理平台，下载依赖，放置自定义目录
APM信息配置
配置APM所需配置信息
增加 Java 启动参数
修改配置文件后，需要在 Java 服务中添加启动参数：
-javaagent:<agent_home>/skywalking-napm-bin-8.10.0-latest/agent/skywalking-agent.jar -Dskywalking_config=<agent_home>/skywalking-napm-bin-8.10.0-latest/agent/config/agent.config
在vm中添加启动参数
重启服务
重启服务，服务启动后，在应用监控模块可以看到全链路数据展示的变化。
容器云接入
产品建立
登录微服务治理平台，点击APM模块，建立产品并关联项目
Dockerfile编写
基于微服务治理平台基础镜像构建，示例Dockerfile如下
基础镜像说明：
| 环境 | 镜像 | Tag |
|---|---|---|
| x86 | 192.102.22.244/nsf/nsf-sw | v1.19 |
| arm64 | 192.102.22.244/nsf/nsf-sw | v1.19-arm64 |
APM信息配置
在Dockerfile中配置APM所需配置信息
增加 Java 启动参数
APM依赖及配置文件的指定在dockerfile中配置
重启服务
重启服务，服务启动后，在应用监控模块可以看到全链路数据展示的变化。
链路日志使用
配置APM如下所示
业务工程日志配置
Pom文件加入依赖坐标
<dependency>
<groupId>org.apache.skywalking</groupId>
<artifactId>apm-toolkit-logback-1.x</artifactId>
<version>8.0.8</version>
</dependency>
Logback配置文件中添加节点
- 程序控制台输出效果
带有 TID 表示配置成功
微服务平台链路日志的使用
- 创建采集任务
- 通过链路id查询日志
