# 安装包卸载与清理 **本文引用的文件** - [cmd/uninstall.bat](file://cmd/uninstall.bat) - [cmd/uninstall.sh](file://cmd/uninstall.sh) ## 目录 1. [简介](#简介) 2. [项目结构中的卸载脚本位置](#项目结构中的卸载脚本位置) 3. [卸载脚本总览](#卸载脚本总览) 4. [Windows 卸载脚本分析](#windows-卸载脚本分析) 5. [Linux/macOS 卸载脚本分析](#linuxmacos-卸载脚本分析) 6. [卸载前备份建议](#卸载前备份建议) 7. [手动清理清单](#手动清理清单) 8. [常见问题与处理方法](#常见问题与处理方法) 9. [数据恢复注意事项](#数据恢复注意事项) 10. [结论](#结论) ## 简介 本指南面向清鉴客户端用户,说明如何通过官方卸载脚本完成安全、完整的卸载,并补充浏览器缓存、Electron AppData、临时文件和残留进程等手动清理项。重点解释: - Windows 下 `cmd/uninstall.bat` 如何强制终止 `qingjian-client.exe` 并清理 `%APPDATA%` 下的 QingJian 相关目录。 - Linux/macOS 下 `cmd/uninstall.sh` 如何通过 `$HOME` 安全检查、`pkill` 进程终止和 `rm -rf` 递归删除用户数据目录。 - 管理员权限执行方式、卸载前备份策略、常见失败场景的排查方法。 ## 项目结构中的卸载脚本位置 卸载逻辑集中在仓库根目录的 `cmd` 子目录中: ```mermaid graph TB Root["仓库根目录"] --> Cmd["cmd 目录"] Cmd --> UninstallBat["uninstall.bat
Windows 卸载脚本"] Cmd --> UninstallSh["uninstall.sh
Linux/macOS 卸载脚本"] ``` **图表来源** - [cmd/uninstall.bat:1-52](file://cmd/uninstall.bat#L1-L52) - [cmd/uninstall.sh:1-53](file://cmd/uninstall.sh#L1-L53) **章节来源** - [cmd/uninstall.bat:1-52](file://cmd/uninstall.bat#L1-L52) - [cmd/uninstall.sh:1-53](file://cmd/uninstall.sh#L1-L53) ## 卸载脚本总览 两个脚本都遵循相似的卸载流程: 1. **安全检查** - Windows:检查 `%APPDATA%` 是否为空,防止误删系统默认应用数据。 - Linux/macOS:检查 `$HOME` 是否为空,防止灾难性递归删除。 2. **强制终止清鉴客户端进程** - Windows:使用 `taskkill /F` 终止 `qingjian-client.exe`。 - Linux/macOS:使用 `pkill -9 -f "qingjian-client"` 终止匹配进程。 3. **递归删除用户数据目录** - Windows:删除 `%APPDATA%\QingJian` 和 `%APPDATA%\qingjian-client`。 - Linux/macOS:删除 `$HOME/.config/qingjian-client`、`$HOME/.local/share/QingJian`、`$HOME/.qingjian-client`。 4. **输出清理结果** - 显示是否已删除、跳过或失败,并在失败时提示可能因权限不足或被占用导致。 ```mermaid flowchart TD Start(["开始卸载"]) --> CheckEnv["检查运行环境变量"] CheckEnv --> KillProcess["强制终止 qingjian-client 进程"] KillProcess --> DeleteDirs["递归删除用户数据目录"] DeleteDirs --> Report["输出清理结果"] Report --> End(["结束"]) ``` [此图为概念流程图,不直接映射具体代码结构] **章节来源** - [cmd/uninstall.bat:9-11](file://cmd/uninstall.bat#L9-L11) - [cmd/uninstall.bat:17-18](file://cmd/uninstall.bat#L17-L18) - [cmd/uninstall.bat:30-52](file://cmd/uninstall.bat#L30-L52) - [cmd/uninstall.sh:8-11](file://cmd/uninstall.sh#L8-L11) - [cmd/uninstall.sh:14-25](file://cmd/uninstall.sh#L14-L25) - [cmd/uninstall.sh:28-50](file://cmd/uninstall.sh#L28-L50) ## Windows 卸载脚本分析 ### 主要职责 `cmd/uninstall.bat` 是 Windows 平台的卸载脚本,核心行为包括: - 检查环境变量 `%APPDATA%` 是否存在且非空。 - 强制结束名为 `qingjian-client.exe` 的进程。 - 删除 `%APPDATA%\QingJian`。 - 删除 `%APPDATA%\qingjian-client`。 - 根据目录是否仍存在,输出“已删除”“跳过”或“无法删除”。 ### 安全机制 脚本在开头判断 `%APPDATA%` 是否为空;若为空,则直接终止执行,避免在环境变量缺失的情况下误删系统默认应用数据。 ### 进程处理 脚本通过任务管理命令强制终止 `qingjian-client.exe`。该方式适用于大多数情况,但如果进程被其他程序锁定、以更高权限运行,或已被外部工具提前结束,可能出现无法终止的情况。 ### 数据清理范围 Windows 脚本只清理以下两个路径: | 目录 | 含义 | 是否由脚本删除 | |---|---|---| | `%APPDATA%\QingJian` | Windows 平台下的 QingJian 用户数据目录 | 是 | | `%APPDATA%\qingjian-client` | Windows 平台下的另一个 QingJian 相关目录 | 是 | 注意:Linux/macOS 使用的 `$HOME/.config/qingjian-client`、`$HOME/.local/share/QingJian`、`$HOME/.qingjian-client` 不在 Windows 脚本的默认清理范围内。 ```mermaid flowchart TD Start(["进入 uninstall.bat"]) --> CheckAppdata["检查 %APPDATA% 是否为空"] CheckAppdata --> Empty{"%APPDATA% 是否为空?"} Empty -->|是| Abort["输出错误并终止"] Empty -->|否| KillExe["强制终止 qingjian-client.exe"] KillExe --> DeleteQingJian["删除 %APPDATA%\\QingJian"] DeleteQingJian --> CheckQingJian{"目录是否仍存在?"} CheckQingJian -->|否| QjOk["输出已删除"] CheckQingJian -->|是| QjFail["输出无法删除,可能因权限或占用"] DeleteQingJian --> DeleteClientDir["删除 %APPDATA%\\qingjian-client"] DeleteClientDir --> CheckClientDir{"目录是否仍存在?"} CheckClientDir -->|否| ClientOk["输出已删除"] CheckClientDir -->|是| ClientFail["输出无法删除,可能因权限或占用"] ``` **图表来源** - [cmd/uninstall.bat:9-11](file://cmd/uninstall.bat#L9-L11) - [cmd/uninstall.bat:17-18](file://cmd/uninstall.bat#L17-L18) - [cmd/uninstall.bat:30-52](file://cmd/uninstall.bat#L30-L52) **章节来源** - [cmd/uninstall.bat:9-11](file://cmd/uninstall.bat#L9-L11) - [cmd/uninstall.bat:17-18](file://cmd/uninstall.bat#L17-L18) - [cmd/uninstall.bat:30-52](file://cmd/uninstall.bat#L30-L52) ## Linux/macOS 卸载脚本分析 ### 主要职责 `cmd/uninstall.sh` 是 Linux 和 macOS 平台的卸载脚本,核心行为包括: - 检查 `$HOME` 是否为空。 - 使用 `pkill -9 -f "qingjian-client"` 终止进程。 - 遍历并删除三个用户数据目录。 - 对每个目录输出“已删除”“跳过”或“无法删除”。 ### 安全检查逻辑 脚本首先判断 `$HOME` 是否为空。如果为空,则立即输出错误并退出,这是为了防止 `$HOME` 缺失时递归删除操作产生危险影响。 ### 进程终止逻辑 脚本使用 `pkill -9 -f "qingjian-client"` 查找并强制终止命令行中包含 `qingjian-client` 的进程。脚本记录了 `pkill` 的返回值: | `pkill` 返回值 | 脚本行为 | |---|---| | `0` | 认为进程已终止,等待约两秒让进程释放文件句柄后继续 | | `1` | 表示未发现运行中的进程或进程已提前退出 | | 其他值 | 输出警告,包含实际错误码 | ### 数据清理范围 Linux/macOS 脚本会尝试删除以下三个目录: | 目录 | 说明 | |---|---| | `$HOME/.config/qingjian-client` | 清鉴客户端配置目录 | | `$HOME/.local/share/QingJian` | 清鉴客户端共享数据目录 | | `$HOME/.qingjian-client` | 清鉴客户端用户数据目录 | ### 删除失败提示 当某个目录存在但 `rm -rf` 返回失败时,脚本会提示“无法删除”,并指出可能存在权限问题或文件被占用。这通常发生在: - 当前用户没有删除该目录的权限。 - 目录中仍有文件被清鉴客户端或其他进程占用。 - 文件系统挂载点、网络盘或容器卷限制删除。 ```mermaid flowchart TD Start(["进入 uninstall.sh"]) --> CheckHome["检查 $HOME 是否为空"] CheckHome --> HomeEmpty{"$HOME 是否为空?"} HomeEmpty -->|是| Abort["输出错误并退出"] HomeEmpty -->|否| Pkill["执行 pkill -9 -f \"qingjian-client\""] Pkill --> ExitCode{"pkill 返回值?"} ExitCode -->|0| Wait["等待约两秒,释放文件句柄"] ExitCode -->|1| NoProcess["提示未发现进程"] ExitCode -->|其他| Warn["输出未知错误码警告"] Wait --> DeleteDirs["遍历删除三个用户数据目录"] NoProcess --> DeleteDirs Warn --> DeleteDirs DeleteDirs --> Result{"删除是否成功?"} Result -->|是| Deleted["输出已删除"] Result -->|否| Failed["输出无法删除,提示权限或占用"] ``` **图表来源** - [cmd/uninstall.sh:8-11](file://cmd/uninstall.sh#L8-L11) - [cmd/uninstall.sh:14-25](file://cmd/uninstall.sh#L14-L25) - [cmd/uninstall.sh:28-50](file://cmd/uninstall.sh#L28-L50) **章节来源** - [cmd/uninstall.sh:8-11](file://cmd/uninstall.sh#L8-L11) - [cmd/uninstall.sh:14-25](file://cmd/uninstall.sh#L14-L25) - [cmd/uninstall.sh:28-50](file://cmd/uninstall.sh#L28-L50) ## 卸载前备份建议 在执行卸载脚本前,建议先备份重要数据,尤其是: - 本地案件数据、导出结果和分析记录。 - 自定义模板、规则、插件或扩展配置。 - 数据库连接信息、服务地址、认证凭据等敏感配置。 - 需要保留的日志文件或诊断信息。 推荐做法: 1. 关闭清鉴客户端,确认后台进程已退出。 2. 将需要保留的数据复制到独立磁盘、移动硬盘或云存储。 3. 记录当前清鉴客户端版本、服务地址和授权信息,便于后续重装或迁移。 4. 仅在你明确知道这些目录用途的前提下,才进行手动删除。 **章节来源** - [cmd/uninstall.sh:28-50](file://cmd/uninstall.sh#L28-L50) ## 手动清理清单 卸载脚本不会清理所有可能的残留位置。如果你希望彻底清除清鉴客户端,请按需检查以下位置。 ### 浏览器缓存中的服务地址 清鉴客户端可能在浏览器缓存中保存过后端服务地址或登录状态。建议检查: - 浏览器设置中的“清除浏览数据”。 - 站点数据中是否仍保留清鉴相关的服务地址、令牌或会话。 - 多账号或多实例环境下,不同配置文件或工作区是否还留有旧服务地址。 ### Electron AppData 清鉴客户端基于 Electron 构建,其运行时数据和缓存通常位于操作系统的应用数据目录中。除了卸载脚本已清理的目录外,还应关注: - 当前用户的应用数据目录。 - 浏览器或 WebView 组件产生的缓存、索引和会话数据。 - 不同用户账户下的独立数据目录。 ### 临时文件 检查系统临时目录中是否残留清鉴客户端生成的日志、调试文件或打包产物。常见位置包括: - 当前用户的临时目录。 - 安装目录下的临时文件夹。 - 系统级临时目录(需具备相应权限)。 ### 残留进程 如果卸载后仍能发现清鉴相关进程,可能是进程未完全退出或父进程仍在维持子进程。处理方式包括: - 使用任务管理器或系统进程查看工具查找 `qingjian-client`。 - 优先结束普通用户进程。 - 如进程属于系统服务或以管理员权限运行,再考虑以管理员身份结束。 ### 注册表项(Windows) 卸载脚本本身没有处理注册表。如果清鉴客户端在安装时写入注册表项,而卸载脚本未覆盖这些键值,可能需要手动清理。建议仅在了解注册表风险的前提下操作: - 使用注册表编辑器搜索与清鉴客户端相关的键值。 - 仅删除与已卸载版本对应的键值。 - 操作前导出并备份相关注册表项。 ```mermaid flowchart TD Start(["卸载后残留排查"]) --> Browser["检查浏览器缓存和服务地址"] Browser --> AppData["检查 Electron AppData 与应用数据目录"] AppData --> Temp["检查临时文件"] Temp --> Process["检查残留进程"] Process --> Registry["Windows 检查注册表项"] Registry --> Done(["清理完成"]) ``` [此图为概念流程图,不直接映射具体代码结构] **章节来源** - [cmd/uninstall.bat:30-52](file://cmd/uninstall.bat#L30-L52) - [cmd/uninstall.sh:28-50](file://cmd/uninstall.sh#L28-L50) ## 常见问题与处理方法 ### 问题一:进程无法终止 **现象** 卸载脚本提示进程终止失败,或卸载后仍能看到 `qingjian-client` 相关进程。 **可能原因** - 进程以更高权限运行。 - 进程被其他程序或系统服务持有。 - 文件句柄尚未释放。 - 进程已在卸载前被手动结束。 **处理方法** - Windows:以管理员身份打开命令提示符或 PowerShell,再次运行 `cmd/uninstall.bat`,或在任务管理器中结束 `qingjian-client.exe`。 - Linux/macOS:以 sudo 权限运行 `cmd/uninstall.sh`,或使用 `ps` 工具定位进程后手动结束。 - 确认清鉴客户端已完全退出后再重试卸载。 **章节来源** - [cmd/uninstall.bat:17-18](file://cmd/uninstall.bat#L17-L18) - [cmd/uninstall.sh:14-25](file://cmd/uninstall.sh#L14-L25) ### 问题二:权限不足 **现象** 脚本输出“无法删除”或提示权限问题。 **可能原因** - 当前用户不是目录所有者。 - 目录受系统保护或权限控制。 - 文件被其他进程占用。 - 网络盘、容器卷或只读文件系统阻止删除。 **处理方法** - Windows:右键选择“以管理员身份运行”批处理脚本。 - Linux/macOS:使用 `sudo` 执行脚本,例如在终端中以 root 权限运行 `cmd/uninstall.sh`。 - 先关闭清鉴客户端及相关服务,再重试删除。 - 若目录位于网络驱动器或特殊挂载点,请联系系统管理员。 **章节来源** - [cmd/uninstall.bat:30-52](file://cmd/uninstall.bat#L30-L52) - [cmd/uninstall.sh:38-50](file://cmd/uninstall.sh#L38-L50) ### 问题三:部分目录未被删除 **现象** 某些用户数据目录仍然存在。 **可能原因** - 该目录不存在,脚本会跳过。 - 删除失败,但脚本仍继续执行后续目录。 - Windows 与 Linux/macOS 的目录结构不同,跨平台复制脚本可能导致误解。 **处理方法** - 确认你使用的是对应平台的卸载脚本。 - 手动检查目标目录是否存在。 - 如果目录仍存在且可安全删除,可手动删除,但请先备份。 **章节来源** - [cmd/uninstall.bat:30-52](file://cmd/uninstall.bat#L30-L52) - [cmd/uninstall.sh:28-50](file://cmd/uninstall.sh#L28-L50) ### 问题四:卸载后仍显示旧授权信息 **现象** 重新安装或重启后,界面仍显示旧的授权、服务地址或登录状态。 **可能原因** - 浏览器缓存或服务地址缓存未被清理。 - Electron 应用数据或本地配置仍保留旧信息。 - 其他用户账户或安装实例保留了旧数据。 - 服务器端仍维护该设备的授权记录。 **处理方法** - 清除浏览器缓存和站点数据。 - 检查 Electron AppData 和应用数据目录中的旧配置。 - 确认当前登录的用户账户是否正确。 - 如需完全重置,请在备份后删除相关数据目录,然后重新安装。 - 若授权来自服务端,请联系管理员刷新或注销设备授权。 **章节来源** - [cmd/uninstall.bat:30-52](file://cmd/uninstall.bat#L30-L52) - [cmd/uninstall.sh:28-50](file://cmd/uninstall.sh#L28-L50) ### 问题五:Linux 脚本报错 `$HOME` 未定义 **现象** Linux/macOS 脚本直接退出,并提示 `$HOME` 未定义。 **可能原因** - 在非交互式 shell 或未正确初始化环境的环境中执行脚本。 - 以异常用户上下文执行脚本。 **处理方法** - 确保在正常登录用户的终端中执行脚本。 - 如果需要以 root 或其他用户执行,请显式设置 `$HOME`,并确认该路径确实是你期望的目标用户数据目录。 - 谨慎操作,避免误删其他用户的数据。 **章节来源** - [cmd/uninstall.sh:8-11](file://cmd/uninstall.sh#L8-L11) ## 数据恢复注意事项 卸载脚本会递归删除用户数据目录,因此一旦删除,数据恢复难度较高。 ### 不要立即清空回收站 Windows 上即使 `rd /s /q` 的行为也可能受系统回收站策略影响。如果发现误删,应: - 停止向目标磁盘写入新数据。 - 尽快从回收站恢复。 - 若数据已被覆盖,可使用专业数据恢复工具。 ### Linux/macOS 上谨慎恢复 `rm -rf` 通常绕过回收站,恢复更困难。建议: - 立即停止对该分区或卷的写入。 - 优先联系数据恢复专业人员。 - 不要反复尝试删除或重建目录,以免进一步覆盖数据。 ### 从备份恢复 最安全的恢复方式是使用卸载前的备份: 1. 重新安装清鉴客户端。 2. 停止客户端进程。 3. 将备份数据恢复到对应目录。 4. 重新启动客户端,验证配置和数据是否正常。 **章节来源** - [cmd/uninstall.bat:30-52](file://cmd/uninstall.bat#L30-L52) - [cmd/uninstall.sh:28-50](file://cmd/uninstall.sh#L28-L50) ## 结论 - `cmd/uninstall.bat` 和 `cmd/uninstall.sh` 提供了基础的清鉴客户端卸载能力,包括进程终止和用户数据目录清理。 - Windows 脚本清理 `%APPDATA%\QingJian` 和 `%APPDATA%\qingjian-client`;Linux/macOS 脚本清理 `$HOME` 下的三个 QingJian 相关目录。 - 若要彻底卸载,还需清理浏览器缓存、Electron AppData、临时文件、残留进程和可能的注册表项。 - 遇到进程无法终止、权限不足或部分目录未删除时,应结合管理员权限、进程管理和手动清理进行处理。 - 卸载前务必备份重要数据;卸载后如发现旧授权信息,应重点检查浏览器缓存、应用数据和服务端授权状态。