顶联 DCIM 对接 WHMCS

适用对象：用 WHMCS 销售服务器、用顶联 DCIM 管理机房的运营方管理员。
适用模块：WHMCS 服务器模组 Toplink DCIM。支持 WHMCS 7.x / 8.x / 9.x。

一、开始之前

对接完成后可以做这些事：

客户下单付款后自动从 DCIM 分配机器、装系统、回填主机名与 IP

机器已在 DCIM 备好时，管理员填一个服务器 ID 就能绑到订单上

客户在会员中心自助开关机、重装、开 VNC、看硬件和端口流量，权限逐项可控

逾期自动关机断网，续费自动恢复，终止自动解绑并释放 IP

带宽、附加 IP、硬件配置可以做成下单时的可配置选项，直接参与计价

动手前先确认六件事：

确认项	怎么看
DCIM 已建好用户分组	后台「用户管理 → 用户分组」不为空
DCIM 已建套餐，要卖的机器已绑套餐	服务器详情的分配信息里能看到套餐
DCIM 有数据中心、有可用镜像	自动开通和装系统要用
知道 WHMCS 站点的 PHP 版本	插件按 PHP 版本分包
站点已装 ionCube Loader	模块加载需要
WHMCS 服务器能访问 DCIM 地址	域名解析、防火墙、证书都通

整体顺序：

DCIM 建分组、建套餐、机器绑套餐、取 API 密钥
  → WHMCS 装插件、添加服务器、测试连接、建服务器分组
  → WHMCS 新增产品、模块设置、同步系统模板
  → 下测试单验收

二、DCIM 侧准备

2.1 建用户分组

WHMCS 卖出一台机器时，系统会在 DCIM 里为这位客户建一个对应账号，再把机器绑给它。建账号用的是 DCIM 的默认用户分组，所以 DCIM 上必须先有可用的分组。

顺序反了的话，账号建不出来，绑定或开通会停在这一步，界面上通常只提示「内部服务器错误」，不会指向分组，容易多花时间排查。所以放在第一位。

操作：DCIM 后台 → 用户管理 → 用户分组，确认有可用分组；没有就新建一个并设为默认。
确认方法：在 DCIM 里手工建一个测试用户，能建成功就说明这一环通了。

2.2 建套餐并把机器绑上去

自动开通靠套餐匹配机器，所以套餐要先建、机器要先绑。

建套餐：DCIM → 用户管理 → 套餐管理 → 添加。只有「名称」必填，CPU、内存、硬盘、IP 数量、上下行端口等按实际售卖规格填，用于套餐的详细描述。

绑定机器，两种做法：

逐台绑：设备管理 → 服务器管理 → 服务器详情 → 分配信息 → 套餐 → 点编辑分配。

批量绑：设备管理 → 服务器管理 → 勾选多台 → 底部「分配套餐」。

上线前清点一次：计划自动开通的机器是不是都绑好了套餐、状态正常、没被占用。这一步漏了，表现就是「下单后一直开不出机器」。

2.3 取 API 密钥

路径：DCIM → 设置 → 系统API → 添加。

标签：建议填 WHMCS 或前台站点名，方便日后识别

IP地址：填 WHMCS 所在服务器的出口 IP，DCIM 只允许该 IP 调用这套密钥

提交后生成 KEY 与 secret，请当场保存。

KEY 填到 WHMCS 服务器配置的「用户名」，secret 填「密码」。

如果站点走 CDN 或有多个出口，实际出口 IP 可能和你以为的不一样，测试连接失败时优先核这一项。

三、WHMCS 侧配置

3.1 安装插件

插件包按 PHP 版本分成 php74、php81、php82 三份。先确认站点实际运行的 PHP 版本，选对应的包，把里面的 modules/servers/toplink_dcim/ 整个目录放到 WHMCS 根目录的 modules/servers/ 下。

最终路径：

<WHMCS 根目录>/modules/servers/toplink_dcim/

两点注意：

模组需要站点安装 ionCube Loader，且版本与 PHP 匹配。缺 Loader 或装错版本的包，页面会提示需要安装 Loader

不要解压成 toplink_dcim/toplink_dcim/... 的嵌套结构

3.2 添加服务器

路径：系统设置 → 产品/服务 → 服务器设置 → 添加新的服务器。

基本信息：

字段	填法
名称	自定义，如 `Toplink-DCIM`
主机名	DCIM 的域名或 IP
IP 地址	DCIM 的域名或 IP

模块与凭据：

字段	填法
模块	选 `Toplink DCIM`。选不到说明插件目录或 PHP 版本不对
用户名	DCIM 的 KEY
密码	DCIM 的 secret
安全	DCIM 走 https 就勾「使用 SSL 连接模式」
端口	勾了 SSL 默认 443。DCIM 用其他端口时勾「用自定义端口覆盖」并填实际端口
访问散列值自定义设置区域	模组自己渲染的一组设置，见 3.4

选中模块为 Toplink DCIM 后，WHMCS 原本的「访问散列值」输入框会被替换成一组表单控件，填完自动保存，这一块不需要手工改原始文本。

3.3 测试连接

填完点「测试连接」，显示「连接成功」即表示密钥与网络正常。

连接成功代表密钥正确、网络可达，不代表用户分组、套餐、数据中心都已就绪，这些要等第一笔测试单才验证得出来。

3.4 自定义设置区域

设置项	说明	建议
用户名前缀	DCIM 账号前缀，账号 = 前缀 + WHMCS 用户 ID。页面会实时预览生成结果	一套 DCIM 接多个 WHMCS 时必须填并区分开，否则不同站点的同号用户会撞车
默认 WHMCS 主机名格式	客户填的主机名不合法时，按此格式重新生成。占位符 `{label}` 服务器标签、`{ipv4}` 主 IP、`{random_4char}` 4 位随机字符，点占位符可直接插入	常用 `{label}-{ipv4}`
强制使用生成的主机名	勾选后一律不用客户填的主机名	客户有自己命名规范时不要勾，见 4.3
不校验自动生成的主机名格式	勾选后跳过生成结果的格式校验	一般不勾
不校验 SSL 证书	自签或内网证书时用	仅测试环境
日志记录明文密码	在日志中记录明文密码	生产环境保持关闭
关闭日志存储	不在 WHMCS 活动日志中记录本模块的操作	按需
下架时移除所有内网	终止时一并移除内网	按机房网络策略
不同步用户数据	新建的 DCIM 账号不带客户姓名与邮箱	有隐私要求时勾
代理商模式	走代理商 API，勾选后需填 API 访问路径	按对接方式
强制使用英文版	界面固定英文	按客户语言

页面底部还有一个 「查找异常未绑定服务器」 按钮，列出 WHMCS 侧没有绑定关系、但在 DCIM 里仍被绑定的机器，用于定期对账，见 4.4。

3.5 建服务器分组

路径：服务器设置 → 创建新的分组。

填个名称（如 Toplink-dcim），填充类型按需要选，然后把 3.2 建的服务器「添加 »」到右边，保存。

产品里选的是服务器组，所以这一步必须做，而且服务器要真的被加进组。

四、产品配置

4.1 新增产品

路径：系统设置 → 产品/服务 → 产品/服务 → 新增产品。

字段	填法
产品类型	独服/VPS
产品组	选已建好的产品组
产品名称	服务器型号一类，可自定义
模块	Toplink DCIM
创建为隐藏	OFF

4.2 模块设置

进产品 → 模块设置，右上角先选 服务器组，保存一次，页面会刷出全部配置项。

上图是较早版本的布局，当前版本按分区呈现，条目一致。

必配的三项

配置项	说明
连接节点	选 3.2 建的那台服务器。必须先选它并保存，下面的数据中心、套餐才会加载出来
数据中心	自动开通时从哪个机房出机器
配置套餐	自动开通时要匹配的套餐。选「不选择套餐」等于关闭自动开通

用户端控制

开关	打开后客户可以	建议
控制服务器电源	开关机、重启	一般打开
自助重装系统	自选镜像重装	一般打开
显示硬件信息	查看硬件明细	按需
VNC 控制	使用 VNC / IPMI	一般打开
显示端口速率	查看端口上下行速率	按需
允许设置主机名	修改主机名	按需
允许自助断网 / 恢复联网	在面板上断网、恢复网络	谨慎，误操作会让客户自己断掉自己

这些开关控制会员中心的功能展示与调用范围。某项能力如果需要按合同或安全要求严格限制，建议同时在 DCIM 侧对该账号配置权限，两边一致更稳妥。

自动化细节

开关	效果	建议
暂停时关闭电源 / 关闭所有网络端口	逾期暂停时关机、断网	建议打开
下架时关闭电源 / 关闭所有网络端口	终止时关机、断网	建议打开
上架机器时不打开内网端口	开通时不动内网端口	按机房网络架构
下架机器时不关闭内网端口	终止时不动内网端口	按机房网络架构
下架时删除所有 IP 地址	终止时释放全部 IP	按 IP 资源策略
下架时删除附加 IP 地址	终止时只释放附加 IP，保留主 IP	按 IP 资源策略

续费恢复时的动作取自「暂停时」那两个开关。

开通时机（页面底部）

选项	适用
当客户下单之后（未付款）立即自动开通	容易被刷单，慎用
当收到客户首付款时自动开通	常规推荐
手动审核通过后自动开通	需要人工核机时
手动开通	全人工

设置完点 Save Changes。价格在「定价」页签配。

4.3 让客户下单时能选操作系统

在产品「模块设置」里点 创建/同步系统模板。系统会拉取 DCIM 的镜像列表，生成一个名为 Toplink DCIM 快速添加配置选项 的可配置选项组，自动关联到当前产品，然后跳到该选项组的管理页，你可以在那里改显示名和价格。

规则：

DCIM 里禁用的镜像不会同步

镜像在 DCIM 改了名字，再同步一次会一并更新

重复点击不会重复建组，会复用已关联的那一个

DCIM 新增镜像后，回来点一次「创建/同步系统模板」即可。

改显示名和价格没问题，但选项名里 | 前面的部分不要动，那是系统用来识别镜像的。

4.4 带宽、附加 IP、硬件配置做成计费选项

产品模块设置里的「自动化开通附加选项」提供了几个一键入口，点一下就会生成对应的可配置选项组并关联到当前产品，跳转后可自行改显示名和价格：

入口	生成的选项	预置内容
添加带宽计费可配置选项（上行 + 下行 / 只上行 / 只下行）	带宽 / 上行带宽 / 下行带宽	默认、10、50、100 Mbps、不限速
添加套餐可配置选项	硬件配置	默认，加上 DCIM 里的全部套餐
附加 IP 段 → 先选一个 IP 段 → 添加	额外 IPv4 地址	无；1～4 个额外 IP；/29 至 /24 的整段，另有「不同 C 段」的随机版本

两点要注意：

附加 IP 段必须先在下拉里选中一个段再点添加，否则会提示先选 IP 段

「硬件配置」选项会覆盖模块设置里配的套餐。客户在下单页选了哪个套餐，就按哪个开通

客户下单时看到的效果：

五、日常运营

5.1 上线前走一笔测试单

配置完先自己下一笔单跑通：

用测试客户下单并付款

看服务记录是否自动变为已激活，主机名、独立 IP、分配的 IP、用户名、密码、远程端口是否都回填了

点「跳转到管理界面」，确认能打开、能读到硬件与端口流量

去 DCIM 看这台机器的分配信息，用户和套餐都应已填上

用测试客户登录会员中心，确认管理界面在、权限符合配置

5.2 手动绑定一台已有的机器

进 WHMCS 后台 → 客户 → 产品/服务，找到该服务，页面上有「手动绑定服务器」输入框。

填入 DCIM 的服务器 ID（设备管理 → 服务器管理列表里的 ID 列，不是物理标签、不是主机名），点确定。

绑定成功后平台会自动同步服务器信息回 WHMCS。

要换一台机器：先执行终止（Terminate），再重新绑定。直接覆盖填 ID 不会解除原来的绑定，DCIM 那边旧机器仍是占用状态。

5.3 后台能做的操作

服务页上的模块命令：开通/创建、暂停、解除暂停、终止、开机、关机、重启、同步、跳转到管理界面、强制解绑。

管理界面里有设备摘要、分配 IP 地址、硬件、硬件历史四个页签，以及重置 BMC、重装系统、救援模式、重置密码、启动 VNC、硬件检测，下方是端口流量图。

客户在会员中心看到的是同一套界面，分 Server Information 与 Configurable Options 两个页签。

5.4 主机名什么时候会被重新生成

配置了主机名格式、或开了「强制使用生成的主机名」之后，这几个时机会按格式重新生成主机名并写回 WHMCS：

下单开通后

手动绑定后

客户续费时

管理员在后台点同步时

客户如果有自己的主机名命名规范，就别开「强制使用生成的主机名」。不开时，只有客户填了不合法的主机名才会被替换。

5.5 定期对账

服务器设置页的「查找异常未绑定服务器」会列出 WHMCS 侧无绑定关系、DCIM 侧仍被绑定的机器。

建议纳入例行运维：批量退订、到期终止之后跑一次，把列出来的机器到 DCIM 手工解绑，避免资源账实不符。

六、常见问题自查

6.1 绑定或开通提示「内部服务器错误」

先看 DCIM 侧的账号有没有建出来。去 DCIM 搜「用户名前缀 + 该客户的 WHMCS 用户 ID」，比如前缀 test、用户 ID 是 1，就搜 test1。

搜不到，说明卡在建账号这一步，绝大多数情况是 DCIM 还没配用户分组。按 2.1 建好分组后重新绑定或重新开通即可。

搜得到，说明账号没问题，看 6.3。

6.2 测试连接失败

现象	原因	处理
连不上、超时	网络不通、域名解析失败、端口未放行	在 WHMCS 服务器上 `curl` 一下 DCIM 地址
认证失败	KEY 或 secret 有误，或已在 DCIM 侧删除	重新生成一对并回填
证书报错	自签或证书链不全	勾「不校验 SSL 证书」，或补全证书链
返回内容无法解析	地址指向的不是 DCIM，比如被反代到别的站点	核对主机名和 IP 地址

另外两条：DCIM 用非 443 端口时要勾「用自定义端口覆盖」；DCIM 系统 API 里填的 IP 白名单要是 WHMCS 的实际出口 IP。

6.3 自动开通没出机器

按顺序查：

检查点	说明
「配置套餐」是不是选了「不选择套餐」	选了就等于关闭自动开通
DCIM 里有没有绑该套餐的空闲机器	见 2.2，机器没绑套餐是最常见的一条
数据中心选对没有	机器在 A 机房、产品配了 B 机房就匹配不到
服务器有没有加进服务器组	见 3.5
开通时机	「收到首付款时自动开通」需要账单真的标记为已付
DCIM 用户分组	见 6.1

6.4 模块下拉里找不到 Toplink DCIM，或提示要装 ionCube Loader

可能	处理
装错 PHP 版本的包	确认站点 PHP 版本，换对应的包重新上传
没装 ionCube Loader	安装与当前 PHP 版本匹配的 Loader 并重启 PHP
目录层级不对	确认路径是 `modules/servers/toplink_dcim/toplink_dcim.php`

6.5 客户下单选不到操作系统

可能	处理
没点过「创建/同步系统模板」	进产品模块设置点一次
DCIM 里镜像被禁用	禁用的不会同步
选项组没关联到产品	同步会自动关联；手工建的组要自己关联
选项名被改过	显示名可以改，`\|` 前面的部分不要动

6.6 点「附加 IP 段 → 添加」没反应

需要先在旁边的下拉里选中一个 IP 段。下拉为空说明 DCIM 侧还没配 IPv4 段，或当前连接节点取不到段列表。

如果产品还没保存过，也会提示先保存产品再试。

6.7 客户说主机名被改掉了

见 5.4，检查「默认 WHMCS 主机名格式」和「强制使用生成的主机名」。

6.8 跳转到管理界面打不开

界面以新窗口打开，浏览器拦弹窗时会失败，允许本站点弹窗

该服务必须已经绑定了机器，没绑定会先要求绑定

一直停在 Loading，检查插件的 ui 目录是否完整上传

6.9 提示显示为 `error.xxxxx` 这样的代号

部分提示以内部代号呈现，对照理解即可，不影响功能：

代号	含义
`error.permission_denied`	产品「用户端控制」里对应的开关是关的
`error.change_power_status`	开关机失败，去 DCIM 看机器状态与任务队列
`error.failed_to_reset_password`	重置密码失败，多为密码复杂度不符或机器有在途任务
`error.failed_to_get_image_list`	获取镜像列表失败
`error.failed_to_reinstall_system_msg`	重装失败
`error.failed_to_edit_hostname` / `error.invalid_hostname`	主机名修改失败或格式不合法
`error.failed_to_set_auto_hostname`	按主机名格式生成失败，检查格式配置
`error.failed_to_send_key`	控制台按键发送失败，VNC 会话可能已断开
`error.package_not_found` / `error.package_server_not_found`	产品或其连接节点找不到，多为产品未保存或连接节点被删除
`error.save_after_select_node`	还没选连接节点，选好保存即可
`error.wrong_product_type`	产品类型不对，改为独服/VPS 后保存
`error.config_not_found`	没有可用的服务器配置，先去服务器设置里添加

主机名格式的规则：按点分段，最后一段要以字母开头、以字母或数字结尾，中间只允许字母、数字和连字符。

七、需要支持时

提供以下信息可以最快定位：

现象：哪个客户、哪个订单、什么操作、什么时间

完整报错截图，含地址栏

WHMCS 该服务页的截图，能看到主机名、IP、状态、服务器

产品「模块设置」页的截图

DCIM 里这台机器的详情页截图，能看到 ID 和分配信息

WHMCS 站点的 PHP 版本与 WHMCS 版本

自己可以先试的：

情况	先试
单笔开通失败	终止后重新绑定或重新开通
怀疑配置没生效	产品模块设置重新保存一次
刚改了密钥	稍等几分钟再测
怀疑机器本身有问题	在 DCIM 里直接对这台机器做同样操作，看 DCIM 是否也报错

附录 A：八条要点

DCIM 先建用户分组，再做 WHMCS 侧配置

套餐要先建，机器要先绑套餐，自动开通才有机器可选

插件按 PHP 版本分包，站点要装匹配的 ionCube Loader

产品模块设置里，连接节点要先选并保存，其余下拉才会加载

换绑机器先终止再绑定，不要直接覆盖填 ID

系统模板和计费选项的显示名可以改，| 前面的值不要动

「硬件配置」可配置选项会覆盖模块设置里的套餐

退订后用「查找异常未绑定服务器」定期对账

附录 B：术语对照

说法	指
服务器 / 节点	WHMCS 里配置的一条 DCIM 连接
服务器组	服务器的容器，产品通过它选到服务器
连接节点	产品模块设置里选的那条 DCIM 连接
套餐	DCIM 里定义的机器规格组合，自动开通靠它匹配机器
绑定	把 DCIM 的一台服务器分配给某个 DCIM 账号
服务器 ID	DCIM 服务器管理列表里的 ID，手动绑定时填的就是它
可配置选项	WHMCS 里给产品挂下单选项（系统、带宽、附加 IP 等）的机制
系统模板	同步过来的 DCIM 镜像列表，客户下单时选的操作系统

顶联 DCIM 对接 WHMCS

一、开始之前#

二、DCIM 侧准备#

2.1 建用户分组#

2.2 建套餐并把机器绑上去#

2.3 取 API 密钥#

三、WHMCS 侧配置#

3.1 安装插件#

3.2 添加服务器#

3.3 测试连接#

3.4 自定义设置区域#

3.5 建服务器分组#

四、产品配置#

4.1 新增产品#

4.2 模块设置#

4.3 让客户下单时能选操作系统#

4.4 带宽、附加 IP、硬件配置做成计费选项#

五、日常运营#

5.1 上线前走一笔测试单#

5.2 手动绑定一台已有的机器#

5.3 后台能做的操作#

5.4 主机名什么时候会被重新生成#

5.5 定期对账#

六、常见问题自查#

6.1 绑定或开通提示「内部服务器错误」#

6.2 测试连接失败#

6.3 自动开通没出机器#

6.4 模块下拉里找不到 Toplink DCIM，或提示要装 ionCube Loader#

6.5 客户下单选不到操作系统#

6.6 点「附加 IP 段 → 添加」没反应#

6.7 客户说主机名被改掉了#

6.8 跳转到管理界面打不开#

6.9 提示显示为 error.xxxxx 这样的代号#

七、需要支持时#

附录 A：八条要点#

附录 B：术语对照#