3分钟完成首次扫描:ChatArchiveGuard 在 macOS、Linux 和 Windows 上的快速上手教程

原创2026-10-23 23:49:362,264 阅读

3分钟完成首次扫描:ChatArchiveGuard 在 macOS、Linux 和 Windows 上的快速上手教程

ChatArchiveGuard 是一个本地只读的聊天归档隐私审计工具,能在共享或迁移前扫描聊天导出文件,找出疑似密钥、个人信息形态、JSON/JSONL 损坏和 SQLite 结构问题,且全程不修改、不上传任何数据。本教程带你 3 分钟内完成三大平台的首次安装与扫描。

1分钟了解:ChatArchiveGuard 能做什么

在把聊天记录导出交给备份、分析或迁移流程之前,先做一道"本地安检"。一次扫描可以回答三个问题:

问题 ChatArchiveGuard 的回答
有没有疑似密钥或凭证? 检测私钥标记、提供商密钥、Bearer 令牌、JWT 形态等(secret.* 类别)
有没有个人信息形态? 邮箱、IP 地址、证件号、通过 Luhn 校验的银行卡号等(pii.* 类别)
文件格式完好吗? 校验 UTF-8 / JSON / JSONL,并对 SQLite 运行结构快检(format.*、sqlite.* 类别)

三个关键设计让你放心使用:

  • 🔒 纯本地扫描:运行时只使用 Python 标准库,没有网络客户端、遥测或自动更新;
  • 🛡️ 只读不改:只读取你指定的文件或目录,SQLite 仅在私有副本上读取;
  • 📋 命中值不进报告:报告只显示类别和数量,永远不会泄露匹配到的实际内容。

⚠️ 它是交付前的审计门禁,不是聊天阅读器:无法证明消息完整或来源真实,匹配结果只是风险提示。

第一步:安装 ChatArchiveGuard(约 1 分钟)

唯一前置要求:Python 3.11 或更高版本。建议先创建隔离环境(venv),避免污染系统 Python。

macOS / Linux 一键安装

python3 -m venv .venv
. .venv/bin/activate
python -m pip install chat-archive-guard

Windows PowerShell 一键安装

Windows 使用 Python Launcher(py)和不同的路径写法:

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install chat-archive-guard

💡 想锁定发布版本?把安装命令改为 python -m pip install "chat-archive-guard==0.1.0",版本说明见 RELEASE_NOTES.md。

第二步:3 分钟完成首次扫描

扫描你自己的聊天导出

安装后直接传入要检查的文件或目录路径:

chat-archive-guard /path/to/archive

Windows 上通过模块方式运行:

.\.venv\Scripts\python.exe -m chat_archive_guard C:\path\to\archive

推荐加上两个参数:--json 输出稳定的 JSON 报告,--summary-only 省略文件名和明细,只保留状态、计数和类别汇总,适合分享给同事或贴进 CI 日志:

chat-archive-guard /path/to/archive --json --summary-only

常用参数一览(完整定义见 src/chat_archive_guard/cli.py):

参数 作用 默认值
--json 输出 JSON 格式报告 关闭
--summary-only 省略发现明细和相对文件名 关闭
--max-file-mib 单个文本文件上限(MiB) 16
--max-sqlite-rows 单个数据库最大检查行数 100,000
--max-files 检查的文件总数上限 10,000

没有导出文件?用内置合成演示体验

仓库自带生成器 scripts/generate_demo.py,只创建两份固定的虚构数据(一份 JSONL + 一份 SQLite),测试标记明确写着"永不有效",适合安全地体验完整流程。在仓库根目录执行:

demo_parent="$(mktemp -d)"
demo_dir="$demo_parent/chat-archive-guard-demo"
PYTHONDONTWRITEBYTECODE=1 python3 scripts/generate_demo.py "$demo_dir"
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m chat_archive_guard "$demo_dir" --summary-only

预期输出如下——注意它故意发现了 3 个问题,这正是演示的目的:

synthetic demo: PASS files=2
FAIL files_seen=2 files_scanned=2 finding_count=3 complete=true truncated=false details_omitted=true findings_omitted=true
category=format.invalid_jsonl count=1
category=secret.assignment count=1
category=secret.provider_key count=1

演示结束后删除刚创建的临时目录即可。

看懂结果:退出码与关键字段

退出码 含义
0 没有发现项,且符合范围的内容全部完成扫描
1 发现问题,或有内容未能完整检查
2 扫描路径或参数无效

报告中还有 4 个字段值得盯住:

  • files_seen:遍历到的文件总数(含不支持检查的文件);
  • files_scanned:真正进入内容检查的文件数;
  • complete:符合范围的内容是否全部完成检查;
  • truncated:是否因限制、读取失败或安全拒绝留下盲区。

只有无发现项 + 扫描完整 + 未截断时,ok 才会是 true。complete=true 只代表扫描范围完成,不代表聊天记录在业务上完整。

平台差异:Windows 的 SQLite 特殊行为

能力 Linux macOS Windows
文本、JSON、JSONL 检查 ✅ 支持 ✅ 支持 ✅ 支持
SQLite / WAL / SHM 检查 ✅ 支持 ✅ 支持 ⚠️ 安全拒绝
符号链接防护 ✅ ✅ ✅(含重解析点)

Windows 标准 Python 缺少本项目安全边界要求的"原子 no-follow 打开"能力,遇到 SQLite 时会返回 sqlite.sidecar_unsafe 并标记 complete=false、truncated=true,而不是降低保护等级继续读取——这是设计行为,不是故障。更多边界说明见 THREAT_MODEL.md。

常见问题速查

Q:会上传我的聊天记录吗? 不会。扫描纯本地运行,没有网络客户端或遥测。

Q:能检查所有聊天导出格式吗? 支持 .txt、.md、.log、.csv、.tsv、.yaml、.yml、.json、.jsonl、.ndjson 及 SQLite 数据库;压缩包、加密文件和附件不在范围内。

Q:扫描干净就绝对安全吗? 不代表绝对安全。无发现项只说明已检查内容没有触发当前规则,未知模式和不支持格式仍可能存在盲区。

Q:能在 CI 中使用吗? 可以。推荐 --json --summary-only 组合,避免相对文件名进入构建日志;切勿把真实聊天内容上传为公开构建产物。

写在最后

从安装到第一次扫描,全程只需 3 步:创建隔离环境 → 安装 chat-archive-guard → 传入路径。把 ChatArchiveGuard 加入你的分享与迁移检查单,在数据离开本机之前,让疑似密钥和格式问题先现形。更多细节可查阅 README.md、安全政策 SECURITY.md 以及贡献规范 CONTRIBUTING.md。

登录后查看全文
chat-archive-guard