# yj_devtool

**Repository Path**: chebin1214_admin/yj_devtool

## Basic Information

- **Project Name**: yj_devtool
- **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-08-20
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DevTools Desktop

桌面端开发工具箱，用于统一管理本地微服务的启动、停止、状态监控和日志查看。

## 技术栈

- **运行时**：Electron 33
- **前端**：Vue 3 + Vite 5 + Pinia + TypeScript
- **配置**：JSONC 格式（jsonc-parser），保留注释的读写
- **通信**：Electron IPC（无 HTTP 服务器，零端口占用）

## 快速开始

```bash
# 安装依赖
npm install

# 启动开发模式（Vite 热更新 + Electron 窗口）
npm run dev
```

启动后自动打开桌面窗口，默认端口 5173（仅开发模式）。

## 打包

打包分两步：先用 Vite 构建前端静态文件（输出到 `dist/`），再用 electron-builder 将 Electron 主进程 + 前端产物打成可执行文件。

以上命令已自动串联两步，直接执行即可。如需分步调试：

```bash
# 第一步：Vite 构建前端
npm run build:frontend

# 第二步：electron-builder 打包（三选一）
npx electron-builder --win portable   # Windows 单文件 exe
npx electron-builder --win --dir      # Windows 免安装目录
npx electron-builder --mac            # macOS dmg
```

| 一键命令 | 产物 | 说明 |
|----------|------|------|
| `npm run build:win` | `release/*-portable.exe` | Windows 单文件 exe，双击即用，不写注册表 |
| `npm run build:dir` | `release/win-unpacked/` | Windows 免安装目录，整个文件夹拷走即可 |
| `npm run build:mac` | `release/*.dmg` | macOS 安装包（需在 Mac 上执行） |

打包后的应用不启动 Vite，直接加载 `dist/index.html`，无端口占用。

## 功能概览

### 服务管理

- 通过 UI 注册/编辑/删除服务，支持后端自动发现（扫描 pom.xml）和前端手动添加
- 按服务 ID 启动/停止/重启/强制终止
- 分组操作（启动全部后端、停止全部前端）
- PID 持久化：应用重启后自动恢复上次运行的服务进程

### 环境变量清单

每个服务的环境变量以 `[{key, value, enabled}]` 数组形式管理：

- 勾选 → 启动时注入，取消勾选 → 不注入
- 状态持久化到配置文件，重启保持
- 提供全选/全不选快捷操作

### 状态监控

7 种服务状态：`RUNNING` / `STARTING` / `STOPPED` / `STUCK` / `FAILED` / `EXTERNAL` / `NO_CONFIG`

- 主进程定时 TCP 探测（默认 5 秒间隔），状态变更时 IPC 主动推送前端
- STUCK 状态自动处理：可配置 `auto-kill`（自动终止）或 `notify-only`（仅通知）

### 日志系统

- **双日志源**：工具启动的服务捕获 stdout/stderr，外部启动的服务 tail 日志文件
- 多标签查看（最多 8 个）、日志级别着色（ERROR/WARN/INFO/DEBUG）
- 搜索高亮、级别过滤、清屏、自动滚动
- 日志文件持久化 + 10MB 自动轮转

### 配置管理

所有配置集中在一个 `config.jsonc` 文件中：

- **配置路径**：`C:\Users\{用户名}\AppData\Roaming\devtools-desktop\config.jsonc`
- **等效环境变量**：`%APPDATA%\devtools-desktop\config.jsonc`
- dev 模式与打包安装后路径一致，配置互通

配置内容包括：

- 全局设置：轮询间隔、日志缓冲区、主题、退出策略
- 服务列表：端口、启动命令、环境变量、超时策略、健康检查
- 自定义端口监听
- 支持导入/导出、从 tasks.json 迁移

### 日志文件

日志持久化存储在 `%APPDATA%\devtools-desktop\logs\` 目录下，每个服务一个 `.log` 文件，超过 10MB 自动轮转。

- **日志路径**：`C:\Users\{用户名}\AppData\Roaming\devtools-desktop\logs\`
- 内存缓冲区行数由配置项 `logBufferSize` 控制（默认 2000，可自行修改）
- 外部启动的服务通过 tail 日志文件采集

### 其他

- 暗色/亮色主题切换
- 告警横幅（自动消失）
- 键盘快捷键（R 刷新、1-9 启动服务、ESC 关闭日志）
- 系统托盘（最小化到托盘、右键菜单）
- 全局快捷键 `Ctrl+Shift+D` 显示/隐藏窗口

## 项目结构

```
devtools-desktop/
├── electron/
│   ├── main.js                 # 主进程入口
│   ├── preload.js              # contextBridge IPC 封装
│   └── core/
│       ├── ConfigStore.js      # JSONC 配置读写
│       ├── ServiceManager.js   # 服务生命周期管理
│       ├── PortMonitor.js      # 端口状态监控（7 态状态机）
│       ├── LogCollector.js     # 日志采集（双源 + 环形缓冲）
│       ├── ProcessGuard.js     # 跨平台进程安全
│       ├── EventBus.js         # 内部事件总线
│       ├── BackendScanner.js   # 后端服务自动发现
│       └── ModuleRegistry.js   # 扩展模块注册
├── frontend/
│   └── src/
│       ├── stores/             # Pinia 状态管理
│       ├── views/              # 页面组件（仪表盘/日志/设置）
│       ├── components/         # UI 组件（卡片/标签/告警等）
│       ├── composables/        # 组合函数（IPC/日志流/快捷键/主题/告警）
│       └── styles/             # CSS 变量主题
├── scripts/
│   └── dev.js                  # Vite + Electron 双进程启动
└── package.json
```

## 退出策略

在设置页可配置应用退出时的行为：

- **keep-running**：退出后服务继续运行，下次启动工具时自动恢复管理
- **stop-all**：退出时停止所有由工具启动的服务