# 安装包卸载与清理
**本文引用的文件**
- [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、临时文件、残留进程和可能的注册表项。
- 遇到进程无法终止、权限不足或部分目录未删除时,应结合管理员权限、进程管理和手动清理进行处理。
- 卸载前务必备份重要数据;卸载后如发现旧授权信息,应重点检查浏览器缓存、应用数据和服务端授权状态。