# x-analyzer

**Repository Path**: luodeb/x-analyzer

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# x-analyzer

Electron + Vue 3 + TypeScript 打造的监控仪表盘桌面应用。

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Electron](https://img.shields.io/badge/Electron-33.4.11-9feaf9.svg)
![Vue](https://img.shields.io/badge/Vue-3.5.13-4fc08d.svg)

## 快速开始

### 环境要求

- Node.js >= 20

### 安装

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

# 安装依赖
npm install

# 复制环境变量配置
cp .env.example .env
# Windows: Copy-Item .env.example .env
```

### 开发

```bash
# 启动开发服务器
npm run dev

# 开发模式 + 打开 DevTools
npm run dev:debug
```

### 构建

```bash
# 构建应用
npm run build

# 预览生产构建
npm run preview
```

构建产物输出到 `out/` 目录。

## 项目结构

```
x-analyzer/
├── electron/                # Electron 主进程
│   ├── main.ts             # 主进程入口
│   ├── preload.ts          # 预加载脚本
│   ├── ipc-types.ts        # IPC 类型定义
│   ├── mount-manager.ts    # 磁盘镜像挂载管理
│   ├── service-manager.ts  # Prometheus 进程管理
│   └── tray.ts             # 系统托盘
├── src/                    # Vue 渲染进程
│   ├── main.ts             # 前端入口
│   ├── App.vue             # 根组件
│   ├── views/              # 页面视图
│   │   ├── Dashboard.vue   # 仪表盘
│   │   ├── Query.vue       # 自定义查询
│   │   └── Settings.vue    # 设置页
│   ├── components/         # 组件
│   ├── composables/        # 组合式函数
│   ├── adapters/           # 数据源适配器
│   │   ├── prometheusApi.ts  # Prometheus HTTP API 适配
│   │   └── types.ts          # 适配器类型定义
│   ├── config/             # 运行时配置
│   │   └── datasource.ts    # 数据源配置
│   ├── types/              # 共享类型
│   │   ├── panel.ts         # 查询面板类型
│   │   └── service.ts       # 服务状态类型
│   └── router/             # 路由配置
├── out/                    # 构建输出
└── resources/              # 静态资源
```

## 技术栈

- **框架**: Electron 33 + Vue 3 + TypeScript
- **构建**: electron-vite
- **UI**: Naive UI
- **图表**: ECharts 6
- **路由**: Vue Router
- **IPC**: Electron contextBridge

## 配置说明

### 环境变量

编辑 `.env` 文件配置 API：

```env
VITE_REQUEST_TIMEOUT_MS=10000
```

### 数据源模式

- `online`（在线连接）：连接远程 Prometheus 实例，地址通过配置指定
- `offline`（离线查询）：内嵌 Prometheus 服务，挂载本地 `disk.img` 镜像提供查询

### 内嵌 Prometheus 服务架构

目标平台：**Kylin OS V11 (ARM64/aarch64)**。非目标平台上服务功能自动禁用。

```
┌─────────────────────────────────────────────────┐
│  Electron Main Process                          │
│                                                 │
│  ┌──────────────┐  ┌──────────────────────────┐│
│  │ServiceManager│  │  MountManager            ││
│  │ - start()    │  │  - mountImage(imgPath)    ││
│  │ - stop()     │  │  - unmountImage()         ││
│  │ - status()   │  │  - isMounted()            ││
│  └──────┬───────┘  └──────┬───────────────────┘│
│         │                  │                    │
│         ▼                  ▼                    │
│  启动 prometheus      mount -o loop,ro          │
│  二进制进程            disk.img →               │
│  --storage.tsdb.path  /mnt/x-analyzer-data      │
└─────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────┐
│  Vue 渲染进程                                    │
│  prometheusApi.ts → http://127.0.0.1:19090      │
│  /api/v1/query_range?query=...                  │
└─────────────────────────────────────────────────┘
```

核心流程：App 启动 → MountManager 只读挂载 disk.img → ServiceManager 启动 prometheus → 前端通过 PromQL 查询数据 → App 退出时清理

### 自定义查询页面

"查询"页面允许用户通过指标下拉选择或手动输入 PromQL 来查询 Prometheus 数据，结果渲染为折线图。

功能特性：
- **指标下拉**：自动从 Prometheus `/api/v1/label/__name__/values` 获取所有可用指标，可搜索筛选
- **PromQL 输入**：选择指标后自动填充，支持手动编辑补充（加函数、过滤等）
- **多面板布局**：可添加多个面板同时查看不同指标，每个面板独立查询和渲染
- **面板操作**：支持折叠、展开、删除面板
- **配置持久化**：面板配置通过 IPC 保存到 `$userData/x-analyzer-panels.json`，重启后自动恢复
- **自动刷新**：从其他页面切回时自动重新查询

#### 服务状态机

```
IDLE → MOUNTING → MOUNTED → STARTING_PROM → RUNNING
  ↑                                 ↓
  └──── ERROR ←─────────────────────┘

RUNNING → STOPPING_PROM → UNMOUNTING → IDLE
```

| 状态 | 含义 |
|------|------|
| IDLE | 未启动 |
| MOUNTING | 正在挂载磁盘镜像 |
| MOUNTED | 已挂载 |
| STARTING_PROM | 正在启动 Prometheus |
| RUNNING | 运行中 |
| STOPPING_PROM | 正在停止 |
| UNMOUNTING | 正在卸载 |
| ERROR | 异常 |
| DISABLED | 当前平台不支持 |

#### IPC 频道

| 频道 | 方向 | 用途 |
|------|------|------|
| `SERVICE_STATUS` | 渲染→主 | 查询服务状态 |
| `START_SERVICE` | 渲染→主 | 挂载 + 启动 Prometheus |
| `STOP_SERVICE` | 渲染→主 | 停止 Prometheus + 卸载 |
| `GET_CONFIG` | 渲染→主 | 获取应用配置 |
| `SET_CONFIG` | 渲染→主 | 保存应用配置 |
| `GET_PANELS` | 渲染→主 | 获取查询面板配置 |
| `SET_PANELS` | 渲染→主 | 保存查询面板配置 |

#### 安装包（deb）注意事项

- postinst 创建 `/mnt/x-analyzer-data` 挂载点目录并写入 `/etc/sudoers.d/x-analyzer` 白名单（mount/umount/mkdir）
- prerm 卸载镜像并清理 sudoers
- 内嵌资源通过 electron-builder `extraResources` 打包：`bin/prometheus`、`conf/prometheus.yml`、`data/disk.img`

### 打包体积优化

Electron 打包时，`electron-vite` 的 `externalizeDepsPlugin()` 会将 `package.json` 中所有 `dependencies` 外部化并复制进 `app.asar` 的 `node_modules/`。但渲染进程依赖（如 `echarts`、`naive-ui`、`vue`、`vue-router`）已被 Vite 打包进 JS bundle，无需在 `node_modules` 中再保留一份。

优化措施：

1. **`electron.vite.config.ts`** — 在 `externalizeDepsPlugin()` 中排除渲染进程依赖，避免它们被打包进 `node_modules/`：
   ```ts
   externalizeDepsPlugin({ exclude: ['echarts', 'naive-ui', 'vue', 'vue-router'] })
   ```

2. **`package.json`** — 渲染进程依赖放在 `devDependencies`，仅保留主进程实际使用的 `electron-log` 在 `dependencies`。Vite 打包时从 `node_modules` 解析依赖，不受 `dependencies`/`devDependencies` 分类影响。

这两处配合可减少约 150MB 的冗余 `node_modules` 打包体积。

## 开发指南

### IPC 通信

预定义的 IPC 频道：

```typescript
// 获取配置
const config = await window.xAnalyzer.getConfig()

// 保存配置
await window.xAnalyzer.setConfig(newConfig)

// 查询服务状态
const status = await window.xAnalyzer.serviceStatus()

// 启动服务
await window.xAnalyzer.startService(imgPath?, password?)

// 停止服务
await window.xAnalyzer.stopService(password?)

// 获取查询面板配置
const panels = await window.xAnalyzer.getPanels()

// 保存查询面板配置
await window.xAnalyzer.setPanels(panels)
```

### 类型检查

```bash
# 仅检查前端代码（src/）
npm run typecheck

# 注意：Electron 主进程代码不会被 typecheck 检查
```

### 常见问题

**Electron 二进制下载失败**

项目已配置 `.npmrc` 使用 npmmirror 镜像。如果下载失败：

```bash
# 手动设置镜像后重新安装
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
npm install
```

验证安装成功：`node_modules/electron/path.txt` 和 `dist/` 目录应存在。

**Kylin OS 下 root 用户运行白屏**

Kylin OS 上以 `root` 用户运行 Electron 应用时，GPU 子进程无法通过 XCB 连接 X11 服务器（root 缺少 X11 认证 cookie），导致 `xcb_connect() failed, error 1` → `eglInitialize SwANGLE failed` → GPU 进程反复崩溃 → Chromium FATAL 退出（`GPU process isn't usable. Goodbye.`），最终窗口白屏。

代码层面已通过 `app.commandLine.appendSwitch('in-process-gpu')`（`electron/main.ts`）将 GPU 功能合并到主进程运行，绕过子进程 X11 认证问题。

若仍白屏，可在桌面用户的终端中授权 root 访问 X 服务器：

```bash
xhost +local:root

# 之后运行
npm run dev

# 恢复默认权限限制
xhost -local:root
```