上游供应商对接
机器从上游开出来，前提是供应商记录、凭据与商品绑定三样都配好。本文说明入口、三种供应商协议怎么选、凭据填什么、连通性怎么自检，以及开通失败时先看哪里。
1. 后台入口
| 页面 | 路径 | 权限 |
|---|---|---|
| 上游提供商 | 产品配置 → 上游供应 → 上游提供商 | supplier.list / supplier.detail |
| 上游开通插件 | 系统设置 → 集成插件 → 上游开通 | 列表 integration_plugin.view；安装/启停 integration_plugin.manage；测试 integration_plugin.test |
| 商品管理 | 产品配置 → 商品管理 → 商品管理 | product.list / product.manage |
| 服务实例 | 服务管理 → 服务实例 | 服务相关权限 |
| 上传/清理日志 | 日志中心 → 日志管理 → 上传/清理日志 | log.list |
supplier.manage 才能新增/修改/删除供应商，supplier.sync 才能跑同步任务与批量对接，supplier.secret_reveal 才能明文查看已保存的凭据（10 次/分钟限流并写操作日志）。
2. 可用的上游协议
供应商表单的字段由提供商类型决定，不是每个类型都一样。当前可选项：
| 提供商类型 | provider_key | 凭据字段 | 协议说明 |
|---|---|---|---|
| 主机面板接口 | hosting_panel_api | api_url 接口地址、api_username 接口账号、api_key 接口密钥 | 通用主机面板协议，核心内置，不需要装插件 |
| ZJMF 财务接口 | zjmf_finance_api | 同样走上面三项凭据（该插件不声明自定义表单字段） | 对接魔方财务上游，需启用 zjmf_finance 插件 |
| 康乐虚拟主机 | kanghostx | 接口地址填面板根地址，API 密钥填 accesshash | Kangle WHM API，需启用 kanghostx 插件 |
| TuraIDC 开放接口 | tura_open_api | 接口地址填上游站点根地址，API 密钥填上游「API 密钥」页创建的完整密钥（仅创建时展示一次） | 纯自有协议，不走 ZJMF 兼容链路，需启用 tura_open_api 插件 |
| Demo 上游服务 | demo_servers | 无真实凭据，只模拟上游 | 仅用于验证流程 |
供货商类型下拉框的候选来自「插件注册表 + 核心驱动」，未安装的插件不会出现在下拉里；选了却保存不了会报参数校验错误。选不到某个类型时先去「上游开通」插件页安装并启用它。
hosting_panel_api（主机面板接口）是内置驱动，但下拉框走的是插件注册表，需要有对应的上游插件记录才会出现。如果你确认代码里有这个驱动、下拉里却没有，先在「上游开通」页点「扫描插件」；仍然没有说明该驱动在当前部署里没有可注册的插件条目（具体注册方式未在代码中确认）。
zjmf_finance 插件的配置页只有一个只读的「上游标识」zjmf_finance_api，并明确要求供应商绑定的 provider_key 保持该值、不要别名为 hosting_panel_api——填成别名会导致走错适配链路。
tura_open_api 要求上游密钥具备 products/orders/services/finance 读写权限且上游账户余额充足；密钥只在上游创建时展示一次，丢了只能重建。
3. 新增供应商
- 「上游提供商」页点「添加提供商」，先选「插件提供商」（即上面的提供商类型）。
- 「接口名称」是只在本站显示的供应商名字。
- 按选中的类型出现对应凭据字段：必填项留空无法保存；已保存过的密钥字段会显示「已配置」，编辑时留空表示保持原值而不是清空。
- 「上游余额告警」区：
low_balance_alert_enabled开关与low_balance_threshold阈值。阈值留空表示沿用默认值 20，不等于关闭提醒。 - 保存后供应商以启用状态（
status=1）存在；用它行内的启用/停用按钮切换，停用不会影响已开通的服务，但新的开通不会走它。
接口地址有严格校验：必须是 http 或 https 且带主机名，非 local 环境强制 HTTPS，禁止带账号密码，禁止 localhost 与 .localhost 结尾的域名，禁止内网与保留 IP。另外可以用 HOSTING_PANEL_API_ALLOWED_HOSTS（逗号分隔）把允许的域名收紧成白名单，一旦设置，不在名单内的域名会被拒。
凭据存储的实质是 supplier_plugin_bindings 行：base_url、account_name、API 密钥，加上插件自定义的 provider_config。同一供应商下可能有多条绑定（例如同时对接两个不同的上游），「批量导入/对接」里指定的 supplier_id + 来源组合就是用来区分它们的。
4. 商品怎么连到上游
凭据配好不等于能卖，还要把本地商品与上游商品绑上：
- 打开商品编辑页，在供应商下拉里选这个供应商，再同步或选择上游商品；选择时会实时拉取上游商品列表，拉不到就说明凭据或网络有问题。
- 或者在「上游提供商」页用供应商卡片上的「批量导入/对接」：先刷新上游商品树，勾选要对接的远端商品与本地的目标分类，再执行。对话框里有三个选项：「默认上架」「自动开通」「同步配置项」，分别决定导入后的商品状态、是否走自动开通、是否把上游的配置项模板一并带过来。
- 上游商品的配置项模板可以按单个商品查看（卡片动作里的
config-template），用于核对参数是否齐全。
批量对接需要 supplier.sync；没有该权限时按钮点了只会提示，不会静默失败。
5. 自检与验证
按顺序检查，每一步都能定位到一层：
- 上游开通插件页的「检测」（
health_check）：校验清单与必需配置、实例化入口类，回答「插件能不能正常加载」；不联系上游。 - 上游开通插件页的「连接测试」：解析插件声明的第一个能力，验证插件在运行时能取到。
- 供应商卡片上的「同步余额」：真正请求上游并刷新「上游余额 / 最近更新时间」。余额一直是
-且按钮灰着（提示「接口配置不完整，暂时无法同步余额」），说明api_url、api_username、api_key有缺失。 - 供应商卡片上的「批量导入/对接」：能拉到上游商品树，说明凭据、HTTPS、域名白名单与网络全部打通。
- 用一笔真实小额订单走开通，然后到「服务实例」看状态，到「上传/清理日志」「工单推送日志」看上游交互记录。
# 后端到上游的网络连通性：上游调用不做 SSL 校验，但网络与域名白名单仍会挡住请求
curl -sS -o /dev/null -w '%{http_code}\n' --max-time 10 https://你的上游域名/上面这条只是确认网络可达，真正的接口鉴权要看第 3、4 步的结果。
6. 排障
- 下拉里没有想要的提供商类型：对应插件没安装或没启用，先去「上游开通」插件页处理。
- 保存报「上游接口地址必须使用 HTTPS」：非 local 环境强制 HTTPS，纯 HTTP 上游要么改域名证书，要么在本地联调环境验证。
- 报「上游接口域名不在允许范围内」：
HOSTING_PANEL_API_ALLOWED_HOSTS设了白名单，把上游域名加进去或清空该变量。 - 余额同步失败：先看是网络、域名白名单还是凭据问题——错误信息由
ProviderErrorMapper统一成中文，会写明是「接口暂时不可用」还是业务错误。 - 订单支付了但机器没开出来：新购与续费在支付回调里同步履约，同步失败才回退
provision队列由每分钟心跳重试。先看服务实例的最近一次开通尝试记录，再看队列是否在跑（见部署与调度）。 - 供应商停用后老服务受影响吗：停用只影响后续开通路由，已开通服务仍可管理；但状态同步类定时任务不会再从它拉数据。