007CDN 官方使用指南

智简魔方财务插件:从安装到开通续费

配置代理接口、对接套餐/流量包/游戏盾商品,完成新购、续费、网站与防御设置,并处理常见开通错误。

智简魔方财务插件:从安装到开通续费

本教程适用于 007CDN 智简魔方财务插件,已联调的宿主为魔方财务 3.7.8、PHP 7.2.33。V10 业务系统不使用此安装包。下载页显示当前发布版本;不同宿主版本请先用隐藏商品验证,再开放销售。

先理解两边如何结算

客户在你的魔方财务付款,魔方调用 007CDN 接口,从你的 CDN 代理余额采购对应权益。客户零售价由魔方管理,代理采购价由 CDN 返回,两者可以不同。魔方客户的余额不会直接进入 CDN 客户钱包。

开通成功需要三项同时成立:魔方账单已付款、CDN 采购成功、权益已交付。请求已受理不等于产品已开通。不要删除旧订单或再次购买来解决处理中状态。

1. 准备账号和接口

  1. 登录 007CDN 代理账号,确认余额足够支付测试采购和后续续费。
  2. 在 API 对接中建立专用 AccessKey,记录 key 和 secret。请勿将密钥放在商品描述、客户自定义字段、工单截图或网页源码中。
  3. 平台管理员进入 系统管理 → 代理销售 · 安装实例,填写已开启代理购买 API 的账号 ID 和该账号专用的 Access Key ID,点击 登记安装实例。密钥需具备订单写入、支付写入权限。将生成的安装实例 ID 提供给魔方管理员,填写到 魔方后台 → 系统设置 → 接口/服务器 → 007CDN 代理销售 → Access Hash。

用户自助管理默认关闭。管理员开启“允许用户管理自己的安装实例”后,代理可在 用户中心 → 代理中心 → 我的安装实例 选择自己的合格 Key 登记、更换密钥及启用/停用。不能操作他人的账号、密钥和实例;无需额外向管理员申请单个 Key 的登记名额。关闭后所有用户管理接口返回无权限,但已有实例的正常代理调用不受开关影响。实例页面不显示 Secret,请在创建 Key 时妥善保存。

  1. 确认可售目录中有需要销售的套餐、流量包或游戏盾商品,以及对应付款周期。不是所有产品都包含转发、游戏盾或所有防御功能。
  2. 准备可用的 HTTPS API 域名。主机名字段只填域名,不填 https://、路径或 /api/v1;若使用非默认端口,单独填写端口。

2. 安装模块

先备份魔方数据库和现有同名模块。服务器 PHP CLI 和网页 PHP 都需要 cURL、PDO MySQL 扩展,并能够校验公网 TLS 证书。

  1. 从 软件下载 登录下载最新版,核对页面 SHA-256;压缩包包含编译好的控制台,无须在财务服务器安装 Node.js。
  2. 在已验收的魔方财务 3.7.8 中,将 cdn007finance 文件夹放到站点的 public/plugins/servers/,最终应有 public/plugins/servers/cdn007finance/cdn007finance.php,不能多套一层目录。
  3. 使用站点对应的 PHP 执行安装器:

``sh /实际PHP路径/php /站点根目录/public/plugins/servers/cdn007finance/bin/install.php ``

安装器创建插件业务表和索引,可重复执行,保留已有采购记录。不要从浏览器访问安装器。官方模块开发文档中的目录示例与部分实际版本不同;若模块不出现在列表,先核对本机已有服务器模块的实际目录,不要同时安装两份。

3. 创建魔方接口并同步商品

在魔方管理员后台进入服务器接口设置,新建接口。不同主题的菜单文字可能略有差异,以包含“接口设置/服务器”的页面为准。

字段填写内容
模块007CDN 代理销售
主机名平台提供的 API 域名,仅域名
安全连接启用 HTTPS
端口默认 443,或平台指定值
用户名专用 AccessKey 的 key
密码对应 secret,由魔方正常保存加密
Access Hash已登记的安装实例 ID

保存后点击“测试连接”。成功提示应同时显示同步到的商品数量。再把该接口加入接口分组,后续商品选择此分组。

user007cdn.007cdn.com 和 admin007cdn2026.007cdn.com 均提供代理接口;新接入建议统一使用前者,已有接口不要随意修改地址。0.3.8 起,管理员测试连接在核验 Key 与安装实例匹配后,自动创建/升级插件专用数据表;若数据库缺少权限,按提示运行安装器或联系站点管理员。

连接失败时依次核对 HTTPS、证书、服务器时间、key/secret、安装实例登记和代理权限。不要关闭证书校验。目录为空不等于接口连接失败,也不代表可以开始销售;请按下面的准入条件核对。

同步到 0 个商品时怎么处理

目录只包含已上架、允许该代理采购且商品规格受模块支持的项目。商品在 CDN 后台可见,并不自动代表代理接口可采购。

  • 实名认证、手机和邮箱验证要求作用于 CDN 代理采购账号。插件会读取该代理账号已验证的实名状态及手机号/邮箱验证标记,目录、报价和采购执行阶段都会校验。即使商品已出现在目录中,认证撤销或失效也会在实际采购前拦截,不会扣款。魔方客户自己的资料和验证由魔方财务管理,不把代理账号身份冒用成客户身份。
  • 商品状态:套餐、流量包、游戏盾必须上架,测试或下架商品不会用于新购。
  • 商品规格及周期:模块暂不支持的限额组合、付款周期和游戏盾数据面能力仍会被过滤。不要手填商品 ID 绕过目录准入。

如果目录为空,先检查代理账号的实名审核、手机/邮箱验证状态、商品上架状态、代理销售权限及商品规格;测试连接成功本身不代表商品已同步。不要为了让商品出现而关闭 CDN 商品验证要求。

目录为空时,先保持魔方商品隐藏并停止接受该商品的新订单;条件满足后重新同步目录、选择商品,再完成新购与续费验证后开放销售。

多个接口和密钥更换

同一个 CDN 代理账号可以登记多个安装实例,各自绑定一个专用 Key;仅创建 API Key 不会自动登记。不同魔方站点使用各自的安装实例 ID。

已有站点更换 Key:平台管理员在“系统管理 → 代理销售 · 安装实例”的原实例上点击“更换密钥”,填写同一代理账号下有效、具备采购权限且未绑定其他实例的新 Access Key ID。再修改魔方接口的用户名和密码,Hash 保持不变。旧 Key 不能再调用该实例,已有订单、客户和产品关联保留。不要为更换密钥而重建已有站点的实例。后台开放自助管理时,用户也可在“我的安装实例”中更换自己的 Key。建议先升级插件至 0.3.8 或更高版本并完成初始化;同一 API 地址和安装实例下换钥会保留魔方原接口、商品和账本关联。

4. 配置套餐、流量包和游戏盾商品

每个魔方商品对应一个 CDN 商品。建议先建立隐藏的测试商品,完成一笔新购和续费后再公开。

  1. 新建魔方商品,模块选择“007CDN 代理销售”,接口分组选择上一节的分组。
  2. 在模块配置的“CDN 产品”下拉框选对应商品。选项与接口绑定,更换接口后应重新同步目录并核对映射,不能直接复用其他接口的选项。0.3.8 起,同一 API 地址和安装实例内换钥保留原接口标识及商品映射。
  3. 设置“每次采购金额上限(元)”。它限制每次 CDN 采购支出,不是客户售价。应覆盖你销售的最长周期的真实采购价,超过上限会停止采购并保留原账单。
  4. 在魔方价格页配置客户零售价和付款周期。示例:CDN 月采购价 30 元,魔方可设月零售价 50 元;季付需要独立核对季采购价和上限。
  5. 不销售的周期设置为 -1,不要设置为 0;魔方的 0 表示可免费购买。
  6. 配置付款成功后自动开通,先通过隐藏商品验证宿主的付款回调和自动任务确实运行。
商品类型开通后操作配置注意事项
CDN 套餐添加网站、配置 DNS、HTTPS、回源、缓存和防御功能由购买套餐授权,TCP/UDP 需商品包含该能力
流量包在该产品控制台添加及配置网站与其他商品的网站分开管理;有效期和流量按 CDN 商品定义
游戏盾管理已交付的实例、防护和 TCP/UDP 转发关联网站必须属于同一客户且符合实例集群要求;需要时另购同集群网站套餐

当前模块映射月付、季付、半年付、年付、一次性;对应 CDN 周期为 month、quarter、half_year、year、forever。只有目录提供对应周期时才可销售。CDN 平台允许自定义月数,不代表此魔方模块已支持任意月数;不要启用未验收的小时、日付或多年周期。一次性也不代表所有产品永久有效。

5. 配置自动处理任务

用站点运行用户每分钟执行一次 worker。下面示例用于 /etc/cron.d/,需要替换 PHP、站点和日志路径;宝塔计划任务或用户 crontab 通常不填写中间的 www 用户列。

```cron

  • * * * * www /usr/bin/timeout 55s /实际PHP路径/php /站点根目录/public/plugins/servers/cdn007finance/bin/worker.php >> /日志目录/cdn007finance-worker.log 2>&1

```

确认站点用户可写站点 data 和日志目录。仅安装一份任务;程序有锁、防重及退避,但重复安装 cron 没有好处。设置日志按日轮转和容量上限。手动运行一次检查退出状态,再观察定时任务是否执行。

6. 从客户下单到网站可访问

  1. 客户选择商品和周期,在魔方生成订单并完成付款。测试时可使用宿主允许的线下测试支付方式;这不能替代微信、支付宝真实支付验收。
  2. 查看产品详情的“CDN 控制台”。处理中时等候 worker 或管理员同步,不要重复付款。
  3. 确认“权益已开通”,核对魔方财务到期时间与 CDN 权益到期时间。首次开通时间可能有秒级差异;若差异明显,先处理再销售。
  4. 点击“添加网站”,填客户自己的域名,选择可用集群,填写源站地址、HTTP/HTTPS 协议和真实源站端口。
  5. 复制完整 CNAME,在域名 DNS 服务商添加 CNAME 记录,移除冲突的同名记录。若机房要求域名过白,先完成过白。
  6. 在 HTTPS 配置申请或上传证书,确认签发和节点生效后访问 HTTPS。不得只依据面板“已保存”判断成功。
  7. 配置缓存、CC/WAF、回源、访问控制等授权功能,保存后回读。用真实网站测试状态码、内容、证书和首包耗时;缓存测试保持完整 URL 一致,动态鉴权接口按业务规则排除缓存。
  8. 查看用量与访问日志。计费用量和访问明细统计口径不同;短时间内日志未出现应先核对上报延迟与时间范围。

TCP/UDP 转发需要填写监听端口、目标主机和目标端口,并分别从外部验证 TCP 连接与 UDP 回包。仅保存转发规则不代表网络可达。游戏盾 SDK 接入应先检查能力接口是否已就绪;未就绪时不要向客户承诺 SDK 可用。

7. 续费、暂停、删除和恢复

客户在魔方原产品发起续费并付款,由原账单驱动同一 CDN 权益续费。管理员核对原服务 ID、权益 ID、采购记录和两端到期时间,重复回调不能产生重复扣款。不要用新购替代续费。

代理余额不足:补充 CDN 代理余额,在魔方原产品后台执行“同步”,恢复原任务;客户无须再次付款。商品下架、周期不支持、采购上限不足或上游商品定义不兼容时,先修正对应问题,不能删账单、修改幂等键或强制伪造成功。

魔方“暂停”和“删除”在 CDN 侧都执行暂停,保留权益、网站和配置,不执行资源删除,也不自动退款。解除暂停可恢复符合条件的原权益。若在 CDN 恢复,可在魔方原产品后台同步拉取;原订单找回需管理员使用原采购订单号,并保留原服务记录及客户归属。不能将其他客户订单绑定到新服务。

域名过白按机房和规范化域名永久去重:同一机房提交过,即使失败或驳回也不能再次提交。应查询原申请并联系处理,不要换网站或账号重复提交。

跨商品升级/降级和魔方退款自动联动 CDN 采购退款目前未接通。客户侧退款与上游采购补偿需分别核对,不能把删除产品等同于退款完成。

8. 常见问题

现象检查与处理
找不到 CDN 商品先测试连接同步目录;若为 0,检查上架状态、实名认证/手机/邮箱要求、代理权限和所选接口,参照第 3 节
已付款但仍处理中检查 worker、代理余额、任务错误码;保留原账单同步
PURCHASE_LIMIT_EXCEEDED核对实际采购价格、所选周期和采购上限,不调整客户已付金额来绕过
PRICE_CHANGED上游报价或产品定义已变,核对原权益和商品;不能反复重购
PRODUCT_CONNECTION_MISMATCH商品映射与接口不一致,检查接口分组及同步目录
UNSUPPORTED_BILLING_CYCLE魔方付款周期不受支持,请关闭对应售价并选用已验证的周期
SERVICE_BINDING_MISMATCH核对客户、原产品、接口、安装实例,不直接修改数据库绑定
防御功能不可用或模板为空核对产品授权、资源归属和平台模板,不能把加载失败当成未启用
已保存但站点无法访问分别核对 DNS、证书、节点配置、源站、监听端口及链路
重复提交过白失败查看该机房原记录并跟进原申请

9. 上线前自检和更新

逐项验证:连接及目录、新购付款、单次采购扣款、权益交付、网站配置保存回读、HTTPS、续费后到期时间、暂停与恢复、删除转暂停、跨产品资源隔离和错误提示。游戏业务还需持续验证 UDP 丢包和故障恢复。

更新前备份数据库和原模块目录,覆盖新模块文件后运行安装器,检查历史服务和任务,再验证一笔隐藏商品流程。保留旧包用于回退,不能通过删除财务记录回滚。下载页的文件散列用于核验安装包,密钥不得随备份或安装包公开分发。

本模块核心新购、续费和资源管理已有联调记录,但不代表所有宿主主题、支付网关、机房审批或网络路径都通过验收。遇到问题提交脱敏错误码、时间、魔方订单/账单号和服务 ID,不提交密码、secret 或客户授权令牌。

官方参考:智简魔方财务开发文档。具体菜单和模块路径请结合本机版本核对。

插件内部错误排查

旧版 MODULE_INTERNAL_ERROR 不能仅凭提示确定原因,也不等于地址填错。新版区分数据表未初始化、数据库权限不足及接口实例不匹配;未识别异常显示诊断编号。站点管理员可在 PHP 错误日志搜索 [007CDN] 和该编号,日志仅记录异常类型、文件名与行号,不记录密码、Secret 或 SQL 内容。不要通过重购产品来排查连接问题。

本文由 007CDN 文档中心维护。产品支持范围和价格以控制台及订单为准。提交工单