3分钟完成首次扫描:ChatArchiveGuard 在 macOS、Linux 和 Windows 上的快速上手教程
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。