# ferryman2

**Repository Path**: jcown/ferryman2

## Basic Information

- **Project Name**: ferryman2
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-04
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Ferryman V2.0

<div align="center">

**面向信创环境的高性能数据交换网关**

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Java](https://img.shields.io/badge/Java-21-orange.svg)](https://openjdk.org/projects/jdk/21/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.5-brightgreen.svg)](https://spring.io/projects/spring-boot)

[在线文档](./docs/) | [快速开始](#快速开始) | [贡献指南](./CONTRIBUTING.md) | [English](./README.en.md)

</div>

---

## Recent Changes

### v2.0.0 - Node Management Redesign (2026-03-09)

**Breaking Change**: "传输管理" (Transfer Management) 模块已重构为"节点管理" (Node Management)。

- ✨ **新的节点抽象**: 统一抽象 Runner + MQ 源 + 队列配置
- ✨ **节点角色**: 中心节点（CENTER）和分节点（EDGE）的逻辑角色区分
- ✨ **简化的任务创建**: 通过选择节点而非配置复杂的队列映射
- 📚 **用户指南**: [节点管理功能文档](./ferryman-web/docs/features/node-management.md)
- 🔄 **数据迁移**: [数据迁移脚本](./ferryman-admin/scripts/migrate-to-nodes.sql)

**迁移说明**:
- 现有传输对象会自动迁移到节点
- 旧路由 `/config/transfer-management` 重定向到 `/config/node-management`
- 旧数据保留3个月，建议在此期间完成验证和切换

---

## 项目简介

Ferryman 是一款面向**信创环境**的高性能数据交换网关，支持国产消息中间件（TongLink/Q）与文件系统之间的可靠数据传输。采用**控制面与数据面分离**的云原生架构，具备虚拟线程优化、原子落盘、断点续传等企业级特性。

### 核心特性

| 特性 | 描述 |
|------|------|
| 🚀 **Java 21 虚拟线程** | 基于 Virtual Threads 的高并发任务执行，大幅提升吞吐量 |
| 🏗️ **控制面/数据面分离** | Admin 控制面 + Runner 数据面架构，支持水平扩展 |
| 🔒 **原子落盘** | 文件写入采用原子操作，确保数据一致性 |
| 📡 **断点续传** | 基于位点的传输恢复机制，网络中断后自动续传 |
| 🇨🇳 **信创环境支持** | 原生支持达梦 DM8、TongLink/Q 等国产化组件 |
| 📊 **实时监控** | gRPC 通信 + Actuator 指标，完整的运维可观测性 |

---

## 系统架构

```mermaid
graph TB
    subgraph "控制面 (Admin)"
        A[Admin gRPC Server] --> B[Admin Service]
        B --> C[(达梦 DM8)]
        B --> D[任务调度器]
        B --> E[Runner 注册中心]
    end
    
    subgraph "数据面 (Runner)"
        F[Runner gRPC Client] --> G[Runner Core]
        G --> H[(H2 本地库)]
        G --> I[任务执行器]
        I --> J[MQ 适配器]
        I --> K[文件处理器]
    end
    
    subgraph "外部系统"
        L[TongLink/Q]
        M[文件系统]
    end
    
    A <-->|gRPC 心跳/配置| F
    J <-->|消息收发| L
    K <-->|文件读写| M
    
    style A fill:#4A90D9
    style F fill:#67C23A
```

### 架构说明

- **Admin（控制面）**：负责任务编排、配置管理、Runner 节点监控
- **Runner（数据面）**：负责实际的数据传输任务执行
- **gRPC 通信**：Admin 与 Runner 之间通过 gRPC 进行心跳、配置同步、日志上报
- **数据库**：Admin 使用达梦 DM8（生产）/ H2（开发），Runner 使用 H2 本地库

---

## 快速开始

### 环境要求

| 组件 | 版本要求 |
|------|----------|
| JDK | 21+ |
| Maven | 3.9+ |
| Node.js | 18+ (仅 Web 控制台) |
| 达梦 DM8 | 8.1.3+ (可选，生产环境) |

### 1. 克隆项目

```bash
git clone https://gitee.com/your-username/ferryman.git
cd ferryman
```

### 2. 配置数据库

复制配置模板：

```bash
# Admin 配置
cp ferryman-admin/ferryman-admin-grpc/src/main/resources/config/application.yml.example \
   ferryman-admin/ferryman-admin-grpc/src/main/resources/config/application.yml

# Runner 配置
cp ferryman-runner/ferryman-runner-grpc/src/main/resources/config/application.yml.example \
   ferryman-runner/ferryman-runner-grpc/src/main/resources/config/application.yml
```

编辑配置文件，替换 `YOUR_*_HERE` 占位符：

```yaml
# 示例：Admin 数据库配置
spring:
  datasource:
    url: jdbc:dm://localhost:5236/FERRYMAN
    username: ${DB_USERNAME:ferryman}
    password: ${DB_PASSWORD:your_password_here}
```

### 3. 编译项目

```bash
mvn clean package -DskipTests
```

### 4. 启动服务

```bash
# 解压 Admin
cd ferryman-admin/ferryman-admin-grpc/target
unzip ferryman-admin-grpc-1.0.0-SNAPSHOT.zip
cd ferryman-admin-grpc-1.0.0-SNAPSHOT

# 启动 Admin
bin/startup.bat  # Windows
bin/startup.sh   # Linux/Mac

# 解压 Runner
cd ../../../ferryman-runner/ferryman-runner-grpc/target
unzip ferryman-runner-grpc-1.0.0-SNAPSHOT.zip
cd ferryman-runner-grpc-1.0.0-SNAPSHOT

# 启动 Runner
bin/startup.bat  # Windows
bin/startup.sh   # Linux/Mac
```

### 5. 访问服务

| 服务 | 地址 |
|------|------|
| Admin HTTP | http://localhost:8080 |
| Admin gRPC | localhost:9096 |
| Runner HTTP | http://localhost:9090 |
| Web 控制台 | http://localhost:5173 (开发模式) |

---

## 打包部署

### 目录结构

```
ferryman-{admin|runner}-grpc-1.0.0-SNAPSHOT/
├── bin/           # 运维脚本（startup/shutdown/status）
├── config/        # 外部配置文件
├── lib/           # JAR 依赖库
├── logs/          # 运行时日志
├── data/          # 数据目录（H2 数据库/本地缓存）
├── temp/          # 临时文件（原子落盘缓冲）
└── backup/        # 备份目录（发送成功后归档）
```

### 运维脚本

| 脚本 | 功能 |
|------|------|
| `startup.bat/sh` | 启动服务（自动检测 Java 21、创建目录、配置 JVM 参数） |
| `shutdown.bat/sh` | 优雅停机（SIGTERM + 超时强制终止） |
| `status.bat/sh` | 状态查询（进程 PID、HTTP 端点、API 详细状态） |

### JVM 参数

```bash
-Xms512m -Xmx1g                    # 内存配置
--enable-preview                   # 启用预览特性（虚拟线程）
-XX:+UseZGC                        # 使用 ZGC 垃圾回收器
-Djdk.virtualThreadScheduler.parallelism=4  # 虚拟线程并行度
-Dspring.config.location=../config/application.yml  # 外部配置
```

---

## 项目结构

```
ferryman/
├── ferryman-common/               # 公共模块
│   ├── ferryman-common-core/      # 核心工具类
│   ├── ferryman-common-protocol/  # Protobuf 协议定义
│   └── ferryman-common-grpc/      # gRPC 公共组件
├── ferryman-admin/                # 控制面
│   ├── ferryman-admin-service/    # 业务服务层
│   ├── ferryman-admin-api/        # REST API 层
│   └── ferryman-admin-grpc/       # gRPC 服务入口
├── ferryman-runner/               # 数据面
│   ├── ferryman-runner-core/      # 核心执行引擎
│   ├── ferryman-runner-tasks/     # 任务类型实现
│   └── ferryman-runner-grpc/      # gRPC 客户端
├── ferryman-web/                  # Vue 3 Web 控制台
├── docs/                          # 文档
│   ├── design/                    # UI 设计文档
│   ├── api/                       # API 文档
│   └── deployment/                # 部署文档
├── LICENSE                        # Apache 2.0 许可证
├── CONTRIBUTING.md                # 贡献指南
└── README.md                      # 本文件
```

---

## 技术栈

### 后端

| 分类 | 技术 | 版本 |
|------|------|------|
| 核心框架 | Spring Boot | 3.2.5 |
| Java 版本 | OpenJDK | 21 |
| RPC 框架 | gRPC | 1.61.1 |
| ORM 框架 | MyBatis-Plus | 3.5.5 |
| 数据库 | 达梦 DM8 / H2 | 8.1.3 / 2.2.224 |
| 认证授权 | Sa-Token | 1.37.0 |
| 工具类 | Hutool | 5.8.26 |

### 前端

| 分类 | 技术 | 版本 |
|------|------|------|
| 框架 | Vue | 3.4.x |
| UI 库 | Arco Design Vue | 2.x |
| 构建 | Vite | 5.x |
| 状态管理 | Pinia | 2.x |

---

## 开发指南

### 本地开发

```bash
# 启动后端（开发模式）
cd ferryman-admin/ferryman-admin-grpc
mvn spring-boot:run

cd ferryman-runner/ferryman-runner-grpc
mvn spring-boot:run

# 启动前端
cd ferryman-web
npm install
npm run dev
```

### 运行测试

```bash
mvn test
```

### 代码规范

请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解：
- 代码风格规范
- Commit Message 格式
- 分支管理策略
- Pull Request 流程

---

## 贡献

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'feat: add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 提交 Pull Request

详见 [CONTRIBUTING.md](./CONTRIBUTING.md)

---

## 许可证

本项目基于 [Apache License 2.0](./LICENSE) 开源协议。

---

## 联系方式

- 问题反馈：[Gitee Issues](https://gitee.com/your-username/ferryman/issues)
- 邮件：ferryman@example.com

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给一个 Star！⭐**

</div>