IntegrationService

插件系统与供应商集成的核心服务，负责插件定义管理、接口实例 CRUD、供应商询价/下单、上游实例同步和余额查询。是 Admin UI 插件管理页和 Upstream 页的主要后端服务。

RPC 列表

RPC	描述	权限
ListProviders	列出所有 Provider 插件接口	admin
ListGateways	列出所有 Gateway 插件接口	admin
ListNotifiers	列出所有 Notifier 插件接口	admin
ListPlugins	列出所有插件定义（.rn 文件）	admin
GetPlugin	获取单个插件定义	admin
ListPluginInterfaces	列出所有插件接口实例	admin
GetPluginInterface	获取单个接口实例详情	admin
CreatePluginInterface	创建新的接口实例	admin
UpdatePluginInterface	更新接口实例配置	admin
TogglePluginInterface	启用/禁用接口实例	admin
DeletePluginInterface	删除接口实例	admin
CheckPluginHealth	检查接口实例健康状态	admin
GetPluginAdminPage	获取插件管理嵌入页面 HTML	admin
CallPluginAction	调用插件自定义 action（admin panel bridge）	admin
RestartServer	重启服务器	admin
SyncProducts	从 Provider 接口同步商品	已认证
QueryPrice	向 Provider 询价	已认证
CreateUpstreamInstance	向上游 Provider 下单开通实例	已认证
GetInstanceStatus	查询上游实例状态	admin
SyncUpstreamInstances	从上游同步实例列表	admin
ImportUpstreamInstance	导入上游实例到本地	admin
GetUpstreamBalance	查询上游账户余额	admin

ListProviders

描述

列出所有已启用的 Provider 类型插件接口实例，含健康状态和规格模板。

Request — `EmptyRequest`

无字段。

Response — `ListProvidersResponse`

字段	类型	编号	描述
providers	repeated ProviderInfo	1	Provider 列表

ProviderInfo

字段	类型	编号	描述
interface_id	string	1	接口实例 ID
provider_name	string	2	提供者名称
provider_type	string	3	类型：`"upstream"` / `"first_party"`
is_healthy	bool	4	是否健康
spec_template	SpecTemplate	5	规格模板（含字段定义和分组）

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{}' \
  localhost:50051 rustbill.integration.IntegrationService/ListProviders

ListGateways

描述

列出所有已启用的 Gateway 类型插件接口实例。

Request — `EmptyRequest`

无字段。

Response — `ListGatewaysResponse`

字段	类型	编号	描述
gateways	repeated GatewayInfo	1	Gateway 列表

GatewayInfo

字段	类型	编号	描述
gateway_id	string	1	接口实例 ID
gateway_name	string	2	网关名称
is_healthy	bool	3	是否健康

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{}' \
  localhost:50051 rustbill.integration.IntegrationService/ListGateways

ListNotifiers

描述

列出所有已启用的 Notifier 类型插件接口实例。

Request — `EmptyRequest`

无字段。

Response — `ListNotifiersResponse`

字段	类型	编号	描述
notifiers	repeated NotifierInfo	1	Notifier 列表

NotifierInfo

字段	类型	编号	描述
channel_id	string	1	接口实例 ID
channel_name	string	2	渠道名称
is_healthy	bool	3	是否健康

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{}' \
  localhost:50051 rustbill.integration.IntegrationService/ListNotifiers

ListPlugins

描述

列出所有已扫描的插件定义（plugins 表记录，由 PluginScanner 自动同步自 plugins/*.rn 文件）。

Request — `ListPluginsRequest`

字段	类型	编号	必填	描述
plugin_type	string?	1	否	按类型过滤：`"first_party_provider"` / `"upstream_provider"` / `"gateway"` / `"notifier"`

Response — `ListPluginsResponse`

字段	类型	编号	描述
plugins	repeated PluginDef	1	插件定义列表

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"plugin_type":"gateway"}' \
  localhost:50051 rustbill.integration.IntegrationService/ListPlugins

GetPlugin

描述

获取单个插件定义详情。

Request — `GetPluginRequest`

字段	类型	编号	必填	描述
id	string	1	是	插件定义 ID（UUID）

Response — `GetPluginResponse`

字段	类型	编号	描述
plugin	PluginDef	1	插件定义

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"id":"0192a123-..."}' \
  localhost:50051 rustbill.integration.IntegrationService/GetPlugin

ListPluginInterfaces

描述

列出所有插件接口实例，可按类型过滤。

Request — `ListPluginInterfacesRequest`

字段	类型	编号	必填	描述
plugin_type	string?	1	否	按类型过滤

Response — `ListPluginInterfacesResponse`

字段	类型	编号	描述
interfaces	repeated PluginInterfaceInfo	1	接口实例列表

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"plugin_type":"first_party_provider"}' \
  localhost:50051 rustbill.integration.IntegrationService/ListPluginInterfaces

GetPluginInterface

描述

获取单个接口实例详情。

Request — `GetPluginInterfaceRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	接口实例 ID（UUID）

Response — `GetPluginInterfaceResponse`

字段	类型	编号	描述
interface	PluginInterfaceInfo	1	接口实例详情

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-..."}' \
  localhost:50051 rustbill.integration.IntegrationService/GetPluginInterface

CreatePluginInterface

描述

基于插件定义创建新的接口实例。服务端自动从插件脚本提取 config_schema() 填充初始 config_schema 字段。

Request — `CreatePluginInterfaceRequest`

字段	类型	编号	必填	描述
plugin_def_id	string	1	是	插件定义 ID（UUID）
display_name	string	2	是	显示名称（同一插件下唯一）
config_json	string	3	是	初始配置 JSON 字符串

Response — `CreatePluginInterfaceResponse`

字段	类型	编号	描述
interface	PluginInterfaceInfo	1	创建的接口实例

错误码

错误	说明
NotFound	插件定义不存在
AlreadyExists	同插件下 display_name 重复
InvalidArgument	config_json 格式无效
PermissionDenied	非 admin 用户

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"plugin_def_id":"0192a123-...","display_name":"易支付-生产","config_json":"{\"api_url\":\"https://pay.example.com\",\"key\":\"xxx\"}"}' \
  localhost:50051 rustbill.integration.IntegrationService/CreatePluginInterface

UpdatePluginInterface

描述

更新接口实例的配置或显示名称。更新 config_json 后自动 evict 脚本缓存，下次调用热加载。

Request — `UpdatePluginInterfaceRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	接口实例 ID（UUID）
config_json	string?	2	否	新配置 JSON
display_name	string?	3	否	新显示名称

Response — `UpdatePluginInterfaceResponse`

字段	类型	编号	描述
interface	PluginInterfaceInfo	1	更新后的接口实例

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-...","config_json":"{\"api_url\":\"https://pay2.example.com\",\"key\":\"yyy\"}"}' \
  localhost:50051 rustbill.integration.IntegrationService/UpdatePluginInterface

TogglePluginInterface

描述

启用或禁用接口实例。

Request — `TogglePluginInterfaceRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	接口实例 ID（UUID）
enable	bool	2	是	true=启用, false=禁用

Response — `TogglePluginInterfaceResponse`

字段	类型	编号	描述
interface	PluginInterfaceInfo	1	更新后的接口实例

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-...","enable":true}' \
  localhost:50051 rustbill.integration.IntegrationService/TogglePluginInterface

DeletePluginInterface

描述

删除接口实例。

Request — `DeletePluginInterfaceRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	接口实例 ID（UUID）

Response — `DeletePluginInterfaceResponse`

无字段。

错误码

错误	说明
NotFound	接口实例不存在
PermissionDenied	非 admin 用户

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-..."}' \
  localhost:50051 rustbill.integration.IntegrationService/DeletePluginInterface

CheckPluginHealth

描述

检查指定接口实例的健康状态。调用插件脚本的 health_check() 函数。

Request — `CheckPluginHealthRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	接口实例 ID（UUID）

Response — `CheckPluginHealthResponse`

字段	类型	编号	描述
is_healthy	bool	1	是否健康
error	string?	2	错误信息（不健康时）
checked_at	string	3	检查时间（RFC3339）

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-..."}' \
  localhost:50051 rustbill.integration.IntegrationService/CheckPluginHealth

GetPluginAdminPage

描述

获取插件自定义管理页面的 HTML 内容，在 Admin UI 中以 iframe 嵌入渲染。

Request — `GetPluginAdminPageRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	接口实例 ID（UUID）

Response — `GetPluginAdminPageResponse`

字段	类型	编号	描述
html_content	string	1	HTML 页面内容
title	string	2	页面标题

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-..."}' \
  localhost:50051 rustbill.integration.IntegrationService/GetPluginAdminPage

CallPluginAction

描述

在插件管理页面中调用插件的自定义 action 函数（通过 postMessage bridge）。function 名称为插件脚本中的函数名，args_json 自动合并到 config 中传入。

Request — `CallPluginActionRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	接口实例 ID（UUID）
function	string	2	是	要调用的函数名（如 `"admin_list_instances"`）
args_json	string	3	是	JSON 编码的参数（合并入 config）

Response — `CallPluginActionResponse`

字段	类型	编号	描述
result_json	string	1	JSON 编码的返回值

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-...","function":"admin_list_instances","args_json":"{}"}' \
  localhost:50051 rustbill.integration.IntegrationService/CallPluginAction

RestartServer

描述

重启 RustBill 服务器（执行 graceful shutdown 后由 systemd/进程管理器重新拉起）。

Request — `EmptyRequest`

无字段。

Response — `EmptyResponse`

无字段。

错误码

错误	说明
PermissionDenied	非 admin 用户

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{}' \
  localhost:50051 rustbill.integration.IntegrationService/RestartServer

SyncProducts

描述

从指定的 Provider 接口同步商品列表到本地。调用 Provider 插件的 sync_products() 函数。

详情同 ProductService 中的 SyncProducts。

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-..."}' \
  localhost:50051 rustbill.integration.IntegrationService/SyncProducts

QueryPrice

描述

向 Provider 插件查询指定规格的价格。调用 Provider 插件的 query_price() 函数。

Request — `QueryPriceRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	Provider 接口 ID（UUID）
cpu_cores	uint32	2	是	CPU 核心数
memory_gb	uint32	3	是	内存（GB）
disk_gb	uint32	4	是	磁盘（GB）
bandwidth_mbps	uint32	5	是	带宽（Mbps）
region	string	6	是	地域
os	string	7	是	操作系统
extra_specs	map<string,string>	8	否	扩展规格

Response — `QueryPriceResponse`

字段	类型	编号	描述
amount	string	1	价格（字符串金额）
currency	string	2	货币代码
billing_cycle	string	3	计费周期

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-...","cpu_cores":2,"memory_gb":4,"disk_gb":50,"bandwidth_mbps":100,"region":"us-west","os":"ubuntu-22.04"}' \
  localhost:50051 rustbill.integration.IntegrationService/QueryPrice

CreateUpstreamInstance

描述

向上游 Provider 下单创建实例。调用 Provider 插件的 create_instance() 函数。

Request — `UpstreamOrderRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	Provider 接口 ID（UUID）
server_spec	ServerSpec	2	是	服务器规格（引用 `rustbill.order.ServerSpec`）

Response — `UpstreamOrderResponse`

字段	类型	编号	描述
provider_instance_id	string	1	上游实例 ID
status	string	2	实例状态
ip_address	string	3	IP 地址

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-...","server_spec":{"cpu_cores":2,"memory_gb":4,"disk_gb":50,"bandwidth_mbps":100,"region":"us-west","os":"ubuntu-22.04"}}' \
  localhost:50051 rustbill.integration.IntegrationService/CreateUpstreamInstance

GetInstanceStatus

描述

查询上游 Provider 中指定实例的状态。

Request — `InstanceStatusRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	Provider 接口 ID（UUID）
instance_id	string	2	是	上游实例 ID

Response — `InstanceStatusResponse`

字段	类型	编号	描述
status	string	1	实例状态
ip_address	string	2	IP 地址

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-...","instance_id":"i-abc123"}' \
  localhost:50051 rustbill.integration.IntegrationService/GetInstanceStatus

SyncUpstreamInstances

描述

从上游 Provider 同步实例列表。调用 Provider 插件的 sync_upstream_instances() 函数。

Request — `SyncUpstreamInstancesRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	Provider 接口 ID（UUID）

Response — `SyncUpstreamInstancesResponse`

字段	类型	编号	描述
instances	repeated UpstreamInstanceItem	1	上游实例列表

UpstreamInstanceItem

字段	类型	编号	描述
instance_id	string	1	上游实例 ID
status	string	2	实例状态
ip_address	string	3	IP 地址
created_at	string	4	创建时间

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-..."}' \
  localhost:50051 rustbill.integration.IntegrationService/SyncUpstreamInstances

ImportUpstreamInstance

描述

将上游实例导入本地 instances 表，建立关联。

Request — `ImportUpstreamInstanceRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	Provider 接口 ID（UUID）
instance_id	string	2	是	上游实例 ID

Response — `ImportUpstreamInstanceResponse`

字段	类型	编号	描述
instance_id	string	1	本地实例 ID
status	string	2	实例状态
ip_address	string	3	IP 地址

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-...","instance_id":"i-abc123"}' \
  localhost:50051 rustbill.integration.IntegrationService/ImportUpstreamInstance

GetUpstreamBalance

描述

查询上游 Provider 的账户余额。调用 Provider 插件的 get_upstream_balance() 函数。

Request — `GetUpstreamBalanceRequest`

字段	类型	编号	必填	描述
interface_id	string	1	是	Provider 接口 ID（UUID）

Response — `GetUpstreamBalanceResponse`

字段	类型	编号	描述
balance	string	1	余额（字符串金额）
currency	string	2	货币代码

示例

grpcurl -plaintext -H "authorization: Bearer <token>" \
  -d '{"interface_id":"0192a123-..."}' \
  localhost:50051 rustbill.integration.IntegrationService/GetUpstreamBalance

公共类型

PluginDef

插件定义（plugins 表记录，由 PluginScanner 从 plugins/*.rn 文件扫描同步）。

字段	类型	编号	描述
id	string	1	插件定义 UUID
plugin_type	string	2	类型：`"first_party_provider"` / `"upstream_provider"` / `"gateway"` / `"notifier"`
plugin_id	string	3	插件标识符（如 `"incus"`, `"yipay"`, `"webhook"`）
has_admin_page	bool	4	是否有自定义管理页面（预计算列）
created_at	string	5	创建时间（RFC3339）
updated_at	string	6	更新时间（RFC3339）
version	string	7	插件版本号（semver，来自 `fn version()`，默认 `"0.0.0"`）

PluginInterfaceInfo

接口实例（plugin_interfaces 表记录，管理员通过 UI 创建和管理）。

字段	类型	编号	描述
id	string	1	接口实例 UUID
plugin_def_id	string	2	关联插件定义 ID（FK）
plugin_type	string	3	类型（反范式列）
plugin_id	string	4	插件标识符（反范式列）
display_name	string	5	显示名称
enabled	bool	6	是否启用
config_json	string	7	配置 JSON 字符串
config_schema	string	8	配置 JSON Schema（用于 UI 表单渲染）
created_at	string	9	创建时间（RFC3339）
updated_at	string	10	更新时间（RFC3339）
is_healthy	bool	11	是否健康
health_error	string?	12	健康检查错误信息
last_check_at	string?	13	最近一次健康检查时间
has_admin_page	bool	14	是否有管理页面
plugin_version	string	15	插件版本快照（创建时从父插件复制）

插件类型说明

类型	DB 值	说明
FirstPartyProvider	`first_party_provider`	自建资源（KVM, Incus）
UpstreamProvider	`upstream_provider`	上游分销（RustBill 上游）
PaymentGateway	`gateway`	支付网关（易支付, 银行转账）
Notifier	`notifier`	通知渠道（Webhook, Email）

Keyboard shortcuts

RustBill 文档