后端前端金融科技【免费下载链接】ezbookkeepingezBookkeeping is an open source, powerful, self-hosted personal finance app that is easy to use.项目地址https://gitcode.com/gh_mirrors/ez/ezbookkeeping点击查看免费下载ezBookkeeping 是开源、可自托管的个人记账应用其官方 Skills 目录下内置了一套名为ebktools的 API 命令行工具SKILL.md允许你无需登录网页端直接用 Shell 或 PowerShell 调用服务端 REST API 来完成新增交易、查询流水、读取账户/分类/标签以及拉取汇率等操作。阅读本文后你将掌握 ebktools 的完整用法list/help/ 直接调用、全局时区与原始输出选项、12 个内置命令的详细参数并能理解脚本底层如何与 ezBookkeeping 的/api/v1接口对接从而把它接入自己的脚本、定时任务或 AI Agent 工作流。一、认识 ebktoolsezBookkeeping 的 API 命令行封装ebktools 不是独立的可执行程序而是随仓库一起分发的两个脚本文件运行环境依赖ebktools.shLinux / macOSsh兼容 Shellgrep、sed、awk、date、curl、jqebktools.ps1WindowsPowerShell 5.1 / 7无需额外依赖内部使用Invoke-WebRequest两个脚本共享同一套API 配置结构脚本内部以 JSONShell 版或 PowerShell 哈希表PS 版定义了每个命令的名称、HTTP 方法、请求路径、必填/可选参数、参数类型、参数说明、响应结构以及**美化输出PrettyResponse**规则。这意味着新增 API 只需扩展这份配置即可无需改动调用逻辑。从脚本的main()ebktools.sh可以看到入口在执行前会先做两件事检查必要依赖是否可用缺失时报错并返回退出码 127以及加载环境变量配置。二、快速上手配置、验证与三种基本用法1. 配置服务器地址与 API Token所有调用都依赖两个环境变量缺一不可变量是否必填含义示例EBKTOOL_SERVER_BASEURL必填ezBookkeeping 服务器基础地址不包含/api/v1前缀http://localhost:8080EBKTOOL_TOKEN必填ezBookkeeping API Token在 Web 端Token 管理中生成一段 JWT 字符串Linux / macOS 下通过export设置export EBKTOOL_SERVER_BASEURLhttp://localhost:8080 export EBKTOOL_TOKENYOUR_TOKENWindows PowerShell 下通过$env:设置$env:EBKTOOL_SERVER_BASEURL http://localhost:8080 $env:EBKTOOL_TOKEN YOUR_TOKEN关于 Token 的生成脚本配置中tokens-list返回的tokenType字段约定1: Normal Token普通登录会话、5: MCP Token、8: API Token。后端在 pkg/api/tokens.go 中提供TokenGenerateAPIHandler生成 API Token且只有USER_TOKEN_TYPE_NORMAL类型的当前令牌才有权生成 API Token见TokenGenerateAPIHandler中对claims.Type ! core.USER_TOKEN_TYPE_NORMAL的校验因此建议在网页端登录后用API Token渠道生成专用令牌供脚本使用。2. 列出所有可用命令Linux / macOSsh scripts/ebktools.sh listWindowsscripts\ebktools.ps1 list输出为按名称对齐的命令清单例如tokens-list、accounts-list、transactions-add、exchangerates-latest、server-version等每行附一句功能描述。3. 查看某个命令的帮助Linux / macOSsh scripts/ebktools.sh help commandWindowsscripts\ebktools.ps1 help command例如sh scripts/ebktools.sh help server-version。帮助页会展示HTTP 方法、请求路径、是否需要当前时区信息、必填参数含类型与说明、可选参数、响应结构以及一条可直接复制的调用示例。由于帮助文本会根据当前系统时区动态生成示例即使你记不住参数也能照着执行。4. 直接调用 API通用调用语法# Linux / macOS sh scripts/ebktools.sh [global-options] command [command-options] # Windows scripts\ebktools.ps1 [global-options] command [command-options]最小示例——查询服务器版本sh scripts/ebktools.sh server-version脚本会打印Calling API: GET http://localhost:8080/api/v1/systems/version.json随后输出响应结果默认格式化为 Markdown 表格而非原始 JSON。三、全局选项时区与输出格式调用任何命令前可附加三个全局选项Shell 版以--开头PowerShell 版以-开头选项说明--tz-name name/-tzName name当前时区的 IANA 名称例如北京时间用Asia/Shanghai--tz-offset offset/-tzOffset offset当前时区相对 UTC 的分钟偏移例如 UTC8 填480--raw-response/-rawResponse关闭美化输出直接显示原始 JSON 响应时区选项存在如下优先级规则见 ebktools.sh 的call_api实现若同时设置--tz-name与--tz-offset--tz-name优先若两者都未设置脚本自动探测当前系统时区Linux 下读取/etc/timezone或解析/etc/localtime符号链接Windows 下通过[System.TimeZoneInfo]::Local获取并附带一张 Windows 时区 ID → IANA 名称的映射表例如China Standard Time→Asia/Shanghai若探测失败示例帮助文本会回退到Asia/Shanghai与偏移480若某个命令标记为RequiresTimezone: true如transactions-list、transactions-add而脚本既探测不到系统时区、也未提供上述选项则会报错退出提示补全时区信息。为什么部分命令强制要求时区因为交易的时间语义依赖本地时区 UTC 偏移才能正确还原为账户所在地的记账时刻。脚本会把时区信息放入请求头X-Timezone-Name或X-Timezone-Offset一并发送给服务端。--raw-response则适合调试或对接其他程序此时脚本跳过 Markdown 表格渲染用jqShell 版对 JSON 做格式化后原样输出。四、12 个内置命令全景下面按功能分组列出全部内置命令及其参数。命令名即脚本第二参数参数以--Shell/-PowerShell前缀传入。1. 会话与 Token 查询tokens-list—GET /tokens/list.json无参数。返回当前用户的所有会话字段包括tokenId、tokenType1普通、5MCP、8API、userAgent、lastSeen会话最后刷新的 Unix 时间、isCurrent是否为当前会话。2. 账户管理accounts-list—GET /accounts/list.json无参数。返回当前用户全部账户含子账户层级字段id、name、parentId0表示一级账户、category、type、icon、iconType、colorRRGGBB 十六进制、currency、balance、comment、creditCardStatementDate、displayOrder、isAsset、isLiability、hidden、subAccounts。其中两个关键枚举category账户类别1现金、2活期/支票账户、3信用卡、4虚拟账户、5债务账户、6应收账户、7投资账户、8储蓄账户、9定期存单type账户类型1单一账户、2多子账户。accounts-add—POST /accounts/add.json需要时区参数必填类型说明name是string账户名称category是integer账户类别枚举同上type是integer账户类型1/2icon是string图标 IDiconType是integer图标类型0系统图标、1用户自定义图标color是string图标颜色 RRGGBBcurrency是stringISO 4217 货币代码父账户传---balance否string初始余额支持两位小数负债账户传负数balanceTime否integer余额对应的 Unix 时间设置balance时必填comment否string账户备注creditCardStatementDate否integer信用卡账单日3. 交易分类transaction-categories-list—GET /transaction/categories/list.json无参数。返回按类型组织的层级分类树1: Income收入、2: Expense支出、3: Transfer转账每个分类含id、name、parentId0为一级分类、type、icon、iconType、color、comment、displayOrder、hidden、subCategories。列表接口允许传type过滤类型枚举同上。transaction-categories-add—POST /transaction/categories/add.json参数必填类型说明name是string分类名称type是integer分类类型1收入 /2支出 /3转账icon是string图标 IDiconType是integer图标类型0系统 /1自定义color是stringRRGGBB 颜色parentId否string父分类 ID0表示一级分类comment否string分类备注4. 交易标签transaction-tags-list—GET /transaction/tags/list.json无参数。返回所有标签字段id、name、groupId所属标签组、displayOrder、hidden。transaction-tags-add—POST /transaction/tags/add.json参数必填类型说明name是string标签名称groupId否string标签组 ID0表示默认组5. 交易流水查询transactions-list—GET /transactions/list.json需要时区分页参数必填类型说明count是integer每页条数最大 50type否integer按交易类型过滤1余额调整、2收入、3支出、4转账category_ids否string按分类 ID 过滤逗号分隔account_ids否string按账户 ID 过滤逗号分隔tag_filter否string按标签过滤amount_filter否string按金额过滤keyword否string按关键词过滤must_have_pictures否boolean是否只取带凭证图片的交易max_time否integer最大时间序列 ID 游标0表示最新min_time否integer最小时间序列 ID 游标page否integer指定页码with_count否boolean是否返回总条数with_pictures否boolean是否返回图片 IDtrim_account否boolean是否只返回账户 IDtrim_category否boolean是否只返回分类 IDtrim_tag否boolean是否只返回标签 ID响应结构items数组每项含id、timeSequenceId、type、categoryId、category、time、utcOffset、sourceAccountId、sourceAccount、destinationAccountId、destinationAccount、sourceAmount、destinationAmount、hideAmount、tagIds、tags、pictures、comment、geoLocation、editable外加nextTimeSequenceId请求更早数据时作为下一次的max_time游标与totalCount开启with_count时返回。transactions-list-all—GET /transactions/list/all.json需要时区一次性返回全部匹配参数与transactions-list大致相同但分页参数替换为时间区间参数必填类型说明start_time否integer查询起始 Unix 时间end_time否integer查询结束 Unix 时间其余可选参数type、category_ids、account_ids、tag_filter、amount_filter、keyword、must_have_pictures、with_pictures、trim_account、trim_category、trim_tag语义与transactions-list一致。响应为交易对象数组无分页元数据适合一次性导出或全量分析。6. 新增交易transactions-add—POST /transactions/add.json需要时区参数必填类型说明type是integer交易类型1余额调整、2收入、3支出、4转账categoryId是string交易分类 ID支持二级分类time是integer交易 Unix 时间utcOffset是integer交易时区偏移分钟sourceAccountId是string来源账户 ID支持无子账户的账户或子账户sourceAmount是integer来源金额两位小数整数表示见下文金额单位destinationAccountId否string转账目标账户 IDdestinationAmount否integer转账目标金额hideAmount否boolean是否隐藏金额tagIds否string标签 ID 列表逗号分隔如tagid1,tagid2pictureIds否string凭证图片 ID 列表逗号分隔如picid1,picid2comment否string交易备注geoLocation否string地理位置格式longitude,latitude如116.33,39.93典型调用示例新增一笔支出金额 12.34sh scripts/ebktools.sh --tz-name Asia/Shanghai transactions-add \ --type 3 \ --categoryId 分类ID \ --time 1735689600 \ --utcOffset 480 \ --sourceAccountId 账户ID \ --sourceAmount 1234 \ --comment 午餐7. 汇率与版本exchangerates-latest—GET /exchange_rates/latest.json无参数。返回最新汇率快照dataSource数据源名称、referenceUrl参考来源、updateTime更新时间 Unix 时间戳、baseCurrency基准货币、exchangeRates数组每项为currency货币代码与rate汇率含义是1 单位基准货币 多少单位该货币。server-version—GET /systems/version.json无参数。返回version服务端版本号与commitHashGit 提交哈希可用于脚本自检服务连通性与版本兼容性。五、参数类型、金额单位与校验规则脚本会根据配置表中声明的ParamTypes对参数做本地校验类型不合法会直接报错退出而不是把错误请求发给服务器。共有五种参数类型类型校验规则典型参数string任意字符串name、comment、currencyinteger匹配^-?[0-9]$含负整数type、count、time、utcOffsetboolean仅接受true/false/1/0hideAmount、with_countstring_array逗号分隔字符串拆分为数组后放入请求体tagIds、pictureIdsgeo_location匹配longitude,latitude格式geoLocationPOST 时被转换为{latitude:…,longitude:…}JSON 对象金额单位是一个必须注意的约定API 中所有金额字段都以整数 隐含两位小数传输。例如1234表示12.34-500表示-5.00。这一规则同时适用于账户余额balance与交易金额sourceAmount/destinationAmount文档与脚本注释中均有明确说明。此外脚本还校验必填参数完整性配置表中RequiredParams声明的参数若未传入会提示Required parameter --xxx is missing并退出--开头参数若缺少值也会报错。六、响应输出从 JSON 到 Markdown 表格为了让人和 LLM 都能直观阅读结果脚本默认按PrettyResponse配置将响应渲染为 Markdown 表格共四种渲染策略对应 ebktools.sh 的print_result分支策略适用响应说明simple_array_to_markdown_table平铺数组直接按Columns列渲染如tokens-list、transaction-tags-listhierarchical_array_to_markdown_table含子节点的数组先按ChildKey如subAccounts把父子节点展平再渲染如accounts-listhierarchical_object_to_markdown_table按类型分组的对象先展平ChildKey如subCategories再渲染如transaction-categories-listnested_array_to_markdown_table嵌套在对象中的数组按DataPath如.items、.exchangeRates取出数组渲染并在表格上方打印Metadata元信息如Total Count、Next Time Sequence ID如transactions-list、exchangerates-latest当响应没有配置PrettyResponse如server-version、数据为空输出No data to display或指定了--raw-response时则回退为格式化 JSON 输出。七、故障排查指南脚本在使用中最常见的几类问题及解决办法1. 环境变量未设置错误信息形如Error: Environment variable EBKTOOL_SERVER_BASEURL is not set.或Error: Environment variable EBKTOOL_TOKEN is not set.。解决办法有两种在系统中设置环境变量export/$env:见上文在当前目录、父目录或用户主目录下创建.env文件并写入两个变量。脚本启动时会按当前目录 → 父目录 → 主目录的顺序查找并解析.envShell 版实现见 ebktools.sh 的load_env_from_paths支持#注释、空行、键值对以及带引号的值# ~/.env EBKTOOL_SERVER_BASEURLhttp://localhost:8080 EBKTOOL_TOKENYOUR_TOKEN2. 必要依赖缺失仅 Shell 版check_dependency会逐个检查grep sed awk date curl jq缺失时输出Error: curl is required.并返回退出码 127。安装对应工具如 Ubuntu 下apt install curl jq即可。3. 需要时区的命令缺少时区信息若探测不到系统时区且未传--tz-name/--tz-offset会提示Command transactions-list requires timezone information.按提示补传任一参数即可。4. API 调用失败curl 层失败提示API call failed (curl exit code: N)通常是服务器地址不可达或网络问题业务层失败脚本解析响应中的success字段若为false或缺失则原样打印 JSON 响应此时应重点检查 Token 是否有效/过期、请求参数是否合法。从源码看所有/api/v1路由都经过JWTAuthorizationByHeader与APITokenIpLimit两个中间件cmd/webserver.goToken 通过Authorization: Bearer token请求头传递——如果你的服务器开启了 API Token IP 限制还需保证脚本所在机器的出口 IP 在允许列表内。八、源码级原理脚本与后端的调用链理解调用链有助于排查问题与二次开发。一次完整的ebktools调用实际发生以下步骤URL 拼接${EBKTOOL_SERVER_BASEURL}/api/v1/${Path}ebktools.sh。配置表中的Path均为相对路径如transactions/add.json前缀/api/v1由脚本统一补齐参数处理GET 命令把参数 URL 编码后拼入查询字符串keyvalue...POST 命令把参数按类型转换后序列化为 JSON 请求体integer/boolean转成原生类型、string_array拆数组、geo_location转经纬度对象并设置Content-Type: application/json请求头统一携带Authorization: Bearer token需要时区的命令额外携带X-Timezone-Name或X-Timezone-Offset后端路由服务端在 cmd/webserver.go 中注册了GET /accounts/list.json、POST /accounts/add.json、GET /transactions/list.json、POST /transactions/add.json、GET /transaction/categories/list.json、GET /transaction/tags/list.json等路由分别绑定到api.Accounts.AccountListHandler、api.Transactions.TransactionListHandler、api.TransactionCategories.CategoryListHandler等处理器如 pkg/api/accounts.go 的AccountListHandler与脚本配置表中的Path一一对应结果渲染脚本读取响应的success字段判断业务成功与否成功则取result按PrettyResponse渲染成 Markdown 表格。从这些细节可以推断ebktools 本质上是 ezBookkeeping/api/v1REST 接口的一个配置驱动型客户端——只要维护好命令配置表就能稳定跟随服务端 API 演进非常适合作为自托管记账的自动化入口定时同步账单、AI 助手记账、批量导入等场景。延伸阅读核心文档 SKILL.md、Shell 实现 ebktools.sh、PowerShell 实现 ebktools.ps1、服务端路由注册 cmd/webserver.go、API Token 生成逻辑 pkg/api/tokens.go、请求鉴权中间件 pkg/middlewares/authorization.go。赞分享后端前端金融科技【免费下载链接】ezbookkeepingezBookkeeping is an open source, powerful, self-hosted personal finance app that is easy to use.项目地址https://gitcode.com/gh_mirrors/ez/ezbookkeeping点击查看免费下载相关推荐Peekaboo 的 peekaboo tools 命令实战指南查询 MCP 工具目录与按需获取输入 SchemaPeekaboo 的 peekaboo tools 命令实战指南查询 MCP 工具目录与按需获取输入 Schema peekaboo tools 是 PeekGUI 自动化MCP 服务AI 应用Hyperledger Fabric peer snapshot 命令完全指南提交、取消与查询账本快照请求Hyperledger Fabric peer snapshot 命令完全指南提交、取消与查询账本快照请求 本指南以 Hyperledger Fabric 仓区块链密码学ezBookkeeping个人记账系统完整部署指南ezBookkeeping个人记账系统完整部署指南 项目介绍 ezBookkeeping是一款轻量级、自托管的个人记账应用程序提供用户友好的界面适用于桌面和后端前端金融科技上一篇FanControl终极指南Windows平台专业风扇控制与散热优化完整教程下一篇FanControl3个方法让你的Windows电脑安静又凉爽创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考