版本 2.4.8 · 最新
套餐 packages
可售卖的基础套餐,定义流量、带宽、域名数等额度与价格。
点击任一接口,右侧显示对应的调用示例。
套餐鉴权: 仅管理员8 个接口
鉴权
请求头带 X-API-Key(在「API 密钥」页开通,密钥只在开通时显示一次);也可用登录得到的 Authorization: Bearer 令牌。
X-API-Key
鉴权失败回 401;无权回 403(code 为 insufficient_scope 等)。
约定
分页参数 page(从 1 起)、page_size;排序 sort=字段 或 -字段。
时间一律 RFC 3339(UTC);金额单位为分。
写操作成功回 200/201/204;重复提交按资源唯一键回 409。
GET
/api/v2/packages列出套餐
鉴权: 仅管理员
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
page | integer | 页码,从 1 开始。 |
page_size | integer | 每页条数。 |
sort | string | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
POST
/api/v2/packages创建套餐
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
backup_group_id | integer | 备用线路分组;null = 没有 |
bandwidth_mbps | integer | 带宽 Mbps,-1 不限 |
buy_limit | integer | 每租户最多持有几份,-1 不限 |
cname_domain_id | integer | 接入根域(CNAME 域名);null = 套餐不绑线路 |
cname_host_suffix | string | 新生成主机记录的后缀;空 = 只有 8 位随机名 |
cname_mode | PackageCnameMode | CNAME 模式:site = 按站点生成(每个站点/四层转发各一个接入名);package = 按套餐生成(已售套餐下的站点/四层转发共用一个接入名)。 |
connections | integer | 并发连接数,-1 不限 |
custom_cc_rule | boolean | 可自定义 CC 规则 |
des | string | 备注说明 |
domains | integer | 域名数(IP 站每站占 1),-1 不限 |
enabled | boolean | 是否启用 |
expected_updated_at | string | 乐观锁:修改时带上读到的 updated_at,与当前不一致则 409 package_changed、不保存;不带不校验。创建时忽略。 |
featured | boolean | 主推(全站至多一个;须设了档位、上架、不限定用户、没设停售时间)。 |
group_ids | integer[] | 所属套餐分组 |
http_ports | integer | HTTP/HTTPS 非标端口数(80/443 之外),-1 不限 |
ip_num | integer | 可选 IP 数(「我的 IP」),-1 不限 |
ip_pool_id | integer | 开通 IP 站点用的 IP 池(IP 产品线);null = 不开通 |
ip_site | boolean | 开放 IP 网站:true 才能新建 IP 网站、选新 IP;为 true 时须配 IP 池。关掉不清池、可选 IP 数、端口数与已选 IP;存量套餐为 false(升级时在用 IP 网站的套餐置 true) |
ip_site_port | integer | IP 站端口数:套餐下全部 IP 站点去重后的端口个数(含 80/443),-1 不限;IP 站端口不占非标端口数 |
l2 | boolean | 含分层回源(付费项 l2 的租户开关):租户还要主控授权的分层回源已开通,才能给网站打开分层回源、节点才按它回源;存量套餐为 false(升级时已开分层回源的租户,其已售套餐置 true) |
name必填 | string | 名称 |
node_group_id | integer | 主线路分组;null = 套餐不绑线路 |
origin_ip_limit | string[] | 允许的源站 IP/网段;空 = 不限。非空时该套餐下站点的源站须落在其中,域名源站不许 |
owners | integer[] | 限定可购买的租户 id;空 = 不限 |
price_month_cents必填 | integer | 月价,分 |
price_quarter_cents必填 | integer | 季价,分 |
price_year_cents必填 | integer | 年价,分 |
prices | PackagePrice[] | 分币种价目;须含基准币一行(mode=base,价 = price_*_cents)。mode=manual 用固定价,mode=auto 由基准价按汇率现算(.99 取整只用于标价);读出时 auto 行带当前折算价。写入不带 prices 则非基准行不动。套餐目录(/package-catalog)按购买口径出:缺行按 auto 现算补,汇率未就绪的币不出行;管理端只出存行。 |
region_id | integer | 区域;null = 套餐不绑线路 |
renew_before_days | integer | 到期前几天内才许续费,-1 不限 |
require_verified | boolean | 须实名认证才能购买 |
sale_until | string | 过了此刻不再出售;不给/null = 不限 |
sort | integer | 排序值(小的在前)。 |
stream_ports | integer | 四层转发端口数,-1 不限 |
tier | integer | 购买页档位,0 = 不设,1-4 = 第几档;大于 0 时全站唯一。 |
traffic_gb | integer | 每计费周期流量 GB,-1 不限 |
waf_enhanced | boolean | 含 WAF 增强(付费项 waf_enhanced 的租户开关):租户还要主控授权的 WAF 增强未降级才能用标准/严格等级、大屏、Bot 深度、防篡改等;存量套餐为 false |
websocket | boolean | 可开 WebSocket |
POST
/api/v2/packages/batch-enable批量启用或禁用套餐
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
enabled必填 | boolean | 是否启用 |
ids必填 | integer[] | 要改的对象 id,至多 100 个。 |
GET
/api/v2/packages/{id}获取套餐
鉴权: 仅管理员
PUT
/api/v2/packages/{id}修改套餐
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
backup_group_id | integer | 备用线路分组;null = 没有 |
bandwidth_mbps | integer | 带宽 Mbps,-1 不限 |
buy_limit | integer | 每租户最多持有几份,-1 不限 |
cname_domain_id | integer | 接入根域(CNAME 域名);null = 套餐不绑线路 |
cname_host_suffix | string | 新生成主机记录的后缀;空 = 只有 8 位随机名 |
cname_mode | PackageCnameMode | CNAME 模式:site = 按站点生成(每个站点/四层转发各一个接入名);package = 按套餐生成(已售套餐下的站点/四层转发共用一个接入名)。 |
connections | integer | 并发连接数,-1 不限 |
custom_cc_rule | boolean | 可自定义 CC 规则 |
des | string | 备注说明 |
domains | integer | 域名数(IP 站每站占 1),-1 不限 |
enabled | boolean | 是否启用 |
expected_updated_at | string | 乐观锁:修改时带上读到的 updated_at,与当前不一致则 409 package_changed、不保存;不带不校验。创建时忽略。 |
featured | boolean | 主推(全站至多一个;须设了档位、上架、不限定用户、没设停售时间)。 |
group_ids | integer[] | 所属套餐分组 |
http_ports | integer | HTTP/HTTPS 非标端口数(80/443 之外),-1 不限 |
ip_num | integer | 可选 IP 数(「我的 IP」),-1 不限 |
ip_pool_id | integer | 开通 IP 站点用的 IP 池(IP 产品线);null = 不开通 |
ip_site | boolean | 开放 IP 网站:true 才能新建 IP 网站、选新 IP;为 true 时须配 IP 池。关掉不清池、可选 IP 数、端口数与已选 IP;存量套餐为 false(升级时在用 IP 网站的套餐置 true) |
ip_site_port | integer | IP 站端口数:套餐下全部 IP 站点去重后的端口个数(含 80/443),-1 不限;IP 站端口不占非标端口数 |
l2 | boolean | 含分层回源(付费项 l2 的租户开关):租户还要主控授权的分层回源已开通,才能给网站打开分层回源、节点才按它回源;存量套餐为 false(升级时已开分层回源的租户,其已售套餐置 true) |
name必填 | string | 名称 |
node_group_id | integer | 主线路分组;null = 套餐不绑线路 |
origin_ip_limit | string[] | 允许的源站 IP/网段;空 = 不限。非空时该套餐下站点的源站须落在其中,域名源站不许 |
owners | integer[] | 限定可购买的租户 id;空 = 不限 |
price_month_cents必填 | integer | 月价,分 |
price_quarter_cents必填 | integer | 季价,分 |
price_year_cents必填 | integer | 年价,分 |
prices | PackagePrice[] | 分币种价目;须含基准币一行(mode=base,价 = price_*_cents)。mode=manual 用固定价,mode=auto 由基准价按汇率现算(.99 取整只用于标价);读出时 auto 行带当前折算价。写入不带 prices 则非基准行不动。套餐目录(/package-catalog)按购买口径出:缺行按 auto 现算补,汇率未就绪的币不出行;管理端只出存行。 |
region_id | integer | 区域;null = 套餐不绑线路 |
renew_before_days | integer | 到期前几天内才许续费,-1 不限 |
require_verified | boolean | 须实名认证才能购买 |
sale_until | string | 过了此刻不再出售;不给/null = 不限 |
sort | integer | 排序值(小的在前)。 |
stream_ports | integer | 四层转发端口数,-1 不限 |
tier | integer | 购买页档位,0 = 不设,1-4 = 第几档;大于 0 时全站唯一。 |
traffic_gb | integer | 每计费周期流量 GB,-1 不限 |
waf_enhanced | boolean | 含 WAF 增强(付费项 waf_enhanced 的租户开关):租户还要主控授权的 WAF 增强未降级才能用标准/严格等级、大屏、Bot 深度、防篡改等;存量套餐为 false |
websocket | boolean | 可开 WebSocket |
DELETE
/api/v2/packages/{id}删除套餐
鉴权: 仅管理员
PUT
/api/v2/packages/{id}/groups修改套餐的分组归属
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
group_ids必填 | integer[] | 所属套餐分组 |
POST
/api/v2/packages/{id}/syncs同步基础套餐到已购套餐
鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 说明 |
|---|---|---|
items必填 | PackageSyncField[] | 要同步的字段 |
套餐对象
| 字段 | 类型 | 说明 |
|---|---|---|
backup_group_id | integer | 备用线路分组;null = 没有 |
bandwidth_mbps | integer | 带宽 Mbps,-1 不限 |
buy_limit | integer | 每租户最多持有几份,-1 不限 |
cname_domain_id | integer | 接入根域(CNAME 域名);null = 套餐不绑线路 |
cname_host_suffix | string | 新生成主机记录的后缀;空 = 只有 8 位随机名 |
cname_mode | PackageCnameMode | CNAME 模式:site = 按站点生成(每个站点/四层转发各一个接入名);package = 按套餐生成(已售套餐下的站点/四层转发共用一个接入名)。 |
connections | integer | 并发连接数,-1 不限 |
created_at | string | 创建时间 |
custom_cc_rule | boolean | 可自定义 CC 规则 |
des | string | 备注说明 |
domains | integer | 域名数(IP 站每站占 1),-1 不限 |
enabled | boolean | 是否启用 |
errors | FieldError[] | 没改的逐条原因;field 为 /ids/<下标>,code 同单条修改接口(not_found、readonly 等)。 |
expected_updated_at | string | 乐观锁:修改时带上读到的 updated_at,与当前不一致则 409 package_changed、不保存;不带不校验。创建时忽略。 |
featured | boolean | 主推(全站至多一个;须设了档位、上架、不限定用户、没设停售时间)。 |
group_ids | integer[] | 所属套餐分组 |
http_ports | integer | HTTP/HTTPS 非标端口数(80/443 之外),-1 不限 |
id | integer | 记录 ID |
ids必填 | integer[] | 要改的对象 id,至多 100 个。 |
ip_num | integer | 可选 IP 数(「我的 IP」),-1 不限 |
ip_pool_id | integer | 开通 IP 站点用的 IP 池(IP 产品线);null = 不开通 |
ip_site | boolean | 开放 IP 网站:true 才能新建 IP 网站、选新 IP;为 true 时须配 IP 池。关掉不清池、可选 IP 数、端口数与已选 IP;存量套餐为 false(升级时在用 IP 网站的套餐置 true) |
ip_site_port | integer | IP 站端口数:套餐下全部 IP 站点去重后的端口个数(含 80/443),-1 不限;IP 站端口不占非标端口数 |
items必填 | PackageSyncField[] | 要同步的字段 |
l2 | boolean | 含分层回源(付费项 l2 的租户开关):租户还要主控授权的分层回源已开通,才能给网站打开分层回源、节点才按它回源;存量套餐为 false(升级时已开分层回源的租户,其已售套餐置 true) |
name | string | 名称 |
node_group_id | integer | 主线路分组;null = 套餐不绑线路 |
origin_ip_limit | string[] | 允许的源站 IP/网段;空 = 不限。非空时该套餐下站点的源站须落在其中,域名源站不许 |
owners | integer[] | 限定可购买的租户 id;空 = 不限 |
price_month_cents | integer | 月价,分 |
price_quarter_cents | integer | 季价,分 |
price_year_cents | integer | 年价,分 |
prices | PackagePrice[] | 分币种价目;须含基准币一行(mode=base,价 = price_*_cents)。mode=manual 用固定价,mode=auto 由基准价按汇率现算(.99 取整只用于标价);读出时 auto 行带当前折算价。写入不带 prices 则非基准行不动。套餐目录(/package-catalog)按购买口径出:缺行按 auto 现算补,汇率未就绪的币不出行;管理端只出存行。 |
region_id | integer | 区域;null = 套餐不绑线路 |
renew_before_days | integer | 到期前几天内才许续费,-1 不限 |
replaced | PackageReplaced | 本次保存换下的别的套餐(套餐名);没换下就不给对应字段。 |
require_verified | boolean | 须实名认证才能购买 |
sale_until | string | 过了此刻不再出售;不给/null = 不限 |
skipped | integer | 不跟随或至少一个改动字段单独改过而跳过的个数(其余字段照常同步) |
skipped_ids | integer[] | 被跳过的已购套餐 id |
sold_count | integer | 已售份数(引用本套餐的已购套餐数);只在管理员列表与详情里给,购买目录不给。 |
sort | integer | 排序值(小的在前)。 |
stream_ports | integer | 四层转发端口数,-1 不限 |
sync | PackageSyncResult | 同步结果。 |
synced | integer | 已同步的已购套餐数(自动同步时 = 本次改动的字段全部同步了的个数) |
tier | integer | 购买页档位,0 = 不设,1-4 = 第几档;大于 0 时全站唯一。 |
traffic_gb | integer | 每计费周期流量 GB,-1 不限 |
updated | integer[] | 已改好的 id(含本来就是目标状态的),按请求顺序。 |
updated_at | string | 更新时间 |
waf_enhanced | boolean | 含 WAF 增强(付费项 waf_enhanced 的租户开关):租户还要主控授权的 WAF 增强未降级才能用标准/严格等级、大屏、Bot 深度、防篡改等;存量套餐为 false |
websocket | boolean | 可开 WebSocket |
返回与错误
成功直接回资源 JSON(HTTP 2xx);失败回 application/problem+json(code、detail,校验失败带 errors);列表为 items + total。
成功
{
"id": 1,
"name": "example"
}列表
{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}失败
{
"code": "validation_failed",
"detail": "请求参数不合法",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name 必填"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}