零上传零遥测：claude-usage本地用量统计工具的隐私保护与安全性设计全解析
【免费下载链接】claude-usageA local dashboard for tracking your Claude Code token usage, costs, and session history. Pro and Max subscribers get a progress bar. This gives you the full picture.项目地址: https://gitcode.com/gh_mirrors/cl/claude-usage
claude-usage是一款专为 Claude Code 打造的本地用量统计工具：它只读取你电脑上的本地日志，零上传、零遥测，即可生成 Token 用量图表、成本估算与会话历史，并支持 Pro / Max 订阅进度条。本文带你完整拆解它的隐私保护与安全性设计，看看"数据不出本机"是如何做到的。
一、数据从哪来？全部来自本地日志
claude-usage 不接入任何云端 API，它的数据源只有一个——Claude Code 在你本机写下的会话日志：
~/.claude/projects/**/*.jsonl → scanner.py 解析 → ~/.claude/usage.db（SQLite）也就是说，整条数据流100% 发生在你的机器内部。扫描器 scanner.py 只做两件事：逐行解析 JSONL 记录中的 Token 数与模型信息，然后写入本地 SQLite 数据库。
数据库里存了什么？打开 scanner.py 的建表语句可以看到：sessions、turns、agents三张表只记录Token 计数、时间戳、模型名称、项目名等聚合统计字段，不存储对话原文——你的代码内容和聊天记录始终留在原始日志里，不会被二次搬运。
二、零遥测：没有后台，连"上报心跳"都没有
这是 claude-usage 最硬核的隐私设计之一：
- 零第三方依赖🛡️：整个工具只用 Python 标准库（
sqlite3、http.server、json、pathlib），不需要pip install，没有供应链依赖风险，也不存在任何遥测 SDK。 - 唯一的网络行为可被明确审计：网页版仪表盘底部有一个"检查更新"链接，它由浏览器直接请求公开发布 API 的元数据，不携带任何用量数据、无需认证，结果在本地缓存 24 小时，且网络失败时静默处理——在 dashboard.py 中一目了然，VS Code 扩展内置界面则完全不触发该检查。
- 没有账户体系：无需登录、不采集设备指纹、不收集崩溃日志。
简单说：这个工具没有任何代码路径会把你的用量数据发往互联网。
三、默认只监听 localhost，局域网也访问不到
仪表盘本质是一个本地 Web 服务。看 dashboard.py 的serve()函数：默认绑定地址是localhost:8080，只有当用户主动传入--host 0.0.0.0或设置HOST环境变量时，才会监听所有网卡。
这意味着：
| 场景 | 谁可以访问 |
|---|---|
| 默认启动 | 仅本机localhost |
明确指定0.0.0.0 | 同局域网（需用户主动配置） |
安全姿态是"默认安全，暴露需显式选择"，符合最小暴露面原则。
四、Docker 模式：只读挂载 + 网络隔离
如果你倾向用容器运行，scripts/run-docker.sh 提供了教科书级的隔离配置：
~/.claude以只读（ro）方式挂载——容器能读日志，但无法修改或删除你的原始数据；- 容器运行在独立 Docker 网络中，与宿主机其他容器隔离；
- SQLite 数据库存放在独立的命名卷（
claude-usage-data）里，跨重启持久化，又不污染你的家目录； - 镜像本身也很干净：Dockerfile 基于
python:3.12-slim，仅复制 3 个 Python 文件，无多余服务。
五、VS Code 扩展：只走本机回环地址
VS Code 扩展把同一套仪表盘嵌进侧边栏，其实现同样保守：面板以http://127.0.0.1:<端口>/的 iframe 形式加载，只走本机回环。端口由 vscode-extension/src/port-allocator.ts 分配并稳定复用，保证 UI 状态（折叠区域等）在刷新后不丢失。Python 源码直接打包进.vsix，扩展侧没有任何远程数据通道。
六、快速上手：3 条命令开始
git clone https://gitcode.com/gh_mirrors/cl/claude-usage cd claude-usage python3 cli.py dashboard浏览器打开http://localhost:8080，即可看到完整的用量图表。其他常用命令见 README.md：scan（增量扫描）、today、week、stats。
七、核心文件速查
| 文件 | 隐私/安全要点 |
|---|---|
| scanner.py | 只读解析本地 JSONL，写入本地 SQLite，不存储对话原文 |
| dashboard.py | 默认绑定localhost，唯一网络行为是可选的更新检查 |
| cli.py | 终端命令入口，全部本地计算 |
| Dockerfile + scripts/run-docker.sh | 只读挂载 + 隔离网络 + 独立数据卷 |
| vscode-extension/src/ | 仅127.0.0.1回环通信，无远程数据通道 |
| tests/ | 测试使用临时文件隔离数据库，绝不触碰真实数据 |
总结：为什么说它"零上传零遥测"？
| 检查项 | 结论 |
|---|---|
| 数据是否离开本机？ | ❌ 全部在本机读取、存储、计算 |
| 是否有遥测/上报？ | ❌ 无任何代码路径发送用量数据 |
| 是否有第三方依赖？ | ❌ 纯 Python 标准库 |
| Web 服务是否暴露？ | ❌ 默认仅localhost |
| 原始日志是否被修改？ | ❌ 只读访问（Docker 模式强制只读挂载） |
对于在意隐私的开发者，claude-usage 证明了：透明的本地工具，同样可以给出"完整画面"——Token 消耗、成本估算、会话历史、订阅进度，一个都不少。🔒
【免费下载链接】claude-usageA local dashboard for tracking your Claude Code token usage, costs, and session history. Pro and Max subscribers get a progress bar. This gives you the full picture.项目地址: https://gitcode.com/gh_mirrors/cl/claude-usage
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
