Ubuntu 22.04 安装 Apache ServiceComb java-chassis 3.3.0 指南
Ubuntu 22.04 安装 Apache ServiceComb java-chassis 3.3.0（微服务开发框架 SDK）指南：JDK 17 与 Maven 环境准备、版本选型（1.x/2.x/3.x 与 JDK 对照）、Maven 依赖引入与官方发行版 zip 离线两种方案、sha512 校验与卸载，全程实测。
Ubuntu 22.04 安装 Apache ServiceComb java-chassis 3.3.0 指南
目标：在 Ubuntu 22.04 服务器上完成 Apache ServiceComb java-chassis 3.3.0（Java 微服务开发框架，以 Maven 依赖或官方发行版 jar 引入，配合你的 Spring Boot 工程构建 REST 微服务，非独立守护进程）的安装与验证。本文给出 JDK 17 环境准备、1.x/2.x/3.x 版本选型对照、Maven 依赖引入与「官方发行版 zip 离线安装」两种方案，以及编译验证与卸载方式。所有命令与回显均在 Ubuntu 22.04.5 + JDK 17 环境实测通过。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（VERSION_CODENAME=jammy）
- 架构：x86_64（内核 6.8.0-138-generic）
- Java：OpenJDK 17.0.20.1（
openjdk-17-jdk-headless，Ubuntu 官方源） - 构建工具：Apache Maven 3.6.3（Ubuntu 官方源）
- java-chassis 版本：3.3.0（当前最新稳定主线，需 JDK 17，基于 Spring Boot 3.x / Jakarta EE 9+ 命名空间）
- 演示账号：root
- 示例工程目录：
/root/servicecomb-hello/ - 发行版安装目录（方案 B）：
/opt/servicecomb/
💡 说明：Apache ServiceComb java-chassis 是一个发布为 Maven 依赖（
org.apache.servicecomb:*）的微服务框架，本身没有独立守护进程或管理端口；所谓「安装」本质是准备好 JDK/Maven 环境并把 java-chassis 的 starter 依赖引入到你的 Spring Boot 工程，随应用进程启动 REST 服务。
二、前置条件
2.1 更新软件源
sudo apt-get update
2.2 安装 JDK 17 与 Maven
java-chassis 3.x 需要 JDK 17（Spring Boot 3.x / Jakarta 命名空间），Ubuntu 22.04 官方源已内置：
sudo apt-get install -y openjdk-17-jdk-headless maven wget curl unzip
验证 JDK 与 Maven：
java -version
mvn -version
实测回显：
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)
Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64
Default locale: en_US, platform encoding: ANSI_X3.4-1968
⚠️ 注意：若
mvn -version显示的Java version不是 17，说明默认 JVM 指向了其他版本，请在当前会话执行：export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 export PATH=$JAVA_HOME/bin:$PATH
三、版本选型说明
通过 Apache 官方发行目录探测当前在维护的版本：
curl -s https://dlcdn.apache.org/servicecomb/servicecomb-java-chassis/ | grep -oE "href=\"[0-9][^\"]+/\"" | tr -d "href=\"/"
实测返回：
1.3.11
2.8.31
2.9.5
3.3.0
三个主线版本对照如下：
| 版本 | 所需 JDK | 编程命名空间 | 适用场景 | 结论 |
|---|---|---|---|---|
| 1.3.11 | JDK 8 | javax | 遗留系统维护 | 仅旧系统使用 |
| 2.8.31 / 2.9.5 | JDK 8 / 11 | javax | 存量 JDK8/11 环境 | 用 2.x |
| 3.3.0 | JDK 17 | jakarta（Spring Boot 3.x） | 新项目、最新稳定主线 | 推荐 3.3.0 |
💡 版本选择建议：新项目直接选 java-chassis 3.3.0 + JDK 17；只有服务器停留在 JDK 8/11 且无法升级时才选 2.x（2.x 使用 javax 命名空间与 Spring Boot 2.x，API 与 3.x 不兼容）。本指南全程按 JDK 17 + java-chassis 3.3.0 实测。
四、方案 A：Maven 项目依赖引入（官方推荐）
java-chassis 官方推荐通过 Maven 以依赖方式引入，便于统一版本、传递依赖与打包。本方案从零创建一个最小 Maven 工程并验证依赖可解析、可编译。
4.1 创建 Maven 工程
mkdir -p /root/servicecomb-hello/src/main/java/demo
mkdir -p /root/servicecomb-hello/src/main/resources
cd /root/servicecomb-hello
4.2 编写 pom.xml 并引入 java-chassis 依赖
使用 <dependencyManagement> 同时导入 java-chassis-bom 与 spring-boot-dependencies，锁定全部版本：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>demo</groupId>
<artifactId>servicecomb-hello</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>
<properties>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<java-chassis.version>3.3.0</java-chassis.version>
<spring-boot.version>3.2.12</spring-boot.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.apache.servicecomb</groupId>
<artifactId>java-chassis-bom</artifactId>
<version>${java-chassis.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.apache.servicecomb</groupId>
<artifactId>java-chassis-spring-boot-starter-standalone</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
</dependencies>
<build>
<finalName>servicecomb-hello</finalName>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>${spring-boot.version}</version>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
💡 说明：
java-chassis-spring-boot-starter-standalone是 3.x「REST over Vert.x 独立进程」形态的最小 starter，自带 REST 服务能力（基于 vert.x 4.5.15），不依赖外置 Servlet 容器。若你的工程要部署到外部 Tomcat，可改用java-chassis-spring-boot-starter-servlet。
4.3 编译验证
为让工程可编译，先放一个最小主类：
cat > /root/servicecomb-hello/src/main/java/demo/HelloApplication.java <<'EOF'
package demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class HelloApplication {
public static void main(String[] args) {
SpringApplication.run(HelloApplication.class, args);
}
}
EOF
编译打包：
cd /root/servicecomb-hello
mvn clean package -DskipTests
实测结果（节选）：
[INFO] --- spring-boot-maven-plugin:3.2.12:repackage (repackage) @ servicecomb-hello ---
[INFO] Replacing main artifact /root/servicecomb-hello/target/servicecomb-hello.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
生成的可执行 jar：
-rw-r--r-- 1 root root 63431921 Oct 12 13:44 target/servicecomb-hello.jar
Maven 本地仓库 ~/.m2/repository/org/apache/servicecomb/ 下会生成 java-chassis 全套 3.3.0 jar（java-chassis-core、transport-rest-vertx、provider-springmvc、provider-jaxrs 等 27 个组件）。
五、方案 B：官方发行版 zip 离线安装（内网 / 无 Maven 场景）
在不使用 Maven 的场景（如离线内网、手工 classpath 组装），可以直接下载 Apache 官方发行版 zip 包，内含全部 63 个运行时 jar。
5.1 下载发行版并校验 sha512
mkdir -p /opt/servicecomb
cd /opt/servicecomb
wget https://dlcdn.apache.org/servicecomb/servicecomb-java-chassis/3.3.0/apache-servicecomb-java-chassis-distribution-3.3.0-bin.zip
wget https://dlcdn.apache.org/servicecomb/servicecomb-java-chassis/3.3.0/apache-servicecomb-java-chassis-distribution-3.3.0-bin.zip.sha512
sha512sum apache-servicecomb-java-chassis-distribution-3.3.0-bin.zip
cat apache-servicecomb-java-chassis-distribution-3.3.0-bin.zip.sha512
实测回显（两值一致为校验通过）：
d6e6589068f48c6239a1fbba28977c91bf6beb6875505b3f6f0d7cf551c67dd9ca1f4479a912d65266c6338370680f0188575ef5b4d9a06035bc378aa0649403 apache-servicecomb-java-chassis-distribution-3.3.0-bin.zip
d6e6589068f48c6239a1fbba28977c91bf6beb6875505b3f6f0d7cf551c67dd9ca1f4479a912d65266c6338370680f0188575ef5b4d9a06035bc378aa0649403 *apache-servicecomb-java-chassis-distribution-3.3.0-bin.zip
💡
dlcdn.apache.org只保留当前在维护的版本；历史版本（如 2.x 更早的 2.8.x、3.0~3.2 系列）可到归档站https://archive.apache.org/dist/servicecomb/servicecomb-java-chassis/下载。
5.2 解压与目录结构
unzip -q apache-servicecomb-java-chassis-distribution-3.3.0-bin.zip -d /opt/servicecomb
ls /opt/servicecomb/apache-servicecomb-java-chassis-distribution-3.3.0-bin/
实测回显：
LICENSE
NOTICE
README.md
README_ZH.md
libs
licenses
libs/ 下为全部运行时 jar（共 63 个），核心组件包括：
| jar | 作用 |
|---|---|
| java-chassis-core-3.3.0.jar | 框架核心：SCBEngine、微服务注册与发现骨架 |
| transport-rest-vertx-3.3.0.jar | REST over Vert.x 通信模块 |
| provider-rest-common-3.3.0.jar | @RestSchema REST 生产者支持 |
| provider-springmvc-3.3.0.jar | Spring MVC 注解生产者支持 |
| provider-jaxrs-3.3.0.jar | JAX-RS 注解生产者支持 |
| handler-loadbalance-3.3.0.jar | 消费端负载均衡 |
5.3 验证 jar 版本
unzip -p /opt/servicecomb/apache-servicecomb-java-chassis-distribution-3.3.0-bin/libs/java-chassis-core-3.3.0.jar META-INF/MANIFEST.MF
实测回显：
Manifest-Version: 1.0
Created-By: Maven JAR Plugin 3.4.2
Build-Jdk-Spec: 17
Specification-Title: Java Chassis::Core
Specification-Version: 3.3
Specification-Vendor: The Apache Software Foundation
Implementation-Title: Java Chassis::Core
Implementation-Version: 3.3.0
Implementation-Vendor: The Apache Software Foundation
离线使用时，把 libs/ 全部 jar 加入 CLASSPATH（或安装到内网私服 Nexus/Artifactory），即可按方案 A 相同的坐标编码。
六、配置说明
java-chassis 作为随应用启动的框架，核心配置集中在两处：
- Maven 依赖版本：
java-chassis-bom与spring-boot-dependencies两个 import 必须成对出现，版本分别为 3.3.0 与 3.2.12。 - 微服务配置文件：
src/main/resources/microservice.yaml，声明服务名、版本、注册中心与 REST 监听地址；该文件由 java-chassis 在启动时加载。最小可用配置：
application:
name: hello-app
servicecomb:
service:
name: hello
version: 0.0.1
registry:
enabled: false
rest:
address: 0.0.0.0:8080
⚠️ 注意：standalone 形态（REST over Vert.x）下，classpath 存在 spring-webmvc 但没有 Servlet 容器，Spring Boot 会尝试启动 Servlet Web 服务而失败，需在
src/main/resources/application.yml中关闭：spring: main: web-application-type: none
详细参数含义与生产模板见《Apache ServiceComb java-chassis 3.3.0 配置参数详解》篇；API 用法速查见《Apache ServiceComb java-chassis 3.3.0 常用工具与 API 详解》篇。
七、注意事项
⚠️ 注意：
- java-chassis 3.x 必须 JDK 17+；JDK 8/11 只能配 2.x（javax 命名空间）。选版本前先确认服务器 JDK。
- 3.x 主类无需任何 java-chassis 注解（2.x 的
@EnableServiceComb在 3.x 中已移除，编译会报package org.apache.servicecomb.springboot.starter does not exist）；java-chassis 3.x 各模块通过 Spring Boot 3 标准的META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports自动装配。- java-chassis 3.x 与 2.x 的注册中心地址配置键不同：2.x 为
servicecomb.service.registry.address，3.x 只支持servicecomb.registry.sc.address。- 进程内存建议显式限制 JVM 堆（如
java -Xms256m -Xmx512m -jar app.jar），并用jps -v验证生效。
八、常见问题
Q1：编译报 package org.apache.servicecomb.springboot.starter does not exist / cannot find symbol: class EnableServiceComb？
使用了 2.x 时代的主类写法。java-chassis 3.x 已移除 @EnableServiceComb 注解，主类只保留 @SpringBootApplication，框架经 Spring Boot 3 自动配置装配：
@SpringBootApplication
public class HelloApplication {
public static void main(String[] args) {
SpringApplication.run(HelloApplication.class, args);
}
}
Q2：启动报 Web application could not be started as there was no org.springframework.boot.web.servlet.server.ServletWebServerFactory bean defined in the context？
standalone starter 的 REST 由 Vert.x 提供，classpath 中没有 Servlet 容器；而 Spring Boot 检测到 spring-webmvc 后默认按 Servlet Web 应用启动。在 application.yml 中设置 spring.main.web-application-type: none 即可，REST 端口由 servicecomb.rest.address 管理。
Q3：Maven 下载慢或超时？
可在 ~/.m2/settings.xml 配置镜像仓库，或提前在有网环境执行一次 mvn package 再把 ~/.m2/repository 整体拷贝到目标服务器（离线编译）。
Q4：dlcdn.apache.org 上找不到想要的旧版本？
官方 CDN 只保留当前维护版本，历史版本到 https://archive.apache.org/dist/servicecomb/servicecomb-java-chassis/ 下载。
九、卸载方式
若仅移除 Maven 依赖：删除 pom.xml 中 org.apache.servicecomb 相关 <dependency>，并清理本地仓库缓存：
rm -rf ~/.m2/repository/org/apache/servicecomb
rm -rf /root/servicecomb-hello
若采用方案 B 安装了发行版，直接删除安装目录：
rm -rf /opt/servicecomb
若同时移除 JDK 17 与 Maven：
sudo apt-get remove -y openjdk-17-jdk-headless maven
sudo apt-get autoremove -y
十、参考链接
- Apache ServiceComb 官方下载目录：
https://dlcdn.apache.org/servicecomb/servicecomb-java-chassis/ - 历史版本归档：
https://archive.apache.org/dist/servicecomb/servicecomb-java-chassis/ - java-chassis 官方文档：
https://servicecomb.apache.org/references/java-chassis/zh_CN/ - Maven Central 仓库：
https://repo1.maven.org/maven2/org/apache/servicecomb/