什么是應用

按照官網文檔 創建工程 創建的 SOFABoot 工程，通過 編譯運行，在本地被打包為 {XXX}-executable.jar 文件，并存放于工程根目錄的 target 目錄中。這個 fat JAR 文件，在 SOFAStack 平臺上，就是一個應用。在云端，應用需要和其運行的環境進行關聯，才能實現預期功能。應用和技術棧的關聯方式，請參見 關聯技術棧與應用服務。

什么是技術棧

在 SOFAStack 平臺上，技術棧 指一個應用程序所依賴的全部框架及附屬資源的集合，它定義了應用發布部署和運維時的依賴信息，主要包括下述內容：

• 操作系統和版本

• 開發框架類型和版本

• 應用啟動和部署腳本

• 環境參數

官方技術棧下載

請單擊獲取 官方技術棧。

技術棧命名規則

發布應用時，一旦選定技術棧架構，則不可再更改，但可更新該架構下的技術棧版本號以獲取最新功能。每個技術棧架構都有對應的技術棧，隨著功能迭代和需求變更，該技術棧產生了各種不同的版本。

以技術棧 SOFA_Boot_1.0.7-j180t2114 為例，對 SOFABoot 技術棧的命名規則說明如下：

• 1.0.7：指技術棧的版本。

  更多版本信息，請參見 版本說明。

• j180：指 JDK 版本 1.8.0（技術棧中更具體的是 1.8.0_131，不是 ajdk，也不支持協程）。

• t2114： 指 tengine 版本 2.1.14。

開發框架與技術棧

對于開發框架 SOFABoot 3.x，其所支持的技術棧及推薦的技術棧信息如下：

• JDK 版本：≥ JDK 8

• 技術棧版本：≥ 1.0.6-j180t2114

開發框架與所支持的技術棧配置關系圖：

技術棧目錄結構

技術棧目錄包含以下子文件夾：

• conf/：存放技術棧配置文件。為可選文件，內容可以為空。

• lifecycle/：存放生命周期代碼。理論上您可以使用任何語言來編寫這些生命周期腳本。lifecycle 目錄下所有文件名必須以專屬前綴 ac_ 開頭，且沒有后綴。目前，下述文件的命名為固定命名：

  • ac_setup：技術棧依賴的安裝腳本，主要代碼邏輯為讀取 resources 目錄下的文件，解壓、安裝、配置環境變量等。

  • ac_init_env：可選。用于部署前的相關任務處理。

  • ac_deploy：應用程序包的啟動腳本。核心啟動命令為：java -jar appname.jar

  • ac_check_service：可選。檢測應用是否啟動。

  • ac_shutdown：停止應用。

• resources/：存放技術棧的依賴、生命周期代碼的依賴等。如果您的技術棧足夠簡單，無需任何依賴，resources 文件夾可以為空。

示例

默認提供的 sofaboot-1.0.7 技術棧包的文件結構如下：

sofaboot_buildpack_1.0.7-j180t2114        // 默認沒有 conf 文件夾
├── lifecycle                            // 生命周期代碼
│├── ac_setup
│├── ac_init_env
│├── ac_deploy
│├── ac_check_service
│└── ac_shutdown
└── resources                            // 技術棧和生命周期代碼的依賴
├── centos6.5// 該技術棧在 CentOS 6.5 操作系統上的依賴
│├── cronolog-1.7.0-0.x86_64.rpm
│├── jdk-1.8.0_131-normal-1.x86_64.rpm
│├── nginx-gray-module-0.0.2.rpm
│└── tengine-2.0.0-12298.el6u0.x86_64.rpm
├── centos7.2// 該技術棧在 CentOS 7.2 操作系統上的依賴
│├── cronolog-1.7.0.tgz
│├── jdk-1.8.0_131-normal-1.x86_64.rpm
│├── nginx-gray-module-0.0.2.rpm
│└── tengine-proxy-2.1.14.rpm
├── check_service.sh
├── deploy.sh
├── nginx.sh
├── stopApp.sh
├── util.py
└── util.sh

制作技術棧壓縮包

技術棧打包的操作步驟如下：

1. 創建 技術棧目錄結構。

2. 在目錄下創建技術棧生命周期腳本和相關依賴。

3. 將目錄下所有腳本和相關依賴壓縮成 .tgz 文件，生成技術棧包。在以下示例中，假定技術棧目錄名為 sofaboot-buildpack。

   $ cd sofaboot-buildpack
   $ tar -cvzf sofaboot-buildpack.tgz ./*
   // ./* 表示：將當前目錄下的所有文件打包

   說明

   .tgz 文件的名稱與實際的技術棧名稱無關。

技術棧與應用發布流程

將應用打包上傳到 SOFAStack 平臺，實現部署的發布方式請參見 關聯技術棧并發布應用。

技術棧支持的功能

發布 SOFABoot 應用時，您必須 將應用關聯至技術棧 才能使用。SOFABoot 技術棧支持以下功能：

• 使用 java -jar {XXXXX-executable.jar} 命令啟動 JAR 文件。{XXXXX-executable.jar} 為工程編譯運行后生成的 fat JAR 文件。JAR 文件在 ECS 服務器上的路徑為：

  • 默認上傳路徑： /home/admin/release/run

  • 可執行文件路徑：/home/admin/app-run

• 支持在云端部署時通過 -D 動態參數來指定配置中心地址。默認會拼接注冊中心的地址，并傳遞給 Java 進程。

• 支持在代碼中設置 java_opts 作為 JVM 的啟動參數。詳見 JVM 參數配置。

• 根據當前 ECS 所在的工作空間名，即 /etc/metafile 文件中的 workspace_name 和 tenant_name，指定啟動參數。詳見 技術棧配置方案。

• 使用 tenginx-conf/tengine.conf 文件配置 Tengine 啟動參數。詳見 Tengine 靜態配置。

• 如果應用發布后沒有檢測到 java -jar 進程，則在健康檢查階段會返回失敗。

• com.alipay.confreg.url 配置項指定配置中心的地址，僅對開通 VPN 或專線的租戶有效。當應用部署至阿里云 ECS 時，技術棧會自動完成此設置。如有需要，您可通過 -D 參數指定此配置項。

• 支持對自定義健康檢查設置端口。配置方式：在應用實例環境參數中配置 ac.healthcheck.port。

• 支持對自定義健康檢查設置超時時間。配置方式：在應用實例環境參數中配置 ac.healthcheck.timeout，單位為秒。

技術棧配置方案

我們約定把所有環境相關的配置，放在應用代碼中可部署模塊的 resources 目錄下。其中，可部署模塊指的是使用 spring-boot-maven-plugin 打包出 fat JAR 的模塊，例如 SOFABoot Web 工程中的 Web 模塊。

properties 配置

單環境

通過 resources/config/application.properties 即可實現全局配置。

多環境

開發者在項目發布前，可能需要頻繁地在開發環境、測試環境、預發布環境、生產環境之間進行切換，通過 profile 的配置，您可以在使用同一套代碼的情況下，為不同的工作空間提供相應配置，省去了多次打包的麻煩。根據 SOFABoot 技術棧版本的不同，配置方式有稍微變化。

配置文件生效優先級，完全參考了 Spring Boot 的 Profile 機制。更多詳情，請參見 Profiles。

多環境下的配置步驟如下：

1. 登錄云端服務器，在 /etc/mefile 中查詢 tenant_name 和 workspace_name 信息。

   說明

   在新版迭代后，將支持在 SOFAStack 控制臺一鍵查詢上述信息，敬請期待。

2. 在本地工程的 resources/config/ 目錄下創建多個 properties 文件。

   • 創建 租戶空間的配置文件：命名格式為 application-{tenant_name}_{workspace_name}.properties。

     • {tenant_name} 為租戶名。其值來自于 /etc/metafile 文件中的 tenant_name。

     • {workspace_name} 為工作空間名。其值來自于 /etc/metafile 文件中的 workspace_name。

     • 示例：假定租戶名 {tenant_name}=tenant1234， 工作空間名 {workspace_name}=dev，則命名格式為：application-tenant1234_dev.properties。其中，命名中第一個分割符為短橫線，第二個分隔符為下劃線。

   • 自定義配置文件：可以自定義多個 properties 文件。

     • 命名方式：application-{profile}.properties，其中 {profile} 為占位符，表示自定義工作空間名。

     • 配置方式：需在 application.properties 中添加鍵值對： spring.profiles.include={profile1},{profile2}。其中 {profile} 為占位符，多個 {profile} 之間用英文逗號分隔。

     • 示例：假定自定義工作空間名為 testDev 和 testProd，則命名格式為：application-testDev.properties 和 application-testProd.properties。

3. 將本地工程打包、上傳到云端服務器，進行發布。詳情參見 技術棧與應用發布流程。

4. 執行命令，讓期望的配置文件生效。生效方式有下述默認和自定義 2 種：

   • 默認方式：服務器啟動時，默認執行的命令為 -Dspring.profiles.active={workspace_name},{tenant_name}_{workspace_name}。

   • 自定義生效方式：具體操作見下述步驟。

     1. 在云端服務器，通過遠程連接，執行 cd /home/admin/app-run 命令，進入應用發布包所在目錄。

     2. 執行命令 java -jar -Dspring.profiles.active={profile} xxxxx-executable.jar。其中的參數說明如下：

        • {profile} 為占位符，表示期待生效的工作空間。

        • xxxxx-executable.jar 為 /home/admin/app-run 目錄下的發布包的名稱。

日志配置

配置路徑

配置文件都在可部署模塊下。可部署模塊指使用 spring-boot-maven-plugin 打包的模塊，例如 SOFABoot Web 工程中的 Web 模塊。日志的配置文件路徑為： resources/logback-spring.xml。

配置文件名稱來源

由于 SOFA 中間件技術棧對日志配置的解決方案使用 Spring Boot，需要引入 Maven 依賴 spring-boot-starter-logging，此依賴默認使用 logback.xml 進行日志打印，因此日志配置文件的名稱使用 logback-spring.xml。

日志依賴

• 日志對應的依賴為：spring-boot-starter-logging。

• 此依賴默認使用 logback 進行日志打印。

• 按照官網文檔 創建工程 創建的 SOFABoot 工程，在可部署模塊下的 pom.xml 文件中，默認已經引入該依賴。

生效方式

• 在 logback-spring.xml 配置文件中增加 <springProfile> 標簽并使用 name={profile1,profile2} 屬性來定義該段配置對應的運行環境。

• 在 application.properties 中配置：spring.profiles.active={profile}。只要 profile 中包含有 name 對應的值，配置就會被激活。

示例如下：

<springProfile name="dev,test">
    <appender name="DEV-TEST-APPENDER" class="ch.qos.logback.core.rolling.RollingFileAppender">
        ...
     </appender>
</springProfile>

• springProfile 對應的環境為 dev,test

• application.properties 中配置：spring.profiles.active=dev 或 spring.profiles.active=test后，這段配置被激活。

• 激活后，<appender> 標簽中定義的 DEV-TEST-APPENDER 可以通過 <appender-ref> 標簽被引用。

Tengine 靜態配置

可以使用 Tengine 靜態配置文件來配置下述內容：

• 資源的訪問

• 指定端口流量的轉發

配置路徑

配置文件都在可部署模塊下。可部署模塊指使用 spring-boot-maven-plugin 打包的模塊，例如 SOFABoot Web 工程中的 Web 模塊。

• Tengine 配置文件路徑：tenginx-conf/tengine.conf。

• 打包路徑：BOOT-INF/classes。

生效方式

當使用 SOFABoot 技術棧在 SOFAStack 平臺上自動發布部署時，技術棧會讀取 tenginx-conf/tengine.conf 中的配置，并按配置來啟動 tengine。

JVM 參數配置

JVM 配置需求

在不同的 ECS 上啟動應用時，需要指定的堆大小也可能不一致，這就產生了按照 ECS 內存大小，來選擇不同 JVM 參數的需求。

JVM 配置規則

您可以通過提供多份 java_opts 開頭的文件來設置不同 ECS 上的 JVM 參數。

關于 java_opts 文件，約定規則如下：

• 存放路徑：應用代碼的 src/main/resources 目錄下。即需要部署的 fat JAR 包中的 classpath 根目錄下。

• 多文件支持：有多份該文件時，文件名稱以 java_opts 開頭，以內存大小標識作為后綴，且內存大小為整數。如 java_opts_2g，java_opts_4g等。

• 默認處理：

  • 如果找不到正確的 java_opts_?g 文件，默認讀取 java_opts 文件。

  • 如果不存在 java_opts 文件，則相當于沒有任何 JVM 參數。

Shell 腳本 Hook 的配置

Hook 配置需求

SOFABoot 技術棧支持在應用代碼中添加 hook 腳本。您可以通過添加 hook 腳本使應用在啟動 Java 程序前執行其它操作，例如：啟動一個 python 腳本，將一個 .so 文件添加到環境變量中等。在部署應用時，技術棧會調用這些腳本中的函數。

Hook 配置規則

hook 腳本配置規則如下：

• 腳本路徑：必須為 src/main/resources/hook.sh。即腳本需要部署在 fat JAR 包（即可部署模塊）中的 classpath 根目錄下。

• 調用時機：在 hook.sh 腳本中聲明待被調用的函數，不同函數名對應不同的調用時機：

  • before_appstart_hook：應用啟動前

  • after_appstart_hook：應用啟動后

  • 其他名字的函數不會被調用

• 其它執行邏輯：hook.sh 腳本中，除了 Shell 函數的聲明以外，不要有其它執行邏輯，否則每次在調用 hook 函數時都會觸發這些執行邏輯。

• 如果不需要這個功能，可以不提供 hook 腳本。

hook.sh 示例：

function before_appstart_hook {
    echo 'before_appstart_hook executed'
}

function after_appstart_hook {
    echo 'after_appstart_hook executed'
}