# 内置运维：离线自检、临时缓存清理与配置备份去重

> 控制台「运维」页直接提供这三项能力，无需安装扩展或编写本机脚本。旧的本机 ops 扩展加载机制已移除；旧环境变量和本机扩展文件不再作为插件能力入口。本文件保留原名，避免旧文档链接失效。

## 一、三个按钮各做什么

| 动作 | 行为 | 不会做什么 |
|---|---|---|
| 跑离线自检（`selfcheck`） | 使用内置诊断的离线检查，返回检查清单 | 不联网、不发 QQ 消息、不写诊断报告、不运行外部测试或 shell |
| 清理临时文件（`cleanup-tmp`） | 预演并按确认结果清理系统临时目录下 `dsh-onebot-qq/incoming` / `dsh-onebot-qq/imagegen` 的直接普通文件，仅超过 24 小时且非在用的才处理（不递归、不跟随软链） | 不清整个系统临时目录，不清用户上传目录、参考图库、头像、表情库、记忆或日志 |
| 配置备份去重（`dedup-baks`） | 只处理当前配置文件旁的 `.bak-console-<17位数字时间戳>` 备份；仅对不超过 10 MiB 的合法 JSON、内容字节完全相同的重复版本去重，并按时间戳降序至少保留最新 3 份 | 不修改当前配置，不删除不同字节版本、非法 JSON、迁移备份或其他文件 |

自检和「一键诊断 / 导出运维报告」不是同一动作：后者仍用于完整排障与导出脱敏报告，可能探测网络并落盘；见[排错](<排错.md>)。也不要把离线自检成功当作 QQ 已登录或能真实收发的证明。

## 二、清理必须先预演、再确认

1. 点击清理或去重按钮，服务端只扫描候选，返回预演清单与 `previewToken`，此时不删除。
2. 查看范围和候选后确认。执行请求必须带 `confirm: true` 及同一次预演返回的 `previewToken`；单独传确认标志不能授权删除。
3. 服务端校验预演令牌，并在执行时重新检查路径、文件状态和候选条件。预演后有变化、正在使用或不再满足条件的对象跳过，不扩大到新出现的候选。
4. 令牌有效期 10 分钟且仅可使用一次；令牌失效、使用后或实例重启后，请重新预演。以执行结果中的删除/跳过信息为准，不把预演数量当作实际已删除数量。

RPC 仍通过现有 `/qq-console` 的 `action` 端点调用，不新增接口：

```js
// 预演：只读扫描
const preview = await call('action', { id: 'cleanup-tmp' })
// 确认：必须用服务端本次返回的令牌，不能自行拼造
await call('action', {
  id: 'cleanup-tmp',
  confirm: true,
  previewToken: preview.previewToken,
})
// dedup-baks 使用相同的两步流程。
```

预演与执行返回 `ok`、`previewLines`、`message`、`removed`、`skipped`、`planned`、`totalBytes`；`previewToken` 只在预演成功时提供。取消确认不会删除文件。临时缓存不在插件启动时自动清理，须显式走这个流程。

这些动作不接受任意删除路径、shell 命令或用户自定义清理脚本。目录、在用文件与备份规则由包内安全实现约束，不提供“强制清空”开关。

## 三、配置、路径与升级

- 无需新增实例配置键；数据与配置路径沿用当前实例的运行路径。备份去重只处理 `dataDir` 内当前 `configPath` 的备份；自定义配置移到数据目录之外时不会扫描删除，需由部署者自行管理备份。
- 临时缓存清理与「文件与图片」的入站文件保留天数是两套规则：前者只针对插件专用临时缓存，后者管理已接收并落盘的上传文件。
- 去重不是按时间一刀切的备份保留策略。至少最新 3 份保留；不同内容的历史配置不会因为“旧”而被本按钮删除。备份也可能含凭据，仍需保护整个配置目录的权限。
- 插件不管理 systemd、cron、Windows 服务或 QQ 登录。DSH 进程由部署者管理；QQ 登录使用协议端自己的界面。群记忆自动积累由插件内置调度，不接入本机扩展兜底。
- 可选 `:3971` 兼容网关与这些运维按钮无关，默认关闭；不要为了启用运维而打开网关。

## 四、实现与安全边界

内置维护实现见 [`ops/maintenance.js`](<../ops/maintenance.js>)；控制台动作沿用既有端点。维护操作应跨平台运行，只使用受限的文件系统能力，不执行外部命令、不请求任意 URL、不删除用户数据。扩展业务能力请使用正式子插件契约，见[开发指南](<开发指南.md>)，不再通过可执行的本机运维扩展注入代码。