顶联 DCIM 对接魔方财务

适用对象：用魔方财务销售服务器、用顶联 DCIM 管理机房的运营方管理员。
适用模块：魔方财务服务器模组 TopLink DCIM。

一、开始之前

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

客户下单付款后自动从 DCIM 分配机器、装系统、回填 IP 和密码

机器已在 DCIM 备好时，管理员填一个服务器 ID 即可绑定到订单

客户在会员中心自助开关机、重装系统、开 VNC、查看硬件与流量，权限由你逐项控制

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

动手前先确认四件事：

确认项	怎么看
DCIM 已建好用户组	后台「用户管理 → 用户组」不为空
DCIM 有数据中心和套餐	自动开通要用到
要卖的服务器已上架、已分配 IP、状态正常	服务器详情页能看到 ID 和 IP
魔方站点能访问 DCIM 地址	域名解析、防火墙、证书都通

整体顺序：

DCIM 建用户组、取 API 密钥
  → 魔方装插件、建接口、测通
  → 建商品组、建商品、配自动开通
  → 下一笔测试单验收

二、DCIM 侧准备

2.1 建用户组

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

顺序反了的话，账号建不出来，开通就会停在这一步，而界面上给出的提示未必会指向用户组，容易多花时间排查。所以把它放在第一位。

操作：DCIM 后台 → 用户管理 → 用户组，确认存在可用的用户组；没有就新建一个，并按 DCIM 的规则设为默认组。

确认方法：在 DCIM 里手工建一个测试用户，能建出来就说明这一环通了。

2.2 取 API 密钥

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

标签：填个能认出来源的名字，比如 魔方

IPV4地址：填魔方站点的出口 IP 可以做白名单收敛，不确定就留空

提交后会弹出 KEY 和 secret。

这两串只显示这一次，请当场复制保存，关掉窗口就看不到了，丢了只能重新生成一对。

拿到的	稍后填到
KEY	魔方通用接口的「用户名」
secret	魔方通用接口的「密码」

三、魔方财务侧配置

3.1 安装插件

把 toplinkdcim.zip 上传到魔方站点的 public/plugins/servers/ 目录，就地解压。

解压后应得到一个 toplinkdcim 目录，里面直接是插件文件。几点注意：

如果解压成了 toplinkdcim/toplinkdcim/...，要把里面一层挪出来

附带的 __MACOSX 目录可以删掉

3.2 建接口分组

路径：设置 → 商品设置 → 自动化接口 → 通用接口 → 接口分组名 → 创建。

接口分组名填 Toplink 之类即可。分配方式在单节点场景下选哪个都一样，多节点时「平均分配」更均衡。此时「选择空闲接口」是空的，属正常，先提交。

3.3 建接口

路径：通用接口 → 接口 → 创建接口。

字段	填法
名称	自定义
IP地址	DCIM 的域名或 IP，不带 `http://`、`https://`。例：`demo.dcim.co`
服务器模块	选 `TopLink DCIM`；选不到说明插件目录不对，回 3.1 检查
接口容量	这个节点计划承载的产品数，建议不小于 DCIM 授权数量
主机名	备注用
接口分组名	选 3.2 建的分组
用户名	DCIM 的 KEY
密码	DCIM 的 secret
端口	填 `80`。DCIM 若使用非标准端口，见下方说明
secure	DCIM 用 https 就勾上
Hash	高级参数，一般留空，见 5.4

提交后回到列表，状态图标变绿即表示密钥和网络都正常。

三点补充：

协议头。 系统会根据 secure 开关自动补 http:// 或 https://，所以 IP地址栏只填域名或 IP。填成 https://demo.dcim.co 会重复拼接，导致连不上。

非标准端口。 DCIM 跑在 8443 之类的端口时，在 Hash 里写一行 port = 8443，不要改「端口」栏。访问地址的端口取自 Hash。

绿色状态的含义。 它表示密钥正确、网络可达，不代表用户组、套餐、数据中心都已就绪，这些要等第一笔测试单才验证得出来。

四、把服务器做成商品

4.1 建商品组和商品

路径：设置 → 商品设置 → 商品配置 → 商品管理。先「新增分组」，再「新增商品」。

字段	填法
商品名称	自定义
商品类型	选「虚拟主机」或其他非「独立服务器」类型
商品组	选刚建的分组
会员中心导航分类	按需要选，只影响展示位置

商品类型这里请选「虚拟主机」。选「独立服务器」时，魔方会走另一套客户区渲染，本模组的「管理」选项卡在客户端不会显示。这与你实际卖的是不是独服无关，只是类型字段的选择。

4.2 配置自动开通

进商品 → 自动开通页签，开通方式选「自动化接口」，接口分组选 Toplink(TopLink DCIM)，保存。

保存后页面会刷出全部配置项。

必填两项：

配置项	说明
数据中心	从哪个机房出机器
套餐	对应 DCIM 里的套餐。选「不自动开通」即关闭自动开通，客户付款后需你手动绑定

客户端权限开关：

开关	打开后客户可以	建议
控制服务器电源	开关机、重启	一般打开
自助重装系统	自选镜像重装	一般打开
显示硬件信息	查看 CPU、内存、硬盘型号	按需
VNC 控制	使用 VNC	一般打开
显示端口速率	查看端口上下行速率	按需
允许设置主机名	修改主机名	按需

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

生命周期开关：

开关	效果	建议
暂停时关闭电源	逾期暂停时关机	建议打开
暂停时关闭端口	逾期暂停时断网	建议打开
下架时关闭电源、关闭端口	退订时关机、断网	建议打开
下架时删除所有 IP 地址	退订释放全部 IP	按 IP 资源策略
下架时删除附加 IP 地址	退订只释放附加 IP，保留主 IP	按 IP 资源策略
开通新机器时解绑旧机器的 IP 地址	换机时让出旧 IP	有换机需求时打开
开通新机器时强制端口 VLAN 跟随 IP	网络配置一致性	按机房架构

续费恢复时的动作取自「暂停时」那两个开关：暂停时关了电源，恢复时就开机；暂停时断了网，恢复时就恢复网络。

页面底部的开通方式：

选项	适用
不自动	需要人工核机，或首次调试
付款后自动	常规推荐
下单后直接开通（无需付款）	容易被刷单，慎用

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

分两步，第二步容易漏。

同步镜像。 打开商品的「自动开通」配置页时，系统会自动去 DCIM 拉一次镜像列表，无需点任何按钮。结果显示在页面上方的「模块提示」框里，形如：

镜像同步: 完成, 新增 12 个, 已存在跳过 30 个

同步有 3 分钟的间隔保护，期间重复打开会跳过。同步只新增不覆盖，你手工改过的镜像显示名不会被冲掉。DCIM 里已禁用的镜像不会同步过来。

同步会建出一个配置选项组，名为 Toplink DCIM 快速添加配置选项。

把配置选项组分配给商品。 同步只负责建出选项组，还需要你到商品的「产品配置 / 可配置选项」里，把 Toplink DCIM 快速添加配置选项 分配给这个商品。做完之后客户下单页才会出现操作系统下拉框。

后续 DCIM 新增了镜像想让客户看到：DCIM 里加好镜像，回魔方打开一次商品的自动开通页，看提示显示新增成功即可。

五、日常运营

5.1 上线前走一笔测试单

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

用测试客户账号下单并付款

看该产品是否自动变为「已激活」，IP地址、用户名、密码、主机名、远程端口、系统是否都已回填

点「管理面板」，确认能打开、能读到硬件和网络信息

去 DCIM 看这台服务器的分配信息，用户应显示为 userXX(独享)

用测试客户登录会员中心，确认「管理」选项卡在、权限符合配置

5.2 手动绑定已有机器

适用于机器已在 DCIM 备好、或这笔单不走自动开通的情况。

第一步，后台进客户 → 产品/服务，选中该产品，状态改为「已激活」并保存。

第二步，点「接口命令」里的「管理面板」，弹出绑定窗口。

不同插件版本这个窗口的外观略有差异，旧版是一行输入框，新版是卡片式表单带确认弹窗，操作一致。

第三步，去 DCIM 的设备管理 → 服务器管理 → 服务器详情，复制页面上的 ID。要的是这个数字 ID，不是物理标签，也不是主机名。

第四步，填入提交，出现「添加成功，5 秒后将跳转到该服务器的管理面板」即完成。

绑完回产品页确认 IP 已回填，DCIM 那边分配信息里有这个用户。

5.3 逾期、续费、退订时系统做了什么

场景	自动执行
逾期暂停	按「暂停时关闭电源 / 关闭端口」执行关机、断网
续费恢复	按同样两个开关反向执行开机、恢复网络
退订、到期终止	按「下架时」的开关执行关机断网，解除服务器与客户的绑定，按 IP 配置释放 IP，清除魔方侧的绑定关系

退订环节有一点需要留意：解绑动作以魔方侧为准，若 DCIM 那边因机器正在跑任务等原因未能同步完成，魔方的绑定关系仍会清除。建议对退订和到期终止的机器做定期对账，在 DCIM 里按分配信息筛一遍，确认没有本该空闲却仍挂着用户的机器。这个动作顺手做，能避免资源账实不符。

5.4 Hash 高级参数

多数场景用不到。需要时填在接口配置的 Hash 字段里，一行一个：

参数	用途
`port`	DCIM 使用非标准端口时填这里，访问地址的端口取自本项
`no_verify_ssl = 1`	DCIM 使用自签或内网证书，连接报证书错误时打开
`username_prefix`	改 DCIM 中自动创建账号的前缀。默认 `user`，账号形如 `user12`；改成 `mf` 后为 `mf12`
`force_use_auto_hostname` + `hostname_format`	开通时按规则自动生成主机名。占位符：`{label}` 物理标签、`{ipv4}` 主 IP、`{random_4char}` 四位随机字符
`remove_intranet_on_terminate = 1`	退订时一并解除内网绑定并关闭内网端口

主机名这两项要成对配置，只填 force_use_auto_hostname 而不给格式，开通会失败。生成的主机名按点分段，最后一段需以字母开头，所以 {ipv4}.example.com 可用，srv.{ipv4} 这种把 IP 放末尾的写法不行。

六、常见问题自查

6.1 开通失败，或产品页 IP 一直为空

先看 DCIM 侧的账号有没有建出来。去 DCIM 搜 user 加客户在魔方里的用户 ID，比如客户 ID 是 12 就搜 user12。

搜不到这个账号，说明卡在建账号这一步，绝大多数情况是 DCIM 还没配用户组，按 2.1 建好用户组，清掉该产品的绑定关系重新开通即可。

搜得到账号，说明账号没问题，看下面几条：

现象	原因	处理
提示「该产品不支持自动开通，请在产品设置处设置套餐后再试」	商品的套餐选的是「不自动开通」	改成真实套餐并保存
提示重装系统失败	镜像有问题、密码不符合 DCIM 复杂度要求、或机器正在跑任务	先去 DCIM 确认这台机器是否已经分配出去，必要时手工解绑再重试
没有符合条件的空闲机器	该套餐与数据中心组合下无可分配机器	去 DCIM 补机器或调整套餐

6.2 接口状态红色

提示	原因	处理
连接错误	网络不通、域名解析失败、端口未开放	在魔方服务器上 `curl` 一下 DCIM 地址
认证失败	KEY 或 secret 有误，或已在 DCIM 侧删除	重新生成一对并回填
无法解析数据	IP地址指向的不是 DCIM，比如被反代到了别的站点	核对地址
证书相关报错	自签证书或证书链不全	Hash 里加 `no_verify_ssl = 1`

两个高频情况：IP地址栏填了协议头，去掉即可；刚改完密钥立刻测试还是旧结果，登录凭证有 3 分钟缓存，等一会儿再测。

6.3 客户看不到「管理」选项卡

商品类型选成了「独立服务器」，改为「虚拟主机」保存，让客户重新进会员中心。见 4.1。

6.4 管理面板打不开

管理面板以弹出窗口方式打开，所以：

浏览器拦截弹窗时会打不开，允许本站点弹窗即可

它的网址不能复制出来单独访问，需从产品页的「管理面板」按钮进入

点开后如果出现的是绑定界面而不是管理界面，说明这个订单还没有绑定关系。系统会自动判断：已绑定进管理界面，未绑定进绑定界面。这时回 6.1 查。

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

可能	处理
没打开过商品的自动开通页	打开一次即触发同步
3 分钟内重复打开被跳过	稍后再打开，看「模块提示」里的同步结果
同步成功但客户仍选不到	配置选项组还没分配给商品，见 4.3 第二步，这是最常见的原因
DCIM 里镜像被禁用	禁用的镜像不会同步

6.6 权限开关的作用范围

各开关的实际覆盖范围如下，配置时按这个预期来：

开关	覆盖范围
控制服务器电源	会员中心的电源按钮受控。校验在指令下发之后返回，因此关闭后客户误点仍可能触发一次实际动作
自助重装系统	覆盖镜像列表与分区方案的展示
VNC 控制	覆盖 VNC 会话；远程控制台是另一条通道，不在此开关范围内
显示端口速率	端口速率在服务端过滤，关闭后管理端一并不显示
允许设置主机名	主机名修改请使用单独的「修改主机名」操作；重装流程不支持同时改主机名
显示硬件信息	覆盖硬件明细与硬件履历

需要按合同或安全要求严格限制某项能力时，在 DCIM 侧对该用户一并配置权限，两边一致最稳妥。

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

部分提示以内部代号形式呈现，对照下表理解含义即可，不影响功能：

代号	含义
`error.permission_denied`	商品里对应的权限开关处于关闭状态
`error.change_power_status`	开关机失败，去 DCIM 看机器状态和任务队列
`error.failed_to_reset_password`	重置密码失败，多为密码复杂度不符或机器有在途任务
`error.failed_to_get_image_list`	获取镜像列表失败
`error.unsupport_change_hostname`、`error.invalid_hostname`	重装时带了自定义主机名，见 6.6
`error.failed_to_reinstall_system_msg`	重装失败
`error.failed_to_edit_hostname`	修改主机名失败，多为格式不合法
`error.failed_to_set_auto_hostname`	自动主机名生成失败，检查 `hostname_format`，见 5.4
`error.failed_to_next_boot_device`、`error.invaild_boot_device`	启动项设置失败
`error.failed_to_send_key`	控制台按键发送失败，VNC 会话可能已断开
`error.failed_to_get_task`、`error.failed_to_cancel_task`	任务查询或取消失败
`error.request_resuce_mode_failed`	进入救援模式失败
`Invaild hostname`	主机名格式不合法，格式要求见 5.4

七、需要支持时

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

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

完整报错截图，含地址栏

魔方后台该产品页截图，能看到 IP、状态、接口

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

魔方服务器上的 /tmp/toplinkdcim-params.log，记录了每次开通与绑定的参数，排查开通类问题最有用

商品「自动开通」页的配置截图

/tmp/toplinkdcim-params.log 会持续增长，建议纳入日志清理策略或定期手工清理。

自己可以先试的几件事：

情况	先试
单笔开通失败	清掉该产品的绑定关系，重新触发开通
怀疑配置没生效	商品自动开通页重新保存一次
刚改了密钥	等 3 分钟再测
怀疑机器本身有问题	在 DCIM 里直接对这台机器做同样操作，看 DCIM 是否也报错

附录 A：商品配置项速查

配置项	作用	建议
数据中心	从哪个机房出机器	必选
套餐	对应 DCIM 套餐，选「不自动开通」即关闭自动开通	自动开通必选
控制服务器电源	客户可开关机、重启	一般打开
自助重装系统	客户可自选镜像重装	一般打开
显示硬件信息	客户可见硬件明细	按需
VNC 控制	客户可用 VNC	一般打开
显示端口速率	端口速率展示，关闭后管理端一并不显示	按需
允许设置主机名	客户可改主机名	按需
暂停时关闭电源、关闭端口	逾期暂停时关机断网，恢复时反向执行	建议打开
下架时关闭电源、关闭端口	退订时关机断网	建议打开
下架时删除所有 IP 地址	退订释放全部 IP	按 IP 策略
下架时删除附加 IP 地址	退订只释放附加 IP	按 IP 策略
开通新机器时解绑旧机器的 IP 地址	换机时让出旧 IP	有换机需求时打开
开通新机器时强制端口 VLAN 跟随 IP	网络一致性	按机房架构
拉取远程镜像信息	镜像同步在打开配置页时自动执行，无需手动开启	无需设置

附录 B：八条要点

DCIM 先建用户组，再做魔方侧配置

接口的 IP地址栏不带协议头，是否 https 由 secure 开关决定

DCIM 非标准端口写在 Hash 的 port，不是「端口」栏

商品类型选「虚拟主机」，不选「独立服务器」

镜像同步之后，还要把配置选项组分配给商品

需要严格限制客户能力时，DCIM 侧一并配置权限

退订后建议定期在 DCIM 对账，确认机器已释放

改完密钥等 3 分钟再测

附录 C：术语对照

说法	指
通用接口、接口	魔方里配置的一条 DCIM 连接
接口分组	接口的容器，商品通过它选到接口
套餐（package）	DCIM 里定义的机器规格组合
绑定、link	把 DCIM 的一台服务器分配给某个 DCIM 账号
服务器 ID	DCIM 服务器详情页上的数字 ID，手动绑定时填的就是它
管理面板	产品页上打开的服务器管理弹窗
配置选项组	魔方里给商品挂可选项（如操作系统）的容器

顶联 DCIM 对接魔方财务

一、开始之前#

二、DCIM 侧准备#

2.1 建用户组#

2.2 取 API 密钥#

三、魔方财务侧配置#

3.1 安装插件#

3.2 建接口分组#

3.3 建接口#

四、把服务器做成商品#

4.1 建商品组和商品#

4.2 配置自动开通#

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

五、日常运营#

5.1 上线前走一笔测试单#

5.2 手动绑定已有机器#

5.3 逾期、续费、退订时系统做了什么#

5.4 Hash 高级参数#

六、常见问题自查#

6.1 开通失败，或产品页 IP 一直为空#

6.2 接口状态红色#

6.3 客户看不到「管理」选项卡#

6.4 管理面板打不开#

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

6.6 权限开关的作用范围#

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

七、需要支持时#

附录 A：商品配置项速查#

附录 B：八条要点#

附录 C：术语对照#