# safevault

**Repository Path**: li_dg/safevault

## Basic Information

- **Project Name**: safevault
- **Description**: 开源的保险箱
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-28
- **Last Updated**: 2026-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SafeVault 保险箱

面向 Windows 和 Linux 的单文件加密保险箱项目。目标是在一个桌面窗口中完成新建、导入、打开、关闭、扩容和安全删除，解锁后通过系统文件管理器访问文件。

**当前源码0.1.69，Windows宿主最近核验的安装版本为0.1.64，Linux远程验收记录的安装版本为0.1.57，处于 Gate 0 技术验证阶段。已有 Linux 本机实验安装和升级入口，以及 Windows x64 实验版安装包；尚非完整产品，不可用于保存实际秘密或重要数据。**

本机0.1.54的任务数据库锁丢失与WAL分离已完成[现场封存和完整恢复](docs/testing/linux-wal-recovery.md)，138条历史任务保留。0.1.55锁修复已部署，真实权限、原生扩容/恢复、数据校验及[实际桌面与系统文件管理器全链路](docs/testing/linux-filemanager.md)通过；末次核对服务正常，登记列表为空。早期失败测试样本的密文及诊断副本保留，未冒充安全擦除。

此前Linux验收限定为Deepin 25 x86_64、X11/DDE会话及已实现功能，所列验收已通过；用户随后要求继续Windows测试、修复和打包。其他发行版、硬件掉电、完整异常自动恢复、生产格式与GC等仍暂缓；Linux结果见[当前系统验收与暂缓项](docs/testing/linux-acceptance-status.md)。

2026-10-30 已通过DEB实际安装和0.1.55→0.1.56升级，实际进程、三份程序散列及真实桌面文件管理器复验通过，见[包安装验收](docs/testing/linux-packages.md)。随后0.1.57补齐应用/安装入口的自有图标和桌面快捷方式，已通过实际升级及快捷方式启动，见[图标验收](docs/testing/linux-icons.md)。

代码仓库：[Gitee / li_dg / safevault](https://gitee.com/li_dg/safevault)。

Windows 0.1.60已生成中文NSIS实验版安装包，包含Release桌面、实验CLI和离线WebView2运行时；断网沙箱安装、已安装CLI的11项检查及桌面启动通过。本轮全工作区88项原生测试、严格Clippy和格式检查通过。此为0.1.60历史结果；0.1.63已接入Windows受保护服务及可写盘符，沙箱验收见[Windows服务测试](docs/testing/windows-service.md)，宿主已更新0.1.64并核对真实服务连接，详见[安装包与验收](docs/testing/windows-packages.md)及[Windows接手进度](docs/WINDOWS_HANDOFF.md)。

0.1.61的新建窗口增加“选择文件夹”，并用保险箱名称自动生成`.svlt`文件名和完整路径预览。88项Rust测试、5项模型及35项界面回归通过，更新安装包已生成；按用户不干扰正常工作的要求停止前台自动化，原生点选验收尚未完成，见[目录选择验收记录](docs/testing/windows-folder-picker.md)。

## 目标功能与实现状态

| 能力 | 目标行为 | 当前状态 |
|---|---|---|
| 新建 | 自定义容量、密码及保存位置，预分配单文件容器 | 实验服务与原生桌面创建通过；生产格式未接入 |
| 导入 | 校验并登记已有容器，不复制原文件 | 实验服务及原生桌面导入通过，原文件身份/散列不变；生产流程待完成 |
| 打开 | 正确密码解锁；Linux 挂载目录，Windows 自动盘符 | Linux 服务打开事务与真实挂载通过；Windows受保护服务及可写盘符沙箱验收通过 |
| 关闭 | 冲刷缓存、安全卸载、清理密钥 | Linux及Windows关闭事务、占用保护、停止卸载和无残留挂载时的验密恢复已实现 |
| 扩容 | 关闭后验密、只增不减、预检可用空间 | Linux真机验收通过；Windows服务、界面及隔离沙箱真实扩容通过，服务事务四阶段中断续做通过 |
| 删除 | 验证密码、输入确认词、卸载、擦除并报告实际结果 | Linux及Windows已关闭/已挂载实验容器擦除通过；文件占用时保留挂载 |
| 数据加密 | 文件内容、名称及目录元数据均认证加密 | 文件内容采用 64KiB 认证加密块，名称和块索引单独加密；生产格式未冻结 |
| 恢复 | 从最后有效持久化提交恢复 | Windows有限自动重启、重新验密恢复打开及已销毁擦除收尾通过；未知现场保留，创建/导入中断及真实掉电未完成，见[验收边界](docs/testing/windows-lifecycle.md) |
| 防直接删除 | 系统受控目录及权限服务保护容器 | Linux root/普通用户权限验收及本机实验安装通过；恢复流程待完成 |
| 桌面界面 | V1.2 原型的单窗口、五列列表和操作弹窗 | 已安装 Release 与系统服务；原生主流程、扩容及有限验密恢复通过；完整异常恢复待完成 |
| 跨平台 | 同一格式在 Windows/Linux 读写 | 尚未完成互操作验证 |

## 设计依据

- [V1.2 需求](docs/reference/SafeVault_简洁版需求_v1.2.md)：界面、功能范围和 Linux 挂载目录规则。
- [V1.2 HTML 原型](docs/reference/SafeVault_简洁版原型_v1.2.html)：交互参考，仅模拟流程。
- [详细设计 V1](docs/reference/保险箱设计V1.md)：Rust、Tauri 2、FUSE/WinFsp、加密格式、事务、安全边界及测试门限。

范围与交互以较新的 V1.2 为准，底层安全要求保留详细设计约束。文档中的阶段目标不代表已实现能力。

实施基线：新建和导入限定受控目录，导入仅登记原文件；容量暂按 128MiB～1TiB；不自动删除备份；不承诺清除 SSD 历史页、快照或离线副本。以上基线依据用户授权自主实施及设计建议确定，尚未全部落实到代码。实验库接受的小容量测试文件不代表产品容量规格。

## 现有目录

```text
safevault/
  Cargo.toml                 Rust workspace 与统一版本
  Cargo.lock                 依赖版本锁定
  crates/sv-format/          SVLT v1 草案头部与容量编解码
  crates/sv-crypto/          全头部认证、密钥封装与记录加密
  crates/sv-core/            Gate 0 加密持久化实验
  crates/sv-fs/              Gate 0 加密命名空间实验
  crates/sv-mount-fuse/      Linux FUSE 挂载实验与真实集成测试
  crates/sv-mount-winfsp/    Windows WinFsp 只读及可写实验适配
  crates/sv-cli/             实验命令行工具
  crates/sv-service/         服务领域基础与本机注册表
  tests/cli_smoke.py         真实终端交互与挂载测试
  apps/desktop/             Tauri 桌面客户端、原型界面与交互测试
  docs/reference/            原始需求、原型与详细设计
  README.md                  功能、使用方式及当前状态
  AGENTS.md                  开发约束与验收规则
  CHANGELOG.md               按功能记录的开发历史
```

`sv-service` 已有注册表、鉴权 IPC、受控目录访问、请求解析和持久任务日志基础库；已有Windows可写WinFsp、SYSTEM服务和Tauri桌面客户端；Linux 实验服务的创建、导入、擦除、打开、关闭和扩容已接入，本机实验安装通过；无残留挂载时的验密恢复及扩容续做已实现，完整异常现场恢复与正式发布仍待完成。现有 `sv-core` 与 `sv-fs` 仅为验证用模块，生产分层须在 Gate 0 评审后落实。

## Linux 实验安装

Deepin 25 x86_64可使用无需编译的DEB安装器包，见[安装包说明](docs/packages.md)。包安装完成后，以普通用户运行 `safevault-setup`完成当前用户配置，服务与已有数据沿用原安装器管理。

以普通用户执行，构建结束后经系统弹窗认证安装服务及桌面入口：

```bash
bash scripts/install-linux.sh
```

已在本机安装并验证 systemd 正常停止/启动、空列表下 SIGKILL 后自动重启和普通用户鉴权连接。日常桌面操作使用常驻受保护服务，无需反复输入管理员密码；保险箱密码仍需输入。路径、前置条件、重复安装边界和当前限制见 [Linux 实验安装说明](docs/linux-install.md)。

## Windows 实验版安装包

当前产物为 `target/packages/windows/SafeVault-Experimental_0.1.64_windows-x64-setup.exe`，约213.33MiB，附带SHA-256和使用说明；包与日志被Git忽略，不随源码拉取。桌面按当前用户安装，后台服务位于Program Files；包内包含离线WebView2和官方WinFsp，已有组件复用。

0.1.64已通过后台沙箱安装、真实服务通信及升级前数据重开验证，并更新宿主现有安装。创建、导入、打开及正常关闭已接入；扩容、擦除及异常自动恢复尚未实现。包未签名，仍只用于实验数据；原生目录点选和Office全套未验收。构建入口、运行范围和实际证据见[Windows安装包说明](docs/testing/windows-packages.md)。

## 构建与验证

在项目根目录安装 Rust 稳定工具链后执行。当前已验证工具链为 Rust/Cargo 1.98.1，开发机为 Deepin 25 x86_64。

```bash
cargo build --workspace --locked
```

```bash
cargo test --workspace --locked
```

```bash
cargo clippy --workspace --all-targets --locked -- -D warnings
```

```bash
cargo fmt --all -- --check
```

已有 `safevault-lab`实验命令行、Tauri客户端及当前Deepin系统的DEB实验安装器包。测试使用临时目录中的实验容器，不触碰已有保险箱；包交付不改变实验格式和已记录的功能限制。

首批 4 项测试已通过（这是初始基线；最新完整验证见下方统一验证入口）：加密往返及密文检查、错误密码不改写源文件、单头部损坏恢复、最新提交页损坏后回退。Clippy 严格检查及格式检查通过。它们不等同于完整的故障注入或安全评审。

## 实验实现与限制

实验格式使用 `SVGATE00` 标识，**不兼容且不冒充生产 SVLT v1**。实现采用 Argon2id、XChaCha20-Poly1305 和 HKDF-SHA256；通过双头部、追加记录与交替提交页验证持久化顺序。密钥及解密缓冲使用 `Zeroizing`，调用方仍须负责自身口令和明文缓冲生命周期。

单条实验记录上限为 16MiB，命名空间 v3 已改为 64KiB 加密块索引，单次 I/O 上限 1MiB、1024 节点；旧实验快照不自动迁移，尚无垃圾回收与完整产品容量核算，空间耗尽后拒绝提交。已补充创建临时文件清理、Unix 父目录刷盘、文件排他锁及最后一级符号链接拒绝；父目录信任边界、完整头部认证及生产 KDF 校准仍需实现。不得把这里的实现用于生产数据。

0.1.51 修复写满后文件通道误关闭，已确认内容仍可读取；0.1.52 保留 Linux 创建权限和 umask；0.1.53 向系统报告真实的实验物理总量、剩余追加空间和节点名额。统计余量还需承担加密/对齐/元数据开销，不保证可写入等量文件；删除只恢复节点名额，尚不会回收追加区。对应回归见 [写满](docs/testing/linux-0.1.51.md)、[权限](docs/testing/linux-0.1.52.md)、[容量统计](docs/testing/linux-0.1.53.md)。

当前环境的 FUSE3、GTK3、WebKitGTK4.1 开发依赖已经通过系统认证安装，Linux 真实挂载测试通过。Windows 构建目标存在不代表已通过 WinFsp/Office 或 Windows 实机验收。

## 后续迭代顺序

1. 补齐 Gate 0 的 Windows/WinFsp、目标 Linux 发行版、跨平台语义和硬件掉电验收，完成评审。
2. Gate 0 通过后接入生产格式、安全 GC 和完整容量核算，解除明确的实验限制。
3. 完善 Windows 可写挂载、服务与权限，以及 Linux 创建/导入/擦除中断和残留挂载的安全恢复。
4. 完成跨平台文件操作、Office 行为、关机可靠性及安全审查。
5. 完成正式安装包、升级部署和发布验收；保留现有实验安装与生产发布的区别。

Gate 0 未通过时不得宣称技术路线已验收或进入生产发布。目标系统 Ubuntu 24.04、Debian 12、Windows 10/11 均需实测，Deepin 测试不能替代它们。

## 开发记录与版本

每个独立功能点必须完成实现、相关验证、开发记录及 Git 提交后再进入下一功能。采用中文 Conventional Commits，正文说明功能、设计原因、验证命令与结果、剩余限制。

新增功能完成后补丁版本递增一次；纯文档不递增。查看 [开发记录](CHANGELOG.md) 和 Git 历史：

```bash
git log --date=iso --format=fuller
```

当前仓库尚未授予开源许可；`UNLICENSED` 表示未声明可自由分发的许可证。

真实挂载测试需要 Linux 和可访问的 `/dev/fuse`，默认不自动执行：

```bash
cargo test -p sv-mount-fuse --test mount --locked -- --ignored --nocapture
```

显式进程中断和 I/O 失败注入测试（仅测试临时容器）：

```bash
cargo test -p sv-core --features fault-injection --test crash --locked
```

该测试覆盖五个阶段的 SIGKILL 和注入错误，不代替硬件掉电测试。核心和命名空间已通过 Windows GNU 目标交叉编译检查，WinFsp 实机仍未验证。

## 实验工具

Release 产物位于 `target/release/safevault-lab`，不是正式桌面保险箱。

```bash
cargo run -p sv-cli -- doctor
```

```bash
cargo run -p sv-cli -- create /绝对路径/临时测试.svlt --experimental --capacity-mib 128
```

密码在终端内交互输入。容量参数目前代表实验文件物理大小，不能作为产品逻辑容量；仅使用新建的临时测试目录。挂载目录须事先存在且为空：

```bash
cargo run -p sv-cli -- mount /绝对路径/临时测试.svlt /绝对路径/空挂载目录
```

按 Ctrl+C 尝试正常卸载；若文件被占用，先关闭文件再重试。可通过 `check` 命令验证解锁、目录结构及当前引用的全部数据块认证。检查不写源数据，逐块处理稀疏文件，不扫描已废弃的历史块；它不会修复损坏或解除服务恢复状态。

CLI 真实交互测试（先执行 `cargo build -p sv-cli --locked`）：

```bash
python3 tests/cli_smoke.py
```

## 统一回归

在本机执行全部特性单测、五阶段故障注入、真实 FUSE、CLI 伪终端交互以及 Release 构建：

```bash
bash scripts/verify.sh --with-fuse
```

不传 `--with-fuse` 时明确跳过真实挂载与 CLI 交互，不将跳过计为通过。2026-10-28 已在 Deepin 25 成功执行完整流程：31 项 Rust 测试（含故障注入入口）、1 项显式 FUSE 测试及 CLI 交互通过，Release 版本为 0.1.12。该记录不替代 Windows 或真实硬件断电验收。这是早期基线，最新完整回归与原生安装结果见 [0.1.49 验收](docs/testing/linux-0.1.49.md)和 [0.1.50 验收](docs/testing/linux-0.1.50.md)。

## 挂载依赖维护

Linux 使用 fuser 0.18，并通过 [本地补丁](vendor/README.md) 修复旧会话清理误卸载同路径新会话的问题。真实挂载回归覆盖该场景。会话结束的 I/O 错误会向上返回；占用时仍执行普通卸载并报告失败，不以强制卸载伪装关闭成功。

## 本机注册表

`sv-service::registry` 保存容器 UUID、名称、路径、逻辑容量、Linux 挂载目录和时间戳，不保存密码、密钥、内部文件清单或伪造的实时挂载状态。登记 API 只修改管理快照，不打开、复制或移动容器；容器检查和受控目录校验已由 Linux 实验业务入口执行，打开、扩容及擦除还须验密。

使用独立锁文件排他访问，以同目录临时文件写入、刷盘、原子替换提交快照；Linux 再刷盘父目录。损坏或未知字段拒绝加载，失败不自动重置为空列表。Linux 状态目录必须由运行身份持有且不可被组/其他用户写入。父目录信任链、Windows ACL 和 Windows 断电持久化仍待平台验证。

## Linux 本地 IPC 传输

`sv-service::ipc` 提供 Unix 套接字连接，服务端和客户端均通过内核 SO_PEERCRED 核验对端 UID，不采信请求中的自报身份。套接字权限 0600，运行目录须由服务身份持有且不可被组/其他用户写入；已有路径不自动删除，退出只清理身份仍一致的本实例套接字。

消息采用 4 字节大端长度，请求最多 64KiB、响应最多 2MiB，接收请求及写入超时 5 秒，客户端业务响应等待 35 秒；长度、截断、超时或写入错误后关闭连接，避免半条消息污染后续协议。接收缓冲析构时零化，无载荷日志。Linux JSON 分发、后台任务、特权进程实验安装和受控运行目录均已接入；Windows 命名管道尚未实现。

## Windows 只读验证适配

`sv-mount-winfsp` 提供大小写不敏感路径解析、只读文件与目录回调和自动空闲盘符请求。它不是 Windows 可写版本，尚未在 Windows 驱动上运行；安全关闭、共享模式和 Office 保存仍待实现。[验证矩阵与构建前提](docs/testing/windows.md) 记录明确的测试边界及依赖说明。

## 桌面客户端开发与测试

```bash
cargo run -p safevault-desktop --locked
```

界面按 V1.2 原型提供五列列表、原有五项操作及用户后续要求的扩容、右键菜单与密码弹窗，自动检测系统；Linux 挂载目录一旦手动修改就不再覆盖。受保护服务未部署时会明确显示连接失败，没有演示保险箱或模拟成功流程。Linux 已通过窗口完成真实创建、导入、打开、关闭、扩容及擦除；Windows 服务通道尚未接入。

安装界面测试依赖并下载浏览器：

```bash
cd apps/desktop && npm ci && npx playwright install chromium
```

在项目根目录运行：

```bash
npm --prefix apps/desktop test
```

界面测试使用独立测试适配器，验证失败停留、密码原样发送与清空、重复提交拦截、确认词和平台字段；不替代真实挂载/擦除测试。Linux 原生窗口已验证服务不可用提示、新建、挂载、关闭和擦除主流程；0.1.41 补齐挂载中擦除、取消和占用后重试。0.1.48 补齐扩容，0.1.49 收紧结果确认和任务查询重试；[IPC 约定](docs/architecture/desktop-ipc.md) 记录当前接口、任务状态和安全边界。

桌面版本须同步根 Cargo.toml、Tauri 配置、前端 package.json 与 package-lock.json；测试产物和自动生成的 Tauri schema 不提交。

## 受控目录访问基础

Linux 的 `sv-service::managed` 通过目录文件描述符逐级打开 root 所有、不可被组/其他用户写入的完整路径链。容器只接受服务身份所有的私有普通文件，拒绝符号链接、硬链接、路径跳转及非普通文件；已打开目录不会因原路径被替换而重定向。此库不安装服务，也不替代加密事务和文件锁。

权限验收探针仅操作自己创建的 `/var/lib/safevault-permission-probe-*` 临时目录；普通用户分支先验证路径、标记与 root 权限，再检查删除、改名、截断、覆盖和替换均遭拒绝。已通过系统认证实测：普通用户的五种直接破坏均被拒绝，同时经 root 鉴权 Socket 创建、查询及确认擦除真实加密容器成功。测试目录已按准确文件名清理；此结论限于 Linux 实验服务与本次环境。

```bash
cargo build -p sv-service --example managed_permissions --locked
```

在系统认证可用时执行（不会处理实际保险箱）：

```bash
pkexec target/debug/examples/managed_permissions "$(id -u)" "$(id -g)"
```

服务端强类型请求解析已加入 `sv-service::protocol`：校验版本、标识、参数、容量、路径和确认词，拒绝未知字段及强制卸载；密码与擦除凭据不提供 Debug/Serialize 并使用零化内存。该解析器已用于 Linux 实验服务的实际业务分发。

## 持久任务日志

`sv-service::jobs` 使用 SQLite WAL 与 FULL 同步保存非敏感任务目标、阶段、进度和固定错误码；密码和擦除凭据不进入可持久化类型。请求按调用者身份与请求 id 去重，同一个保险箱只允许一个未结束任务。只有达到操作的最终阶段才能发布成功。

服务重新打开日志时将排队和运行中的任务标记为 `INTERRUPTED`，保留原阶段并继续阻止冲突操作；后续调度器必须检查实际容器、注册表和挂载现场，再解除恢复占用。日志不会自动重放擦除。数据库损坏不会自动创建空历史，写入状态不确定后要求重新打开。0.1.50 在启动恢复时逐项核对待恢复任务的索引与 JSON，并要求每次更新命中一行；错配或未生效时回滚整批恢复，防止损坏记录重定向改写其他历史。

该模块已用于实验服务的创建、导入、打开、关闭、扩容与擦除事务；进程 SIGKILL 测试不等同于硬件掉电测试。状态目录须由调用者预先创建并验证整条受信路径，Windows ACL 和实机恢复仍待验证。

擦除确认基础库 `sv-service::challenge` 已实现随机一次性凭据、用户/目标绑定、120 秒过期与内存容量限制；凭据不持久化，重启需重新验密。该库已接入实验删除流程；凭据消费后无论成功或失败，新的擦除尝试均须重新验密。

`sv-core::Container::open_file` 可直接接收服务已核验的文件句柄，避免按路径二次打开；调用方仍负责受控目录、所有权及句柄独占要求。实验容器的 `erase_key_slots` 消费已解锁实例，清零两份当前头部、刷盘并回读验证，成功后返回仍持锁的文件句柄。它不会删除文件或注册表，也不承诺 SSD 历史页、快照和备份不可恢复；生产擦除流程尚未完成。

Linux `ManagedDirectory::unlink_verified_container` 已实现排他占用检查、目录权限复核、文件设备/inode 身份比对、相对目录 fd 移除和目录刷盘。它要求调用方先完成验密与擦除，不对任意客户端路径提供删除入口；已在 Linux 实验服务中串联并通过 root/普通用户验收。

Linux `experimental_erase::ExperimentalErase` 已串联实验格式的删除事务：UID 鉴权、注册表与认证 UUID 核对、固定目录/文件句柄、验密发凭据、任务阶段、双头部擦除、文件移除、注册表移除与幂等查询。中途失败保留 INTERRUPTED 阶段并阻止自动重试。已加入用户级验密失败限速并通过 Linux Socket 暴露。0.1.41 支持已挂载容器：在固定句柄上只读验密，确认后才正常卸载；占用时任务失败并保持挂载，释放占用后重新验密重试。卸载后重新取得排他锁、核对验密时两份头部的摘要再擦除。授权能力不保留密码或数据密钥，仍不能作为生产服务部署。

实验擦除协调器在单个配置用户的 60 秒滚动窗口内最多接受 5 次验密失败，达到上限后在 KDF 前拒绝并提供等待秒数；切换保险箱或成功验证不会清空失败历史。限速状态仅在服务内存中，服务重启会清空，不能替代生产服务的完整防滥用设计。

实验创建入口现在复用 `Container::initialize_file`：仅初始化新建的空普通文件，保持排他锁并从零偏移预分配；Unix 拒绝只读、追加模式和多链接文件。受控服务须负责临时文件的不可覆盖发布及失败清理，不能把该接口当作生产创建流程已经完成。

受控目录的 `StagedContainer` 支持按任务标识独占创建私有临时文件，以固定目录 fd 发布且不覆盖已有目标。发布前核验临时 inode、刷盘文件，发布后移除临时链接并刷盘目录。失败清理只处理仍匹配的本次临时文件，不删除正式文件或替换后的文件。链接发布中断可能留下两条链接，必须由任务恢复处理后才能重新打开，当前不会自动处理该现场。

`sv-service::experimental::ExperimentalService` 已串联创建任务：先持久记录目标及随机 UUID，再初始化受控临时文件、发布正式名称和登记。重复请求返回原任务；不同创建意图复用请求 id 会被拒绝。发布后登记失败保留容器及恢复阶段，同路径的待恢复任务阻止再次创建。`ExperimentalErase` 保留为兼容别名。实验容量当前是容器物理预分配字节数，尚未兑现生产逻辑容量与额外开销核算，不能作为正式容量保证。

实验服务导入仅检查受控根中的原文件并登记，不复制、移动或修复源文件。检查两份头部一致、公开 UUID、尺寸及占用；`UnverifiedInfo` 明确表示尚未验密，后续打开/擦除仍必须认证。头部不一致时保守拒绝导入，不能无密码猜测有效副本。实验头部没有创建时间，登记时间记录本机首次导入时刻；容量仍为实验文件物理字节数。

后台服务接入已有独立 `JobReader` 与注册表已发布快照读取：长任务进行时可查询持久阶段，不取得服务写锁或触发启动恢复。事务内部接受通知仅在任务落盘后发出，便于 IPC 先返回 job_id，再继续执行；实际 Socket 分发与后台执行入口已接入。

## Linux 实验服务入口

`safevault-service` 已支持 `vault.list`、`vault.info`、`vault.create`、`vault.import`、`vault.open`、`vault.close`、`vault.expand`、`vault.erase.prepare`、`vault.erase.commit` 和 `job.get`。任务落盘后立即返回编号，后台执行期间可独立查询列表和进度；重复请求按原意图去重。打开/关闭已串联会话日志与真实工作进程；已有本机实验安装与升级入口；异常恢复仍待完成，不能用作完整桌面成品。

服务必须由 root 通过系统认证启动，显式指定 `--experimental`、`--user`、`--group`、`--container-root` 和 `--state-directory`。容器根、状态目录及完整父路径须为 root 所有且不可被普通用户写入；状态目录建议 0700。默认 Socket 为 `/run/safevault/<UID>.sock`，运行目录需预先配置为 root 所有、用户可遍历。工作进程默认取服务程序同目录的 `safevault-mount-worker`，也可通过 `--mount-worker` 指定 root 受控 ELF 文件；不能直接使用普通用户可改写的工作区程序。已有 Socket 只按严格的失效检测规则回收，活动或未知对象不覆盖；正常退出只移除自身 Socket。当前尚未提供正式安装器，不建议长期部署实验版本。

```bash
cargo run -p sv-service --bin safevault-service -- --help
```

已执行真实 Socket 的创建、导入、列表、进度、擦除、幂等及错误响应测试，以及 root/普通用户隔离验收；原生桌面主流程及扩容已通过 Linux 实验验收；无残留挂载时的验密恢复与扩容续做已实现，完整异常恢复、Windows 服务及生产格式尚未完成。服务不会把未接入的功能报告为成功。

挂载适配现通过 `sv_fs::backend::Backend` 的最小文件接口访问节点和内容，节点视图不携带加密块位置；`mount_backend` 可接入远程后端，原 CLI 本地挂载接口保持兼容。权限分离的远程文件接口及普通用户挂载工作进程已经接入，并通过真实权限验收。

## 挂载专用文件通道（0.1.33）

`sv-service::fs_rpc` 将内部 inode 操作转发给持有加密核心的服务，客户端只有节点视图和文件数据，不能取得容器句柄、密钥或操作宿主路径。连接核验 UID/PID，每次请求检查递增序号，异常后不自动重试写入。文件通道单帧最多 8MiB、单次读写最多 1MiB；业务 Socket 的请求/响应限制保持 64KiB/2MiB。

该模块已由下述独立挂载进程使用，并于 0.1.37 接入服务打开/关闭事务；JSON 文件数据编码用于实验验证，性能与生产协议仍待评估。6 项测试覆盖真实加密持久化、空闲连接、越界读写及双方进程身份/序号校验。

## 普通用户挂载进程（0.1.34）

新增 `safevault-mount-worker`：只由指定服务以非 root 身份启动，核验 root 文件通道及服务 PID；控制管道只接受 `CLOSE`，报告 `MOUNTED`、`BUSY`、`CLOSED`。占用时保持挂载，不使用强制或懒卸载；正常卸载前核对挂载标识，异常退出留给服务恢复处理。父服务退出时内核终止工作进程。

真实 FUSE/RPC 组合测试已验证 1MiB 文件读写、重命名、占用拒绝卸载、释放后正常卸载及重新打开后的数据一致性。该测试的两端为同一普通用户，不能代替 root/普通用户隔离验收。root 验收工具 `remote_mount` 已在修复降权顺序后实测通过：root 持有加密核心、UID/GID 1000 执行文件操作，验证容器直接读取/删除被拒绝、正常卸载和控制管道断开后的卸载，重开数据一致。专用测试目录已逐项清理。

构建验收工具：`cargo build -p sv-service --bins --example remote_mount --locked`。经系统图形认证运行：`pkexec --disable-internal-agent "$PWD/target/debug/examples/remote_mount" "$(id -u)" "$(id -g)" "$PWD/target/debug/safevault-mount-worker"`。仅使用新建的 `/var/lib/safevault-mount-probe-*` 专用测试目录；失败时保留现场，不递归清理。

服务打开/关闭任务已调用此进程；实验安装器部署 root 所有的程序和受控运行目录。已有有限验密恢复，完整异常现场恢复和生产交付仍未完成。

## 一次认证运行整批权限测试

以普通用户运行 `bash scripts/verify-privileged.sh`。脚本先用普通用户构建，再通过一次系统认证依次执行：受控容器权限及创建/擦除验收、跨权限挂载与占用拒绝关闭、控制管道断开后的正常卸载。root 阶段只执行这些固定探针，不运行构建工具。结束后进程退出，不修改 sudoers、Polkit 免密规则或保存管理员密码。

每次运行整批仍可能需要一次系统认证；不是永久免密。0.1.38 的 Linux 实验安装已提供常驻系统服务，桌面日常操作直接发送已鉴权请求。保险箱解锁密码与系统认证相互独立。

0.1.34 阶段的历史测试结果见 [Linux 回归记录](docs/testing/linux-0.1.34.md)；当次仅补充验收工具和测试记录，没有增加功能版本。

## 当前 Linux 机器验收

已在 Deepin 25 真机复测完整回归与跨权限挂载，并新增 `python3 tests/linux_workload.py`：覆盖混合文件操作、错误密码不改写源文件、4 次真实挂载及 SIGKILL 后已同步数据的散列一致性。该脚本已纳入 `bash scripts/verify.sh --with-fuse`。

早期仅验证窗口启动，记录见 [Linux 真机验收记录](docs/testing/linux-machine-acceptance.md)。0.1.37 接通打开/关闭，0.1.38 首次实验安装；本机当前实际安装为 **0.1.54**，安装时已核对运行程序路径、安装散列和真实原生流程，后续出现的服务故障尚待恢复。记录见 [0.1.54](docs/testing/linux-0.1.54.md)、[0.1.55](docs/testing/linux-0.1.55.md)；完整产品验收仍未通过。

## 挂载会话管理（0.1.35）

`sv-service::mount_session` 用独立管理线程保持普通用户挂载进程，避免短时业务线程退出触发父线程死亡信号。占用时保留挂载；只有子进程正常卸载退出、加密文件通道同步结束并释放密钥之后，才确认关闭。消息长度及等待时间有界，异常时中止文件通道并要求恢复，不采用强制或懒卸载。

工作进程须位于 root 受控安装路径，按固定文件句柄执行，拒绝脚本、可被普通用户改写的文件及链接。`verify-privileged.sh` 增加第 4 个托管会话探针，已实际验证短时启动线程退出后仍可读写、占用保持、正常关闭及重复关闭。

该管理器已于 0.1.37 接入持久会话记录及 `vault.open/close` 业务接口；0.1.38 原生主流程已通过，导入与异常恢复仍待验收。

## 挂载意图持久化（0.1.36）

任务数据库升级到本机 schema v2，保留原任务并增加不含秘密的会话记录。启动前登记会话意图，记录打开中、已挂载、关闭中或待恢复状态；每次服务重新打开日志时，所有未确认关闭的会话进入待恢复，不能依据“打开任务曾成功”推断当前已关闭。

记录按用户、保险箱、会话标识及挂载路径校验，迟到的旧会话关闭不能移除新会话。正常关闭只有在 Closing 状态并核对会话标识后才能移除记录；恢复移除另有明确的现场检查入口。已通过 v1 迁移、损坏记录拒绝、状态转换及 SIGKILL/WAL 恢复测试。该日志已于 0.1.37 接入业务打开/关闭，0.1.44 接入无残留挂载时的验密恢复；完整残留挂载自动恢复仍未实现。

## Linux 服务打开/关闭（0.1.37）

真实业务接口已支持密码验证、打开任务、普通用户挂载、列表状态、文件占用拒绝关闭、正常关闭与重复请求去重；打开成功记录最近打开时间。挂载目录不存在时仅由普通用户工作进程创建最后一级，父目录必须已有且可访问，失败不会擅自换路径。

关闭只有在挂载进程和加密文件通道均正常结束后才移除会话记录；占用时任务失败并保持已打开状态。服务停止会尝试正常关闭所有会话，失败保留恢复记录，禁止强制或懒卸载。已关闭容器的关闭请求也检查原文件排他锁，避免误判其他实例的占用。

业务响应等待调整为 35 秒，与服务 30 秒处理等待匹配；入站请求仍为 5 秒，帧大小限制不变。新增 6 秒延迟响应回归，覆盖此前真机验密请求提前超时的问题。

已通过真实 Socket 的错误密码、重复打开请求、1MiB 读写、占用关闭失败、列表状态、重开数据一致及服务停止自动卸载验收。0.1.38 补齐实验安装和原生主流程，0.1.41 接通已挂载容器擦除，0.1.44 接通有限验密恢复；完整异常现场恢复仍待完成。

## 挂载路径准备（0.1.39）

验密后、任务和挂载意图入库前，由普通用户工作进程检查路径。非空目录、缺失父目录和权限不足等确定错误返回 `E_MOUNT_PATH`，保持已关闭；修正现场后可直接重试。正式挂载时再次检查，竞争或实际挂载异常仍进入待恢复状态。

受控容器旁不存在的默认挂载目录由服务通过固定父目录句柄创建为用户 0700，受控父目录继续保持 root 所有且不可被用户写入；已有文件、链接和权限不匹配目录保留原样。实际 root/普通用户探针已验证默认目录挂载、停服卸载，以及非空目录错误后的重试。该能力已随 0.1.40 部署到本机。

## 升级与独立原生测试（0.1.40）

使用 `bash scripts/install-linux.sh --upgrade` 升级已安装实验版；核对旧安装散列、拒绝活动会话，保留旧程序及配置资料。中断后可用同一版本产物继续；实际新服务与鉴权 IPC 通过后才报告完成。[安装说明](docs/linux-install.md) 记录了边界和恢复标记。

安装 Xvfb、xauth、xdotool、Python GI/Gdk 后，`bash scripts/verify-native.sh` 在独立显示和会话总线中驱动实际 Tauri 程序，连接本机 root 服务和真实 FUSE；只在空的实验列表中操作新测试容器。已验证非空目录失败重试及错误确认词保护，并复测主流程。独立会话中的 Deepin 文件管理器启动受环境限制，不能据此认定系统文件管理器完整验收通过。

原生导入与服务重启验收见 [Linux 0.1.41 测试记录](docs/testing/linux-0.1.41.md)。导入前后核对原文件身份和整文件 SHA-256；带已关闭容器的正常重启、SIGKILL 重启及连续崩溃限速后的管理员恢复均已实测。该管理员恢复仅重启系统服务，不等于已实现异常挂载/未完成事务的恢复执行器。

## 无残留挂载时的恢复与重新打开（0.1.44）

“需要恢复”的保险箱可点“打开”，输入密码后先检查当前目录和所有引用的数据块。服务持续持有原容器固定文件句柄及排他锁，核对 UUID 和旧会话来源，确认实际无挂载、挂载目录可用后，才在同一个 SQLite 事务中解除旧打开/关闭任务与会话的恢复保护；旧任务保留为失败，新打开另行记录。错误密码、占用、损坏或持久化失败均保留恢复状态。

当前 schema v3 及旧 v2 均未记录内核挂载身份，因此此流程要求本用户在服务所在挂载命名空间中没有任何 `safevault-gate0` 挂载；需先关闭其他保险箱，失效挂载由管理员核对身份后正常卸载。不会按旧路径擅自卸载，不使用强制/懒卸载，也不会重放中断的创建、导入或擦除。大量数据检查可能超过单次 IPC 等待时间；客户端保留原请求标识，重试同一请求查询结果，避免重复打开。

本轮验证详见 [Linux 0.1.44 测试记录](docs/testing/linux-0.1.44.md)。完整异常现场自动恢复、生产格式、GC、Windows 实机、硬件掉电和安全审查仍待完成。

0.1.45 补齐异常退出后的失效文件通道清理：恢复前只处理原会话的断开套接字，启动时清理有已结束任务依据的历史通道；活动监听、未知对象及待恢复任务均保留。当时已通过全量回归、真实权限、升级及原生强杀恢复验收并安装 0.1.45；当前安装版本见上方最新机器验收。

## 扩容增量

用户于 2026-10-29 新增扩容和扩容前空间检查要求，见 [扩容设计](docs/expansion.md)。0.1.46 已实现 Linux 底层空间预检、实际预留、双头部容量发布及中断后继续；已有文件数据、UUID 和 inode 保持不变。0.1.47 已接入服务持久扩容任务、文件身份核对、验密续做和请求幂等；0.1.48 已接入桌面扩容、固定目标续做、密码重输和任务查询重试；0.1.48 阶段实际完成安装，并核对运行进程、安装文件散列和 schema v3；原生空间不足、错密、正常扩容、服务失败/重启续做和数据复验通过，见 [扩容验收记录](docs/testing/linux-expansion.md)。