dify_market_manager_gui/SINGLE_INSTANCE_FIX.md

单实例锁问题修复说明

问题描述

运行 npm run dev 时，程序检测到已有实例运行并退出，但任务管理器中并没有看到已启动的实例：

13:05:39.374 > 单实例锁检查结果: false
13:05:39.375 > 检测到已有实例运行，退出当前实例
Process finished with exit code 0

问题原因分析

1. 锁文件未正确清理：之前的实例异常退出时，单实例锁文件没有被正确删除
2. 进程检查不完善：只检查了锁文件存在，没有验证对应的进程是否还在运行
3. 锁文件位置不明确：Electron 的单实例锁可能存储在不同位置
4. 异常退出处理不当：应用崩溃或强制关闭时，锁文件没有被清理

修复内容

1. 创建单实例锁管理工具 (src/main/utils/singleInstance.js)

• 提供完整的锁文件管理功能
• 自动清理无效的锁文件
• 检查进程是否还在运行
• 在应用退出时自动清理锁文件

2. 改进单实例检查逻辑 (src/main/index.js)

• 使用新的单实例管理器
• 在启动时自动清理无效锁文件
• 如果找不到现有实例窗口，允许强制启动
• 添加详细的日志记录

3. 添加手动清理功能 (src/main/tray.js)

• 在托盘菜单中添加"清理实例锁"选项
• 允许用户手动清理锁文件
• 提供清理结果反馈

4. 创建测试脚本 (test-single-instance.js)

• 提供锁文件检查和清理的测试功能
• 验证进程检查逻辑
• 帮助调试锁文件问题

修复后的功能特点

自动锁文件管理

1. 启动时检查：应用启动时自动检查并清理无效锁文件
2. 进程验证：验证锁文件中的进程是否还在运行
3. 自动清理：应用正常退出时自动清理锁文件
4. 异常处理：监听各种退出信号，确保锁文件被清理

手动清理功能

1. 托盘菜单：右键点击托盘图标，选择"清理实例锁"
2. 批量清理：清理多个可能的锁文件位置
3. 结果反馈：显示清理的文件数量和结果

智能启动逻辑

1. 锁文件检查：启动前检查锁文件有效性
2. 窗口激活：如果找到现有实例，尝试激活其窗口
3. 强制启动：如果找不到现有实例，允许强制启动
4. 详细日志：记录每个步骤的执行情况

使用方法

自动修复

1. 重新运行 npm run dev
2. 应用会自动检查并清理无效锁文件
3. 如果清理成功，应用会正常启动

手动清理

1. 如果应用已经启动，右键点击托盘图标
2. 选择"清理实例锁"
3. 查看日志确认清理结果
4. 重新启动应用

测试锁文件

# 运行测试脚本
node test-single-instance.js

锁文件位置

Windows 系统

• %APPDATA%\[应用名称]\single-instance-lock
• %APPDATA%\[应用名称]\lockfile
• %APPDATA%\[应用名称]\.lock

macOS 系统

• ~/Library/Application Support/[应用名称]/single-instance-lock
• ~/Library/Application Support/[应用名称]/lockfile
• ~/Library/Application Support/[应用名称]/.lock

Linux 系统

• ~/.config/[应用名称]/single-instance-lock
• ~/.config/[应用名称]/lockfile
• ~/.config/[应用名称]/.lock

验证修复效果

1. 正常启动

运行 npm run dev 后，应该看到：

[时间] 单实例锁检查结果: true
[时间] 这是第一个实例，继续启动
[时间] 应用已准备就绪，开始初始化...

2. 重复启动

如果尝试启动第二个实例，应该看到：

[时间] 单实例锁检查结果: false
[时间] 检测到已有实例运行，尝试激活现有实例
[时间] 成功激活现有实例窗口

3. 异常恢复

如果之前的实例异常退出，应该看到：

[时间] 发现锁文件: [路径]
[时间] 进程 [PID] 不存在，删除无效锁文件
[时间] 单实例锁检查结果: true
[时间] 这是第一个实例，继续启动

常见问题解决

1. 仍然无法启动

1. 手动清理锁文件：
   • 右键点击托盘图标 → 清理实例锁
   • 或者手动删除锁文件
2. 检查任务管理器，确保没有残留进程
3. 重启开发环境

2. 锁文件清理失败

1. 检查文件权限
2. 确保没有其他程序占用锁文件
3. 以管理员身份运行应用

3. 进程检查不准确

1. 在 Windows 上使用 tasklist 命令手动检查
2. 确认进程 ID 是否正确
3. 检查系统权限

注意事项

1. 开发环境

• 在开发过程中，锁文件可能会频繁创建和删除
• 如果遇到问题，使用托盘菜单的清理功能
• 查看日志文件获取详细信息

2. 生产环境

• 确保应用正常退出时能清理锁文件
• 监控锁文件的状态
• 定期检查是否有无效锁文件

3. 调试建议

• 使用 test-single-instance.js 脚本测试锁文件功能
• 查看日志文件了解锁文件的状态
• 使用托盘菜单的手动清理功能

相关文件

• src/main/utils/singleInstance.js - 单实例锁管理工具
• src/main/index.js - 主进程启动文件（已更新）
• src/main/tray.js - 托盘功能（已更新）
• test-single-instance.js - 锁文件测试脚本