kenaito-kopsc/README.java.md

Java 应用（kopsc java <子命令>）

返回 README.md

按 JDK 版本自动套用调优参数并前台运行 Java 应用。你不需要逐条抄 JVM 参数， kopsc 会根据宿主机（或容器）的实际资源算出堆大小，并按 JDK 版本选择对应的 GC 日志写法。

kopsc java run app.jar                                  # 一键启动，参数自动生成
kopsc java run app.jar -- --spring.profiles.active=prod # 应用参数写在 jar 之后
kopsc java run --jdk 17 --print-flags app.jar           # 只打印最终 java 命令行

运行应用（java.run）

kopsc java run <app.jar> [-- 应用参数...] 等价于用一组业界常用参数执行 java <flags> -jar <app.jar> <应用参数>，并在前台运行：日志直接打印到终端，Ctrl+C 可停止， 退出码原样返回给调用方。

kopsc java run myapp.jar
kopsc java run myapp.jar -- --server.port=9000 --spring.profiles.active=prod
kopsc java run --jdk 11 --heap 4g myapp.jar
kopsc java run --env staging --gc-log /var/log/app myapp.jar
kopsc java run --dry-run myapp.jar          # 只看将执行的命令，不启动

自动识别的内容

项目	规则
JDK 版本	执行 java -version 解析版本，识别不到时回退 -XshowSettings:properties；支持 8 / 11 / 17 / 21，其它版本会提示用 --jdk 指定
CPU 核数	取可用逻辑核数；容器内优先采用 cgroup 配额（cpu.max / cfs_quota_us）
内存	Linux 读 /proc/meminfo（容器内以 cgroup memory.max / memory.limit_in_bytes 为准）、macOS 用 sysctl hw.memsize、Windows 用 wmic
堆大小	默认取可用内存的 50%，-Xms 与 -Xmx 同值；可用 --heap / --xms 覆盖
直接内存	-XX:MaxDirectMemorySize 取堆的 1/4，最低 64m
配置环境	-Dconfig.file=application-<env>.yaml，来源依次为 --env、环境变量 APP_ENV、默认 prod

生成的参数

类别	参数
通用	-server、-Xss256k、-XX:+SegmentedCodeCache、-XX:+ExplicitGCInvokesConcurrent、-Djava.security.egd=file:/dev/./urandom
堆	-Xmx<size>、-Xms<size>、-XX:MaxDirectMemorySize=<size>
压缩指针	-XX:+UseCompressedOops、-XX:+UseCompressedClassPointers；堆超过 30g 时自动省略
GC	-XX:+UseG1GC
GC 日志（JDK 9+）	-Xlog:gc*,safepoint:<dir>/gc.log:time,uptime:filecount=100,filesize=50M
GC 日志（JDK 8）	-verbose:gc、-Xloggc:<dir>/gc.log、-XX:+PrintGCDetails、-XX:+PrintGCDateStamps、-XX:+UseGCLogFileRotation、-XX:NumberOfGCLogFiles=100、-XX:GCLogFileSize=50M
命令回显	-XX:+PrintCommandLineFlags
可选	-XX:+HeapDumpOnOutOfMemoryError（--heap-dump-on-oom）

JDK 8 与 9+ 的 GC 日志写法不兼容：-Xlog: 是 JDK 9 引入的，JDK 8 用它会导致 JVM 直接拒绝启动。 kopsc 按检测到的版本自动切换，所以同一份启动命令在 JDK 8 和 JDK 21 上都能跑。

选项

选项	说明
<app.jar>	应用 jar，必填
-- <应用参数>...	交给应用自身的参数；写在 jar 之后的所有内容也会原样传给应用
--jdk <8|11|17|21>	指定按哪个 JDK 版本的方案生成参数；可写 1.8、jdk17
--java <路径>	指定使用的 java 可执行文件，默认取 PATH 中的 java
--heap <大小> / --xmx <大小>	指定堆上限，如 4g、512m；默认取可用内存 50%
--xms <大小>	指定初始堆，默认与堆上限相同
--env <环境>	指定配置环境，生成 -Dconfig.file=application-<环境>.yaml
--gc-log <目录>	开启 GC 日志并指定输出目录；默认不开启
--heap-dump-on-oom	OOM 时导出堆转储
--print-flags	只打印最终 java 命令行（一行），可直接复制到 Dockerfile / systemd
-q, --quiet	不打印启动摘要
--dry-run	只展示将执行的命令与资源判定，不启动进程

注意

• 选项必须写在 jar 之前；jar 之后的内容全部视为应用参数，所以 --spring.profiles.active=prod 不会被 kopsc 当成自己的选项。
• 应用参数里出现的 -Xmx、-D... 只是应用自己的参数，kopsc 不会解析它们。
• 前台运行依赖终端；长时间运行的场景请配合 kopsc proc nohup 或容器编排使用。
• --gc-log 指定的目录不存在时会自动创建。