核心用法
ezBookkeeping API Tools 是一个 POSIX Shell 编写的命令行工具，用于与自托管个人财务管理应用 ezBookkeeping 进行 API 交互。用户需配置 EBKTOOL_SERVER_BASEURL 和 EBKTOOL_TOKEN 环境变量或 .env 文件，通过 ebktools.sh 或 ebktools.ps1 脚本执行各类操作。
核心功能模块：
- 账户管理：
accounts-list 查询账户信息，accounts-add 添加新账户 - 交易管理：
transactions-list / transactions-list-all 查询交易，transactions-add 创建新交易 - 分类标签：
transaction-categories-list/add、transaction-tags-list/add 管理交易分类体系 - Token 管理：
tokens-list 查看会话，tokens-revoke 撤销指定 Token - 辅助功能：
exchangerates-latest 查询汇率，server-version 获取服务器版本
技术特性：
- 依赖标准 Unix 工具链（curl、jq、grep、sed、awk、date）
- 支持时区配置（
--tz-name 或 --tz-offset） - 双重输出模式：Markdown 表格（默认）或原始 JSON（
--raw-response） - 参数类型验证（整数、布尔值、地理位置）与 URL 编码防护
显著优点
1. 自托管数据主权：用户完全掌控财务数据存储位置，避免 SaaS 服务的隐私风险
2. 轻量无依赖：仅依赖系统标准工具，无需额外运行时或库
3. 安全防护机制：Bearer Token 认证、参数 URL 编码、输入类型验证、环境变量隔离敏感信息
4. 功能完整：覆盖个人财务管理的 CRUD 全场景，支持多币种汇率查询
5. 跨平台支持：提供 POSIX Shell 和 PowerShell 双版本
潜在缺点与局限性
1. 写操作风险高：transactions-add、accounts-add 等命令直接修改财务数据，误操作可能导致数据损坏
2. Token 管理双刃剑：tokens-revoke 可终止任意会话，存在意外踢出其他客户端的风险
3. Shell 注入隐患：虽经 URL 编码缓解，但 Shell 脚本本质存在命令注入攻击面
4. 证书验证依赖系统：curl 未强制证书验证，依赖系统默认配置
5. 无内置备份机制：写操作前需用户自行确保数据备份
6. 地理位置合规：geoLocation 参数涉及敏感个人信息，需用户自行评估 GDPR/CCPA 合规性
适合人群
- 技术型个人用户：熟悉命令行操作，具备自托管服务器维护能力
- 隐私敏感用户：不愿将财务数据托管至第三方云服务
- 开发者/自动化需求：需要将记账流程集成到脚本或 CI/CD 流水线
- 多币种使用者：需要实时汇率转换支持的国际收支管理
常规风险
| 风险类型 | 具体表现 | 缓解建议 |
|---------|---------|---------|
| 数据完整性风险 | API 调用错误导致财务记录错误 | 写操作前复核参数、定期备份、开启审计日志 |
| 访问控制风险 | Token 泄露或权限过大 | 使用最小权限 Token、90 天轮换、限制 `.env` 文件权限（chmod 600） |
| 会话中断风险 | `tokens-revoke` 误操作 | 确认 Token ID 后再执行、避免自动化清理 |
| 隐私合规风险 | 地理位置数据收集 | 建立 ROPA 记录、获取明确同意、提供数据导出机制 |
| 网络安全风险 | HTTP 传输或证书未验证 | 强制 HTTPS、部署可信证书、定期安全审计 |