CamWalGuardian

A Windows desktop guardian for abnormal CapabilityAccessManager.db-wal growth.

CamWalGuardian 是一个面向 Windows 10/11 的中文桌面守护应用，专门用于持续监控、诊断并安全清理 CapabilityAccessManager.db-wal 异常膨胀问题。它不是通用清理器，也不是简单的脚本按钮集合，而是一个具备后台守护、权限提示、日志留痕、诊断导出和任务计划自启能力的专用缓解工具。

当前版本：0.2.0

为什么要做这个项目

当 CapabilityAccessManager.db-wal 持续增长时，它可能在很短时间内占掉几十 GB 甚至上百 GB 的系统盘空间。受影响用户往往不知道：

• 该停哪个服务
• 能删哪个文件，不能删哪个文件
• 什么时候必须使用管理员权限
• 如何避免误删主数据库或误杀共享宿主进程
• 出问题后应该看什么日志和诊断信息

CamWalGuardian 的目标不是“完美找出根因”，而是把这条高风险、反复出现、容易误操作的处理链路封装成一个更安全、更可理解、更适合长期运行的桌面应用。

核心亮点

• 持续监控 WAL 文件大小，超过阈值时自动执行受控清理。
• 严格白名单校验，只处理指定 .db-wal 文件，绝不触碰主数据库文件。
• 清理流程感知 camsvc 状态，拒绝粗暴结束共享 svchost。
• 提供中文桌面界面、系统托盘、后台守护和开机自动启动。
• 提供滚动日志、诊断导出和最近清理记录，方便自查和远程协助。
• 采用 PySide6 + Python 构建，适合继续维护、打包和二次开发。

架构摘要

• app/ui：中文桌面界面、托盘菜单和页面展示。
• app/core：数据模型、清理流程编排、守护线程、Qt 信号桥。
• app/services：WAL 文件访问、camsvc 服务控制、任务计划、自诊断、提权检测。
• app/utils：路径、配置、日志、格式化和子进程封装。
• tests：配置与 WAL 安全校验的基础单元测试。
• samples：示例配置与示例日志输出。
• .github/workflows：Windows CI。
• docs：架构文档与工程说明。

项目树

CamWalGuardianApp
├─ .github
│  └─ workflows
│     └─ windows-ci.yml
├─ app
│  ├─ main.py
│  ├─ bootstrap.py
│  ├─ app_info.py
│  ├─ runtime.py
│  ├─ core
│  │  ├─ cleanup_manager.py
│  │  ├─ models.py
│  │  ├─ signals.py
│  │  └─ watcher.py
│  ├─ resources
│  │  └─ icons
│  │     └─ guardian.svg
│  ├─ services
│  │  ├─ camsvc_service.py
│  │  ├─ diagnostics_service.py
│  │  ├─ elevation_service.py
│  │  ├─ scheduler_service.py
│  │  └─ wal_service.py
│  ├─ ui
│  │  ├─ dashboard_page.py
│  │  ├─ diagnostics_page.py
│  │  ├─ logs_page.py
│  │  ├─ main_window.py
│  │  ├─ settings_page.py
│  │  └─ tray.py
│  └─ utils
│     ├─ config.py
│     ├─ formatting.py
│     ├─ logger.py
│     ├─ paths.py
│     └─ process_helpers.py
├─ docs
│  └─ ARCHITECTURE.md
├─ samples
│  ├─ config.sample.json
│  └─ sample.log
├─ tests
│  ├─ test_cleanup_manager.py
│  ├─ test_config.py
│  └─ test_wal_service.py
├─ .editorconfig
├─ .gitignore
├─ build.bat
├─ CamWalGuardian.spec
├─ CONTRIBUTING.md
├─ pyproject.toml
├─ requirements.txt
└─ run_dev.bat

GitHub 就绪度

当前仓库已经补齐了面向公开协作的基础设施：

• .gitignore
• .editorconfig
• pyproject.toml
• CONTRIBUTING.md
• docs/ARCHITECTURE.md
• GitHub Actions Windows CI
• 稳定的 PyInstaller .spec 文件

如果后续准备正式公开发布，还建议再补一个明确许可证文件。

功能范围

• 默认每 10 秒检查一次：
  • C:\ProgramData\Microsoft\Windows\CapabilityAccessManager\CapabilityAccessManager.db-wal
• 可选附加监控：
  • C:\ProgramData\Microsoft\Windows\CapabilityAccessManager\CapabilityConsentStorage.db-wal
• 默认阈值：64 MB。
• 支持主界面手动检查、手动清理、启动/停止守护、安装/移除开机自启。
• 支持系统托盘模式、最小化到托盘、托盘快捷清理与守护控制。
• 支持 ProgramData 下的滚动日志、界面日志尾部查看、诊断导出。
• 支持无界面命令：
  • --version
  • --check-once
  • --cleanup-now
  • --export-diagnostics

清理工作流

CamWalGuardian 的核心清理流程如下：

1. 精确校验目标路径，只允许白名单中的 .db-wal 文件。
2. 明确拒绝主数据库文件：
   • CapabilityAccessManager.db
   • CapabilityConsentStorage.db
3. 读取 WAL 当前大小和 C 盘可用空间。
4. 优先尝试停止 camsvc。
5. 仅对已验证的 WAL 目标执行删除。
6. 如果删除失败且疑似文件占用：
   • 重新检查 camsvc 当前宿主进程和共享服务列表。
   • 只有在确认 camsvc 独占该进程时，才允许按配置强制结束进程。
   • 绝不盲目结束共享的 svchost。
7. 重试删除。
8. 按设置决定是否重启 camsvc。
9. 记录日志、耗时、清理前后文件大小、清理前后 C 盘空间和错误信息。

安全保护

• 永不删除主 .db 文件。
• 永不删除 CapabilityAccessManager 整个目录。
• 永不对 ProgramData 做泛化清理。
• 永不清理白名单之外的文件。
• 永不强制结束共享宿主中的 camsvc。
• 所有删除动作都必须经过精确路径校验。
• 计划任务、自启和服务控制均明确区分是否具备管理员权限。

配置文件与日志

• 运行时配置：
  • C:\ProgramData\CamWalGuardian\config.json
• 运行时状态：
  • C:\ProgramData\CamWalGuardian\state.json
• 滚动日志目录：
  • C:\ProgramData\CamWalGuardian\logs\
• 诊断导出目录：
  • C:\ProgramData\CamWalGuardian\exports\

config.json 示例见 samples/config.sample.json。

管理员权限说明

应用会检测当前是否以管理员身份运行，并在界面顶部显示警告横幅。以下操作通常需要管理员权限才更可靠：

• 停止或启动 camsvc
• 删除被服务占用的 WAL
• 强制结束独立的 camsvc 宿主进程
• 创建或删除“开机自动启动”计划任务

开发运行

run_dev.bat

带参数运行：

run_dev.bat --watch --minimized

命令行模式：

set PYTHONPATH=%cd%
.venv\Scripts\python.exe -m app.main --version
.venv\Scripts\python.exe -m app.main --check-once
.venv\Scripts\python.exe -m app.main --cleanup-now
.venv\Scripts\python.exe -m app.main --export-diagnostics

PyInstaller 打包

推荐直接运行：

build.bat

等价命令如下：

python -m PyInstaller ^
  --noconfirm ^
  --clean ^
  CamWalGuardian.spec

输出目录为：

dist\CamWalGuardian

任务计划行为

开机自启通过 Windows Task Scheduler 实现，策略如下：

• 触发时机：用户登录时。
• 权限级别：最高权限。
• 启动参数：--watch，并在配置启用时追加 --minimized。
• 界面会实时检查计划任务是否存在。

测试

set PYTHONPATH=%cd%
.venv\Scripts\python.exe -m unittest discover -s tests -v

已知现实限制

• 该工具不会尝试对 WAL 膨胀根因做强耦合推断。
• camsvc 控制与计划任务创建在未提权环境下可能失败，但应用会给出可见提示并保留日志。
• 某些 Windows 构建上的服务宿主命令行细节可能不同，因此“独立宿主”判定采用了进程内服务列表校验，而不是仅依赖命令行字符串。
• 在受限开发环境下，日志会自动从 ProgramData 回退到本地目录或当前工作目录，避免 CLI 命令因日志初始化失败而中断。