KonaJDK：超详细部署与使用教程

Tencent Kona（腾讯 Kona OpenJDK）是腾讯开源的 OpenJDK 发行版，提供 8 / 11 / 17 / 21 / 25 多个 LTS 版本，是腾讯内部大规模业务（大数据、机器学习、云计算）默认使用的 JDK，支持 Linux / macOS / Windows，x86_64 与 aarch64 架构，并在 Kona 8 / 17 中原生内置国密（SM2/SM3/SM4、TLCP）能力。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

Tencent Kona JDK 是腾讯对外发布的、零费用、生产可用的 OpenJDK 发行版（no-cost, production-ready distribution of OpenJDK），按季度更新维护长期支持（LTS）版本。它是腾讯内部的默认 JDK，针对超大规模的大数据、机器学习与云计算工作负载做了优化；同时腾讯也面向外部客户与合作伙伴提供经过腾讯支持的 OpenJDK 发行版。

Kona JDK 采用「友好分叉（friendly fork）」模式：许可证与上游 OpenJDK 完全一致（GPL v2 + Classpath Exception），腾讯致力于把增强能力尽可能回馈上游 OpenJDK。

1.2 核心功能

• 多 LTS 版本：提供 Kona 8、Kona 11、Kona 17、Kona 21、Kona 25 共 5 个长期支持版本（以官方仓库为准），每个版本独立仓库、独立发版，季度更新。
• 跨平台支持：Linux（x86_64 / aarch64）、Windows（x86_64）、macOS（x86_64 / aarch64，Apple Silicon）。
• 大规模生产验证：腾讯内部默认 JDK，服务于大数据、机器学习、云计算等超大规模场景。
• 国密算法与 TLCP 支持：最新的 Tencent Kona JDK 8 和 17 已原生支持国密算法（SM2 / SM3 / SM4）、TLCP（传输层密码协议，即国标 GB/T 38636-2020，俗称 GMSSL）以及基于 RFC 8998 的 TLS 1.3 国密套件。
• 国密增强套件（Tencent Kona SM Suite）：一套 Java Security Provider，包含 KonaCrypto、KonaCrypto-Native、KonaPKIX、KonaSSL、Kona 等 6 个 Provider，可在任意 JDK 8/11/17/21/25 上以 Maven 依赖方式引入国密能力，已签名并可在 Oracle JDK 上运行。
• Maven Central 发布：SM Suite 构件全部发布在 Maven Central（com.tencent.kona:kona-*），纯 Java 实现可跑在所有主流操作系统。
• 与 BouncyCastle 互通：自 1.0.5 起不再依赖 BouncyCastle，两套实现均遵循国密规范、可直接互通；但注意 BouncyCastle 不支持 TLCP 与 TLS 1.3/RFC 8998 协议。

SM Suite 包含的 6 个 Provider 分工如下：

1.3 技术架构

Kona JDK 本身是 OpenJDK 的发行版（fork），其内部结构与标准 OpenJDK 一致：HotSpot VM、Class Library（java.base 等模块）、JDK 工具链。下图为 Tencent Kona 官方 Logo：

说明：Kona JDK 作为 OpenJDK 发行版，官方未单独提供公开可用的系统架构图；其内部架构即上游 OpenJDK 架构（HotSpot + 模块系统 + 类库），以官方 Wiki 与 OpenJDK 文档为准。

二、环境要求

三、部署方式

下面给出三种部署方式：方式一：从 GitHub Releases 下载二进制包（推荐）→ 方式二：源码编译 → 方式三：引入国密增强套件（SM Suite，Maven 依赖）。

3.1 方式一：二进制包安装（推荐，以 Kona 21 为例）

步骤 1：下载对应平台的安装包

各版本 Release 页面： - Kona 21：https://github.com/Tencent/TencentKona-21/releases - Kona 17：https://github.com/Tencent/TencentKona-17/releases - Kona 8：https://github.com/Tencent/TencentKona-8/releases - Kona 11：https://github.com/Tencent/TencentKona-11/releases - Kona 25：https://github.com/Tencent/TencentKona-25/releases

以 Kona 21.0.12（Linux x86_64）为例，官方资产命名规则为 TencentKona-<版本号>.b<n>-jdk_<平台>.tar.gz：

cd /opt
# Linux x86_64
wget https://github.com/Tencent/TencentKona-21/releases/download/TencentKona-21.0.12/TencentKona-21.0.12.b1-jdk_linux-x86_64.tar.gz

# Linux aarch64
wget https://github.com/Tencent/TencentKona-21/releases/download/TencentKona-21.0.12/TencentKona-21.0.12.b1-jdk_linux-aarch64.tar.gz

# macOS Apple Silicon（公证版）
wget https://github.com/Tencent/TencentKona-21/releases/download/TencentKona-21.0.12/TencentKona-21.0.12.b1_jdk_macosx-aarch64_notarized.tar.gz

# Windows x86_64（签名 zip）
# 浏览器下载：TencentKona-21.0.12.b1_jdk_windows-x86_64_signed.zip

每个包都附带 .md5 校验文件，下载后建议校验：

md5sum -c TencentKona-21.0.12.b1-jdk_linux-x86_64.tar.gz.md5

国内下载慢时可使用 GitHub 代理加速（如 ghproxy），或在腾讯云内网通过镜像源下载（以官方渠道为准）。

步骤 2：解压

cd /opt
tar -zxvf TencentKona-21.0.12.b1-jdk_linux-x86_64.tar.gz
# 解压后目录名形如 TencentKona-21.0.12
ls -d /opt/TencentKona-*

步骤 3：配置环境变量

# 写入 /etc/profile.d/kona.sh（所有用户生效）
cat > /etc/profile.d/kona.sh <<'EOF'
export JAVA_HOME=/opt/TencentKona-21.0.12
export PATH=$JAVA_HOME/bin:$PATH
EOF

source /etc/profile.d/kona.sh

步骤 4：验证安装成功

java -version

预期输出（版本号以实际安装为准）：

openjdk version "21.0.12" TencentKona-21.0.12-b1
OpenJDK Runtime Environment TencentKona-21.0.12-b1 (build 21.0.12-b1)
OpenJDK 64-Bit Server VM TencentKona-21.0.12-b1 (build 21.0.12-b1, mixed mode, sharing)

同时 javac -version、jps、jcmd 等命令应可直接执行。

Windows 安装：

解压 TencentKona-<版本>_jdk_windows-x86_64_signed.zip 到如 D:\TencentKona-21.0.12，在「系统属性 → 环境变量」中新增 JAVA_HOME=D:\TencentKona-21.0.12，并把 %JAVA_HOME%\bin 追加到 Path。

各版本下载地址汇总（截至 2026-10-27）

各版本资产命名规则一致：TencentKona-<版本>.b<n>-jdk_<平台>.tar.gz（Linux）、_jdk_windows-x86_64_signed.zip（Windows）、_jdk_macosx-<arch>_notarized.tar.gz（macOS 公证版）。

多版本共存与切换

在同一台机器上安装多个 Kona 版本，用 JAVA_HOME 切换：

# 安装 Kona 8 与 Kona 17
ls -d /opt/TencentKona-*
# /opt/TencentKona-1.8.0.27  /opt/TencentKona-17.0.20

# 切换到 Kona 17
export JAVA_HOME=/opt/TencentKona-17.0.20
export PATH=$JAVA_HOME/bin:$PATH
java -version

# 切换到 Kona 8
export JAVA_HOME=/opt/TencentKona-1.8.0.27
export PATH=$JAVA_HOME/bin:$PATH

CentOS/RHEL 也可用 alternatives 管理默认 java：

sudo alternatives --install /usr/bin/java java /opt/TencentKona-17.0.20/bin/java 170
sudo alternatives --config java

3.2 方式二：源码编译（自定义需求）

Kona JDK 各版本仓库即为 OpenJDK 源码 fork，编译方式与 OpenJDK 一致（1.16 仓库默认分支为 universal）：

# 安装编译依赖（Ubuntu/Debian 示例，具体以官方文档为准）
sudo apt install build-essential autoconf make zip unzip

# 克隆源码
git clone https://github.com/Tencent/TencentKona-21.git
cd TencentKona-21
git checkout universal   # 该仓库默认分支为 universal

# 配置构建（--with-boot-jdk 指定一个可用的 JDK 作为引导 JDK）
bash configure --enable-debug --with-boot-jdk=/usr/lib/jvm/java-21-openjdk

# 构建（N 为 CPU 核数）
make images

构建产物在 build/*/images/ 目录下，得到 jdk 与 jre 镜像目录，直接拷贝到部署机即可。

编译 OpenJDK 源码对磁盘（5GB+）、内存（4GB+）有要求，详细步骤参考 OpenJDK 官方构建文档与各仓库 Wiki。

3.3 方式三：引入国密增强套件（Kona SM Suite，Maven 依赖）

如果你的 JDK 已经是其他发行版（如 Oracle JDK、Adoptium），只需在 Java 应用里获得国密算法 / TLCP 能力，可使用 Tencent Kona SM Suite：

Gradle 依赖（已发布 Maven Central）：

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.tencent.kona:kona-crypto:<version>")
    implementation("com.tencent.kona:kona-pkix:<version>")
    implementation("com.tencent.kona:kona-ssl:<version>")
    implementation("com.tencent.kona:kona-provider:<version>")
}

版本号以 Maven Central 为准：https://central.sonatype.com/search?q=com.tencent.kona （最新 Release 为 v1.0.24）。 不需要把全部 Provider 都加进 classpath：只需要国密算法时，引入 kona-crypto + kona-provider 即可。

3.4 验证部署成功（通用）

1. java -version 输出含 TencentKona 字样；
2. echo $JAVA_HOME 指向 Kona 安装目录；
3. 运行一个 Hello World 或用 jcmd 查看进程，确认 HotSpot VM 正常。

四、使用方法

4.1 基础用法：作为应用默认 JDK

Kona JDK 与标准 OpenJDK / Oracle JDK 使用方式完全一致，现有 Java 应用无需修改代码：

# 直接运行 jar 包
java -jar your-app.jar

# 常用启动参数与 OpenJDK 相同
java -Xms2g -Xmx4g -XX:+UseG1GC -jar your-app.jar

# 查看 JDK 自带工具
jps          # 列出本机 Java 进程
jcmd <pid> VM.system_properties   # 查看系统属性
jstack <pid> # 打印线程栈

4.2 使用国密能力（SM Suite）

引入 SM Suite 后，在代码中注册 Provider 即可使用 SM2/SM3/SM4：

import com.tencent.kona.provider.Kona;
import java.security.Security;

public class SMExample {
    public static void main(String[] args) throws Exception {
        // 注册 Kona Provider（封装 KonaCrypto/KonaPKIX/KonaSSL）
        Security.addProvider(new Kona());

        // 使用 SM3 摘要
        java.security.MessageDigest md = java.security.MessageDigest.getInstance("SM3");
        byte[] digest = md.digest("hello".getBytes("UTF-8"));
        System.out.println(javax.xml.bind.DatatypeConverter.printHexBinary(digest));
    }
}

KonaSSL 实现 TLCP（GB/T 38636-2020）与 TLS 1.3 的 TLS_SM4_GCM_SM3 套件（基于 RFC 8998），可用于符合国密合规要求的 HTTPS 通信；官方在 kona-demo 模块中提供了与 Jetty / Tomcat 集成的服务端示例，kona-ssl 测试集提供了与 Netty、gRPC、Apache HttpClient、OkHttp 集成的示例。

4.3 进阶功能

• TLCP 双向国密证书：KonaPKIX 提供 KeyTool（与 JDK keytool 一致），可用 PBEWithHmacSM3AndSM4 加密私钥、HmacPBESM3 校验 keystore 完整性；KeyStoreTool 可把现有 PEM 编码私钥/证书导入 keystore。
• JNI 原生加速：KonaCrypto-Native 基于 JNI + OpenSSL，支持 Linux x86_64 / aarch64，通过 PhantomReference 自动管理 JNI 本地内存，性能更高。
• Android 平台：SM Suite 默认不依赖任何 JDK 内部 API，可直接跑在 Android 上。
• Kona 8 / 17 原生国密：使用最新 Kona 8 / 17 的用户无需引入 SM Suite，JDK 层面即支持国密算法与 TLCP。
• Spring Boot / Web 服务器集成：官方在 kona-demo 模块中演示了把 Kona SM Suite 接入 Jetty、Tomcat 的服务端用法；测试集还演示了 Netty、gRPC、Apache HttpClient、OkHttp 的客户端集成。
• 构建 SM Suite 源码：基于 Gradle（Kotlin DSL），./gradlew build 全量构建，或 ./gradlew :kona-pkix:build 单独构建子模块。

4.4 JVM 参数调优参考

Kona JDK 兼容标准 HotSpot 参数，常见启动示例：

# 堆内存与 G1GC（大堆服务端）
java -Xms4g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -jar app.jar

# 打印 GC 日志（JDK 11+）
java -Xmx4g -Xlog:gc*:file=gc.log -jar app.jar

# 查看进程实时状态
jcmd <pid> VM.flags        # 当前生效的 JVM 参数
jcmd <pid> GC.heap_info    # 堆使用情况
jcmd <pid> Thread.print    # 线程栈

腾讯内部针对大数据/机器学习负载做过优化，具体增强项以官方 Wiki 与 Release Note 为准。

4.5 适用场景

• 企业级 Java 应用运行时替换：从 Oracle JDK / 其他发行版平滑迁移，零费用、生产验证充分；
• 信创/国密合规场景：需要 SM2/SM3/SM4 算法、TLCP 协议的金融、政务、运营商系统；
• 大数据与云原生工作负载：Hadoop、Spark、Kafka 等服务端 JDK；
• 腾讯云生态客户：使用腾讯支持的 OpenJDK 发行版。

五、常见问题排查（FAQ）

Q1：java -version 仍显示旧 JDK 版本 - 原因：环境变量未生效或系统中有多个 JDK。 - 解决：which java 确认实际路径；检查 /etc/profile.d/、~/.bashrc 中 JAVA_HOME 配置；用 alternatives（CentOS）或 update-alternatives（Debian）管理默认 JDK 优先级。

Q2：SM2 加密报错 java.security.InvalidKeyException: Illegal key size or default parameters - 原因：JDK 8u161 之前默认不支持高强度算法与长密钥（如 AES-256、SM2 需要的 256 位密钥）。 - 解决：升级到 JDK 8u161+；或参考官方 FAQ（Stack Overflow 上关于 JCE 策略文件的说明）安装无限制权限策略文件。

Q3：为什么 Oracle JDK 下跑不了 SM Suite 的单元测试？ - 原因：Oracle JDK 要求 JCE 实现必须经过 Oracle JCE Code Signing CA 签名；源码里的 KonaCrypto 尚未签名。 - 解决：Maven Central 上发布的构件均已签名，可在 Oracle JDK 上直接使用；只有从源码直接跑测试才需要自行签名。

Q4：是否支持 ECC_SM4_GCM_SM3 / ECDHE_SM4_GCM_SM3 的 TLS 1.2？ - 原因：没有 RFC 把这些套件引入 TLS 1.2 标准。 - 解决：本项目在 TLS 1.3 中基于 RFC 8998 支持 TLS_SM4_GCM_SM3；需要 TLS 1.2 国密对接请确认对端实现（TLCP 1.1 是独立协议）。

Q5：GMSSL / GMSSL 1.1 是 TLCP 吗？ - 解答：是。国标 GB/T 38636-2020 将该类 TLS 风格协议命名为「传输层密码协议（TLCP）」，版本号 1.1，即业界俗称的 GMSSL / GMSSL 1.1。

Q6：Linux 下图形化 Java 程序中文乱码 - 原因：服务器缺少中文字体。 - 解决：安装字体包（如 fonts-noto-cjk），并在 JVM 参数中指定字体。

Q7：源码编译时 configure 失败 - 解决：按报错安装缺失的依赖包；确认 --with-boot-jdk 指向一个版本兼容的已安装 JDK；磁盘与内存满足要求。

Q8：JDK 8 各场景最低版本要求是什么？ - 解答（官方 FAQ）：只需 SM 算法/TLCP 时最低 8u141；TLCP 需要 ALPN 扩展时最低 8u251；需要 TLS 1.3/RFC 8998 时最低 8u261。

Q9：Kona JDK 与 OpenJDK 上游什么关系？ - 解答：「友好分叉」，许可证与上游 OpenJDK 一致（GPL v2 + Classpath Exception），增强能力尽量回馈上游，因此迁移到 Kona 与迁移到任意 OpenJDK 发行版风险相当。

六、部署注意事项与最佳实践

1. 版本选择：新生产环境推荐 Kona 17 或 Kona 21；存量业务从 JDK 8 迁移时直接换 Kona 8 包，代码零改动。
2. 固定版本号：下载后把安装包与 md5 存入内部制品库，避免多台机器版本不一致。
3. 校验 MD5：每次下载后执行 md5sum -c，防止下载不完整或被篡改。
4. 国密合规：金融/政务场景优先选择已原生支持国密的 Kona 8 / 17；若已用其他 JDK，则用 SM Suite 补齐算法层。
5. JCE 签名：Oracle JDK 环境务必使用 Maven Central 正式发布的构件，不要用源码自行打包。
6. 监控一致：Kona JDK 兼容标准 JDK 监控工具（JMX、Prometheus JMX exporter），接入方式不变。
7. 升级策略：跟随官方季度更新节奏升级；升级前阅读各 Release Note 与 Wiki。

七、参考资料

• GitHub 仓库（Kona 21）：https://github.com/Tencent/TencentKona-21
• Kona 8：https://github.com/Tencent/TencentKona-8
• Kona 11：https://github.com/Tencent/TencentKona-11
• Kona 17：https://github.com/Tencent/TencentKona-17
• Kona 25：https://github.com/Tencent/TencentKona-25
• Kona 21 Wiki（安装与使用指南）：https://github.com/Tencent/TencentKona-21/wiki
• Kona 21 Releases 下载：https://github.com/Tencent/TencentKona-21/releases
• Kona 国密增强套件（SM Suite）：https://github.com/Tencent/TencentKonaSMSuite
• Maven Central 构件：https://repo1.maven.org/maven2/com/tencent/kona/