全部产品
云市场

技术栈使用指南

更新时间:2019-09-18 11:19:46

在 SODAStack 上,技术栈 指一个应用程序所依赖的全部框架及附属资源的集合,定义了应用发布部署和运维时应用的依赖信息,包括操作系统和版本、开发框架类型和版本、应用启动和部署脚本、环境参数等。

SODAStack 提供 SOFABoot 技术栈(2.0 架构)。发布 SOFABoot 应用时,您必须 将应用关联至技术栈 才能使用。

技术栈支持功能

SOFABoot 技术栈(2.0 架构)支持以下功能:

  • 使用 java -jar {XXXXX-executable.jar} 命令启动 .jar 文件。{XXXXX-executable.jar} 为工程编译运行后生成的 fat JAR 文件。
    • .jar 原始文件默认上传到 ECS 服务器的以下路径: /home/admin/release/run
    • 最终生效的 .jar 文件位于 ECS 服务器的以下路径,该路径下的 fat JAR 文件将作为可执行的 .jar 文件: /home/admin/app-run
  • 支持在云端部署时通过 -D 动态参数来指定配置中心地址;也可以在代码中设置 java_opts 作为 JVM 的启动参数。详见 JVM 参数设置
  • 默认会拼接注册中心的地址,并传递给 Java 进程。
  • 根据当前 ECS 所在的工作空间名,即 /etc/metafile 文件中的 workspace_nametenant_name,指定启动参数。详见 全局配置解决方案
  • 使用 tenginx-conf/tengine.conf 文件配置 Tengine 启动参数。详见 Tengine 静态配置
  • 如果应用发布后没有检测到 java -jar 进程,则在健康检查阶段会返回失败。
  • com.alipay.confreg.url 配置项指定配置中心的地址,仅对开通 VPN 或专线的租户有效。当应用部署至阿里云 ECS 时,技术栈会自动完成此设置。如有需要,您可通过 -D 参数指定此配置项。

配置解决方案

通过 profile 的配置,您可以在使用同一套配置和代码的情况下为不同的环境(例如开发环境、测试环境、预发布环境、生产环境)提供适合于该环境的相应配置,省去多次打包的麻烦。

我们约定把所有环境相关的配置,放在应用代码中可部署模块的 resources 目录下(可部署模块指的是使用 spring-boot-maven-plugin 打包出 fat jar 的模块)

全局配置解决方案

全局配置文件默认为 config/application.properties,用于全局通用(即不依赖环境)的公共配置项。要为多个环境提供不同的 profile,请在 config目录下创建多个 .properties 文件。

配置方法
  1. 配置 application.properties 文件。

    • SOFABoot 技术栈 1.0.6 及更早的版本:

      支持针对工作空间进行 profile 配置。建议将 config 目录下的配置文件命名为 config/application-{$workspace_name}.properties,其中 {$workspace_name} 变量为该文件对应的工作空间名称,如 dev、test、pre、prod 等。例如 application-dev.properties

    • SOFABoot 技术栈 1.0.7 及以上版本:

      支持针对工作空间及单个租户进行 profile 配置。建议将config目录下的配置文件命名为 application-${tenant_name}_${workspace_name}.properties,其中 ${tenant_name} 为租户名,${workspace_name} 为工作空间名。同时以前的 application-${workspace_name}.properties 命名风格依然支持。

      例如:租户名为 1234, 工作空间名为 dev,则配置文件命名推荐为:application-1234_dev.properties。 如果 application-1234_dev.propertiesapplication-dev.properties 两个文件同时存在,那么它们都会生效,且 application-1234_dev.properties 优先级别更高。

  2. 配置 /etc/metafile 文件。

    • SOFABoot 技术栈 1.0.6 及更早的版本:

      技术栈根据当前工作空间名,即 /etc/metafile 文件中的 workspace_name 值,指定启动参数 -Dspring.profiles.active=${workspace_name}。要使用某个环境的配置文件,请将中 workspace_name 配置项对应的值设置为该环境名称。例如,当workspace_name=dev 时,dev环境的配置文件 application-dev.properties 生效。

    • SOFABoot 技术栈 1.0.7 及以上版本:

      技术栈根据当前工作空间名及租户名,即 /etc/metafile 文件中的 workspace_nametenant_name,指定启动参数 -Dspring.profiles.active=${workspace_name},${tenant_name}_${workspace_name}。例如,当workspace_name=devtenant_name=1234时,配置文件 application-1234_dev.properties 生效。

  3. 如果需要自定义激活多个 profile,请在全局通用配置文件 config/application.properties 中添加属性值 spring.profiles.include=${profile1},${profile2}。多个 profile 用英文逗号分隔。被添加的 profile 将和 -Dspring.profiles.active=${workspace_name} 参数指定的 profile 同时被加载。

生效方式

SOFABoot 技术栈在启动 SOFABoot 应用时会自动加上 JVM 的启动参数 -Dspring.profiles.active=,用以制定在启动后将会生效指定后缀的全局配置文件。此机制完全使用 Spring Boot 的 Profile 机制,详情请参考 Spring Boot Reference Guide > Profiles(英文)

日志配置解决方案

配置路径

日志配置存放在可部署模块的 resources/logback-spring.xml 文件下。

由于 SOFA 中间件技术栈对日志配置的解决方案使用 Spring Boot,需要引入 Maven 依赖 spring-boot-starter-logging,此依赖默认使用 logback.xml 进行日志打印,因此日志配置文件的名称使用 logback-spring.xml

生效方式

logback-spring.xml 配置文件中增加 <springProfile> 标签并使用 name 属性来定义该段配置对应的运行环境。当参数 spring.profiles.active 包含了该环境名称时,这段配置被激活生效。

例如,在以下示例代码中,配置 springProfile 对应的环境为 dev,test,那么当激活参数 spring.profiles.active 中包含 devtest 时,这段配置被激活。此时,<appender> 标签中定义的 DEV-TEST-APPENDER 可以通过 <appender-ref> 标签被引用。

  1. <!-- logback-spring.xml -->
  2. <springProfile name="dev,test">
  3. <appender name="DEV-TEST-APPENDER" class="ch.qos.logback.core.rolling.RollingFileAppender">
  4. <append>true</append>
  5. <filter class="ch.qos.logback.classic.filter.LevelFilter">
  6. <level>${logging.level}</level>
  7. <onMatch>ACCEPT</onMatch>
  8. <onMismatch>DENY</onMismatch>
  9. </filter>
  10. <file>${logging.path}/slite2-client/app-default-dev.log</file>
  11. <!-- 每天生成一个日志文件,保存30天的日志文件 -->
  12. <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
  13. <!--日志文件输出的文件名:按天回滚 daily -->
  14. <FileNamePattern>${logging.path}/slite2-client/app-default-dev.log.%d{yyyy-MM-dd}
  15. </FileNamePattern>
  16. <!--日志文件保留天数-->
  17. <MaxHistory>30</MaxHistory>
  18. </rollingPolicy>
  19. <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
  20. <!--格式化输出:%d表示日期,%thread表示线程名,%-5level:级别从左显示5个字符宽度%msg:日志消息,%n是换行符-->
  21. <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
  22. <!-- 编码 -->
  23. <charset>UTF-8</charset>
  24. </encoder>
  25. </appender>
  26. </springProfile>

关于 springProfile 的详细说明请参考 Spring Boot Reference Guide > Profile-specific configuration(英文)

Tengine 静态配置

可以使用 Tengine 静态配置文件来配置资源的访问和指定端口流量的转发。

配置路径

Tengine 配置文件存放在可部署模块(即使用 spring-boot-maven-plugin 打包的模块)的 tenginx-conf 目录下,文件名为 tengine.conf。打包之后,该配置文件默认被打包在 BOOT-INF/classes 目录。

生效方式

当使用 SOFABoot 技术栈在 SOFAStack 平台上自动发布部署时,技术栈会根据这个文件的存在,并读取 tenginx-conf/tengine.conf 配置文件内容来作为 tengine 的配置来启动 tengine。

JVM 参数支持

应用在不同的 ECS 上启动,需要指定的堆大小也可能不一致,这就产生了按照 ECS 内存大小,来选择不同 JVM 参数的需求。您可以通过提供多份 java_opts 开头的文件来设置不同 ECS 上的 JVM 参数。

约定规则如下:

  • java_opts 开头的参数配置文件存放在需要部署的 fat jar 包中的 classpath 根目录下,即应用代码的 src/main/resources 目录下。
  • 支持多份 java_opts 开头的文件,以内存大小标识作为后缀,如 java_opts_2gjava_opts_4g等,只支持整数。
  • 如果找不到正确的 java_opts_?g 文件,默认读取 java_opts 文件。
  • 如果不存在 java_opts 文件,则相当于没有任何 JVM 参数。

Shell 脚本 Hook 机制支持

SOFABoot 技术栈支持在应用代码中添加 hook 脚本。您可以通过添加 hook 脚本使应用在启动 Java 程序前执行其它操作,例如:启动一个 python 脚本,将一个 .so 文件添加到环境变量中等。在部署应用时,技术栈会调用这些脚本中的函数。

规则如下:

  • hook 脚本必须放置在需要部署的 fat jar 包(即可部署模块)中的 classpath 根目录下,即应用代码的 src/main/resources 目录下,名字为 hook.sh
  • 在 hook.sh 脚本中声明要被调用的函数,不同函数名对应不同的调用时机:
    • before_appstart_hook:应用启动前
    • after_appstart_hook:应用启动后
    • 其他名字的函数不会被调用
  • hook.sh 脚本中,除了 shell 函数的声明以外,不要有其他执行逻辑,否则每次在调用 hook 函数时都会触发这些执行逻辑。
  • 如果不需要这个功能,可以不提供 hook 脚本。

hook.sh 示例:

  1. function before_appstart_hook {
  2. echo 'before_appstart_hook executed'
  3. }
  4. function after_appstart_hook {
  5. echo 'after_appstart_hook executed'
  6. }