# yx-cloud

**Repository Path**: wp-1013/yx-cloud

## Basic Information

- **Project Name**: yx-cloud
- **Description**: yx-cloud，基于SpringBoot, SpringCloud Alibaba等框架的分布式架构应用
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2024-06-03
- **Last Updated**: 2024-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# yx-cloud分布式架构应用

## 简介

yx-cloud是基于SpringBoot, SpringCloud Alibaba等框架的分布式架构应用。应用的技术包含但不限于：

| 名称 | 说明 |
| -- | -- |
| SpringBoot | 基础框架 |
| Nacos | 服务注册，服务发现，配置中心 |
| SpringCloud Dubbo | 远程过程调用 |
| SpringCloud Gateway | Gateway网关 |
| SpringSecurity | 认证授权 |
| JWT | JWT Token |
| MySQL | 关系型数据库 |
| Druid | 数据连接池 |
| MyBatis | 可选MyBatis |
| MyBatis-plus | 可选MyBatis-plus |
| Spring Data JPA | 可选JPA |
| Redis | 缓存 |
| Sentinel | 服务熔断和限流 |
| Seata | 分布式事务 |
| slf4j&Logback | 日志记录 |
| SkyWalking | 链路追踪 |
| lombok | Getter&Setter生成 |
| MapStruct | JavaBean对象映射与拷贝 |
| Swagger&Knife4j | 接口文档 |
| SpringBoot Actuator | 应用服务监控 |
| LPG | Loki + Promtail + Grafana轻量级日志系统 |

## yx-cloud整体模块架构

```text
yx-cloud
    yx-common[通用模块]
        yx-common-core[核心基础代码]
        yx-common-data[数据访问模块]
            yx-common-starter-jdbc[jdbc相关类]
            yx-common-starter-mybatis[MyBatis和MyBatis-plus的封装]
            yx-common-starter-jpa[Spring Data JPA的封装]
            yx-common-starter-redis[Redis缓存]
        yx-common-log[日志模块]
            yx-common-starter-log[系统操作日志，日志注解]
            yx-common-starter-mdc[MDC模块，异步任务加入MDC上下文信息]
        yx-common-message[消息模块]
            yx-common-starter-mail[邮件模块]
        yx-common-security[安全模块]
            yx-common-starter-security[SpringSecurity基础模块]
            yx-common-starter-security-webmvc[SpringSecurity WebMvc版本]
            yx-common-starter-security-webflux[SpringSecurity WebFlux版本]
        yx-common-web[Web模块]
            yx-common-starter-web[Web模块，全局异常、拦截器等]
            yx-common-starter-webflux[WebFlux模块]
        yx-common-starter-knife4j[Knife4j接口文档]
        yx-common-starter-i18n[国际化通用模块]
        yx-common-starter-actuator[Spring boot Actuator监控模块]
        yx-common-starter-sentinel[Sentinel通用模块]
    yx-micro-service[微服务模块]
        yx-app[yx-app应用服务模块]
        yx-sys[yx-sys系统服务模块]
            yx-sys-log-remote-api[系统日志远程服务接口]
            yx-sys-i18n-remote-api[国际化消息远程服务接口]
            yx-sys-config-remote-api[系统配置远程服务接口]
            yx-sys-service[系统服务，端口8180]
        yx-user[yx-user用户服务模块]
            yx-user-remote-api[用户远程服务接口]
            yx-user-service[用户服务，端口8181]
            yx-user-consumer[用户服务消费者，端口18181]
        yx-permission[yx-permission权限服务模块]
            yx-permission-remote-api[权限远程服务接口]
            yx-permission-service[权限服务，端口8182]
    yx-application[yx-application主应用模块]
    yx-application-gateway[yx-application-gateway统一网关模块，端口9190]
    yx-application-doc[yx-application-doc文档聚合模块，端口9191]
    yx-application-admin[yx-application-admin服务管理和监控模块，端口9192]
    yx-tool[工具模块]
        yx-tool-message-generator[国际化消息SQL生成器模块]
        yx-tool-config-generator[系统配置SQL生成器模块]
```

## 目录说明

`config`目录用于存储Nacos导出的配置文件。

`db`目录用于存储SQL文件或DB相关设计文档，本项目的数据库设计及生成的SQL脚本均在此目录中，各微服务对应独立的SQL文件。

`docker`目录用于存储Docker相关文件。

`shell`目录用于存储Shell脚本文件。

## 端口分配

微服务端口从`8180`开始分配，yx-application-gateway, yx-application-doc, yx-application-admin等端口从`9190`
开始分配，微服务的消费示例服务端口在微服务提供方端口前加1，如`18180`。

## 重要说明

### 单体架构应用

yx-erp-api和yx-erp-multi-ds-api为前期的单体架构应用，其依赖的yx-common-starter-web模块在分布式模式下添加了spring-cloud-starter-dubbo依赖，在启动这两个单体架构应用时将报错，此项目暂不删除这两个单体架构应用，便于后期有需要时快速改造。

如果专注于分布式架构的开发，则可直接忽略这两个项目。

2022-12-08已移除单体架构应用，可通过标签yx-cloud-single-application找回。

### yaml配置

所有服务（含yx-application-gateway, yx-application-doc,
yx-application-admin）均注册到Nacos注册中心，除了spring相关的部分配置，Nacos，Dubbo和Sentinel相关的基础配置，其他配置均在Nacos配置中心，详细配置参考`config`
目录中的yml文件。

```yaml
# bootstrap.yml中的spring相关的配置
spring:
  application:
    name: yx-application-gateway
  profiles:
    active: dev
  main:
    allow-circular-references: true
```

### 模块basePackage

项目模块basePackage详细到具体的模块名（如yx-common-starter-web的basePackage为`cn.yx.common.web`
），模块内如有configuration，handler，component需要在`resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`
文件中声明，以便在其他应用中完成自动配置和自动注入，文件示例内容如下：

```text
cn.yx.common.web.configuration.LoggerInterceptorConfiguration
cn.yx.common.web.handler.GlobalExceptionHandler
cn.yx.common.web.advice.AppResponseBodyAdvice
```

且configuration类不需要使用`@EnableAutoConfiguration`注解，否则会报`A circular @Import has been detected`错误。

### 使用lombok

本项目推荐使用lombok，推荐的注解如下示例：

```java
@Data
@NoArgsConstructor
@AllArgsConstructor
@EqualsAndHashCode(callSuper = true)
public class UserVo extends BaseVo {

}
```

如果使用`@Builder`注解，在属性设置默认值的情况下，需要给属性增加`@Builder.Default`注解。

根据实际情况使用constructor注解，如ResponseVo不需要自动生成构造方法：

```java
@Data
@EqualsAndHashCode(callSuper = true)
public class ResponseVo<T> extends BaseVo {

    private Integer code;
    private String transId;
    private String message;
    private T data;

    private ResponseVo() {}

    private ResponseVo(Integer code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }
}
```

可自行编写getter/setter，constructor，equals，hashcode等方法实现自定义逻辑。

### 使用MapStruct

本项目推荐使用MapStruct，并提供了四个基础接口完成DTO与DO，DTO与VO，DTO与DTO，Cond与Cond之间的转换：

`cn.yx.common.core.mapping.CondMapping`完成Cond条件对象间的转换，如客户端Cond条件对象转为服务端Cond条件对象；

`cn.yx.common.core.mapping.DtoDoMapping`完成DTO对象与DO对象间的转换；

`cn.yx.common.core.mapping.DtoMapping`完成DTO对象间的转换，如客户端DTO对象转为服务端DTO对象；

`cn.yx.common.core.mapping.DtoVoMapping`完成DTO对象与VO对象间的转换。

### annotationProcessorPaths

由于使用了MapStruct，在yx-cloud模块的pom.xml中需配置`annotationProcessorPaths`，当配置了`annotationProcessorPaths`
，也需要把lombok配置到`annotationProcessorPaths`：

```xml
<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>${maven-compiler-plugin.version}</version>
                <configuration>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
                    <encoding>${encoding}</encoding>
                    <annotationProcessorPaths>
                        <!-- 注意lombok在MapStruct前面 -->
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>${lombok.version}</version>
                        </path>
                        <path>
                            <groupId>org.mapstruct</groupId>
                            <artifactId>mapstruct-processor</artifactId>
                            <version>${mapstruct.version}</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>${maven-surefire.version}</version>
                <configuration>
                    <skipTests>true</skipTests>
                </configuration>
            </plugin>
        </plugins>
    </pluginManagement>
</build>
```

### yx-application-gateway网关模块

SpringCloud Gateway基于WebFlux，与spring-boot-starter-web模块有冲突，故yx-application-gateway模块不可引用spring-boot-starter-web模块。

在yx-application-gateway模块中整合Knife4实现文档聚合可参考 <https://doc.xiaominfo.com/docs/action/springcloud-gateway> 。

由于yx-cloud服务调用使用了Dubbo，yx-application-gateway模块按上述文档整合Knife4j有异常，故单独新增文档聚合模块yx-application-doc。

yx-application-gateway引用了yx-common-starter-i18n模块，而yx-common-starter-i18n模块引用了yx-common-starter-redis模块，故yx-common-starter-redis模块中不再引用`spring-boot-starter-web`
，而是单独指定引用`spring-context`，`spring-boot-autoconfigure`。

### yx-application-doc接口文档模块

yx-application-doc文档聚合模块使用了knife4j-aggregation-spring-boot-starter，方便与Nacos整合完成文档聚合。knife4j-aggregation-spring-boot-starter目前最新版本为2.0.9版本，knife4j-spring-boot-starter版本与其保持一致。

### yx-common-starter-actuator模块

spring-boot-starter-actuator与knife4j存在冲突，导致项目启动报错，故单独增加了yx-common-starter-actuator模块，该模块中的`WebMvcEndpointConfiguration`
类解决了冲突，所有服务模块均可引用yx-common-starter-actuator模块。

### yx-common-starter-log日志模块

yx-common-starter-log日志模块引用了yx-sys-log-remote-api系统日志远程服务模块，使用Dubbo远程调用系统日志服务。该模块的SysLogAspect调用了`AsyncSysLogService`，`AsyncSysLogService`
异步调用Dubbo服务。引用yx-common-starter-log的微服务模块的Application启动类需要添加`@EnableAsync`注解。

### yx-common-starter-web模块

yx-common-starter-web模块引用了yx-common-starter-i18n国际化通用模块，在`AppResponseBodyAdvice`中完成国际化消息的处理。

### yx-common-starter-redis模块

yx-common-starter-redis模块中扩展了自定义的`MyRedisCacheManager`，在使用`@Cacheable`
等注解时，可在cacheNames中指定缓存失效时间（详细规则可查看`MyRedisCacheManager`类注释），如：

```java
@Override
@Cacheable(key = "#id", cacheNames = "yx-user#24H", unless="#result == null")
public UserAccountDto getById(Long id) {
    log.info("getById");
    UserAccountDto userAccountDto = new UserAccountDto();
    userAccountDto.setId(id);
    userAccountDto.setPhone("18888888888");
    return userAccountDto;
}
```

如果未指定失效时间，则永久有效。

### yx-common-starter-security相关模块

yx-common-starter-security是SpringSecurity和JWT的基础模块，yx-common-starter-security-webmvc和yx-common-starter-security-webflux分别是WebMvc模式和WebFlux模式下认证和授权的自定义实现。

可在服务模块中引用yx-common-starter-security-webmvc模块，而在yx-common-starter-gateway模块中引用yx-common-starter-security-webflux模块。

### Redis配置与监控

微服务模块中引用了yx-common-starter-redis模块并配置了Redis连接，spring-boot-starter-actuator会连接并监控Redis，若配置的Redis的host地址为具体的IP（如192.168.139.130），则需要修改redis.conf配置文件中的protected-mode为no，并把IP地址配置到bind部分，如`bind 127.0.0.1 192.168.139.130`
，启动Redis时指定配置文件，Windows系统下的启动命令如下：

```shell
redis-server.exe ./redis.conf
```

### @SysLog注解

在业务模块Controller类方法添加`@SysLog`注解，可指定方法日志行为，如是否启用日志输出，是否输出请求数据，是否输出响应数据，是否保存到数据库等。

即使未启用日志输出，当响应有异常时，也会默认打印ERROR日志。

### ResponseVo国际化消息

yx-common-starter-web模块中的`AppResponseBodyAdvice`
统一处理ResponseVo返回，对message进行国际化处理，`ResponseVo.setMessageParams`可设置消息参数，如：`已创建品牌{0}`。

对各模块的Controller，GlobalExceptionHandler，消费者端URL资源进行熔断降级的Handler中的RespnoseVo返回有效。

对yx-application-gateway模块`GatewayExceptionHandler`
中的ResponseVo返回无效，故yx-application-gateway模块引用了yx-common-starter-i18n国际化通用模块。

对yx-common-starter-sentinel模块`SentinelBlockExceptionHandler`
中的ResponseVo返回无效，可优化`SentinelBlockExceptionHandler`，在此类中抛出异常交由`GlobalExceptionHandler`统一处理。

### 异常和ResponseVo国际化消息处理

在`CommonException`和`AppException`抛出的异常及`ResponseVo`的返回消息均支持国际化消息，并可指定消息参数。

1、直接抛出异常消息和返回消息：

```java
throw new CommonException("文件创建异常", e);
throw new CommonException("{0}文件创建异常", new String[]{fileName}, e);
return ResponseVo.fail("文件创建异常", null);
return ResponseVo.fail("{0}文件创建异常", new String[]{fileName}, null);
```

2、使用国际化messageKey返回消息：

```java
throw new CommonException("cn.yx.common.core.createNewFileError", e);
throw new CommonException("cn.yx.common.core.createNewFileError", new String[]{fileName}, e);
return ResponseVo.fail("cn.yx.common.core.createNewFileError", null);
return ResponseVo.fail("cn.yx.common.core.createNewFileError", new String[]{fileName}, null);
```

`cn.yx.common.core.createNewFileError`为messageKey，其对应的中文消息为`{0}文件创建异常`。

### SpringBoot Validation国际化

SpringBoot
Validation国际化，在模块Resources目录中新增ValidationMessages.properties，ValidationMessages_zh_CN.properties等i18n配置文件，内容如下（注意中文需要使用ASCII码）：

```text
cn.yx.user.vo.userNameNotEmpty=用户名不能为空
```

Vo类中注解代码如下：

```java
@NotEmpty(message = "{cn.yx.user.vo.userNameNotEmpty}")
private String userName;
```

如果是2.6.X及以后版本的SpringBoot，Validation可直接支持SpringBoot的国际化配置

```yaml
spring:
  messages:
   basename: i18n/messages
   encoding: UTF-8
```

使用方式与SpringBoot Validation的形式一致，区别在于指定了国际化资源文件的路径、前缀和编码。指定编码为UTF-8后，资源文件中的中文不需要使用ASCII码。

### 异步日志配置

使用logback，可开启异步日志：

```xml
<appender name="file_info_async" class="ch.qos.logback.classic.AsyncAppender">
  <discardingThreshold>0</discardingThreshold>
  <queueSize>512</queueSize>
  <!-- 指定异步写入名称为 file_info 的 appender，这里最多只能添加一个 appender-ref -->
  <appender-ref ref="file_info" />
</appender>

<root level="info">
  <appender-ref ref="file_info_async" />
</root>
```

### transId的生成与使用

transId有两种生成方式：

1. 前端生成并通过`Transaction-Id`请求头传递到后端
2. 如果前端未传递`Transaction-Id`请求头，或者为空，则后端生成

`GatewayLoggerFilter`类完成从请求头中获取或生成transId，并放入MDC。

`GatewayExceptionHandler`类完成从请求头中获取或生成transId，并放入MDC。

`LoggerInterceptor`类完成从请求头中获取或生成transId，并放入MDC。

### 异步任务、线程支持MDC上下文信息

yx-common-starter-mdc模块可支持在Java线程及线程池任务中加入MDC上下文信息，同时也支持在SpringBoot的`@Async`
注解开启的异步任务加入MDC上下文信息。

### logback整合SkyWalking TraceId

在需要logback日志中输出SkyWalking TraceId的模块中引入`apm-toolkit-logback-1.x`，版本号与SkyWalking的版本号保持一致。

指定encoder class和layout class，如下：

```xml
<!-- %tid为SkyWalking中的TraceId -->
<property name="log.pattern" value="%date [%thread] %level [%X{traceId}] [%tid] %logger[%method,%line] - %msg%n" />

<appender name="file_all" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
        <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.TraceIdPatternLogbackLayout">
            <pattern>${log.pattern}</pattern>
        </layout>
    </encoder>
</appender>
```

未指定前如下：

```xml
<property name="log.pattern" value="%date [%thread] %level [%X{traceId}] %logger[%method,%line] - %msg%n" />

<appender name="file_error" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <encoder>
        <pattern>${log.pattern}</pattern>
    </encoder>
</appender>
```

如果未使用SkyWalking java agent启动项目，则输出的tid为：[TID: N/A]。

可配置日志直接被SkyWalking收集，方便在SkyWalking管理界面上查看日志，新增如下appender：

```xml
<property name="log.pattern" value="%date [%thread] %level [%X{traceId}] [%tid] %logger[%method,%line] - %msg%n" />

<appender name="grpc-log" class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.log.GRPCLogClientAppender">
    <encoder>
        <pattern>${log.pattern}</pattern>
    </encoder>
</appender>

<root level="info">
    <appender-ref ref="file_info" />
    <appender-ref ref="file_error" />
    <appender-ref ref="grpc-log"/>
</root>
```

yx-application-gateway模块logback配置中使用%tid不能输出SkyWalking的traceId，故使用自定义逻辑获取SkyWalking的traceId并添加到MDC上下文。具体逻辑可参考如下三个类：

```text
cn.yx.application.gateway.filter.GatewayLoggerFilter
cn.yx.application.gateway.subscriber.MdcSkyWalkingSubscriber
cn.yx.application.gateway.hook.MdcHook
```

### Dubbo负载均衡

使用`@DubboReference`注解引用Dubbo服务时，可使用负载均衡算法，如：

```java
@DubboReference(loadBalance = RoundRobinLoadBalance.NAME)
```

算法说明如下：

| 算法 | 特性 | 备注 |
| -- | -- | -- |
| RandomLoadBalance | 加权随机 | 默认算法，默认权重相同 |
| RoundRobinLoadBalance | 加权轮询 | 借鉴于 Nginx 的平滑加权轮询算法，默认权重相同 |
| LeastActiveLoadBalance | 最少活跃优先 + 加权随机 | 背后是能者多劳的思想 |
| ShortestResponseLoadBalance | 最短响应优先 + 加权随机 | 更加关注响应速度 |
| ConsistentHashLoadBalance | 一致性 Hash | 确定的入参，确定的提供者，适用于有状态请求 |

## 本地开发环境部署

### MySQL

### Redis

### Nacos

开发环境以单机模式运行，启动命令如下：

```shell
.\startup.cmd -m standalone
```

使用Nacos群集时，可使用Nginx配置Nacos集群的负载均衡。

### Sentinel

Dubbo本身具有服务降级功能，但是没有熔断和限流能力，故使用Sentinel，从Github下载Sentinel jar包后，启动控制台命令如下：

```shell
java -jar -Dserver.port=9193 -Dcsp.sentinel.dashboard.server=localhost:9193 -Dproject.name=sentinel-dashboard -Dcsp.sentinel.api.port=9194 sentinel-dashboard-1.8.5.jar
```

直接在Sentinel控制台配置URL资源或Dubbo服务资源的流控规则。

方式一：消费端限流，当配置URL资源流控规则时，请求可正常返回`Blocked by Sentinel (flow limiting)`。

yx-common-starter-sentinel模块中的`SentinelBlockExceptionHandler`实现了Sentinel的`BlockExceptionHandler`
接口，重新抛出自定义的`AppException`异常，用于替换`DefaultBlockExceptionHandler`。

方式二：服务端限流，当把服务提供者中的Dubbo服务资源配置流控规则后，服务提供者有error日志，消费端无error日志。

```text
服务
yx-user-service
流控资源名
cn.yx.user.remote.service.UserAccountRemoteService:getById(java.lang.Long)
```

error日志信息如下：

```text
ERROR [] org.apache.dubbo.rpc.filter.ExceptionFilter[onResponse,79] -  [DUBBO] Got unchecked and undeclared exception which called by 192.168.133.1. service: cn.yx.user.remote.service.UserAccountRemoteService, method: getById, exception: java.lang.RuntimeException: SentinelBlockException: FlowException, dubbo version: 2.7.15, current host: 192.168.133.1
java.lang.RuntimeException: SentinelBlockException: FlowException
 at com.alibaba.csp.sentinel.slots.block.BlockException.block(BlockException:0)
```

可在消费端全局捕捉RuntimeException异常后判断异常Message是否为SentinelBlockException开头，如果是则说明为Sentinel流控相关异常。

方式三：消费端限流，当把服务消费者中的Dubbo服务资源配置流控规则后，服务提供者和消费端都无error日志，消费端可全局捕捉RuntimeException并判断是否为SentinelBlockException。

```text
服务
yx-user-consumer
流控资源名
cn.yx.user.remote.service.UserAccountRemoteService:getById(java.lang.Long)
```

方式四：使用@SentinelResource注解 **（推荐）**

服务提供者和消费端均引用`spring-cloud-starter-alibaba-sentinel`和`sentinel-apache-dubbo-adapter`。

在消费端引用Dubbo服务的Controller方法上添加`@SentinelResource`注解，并指定`blockHandler`和`fallback`
返回自定义的响应消息，流控规则的配置有如下3种方式：

1. 消费端限流在Sentinel控制台使用`@SentinelResource`配置的资源名配置限流规则（相当于给消费端的Controller接口增加流控规则，服务提供者和消费端均无error日志）。

2. **服务端限流，在Sentinel控制台设置服务提供者接口资源限流规则（相当于直接给Dubbo服务增加了流控规则，服务提供者有error日志，消费端无error日志）。使用注解的情况下，则会覆盖方式二，如果未使用注解，则相当于使用方式二。**

3. 消费端限流，在Sentinel控制台设置消费端Dubbo接口资源限流规则（相当于间接给Dubbo服务增加了流控规则，服务提供者和消费端均无error日志）。

### SkyWalking

分布式链路追踪，需要下载SkyWalking APM和SkyWalking Java Agent。

由于SpringCloud Gateway基于WebFlux，网关链路未能被追踪，需要把SkyWalking Java
Agent的optional-plugins目录中的`apm-spring-webflux-5.x-plugin-8.12.0.jar`
和`apm-spring-cloud-gateway-3.x-plugin-8.12.0.jar`拷贝到plugins目录。使用Java Agent启动项目命令如下（可动态地指定服务名和文件编码）：

```shell
java -javaagent:D:\work\skywalking-agent\skywalking-agent.jar=agent.service_name=yx-user-service -Dfile.encoding=utf-8 -jar yx-user-service-1.0.0.jar
```

IDEA调试时，可在Run/Debug Configurations中配置VM options：

```text
# yx-application-gateway
-javaagent:D:\work\skywalking-agent\skywalking-agent.jar=agent.service_name=yx-application-gateway -Dfile.encoding=utf-8

# yx-application-doc
-javaagent:D:\work\skywalking-agent\skywalking-agent.jar=agent.service_name=yx-application-doc -Dfile.encoding=utf-8

# yx-user-service
-javaagent:D:\work\skywalking-agent\skywalking-agent.jar=agent.service_name=yx-user-service -Dfile.encoding=utf-8

# yx-user-consumer
-javaagent:D:\work\skywalking-agent\skywalking-agent.jar=agent.service_name=yx-user-consumer -Dfile.encoding=utf-8

# yx-sys-service
-javaagent:D:\work\skywalking-agent\skywalking-agent.jar=agent.service_name=yx-sys-service -Dfile.encoding=utf-8
```

### XXL-JOB

调度中心支持集群部署，提升调度系统容灾和可用性，调度中心集群部署时，几点要求和建议：

1. DB配置保持一致；
2. 集群机器时钟保持一致（单机集群忽视）；

建议：推荐通过Nginx为调度中心集群做负载均衡，分配域名。调度中心访问、执行器回调配置、调用API服务等操作均通过该域名进行。

### LPG轻量级日志系统

LPG即Loki + Promtail + Grafana，轻量化的日志收集、存储和展示系统。

Loki完成日志的分片存储，Promtail完成日志的收集，Grafana完成日志的展示。

Loki配置文件可参考`loki-local-config.yaml`：

```yaml
auth_enabled: false

server:
  http_listen_port: 3100

ingester:
  lifecycler:
    address: 127.0.0.1
    ring:
      kvstore:
        store: inmemory
      replication_factor: 1
    final_sleep: 0s
  chunk_idle_period: 5m
  chunk_retain_period: 30s
  max_transfer_retries: 0

schema_config:
  configs:
    - from: 2022-10-20
      store: boltdb
      object_store: filesystem
      schema: v11
      index:
        prefix: index_
        period: 168h

storage_config:
  boltdb:
    directory: /tmp/loki/index

  filesystem:
    directory: /tmp/loki/chunks

limits_config:
  enforce_metric_name: false
  reject_old_samples: true
  reject_old_samples_max_age: 168h

chunk_store_config:
  max_look_back_period: 0s

table_manager:
  retention_deletes_enabled: true
  retention_period: 336h
```

Promtail配置文件可参考`promtail-local-config.yaml`：

```yaml
server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://localhost:3100/loki/api/v1/push

scrape_configs:
- job_name: yx-application-gateway
  static_configs:
  - targets:
      - localhost
    labels:
      job: yx-application-gateway
      __path__: D:\work\yx-cloud\logs\yx-application-gateway\*.log
  pipeline_stages:
  - match:
      selector: '{job="yx-application-gateway"}'
      stages:
        - multiline:
            # 根据正式表达式匹配行
            firstline: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3}'
            # max_lines默认为128，超过128行，会另起一个block
            max_lines: 1000
            max_wait_time: 3s
- job_name: yx-user-service
  static_configs:
  - targets:
      - localhost
    labels:
      job: yx-user-service
      __path__: D:\work\yx-cloud\logs\yx-user-service\*.log
  pipeline_stages:
  - match:
      selector: '{job="yx-user-service"}'
      stages:
        - multiline:
            firstline: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3}'
            max_lines: 1000
            max_wait_time: 3s
- job_name: yx-user-consumer
  static_configs:
  - targets:
      - localhost
    labels:
      job: yx-user-consumer
      __path__: D:\work\yx-cloud\logs\yx-user-consumer\*.log
  pipeline_stages:
  - match:
      selector: '{job="yx-user-consumer"}'
      stages:
        - multiline:
            firstline: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3}'
            max_lines: 1000
            max_wait_time: 3s

```

启动时，先启动Loki，再启动Promtail，Windows下启动命令如下:

```shell
.\loki-windows-amd64.exe --config.file=loki-local-config.yaml
.\promtail-windows-amd64.exe --config.file=promtail-local-config.yaml
```

注意：

Grafana配置Loki数据源时，Loki URL为`http://localhost:3100`，根据`loki-local-config.yaml`配置文件指定的端口号而定。

Grafana的日志展示，Display results推荐使用默认的Newest first，如果使用Oldest first，可能会出现日志未按打印时间顺序显示的问题。

Grafana的日志时间范围搜索是按日志收集的时间范围搜索，而不是日志里打印时间的时间范围搜索。

Promtail日志抓取配置可增加`file_sd_configs`配置，以自动刷新需要抓取的日志文件并自动采集。

**如果需要初始化Loki和Promtail，可把Loki的storage配置和Promtail的positions配置生成的文件删除后再启动。**

## Docker部署

## 本地快速访问路径

yx-sys-service系统服务接口文档：<http://localhost:8180/doc.html#/home>

yx-sys-service系统服务Druid监控：<http://localhost:8180/druid/index.html>

yx-user-service用户服务接口文档：<http://localhost:8181/doc.html#/home>

yx-user-service用户服务Druid监控：<http://localhost:8181/druid/index.html>

yx-user-consumer用户服务消费示例接口文档：<http://localhost:18181/doc.html#/home>

yx-application-gateway网关BaseUrl：<http://localhost:9190>

yx-application-doc聚合接口文档：<http://localhost:9191/doc.html#/home>

yx-application-admin服务监控：<http://localhost:9192>