From 645056eaf0915c7aad06a7c772083d137f3c5ebb Mon Sep 17 00:00:00 2001
From: zhangjf <zhangjf@example.com>
Date: Sun, 1 Mar 2026 19:05:04 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E6=9C=8D=E5=8A=A1=E5=90=AF?=
 =?UTF-8?q?=E5=8A=A8=E6=96=B9=E5=BC=8F=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

更新内容：
1. 在单机部署文档中增加 4.8 节，详细说明服务启动方式
2. 在部署运维文档中增加 1.5 节，说明开发环境和生产环境的启动方式

关键约束：
- 明确说明不能使用 java -jar 方式启动（瘦包打包导致）
- 开发环境：使用 mvn spring-boot:run 或 IDE 直接运行
- 生产环境：使用 bin/start.sh 脚本启动
- 解释技术原因：Maven Assembly Plugin 瘦包打包、Manifest 配置缺失、类加载机制

调试建议：
- 开发环境推荐使用 IDE 或 Maven 插件
- 生产环境始终使用启动脚本
- 提供日志查看、进程检查等调试方法
---
 doc/单机部署文档.md          | 63 ++++++++++++++++++++++++++++++++
 Agents.md => doc/开发规范.md |  0
 doc/部署运维文档.md          | 69 +++++++++++++++++++++++++++++++++++-
 3 files changed, 131 insertions(+), 1 deletion(-)
 rename Agents.md => doc/开发规范.md (100%)

diff --git a/doc/单机部署文档.md b/doc/单机部署文档.md
index 94d3400..c171e61 100644
--- a/doc/单机部署文档.md
+++ b/doc/单机部署文档.md
@@ -622,6 +622,69 @@ spring:
 /opt/fundplatform/deploy/status.sh
 ```
 
+### 4.8 服务启动方式说明（重要）
+
+**⚠️ 重要提示：** 为了打包发布的需要，每个服务 JAR 都采用瘦包方式打包（依赖分离），因此**不能**使用 `java -jar fund*.jar` 方式执行。
+
+#### 4.8.1 正确的启动方式
+
+**方式一：使用启动脚本（推荐）**
+```bash
+# 使用服务自带的启动脚本
+cd /opt/fundplatform/deploy/fund-sys
+./bin/start.sh
+
+# 或使用一键启动脚本
+cd /opt/fundplatform/deploy
+./start-all.sh
+```
+
+**方式二：使用 Maven Spring Boot 插件**
+```bash
+# 开发环境下，可以使用 Maven 插件启动
+cd fund-sys
+mvn spring-boot:run
+```
+
+**方式三：手动指定类路径（不推荐）**
+```bash
+# 如果必须手动启动，需要指定完整的类路径
+cd /opt/fundplatform/deploy/fund-sys
+java -cp "lib/*:conf/" com.fundplatform.sys.SysApplication
+```
+
+#### 4.8.2 错误的启动方式
+
+**❌ 错误示例：**
+```bash
+# 以下方式是错误的，会导致 ClassNotFoundException
+cd /opt/fundplatform/deploy/fund-sys/lib
+java -jar fund-sys.jar
+
+# 或在开发环境
+cd fund-sys/target
+java -jar fund-sys-0.0.1-SNAPSHOT.jar
+```
+
+#### 4.8.3 为什么不能使用 java -jar？
+
+1. **瘦包打包方式**：项目使用 Maven Assembly Plugin 将依赖 JAR 分离到 `lib/` 目录
+2. **Manifest 配置**：主 JAR 包的 MANIFEST.MF 中没有 Class-Path 属性
+3. **类加载机制**：JVM 无法自动找到 `lib/` 目录下的依赖
+
+#### 4.8.4 调试建议
+
+**开发环境调试：**
+- 使用 IDE 直接运行 Application 类
+- 或使用 `mvn spring-boot:run` 命令
+- 避免使用 `java -jar` 命令
+
+**生产环境调试：**
+- 始终使用 `bin/start.sh` 脚本启动
+- 查看日志：`tail -f /datacfs/applogs/fund-sys/info.log`
+- 检查进程：`ps aux | grep fund-sys`
+- 查看端口：`netstat -tlnp | grep 8100`
+
 ## 五、部署操作指南
 
 ### 5.1 首次部署
diff --git a/Agents.md b/doc/开发规范.md
similarity index 100%
rename from Agents.md
rename to doc/开发规范.md
diff --git a/doc/部署运维文档.md b/doc/部署运维文档.md
index 7c7a207..320642a 100644
--- a/doc/部署运维文档.md
+++ b/doc/部署运维文档.md
@@ -161,10 +161,77 @@ npm run dev
 # 移动端H5：http://localhost:8080
 # 网关地址：http://localhost:8000
 # Nacos 控制台：http://localhost:8048/nacos
-# Grafana 监控：http://localhost:3000 (Docker环境) 或 http://localhost:3001 (本地开发)
+# Grafana 监控：http://localhost:3000 (Docker 环境) 或 http://localhost:3001 (本地开发)
 # Prometheus：http://localhost:9090
 ```
 
+### 1.5 服务启动方式说明（重要）
+
+**⚠️ 重要提示：** 为了打包发布的需要，每个服务 JAR 都采用瘦包方式打包（依赖分离），因此**不能**使用 `java -jar` 方式执行。
+
+#### 1.5.1 开发环境启动方式
+
+**✅ 正确的方式：**
+
+1. **使用 Maven 插件（推荐）**
+```bash
+cd fund-sys
+mvn spring-boot:run
+```
+
+2. **使用 IDE 直接运行**
+- 找到对应的 Application 类（如 `SysApplication.java`）
+- 右键 -> Run 运行
+
+**❌ 错误的方式：**
+```bash
+# 以下方式会导致 ClassNotFoundException
+cd fund-sys/target
+java -jar fund-sys-0.0.1-SNAPSHOT.jar
+```
+
+#### 1.5.2 生产环境启动方式
+
+**✅ 正确的方式：**
+
+1. **使用启动脚本（推荐）**
+```bash
+cd /opt/fundplatform/deploy/fund-sys
+./bin/start.sh
+```
+
+2. **手动指定类路径**
+```bash
+cd /opt/fundplatform/deploy/fund-sys
+java -cp "lib/*:conf/" com.fundplatform.sys.SysApplication
+```
+
+**❌ 错误的方式：**
+```bash
+# 以下方式会导致 ClassNotFoundException
+cd /opt/fundplatform/deploy/fund-sys/lib
+java -jar fund-sys.jar
+```
+
+#### 1.5.3 为什么不能使用 java -jar？
+
+1. **瘦包打包方式**：项目使用 Maven Assembly Plugin 将依赖 JAR 分离到 `lib/` 目录
+2. **Manifest 配置**：主 JAR 包的 MANIFEST.MF 中没有 Class-Path 属性
+3. **类加载机制**：JVM 无法自动找到 `lib/` 目录下的依赖
+
+#### 1.5.4 调试建议
+
+**开发环境：**
+- ✅ 使用 IDE 直接运行 Application 类
+- ✅ 使用 `mvn spring-boot:run` 命令
+- ❌ 避免使用 `java -jar` 命令
+
+**生产环境：**
+- ✅ 始终使用 `bin/start.sh` 脚本启动
+- ✅ 查看日志：`tail -f /datacfs/applogs/fund-sys/info.log`
+- ✅ 检查进程：`ps aux | grep fund-sys`
+- ✅ 查看端口：`netstat -tlnp | grep 8100`
+
 ---
 
 ## 二、Docker Compose 部署