---
title: WinUnLock 项目关键决策汇总
type: curated
permalink: main/projects/ea207d36-693c-4349-b3c8-7c40c8c889f5/curated/win-un-lock-项目关键决策汇总
stable_id: 937e5888-0a9b-45ee-9312-6e110ef1619b
scope: project
project_id: ea207d36-693c-4349-b3c8-7c40c8c889f5
workspace_type: development
usage_profile_id: null
preference_context: development
document_type: decisions
revision: 1
source_memory_ids:
- 67499b3a-97a6-4982-9c16-4afaa59d45f3
- d821d390-15d1-484a-98e1-6d9656f69bfe
- ffcc24b6-2d1a-46e8-bceb-49e187dd0c20
source_checkpoint_ids: []
source_file_ids: []
source_git_commit: null
source_git_commits: []
source_agent_sync_ids: []
model_connection: Sub2API
model_name: git-restore
source_count: 15
source_revisions:
  memory:d821d390-15d1-484a-98e1-6d9656f69bfe: '1'
  memory:67499b3a-97a6-4982-9c16-4afaa59d45f3: '1'
  memory:ffcc24b6-2d1a-46e8-bceb-49e187dd0c20: '1'
source_dispositions:
  processed: 15
  unchanged: 0
  unsupported: 0
  skipped: 0
cited_source_ids:
- memory:d821d390-15d1-484a-98e1-6d9656f69bfe
- memory:67499b3a-97a6-4982-9c16-4afaa59d45f3
- memory:ffcc24b6-2d1a-46e8-bceb-49e187dd0c20
job_cited_source_ids:
- memory:d821d390-15d1-484a-98e1-6d9656f69bfe
- memory:67499b3a-97a6-4982-9c16-4afaa59d45f3
- memory:ffcc24b6-2d1a-46e8-bceb-49e187dd0c20
conflicts: []
supersedes: []
preferences: []
source_cursor: 92
source_hash: 4ba0814abe7570a9e62a54340ca352579628d92bc49f330cda285b38a0442283
prompt_version: 2026-08-12.3
schema_version: '3'
curation_job_id: null
created_at: '2026-08-19T10:01:20.395598+00:00'
updated_at: '2026-09-23T15:12:13.999439+00:00'
tags:
- decision
- architecture
- security
- implementation
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
---

# WinUnLock 项目关键决策

以下决策直接来源于项目记忆（memory）文档，按重要性分组。

## 1. 项目整体技术方向
- **决定** 实现一个工程化的 **Credential Provider DLL + 命名管道 + 定时解锁客户端**（保留会话、不重启）。放弃 AutoAdminLogon 重启方案，因为需保留当前会话。*来源: [memory:ffcc24b6-2d1a-46e8-bceb-49e187dd0c20]*

## 2. Rust 工作区结构与关键参数
- Rust 工作区划分为四个 crate：
  - `common`（管道协议、配置、DPAPI 包装）
  - `provider`（cdylib，生成 Credential Provider COM DLL）
  - `client`（binary，负责每日定时读取凭据并通过管道发送）
  - `setup`（binary，交互式设置账户名/密码并使用 DPAPI 加密）
- 附加 PowerShell 安装/卸载脚本与中文 README。*来源: [memory:d821d390-15d1-484a-98e1-6d9656f69bfe]*
- **唯一 CLSID**：`{E9C67B30-B120-4838-A5A3-FBC2DE03C532}`（新生成，避免冲突）。
- **命名管道**：`\\.\pipe\WinUnLock`
- **数据目录**：`%PROGRAMDATA%\WinUnLock\`（包含 `config.toml`, `cred.bin`（DPAPI 加密凭据），日志子目录 `logs\provider.log`、`logs\client.log`）。
- 已验证的依赖组合：Rust edition 2024，`windows = 0.62.2`，`windows-core = 0.62.2`。

## 3. 管道协议与安全措施
- **管道协议 v1**（小端）：
  - `magic u32 = 0x554E4C4B ('UNLK')`
  - `version u32 = 1`
  - `user_len u32` + UTF‑16LE 字符串
  - `pass_len u32` + UTF‑16LE 字符串
  - `domain_len u32` + UTF‑16LE 字符串
  - 长度上限检查，读取完毕后 **zeroize** 内存。
- 数据流：系统计划任务（SYSTEM, Highest） → `client.exe` 读取 `cred.bin`（DPAPI LocalMachine 解密） → 通过命名管道发送凭据（带重试） → Provider 线程接收 → `CredentialsChanged` 通知 LogonUI → `GetSerialization` 调用 `CredPackAuthenticationBufferW` 序列化 → LSA 验证 → 解锁恢复原桌面。
- **安全恢复注意**：如果 Credential Provider 注册错误导致登录卡死，需要进入 WinRE/安全模式手动删除注册表中的 CLSID 项恢复。*来源: [memory:d821d390-15d1-484a-98e1-6d9656f69bfe]*

## 4. 原型验证经验教训（来自 Gitee winlogon 项目）
- 可成功编译生成 `winlogon.dll`（约 256 KB），导出 `DllGetClassObject`、`DllCanUnloadNow`、`DllMain`，说明 Rust cdylib 自动导出。*来源: [memory:67499b3a-97a6-4982-9c16-4afaa59d45f3]*
- **缺陷 & 教训**：
  1. `DllMain` 里硬编码日志路径 `D:\log\winlogon.log` 并使用 `.expect()`，导致加载时在不存在路径下 panic → 系统卡住。**决策**：在实现中绝不在 `DllMain` 中 panic，避免硬编码日志路径。
  2. README 内容占位、命名不规范、死代码。**决策**：提供完整、中文、使用说明的 README，移除死代码。
  3. 必须使用 **长度前缀协议**、**ACL 拒绝远程访问**、**仅在解锁场景激活**、**密码使用后 zeroize**。*来源: [memory:67499b3a-97a6-4982-9c16-4afaa59d45f3]*

## 5. 开发与测试约束
- **协作约定**：AI 负责完整实现（多 crate、安装/卸载脚本、中文文档），用户在虚拟机中验证后再部署到生产机器。
- **禁止** 在开发机器上实际执行 `regsvr32`、修改注册表或创建真实计划任务，只做构建、导出检查等只读验证。*来源: [memory:ffcc24b6-2d1a-46e8-bceb-49e187dd0c20]*

---
*本决策文档仅引用了项目记忆来源，未添加任何未在来源中出现的事实。*