SHKeeper v2.5.32 介绍与选型指南

目标：面向需要在自有服务器上接收加密货币支付的站长与后端开发者，讲清 SHKeeper 是什么、架构如何、能做什么、与 BTCPay Server/Bitcart 及托管型网关相比如何选型。本文为认知篇，全部信息于 2026-10-24 对官方渠道（官网 shkeeper.io、GitHub 仓库 vsys-host/shkeeper.io、官方 Helm Chart、公开实例 demo.shkeeper.io）联网实查溯源，未含本地实测内容；部署与实测见本专栏《SHKeeper v2.5.32 Docker Compose 部署指南》《SHKeeper v2.5.32 API 使用详解》等篇。

一、环境信息

本篇为认知与选型篇，不依赖本地部署环境。为保证可追溯性，先列本次取证的信息源与查询日期。

• 取证查询日期：2026-10-24
• 官方网站：https://shkeeper.io/
• 代码仓库：https://github.com/vsys-host/shkeeper.io（组织 vsys-host，即乌克兰 VSYS 团队，联系邮箱 support@v-sys.org）
• 官方文档站 / API 列表：https://shkeeper.io/api/ 、知识库 https://shkeeper.io/kb/launch/what-is-shkeeper
• 官方公开演示实例：https://demo.shkeeper.io/（运行在测试网，登录 admin/admin）
• 当前最新稳定版：v2.5.32（来源：GitHub Releases 页与 shields.io release 徽章，两者一致）
• 开源许可：GPL-3.0（仓库 LICENSE）
• 社区热度快照：GitHub stars 637（来源：shields.io 星标徽章，查询日期 2026-10-24）
• 技术栈要点：Python 3.13 + Flask 2.2.2 + Gunicorn 25.1.0 + SQLAlchemy 1.4（核心），MariaDB + Redis + Celery（钱包适配器侧），区块链节点为各币种官方节点软件
• 本专栏关联文档：《SHKeeper v2.5.32 Docker Compose 部署指南》（部署实测）、《SHKeeper v2.5.32 配置参数详解》（环境变量全集）、《SHKeeper v2.5.32 API 使用详解》（接口逐条实测）

💡 说明：SHKeeper 更新节奏较快（v2.5.x 为密集小版本迭代），阅读本文时请以官方 Releases 页为准确认最新版本号；本文中「v2.5.32」为取证时点的最新稳定版。

二、软件概述

2.1 定位与身份

SHKeeper 官方定义是「自托管、开源的加密货币支付处理器（cryptocurrency payment processor）」，其独特之处在于同时扮演网关（gateway）与商户（merchant）两个角色：既提供面向买家的收银台（发票页、二维码、汇率换算），又内置链上钱包直接管理资金——收款直接进入自己控制的钱包地址，不经过第三方托管，因此无交易手续费、无中间商、无 KYC/AML 流程。

它解决的核心痛点是：普通网站想把加密货币作为一种支付方式接入（如同接入 PayPal/支付宝），但又不希望把资金和用户隐私交给托管型网关（BitPay、Coinbase Commerce、NOWPayments 等）。SHKeeper 把「钱包 + 收单 + 汇率 + 回调通知」打包成一个可私有部署的 Web 服务，对外暴露标准 REST API 与即插即用的电商模块。

• 产品形态：Web 服务（Gunicorn 托管的 Flask 应用，默认端口 5000，管理后台与收银台一体）
• 资金托管模型：非托管（Non-custodial），密钥由部署者持有
• 部署形态：官方推荐 k3s + Helm Chart 一键部署全家桶；官方发布 Docker Hub 镜像（vsyshost/shkeeper），可自行编排
• 维护方：VSYS 团队（vsys-host 组织），持续迭代中（2026-10-24 时最新版 v2.5.32）

2.2 发展沿革与版本节奏

SHKeeper 由 VSYS 团队于 2022 年前后开源并持续维护。从 GitHub Releases 可见其版本节奏：v2.5.x 系列以周级小版本快速迭代（如 v2.5.23 → v2.5.24 是一次安全加固提交「改进会话 Cookie 安全、新增 CSP、改用本地资源替代外部 CDN」；v2.5.29 修复无 task_id 的打款登记问题；v2.5.32 为取证时点最新版）。查询日期 2026-10-24，release 徽章与 Releases 页均确认 v2.5.32 为最新稳定标签。

新特性持续加入的迹象包括：2025-12-01 官方博客宣布集成 Firo（FIRO 与 FIRO-SPARK 钱包）、Tron 质押管理页、静态地址模式（面向交易所类业务复用同一收款地址）等。总体判断：项目处于活跃维护期，而非废弃或冻结状态。

2.3 开源许可与商业支持

代码以 GPL-3.0 开源（仓库 LICENSE 文件）。官方商业模式为开源核心 + 官方托管/技术支持：官网提供联系方式与技术支持入口，同时提供公共 demo 实例供免安装体验。对使用者而言，GPL-3.0 意味着对 SHKeeper 本身的修改代码在分发时需要开源；与自建业务系统集成（通过 REST API 调用）不传染 GPL。自托管使用无需任何授权费用。

三、核心架构

3.1 总体架构与组件分工

SHKeeper 采用「核心 + 每币种钱包适配器 + 区块链节点」的分层架构（以下组件与镜像名实查自官方 Helm Chart vsys-host/helm-charts 的 values.yaml 与部署模板，查询日期 2026-10-24）：

💡 说明：核心与适配器之间是纯 HTTP 调用——核心通过 BTC_API_SERVER_HOST/BTC_SERVER_PORT（默认 bitcoin-shkeeper:6000）以 Basic 认证访问适配器；适配器通过 SHKEEPER_HOST/SHKEEPER_BACKEND_KEY 回调核心。这种解耦使「加一个币种」等于「部署一组适配器 + 节点」，核心无需改动。

架构上有两个值得注意的设计：

1. 核心极轻：SHKeeper 核心不用重型数据库，SQLite 单文件即可运行管理台与 API；重活（链上监听、扫块、打款）全部下沉到各币种适配器。
2. 节点可内置可外置：Helm Chart 中每个币种既可随 Chart 部署全节点，也可通过 *_fullnode.url 指向外部节点（例如复用交易所或自建节点），BTC 族适配器通过 FULLNODE_URL 连接任意 bitcoind 兼容 RPC。

3.2 支付处理流程：发票（Invoice）模型

SHKeeper 的收单围绕「发票 = 一个链上唯一地址」展开（以下流程描述实查自仓库 README，查询日期 2026-10-24）：

1. 商户系统先拿到自己体系内的 order_id（即 external_id），再调用 POST /api/v1/{crypto}/payment_request 创建发票；SHKeeper 为该发票派生一个该币种的唯一收款地址。
2. 同一 external_id + callback_url 重复请求会更新发票而非新建；买家换币种支付时对新币种再开一张，SHKeeper 自动更新并给出新地址，旧地址收款仍会被识别并回调。
3. 买家付款后，适配器监听到链上交易，发票状态沿 UNPAID → PARTIAL → PAID → OVERPAID 推进（欠付/部分支付/全额支付/超付，阈值可在钱包设置中调整）。
4. 每笔入账交易触发 HTTP POST 回调到 callback_url，携带发票与交易明细；回调要求返回 202 Accepted，否则每 60 秒重发。
5. 新版回调带 HMAC-SHA256 签名头（X-Shkeeper-Signature/X-Shkeeper-Timestamp），以钱包 API Key 作为 HMAC 密钥验签，防伪造回调；旧的 X-Shkeeper-Api-Key 头仅为向后兼容保留。
6. 汇率可在钱包设置中配置「Recalculate invoice rate after」：超时未付则按入账时刻汇率重新折算，recalculate_after 字段返回给商户用于向买家展示锁价时限。

3.3 支持币种与网络

官方 README 声明的直收币种清单（查询日期 2026-10-24）：

• 主链币：BTC（链上 + Lightning Network 闪电网络）、ETH、LTC、DOGE、XMR、XRP、TRX、BNB、SOL、MATIC、AVAX、FIRO、ARB（Arbitrum）、OP（Optimism）、TON、DAI
• 稳定币/代币：USDT（ERC20、TRC20、BEP-20、Polygon、Avalanche、Arbitrum、Optimism、TON 八条链）、USDC（ERC20、TRC20、BEP-20、Polygon、Avalanche、Arbitrum、Optimism 七条链）、PYUSD（ERC20、Solana）

💡 技术拓展：加密货币支付网关的「地址模型」分两类——一单一地址（per-invoice address）与静态复用地址（static address）。前者每个订单独立地址，天然解决「谁付的款」归因问题，但对交易所类充值场景地址量巨大；后者每个客户固定一个充值地址，需要按客户归因。SHKeeper 原生是前者，同时官方文档给出「大额常驻发票」技巧实现静态地址模式：为每个客户/币种建一张金额刻意巨大的长期发票复用其地址，并配合「Recalculate invoice rate after」控制汇率刷新周期，兼顾静态地址与对账。本方案实际采用官方默认的 per-invoice 模型，交易所型业务再启用静态地址技巧。

法币计价方面，SHKeeper 内置 USD 与 EUR，可通过环境变量 EXTRA_CURRENCIES 增加其他法币（如 EXTRA_CURRENCIES="TRY,CAD"）。汇率源内置 Binance、Coinbase、Kraken、KuCoin 四个自动源与一个手动源（源码 shkeeper/modules/rates/），管理台可切换。

3.4 集成方式：REST API、Webhook 与成品模块

对外集成有两条路径：

1. REST API（主集成形态）：完整覆盖加密币列表、报价（quote，不生成发票的询价）、创建发票、查地址、查交易、按 external_id 查发票、钱包解密、余额（单币与全量）、打款（Payout/Multipayout，异步任务 + 任务状态轮询）、打款状态查询等；另有 Prometheus /metrics 指标端点。认证分两种：业务接口用 X-Shkeeper-Api-Key 请求头；打款类接口用 HTTP Basic（SHKeeper 登录账号）。逐接口实测见本专栏《SHKeeper v2.5.32 API 使用详解》。
2. 成品电商模块：官方维护四个插件仓库——WHMCS（实测版本 8.10.1）、WooCommerce/WordPress（WP 5.9.3 + Woo 6.3.1）、OpenCart 3（3.0.3.9）、PrestaShop 8（8.1.7），装上填 API Key 与网关地址即可收款；自研模块则按 Webhook HMAC-SHA256 验签指南实现回调端点。

四、功能特性

以下 12 项为官方 README「Features」清单的忠实转述与解读（查询日期 2026-10-24）：

1. 非托管（Non-custodial）：密钥与资金自持，平台方无法动用商户资金。
2. 多币种（Multi-currency）：一条部署覆盖 16+ 主链币与主流稳定币多链版本。
3. 无交易手续费与第三方：软件本身不抽成，链上矿工费是唯一成本；托管型网关通常抽 0.4%~1% 且有提现门槛。
4. 直接加密货币支付：买家用任意钱包扫码付款，无跳转第三方收银页。
5. 支付按钮/二维码轻松嵌入：发票页自带二维码，API 返回字段可直接渲染按钮。
6. 自定汇率、佣金与手续费：可自设汇率源与加价点数（fee_percent 会体现在回调字段中）。
7. 超付计入余额：买家多付部分记入发票余额而非拒收。
8. 部分支付（Partial payments）：多次转账累计达额自动转 PAID。
9. 自动转入冷钱包（auto-payments into a cold wallet）：收款自动归集到冷钱包地址。
10. 更高的隐私与安全：无 KYC/AML，数据不出自托管服务器。
11. 无 KYC/AML：无需提交主体资质，适合对合规路径有自主判断能力的部署者。
12. 批量打款（Multipayout）：一次 API 调用对多地址批量转账（XMR/BTC/LTC/DOGE 暂不支持，需走单笔 Payout）。

⚠️ 注意：「无 KYC/AML」是软件能力描述，不代表使用行为免于当地法律义务。加密货币收付在多数司法辖区涉及税务、反洗钱与外汇合规，部署前请自行确认所在辖区的合法性与申报义务，本系列文档不构成法律建议。

五、快速开始（最小可用示例）

本节给出「不安装也能体验」的最小示例：直接调用官方公开 demo 实例（运行于测试网）。以下调用为 2026-10-24 联网溯源所得真实回显。

第一步，获取当前在线可收款的币种列表（该接口无需认证）：

curl -s https://demo.shkeeper.io/api/v1/crypto

实测回显（节选，2026-10-24）：

{"crypto":["BNB","BNB-USDC","BTC","ETH","ETH-USDC","ETH-USDT","FIRO","FIRO-SPARK","LTC","XMR","XRP"],
 "crypto_list":[{"display_name":"BNB","name":"BNB"},{"display_name":"BEP20 USDC","name":"BNB-USDC"},
 {"display_name":"Bitcoin","name":"BTC"},{"display_name":"Ethereum","name":"ETH"},
 {"display_name":"ERC20 USDC","name":"ETH-USDC"},{"display_name":"ERC20 USDT","name":"ETH-USDT"},
 {"display_name":"Firo","name":"FIRO"},{"display_name":"Firo-Spark","name":"FIRO-SPARK"},
 {"display_name":"Litecoin","name":"LTC"},
 {"display_name":"Monero XMR","name":"XMR"},{"display_name":"XRP","name":"XRP"}],"status":"success"}

第二步，在浏览器打开 https://demo.shkeeper.io/ 用 admin/admin 登录，进入 Wallets 页可看到各币种钱包同步状态；在 Wallets → Manage → API key 可生成 demo 实例的 API Key。携带有效 Key 即可创建发票（README 官方示例形态）：

curl --location --request POST 'https://demo.shkeeper.io/api/v1/ETH/payment_request' \
--header 'X-Shkeeper-API-Key: <demo实例的APIKey>' \
--header 'Content-Type: application/json' \
--data-raw '{"external_id":107,"fiat":"USD","amount":"18.25","callback_url":"https://my-billing/callback.php"}'

成功时返回 JSON，含 wallet（本次收款地址）、amount（折算后的加密币数量）、exchange_rate（汇率）、id（SHKeeper 发票 ID）、recalculate_after（锁价秒数）等字段。若币种网关不可用则返回 {"message":"BTC payment gateway is unavailable","status":"error"}。

💡 说明：demo 实例仅用于体感流程。真实选型评估请部署自有实例（推荐直接按本专栏《SHKeeper v2.5.32 Docker Compose 部署指南》以 BTC regtest 模式完成零成本全流程验证，再决定是否上主网节点），商户集成细节见《SHKeeper v2.5.32 API 使用详解》。

六、适用场景与限制

6.1 典型适用场景

1. 电商/数字内容站收加密币：WordPress/WooCommerce、OpenCart、PrestaShop、WHMCS 主机账单系统，装官方插件直接收款。
2. SaaS 订阅与账单系统：自有账单体系通过 REST API 开票 + 回调对账，适合订阅扣费、API 计费等场景。
3. 交易所/托管业务的充值地址体系：利用静态地址模式为每个用户维护固定充值地址，Multipayout 批量提现。
4. 跨境电商出海收款：避开传统收单渠道的手续费与拒付风险，直接接收稳定币（USDT/USDC 多链）。
5. 社区捐赠与内容变现：轻量部署，二维码 + 支付按钮即可收款。

6.2 已知限制与风险

• 节点资源是主要成本：每个启用的币种都需要全节点（BTC 主网全节点数据量数百 GB 级）；币种开得越多，磁盘与内存开销越大。测试/验证阶段强烈建议用 regtest/测试网（官方 Chart 与镜像原生支持 -regtest）。
• 打款能力依赖币种适配成熟度：Multipayout 暂不支持 XMR/BTC/LTC/DOGE；XRP 打款要求 X-address 格式等特例，见 README Payout 章节。
• 社区规模中等：637 stars（2026-10-24 取证），远小于 BTCPay Server 量级，遇到深层问题时可参考的社区沉淀有限，主要依赖官方仓库 Issues 与官网支持渠道。
• 安全自担：自托管意味着钱包安全、服务器加固、备份恢复全部由部署者负责；管理台务必改强密码并启用内置 TOTP 双因素（v2.5.x 已内置 2FA），回调必须验 HMAC 签名。
• 合规自评：无 KYC/AML 是软件特性而非法律豁免，商用前需自查辖区合规（见四、末尾注意）。

七、同类选型对比

7.1 候选概览

加密货币收款方案可分为三类：自托管网关（SHKeeper、BTCPay Server、Bitcart）、托管型网关（BitPay、Coinbase Commerce、NOWPayments 等）、自研对账（直接对接链上节点自建）。本节聚焦自托管三类横向对比，托管型仅作参照。

• SHKeeper：多币种一体（16+ 币种官方支持），Flask 单核心 + 适配器架构，自带管理台与收银台，k3s/Helm 与 Docker 镜像双形态，四款电商插件。
• BTCPay Server：C#/.NET 生态最成熟的自托管方案，以 BTC（链上 + 闪电网络）为核心体验，其他币种通过社区插件/扩展（如 Monero、LTC 等）方式补齐；stars 7.8k（shields.io，2026-10-24 取证）。
• Bitcart：Python 生态的自托管多币种收款方案，定位与 SHKeeper 相近，采用「守护进程 + 管理 API」拆分架构，社区规模较小（本轮星数取证未获快照，读者可自行查验）。

7.2 量化对比表

关键差异解读：SHKeeper 与 BTCPay 的本质差别在「多币种开箱度」——BTCPay 的闪电网络与插件生态更深，但山寨币要一个个折腾插件；SHKeeper 一套 Chart 把 16+ 币种适配器与节点模板都写好了，多币种一体化的工程完成度是其最大卖点。与托管型相比，SHKeeper 换来的是资金自主与零抽成，付出的是节点运维与安全自担。

7.3 选型建议（如果……则……）

• 如果只收 BTC 且希望闪电网络体验最完善、社区资料最多 → BTCPay Server。
• 如果要多币种（尤其 USDT 多链、XMR、TON 等新链）开箱即用、且接受中等规模社区 → SHKeeper。
• 如果团队是 Python 技术栈、想基于代码深度二开收款逻辑 → Bitcart（Python 原生，二开门槛低）或 SHKeeper（同样 Python，适配器架构清晰）。
• 如果不想运维任何节点、金额小、接受平台抽成与 KYC → 托管型网关。
• 如果只是想先验证流程再决定 → 用 SHKeeper 的 BTC regtest 模式零成本跑通全流程（见本专栏部署篇），再评估是否迁主网。

八、参考链接

• 官方网站：https://shkeeper.io/
• GitHub 仓库：https://github.com/vsys-host/shkeeper.io
• 官方 Helm Chart：https://github.com/vsys-host/helm-charts
• API 端点总览：https://shkeeper.io/api/
• 知识库：https://shkeeper.io/kb/launch/what-is-shkeeper
• 公开 Demo：https://demo.shkeeper.io/
• Webhook 验签指南：https://github.com/vsys-host/shkeeper-docs/blob/main/docs/getting-started/webhook_verification.md
• WHMCS 模块：https://github.com/vsys-host/whmcs-shkeeper-gateway-module
• WooCommerce 插件：https://github.com/vsys-host/wp-shkeeper-plugin
• OpenCart 3 模块：https://github.com/vsys-host/opencart-3-shkeeper-payment-module
• PrestaShop 8 模块：https://github.com/vsys-host/prestashop-8-shkeeper-payment-module
• 官方教程视频：https://www.youtube.com/watch?v=yYK_JAm1_hg