docs(work): add PR7050 package startup flow summary

src/work/project-summary/pr7050-package-startup-flow.md

@@ -0,0 +1,229 @@
+---
+title: PR7050 打包启动流程说明
+icon: fa6-solid:box-archive
+date: 2026-05-11
+category:
+  - 工作
+tag:
+  - PR7050
+  - Java
+  - 打包
+  - XJar
+  - 启动流程
+---
+
+# PR7050 打包启动流程说明
+
+本文档基于当前仓库脚本重新整理。所有路径、密码、服务清单均以 PR7050 当前文件为准，不沿用 PR7950 目录。
+
+<!-- more -->
+
+## 1. 文档范围
+
+涉及的当前 PR7050 文件：
+
+- `src_java/package/build.sh`：Java 平台、应用、压缩加密工具的主打包入口。
+- `src_java/package/jar_list.txt`：打包后需要收集并加密的 Spring Boot 服务 Jar 清单。
+- `binary/java/bin/encrypt/*.xml`：每个服务压缩时需要保留在服务 Jar 内的依赖清单。
+- `src_java/tool/sunri-package-compress-xjar/src/main/java/com/sunri/Main.java`：XJar 加密密码、加密 include 规则和配置读取逻辑。
+- `src_java/tool/sunri-package-compress-xjar/src/main/java/com/sunri/JarUtil.java`：服务 Jar 压缩、公共依赖抽取和 `*-requirements.txt` 生成逻辑。
+- `binary/java/bin/javacontrol.sh`：Java 服务 start、stop、restart 控制脚本。
+
+## 2. Java 打包流程
+
+在 PR7050 根目录下，Java 打包入口位于 `src_java/package/build.sh`。脚本通过自身路径计算 `PROJECT_ROOT`，实际 Java 工程根为 `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java`。
+
+### 总体流程步骤
+
+1. **清理旧产物**：执行 `clean_stale_java_outputs`，先删除旧 Jar、XJar 中间文件和旧 requirements。
+2. **架构检测**：通过 `uname -m` 选择 `jdk-x64` 或 `jdk-arm`，并设置 Maven 路径。
+3. **同步加密 XML**：从 `binary/java/bin/encrypt` 同步到 `src_java/package/java/bin/encrypt`。
+4. **编译 Platform**：进入 `src_java/platform` 执行 `mvn clean install -DskipTests -T 1C`。
+5. **编译 Platapp**：进入 `src_java/platapp` 执行 `mvn clean package -DskipTests -T 1C`。
+6. **收集服务 Jar**：按 `jar_list.txt` 在 platform 和 platapp 的 `target` 目录查找并复制。
+7. **压缩加密**：构建并执行 `sunri-package-compress-xjar`，生成加密后的服务 Jar。
+8. **同步到 binary**：将加密 Jar 和 common 依赖复制到 `binary/java` 运行目录。
+
+### 2.1 清理旧 Java 输出
+
+`build.sh` 开头调用 `clean_stale_java_outputs`。它会先创建必要目录，再删除下列旧文件，避免上一次构建残留影响本次打包：
+
+- `src_java/package/java/jar/x64_raw/*.jar`
+- `src_java/package/java/jar/x64_compress/*.jar`
+- `src_java/package/java/jar/x64/*.jar`、`*.xjar`、`xjar.go`、`compress-xjar.config`
+- `binary/java/jar/x64/*.jar`
+- `src_java/package/java/lib/common/*.jar` 与 `*-requirements.txt`
+- `binary/java/lib/common/*.jar` 与 `*-requirements.txt`
+
+### 2.2 关键打包命令
+
+```bash
+cd /home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/package
+./build.sh
+```
+
+脚本内部执行的 Maven 命令：
+
+```bash
+cd /home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/platform
+mvn clean install -DskipTests -T 1C
+
+cd /home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/platapp
+mvn clean package -DskipTests -T 1C
+```
+
+> **⚠ 注意：** `build.sh` 当前跳过测试，适合打包流程。若改动源码，应按受影响模块另行执行最小测试命令。
+
+## 3. 压缩与 XJar 加密
+
+压缩加密工具位于 `src_java/tool/sunri-package-compress-xjar`。打包脚本会编译该工具，将 `sunri-package-compress-xjar-1.0-jar-with-dependencies.jar` 复制到 `src_java/package/java/tools`，再由模板生成 `compress-xjar.config`。
+
+### 3.1 配置文件生成
+
+模板 `src_java/package/java/tools/model_compress-xjar.config` 中的 `{项目全路径}` 会被替换为 `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java`。生成后的主要目录如下：
+
+| 配置项 | 当前 PR7050 路径 | 作用 |
+| :--- | :--- | :--- |
+| `entryptXmlDir` | `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/package/java/bin/encrypt/` | 读取每个服务的 encrypt XML。 |
+| `rawJarDir` | `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/package/java/jar/x64_raw` | 待压缩加密的原始服务 Jar。 |
+| `compressJarDir` | `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/package/java/jar/x64_compress` | 移除外置依赖后的中间 Jar。 |
+| `libDir` | `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/package/java/lib/common` | 抽取出的 common 第三方依赖和 `*-requirements.txt`。 |
+| `xjarDir` | `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/package/java/jar/x64` | XJar 加密输出目录。 |
+| `enableCompress` | `1` | 启用压缩和公共依赖抽取。 |
+
+### 3.2 压缩规则
+
+`JarUtil.java` 会遍历服务 Jar 的 `BOOT-INF/lib`。以下依赖保留在服务 Jar 内：
+
+- 文件名以 `cygbusiness-` 开头的依赖。
+- 文件名以 `sunri-` 开头的依赖。
+- 当前服务 encrypt XML 中列出的依赖，例如 `<artifactId>` + `-` + `<version>` + `.jar`。
+
+未保留的 `BOOT-INF/lib/*.jar` 会抽取到 `src_java/package/java/lib/common`，并写入 `服务名-requirements.txt`。启动时 `javacontrol.sh` 会通过 `-Dplainload.include.file=服务名-requirements.txt` 指定该服务需要按需加载的 common 依赖。
+
+### 3.3 XJar 加密规则
+
+`Main.java` 中的默认加密密码为 `0755isa`。当密码为空或以"默认"开头时，也会回退到 `0755isa`。
+
+当前 XJar include 规则如下：
+
+```text
+/com/sunri/**
+*.yaml
+mapper/**.xml
+*.yml
+```
+
+工具先生成 `服务名.xjar`，成功后重命名为 `服务名.jar`，最终由 `build.sh` 复制到 `binary/java/jar/x64`。
+
+### 3.4 ClassLoader 相关说明
+
+运行时通过 XJar 启动器执行加密 Jar。压缩出的 common 依赖由启动参数 `-Dplainload.dir.path` 和 `-Dplainload.include.file` 控制，项目中该机制通常对应 `PlainTextClassLoader` 一类的明文依赖加载逻辑：服务自身 Jar 保留业务和必要基础依赖，外置 common 依赖按 requirements 文件加载。
+
+## 4. Java 服务启动链路
+
+Java 服务控制脚本为 `binary/java/bin/javacontrol.sh`，位置参数含义如下：
+
+| 参数 | 变量 | 说明 |
+| :--- | :--- | :--- |
+| `$1` | `SpringBoot` | 服务 Jar 完整路径。 |
+| `$2` | 函数名 | `start`、`stop` 或 `restart`。 |
+| `$3` | `LIB_PATH` | common 依赖目录，拼接为 `-Dplainload.dir.path=...`。 |
+| `$4` | `JVM_OPTS` | 额外 JVM 参数。 |
+| `$5` | `ENABLE_SKIP_AUTH` | 认证跳过开关，未传时默认 `false`。 |
+
+### 4.1 架构选择
+
+`javacontrol.sh` 使用 `uname -m` 选择 XJar 启动器：
+
+```bash
+if [[ "$ARCH" == "x86_64" ]]; then
+    JAVA_PROC_XJAR_SH="${PRJHOME}/binary/java/jar/x64/xjar"
+elif [[ "$ARCH" == "aarch64" ]]; then
+    JAVA_PROC_XJAR_SH="${PRJHOME}/binary/java/jar/arm/xjar"
+else
+    JAVA_PROC_XJAR_SH="${PRJHOME}/binary/java/jar/x64/xjar"
+fi
+```
+
+### 4.2 真实启动命令链路
+
+服务不存在运行中进程时，脚本最终通过 `xjar java` 启动加密后的 Jar：
+
+```bash
+nohup $JAVA_PROC_XJAR_SH java \
+  -Dplainload.dir.path=$LIB_PATH \
+  -Dplainload.include.file=$requirements_txt \
+  -DenableSkipAuth=$ENABLE_SKIP_AUTH \
+  -Drds.dynamic.sql=true \
+  -Djava.net.preferIPv4Stack=true \
+  -Dfile.encoding=utf-8 \
+  -Duser.timezone=Asia/Shanghai \
+  $JVM_OPTS \
+  -XX:+UseG1GC \
+  -XX:ParallelGCThreads=8 \
+  -XX:NativeMemoryTracking=summary \
+  -jar $SpringBoot &
+```
+
+`requirements_txt` 由服务 Jar 文件名计算得到，例如 `cygsystemweb.jar` 对应 `cygsystemweb-requirements.txt`。
+
+## 5. 关键路径表
+
+| 路径 | 说明 |
+| :--- | :--- |
+| `/home/liumangmang/IdeaProjects/PR7050/V1.00` | PR7050 仓库根目录。 |
+| `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/package/build.sh` | Java 打包主入口。 |
+| `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/package/jar_list.txt` | 服务 Jar 收集清单。 |
+| `/home/liumangmang/IdeaProjects/PR7050/V1.00/binary/java/bin/encrypt` | 源加密依赖配置目录。 |
+| `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/package/java/bin/encrypt` | 打包时同步出的加密依赖配置目录。 |
+| `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/package/java/jar/x64_raw` | 原始服务 Jar 收集目录。 |
+| `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/package/java/jar/x64_compress` | 压缩后的中间 Jar 目录。 |
+| `/home/liumangmang/IdeaProjects/PR7050/V1.00/src_java/package/java/jar/x64` | XJar 加密输出目录。 |
+| `/home/liumangmang/IdeaProjects/PR7050/V1.00/binary/java/jar/x64` | x64 运行目录中的加密服务 Jar 和 xjar 启动器。 |
+| `/home/liumangmang/IdeaProjects/PR7050/V1.00/binary/java/jar/arm` | ARM 运行目录中的 xjar 启动器路径。 |
+| `/home/liumangmang/IdeaProjects/PR7050/V1.00/binary/java/lib/common` | 运行目录中的 common 依赖和 `*-requirements.txt`。 |
+| `/home/liumangmang/IdeaProjects/PR7050/V1.00/binary/java/bin/javacontrol.sh` | Java 服务启动、停止、重启控制脚本。 |
+
+## 6. 服务清单
+
+以下服务来自当前 `src_java/package/jar_list.txt` 和 `binary/java/bin/encrypt/*.xml`。
+
+| # | 服务 Jar | 服务名 | 加密配置 XML | XML include 数 | requirements 文件 |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| 1 | `cygpatrolcenterweb.jar` | `cygpatrolcenterweb` | `cygpatrolcenterweb.xml` | 56 | `cygpatrolcenterweb-requirements.txt` |
+| 2 | `cyganalysecenterweb.jar` | `cyganalysecenterweb` | `cyganalysecenterweb.xml` | 29 | `cyganalysecenterweb-requirements.txt` |
+| 3 | `cygeventsrvmngweb.jar` | `cygeventsrvmngweb` | `cygeventsrvmngweb.xml` | 38 | `cygeventsrvmngweb-requirements.txt` |
+| 4 | `cyganalysesrvweb.jar` | `cyganalysesrvweb` | `cyganalysesrvweb.xml` | 27 | `cyganalysesrvweb-requirements.txt` |
+| 5 | `cygauditweb.jar` | `cygauditweb` | `cygauditweb.xml` | 34 | `cygauditweb-requirements.txt` |
+| 6 | `cygsignsrvweb.jar` | `cygsignsrvweb` | `cygsignsrvweb.xml` | 39 | `cygsignsrvweb-requirements.txt` |
+| 7 | `cygdevopsweb.jar` | `cygdevopsweb` | `cygdevopsweb.xml` | 34 | `cygdevopsweb-requirements.txt` |
+| 8 | `cygmouldweb.jar` | `cygmouldweb` | `cygmouldweb.xml` | 34 | `cygmouldweb-requirements.txt` |
+| 9 | `cygsystemweb.jar` | `cygsystemweb` | `cygsystemweb.xml` | 33 | `cygsystemweb-requirements.txt` |
+| 10 | `cygtwinspatrolweb.jar` | `cygtwinspatrolweb` | `cygtwinspatrolweb.xml` | 34 | `cygtwinspatrolweb-requirements.txt` |
+| 11 | `cygtwinsweb.jar` | `cygtwinsweb` | `cygtwinsweb.xml` | 45 | `cygtwinsweb-requirements.txt` |
+| 12 | `cygservicereportweb.jar` | `cygservicereportweb` | `cygservicereportweb.xml` | 45 | `cygservicereportweb-requirements.txt` |
+| 13 | `cygfileweb.jar` | `cygfileweb` | `cygfileweb.xml` | 35 | `cygfileweb-requirements.txt` |
+| 14 | `cyggraphicweb.jar` | `cyggraphicweb` | `cyggraphicweb.xml` | 41 | `cyggraphicweb-requirements.txt` |
+| 15 | `cygcontrolweb.jar` | `cygcontrolweb` | `cygcontrolweb.xml` | 40 | `cygcontrolweb-requirements.txt` |
+| 16 | `patrolsip.jar` | `patrolsip` | `patrolsip.xml` | 28 | `patrolsip-requirements.txt` |
+
+## 7. 新增服务检查清单
+
+1. 确认服务模块可以在 `src_java/platform` 或 `src_java/platapp` 的 Maven 构建中产出目标 Jar。
+2. 将服务 Jar 文件名追加到 `src_java/package/jar_list.txt`，例如 `newservice.jar`。
+3. 在 `binary/java/bin/encrypt` 新增 `newservice.xml`，根节点使用 `<includes service="newservice">`。
+4. 在 XML 中列出压缩后必须留在服务 Jar 内的依赖。每项至少包含 `groupId`、`artifactId`、`version`，工具会匹配 `artifactId-version.jar`。
+5. 确认服务资源中需要 XJar 加密的内容满足当前 include：`/com/sunri/**`、`*.yaml`、`mapper/**.xml`、`*.yml`。
+6. 执行 `src_java/package/build.sh` 后检查 `binary/java/jar/x64/newservice.jar` 和 `binary/java/lib/common/newservice-requirements.txt`。
+7. 使用 `javacontrol.sh` 启动时，确认 `PRJHOME` 指向 `/home/liumangmang/IdeaProjects/PR7050/V1.00`，并传入正确的 common 依赖目录。
+
+### 7.1 建议检查命令
+
+```bash
+ls -lh /home/liumangmang/IdeaProjects/PR7050/V1.00/binary/java/jar/x64
+ls -lh /home/liumangmang/IdeaProjects/PR7050/V1.00/binary/java/lib/common
+```
+
+---
+PR7050 打包启动流程说明 · 基于当前仓库脚本整理 · 最后更新 2026-05