安装并配置 WHMCS 以配合 HOSTKEY 计费系统工作¶

在这篇文章中

• 所需软件
• 模块安装
• 在 WHMCS 中激活模块
• 使用控制台命令从 HOSTKEY 加载和删除信息
• 用于价格导出的货币配置
• 自定义特定产品的转售
• 编辑特定产品
• 已订购产品的支付激活
• 示例与提示
• 典型错误及解决方案

所需软件¶

• 用于 WHMCS 的 reseller module：download;
• WHMCS 版本 8.8 或更高版本。

模块安装¶

将压缩包的内容解压到会计系统的根目录。

1. 下载并解压模块压缩包至 WHMCS 根目录

   将压缩包的内容解压到会计系统的根目录。

   WHMCS root 是存放 configuration.php 文件以及 vendor/、modules/、includes/ 文件夹的位置。

   通过 SSH：

   cd /path/to/your/whmcs
   

   unzip /path/to/HostkeyResellerMod.zip
   

   通过 FTP： 将压缩包内容上传到 WHMCS root，并同意合并文件夹。

2. 检查解压后的结构

   应出现以下目录和文件：

   • modules/addons/hostkeyresellermod/
   • modules/servers/hostkeyresellermod/
   • modules/gateways/callback/hostkeyresellermod.php
   • includes/hooks/hostkeyresellermod.php

   关键文件：

   • modules/addons/hostkeyresellermod/hostkeyresellermod.php
   • modules/addons/hostkeyresellermod/cron.php
   • modules/addons/hostkeyresellermod/clean.php
   • modules/addons/hostkeyresellermod/import.ini (可选)

3. 刷新您的管理面板会话

   退出并重新登录 WHMCS 管理面板。如有必要，请清除浏览器缓存。

复制时的常见问题¶

• 文件位于错误的文件夹中： 如果模块位于子文件夹而不是 WHMCS root 中，则不会出现在列表中。
• 权限/所有者： 错误的权限会导致无法激活/显示。
• 浏览器缓存/会话： 重新登录可以解决“模块不可见”的问题。

在 WHMCS 中激活模块¶

1. 打开 addon modules 列表

   将模块复制到 WHMCS 目录并配置好文件系统权限后，您需要激活该模块。操作步骤如下：

   • 路径： System Settings > Apps & Integrations > Addon Modules。
   • 找到 HOSTKEY VPS/Dedicated。

   

2. 激活模块并进入设置

   • 点击 Activate。
   • 然后点击 Configure (或 Settings) 以打开设置表单。

   

3. 填写模块设置并保存

   字段：

   • API Url — HOSTKEY 计费 API 地址：
   • 国际版：https://invapi.hostkey.com/ (默认)。
   • API key — 用于访问 HOSTKEY API 的密钥。请通过遵循说明获取；请务必保密。
   • Preset name prefix — 名称前缀（默认为 HKP-），用于在 WHMCS 列表中直观地区分 HOSTKEY 产品。
   • Default product group — 为创建的产品指定的 WHMCS 产品组（默认 Hostkey servers）。
   • Logging of requests to Hostkey API — 如有调试需要，请启用此项。

   点击 Save Changes。

   

4. 设置访问权限 (Access Control)

   勾选需要访问该模块的管理员组（我们建议启用 "Administrators"）。

   警告

   如果您未在 Access Control 下标记任何组，则该模块对这些组将不可用，且不会显示在 Addons 菜单中（即使是管理员也是如此）。

   如果一切操作正确（包括设置权限），HOSTKEY VPS/Dedicated 部分将出现在 Addons 菜单中。

5. 打开模块并配置产品导入

   进入 Addons > HOSTKEY VPS/Dedicated 并选择您希望转售的产品：

   • Import VPS products — 用于 VPS/VDS；
   • Import Bare metal products — 用于专用服务器 (dedicated servers)；
   • Import GPU products — 用于 GPU 服务器。

   对于每个选中的类别，设置加价比例和格式：

   • In percentage: 输入数值并保留 "%"（例如："10 %"）。
   • In fixed currency: 输入数值并选择 WHMCS 货币（例如："5 USD"）。

   在 Round price to 中选择舍入模式：

   • Not round — 不进行舍入。
   • 0.1, 0.2 等 — 保留到十分位。
   • 0.25, 0.5, 0.75 — 保留到四分之一位。
   • 0.5, 1.0 — 保留到半位。
   • 1.0 — 保留到整数。

   

   然后点击 ImportProduct/AdjustPrice 按钮。

   备注

   对于首次运行，我们建议使用另一种方法，因为在加载大量信息时，页面可能会以 504 错误码结束。进行首次批量导入时，可能需要较长的加载时间；如果出现 504 错误，请使用控制台导入。

6. 下载成功及后续操作

   如果模块连接并激活正确，将显示一条关于成功下载 HOSTKEY 产品的信息，并建议您前往 System Settings > Product/Services 菜单中的特定产品设置。

   

   进入 Product/Services：

   • 检查已创建的组和产品。
   • 如有必要，打开产品，在 Pricing 选项卡上设置价格/周期；在 Details 选项卡上，取消勾选 Hidden，以便产品显示在展示橱窗中。

   

   备注

   如果信息量巨大，页面可能会以 504 Gateway Timeout 错误码终止。对于首次加载产品列表，我们建议在计费根目录下执行命令。

使用控制台命令从 HOSTKEY 加载和删除信息¶

执行 cron.php¶

用于从 Hostkey 加载信息。请在您网站的根目录下执行该命令：

php modules/addons/hostkeyresellermod/cron.php

执行 clean.php¶

删除之前从 HOSTKEY 获取的信息。请在您网站的根目录下执行该命令：

php modules/addons/hostkeyresellermod/clean.php

重要提示：import.ini 的优先级高于管理面板设置¶

如果 modules/addons/hostkeyresellermod/ 目录下存在 import.ini 文件，则导入将基于该文件的设置进行，并会覆盖/忽略在 Addons > HOSTKEY VPS/Dedicated 页面通过管理面板指定的设置。

如果通过 Web 界面导入不稳定（卡死、504）或者您打算通过 cron/控制台运行导入，我们建议使用 import.ini。

如果您想通过管理面板配置导入，请删除或重命名 import.ini：

rm modules/addons/hostkeyresellermod/import.ini

删除/重命名文件后，导入将再次使用在管理面板中指定的值。

import.ini 中的参数¶

在运行期间，该命令会使用 modules/addons/hostkeyresellermod/import.ini 文件（如果存在）。

import.ini 中的参数：

• template = 5 — 将 5 替换为 WHMCS 中所需的邮件模板 ID（您可以在 Email Templates 部分查看）
• round = 0 — 价格舍入 (0 = 不舍入, 10 = 保留到 0.1, 4 = 保留到 0.25, 2 = 保留到 0.5, 1 = 保留到 1.0)
• vps = 10 % — VPS 加价比例
• bm = 50 USD — Bare metal 加价金额
• gpu = 100 RUB — GPU 加价金额

import.ini 示例：

[general]
round = 0
template = 5
[markup]
vps = 10 %
bm = 50 USD
gpu = 100 RUB

该文件包含两个部分：

1. general 部分包含 round 参数，用于控制舍入。该参数的可能值包括：

   • 0 — 不进行舍入；
   • 10 — 舍入到最接近的十分位；
   • 4 — 舍入到最接近的四分之一位；
   • 2 — 舍入到最接近的半位；
   • 1 — 舍入到最接近的整数。

2. markup 部分包含每个组的百分比加价比例。

   如果 import.ini 文件不存在或使用了 default 选项，则不应用任何加价或舍入。

自动预设更新 (cron)¶

我们建议设置每天一次的任务计划，在非高峰时段运行。

crontab 示例（每天 03:30；请将 whmcs 的路径替换为您自己的）：

30 3 * * * /usr/bin/php /path/to/whmcs/modules/addons/hostkeyresellermod/cron.php >/dev/null 2>&1

计划任务提示：简要了解 cron，辅助工具 — crontab.guru。

用于价格导出的货币配置¶

为了准确导出产品价格，您需要配置相对于 EUR 或 USD 以及它们之间的汇率。这可以在 Payments >> Currencies 部分完成。

自定义特定产品的转售¶

通过进入 System Settings >> Product/Services，您将看到一张所有可用于转售的产品列表。

通过点击最右侧列中的图标，您可以更改产品设置或将其从列表中移除。大多数设置由 WHMCS 设置决定，我们仅关注那些对转售至关重要的设置。

编辑特定产品¶

点击 Edit 图标将带您进入 Edit Product 参数修改部分。

Details 选项卡¶

此选项卡允许您更改将在您的 storefront 上显示的名称。

此外，通过勾选 Hidden，可以在不删除产品的情况下将其从订单表单中隐藏。

Pricing 选项卡¶

使用此选项卡在您可用的货币中设置产品价格。

您可以设置三种支付类型 (Payment Type)：

• Free - 产品免费提供；
• One Time - 一个月使用的单次付款；
• Recurring - 一定期限内的定期付款。

您需要分别为每个周期和每种货币设置价格，这让您可以灵活调整定价策略：

• One Time/Monthly - 单次付款或每月定期付款。
• Quarterly - 每季度（3个月）支付一次。
• Semi-annual - 每半年（6个月）支付一次。
• Annual - 一年（12个月）的费用。

您有两种独立的定价可用：

• Setup Fee - 安装产品的费用；
• Price - 产品的销售价格。

更改参数和价格后，点击 Save Changes 并保存该产品的设置。

确认设置成功保存后，点击右上角的 Back to product list 按钮返回产品列表。

配置完成后，产品将出现在客户控制面板中。

已订购产品的支付激活¶

要为任何已订购的产品付款，将使用您的 HOSTKEY 账户余额。请确保已启用 automatic payment from balance 模式。

示例与提示¶

• 加价与舍入示例： 价格为 123.56，加价 10% 并向 0.5 舍入 > 136.0。
• 货币： 请检查 Payments > Currencies —— 应设置好相对于 EUR/USD 以及所用货币之间的汇率。

典型错误及解决方案¶

• Invalid API key / 403: 检查 API key 的有效性、URL (是否为 .com) 以及是否存在多余空格。
• Module is not visible in Addons: 检查 Access Control 中的组设置、刷新会话、检查文件/所有者权限。
• 504 Gateway Timeout on import: 使用控制台导入，增加 max_execution_time。
• Prices seem "at a loss": 将您在 Pricing 中设置的价格设得高于采购价；检查加价和舍入设置。
• Error 503: 若要排查原因，请尝试查看服务器错误日志 error.log 或 php_error.log。