文档

• Ubuntu 22.04+ 或 Debian 12+；Mint 21+ 和 Pop!_OS 22+。
• Fedora 42+；Rocky、AlmaLinux、RHEL、Oracle Linux 或 CentOS Stream 9–10。
• openSUSE Leap 16+ 或 Tumbleweed；Arch、Manjaro 或 EndeavourOS。

请选择厂商仍在维护的版本。操作系统本身要求更高时，应以其要求为准： openSUSE Leap 16 需要超过 40 GB 的磁盘空间。

更多区块链和并发账单可能需要更多 CPU 和内存。升级 VPS 不会消除 RPC 配额限制。安装流程已有自动化测试，但尚未在每个发行版上完成全新 VPS 的完整测试。

查看安装程序。添加 --check 到命令中，可仅检查兼容性而不安装；或者添加 --help 查看选项。

继续已保存的安装进度，不替换密钥或设置：

bash <(curl -fsSL https://releases.whollycrypto.com/setup_wholly.sh) --resume

其他基础域名可以使用相同的服务名称。任何 IPv6 记录也必须指向此 VPS。只有完成以下操作后才能开启 Cloudflare 代理： 域名验证.

新生成的已识别稳定币报价会向上取整： 1.321 USDC → 1.33 USDC，即使容差为零也是如此。最低金额：0.01 个代币。

现有账单、余额和部分付款的剩余金额保持精确。其他代币和自定义代币使用正常精度。

你的 Basic Auth 登录信息保存在 /root/whollycrypto/config/setup-credentials.txt。它与控制台的邮箱和密码不同。

新项目会继承 系统默认币种和时区；商店使用项目的币种。现有账户的时区在“设置 → 账户”中单独管理。

whollycrypto welcome 会显示你的控制台网址。

1. 共享节点、汇率、域名、安装额度和更新都位于 运营商面板.
2. 打开 钱包 → 创建收款钱包 ，用于 BTC、ETH 和以太坊上的 USDC/USDT。请备份两组独立的助记词。这个专用项目无法开具销售账单；已有的收款商店会保留。
3. 添加商户时指定额度币种、费率和管理员邮箱。请私下分享邀请链接和商户 Basic Auth 信息。商户自行设置密码。绝不要分享运营商的 Basic Auth 信息。
4. 商户通过你的结账页面充值，也可以由你记录有说明的额度调整。创建项目或商店前必须有额度。用户和额度历史在以下位置管理： 商户 → 管理.

运营商设置需要第四个地址，例如 operator.example.com，以及独立的 Basic Auth 用户名和密码。选择标签，将 DNS 指向 VPS，检查 DNS 并启用 HTTPS。面板会直接在该地址打开。商户、结账和 API 地址仍各自独立。

使用新的运营商 Basic Auth 登录信息，然后输入管理员邮箱和密码。商户 Basic Auth 保持不变。DNS 或证书出错后可继续设置。从 7.0.0 升级的运营商也需完成此步骤；现有线上地址仍可使用。

费率为 3% 时，一张 100 EUR 的账单会消耗 3 EUR 的商户额度。如果额度币种不同，创建时的法币汇率会随费用一同保存。

运营商另行支付正常的 Wholly Crypto 安装处理费。客户资金不会在链上拆分。购买额度不会被再次收费。

只有自动验证的结算才会增加充值额度。打开结账页面或手动接受账单都不会增加额度。冲正会生成账本记录；已冲正的充值若重新到账，需要运营商审核。

托管商户额度不足会暂停 IPN、Webhook、资金归集以及新项目和商店的创建。现有客户账单与收款仍会继续。安装额度不足可能暂停所有托管业务的自动化。禁用商户还会阻止其登录和创建新账单，但旧付款仍会持续监控。

这是应用级隔离，并非为每个商户提供独立 VPS。 商户无法访问彼此的项目、钱包、API 凭据、交易所或额度。服务器管理员可以访问托管热钱包的密钥。入驻前请向商户说明这一点；使用可信的托管服务、独立备份，并为共享负载提供足够容量。

从 7.2.0 起， 钱包 管理收款余额、地址和备份； 资金归集 处理发送和自动规则。请保留 ETH 以支付代币手续费。 商户充值 跟踪商户的购买记录。顶部显示的额度用于单独支付安装费用。 我的业务 会在新标签页中打开你自己的控制台。

打开 财务 查看赚取的费用、已验证的安装费用、估算利润和当前商户额度。可按日期、商户或报表币种筛选，并导出 CSV。

报表按首次结算时间对账单分组，并反映最新的费用冲正。预付余额不属于收入。自营业务的费用单独列出。费用待处理或缺少汇率时，相关利润无法显示。换算金额采用当前缓存的法币汇率，不包含 Gas 和运营成本。

添加商户 会创建邀请。从 7.3.0 起，可以商户额度币种指定免费初始额度，允许为零。这不会补充你的运营商余额。 通过邮件发送邀请 默认勾选。

先在以下位置配置 SMTP 服务商： 设置 → 邀请邮件 ，使用 TLS 或 STARTTLS。连接测试不会发送邮件。也可以取消勾选邮件，并私下分享链接。邮件发送失败时，账户和额度会保留；请勿重新创建商户。

需要新链接或重置密码时，请打开 商户 → 管理 → 用户账户。SMTP 接受邮件不保证收件箱送达。请单独分享商户 Basic Auth 信息，绝不要分享运营商凭据。

邀请有效期为 48 小时；密码重置链接为 1 小时。每个链接仅可使用一次。可在同一页面替换或撤销链接。重置密码会退出已有会话，但保留双重验证。仍需使用商户 Basic Auth。

直接设置密码创建账户，或发送邀请。管理用户、项目、商店、费用和本地预付额度；读取报表并订阅带签名的生命周期事件。首次登录的托管同意、双重验证和租户隔离保持不变。

每次写入都需要已保存的幂等键。赠送额度属于本地账户调整，并非安装额度充值。此 API 不提供钱包机密、发送资金或服务器配置功能。

使用 api.your-domain.com/v1/operator。将运营商密钥保留在后端，绝不要放到浏览器中或交给托管商户。

设置 → 地址簿：保存区块链和地址。原生币和匹配的 CoinGecko 代币会自动显示。这是由管理员管理的只读功能，不会改变结账接受的币种。

代币余额读取支持 22 条链。隐私余额以及 Bitcoin/CashTokens/Kaspa 附加数据需要单独的访问权限或索引服务。读取失败会显示错误，不会显示为零。

通过以下方式将账单余额归集到另一个钱包： 手动发送或自动归集。代币转账也需要该链的原生币来支付手续费。

价格不可用 指汇率不可用，并非余额问题。

1. 商店 → 支付方式 → EVM 或 Solana → 自定义代币.
2. 输入合约或 mint 地址、名称和代码。选择固定美元价格或自动 DEX 定价。

系统会检查网络和小数位。项目级价格不会改变现有报价。仅匹配到目录不会自动在结账中启用该代币。

自动定价

DEX Screener 要求合约完全匹配的交易池、10,000 美元流动性，以及过去一小时内发生过交易。汇率每分钟刷新；获取失败或已过五分钟的汇率会阻止生成新报价。

DEX 价格可能被操纵；这些检查不等于审计。请使用可信的标准 ERC-20 或经典 SPL 代币。不支持 Token-2022 及其扩展。没有合适交易池时，请使用固定定价。

扫描器离线？ 等待检测时，账单仍保留已配置的支付方式。在“区块链连接”中检查支持的 API；节点健康不代表兼容扫描器。默认使用两个独立服务商。

钱包和汇率仍是必要条件。Monero/Lightning 服务必须能够生成支付请求。

API/MCP 错误包括 error.details.payment_methods。SDK 2.4.0 增加了安全说明：PHP getPaymentMethodIssues()、Python payment_method_issues、Node paymentMethodIssues. 错误参考 →

加密货币报价会向上取整，并包含商店的加价比例。以法币定价的账单不会将收到的加密货币兑换为银行余额。

零确认会在检测到付款时结算，不受网络确认保护。EVM 原生币付款以直接转账的形式检测。异常或不确定的付款请在以下位置查看： 需要关注.

默认禁止。启用 商店 → 账单 → 允许零金额账单 即可允许手动或 API 创建总额为零的账单。这些账单会立即完成，不产生付款、收款地址、交易或处理费。

status 是事件创建时的账单状态； event_type 表示发生了什么。

• Ethereum 示例： payment.received + processing，然后 invoice.settled + settled.
• Solana 示例： 检测时已经最终确认，因此 payment.received 和 invoice.settled 两者都携带 settled.

其他链也可能出现上述任一种流程。这些是不同事件，不一定代表两笔付款。它们可能共享 sequence 但具有不同的 event_id 值。发送顺序不保证；请勿要求 processing 先发生。

事件： invoice.created, payment.received, invoice.processing, invoice.settled, invoice.expired, invoice.invalid, invoice.cancelled. 完整事件表与异常规则 →

amount_status: none, partial, paid, overpaid. paid 包含容差，不包含最终确认。 timing_status: on_time 或 late. resolution: automatic, manually_settled 或 manually_invalidated。在以下条件下应用你的异常处理策略： requires_review 为 true。

invoice_id 与 API 响应一致。 amount, currency 和 order_id 描述原始订单。 payment_info 补充转账、精确的加密货币金额、锁定的报价/加价/容差以及参考汇率。客户数据和元数据属于私密信息。

paid_chain, paid_asset, paid_payment_method_id, paid_asset_amount, paid_asset_amount_received 和 settlement_exchange_rate 汇总结算情况。这些值保持冻结；缺失的证据或历史记录保留为 null。后续到账请使用 payment_info 或 付款 API.

使用十进制字符串。绝不要合并不同资产，或将未确认资金视为缺失。明确处理异常；仅有警告绝不代表可以履行订单或退款。经过验证的内部 Gas 补充不属于客户付款，也不会触发 payment.received.

独立的签名密钥： 商店 → IPN 用于签署 IPN 发送，包括账单的自定义 ipn_url。以下位置的每个端点： 商店 → Webhook 都有各自的密钥，在创建或轮换时显示。

两者均使用 Wholly-Signature 和相同的 SDK 验证器，但需要匹配的签名密钥，而非 API 密钥。轮换 IPN 密钥不会更改 Webhook 密钥。

验证原始请求体、时间戳及项目/商店范围。先持久化保存，再返回 HTTP 2xx。后台任务通过你配置的 API 主机检查当前账单，并在数据库事务中仅履行一次订单。请求头没有签名；使用第 2 版请求体中带签名的身份信息。

基于事件： 按带签名的以下字段去重： event_id，再筛选 invoice.settled. SDK 基于状态： 合并项目 + invoice_id + sequence，然后无论事件类型如何都检查状态。合并后不要再添加事件筛选。两种方式都需要独立的订单级防重复保护。

重试保留原始请求体和事件 ID。旧修订版本不得覆盖新版本。IPN 最多尝试八次；Webhook 重试可选。额度不足会暂停发送通知，不会暂停付款。

商店 → IPN / Webhook → 历史 → 详情 显示保存的请求体和结果。载荷在 90 天后过期。重新发送不代表结算已完成。

1. 设置 → 交易所： 连接专用密钥、检查余额并授权项目。不要授予提现权限；将密钥限制为仅允许你的 VPS IP。
2. 项目 → 归集： 核对资产、网络、地址和代币合约。为每个链/代币选择另一个钱包或一家交易所。

市场数据每两分钟刷新。只有匹配且已记账的充值可以兑换；市场数据过时会阻止新订单。交易所会保留来源金额的 1% 用于费用和舍入，与处理额度无关。

最低保留金额 会在自动归集后为整个项目保留币或代币。此设置与触发条件独立；设为零则不保留。手续费从超出部分支付。手动发送不受影响。

继续状态不确定的转账，绝不要用新转账替代。钱包会一直被预留，直到确认到账或未使用报价到期。大规模归集需要分批进行。

适用交易所的托管、KYC、地区限制和费用。不提供银行出款或杠杆。额度不足会暂停新兑换；已提交的订单仍会继续核对。

打开 自动充值 位于“请求”之后。选择已备份的收款钱包、触发阈值、购买金额、每日限额和网络手续费上限。授权并保存。默认关闭。

在可用时使用 BTC、ETH 或以太坊上的 USDC/USDT。代币发送地址需要 ETH；此规则不会补充缺失的 Gas。运营商使用专用收款钱包；托管商户向其运营商付款。

即使额度不足暂停了归集，已批准的充值仍可执行。只有收款服务能确认额度。一次只运行一笔自动购买。禁用会停止尚未发送的任务，不会撤回已提交的交易。

在“自动充值”中使用 检查付款。继续同一笔有效付款，或关闭已验证失败的以太坊转账并暂停规则。待处理或状态不确定的付款会继续保留，避免重复发送。报价过期并不能证明付款失败。

默认 1% 费用按已结算账单的原始法币金额计算。客户的加密货币付款不会被拆分。

费用会继续累计，使余额变为负数。请补足负数部分，并使可用额度高于账户的宽限阈值。连接正常时，余额变化通常在 10–15 秒内显示。

安装更新需要已验证的正额度，即使自动化享有宽限也一样。充值绝不会自动安装更新。

暂停的通知不消耗尝试次数。保留的通知会恢复发送，但仍适用正常过期规则。请通过账单 API 核对遗漏事件。

如果运营商关闭处理费，将不再产生新的处理费或额度限制。以前的费用仍保留在历史记录中。未配对的安装可以配置项目和商店，但开具账单需要经过验证的计费连接。已开具的账单仍会继续监控。

• 收入按结算日期显示已结算账单的金额，未扣除费用和退款。它不是钱包余额或利润。
• 换算使用当前缓存汇率，而非历史记账汇率。缺少汇率时仍可查看原币种合计。
• 账单状态图表使用账单创建日期。“需要关注”的数字反映当前尚未解决的问题。

除 BTC、EVM、SOL 和 TRX 外，还支持 18 种原生适配器。请使用支持提交交易的服务商。ZEC 仅支持透明地址；ADA 保留代币输出；DOT 使用 Asset Hub；HBAR 需要中继。需要 memo/tag/comment 的出款目的地必须使用外部钱包。

1. 打开 项目 → 钱包 → 资产 → 发送。选择地址簿条目或输入目的地址。检查完整地址和网络。
2. 选择精确金额或归集全部可用资金，再选择费用级别。对于支持的代币， 使用项目 ETH 支付 Gas （或该链的原生币）可从同一项目、同一链中补足手续费。
3. 点击 准备转账。检查来源、目的地、金额、最高手续费和 Gas 分配。 批准并发送 才会授权此计划；仅准备不会发送任何资金。

批准后，Gas 补充、确认和代币发送会在后台继续。请查看 转账活动，即使窗口已关闭也可查看。广播不等于确认。

在项目钱包中保留 ETH： 0 表示不增加预留金额，并非花掉所有 ETH。0.005 表示至少保留 0.005 ETH 供以后使用，因此本次流程还需要额外资金。已保存的自动规则保持不变。

1. 打开 自动归集设置 → 资产 → 设置。选择钱包地址或支持的 交易所目的地，两者不能同时选择。
2. 设置最低归集金额和 最低保留金额。例如：达到 100 USDC 时触发，保留 20 USDC，最多发送 80 USDC。预留金额按整个项目计算，而非每个地址。
3. 对于代币，请检查 使用项目 ETH 支付 Gas 并输入 每日补充限额。开启自动归集，然后 保存规则 并确认。仅打开设置不会启用任何功能。

每日限额限制每条代币规则在滚动 24 小时内分配的原生 Gas 金额。€1 可作为轻度使用的初始上限，并非保证费用或每日收费。补充 Gas 的交易本身也有手续费。 最高网络手续费百分比 可限制补充和转账的合计手续费。

检查会自动运行。只有符合条件、持有代币的地址才会收到 Gas；空地址不会。资金不足且低于归集最低金额的地址会等待。 Gas 限额说明 →

• 备份钱包并测试小额转账。先发送代币，再转空原生币。同一项目中其他地址的 ETH 必须先到达每个代币地址；未使用的 Gas 会留在你的钱包中。
• 使用最新余额、健康的服务商和充足的原生币。自动规则需要一个已启用、已备份的钱包，以及在已启用商店中启用的资产。若以下项目不足： 处理额度 可能暂停发送。
• 在 转账活动中查看进度、Gas 补充和浏览器链接。结果不确定时，请刷新同一笔转账，不要新建替代转账。只有审查原因和限额后才能继续。

发送被禁用？检查 whollycrypto transfers status。执行以下操作前检查每条已启用规则： whollycrypto transfers enable：此操作作用于整个服务器，可能立即运行已保存规则。停止后续步骤无法撤销已广播的交易。

商店 → 基本设置： 选择启用的商户/支付/API 主机。链接按商店 → 默认商店 → 系统的顺序选择；停用名称会回退。SDK 主机需单独配置。带签名的重试会保留原始链接。

• 使用 Full (strict)，不要使用 Flexible；无需 API 密钥。
• 为控制台、结账和 API 禁用缓存及浏览器/机器人验证。
• 允许 /.well-known/acme-challenge/ 通过 80 端口访问，且不进行重定向或验证，以便续期。

检查会查询权威 DNS 并验证源站：直连或 Cloudflare。访问者可能仍缓存旧 DNS。

从 5.6.2 起，控制台保存/删除使用 POST；无需添加“Not GET or POST”例外。登录和 CSRF 保护保持启用。在 api.*，允许公共 API 文档中列出的方法。

更换恢复码或关闭双重验证需要密码，以及身份验证器或未使用的恢复码。其他会话将退出。请保持手机和服务器时钟同步；双重验证无法保护已被入侵的服务器。

主题图标依次切换 浅色 → 柔暗 → 深色 并记住此浏览器的选择。商店结账主题单独设置。

可选择添加 Cloudflare 访问规则。豁免 HTTPS 续期验证；避免在 API 和结账页面使用交互式登录验证。仅开启代理模式并不等于限制 IP。

无法访问？运行 whollycrypto access-reset --domain merchant.example.com ，通过 SSH 执行。仅该主机名会在五秒内重新开放，账户身份验证仍保持启用。

运行 whollycrypto ssl --domain merchant.example.com --reissue 可强制替换证书。适用签发频率限制。如果 Cloudflare 阻止 HTTP 验证，请暂时使用仅 DNS 模式。钱包、身份验证和域名保持不变。

旧更新器无法继续？运行此命令一次。已安装的密钥会验证辅助程序。

bash <(curl -fsSL https://releases.whollycrypto.com/update_wholly.sh)

安装和更新会自动尝试 官方 GitHub 镜像。仍需通过签名、校验和与额度检查。

检查为只读；需要关注时会以非零状态退出。 --fix 仅修复受管理的权限和缺失的 CLI 链接。绝不会改变计费、删除数据或重启服务。

whollycrypto reset
# Preview without changing anything:
whollycrypto reset --scope business --check
whollycrypto reset --scope project --project YOUR_PROJECT_IDENTIFIER --check

选择单个项目、所有业务项目或仅修复。项目重置会永久删除选定项目、商店、钱包记录和付款历史。仅修复只会检查并修复受管理的权限及 CLI 链接。

先禁用选定项目，处理未完成的付款/转账，并转出已知的钱包余额。账户、域名、节点、额度、计费身份和安装模式会保留。运营商收款钱包和托管额度记录受保护。此操作不会重新打开设置向导。

破坏性重置需要输入确认文字，并在删除前创建经过验证的恢复备份。还应保留服务器外的钱包备份：旧地址仍可能收到资金，但已删除项目不再跟踪这些资金。缓存余额不能证明钱包已清空。

whollycrypto uninstall --check
whollycrypto uninstall

在备份并输入确认文字后，停止结账、API 和后台任务，移除运行文件及受管理的服务器集成。待处理付款或转账会阻止移除。文件会移入恢复备份，而非彻底擦除。

数据库、配置、密钥和备份会保留。共享的 Nginx/PostgreSQL 软件包及 TLS 证书不受影响。命令会输出离线恢复命令；不要在保留数据上重新运行全新安装。

重置和移除命令适用于原生 VPS 安装，不适用于 Docker 或 Umbrel。容器请使用相应集成的备份与停止命令，并保留卷。两个破坏性命令都不接受 --yes.

whollycrypto htaccess

选择用户，设置用户名和密码并确认。此操作重置浏览器中的第一层登录提示，不是控制台账户。其他用户和 API 凭据保持不变。

whollycrypto admin-reset

按邮箱选择管理员并确认新密码。会清除会话和账户登录锁定，IP 限制仍保留。

普通重置会保留双重验证。如果身份验证器和恢复码都丢失，请明确运行 whollycrypto admin-reset --email admin@example.com --reset-2fa。登录后重新设置双重验证。

需要数据库，不需要应用运行或旧密码。其他账户、钱包和权限保持不变；已禁用账户仍保持禁用。

身份验证器和恢复码都丢失了？以 root 身份选择账户。

whollycrypto 2fa-reset
# Or select the account directly:
whollycrypto 2fa-reset --email user@example.com

移除会话、身份验证器和恢复码。使用现有密码登录，并重新配置双重验证。权限、钱包和 Basic Auth 保持不变；已禁用账户仍保持禁用。

需要数据库，不需要应用运行或额度。非交互模式： --email 和 --yes.

按 Enter 会生成密码并保存到 /root/whollycrypto/config/credential-resets/：私密、未加密，成功后可使用。手动输入的密码不会保存。

whollycrypto htaccess --user admin --new-user operator
whollycrypto admin-reset --email admin@example.com

没有终端时，指定现有账户并添加 --generate 或 --password-file /root/private-password.txt，以及 --yes。密码文件必须归 root 所有，权限模式为 600。绝不要在命令或环境变量中放置密码。

--yes 仅跳过确认。请先完成中断更新的恢复；并发账户更改会停止重置。