Add Linux machine-info GUID management

Add end-to-end support for reading/writing Linux machine-info and computing GUIDs.

Backend: - Introduce MachineInfoUtils (TS) for machine-info path lookup, ROT13 serialization, read/write/delete, backups, and MD5-based GUID computation. - Add a Python utility (guid.py) for CLI inspection, encode/decode, dump, and GUID computation. - Extend QQLogin API with new handlers: GetPlatformInfo, GetLinuxMAC, SetLinuxMAC, GetLinuxMachineId, ComputeLinuxGUID, GetLinuxMachineInfoBackups, CreateLinuxMachineInfoBackup, RestoreLinuxMachineInfoBackup, ResetLinuxDeviceID. Handlers include automatic backup behavior and error handling.

Router: Register new QQLogin routes for platform info and Linux machine-info operations.

Frontend: - Enhance guid_manager UI to detect platform and provide Linux-specific workflow (display machine-id, show/edit MAC, preview computed GUID via MD5, backup/restore/delete machine-info, and restart actions). - Add client-side MD5 (crypto-js) usage and new QQManager API methods to call the new backend endpoints.

This change enables cross-platform GUID management (Windows and Linux), includes CLI tooling for low-level inspection, and adds frontend workflows for Linux device-id management.

packages/napcat-webui-backend/src/api/QQLogin.ts

@@ -4,7 +4,8 @@ import { WebUiDataRuntime } from '@/napcat-webui-backend/src/helper/Data';
 import { WebUiConfig } from '@/napcat-webui-backend/index';
 import { isEmpty } from '@/napcat-webui-backend/src/utils/check';
 import { sendError, sendSuccess } from '@/napcat-webui-backend/src/utils/response';
-import { Registry20Utils } from '@/napcat-webui-backend/src/utils/guid';
+import { Registry20Utils, MachineInfoUtils } from '@/napcat-webui-backend/src/utils/guid';
+import os from 'node:os';
 
 // 获取 Registry20 路径的辅助函数
 const getRegistryPath = () => {
@@ -21,6 +22,19 @@ const getRegistryPath = () => {
   return Registry20Utils.getRegistryPath(dataPath);
 };
 
+// 获取 machine-info 路径的辅助函数 (Linux)
+const getMachineInfoPath = () => {
+  let dataPath = WebUiDataRuntime.getQQDataPath();
+  if (!dataPath) {
+    const oneBotContext = WebUiDataRuntime.getOneBotContext();
+    dataPath = oneBotContext?.core?.dataPath;
+  }
+  if (!dataPath) {
+    throw new Error('QQ data path not available yet');
+  }
+  return MachineInfoUtils.getMachineInfoPath(dataPath);
+};
+
 // 获取QQ登录二维码
 export const QQGetQRcodeHandler: RequestHandler = async (_, res) => {
   // 判断是否已经登录
@@ -265,4 +279,137 @@ export const QQRestartNapCatHandler: RequestHandler = async (_, res) => {
   }
 };
 
+// ============================================================
+// 平台信息 & Linux GUID 管理
+// ============================================================
+
+// 获取平台信息
+export const QQGetPlatformInfoHandler: RequestHandler = async (_, res) => {
+  return sendSuccess(res, { platform: os.platform() });
+};
+
+// 获取 Linux MAC 地址 (从 machine-info 文件读取)
+export const QQGetLinuxMACHandler: RequestHandler = async (_, res) => {
+  try {
+    const machineInfoPath = getMachineInfoPath();
+    const mac = MachineInfoUtils.readMac(machineInfoPath);
+    return sendSuccess(res, { mac });
+  } catch (e) {
+    return sendError(res, `Failed to get MAC: ${(e as Error).message}`);
+  }
+};
+
+// 设置 Linux MAC 地址 (写入 machine-info 文件)
+export const QQSetLinuxMACHandler: RequestHandler = async (req, res) => {
+  const { mac } = req.body;
+  if (!mac || typeof mac !== 'string') {
+    return sendError(res, 'MAC address is required');
+  }
+  try {
+    const machineInfoPath = getMachineInfoPath();
+    // 自动备份
+    try {
+      MachineInfoUtils.backup(machineInfoPath);
+    } catch { }
+
+    MachineInfoUtils.writeMac(machineInfoPath, mac);
+    return sendSuccess(res, { message: 'MAC set successfully' });
+  } catch (e) {
+    return sendError(res, `Failed to set MAC: ${(e as Error).message}`);
+  }
+};
+
+// 获取 Linux machine-id
+export const QQGetLinuxMachineIdHandler: RequestHandler = async (_, res) => {
+  try {
+    const machineId = MachineInfoUtils.readMachineId();
+    return sendSuccess(res, { machineId });
+  } catch (e) {
+    return sendError(res, `Failed to read machine-id: ${(e as Error).message}`);
+  }
+};
+
+// 计算 Linux GUID (用于前端实时预览)
+export const QQComputeLinuxGUIDHandler: RequestHandler = async (req, res) => {
+  const { mac, machineId } = req.body;
+  try {
+    // 如果没传 machineId，从 /etc/machine-id 读取
+    let mid = machineId;
+    if (!mid || typeof mid !== 'string') {
+      try {
+        mid = MachineInfoUtils.readMachineId();
+      } catch {
+        mid = '';
+      }
+    }
+    // 如果没传 mac，从 machine-info 文件读取
+    let macStr = mac;
+    if (!macStr || typeof macStr !== 'string') {
+      try {
+        const machineInfoPath = getMachineInfoPath();
+        macStr = MachineInfoUtils.readMac(machineInfoPath);
+      } catch {
+        macStr = '';
+      }
+    }
+    const guid = MachineInfoUtils.computeGuid(mid, macStr);
+    return sendSuccess(res, { guid, machineId: mid, mac: macStr });
+  } catch (e) {
+    return sendError(res, `Failed to compute GUID: ${(e as Error).message}`);
+  }
+};
+
+// 获取 Linux machine-info 备份列表
+export const QQGetLinuxMachineInfoBackupsHandler: RequestHandler = async (_, res) => {
+  try {
+    const machineInfoPath = getMachineInfoPath();
+    const backups = MachineInfoUtils.getBackups(machineInfoPath);
+    return sendSuccess(res, backups);
+  } catch (e) {
+    return sendError(res, `Failed to get backups: ${(e as Error).message}`);
+  }
+};
+
+// 创建 Linux machine-info 备份
+export const QQCreateLinuxMachineInfoBackupHandler: RequestHandler = async (_, res) => {
+  try {
+    const machineInfoPath = getMachineInfoPath();
+    const backupPath = MachineInfoUtils.backup(machineInfoPath);
+    return sendSuccess(res, { message: 'Backup created', path: backupPath });
+  } catch (e) {
+    return sendError(res, `Failed to backup: ${(e as Error).message}`);
+  }
+};
+
+// 恢复 Linux machine-info 备份
+export const QQRestoreLinuxMachineInfoBackupHandler: RequestHandler = async (req, res) => {
+  const { backupName } = req.body;
+  if (!backupName) {
+    return sendError(res, 'Backup name is required');
+  }
+  try {
+    const machineInfoPath = getMachineInfoPath();
+    MachineInfoUtils.restore(machineInfoPath, backupName);
+    return sendSuccess(res, { message: 'Restored successfully' });
+  } catch (e) {
+    return sendError(res, `Failed to restore: ${(e as Error).message}`);
+  }
+};
+
+// 重置 Linux 设备信息 (删除 machine-info)
+export const QQResetLinuxDeviceIDHandler: RequestHandler = async (_, res) => {
+  try {
+    const machineInfoPath = getMachineInfoPath();
+    // 自动备份
+    try {
+      MachineInfoUtils.backup(machineInfoPath);
+    } catch { }
+
+    MachineInfoUtils.delete(machineInfoPath);
+    return sendSuccess(res, { message: 'Device ID reset successfully (machine-info deleted)' });
+  } catch (e) {
+    return sendError(res, `Failed to reset Device ID: ${(e as Error).message}`);
+  }
+};
+
 

packages/napcat-webui-backend/src/router/QQLogin.ts

@@ -18,6 +18,15 @@ import {
   QQGetGUIDBackupsHandler,
   QQRestoreGUIDBackupHandler,
   QQCreateGUIDBackupHandler,
+  QQGetPlatformInfoHandler,
+  QQGetLinuxMACHandler,
+  QQSetLinuxMACHandler,
+  QQGetLinuxMachineIdHandler,
+  QQComputeLinuxGUIDHandler,
+  QQGetLinuxMachineInfoBackupsHandler,
+  QQCreateLinuxMachineInfoBackupHandler,
+  QQRestoreLinuxMachineInfoBackupHandler,
+  QQResetLinuxDeviceIDHandler,
 } from '@/napcat-webui-backend/src/api/QQLogin';
 
 const router: Router = Router();
@@ -56,4 +65,26 @@ router.post('/RestoreGUIDBackup', QQRestoreGUIDBackupHandler);
 // router:创建GUID备份
 router.post('/CreateGUIDBackup', QQCreateGUIDBackupHandler);
 
+// ============================================================
+// 平台信息 & Linux GUID 管理
+// ============================================================
+// router:获取平台信息
+router.post('/GetPlatformInfo', QQGetPlatformInfoHandler);
+// router:获取Linux MAC地址
+router.post('/GetLinuxMAC', QQGetLinuxMACHandler);
+// router:设置Linux MAC地址
+router.post('/SetLinuxMAC', QQSetLinuxMACHandler);
+// router:获取Linux machine-id
+router.post('/GetLinuxMachineId', QQGetLinuxMachineIdHandler);
+// router:计算Linux GUID
+router.post('/ComputeLinuxGUID', QQComputeLinuxGUIDHandler);
+// router:获取Linux machine-info备份列表
+router.post('/GetLinuxMachineInfoBackups', QQGetLinuxMachineInfoBackupsHandler);
+// router:创建Linux machine-info备份
+router.post('/CreateLinuxMachineInfoBackup', QQCreateLinuxMachineInfoBackupHandler);
+// router:恢复Linux machine-info备份
+router.post('/RestoreLinuxMachineInfoBackup', QQRestoreLinuxMachineInfoBackupHandler);
+// router:重置Linux设备信息
+router.post('/ResetLinuxDeviceID', QQResetLinuxDeviceIDHandler);
+
 export { router as QQLoginRouter };

packages/napcat-webui-backend/src/utils/guid.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import crypto from 'node:crypto';
 import { protectData, unprotectData } from 'napcat-dpapi';
 
 const GUID_HEADER = Buffer.from([0x00, 0x00, 0x00, 0x14]);
@@ -114,3 +115,161 @@ export class Registry20Utils {
     }
   }
 }
+
+// ============================================================
+// Linux machine-info 工具类
+// ============================================================
+
+/**
+ * ROT13 编解码 (自逆运算)
+ * 字母偏移13位，数字和符号不变
+ */
+function rot13 (s: string): string {
+  return s.replace(/[a-zA-Z]/g, (c) => {
+    const base = c <= 'Z' ? 65 : 97;
+    return String.fromCharCode(((c.charCodeAt(0) - base + 13) % 26) + base);
+  });
+}
+
+/**
+ * Linux 平台 machine-info 文件工具类
+ *
+ * 文件格式 (逆向自 machine_guid_util.cc):
+ *   [4字节 BE uint32 长度 N] [N字节 ROT13 编码的 MAC 字符串]
+ *   - MAC 格式: xx-xx-xx-xx-xx-xx (17 字符)
+ *   - ROT13: 字母偏移13位, 数字和 '-' 不变
+ *
+ * GUID 生成算法:
+ *   GUID = MD5( /etc/machine-id + MAC地址 )
+ */
+export class MachineInfoUtils {
+  /**
+   * 获取 machine-info 文件路径
+   */
+  static getMachineInfoPath (dataPath: string): string {
+    return path.join(dataPath, 'nt_qq', 'global', 'nt_data', 'msf', 'machine-info');
+  }
+
+  /**
+   * 从 machine-info 文件读取 MAC 地址
+   */
+  static readMac (machineInfoPath: string): string {
+    if (!fs.existsSync(machineInfoPath)) {
+      throw new Error('machine-info file not found');
+    }
+
+    const data = fs.readFileSync(machineInfoPath);
+
+    if (data.length < 4) {
+      throw new Error(`machine-info data too short: ${data.length} < 4 bytes`);
+    }
+
+    const length = data.readUInt32BE(0);
+
+    if (length >= 18) {
+      throw new Error(`MAC string length abnormal: ${length} >= 18`);
+    }
+
+    if (data.length < 4 + length) {
+      throw new Error(`machine-info data incomplete: need ${4 + length} bytes, got ${data.length}`);
+    }
+
+    const rot13Str = data.subarray(4, 4 + length).toString('ascii');
+    return rot13(rot13Str);
+  }
+
+  /**
+   * 将 MAC 地址写入 machine-info 文件
+   */
+  static writeMac (machineInfoPath: string, mac: string): void {
+    mac = mac.trim().toLowerCase();
+
+    // 验证 MAC 格式: xx-xx-xx-xx-xx-xx
+    if (!/^[0-9a-f]{2}(-[0-9a-f]{2}){5}$/.test(mac)) {
+      throw new Error('Invalid MAC format, must be xx-xx-xx-xx-xx-xx');
+    }
+
+    const encoded = rot13(mac);
+    const length = encoded.length;
+    const buf = Buffer.alloc(4 + length);
+    buf.writeUInt32BE(length, 0);
+    buf.write(encoded, 4, 'ascii');
+
+    // 确保目录存在
+    const dir = path.dirname(machineInfoPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(machineInfoPath, buf);
+  }
+
+  /**
+   * 读取 /etc/machine-id
+   */
+  static readMachineId (): string {
+    const machineIdPath = '/etc/machine-id';
+    if (!fs.existsSync(machineIdPath)) {
+      throw new Error('/etc/machine-id not found');
+    }
+    return fs.readFileSync(machineIdPath, 'utf-8').trim();
+  }
+
+  /**
+   * 计算 Linux GUID = MD5(machine-id + MAC)
+   */
+  static computeGuid (machineId: string, mac: string): string {
+    const md5 = crypto.createHash('md5');
+    md5.update(machineId, 'ascii');
+    md5.update(mac, 'ascii');
+    return md5.digest('hex');
+  }
+
+  /**
+   * 获取备份列表
+   */
+  static getBackups (machineInfoPath: string): string[] {
+    const dir = path.dirname(machineInfoPath);
+    const baseName = path.basename(machineInfoPath);
+    if (!fs.existsSync(dir)) return [];
+
+    return fs.readdirSync(dir)
+      .filter(f => f.startsWith(`${baseName}.bak.`))
+      .sort()
+      .reverse();
+  }
+
+  /**
+   * 创建备份
+   */
+  static backup (machineInfoPath: string): string {
+    if (!fs.existsSync(machineInfoPath)) {
+      throw new Error('machine-info file does not exist');
+    }
+    const timestamp = new Date().toISOString().replace(/[-:T.]/g, '').slice(0, 14);
+    const backupPath = `${machineInfoPath}.bak.${timestamp}`;
+    fs.copyFileSync(machineInfoPath, backupPath);
+    return backupPath;
+  }
+
+  /**
+   * 恢复备份
+   */
+  static restore (machineInfoPath: string, backupFileName: string): void {
+    const dir = path.dirname(machineInfoPath);
+    const backupPath = path.join(dir, backupFileName);
+    if (!fs.existsSync(backupPath)) {
+      throw new Error('Backup file not found');
+    }
+    fs.copyFileSync(backupPath, machineInfoPath);
+  }
+
+  /**
+   * 删除 machine-info
+   */
+  static delete (machineInfoPath: string): void {
+    if (fs.existsSync(machineInfoPath)) {
+      fs.unlinkSync(machineInfoPath);
+    }
+  }
+}