小黑云（XiaoHei Cloud）集成教程
🐾 使用
OpenIDC-XiaoHei插件把 OpenIDCS 对接到小黑云体系，实现 代理售卖 / 二级分销。
🎯 适用场景
- 您是 小黑云（XiaoHei Cloud）代理 / 经销商，希望以自己的品牌对外售卖小黑云资源
- 希望客户在您的财务系统（魔方 / SwapIDC）下单后自动从小黑云开通
- 希望统一接管多个上游供应商（青州云 / 小黑云 / 自建）
📦 插件说明
OpenIDC-XiaoHei 插件是在 OpenIDC-SwapIDC / OpenIDC-IDCSmart 协议基础上为小黑云定制的适配层，核心差异：
- 使用小黑云 OpenAPI 规范（AccessKey / SecretKey 签名）
- 适配小黑云套餐 / 镜像 ID 命名
- 集成小黑云专用功能：免费带宽池、流量复用、抗 CC 面板等
📌 两种接入方式
- 直连模式：财务系统 → OpenIDCS（作为聚合层）→ 小黑云 API
- 聚合模式：OpenIDCS 同时管理
LXD 自建节点 + 小黑云代理节点，对外表现为统一平台
📋 前置条件
| 项 | 要求 |
|---|---|
| 小黑云账号 | 已开通 代理 / 经销 资质 |
| API 密钥 | 控制台 → 我的账户 → API 管理 获取 AccessKey / SecretKey |
| 授权额度 | 确认您的小黑云账户有足够余额或授信 |
| OpenIDCS | 主控端已部署 |
| 财务系统 | 魔方财务 / SwapIDC（二选一） |
🚀 部署步骤
步骤 1 · 在 OpenIDCS 中添加小黑云节点
- OpenIDCS → 主机管理 → 添加主机。
- 填写：
| 字段 | 示例 |
|---|---|
| 平台类型 | 小黑云（XiaoHei Cloud） |
| API Endpoint | https://api.xiaoheiyun.example.com |
| Access Key | AK-xxxxxxxxxxxxxxxx |
| Secret Key | •••••••••••••••• |
| 区域 | cn-shanghai |
| 代理身份 | ✅ 开启分销模式 |
- 测试连接 → 返回账户余额与套餐列表即成功。
- 同步资源 → 拉取小黑云可售卖套餐与镜像。
详见 青州云 / 小黑云 后端部署。
步骤 2 · 配置对外售卖套餐
OpenIDCS → 产品套餐 → 新建：
| 字段 | 示例 |
|---|---|
| 套餐名称 | XiaoHei-VPS-CN-1C1G |
| 后端主机 | 小黑云（步骤 1 添加的节点） |
| 映射上游套餐 | basic-1c1g-10g（小黑云原始套餐 ID） |
| 对外价格 | 19 元 / 月（可高于采购价赚差价） |
| 最大订阅数 | 100 |
| 适用角色 | 所有 / 代理 / 金牌 |
保存后，该套餐可被财务系统使用。
步骤 3 · 在财务系统中配置产品
A. 魔方财务
使用 OpenIDC-IDCSmart 插件，在配置中选择 后端主机 = 小黑云节点，套餐规格与上游一致。
B. SwapIDC
使用 OpenIDC-SwapIDC 插件，在配置中选择 节点 ID = 小黑云节点 ID。
两个插件无需为小黑云单独安装 —— OpenIDCS 作为聚合层已经把小黑云包装成了"一个普通节点"。
步骤 4 · 客户下单
- 客户在财务系统购买
XiaoHei-VPS-CN-1C1G。 - 财务系统 → OpenIDCS → 小黑云 API → 真正开通。
- OpenIDCS 拿到小黑云返回的 IP / 控制台 URL，透传给财务系统。
- 客户在财务前台看到的是 您的品牌，实际资源来自小黑云。
🔁 能力矩阵
| 功能 | 是否支持 |
|---|---|
| 开通 / 删除 | ✅ |
| 续费 | ✅ |
| 升降配 | ✅ |
| 开关机 / 重启 | ✅ |
| 重装系统 | ✅ |
| 修改密码 | ✅ |
| VNC 控制台 | ✅（上游透传 URL） |
| 快照 | ✅ |
| 流量统计回传 | ✅ |
| NAT 端口转发 | ⚠️ 取决于上游是否支持 |
| IPv6 | ⚠️ 取决于套餐 |
| 迁移 / 热迁移 | ❌（上游能力） |
💰 成本 / 售价策略
OpenIDCS 聚合层允许您：
- 加价策略：采购价 + 固定加价 / 百分比加价
- 分级定价：对"普通客户 / 代理 / 金牌" 不同折扣
- 套餐重组：在一个上游套餐基础上叠加 "域名 / 备份 / 加速" 附加服务
- 对账报表：按月自动对比 "上游账单 vs 对外收入"，一目了然利润
🛡 风控建议
- ⚠️ 余额预警：小黑云账户余额 < 阈值时告警（邮件/企业微信）
- 🔒 并发限制：防止单日开通超上游限额，避免 API 被封
- 🚨 滥用检测：IP 黑名单、密集开通/退款识别
- 📜 合规：客户实名信息留存，配合小黑云上游合规要求
🧪 验证清单
完成对接后，建议逐项测试：
- [ ] 客户下单 → 自动开通成功，IP 正常
- [ ] 客户区开关机按钮生效
- [ ] VNC / 控制台可打开
- [ ] 重装系统 → 指定镜像成功
- [ ] 修改密码 → 登录验证
- [ ] 手动暂停 → 上游真实暂停
- [ ] 续费 → 到期时间正确延长
- [ ] 终止 → 上游删除 + 财务订单关闭
- [ ] 流量统计同步到财务
🧯 常见问题
开通失败 "Signature mismatch"
- 确认服务器时间同步（NTP）
- Access Key / Secret Key 复制时无多余空格
- 确认签名算法版本（v1 / v2 按上游要求选）
上游套餐下架导致开通失败
OpenIDCS 定时刷新套餐，一旦检测上游下架会把对外套餐置为 不可售 状态，避免客户下错单。手动可点 同步资源。
VNC URL 访问空白？
上游返回的 console URL 有时效（常见 5~30 分钟），客户每次点击 VNC，OpenIDCS 会重新向上游换取新 URL。
客户 IP 显示为内网？
部分套餐是 NAT VPS（共享出口），OpenIDCS 会自动同步上游返回的 公网 IP + 端口范围，显示在客户区。
🌐 延伸：多上游聚合售卖
您可以把 青州云 + 小黑云 + 自建 LXD/Proxmox 全部添加到同一个 OpenIDCS 里：
OpenIDCS (统一管理面板 + 统一 API)
├─ 自建 LXD 集群（低成本批量小 VPS）
├─ 自建 Proxmox（高配 KVM）
├─ 青州云（上游代理 1）
└─ 小黑云（上游代理 2）客户看到的是一个品牌 / 一份套餐表，底层自动路由到最合适的资源池。
👉 相关：FSPlugins 总览 · SwapIDC 集成 · 魔方财务集成 · 青州云 / 小黑云部署