odboy
f62c1f4872
- 自动识别 JDK 8/11/17/21 与宿主机 CPU、可用内存；容器内以 cgroup 限额为准；堆默认取可用内存 50%，-Xms 与 -Xmx 同值 - 按版本分支生成参数：JDK 8 用 -Xloggc 一组，JDK 9+ 用 -Xlog:； 堆超过 30g 时自动省略压缩指针参数 - 支持 --jdk/--java/--heap/--xms/--env/--gc-log/--heap-dump-on-oom/ --print-flags/--dry-run；jar 之后的参数原样交给应用 - 前台运行：stdio 直连、退出码透传、SIGINT/SIGTERM 转发给 JVM - BuiltinRequest 增加 Stdin，使内置命令可以读取调用方输入 - 修正帮助中的用法行重复（自定义 Usage 不再追加通用透传尾巴） - 文档：新增 README.java.md，主 README 补充导航与示例
79 lines
4.4 KiB
Markdown
79 lines
4.4 KiB
Markdown
# Java 应用（`kopsc java <子命令>`）
|
||
|
||
> 返回 [README.md](README.md)
|
||
|
||
按 JDK 版本自动套用调优参数并前台运行 Java 应用。你不需要逐条抄 JVM 参数，
|
||
kopsc 会根据宿主机（或容器）的实际资源算出堆大小，并按 JDK 版本选择对应的 GC 日志写法。
|
||
|
||
```bash
|
||
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 可停止，
|
||
退出码原样返回给调用方。
|
||
|
||
```bash
|
||
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` 指定的目录不存在时会自动创建。
|