# fars_deploy

**Repository Path**: openaddr/fars_deploy

## Basic Information

- **Project Name**: fars_deploy
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-26
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FarsDeploy - Java应用自动部署工具

FarsDeploy 是一个用 Rust 编写的 Java 应用自动部署工具，用于自动化完成从 Maven 构建到远程服务器部署的完整流程。

## 功能特性

- ✅ 自动执行 Maven 构建（跳过测试）
- ✅ 收集并压缩构建产物
- ✅ 使用 SFTP 上传到远程服务器
- ✅ 多用户切换支持（sopuser → ossuser → ossadm）
- ✅ 自动备份原始文件
- ✅ 智能替换 JAR 包和目录
- ✅ 自动重启 Java 服务
- ✅ 详细的日志记录
- ✅ **.env 文件配置支持**
- ✅ **参数可选，支持交互式输入**
- ✅ **deploy.sh 脚本嵌入到 exe 中，单文件部署**
- ✅ **构建产物自动验证**
- ✅ **友好的错误提示和终端保持打开**

## 系统要求

- Rust 1.70 或更高版本
- Maven 3.x
- 远程服务器需要支持 SSH/SFTP 连接
- 远端服务器需要有以下用户：
  - `sopuser`：用于文件上传
  - `ossuser`：用于文件操作
  - `ossadm`：用于服务重启

## 安装

### 从源码构建

```bash
# 克隆项目
git clone <repository-url>
cd fars_deploy

# 构建 Release 版本
cargo build --release

# 编译后的可执行文件位于：
# Windows: target\release\fars_deploy.exe
# 或 target/release\fars_deploy (Linux/macOS)
```

### 使用 cargo 安装

```bash
cargo install --path .
```

## 使用方法

### 快速开始

```bash
# 编译 Release 版本
cargo build --release

# 运行部署工具
.\target\release\fars_deploy.exe
```

### 命令行参数

```bash
fars_deploy.exe [OPTIONS]
```

### 参数说明

所有参数都是可选的，程序会按照以下优先级获取参数：

| 参数 | 短参数 | 长参数 | 默认值 | 说明 |
|------|---------|---------|---------|------|
| 项目路径 | `-p` | `--project-path` | `.` (当前目录) | 项目根目录路径 |
| 远程IP | `-r` | `--remote-ip` | 无 | 远端服务器 IP 地址 |
| 密码 | `-w` | `--password` | 无 | 远端用户密码（sopuser/ossuser/ossadm 共用） |

### 参数获取优先级

程序按照以下优先级获取参数：

1. **命令行参数**（最高优先级）
2. **.env 文件配置**

### .env 文件配置

在项目根目录下创建 `.env` 文件，配置以下内容：

```bash
# 项目路径（可选，默认为当前目录）
PROJECT_PATH=/path/to/project

# 远程服务器 IP 地址
REMOTE_IP=192.168.1.100

# 远端用户密码（sopuser/ossuser/ossadm 共用）
PASSWORD=your_password
```

**注意**：
- `.env` 文件中的配置会被命令行参数覆盖
- 如果命令行和 `.env` 都没有提供，程序会提示用户输入
- 支持 `#` 开头的注释行

### 使用示例

#### 示例 1：使用命令行参数

```bash
fars_deploy.exe --project-path "D:\Data\IdeaProjects\FarsFrontendService" --remote-ip "192.168.1.100" --password "your_password"
```

#### 示例 2：使用 .env 文件

```bash
# 在项目目录下创建 .env 文件
# 然后直接运行
fars_deploy.exe
```

#### 示例 3：混合使用（命令行覆盖 .env）

```bash
# .env 文件中有 REMOTE_IP=192.168.1.100
# 使用命令行参数覆盖 IP 地址
fars_deploy.exe --remote-ip 192.168.1.200
```

#### 示例 4：交互式输入

```bash
# 不提供任何参数，程序会提示输入
fars_deploy.exe
# 程序会提示输入 IP 地址和密码
```

#### 示例 5：使用短参数

```bash
fars_deploy.exe -p . -r 192.168.1.100 -w your_password
```

### 部署流程

1. **解析命令行参数**：验证项目路径、IP 地址和密码
   - 支持从命令行、.env 文件或交互式输入获取参数
   - 参数验证失败时会显示友好的错误提示和配置指导

2. **执行 Maven 构建**：在项目根目录执行 `mvn clean` 然后 `mvn install -DskipTests`

3. **验证构建产物**：检查 4 个构建产物是否生成成功
   - 验证失败会报错并中断部署流程

4. **收集构建产物**：将构建产物复制到临时目录

5. **压缩构建产物**：将所有产物压缩为 `Fars.zip`

6. **上传文件**：使用 sopuser 通过 SFTP 上传到 `/home/sopuser/`

7. **执行文件替换**：使用 sopuser 连接，通过 `su` 命令切换到 ossuser 执行：
   - 解压 ZIP 文件到 `/home/sopuser/Fars/`
   - 上传并执行部署脚本（deploy.sh 已嵌入到 exe 中）
   - 修改目标目录权限（chmod -R 750）
   - 备份原始文件（使用时间戳命名）
   - 替换目标文件/目录
   - 清理临时文件（`/home/sopuser/Fars.zip` 和 `/home/sopuser/Fars`）

8. **重启服务**：使用 sopuser 连接，通过 `su` 命令切换到 ossadm 执行：
   - 加载环境配置（`engr_profile.sh`）
   - 重启 Java 服务（`ipmc_adm -cmd restartapp`）
   - 等待服务启动（10 秒）

9. **清理临时文件**：删除本地临时文件

**重要说明**：
- 程序仅使用 sopuser 进行 SSH 连接
- ossuser 和 ossadm 通过 `su` 命令切换访问
- 这种架构确保了在只有 sopuser 有 SSH 权限的环境中也能正常工作
- deploy.sh 脚本已嵌入到 exe 中，无需单独分发

### 终端行为

- **成功时**：显示部署成功信息 → 直接退出
- **失败时**：显示详细错误信息 → 暂停等待用户按键 → 退出

## 构建产物

程序会自动处理以下 4 个构建产物：

1. `model/target/FarsFrontendServiceApp.jar`
2. `website-service/target/ROOT/WEB-INF/classes`
3. `website-service/target/ROOT/WEB-INF/validate`
4. `website-service-common/target/farsfrontendservice-website-service-common-*.jar`（使用glob模式匹配任意版本号）

## 远端目标路径

构建产物将被部署到以下远端路径：

| 构建产物 | 远端目标路径 |
|---------|-------------|
| FarsFrontendServiceApp.jar | /opt/cloud/MAE/apps/FarsFrontendService/webapps/ROOT/WEB-INF/lib/farsfrontendservice-model*.jar |
| classes | /opt/cloud/MAE/apps/FarsFrontendService/webapps/ROOT/WEB-INF/classes |
| validate | /opt/cloud/MAE/apps/FarsFrontendService/webapps/ROOT/WEB-INF/validate |
| website-service-common-*.jar | /opt/cloud/MAE/apps/FarsFrontendService/webapps/ROOT/WEB-INF/lib/farsfrontendservice-website-service-common-*.jar |

## 日志输出

程序会输出详细的日志信息，包括：

- 每个步骤的执行状态
- 文件操作详情
- 远程命令执行结果
- 错误信息（如果有）

## 错误处理

程序会在以下情况停止执行并报错：

- 项目路径不存在或不是有效的 Maven 项目
- Maven 构建失败
- 构建产物缺失
- SSH/SFTP 连接失败
- 远端文件操作失败
- 服务重启失败

**参数验证失败时**，程序会显示：
- 详细的错误信息
- 配置参数的多种方式指导
- 提示使用 `--help` 查看详细帮助

## 安全建议

- 不要在命令行历史中记录密码
- 使用 .env 文件存储密码（避免在命令行中明文传输）
- 确保 SSH 密钥安全
- 将 .env 文件添加到 .gitignore 避免敏感信息泄露

## 项目结构

```
fars_deploy/
├── Cargo.toml              # 项目配置文件
├── README.md               # 项目说明文档
├── deploy.sh               # 部署脚本（已嵌入到 exe 中）
├── src/
│   ├── main.rs             # 主程序入口
│   ├── cli.rs              # 命令行参数解析
│   ├── maven.rs            # Maven 构建模块
│   ├── file.rs             # 文件处理模块
│   ├── ssh.rs              # SSH/SFTP 模块
│   ├── service.rs          # 服务控制模块
│   └── logger.rs          # 日志模块
└── docs/
    └── architecture.md     # 架构设计文档
```

## 开发

### 运行测试

```bash
cargo test
```

### 检查代码

```bash
cargo check
```

### 格式化代码

```bash
cargo fmt
```

### 运行 Clippy

```bash
cargo clippy
```

## 故障排除

### Maven 构建失败

- 检查 Maven 是否正确安装
- 确认项目根目录下存在 `pom.xml`
- 检查网络连接和 Maven 依赖下载

### SSH 连接失败

- 确认远端服务器 IP 地址正确
- 检查网络连接
- 确认用户名和密码正确
- 检查 SSH 服务是否运行

### 文件上传失败

- 确认 sopuser 有写入权限
- 检查磁盘空间
- 确认网络连接稳定

### 服务重启失败

- 确认 ossadm 有重启权限
- 检查服务管理命令是否正确
- 查看服务日志排查问题

### 参数配置问题

- 检查 .env 文件格式是否正确
- 确认参数名称拼写正确（PROJECT_PATH、REMOTE_IP、PASSWORD）
- 使用 `--help` 查看所有可用参数

## 版本历史

### v0.1.5 (2026-02-02)
**新增功能**：
- ✨ 使用glob模式匹配支持任意版本号的jar文件
- ✨ 添加构建产物glob模式匹配功能

**改进**：
- 🔧 优化构建产物路径配置，使用通配符匹配版本号
- 🔧 修复clippy::never_loop警告，优化代码质量

**修复**：
- 🐛 修复构建产物版本号硬编码问题

### v0.1.4 (2026-01-30)
**修复**：
- 🐛 修复 Maven 构建命令：从 `mvn clean package -DskipTests` 改为 `mvn clean` 然后 `mvn install -DskipTests`
- 🐛 修复终端行为：成功时直接退出，失败时暂停等待用户按键
- 🐛 修复项目结构文档：删除不存在的 `remote.rs` 文件
- 🐛 修复文档结构：删除不存在的 `sudo-setup.md` 和 `sudo-implementation-summary.md` 文件

### v0.1.3 (2025-01-28)
**新增功能**：
- ✨ 添加 .env 文件配置支持
- ✨ 项目路径参数可选，默认为当前目录
- ✨ 远程 IP 和密码参数可选，支持交互式输入
- ✨ 参数获取优先级：命令行 > .env > 交互式输入
- ✨ 添加构建产物自动验证功能
- ✨ 添加友好的错误提示和配置指导
- ✨ deploy.sh 脚本嵌入到 exe 中，实现单文件部署
- ✨ 终端保持打开，方便查看错误信息
- 🐛 修复代码重复问题，提取通用函数

**改进**：
- 🔧 优化临时文件管理，使用 /home/sopuser/Fars 目录
- 🔧 简化错误处理逻辑
- 🔧 提升用户体验，减少必需参数

### v0.1.2 (2025-01-26)
**修复**：
- 修复 ZIP 文件路径分隔符问题：使用平台特定的路径分隔符（`std::path::MAIN_SEPARATOR`），确保在 Windows 上创建的 ZIP 文件在 Linux 上解压时路径正确
- 修复 SSH 连接架构问题：程序仅使用 sopuser 进行 SSH 连接，通过 `su` 命令切换到 ossuser 和 ossadm 执行操作，确保在只有 sopuser 有 SSH 权限的环境中也能正常工作

### v0.1.1 (2025-01-26)
**初始版本**：
- 实现完整的 Maven 构建流程
- 实现构建产物收集和压缩
- 实现 SFTP 文件上传
- 实现多用户切换支持
- 实现自动备份和文件替换
- 实现 Java 服务自动重启
- 实现详细的日志记录

### v0.1.0 (2025-01-25)
**初始版本**：
- 实现完整的 Maven 构建流程
- 实现构建产物收集和压缩
- 实现 SFTP 文件上传
- 实现多用户切换支持
- 实现自动备份和文件替换
- 实现 Java 服务自动重启
- 实现详细的日志记录

## 许可证

本项目采用 MIT 许可证。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

如有问题或建议，请联系项目维护者。


## 路线图

ossadm@OSSM-1:/home/sopuser>. /opt/cloud/manager/bin/engr_profile.sh&&ipmc_adm -cmd statusapp -nodeip global | grep FarsFrontendService
farsfrontendservice-11-0            farsfrontendservice             FarsFrontendService             MAE              cluster        172.28.129.184   46570   RUNNING             
farsfrontendservice-8-0             farsfrontendservice             FarsFrontendService             MAE              cluster        172.28.129.181   232590  RUNNING             
farsfrontendservice-9-0             farsfrontendservice             FarsFrontendService             MAE              cluster        172.28.129.182   311233  RUNNING             
farsfrontendservice-10-0            farsfrontendservice             FarsFrontendService             MAE              cluster        172.28.129.183   91447   RUNNING