JianAgent - Minecraft 服务器压测与管理平台

一站式 Minecraft 服务器压力测试与运维管理平台，基于 NestJS 11 + React 19 + Mineflayer 全栈架构，支持批量机器人压测、实时控制台、插件探针、会话管理与数据归档。

项目概览

• Monorepo — 使用 pnpm workspace 管理
• 5 个 TypeScript 包 + 1 个 Kotlin 插件（含 api / probe-plugin 两个子项目）
• 全栈技术栈 — NestJS 11（后端）+ React 19（前端）+ Mineflayer（机器人引擎）
• 测试覆盖 — 69 个测试文件，311 个测试用例

架构概览

jian-agent/
├── packages/
│   ├── server/          # 后端服务
│   ├── web/             # 前端 SPA
│   ├── bot-worker/      # 机器人工作进程
│   ├── shared-domain/   # 共享类型与 DTO
│   └── shared-protocol/ # WebSocket/IPC 协议定义
└── plugin/              # Kotlin Bukkit 探针插件
    ├── api/             # 插件 API 模块
    └── probe-plugin/    # Paper 探针插件实现

包名	说明
@jian-agent/server	NestJS 11 + Fastify + Drizzle ORM + SQLite — 提供 REST API、WebSocket 推送、PTY 终端、进程管理
@jian-agent/web	React 19 + Vite 6 + TailwindCSS 3 + Zustand 5 — 控制台 UI、仪表盘、会话管理
@jian-agent/bot-worker	Mineflayer 机器人工作进程 — 通过 IPC 与 server 通信，支持行为模板与调试模式
@jian-agent/shared-domain	共享类型定义、DTO、枚举、常量
@jian-agent/shared-protocol	WebSocket 事件与 IPC 消息协议定义
plugin/	Kotlin Bukkit 探针插件（Paper 1.20.4）— 采集服务器 TPS、玩家、插件状态并上报

功能列表

核心验收标准（SP1–SP10）

#	功能	说明
1	服务器配置	通过 Web UI 配置 MC 服务器路径、JVM 参数、端口
2	启停控制	一键启动 / 停止 / 重启 Minecraft 服务器进程
3	实时控制台	基于 xterm.js + node-pty 的实时终端，支持命令输入
4	进程健康监控	CPU、内存、运行时长实时监控与告警
5	插件探针	Bukkit 探针插件采集 TPS / 玩家列表 / 插件状态并推送
6	批量机器人	批量生成 Mineflayer 机器人连接服务器
7	机器人仪表盘	机器人列表、状态看板、实时连接数
8	压测会话	创建压测会话，配置阶段（phase）逐步加压
9	单 Bot 调试	选中单个机器人，实时查看视角、背包、聊天
10	日志与审计	操作日志、告警记录、审计追踪

进阶功能

• 启动模板 — 预设服务器启动配置，一键切换
• 定时停机 — 计划维护窗口，自动优雅关停
• 崩溃重启 — 进程异常退出后自动重启
• 阶段智能 — 基于 TPS/内存指标自动推进压测阶段
• 机器人分组 — 按角色分组管理机器人（如 PvP / 建造 / 挂机）
• 行为模板 — 预定义机器人行为脚本（走动、挖掘、PvP）
• 插件白名单动作 — 压测时自动执行插件命令（如 /stop、/save-all）
• Java 深度采样 — JFR/热点方法采样分析
• 终端权限与审计 — 终端操作权限控制与录屏回放
• 会话报告导出 — 压测报告 PDF/JSON 导出
• 数据归档 — 历史会话归档与清理
• 分布式 Worker — 多节点机器人 Worker 水平扩展

快速启动

环境要求

依赖	版本
Node.js	>= 20
pnpm	>= 9
JDK	>= 17（运行 Minecraft 服务器及编译 Kotlin 插件）

安装与启动

# 1. 安装依赖
pnpm install

# 2. 构建共享包（server/web 依赖它们）
pnpm build:shared

# 3. 启动后端（默认 :3400）
pnpm dev:server

# 4. 启动前端（默认 :5173）
pnpm dev:web

编译探针插件

cd plugin
./gradlew build
# 产物: probe-plugin/build/libs/*.jar

环境变量

变量	默认值	说明
JWT_SECRET	开发默认值	生产环境必须更改
PORT	3400	后端监听端口

项目结构

jian-agent/
├── package.json              # 根 workspace 脚本
├── pnpm-workspace.yaml       # pnpm workspace 配置
├── tsconfig.base.json        # 共享 TypeScript 配置
├── packages/
│   ├── server/               # NestJS 后端
│   │   └── src/
│   │       ├── auth/         # JWT 认证
│   │       ├── bot/          # 机器人管理
│   │       ├── session/      # 压测会话
│   │       ├── server-process/ # MC 进程管理
│   │       ├── pty/          # PTY 终端
│   │       ├── plugin-bridge/# 插件桥接
│   │       ├── metrics/      # 指标采集
│   │       ├── realtime/     # WebSocket 推送
│   │       ├── audit/        # 审计日志
│   │       ├── storage/      # 数据归档
│   │       ├── java-helper/  # Java 采样辅助
│   │       └── db/           # Drizzle ORM + SQLite
│   ├── web/                  # React 前端
│   │   └── src/
│   │       ├── pages/        # 页面组件
│   │       ├── features/     # 功能模块
│   │       ├── components/   # 通用组件
│   │       ├── stores/       # Zustand 状态
│   │       ├── ws/           # WebSocket 客户端
│   │       └── api/          # REST API 封装
│   ├── bot-worker/           # 机器人 Worker
│   │   └── src/
│   │       ├── behavior/     # 行为模板
│   │       ├── lifecycle/    # 生命周期管理
│   │       ├── debug/        # 调试模式
│   │       ├── registry/     # Bot 注册表
│   │       ├── reporter/     # 状态上报
│   │       └── ipc/          # IPC 通信
│   ├── shared-domain/        # 共享类型
│   │   └── src/
│   │       ├── dto/          # 数据传输对象
│   │       ├── enums/        # 枚举定义
│   │       └── constants/    # 常量
│   └── shared-protocol/      # 协议定义
│       └── src/
│           ├── bot-events.ts
│           └── alert-events.ts
├── plugin/                   # Kotlin Bukkit 插件
│   ├── api/                  # 插件 API
│   └── probe-plugin/         # Paper 探针实现
└── docs/                     # 设计文档与计划

技术栈

层	技术
后端框架	NestJS 11 + Fastify
数据库	SQLite + Drizzle ORM + better-sqlite3
认证	JWT (jsonwebtoken + bcrypt)
终端	node-pty + xterm.js
实时通信	WebSocket (ws)
前端框架	React 19 + React Router 7
构建工具	Vite 6
样式	TailwindCSS 3 + PostCSS
状态管理	Zustand 5
机器人引擎	Mineflayer 4
插件	Kotlin + Paper API 1.20.4
测试	Vitest 3 + JUnit 5
包管理	pnpm 9 workspace
语言	TypeScript 5.7 + Kotlin 1.9

测试

# 运行全部测试（5 个包，69 个文件，311 个用例）
pnpm test

# 并行运行
pnpm -r --parallel run test

# 单包测试
pnpm --filter @jian-agent/server test
pnpm --filter @jian-agent/web test
pnpm --filter @jian-agent/bot-worker test

# 监听模式
pnpm --filter @jian-agent/server test:watch

开发

# 开发模式
pnpm dev:server          # NestJS 热重载 :3400
pnpm dev:web             # Vite HMR :5173

# 构建
pnpm build               # 构建所有包
pnpm build:shared        # 仅构建共享包

# 类型检查
pnpm lint                # 所有包 tsc --noEmit

许可证

GNU GPLv3