鸟不死鸟 CDN文档中心
快速接入 / 准备条件

准备条件

接入只需准备好以下 3 样东西。有疑问随时联系客服。

1 · 域名

  • 不限购买厂商,只要能修改 DNS 解析即可。
  • 支持单域名(domain.com、a.domain.com)和泛域名(*.domain.com)。
域名需满足
  • 在国内可正常访问。已被墙、被污染的域名,接入后仍然无法访问。
  • 个别地区被运营商拉黑或跳转反诈页面的域名,能否解决视情况而定,不做保证。

👉 接入前可用域名查询工具检查健康状况,并参考 《域名保护小技巧》。

2 · 源服务器 IP

你网站的真实服务器地址,需在国内可正常访问。被墙的 IP 接入后同样无法访问。

3 · 选择一个 CDN 套餐

  • 套餐区别只在 域名数量 和 流量额度和带宽大小,所有套餐节点质量完全一致。
  • 流量只统计出站流量。
准备就绪

三项就绪后,即可前往 开始接入。

快速接入 / 开始接入

开始接入

整个流程共 4 步,最快 5 分钟 完成。开始前请确认已满足准备条件。

全程在 控制台 内操作,请先登录。

添加网站

进入 网站管理 → 我的网站 → 新增,填写域名和源站 IP。多个域名用空格隔开,可一次性添加。

添加网站
网站管理 → 我的网站 → 新增
配置域名
输入域名及源站 IP

配置域名解析

网站添加成功后,系统会生成一个 CNAME 值。

生成 CNAME
等待生成 CNAME 值

到你的域名 DNS 服务商(如腾讯 DNSPod、阿里云)添加一条 CNAME 记录,指向该值。

添加域名解析
以腾讯 DNSPod 为例

回控制台核对,解析状态显示绿色对号即配置成功。

解析状态
解析状态为绿色对号即成功
注意

解析生效时间由域名服务商决定,快则几秒、慢则几小时,请耐心等待。

慎用 Cloudflare 等海外 DNS 解析根域名(@)

用 Cloudflare 或其他一些海外解析平台给根域名(@)做 CNAME 时,往往会触发 CNAME 拉平(CNAME Flattening / ALIAS):解析结果被提前解析成固定 IP。这样一来,国内访客本来应走到香港 CN2 高防节点,却可能被拉到美国等海外节点,访问会异常缓慢。

解决方法:

  • 方法一(推荐):根域名(@)不要直接 CNAME,改为 301 重定向到二级域名(如 www 或其他子域名),只给该二级域名做 CNAME。
  • 方法二:把 DNS 托管到腾讯云 DNSPod、阿里云解析等国内服务商;或在 gname.com、dynadot.com 等平台购买 / 解析域名——这些平台不会把 CNAME 拉平,根域名可正常指向不死鸟 CDN 的 CNAME。
慎用 Cloudflare 等海外 DNS 解析根域名(@)

用 Cloudflare 或其他一些海外解析平台给根域名(@)做 CNAME 时,往往会触发 CNAME 拉平(CNAME Flattening / ALIAS):解析结果被提前解析成固定 IP。这样一来,国内访客本来应走到香港 CN2 高防节点,却可能被拉到美国等海外节点,访问会异常缓慢。

解决方法:

  • 方法一(推荐):根域名(@)不要直接 CNAME,改为 301 重定向到二级域名(如 www 或其他子域名),只给该二级域名做 CNAME。
  • 方法二:把 DNS 托管到腾讯云 DNSPod、阿里云解析等国内服务商;或在 gname.com、dynadot.com 等平台购买 / 解析域名——这些平台不会把 CNAME 拉平,根域名可正常指向不死鸟 CDN 的 CNAME。

配置证书,开启 HTTPS

根据你是否已有证书,二选一:

情况 A:没有证书(推荐)

在控制台 一键申请 免费证书,平台自动续期、无需手动维护。

⚠️ 申请前需确保所有域名解析都已生效,否则无法签发。

勾选站点后点击申请证书
先勾选要申请证书的站点,再点击「申请证书」
选用证书
选用证书
签发失败怎么办

绝大多数是域名解析未正确配置导致。可在 网站管理 → 证书管理 查看状态;确认解析无误后,编辑证书切换签发机构再点「重签」。

情况 B:已有证书

前往 网站管理 → 证书管理,上传并选用你的证书。

上传证书
添加证书
选用证书
选用证书

最后:打开 HTTPS 开关

开启 HTTPS
开启 HTTPS

完成

域名已成功接入 CDN!

以上为快速接入配置,缓存、防御等均使用平台预设,开箱即用。如有特殊需求,可在控制台按需调整。


接入完成后:建议开启 CC 防护

重要提醒

网站接入后,防护默认为关闭。一旦遇到突发强力 CC 攻击,源站可能因扛不住海量请求而宕机。建议接入完成后开启自动切换策略,让平台在攻击来临时自动启用人机验证。

推荐配置如下:

  • 开启自动切换:阈值一般设 50 ~ 200 即可(按你的正常流量大小调整)。
  • 提升策略选择 点击验证 / 滑块验证 / 验证码 之一。当请求量超过阈值时,访客会被要求完成相应验证,挡住攻击流量。
CC 参考配置
CC 自动切换策略参考配置

CC 规则不固定,可按网站实际需求自行调整。更多说明见 《自定义 CC 规则》。

常见问题 / 页面访问 50x 错误

页面访问 50x 错误

50x 基本都是回源异常。按下面顺序逐一排查,绝大多数能快速定位。

1 · 源站本身是否可访问

先在未套 CDN 的情况下直接访问源站。如果源服务本身就打不开,套上 CDN 当然也访问不了——先把源站修好。

2 · CDN 配置还没生效

概率较小,等几分钟再试。

3 · 源站拦截了 CDN 回源(概率最大)

如果用了宝塔等控制面板并开了防御,会挡住 CDN 回源。套 CDN 后,宝塔的基础防御可以关闭,防御工作交给 CDN 承担;如需保留防御,则要给 CDN 回源 IP 开白名单。

详见 《宝塔部署接入须知》。未使用宝塔的,请排查服务器防火墙是否拦截了 CDN 回源。

4 · IP 被误封

前往 网站管理 → 监控统计 → 黑名单 IP,查看是否有本机 IP 在内。若在,则是误封,先解除该 IP。这说明当前防御规则不适合你的业务,建议切换为 默认-宽松,提升-50-旋转图片,可满足绝大部分需求。

5 · IP 连通性异常

部分小厂商的低质量服务器 IP 容易进运营商黑名单,被拉黑后会不定时无法连通,需等待恢复。

常见问题 / 宝塔部署接入须知

宝塔部署接入须知

同样适用于其他类宝塔的面板控制工具。接入前请逐项检查。

1 · 检查域名是否绑定

宝塔站点支持通配符绑定,确保绑定的域名包含了在 CDN 平台添加的域名。

2 · 检查站点是否开启 SSL

若宝塔未配置强制 HTTPS 回源,此步可跳过。若宝塔配置了 SSL 且强制 HTTPS 访问,则 CDN 需走 HTTPS 443 回源,否则会报 50x;443 回源需在 CDN 平台配置证书。

强烈推荐

关闭宝塔的「强制 SSL 访问」,让 CDN 走 80 端口回源。80 回源比 443 更快、配置项更少。证书安全由 CDN 承担,可在平台一键配置并自动续期。

3 · 检查其他安全限制项

  • 宝塔的基础安全项(访问限制、流量限制等)都可以关闭,交给 CDN 平台管控。在宝塔中配置可能影响 CDN 回源。这些项若未改动过,默认就是关闭的。
  • 如需保留防御,则要让 CDN 通过白名单正常回源。

4 · 是否对配置文件做过特殊处理

某些服务会改动 Nginx 配置文件。若套 CDN 后无法访问,也需排查此处。未改动过则默认没问题。

常见问题 / 页面打开慢 / 白屏

页面打开慢 / 长时间白屏

套上 CDN 后速度一般不会变慢。如果慢或一直加载中,多半是某处出了问题。

最常见的原因是加载第三方资源时等待过久,导致页面渲染卡住。例如下面这个案例:

白屏案例
jquery、layer 加载 4~7 秒后失败,页面白屏

案例中 jquery、layer 加载失败,而页面渲染依赖这两个库,于是白屏。可单独访问这些库的源地址,大概率也是失败或很慢。

解决办法:更换第三方库的源

案例原本使用 Staticfile 源:

  • cdn.staticfile.org/layer/3.1.1/layer.min.js
  • cdn.staticfile.org/jquery/1.12.4/jquery.min.js

换成 360 的源试试:

  • lib.baomitu.com/jquery/1.12.4/jquery.min.js
  • lib.baomitu.com/layer/3.1.1/layer.min.js

已知 Staticfile、BootCDN 存在访问慢的情况,请按需更换合适的源。若担心第三方不稳定,可把工具库放进项目中加载(public 静态资源方式)。

如仍无法解决,请联系客服协助。

常见问题 / 回调被拦截

无法接收回调请求(如支付回调)

回调是第三方服务合法请求你的服务器。CDN 默认可能拦截这类请求,需要手动放行、告诉 CDN 它是合法的。

前往 我的网站 → 安全配置 添加过滤规则

添加安全过滤规则
我的网站 → 安全配置 → 添加过滤规则

举例一:放行支付平台的通知回调

放行举例
对支付回调请求做放行处理

举例二:已知请求方 IP,直接开白名单

IP 白名单放行
按请求方 IP 开白名单放行

匹配条件很多,原理都一样——按你的实际需求配置即可。

常见问题 / 实时传输 / WebSocket

网站实时传输功能失效

很多场景需要实时传输,例如镜像站中的 AI 聊天。实时传输(含流式传输)需要开启 WebSocket。

开启 WebSocket

开启 WebSocket
在站点配置中开启 WebSocket

开了 WebSocket 还是不行?

每个站点的技术实现不同,开了不一定立刻生效。检查缓存内容,移除 JS 缓存,一般即可解决。

常见问题 / 提示"信息不安全"

浏览器提示"您要提交的信息不安全"

访问时浏览器提示此信息,需手动点击确认后才能继续。

浏览器提示
浏览器安全提示
原因与处理

这是站点内存在 HTTPS 向 HTTP 跳转 导致,触发了浏览器的安全机制。需在站点内处理好全程 HTTPS 访问,避免回退到 HTTP。

知识分享 / 自定义 CC 规则

自定义 CC 规则

平台可抵御绝大多数 CC 攻击。规则不固定,按网站需求自行配置。

参考配置

CC 参考配置
CC 规则参考配置
建议

正常添加网站后防护默认关闭,遇到突发强力 CC 攻击会导致源站被打宕机。建议开启自动切换(阈值一般 50 即可),并提升到「点击验证 / 滑块验证 / 旋转图片」之一。当请求量超过阈值时,访客会被要求执行所设规则。

知识分享 / 域名保护小技巧

关于域名保护的一些小技巧

域名是网站的门面,也是最容易被攻击的环节,保护好域名至关重要。

注:国内备案域名出现以下情况的概率很低,多见于境外 IP。

域名异常分为被墙、被污染、被劫持、被运营商禁用等多种行为。下面介绍最常见的几种:

被墙

域名被墙必有原因,被拉入 GFW 黑名单后放出的可能性极低。首先确认站点内容不存在非法内容。

预防

在确认无非法内容的前提下,可多备域名用引导页分发,或从技术上彻底拦死爬虫。也可做 301 跳转,将旧域名永久跳转到新域名(有专门服务,价格较高)。

被污染

与站点内容无关。表现为:查询自己域名解析时出现一堆陌生的乱解析记录,访问到的也不是自己的站点(通常是非法内容)。

预防

已知在 GoDaddy、Cloudflare 购买的域名风险较高(未列出的不代表一定安全)。如未购买其高级保护服务,强烈建议把 DNS 解析配置到 腾讯 DNSPod(推荐) 或阿里万网等国内大厂,默认自带防护。

被劫持

市面上有些"黑科技"号称可解决,未经实测。

预防

建议把 DNS 解析迁回国内,有条件的可购买高级服务并开启 DNSSEC。

被运营商禁用或劫持

较出名的是移动屏蔽("墙中墙",GFW 不墙但移动墙)。套 CDN 不一定能 100% 解决,判定过程很复杂,只能尝试。它和被墙一样分 IP 被墙与域名被墙,需先确认再想办法。地方运营商禁用(如某些地区电信常年无法访问)基本无解;某些地区短期解析到 0.0.0.0 或解析失败,多为当地运营商拦截,一般会恢复,可用网络拨测工具查看解析情况。

预防

做好反爬虫,保证站内无非法内容——运营商不会无缘无故禁用。

跳转反诈页面

  • 运营商拦截跳反诈页,打开呈红屏,某些地区的联通尤为常见。
  • 地区拦截跳反诈页,常见于江苏苏州,会跳到江苏特有的反诈页面。
处理

都不易解决。可尝试拨打国家反诈中心要求解封:010-67825170。苏州地区可在微信搜索"苏州市反通信网络诈骗中心",进入「封停申述 → 网站域名」填写申述表提交。

污染导致被墙

域名被污染后内容被替换成非法内容,而被污染域名不发生跳转、域名仍是你的,于是 GFW 误判该域名为非法站点并拉黑——这是一连串动作连带导致的。

处理

这种情况建议直接放弃该域名。

如果你的域名很好,务必保护好,否则后悔莫及。

知识分享 / 是否开启 HSTS

网站 HSTS 是否要开启?

HSTS 是什么

HSTS 是 IETF 推行的一种 Web 安全协议。网站采用 HSTS 后,用户访问时无需手动输入 HTTPS,浏览器会自动以 HTTPS 访问,从而始终走加密链接,保护数据传输安全。

开启 HSTS 有哪些作用

  • 预防 SSLStrip 中间人攻击,有效避免中间人对 80 端口的劫持。
  • 证书出现错误时直接显示错误,用户无法绕过警告。
  • 省去一次 301/302 跳转,提升安全性与用户体验。
  • 强制使用 HTTPS:用户用 HTTP 访问时客户端自动内部跳转(可见 307 Redirect Internal 响应码)。

是否需要开启

如果是 HTTPS 站点,建议开启。

在 CDN 中如何配置

不死鸟 CDN 默认未开启该选项(因为并非所有站点都需要 HTTPS 访问),需在站点配置中手动开启。

功能使用 / 刷新与预热缓存

刷新与预热缓存

更新了源站内容、但 CDN 还在返回旧版本?用刷新清掉旧缓存、让 CDN 重新拉取最新内容;用预热提前把资源缓存到节点,提升首次访问速度。

入口:网站管理 → 对应站点 → 刷新预热。

刷新缓存

支持三种粒度,按需选择:

  • 按 URL:精确刷新单个文件,如 https://你的域名/app.apk。
  • 按目录:刷新某目录下全部缓存,如 https://你的域名/static/。
  • 按正则:用正则表达式批量匹配刷新。

提交后,节点会清除对应缓存,下次访问时重新回源拉取最新内容。

什么时候用

更新了图片、JS、安装包等已被缓存的资源后,记得刷新对应 URL,否则在缓存有效期内用户仍会看到旧版本。

注意

避免频繁做全站刷新——会导致大量回源、瞬时拉高回源带宽。优先用按 URL / 按目录精确刷新。

预热缓存

提前把指定 URL 的资源缓存到各节点,用户首次访问即命中、无需等待回源。适合新发布的大文件(如新版 apk、活动素材)提前铺好。

功能使用 / 自定义缓存规则

自定义缓存规则

平台默认缓存规则已覆盖常见文件类型。若你的站点有特殊需求,可自定义规则,精细控制哪些资源缓存、缓存多久。

入口:网站编辑 → 缓存配置。

规则可按三种维度匹配

  • 按后缀名:如 jpg|png|mp4|apk。
  • 按目录:如 /static/。
  • 按全路径:精确到某个具体文件。

每条规则可设置

  • 有效期:该类资源缓存多久。
  • 忽略参数:URL 带不同参数时是否当作同一文件缓存。图片、下载类资源若参数只是防盗链/版本号,设为是可大幅提升命中率;若参数代表不同内容(如图片处理参数)则设为否。
  • 强制缓存:忽略源站返回的缓存头、强制缓存。适用于确定不变的静态资源(字体、安装包等)。
动态内容不要缓存

带登录态的页面、API 接口等动态内容应设为不缓存或缓存时间极短,否则用户可能看到他人页面或过期数据。

缓存规则从上到下匹配,匹配到即停止,注意排列顺序。

功能使用 / 访问控制(ACL)

访问控制(ACL)

ACL 用于精细控制"谁能访问你的站点"。可针对 IP、域名、User-Agent、URL 等设置放行或封禁,多条规则可自由组合,实现复杂的访问策略。

入口:我的网站 → 安全配置(添加过滤规则)。

常见用法

  • 放行(白名单):把合法的第三方请求加白,避免被防御误拦。例如支付回调、API 调用方的 IP——详见 《回调被拦截》。
  • 封禁(黑名单):封掉恶意 IP、可疑 User-Agent(如某些爬虫)、或特定 URL 路径。
  • 组合策略:多条规则按顺序匹配,可实现如"仅放行特定来源、禁止空 UA"等复杂控制。

可匹配的维度

IP / IP 段、域名、User-Agent、URL、请求方法等,多条条件可组合使用。

注意顺序

规则从上到下匹配。放行规则要放在封禁规则之前,否则合法请求可能先被封禁规则拦掉。

功能使用 / 多源站与负载均衡

多源站与负载均衡

如果你有多台源服务器,可在 CDN 配置多个源站,实现负载均衡与故障自动切换,提升稳定性与承载能力。

入口:网站编辑 → 源站设置。

能力

  • 负载均衡:配置多个源 IP,CDN 回源时按轮询分配,分摊源站压力。
  • 故障自动切换:某个源站故障时,自动尝试下一个源,避免单点故障导致全站不可用。
  • 回源参数:回源协议(HTTP / HTTPS / 跟随协议)、回源端口、回源超时等均可配置。
建议

多个源站的内容应保持一致,否则不同用户可能从不同源拿到不一样的结果。

回源相关报错(50x)排查见 《页面访问 50x 错误》。

功能使用 / 访问统计与日志

访问统计与日志

在控制台可实时查看站点的关键指标,并下载访问日志用于排查问题。

入口:网站管理 → 监控统计 / 访问日志。

可以看到

  • 实时指标:带宽、流量、请求数、缓存命中率、回源质量等。
  • 黑名单 IP:被防御拦截的 IP 列表。若本机或合法 IP 被误封,可在此解除(详见 50x 排查)。
  • 访问日志:可按日期、条件查询,并申请下载指定范围的日志。

命中率偏低说明缓存效果不佳,可结合 《自定义缓存规则》 优化;回源质量差则可能是源站或线路问题。

功能使用 / TLS 指纹(JA4)防护

TLS 指纹(JA4)防护

不死鸟CDN 支持 JA4 TLS 指纹识别:根据客户端在 TLS 握手时暴露的特征来辨认它是谁,再配合 URI、请求头等维度一起判断,让防护从「认 IP」升级到「认客户端」。在控制台里,它对应 CC 匹配器中的两个匹配项:TLS指纹 和 独立TLS指纹数量。

TLS 握手采集特征
→
JA4 算法生成指纹
→
多维统计找出异常
→
精准处置拉黑 / 验证 / 只记录
CC规则 → 添加匹配器 → 匹配项 选择 TLS指纹
▲ CC规则 → 添加匹配器 → 匹配项 选择 TLS指纹

9.1 只看 IP 的三个短板

短板说明
IP 太好换代理池、VPN 能轻松拿到大量 IP,按 IP 限速基本拦不住。
容易误伤公司、学校等场景里很多人共用一个出口 IP,按 IP 限速会把真实用户一起封掉。
绕过成本低代理 IP 很便宜,攻击者换一批就能绕开封禁,防守方疲于追赶。
核心问题

IP 只能说明请求「从哪里来」,说明不了「是谁发的」。要区分正常用户和攻击者,需要更深一层的特征。

9.2 多维特征识别

维度一:JA4 指纹 —— 客户端的「身份证」

JA4 根据 TLS 握手中的参数(TLS 版本、加密套件、扩展列表等)算出一个指纹字符串。它由客户端程序本身决定,换 IP 一般不会变:同一款攻击工具不管走多少代理,指纹往往一样;而真实浏览器的指纹与脚本工具明显不同。

对比项IP 地址JA4 指纹
能否代表身份弱,可共享、可更换强,跟客户端程序绑定
伪造难度低,挂代理 / VPN 即可高,需要改 TLS 底层实现
NAT 后的多个用户无法区分能区分不同客户端

在 统计分析 → 访问日志 / 拉黑日志 中观察请求量异常的指纹:攻击者怎么换 IP 都没用,只要还用同一个工具,指纹就不会变。

维度二:URI —— 精确到接口

把 请求URI / 请求URI(不带参数) 作为匹配条件,可以按路径设置不同强度的防护,例如对 /api/login 收紧,对 /static/ 放宽。

维度三:请求头等其它字段

结合 请求头、浏览器UA、独立UA数量、国家代码、AS号码 等匹配项,可以识别缺少正常请求头的自动化工具,构建更贴合业务的规则。

维度四:独立 TLS 指纹数量

统计同一个 IP 出现过多少种不同的指纹。正常用户一般只有 1~2 种,如果一个 IP 短时间内冒出 3 种以上,很可能是代理池或在随机伪造客户端。

9.3 精准匹配配置

在 CC规则 → 匹配器 → 添加匹配器(或网站的 安全设置 → 自定义规则)中,可以使用下面两个匹配项:

匹配项一:TLS指纹

直接匹配客户端的 JA4 指纹值,精确识别并处理已知的恶意客户端。

配置项填写
匹配项TLS指纹
操作符等于、不等于、包含、不包含、前缀、后缀、正则匹配等
匹配值JA4 指纹字符串(从日志中复制),一行一个
动作在规则组中选 拉黑 / 只记录,或在自定义规则中选验证类过滤
操作步骤

1. 在日志中找到异常指纹 → 2. 复制指纹字符串 → 3. 添加匹配器,匹配项选「TLS指纹」、操作符选「等于」,粘贴指纹 → 4. 在规则组里引用该匹配器,动作选「拉黑」。攻击者换再多 IP,只要用的是同一个工具,就会被拦下。

匹配项二:独立TLS指纹数量

统计某个 IP 在一段时间内出现的不同指纹数量,用来发现代理池攻击。阈值设得明显高于正常访客即可,具体可用的操作符以控制台该匹配项为准。

实战案例

设置「独立TLS指纹数量 大于 3 → 拉黑」。正常用户通常只有 1 个指纹,一个 IP 出现 3 个以上不同指纹,就是典型的代理池 / 攻击工具特征。

9.4 组合策略实战

只靠一个维度总有盲区,多个维度组合起来才能形成立体防御:

策略一 · JA4 + URI
  1. 匹配器添加两条:TLS指纹 等于 可疑指纹 + 请求URI 前缀 /api/。
  2. 两个条件同时满足才处理,既拦住扫描接口的工具,又降低误伤。
策略二 · 指纹 + 频率 + 验证
  1. 匹配器:TLS指纹 等于 已确认的恶意指纹。
  2. 过滤器1:请求频率;过滤器2:验证码 或 旋转图片。
  3. 动作:拉黑。
策略三 · 循序渐进
  1. 先用 只记录 观察命中情况;
  2. 确认无误后再换成验证类过滤器或 拉黑,避免一步到位造成误伤。

传统 IP 统计

  • 只看网络层,识别精度低
  • NAT 场景容易大面积误封
  • 代理池攻击难以防住
  • 换 IP 就能绕过

JA4 多维识别

  • 协议层 + 应用层,识别更准
  • 能区分同一出口后的不同客户端
  • 指纹锁定,与 IP 无关
  • 绕过需要重写 TLS 实现,成本高

9.5 部署建议

建议分三个阶段逐步上线,避免一次性开启造成误拦:

阶段一:观察(1~2 周)

新规则的动作先设为 只记录,只写日志不拦截,在 统计分析 → 访问日志 / 拉黑日志 中摸清正常用户的指纹分布和请求频率。重点留意 APP、支付回调、搜索引擎爬虫、监控探针等非浏览器客户端,必要时先加放行规则。

阶段二:精细化

根据观察结果,把规则逐步改为验证类过滤或 拉黑。先处理最明显的异常(比如某一个指纹占了绝大部分攻击流量)。

阶段三:持续优化

定期更新恶意指纹清单,调整统计周期和阈值。建议配合双过滤器:JA4 指纹做第一道筛选,传统验证兜底。攻击工具升级后指纹可能变化,记得复查。

重要提示

TLS 指纹只存在于 HTTPS 请求中,使用前请确认网站已开启 HTTPS(见 第八章 和 3.2 HTTPS 设置)。不要把 Chrome、Safari 等常见浏览器的指纹加入封禁,否则会大面积误伤正常访客。

需要帮助

遇到攻击需要协助分析指纹,可联系 Telegram @cdnbsn。

用户 API / API调用方法

API 调用方法

调用需要身份验证的用户 API 时,可使用以下两种方式之一。

方式一 · API 密钥

API 密钥长期有效,适合服务端程序、自动化任务等不便频繁登录的场景。

在用户后台的「账户中心 → API密钥」中开启后,可以获得 API Key 和 API Secret。调用 API 时,必须同时发送以下两个请求头:

  • api-key:填写 API Key
  • api-secret:填写 API Secret
curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/sites/1'

请将示例中的主控域名、YOUR_API_KEY 和 YOUR_API_SECRET 替换为实际值。API Secret 仅在可信环境中保存和使用,不要写入前端代码或公开仓库。

方式二 · Access Token

Access Token 有有效期,适合登录后的临时调用。先通过登录接口获取令牌,再通过 access-token 请求头调用其他 API。

1. 登录并获取令牌

curl -X POST \ -H 'Content-Type: application/json' \ -d '{"account":"YOUR_ACCOUNT","password":"YOUR_PASSWORD"}' \ 'https://master.example.com/v1/login'

account 可以填写用户名、手机号或邮箱地址。登录成功后,响应的 data.access_token 即为访问令牌。

2. 使用令牌调用 API

curl \ -H 'access-token: YOUR_ACCESS_TOKEN' \ 'https://master.example.com/v1/sites/1'
提示

下文各接口页的调用示例统一使用 https://master.example.com 作为主控域名占位,接入时请替换为你的实际主控地址。

用户 API / 公共接口

公共接口

验证码、注册信息和公共配置。

接口列表

GET
/v1/common/captcha
获取图形验证码 — 生成一次性图形验证码图片。响应为 image/gif 二进制内容,并通过 code Cookie 返回加密验证码数据;Cookie 中的验证码有效期为 60 秒
GET
/v1/common/captcha-type
获取验证码配置 — 获取登录/注册页面所需的验证码类型配置。接口读取系统 captcha_type 配置,并补充腾讯云验证码 appid、带有效期的加密 appid 令牌以及极验
GET
/v1/common/menu
获取面板菜单 — 根据当前登录账号类型返回面板侧边栏菜单。管理员返回内置管理员菜单,普通用户读取用户菜单 JSON;菜单节点可包含名称、标题、图标、跳转地址、隐藏侧栏标记和嵌套子
GET
/v1/common/menu2
获取新版面板菜单 — 根据当前登录账号类型返回新版面板的侧边栏和顶部菜单。管理员与普通用户使用不同的侧边栏集合,但顶部菜单固定包含首页和日志入口。侧边栏节点使用 path、title
GET
/v1/common/register-info
获取注册与用户协议配置 — 获取公开注册页面使用的字段要求和用户协议。配置由系统 register_require JSON 与 user_agreement JSON 合并返回;该公共接
GET
/v1/common/sysinfo
获取系统展示信息 — 读取系统展示配置并返回控制台标题、页脚版权、页脚链接和系统名称。该公共接口不要求登录,配置内容由管理员在系统设置中维护。
用户 API / 公共接口 / 获取图形验证码

GET获取图形验证码

GET /v1/common/captcha

生成一次性图形验证码图片。响应为 image/gif 二进制内容,并通过 code Cookie 返回加密验证码数据;Cookie 中的验证码有效期为 60 秒。该公共接口不要求登录,客户端应保存 Cookie 并在后续需要验证码的请求中携带。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

响应

HTTP 200

成功返回 GIF 图像,同时通过 Set-Cookie 写入加密验证码 Cookie。

字段类型必填说明示例
(root)string(binary)否验证码 GIF 图片二进制内容。

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/common/captcha'
用户 API / 公共接口 / 获取验证码配置

GET获取验证码配置

GET /v1/common/captcha-type

获取登录/注册页面所需的验证码类型配置。接口读取系统 captcha_type 配置,并补充腾讯云验证码 appid、带有效期的加密 appid 令牌以及极验 captcha_id;未配置第三方验证码时对应字段为空字符串。该公共接口不要求登录。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

响应

HTTP 200

业务结果通过 HTTP 200 返回。成功时返回配置对象;系统维护或认证状态不影响该公共 GET 接口,数据库配置读取异常则不会生成业务错误响应。

字段类型必填说明示例
codeinteger enum是成功状态码,验证码配置读取成功时固定为 0。0
msgstring enum是配置读取成功时固定为空字符串。
dataobject是系统验证码类型配置及服务端补充的第三方验证码参数。
data.emailstring是邮箱验证码方式配置值,例如空字符串表示未启用。
data.phonestring是手机验证码方式配置值,例如 native 表示内置方式。
data.appidstring是腾讯云验证码 AppID;未配置时为空字符串。
data.appid_encryptstring是使用腾讯云密钥加密的短期 AppID 参数;未配置时为空字符串,示例使用占位值。
data.geetest_captcha_idstring是极验验证码 captcha_id;未配置时为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "email": "string", "phone": "string", "appid": "string", "appid_encrypt": "string", "geetest_captcha_id": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/common/captcha-type'
用户 API / 公共接口 / 获取面板菜单

GET获取面板菜单

GET /v1/common/menu

根据当前登录账号类型返回面板侧边栏菜单。管理员返回内置管理员菜单,普通用户读取用户菜单 JSON;菜单节点可包含名称、标题、图标、跳转地址、隐藏侧栏标记和嵌套子菜单。该接口需要登录,响应不包含业务分页信息。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

响应

HTTP 200

业务结果通过 HTTP 200 返回。认证成功时返回当前账号可见菜单数组;认证失效时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,菜单读取成功时固定为 0。0
oneOf#1.msgstring enum是菜单读取成功时固定为空字符串。
oneOf#1.dataarray是当前账号可见的菜单节点,数组顺序决定面板显示顺序。
oneOf#1.dataarray<object>否当前账号可见的菜单节点,数组顺序决定面板显示顺序。
oneOf#1.data[].namestring否菜单节点内部名称,用于前端路由或权限识别。
oneOf#1.data[].titlestring否菜单显示标题。 具体说明
oneOf#1.data[].iconstring否菜单图标名称,可省略。
oneOf#1.data[].jumpstring否点击菜单时使用的前端跳转地址,可省略。
oneOf#1.data[].hideSiderboolean否是否隐藏侧边栏,可省略。
oneOf#1.data[].listarray否嵌套子菜单节点,可省略。
oneOf#1.data[].listarray<object>否嵌套子菜单节点,可省略。
oneOf#2.codestring enum是login_required 表示认证无效。login_required
oneOf#2.msgstring是认证失败原因。 具体说明
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/common/menu'
用户 API / 公共接口 / 获取新版面板菜单

GET获取新版面板菜单

GET /v1/common/menu2

根据当前登录账号类型返回新版面板的侧边栏和顶部菜单。管理员与普通用户使用不同的侧边栏集合,但顶部菜单固定包含首页和日志入口。侧边栏节点使用 path、title、header、icon、children 和可选 auth;其中 auth 为 [&#x27;hidden&#x27;] 时表示该路由不在菜单中直接展示。该接口需要登录。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

响应

HTTP 200

业务结果通过 HTTP 200 返回。认证成功时返回 sider 和 header 菜单数组;认证失效时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,菜单读取成功时固定为 0。0
oneOf#1.msgstring enum是菜单读取成功时固定为空字符串。
oneOf#1.dataobject是新版面板菜单集合。
oneOf#1.data.siderarray是侧边栏菜单节点数组。
oneOf#1.data.siderarray<object>否侧边栏菜单节点数组。
oneOf#1.data.sider[].pathstring是前端页面路由,例如 /dashboard/site 或 /site/list。
oneOf#1.data.sider[].titlestring是该侧边栏菜单项在面板中的显示名称。
oneOf#1.data.sider[].headerstring是该菜单所属顶部导航标识,例如 home 或 system。
oneOf#1.data.sider[].iconstring是该侧边栏菜单项使用的前端图标名称。
oneOf#1.data.sider[].autharray否可选的菜单展示控制标记;当前服务端中 ["hidden"] 表示隐藏该路由菜单项。
oneOf#1.data.sider[].autharray<string>否可选的菜单展示控制标记;当前服务端中 ["hidden"] 表示隐藏该路由菜单项。
oneOf#1.data.sider[].childrenarray否可选的子菜单列表;子节点使用与父节点相同的 path、title 和可选 auth 字段。
oneOf#1.data.sider[].childrenarray<object>否可选的子菜单列表;子节点使用与父节点相同的 path、title 和可选 auth 字段。
oneOf#1.data.sider[].children[].pathstring是子菜单对应的前端页面路由。
oneOf#1.data.sider[].children[].titlestring是该子菜单项在面板中的显示名称。
oneOf#1.data.sider[].children[].autharray否可选的菜单展示控制标记。
oneOf#1.data.sider[].children[].autharray<string>否可选的菜单展示控制标记。
oneOf#1.data.headerarray是顶部菜单节点数组。
oneOf#1.data.headerarray<object>否顶部菜单节点数组。
oneOf#1.data.header[].pathstring否前端页面路由;服务端固定返回 /dashboard/ 或 /log。
oneOf#1.data.header[].titlestring否顶部菜单显示标题;服务端固定为首页或日志。
oneOf#1.data.header[].iconstring否顶部菜单图标名称。
oneOf#1.data.header[].hideSiderboolean否进入该顶部页面后是否隐藏左侧菜单栏。
oneOf#1.data.header[].namestring否顶部菜单内部标识;服务端固定为 home 或 system。
oneOf#2.codestring enum是login_required 表示认证无效。login_required
oneOf#2.msgstring是认证失败原因。 具体说明
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "sider": [], "header": [] } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/common/menu2'
用户 API / 公共接口 / 获取注册与用户协议配置

GET获取注册与用户协议配置

GET /v1/common/register-info

获取公开注册页面使用的字段要求和用户协议。配置由系统 register_require JSON 与 user_agreement JSON 合并返回;该公共接口不要求登录。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

响应

HTTP 200

配置读取成功时返回注册字段规则和用户协议;数据库配置读取异常不会转换为业务错误响应。

字段类型必填说明示例
codeinteger enum是成功状态码,注册配置读取成功时固定为 0。0
msgstring enum是配置读取成功时固定为空字符串。
dataobject是公开注册字段要求及用户协议配置。
data.usernameobject是用户名注册规则。
data.username.needinteger enum是是否要求注册用户名:1 要求,0 不要求。0 | 1
data.emailobject是邮箱注册规则。 具体说明
data.email.needinteger enum是是否要求填写邮箱。0 | 1
data.email.verifyinteger enum是是否要求邮箱验证。0 | 1
data.phoneobject是手机号注册规则。
data.phone.needinteger enum是是否要求填写手机号。0 | 1
data.phone.verifyinteger enum是是否要求手机验证。0 | 1
data.qqobject是QQ 注册规则。
data.qq.needinteger enum是是否要求填写 QQ。0 | 1
data.user_agreementobject是用户协议内容。 具体说明
data.user_agreement.titlestring是用户协议显示标题。
data.user_agreement.datastring是用户协议、法律声明和隐私政策正文。

响应示例

{ "code": 0, "msg": "string", "data": { "username": { "need": 0 }, "email": { "need": 0, "verify": 0 }, "phone": { "need": 0, "verify": 0 }, "qq": { "need": 0 }, "user_agreement": { "title": "string", "data": "string" } } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/common/register-info'
用户 API / 公共接口 / 获取系统展示信息

GET获取系统展示信息

GET /v1/common/sysinfo

读取系统展示配置并返回控制台标题、页脚版权、页脚链接和系统名称。该公共接口不要求登录,配置内容由管理员在系统设置中维护。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

响应

HTTP 200

配置读取成功时返回系统展示信息;数据库配置读取异常不会转换为业务错误响应。

字段类型必填说明示例
codeinteger enum是成功状态码,系统信息读取成功时固定为 0。0
msgstring enum是系统信息读取成功时固定为空字符串。
dataobject是系统前端展示信息对象。服务端直接透传 system_info 配置;除已列字段外,管理员保存的其他展示配置也可能出现。
data.footer_copyrightstring是前端页脚显示的版权文本。
data.footer_linkstring是前端页脚链接配置:每行一个链接,行内以“显示名|URL”分隔。
data.user_console_titlestring是用户控制台标题。
data.admin_console_titlestring是管理员控制台标题。
data.sys_namestring是系统名称,供登录、注册等公开页面展示。
data.js_codestring否可选的前端注入 JavaScript 配置,例如统计或客服脚本。
data.sub_titlestring否可选的公开页面副标题。

响应示例

{ "code": 0, "msg": "string", "data": { "footer_copyright": "string", "footer_link": "string", "user_console_title": "string", "admin_console_title": "string", "sys_name": "string", "js_code": "string", "sub_title": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/common/sysinfo'
用户 API / 身份认证

身份认证

登录、密码重置、验证码和登录策略。

接口列表

POST
/v1/email-captcha
发送邮箱验证码 — 向指定邮箱发送 6 位验证码,用于注册、找回密码或邮箱验证。该公共接口不要求登录。收件人可由 account 指定的已启用账号解析,或直接由 email 指定;
POST
/v1/login
用户登录并获取访问令牌 — 使用用户名、邮箱或手机号和密码登录,成功后返回 access_token。后续需要登录的接口应将该值放入 access-token 请求头。该接口本身不要求令牌
POST
/v1/phone-captcha
发送手机验证码 — 向手机号码发送 4 位数字验证码。该公共接口不要求登录。手机号可由 `account` 指定的已启用账号解析,或直接由 `phone` 指定;两种方式不能混用。
POST
/v1/reset-pass
重置密码 — 通过已启用账号的邮箱验证码或手机验证码重置密码。该公共接口不要求登录。邮箱方式会在更新密码前向该邮箱发送包含新密码的重置成功邮件;邮件发送失败时本次重置会回滚。
GET
/v1/user/login-policy
查询账号登录策略 — 按账号查询登录时需要使用的验证码策略,以及该账号已脱敏的邮箱和手机号。账号可为已启用用户的用户名、邮箱或手机号;接口不需要登录。
用户 API / 身份认证 / 发送邮箱验证码

POST发送邮箱验证码

POST /v1/email-captcha

向指定邮箱发送 6 位验证码,用于注册、找回密码或邮箱验证。该公共接口不要求登录。收件人可由 account 指定的已启用账号解析,或直接由 email 指定;两种方式不能混用。系统会按 captcha_type.email 配置校验原生图形验证码、腾讯云验证码或极验验证码;同一客户端 IP 在 60 秒内最多成功发送一次。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
codecookiestring否当系统邮箱验证码类型为 native 时必填。应携带先调用 GET /v1/common/captcha 时服务端写入的 code Cookie;该 Cookie 中的图形验证码约 60 秒失效。腾讯云或极验验证模式不使用此 Cookie。<encrypted-captcha-cookie>

请求体

请求体必填。

Content-Type:application/json

发送邮箱验证码的请求。account 存在时服务端忽略 email 和 check_exist,并按账号查询已启用用户的邮箱;否则 email 和 check_exist 均为必填。验证码平台字段由服务器的 captcha_type.email 配置决定。

字段类型必填说明示例
accountstring否可选。已启用用户的邮箱、用户名或手机号;服务端据此取得该用户已配置的邮箱。提供时不能为空,且账号必须存在并已设置邮箱。
emailstring(email)否未提供 account 时必填。直接接收验证码的邮箱地址,必须为合法邮箱格式。
check_existinteger enum否未提供 account 时必填。邮箱存在性要求:0 表示邮箱必须不存在(通常用于注册);1 表示邮箱必须是已启用用户的邮箱(通常用于找回密码)。0 | 1
codestring否当 captcha_type.email 为 native 时必填。GET /v1/common/captcha 返回的图形验证码文本,按不区分大小写方式与 code Cookie 中的值比对;同一图形验证码一分钟内不能重复用于发送邮件。
ticketstring否当 captcha_type.email 为 qcloud 时必填。腾讯云验证码返回的票据。
randstrstring否当 captcha_type.email 为 qcloud 时必填。腾讯云验证码返回的随机字符串。
lot_numberstring否当 captcha_type.email 为 geetest 时必填。极验验证结果中的 lot_number。
captcha_outputstring否当 captcha_type.email 为 geetest 时必填。极验验证结果中的 captcha_output。
pass_tokenstring否当 captcha_type.email 为 geetest 时必填。极验验证结果中的 pass_token。
gen_timestring否当 captcha_type.email 为 geetest 时必填。极验验证结果中的 gen_time。

请求体示例

{ "account": "string", "email": "string", "check_exist": 0, "code": "string", "ticket": "string", "randstr": "string", "lot_number": "string", "captcha_output": "string", "pass_token": "YOUR_PASS_TOKEN", "gen_time": "string" }

响应

HTTP 200

业务结果始终使用 HTTP 200 返回。发送成功时 data 为 null;参数、收件人、验证码平台校验、频率限制和邮件发送失败均在同一响应中以业务错误码表示。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是发送成功提示。发送成功!
oneOf#1.datastring是成功时为 null。
oneOf#2.codestring enum是邮箱/账号、存在性要求、验证码平台参数或校验、60 秒发送频率限制、邮件投递失败对应的业务错误码。email_captcha-1 | email_captcha-2 | email_captcha-3 | email_captcha-4 | email_captcha-5 | email_captcha-6 | email_captcha-7 | email_captcha-8 | email_captcha-9 | email_captcha-10 | email_captcha-11 | email_captcha-12 | email_captcha-13 | email_captcha-14 | email_captcha-15 | email_captcha-16 | email_captcha-17 | email_captcha-18 | email_captcha-19 | email_captcha-20 | email_captcha-21 | email_captcha-22 | email_captcha-23 | email_captcha-24 | email_captcha-25 | email_captcha-26 | email_captcha-27 | email_captcha-28 | email_captcha-29 | email_captcha-30 | email_captcha-31 | email_captcha-32 | email_captcha-33 | email_captcha-34
oneOf#2.msgstring是具体错误原因,例如邮箱已存在、验证码错误、请等待 60 秒后再获取或邮件发送失败。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"account":"string","email":"string","check_exist":0,"code":"string","ticket":"string","randstr":"string","lot_number":"string","captcha_output":"string","pass_token":"YOUR_PASS_TOKEN","gen_time":"string"}' \ 'https://master.example.com/v1/email-captcha'
用户 API / 身份认证 / 用户登录并获取访问令牌

POST用户登录并获取访问令牌

POST /v1/login

使用用户名、邮箱或手机号和密码登录,成功后返回 access_token。后续需要登录的接口应将该值放入 access-token 请求头。该接口本身不要求令牌。服务端会按客户端 IP 统计最近一小时失败次数:达到系统配置的封禁阈值将拒绝登录;达到图形验证码阈值且最近三次均未成功时,必须完成图形验证码校验。用户还可能配置邮件或短信登录验证码、登录 IP 白名单和登录域名限制。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
codecookiestring否仅当该客户端 IP 触发图形验证码登录校验时必填。携带 GET /v1/common/captcha 写入的 code Cookie;服务端会验证其加密内容和过期时间。未触发图形验证码时不使用该 Cookie。<encrypted-captcha-cookie>

请求体

请求体必填。

Content-Type:application/json

登录凭据。code 仅在服务器要求图形验证码时使用;captcha 仅在用户已启用邮件或短信登录验证码时使用。

字段类型必填说明示例
accountstring是必填。用户名、邮箱地址或手机号;不能为空,且必须符合其中一种格式。
passwordstring(password)是必填。用户密码明文;服务端使用保存的 bcrypt 哈希验证。
codestring否条件必填。当当前 IP 达到系统图形验证码阈值且最近三次登录均未成功时,填写 GET /v1/common/captcha 图片中的验证码;与 code Cookie 中的值不区分大小写比较。
captchastring否条件必填。当该用户的 login_captcha 配置为 email 或 sms 时,填写已发送的邮件验证码或短信验证码。

请求体示例

{ "account": "string", "password": "YOUR_PASSWORD", "code": "string", "captcha": "string" }

响应

HTTP 200

业务结果始终使用 HTTP 200 返回。成功时 data 返回令牌及用户身份;凭据、验证码、用户状态、IP/域名限制或系统授权检查失败时返回业务错误封装。密码错误会被记入登录日志。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是登录成功提示。登录成功!
oneOf#1.dataobject是登录成功后的会话和用户身份。
oneOf#1.data.access_tokenstring是加密会话令牌。后续请求以 access-token 请求头携带,实际有效期由系统 login_session_valid_time 配置决定。
oneOf#1.data.usernamestring是登录用户的用户名。
oneOf#1.data.uidinteger(int64)是登录用户 ID。
oneOf#1.data.typeinteger enum是用户类型:1 为管理员,2 为普通用户。1 | 2
oneOf#2.codestring enum是账号或密码缺失/格式错误、失败次数限制、图形验证码、用户不存在或禁用、密码错误、登录域名、系统授权、IP 白名单及邮件/短信登录验证码失败的业务错误码。user_login-1 | user_login-2 | user_login-3 | user_login-4 | user_login-5 | user_login-6 | user_login-7 | user_login-8 | user_login-9 | user_login-10 | user_login-11 | user_login-12 | user_login-13 | user_login-14 | user_login-15 | user_login-16 | user_login-17 | user_login-18 | user_login-19 | user_login-20 | user_login-21 | user_login-22 | user_login-23
oneOf#2.msgstring是具体错误原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "access_token": "YOUR_ACCESS_TOKEN", "username": "string", "uid": 0, "type": 1 } }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"account":"string","password":"YOUR_PASSWORD","code":"string","captcha":"string"}' \ 'https://master.example.com/v1/login'
用户 API / 身份认证 / 发送手机验证码

POST发送手机验证码

POST /v1/phone-captcha

向手机号码发送 4 位数字验证码。该公共接口不要求登录。手机号可由 `account` 指定的已启用账号解析,或直接由 `phone` 指定;两种方式不能混用。系统按 `captcha_type.phone` 配置校验原生图形验证码、腾讯云验证码或极验验证码;同一客户端 IP 在 60 秒内最多发送一次。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
codecookiestring否当系统手机验证码类型为 native 时必填。应携带 GET /v1/common/captcha 写入的 `code` Cookie;其中的图形验证码约 60 秒失效。腾讯云或极验模式不使用此 Cookie。<encrypted-captcha-cookie>

请求体

请求体必填。

Content-Type:application/json

发送手机验证码的请求。`account` 存在时服务端忽略 `phone` 和 `check_exist`,并按账号查询已启用用户的手机号;否则 `phone` 和 `check_exist` 均为必填。验证码平台字段由服务器的 `captcha_type.phone` 配置决定。

字段类型必填说明示例
accountstring否可选。已启用用户的邮箱、用户名或手机号;服务端据此取得该用户已配置的手机号。提供时不能为空,账号必须存在且已设置手机号。
phonestring否未提供 `account` 时必填。直接接收验证码的手机号码,必须符合服务端手机号格式校验。13800138000
check_existinteger enum否未提供 `account` 时必填。手机号存在性要求:0 表示手机号必须不存在(通常用于注册);1 表示手机号必须属于已启用用户(通常用于找回密码)。0
codestring否当 `captcha_type.phone` 为 native 时必填。GET /v1/common/captcha 返回的图形验证码文本,按不区分大小写方式与 `code` Cookie 中的值比对;同一图形验证码一分钟内不能重复用于发送短信。
ticketstring否当 `captcha_type.phone` 为 qcloud 时必填。腾讯云验证码返回的票据。
randstrstring否当 `captcha_type.phone` 为 qcloud 时必填。腾讯云验证码返回的随机字符串。
lot_numberstring否当 `captcha_type.phone` 为 geetest 时必填。极验验证结果中的 `lot_number`。
captcha_outputstring否当 `captcha_type.phone` 为 geetest 时必填。极验验证结果中的 `captcha_output`。
pass_tokenstring否当 `captcha_type.phone` 为 geetest 时必填。极验验证结果中的 `pass_token`。
gen_timestring否当 `captcha_type.phone` 为 geetest 时必填。极验验证结果中的 `gen_time`。

请求体示例

{ "account": "string", "phone": "13800138000", "check_exist": 0, "code": "string", "ticket": "string", "randstr": "string", "lot_number": "string", "captcha_output": "string", "pass_token": "YOUR_PASS_TOKEN", "gen_time": "string" }

响应

HTTP 200

发送成功时 `data` 为 null;参数、账号/手机号、验证码平台校验、频率限制和短信发送失败均使用 HTTP 200 的业务错误响应。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是发送成功提示。发送成功!
oneOf#1.datastring是成功时为 null。
oneOf#2.codestring enum是手机号或账号、存在性要求、验证码平台参数及校验、60 秒发送频率限制或短信发送失败对应的业务错误码。phone_captcha-1 | phone_captcha-2 | phone_captcha-3 | phone_captcha-4 | phone_captcha-6 | phone_captcha-7 | phone_captcha-8 | phone_captcha-9 | phone_captcha-10 | phone_captcha-11 | phone_captcha-12 | phone_captcha-13 | phone_captcha-14 | phone_captcha-15 | phone_captcha-16 | phone_captcha-17 | phone_captcha-18 | phone_captcha-19 | phone_captcha-20 | phone_captcha-21 | phone_captcha-22 | phone_captcha-23 | phone_captcha-24 | phone_captcha-25 | phone_captcha-26 | phone_captcha-27 | phone_captcha-28 | phone_captcha-29 | phone_captcha-30 | phone_captcha-31 | phone_captcha-32 | phone_captcha-33 | phone_captcha-34 | phone_captcha-35
oneOf#2.msgstring是具体错误原因,例如手机号已存在、验证码错误、请等待 60 秒后再获取或短信发送失败。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"account":"string","phone":"13800138000","check_exist":0,"code":"string","ticket":"string","randstr":"string","lot_number":"string","captcha_output":"string","pass_token":"YOUR_PASS_TOKEN","gen_time":"string"}' \ 'https://master.example.com/v1/phone-captcha'
用户 API / 身份认证 / 重置密码

POST重置密码

POST /v1/reset-pass

通过已启用账号的邮箱验证码或手机验证码重置密码。该公共接口不要求登录。邮箱方式会在更新密码前向该邮箱发送包含新密码的重置成功邮件;邮件发送失败时本次重置会回滚。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
oneOf#1.reset_bystring enum是使用邮箱验证码重置密码。email
oneOf#1.emailstring(email)是已启用用户的邮箱地址;必须存在。
oneOf#1.captchastring是发送到该邮箱的验证码;由服务端校验有效性和时效。
oneOf#1.passwordstring(password)是新密码,至少 6 位,且必须同时包含英文字母和数字。
oneOf#2.reset_bystring enum是使用手机验证码重置密码。phone
oneOf#2.phonestring是已启用用户的手机号码;必须符合服务端手机号格式且已存在。
oneOf#2.phone_captchastring是发送到该手机号的验证码;由服务端校验有效性和时效。
oneOf#2.passwordstring(password)是新密码,至少 6 位,且必须同时包含英文字母和数字。

请求体示例

{ "reset_by": "string", "email": "string", "captcha": "string", "password": "YOUR_PASSWORD" }

响应

HTTP 200

重置成功时 `data` 为 null;参数、账号、验证码、密码强度和邮件发送失败均通过 HTTP 200 的业务错误响应返回。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是重置成功提示。重置成功!
oneOf#1.datastring是成功时为 null。
oneOf#2.codestring enum是重置方式、邮箱/手机号、验证码、密码强度或邮件发送失败对应的业务错误码。reset_pass-1 | reset_pass-2 | reset_pass-3 | reset_pass-4 | reset_pass-5 | reset_pass-6 | reset_pass-7 | reset_pass-8 | reset_pass-9 | reset_pass-10 | reset_pass-11 | reset_pass-12 | reset_pass-13 | reset_pass-14 | reset_pass-15 | reset_pass-16 | reset_pass-17 | reset_pass-18 | reset_pass-19 | reset_pass-20 | reset_pass-21 | reset_pass-22
oneOf#2.msgstring是具体错误原因,例如验证码错误、账号不存在或密码不符合强度要求。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"reset_by":"string","email":"string","captcha":"string","password":"YOUR_PASSWORD"}' \ 'https://master.example.com/v1/reset-pass'
用户 API / 身份认证 / 查询账号登录策略

GET查询账号登录策略

GET /v1/user/login-policy

按账号查询登录时需要使用的验证码策略,以及该账号已脱敏的邮箱和手机号。账号可为已启用用户的用户名、邮箱或手机号;接口不需要登录。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
accountquerystring是必填。登录账号,可填写用户名、邮箱或手机号;必须对应已启用用户。demo

响应

HTTP 200

请求已被处理。成功时返回登录验证码设置及脱敏联系方式;未提供账号或账号不存在时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。获取成功!
dataobject是账号的登录策略和脱敏联系方式。
data.login_captchainteger是登录是否需要验证码的账号设置值。1
data.emailstring是脱敏后的邮箱地址:邮箱用户名仅保留前两个字符,其余以四个星号替代。de****@example.invalid
data.phonestring是脱敏后的手机号:保留前 3 位和后 4 位,中间以四个星号替代。138****1234

响应示例

{ "code": 0, "msg": "获取成功!", "data": { "login_captcha": 1, "email": "de****@example.invalid", "phone": "138****1234" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user/login-policy'
用户 API / API 密钥

API 密钥

用户 API Key 与 Secret 管理。

接口列表

DELETE
/v1/api-key
关闭 API Key — 关闭并删除当前登录用户的 API Key 配置;管理员可通过 `uid` 关闭指定用户。删除的是整条配置记录,包括 API Key、API Secret 和来源
GET
/v1/api-key
获取 API Key 配置 — 获取当前登录用户的 API Key 配置;管理员可通过 `uid` 查询指定用户。接口直接返回数据库中保存的 API Key、API Secret 和来源 IP
POST
/v1/api-key
开通 API Key — 为当前登录用户开通 API Key;管理员可通过可选的 `uid` 为指定用户开通。每个用户只能保存一组 API Key,已开通时不能重复创建。服务端随机生成
PUT
/v1/api-key
更新或重置 API Key — 更新当前登录用户的 API Key 配置;管理员可通过 `uid` 操作指定用户。请求体支持两种操作:通过 `ip` 设置最多 10 个 IPv4/IPv6 来
用户 API / API 密钥 / 关闭 API Key

DELETE关闭 API Key

DELETE /v1/api-key

关闭并删除当前登录用户的 API Key 配置;管理员可通过 `uid` 关闭指定用户。删除的是整条配置记录,包括 API Key、API Secret 和来源 IP 白名单;事务提交后旧凭证立即无法用于后续 API 认证。目标用户必须已经开通 API Key。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
uidqueryinteger(int64)否要关闭 API Key 的用户 ID。省略时关闭当前登录用户的密钥;仅管理员可指定其他用户。

响应

HTTP 200

业务结果通过 HTTP 200 返回。API Key 配置删除并提交后返回确认消息;目标用户未开通、普通用户尝试指定 `uid` 或认证无效时返回字符串业务错误码,删除事务会回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,API Key 配置删除成功时固定为 0。0
oneOf#1.msgstring enum是API Key 配置删除并提交事务后返回的确认消息。api_key关闭成功
oneOf#1.datastring enum是关闭成功时没有额外业务数据,固定为 null。
oneOf#2.codestring enum是业务错误码:`api-key-4` 表示目标用户尚未开通 API Key,`message-28` 表示普通用户尝试关闭指定用户的密钥,`login_required` 表示登录态或 API Key 认证无效。api-key-4 | message-28 | login_required
oneOf#2.msgstring是与业务错误码对应的中文未开通、权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/api-key'
用户 API / API 密钥 / 获取 API Key 配置

GET获取 API Key 配置

GET /v1/api-key

获取当前登录用户的 API Key 配置;管理员可通过 `uid` 查询指定用户。接口直接返回数据库中保存的 API Key、API Secret 和来源 IP 白名单,不会对密钥做掩码;调用方不得把响应写入日志、前端持久化存储或转发给无关方。目标用户尚未开通 API Key 时请求仍成功,`data` 返回 null。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
uidqueryinteger(int64)否要查询 API Key 的用户 ID。省略时查询当前登录用户;仅管理员可指定其他用户,普通用户传入该参数会返回权限错误。

响应

HTTP 200

业务结果通过 HTTP 200 返回。查询成功时 `data` 为完整 API Key 记录;目标用户尚未开通时 `data` 为 null;普通用户尝试指定 `uid` 或登录凭证无效时返回字符串业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是查询完成时的成功状态码,固定为 0,包括用户尚未开通 API Key 的情况。0
oneOf#1.msgstring enum是API Key 查询完成时返回的确认消息。获取成功
oneOf#1.dataoneOf是目标用户的完整 API Key 配置;尚未开通 API Key 时为 null。
oneOf#1.data(oneOf#1).idinteger(int64)是API Key 配置记录的唯一 ID。
oneOf#1.data(oneOf#1).uidinteger(int64)是该 API Key 所属用户的 ID。
oneOf#1.data(oneOf#1).api_keystring是调用 API 时通过 `api-key` 请求头提交的 16 位访问标识。
oneOf#1.data(oneOf#1).api_secretstring是与 API Key 配对、通过 `api-secret` 请求头提交的 30 位明文密钥。
oneOf#1.data(oneOf#1).api_ipstring是允许使用该密钥的来源 IP 白名单,多个地址以竖线 `|` 分隔;null 或空字符串表示不限制来源 IP。
oneOf#1.data(oneOf#2)string否
oneOf#2.codestring enum是业务错误码:`task-5` 表示普通用户尝试查询指定用户的 API Key,`login_required` 表示登录态或 API Key 认证无效。task-5 | login_required
oneOf#2.msgstring是与业务错误码对应的中文权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": null }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/api-key'
用户 API / API 密钥 / 开通 API Key

POST开通 API Key

POST /v1/api-key

为当前登录用户开通 API Key;管理员可通过可选的 `uid` 为指定用户开通。每个用户只能保存一组 API Key,已开通时不能重复创建。服务端随机生成 16 位 API Key 和 30 位 API Secret,并以明文返回;新记录的来源 IP 白名单初始为 null,即不限制调用来源 IP,后续可通过更新接口设置。调用方应立即安全保存响应,避免写入日志或暴露给无关方。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

Content-Type:application/json

字段类型必填说明示例
uidinteger(int64)否要开通 API Key 的用户 ID。省略请求体或该字段时为当前登录用户;仅管理员可指定其他用户。

请求体示例

{ "uid": 0 }

响应

HTTP 200

业务结果通过 HTTP 200 返回。开通成功时返回新生成的 API Key 和 API Secret;目标用户已有密钥、普通用户尝试指定 `uid` 或登录认证无效时返回字符串业务错误码,创建事务会回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,API Key 开通成功时固定为 0。0
oneOf#1.msgstring enum是API Key 记录创建并提交后返回的确认消息。api key开通成功
oneOf#1.dataobject是新开通的 API Key 凭证对。
oneOf#1.data.api_keystring是新生成的 16 位访问标识,调用 API 时通过 `api-key` 请求头提交。
oneOf#1.data.api_secretstring是与 API Key 配对的新生成 30 位明文密钥,调用 API 时通过 `api-secret` 请求头提交。
oneOf#2.codestring enum是业务错误码:`api-key-1` 表示目标用户已经开通 API Key,`task-6` 表示普通用户尝试为指定用户开通,`login_required` 表示登录态或 API Key 认证无效。api-key-1 | task-6 | login_required
oneOf#2.msgstring是与业务错误码对应的中文重复开通、权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET" } }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"uid":0}' \ 'https://master.example.com/v1/api-key'
用户 API / API 密钥 / 更新或重置 API Key

PUT更新或重置 API Key

PUT /v1/api-key

更新当前登录用户的 API Key 配置;管理员可通过 `uid` 操作指定用户。请求体支持两种操作:通过 `ip` 设置最多 10 个 IPv4/IPv6 来源地址,传空字符串或 null 可清除白名单;通过 `reset` 重新生成 16 位 API Key 和 30 位 API Secret,旧凭证立即失效。目标用户必须已经开通 API Key。`ip` 与 `reset` 不应同时提交;若同时存在,服务端只执行 `ip` 分支而不会重置凭证。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
oneOf#1.ipstring是允许使用该 API Key 的来源 IP 白名单,最多 10 个 IPv4 或 IPv6 地址,多个地址以竖线 `|` 分隔;空字符串或 null 表示清除限制。
oneOf#1.uidinteger(int64)否要修改 API Key 的用户 ID;省略时为当前登录用户,仅管理员可指定其他用户。
oneOf#2.resetboolean enum是传 true 重新生成 API Key 和 API Secret;服务端以字段是否存在触发重置。true
oneOf#2.uidinteger(int64)否要重置 API Key 的用户 ID;省略时为当前登录用户,仅管理员可指定其他用户。

请求体示例

{ "ip": "string", "uid": 0 }

响应

HTTP 200

业务结果通过 HTTP 200 返回。IP 白名单修改成功时返回空业务数据;凭证重置成功时返回新 API Key 和 API Secret;目标用户未开通、IP 数量或格式不合法、普通用户指定 `uid` 或认证无效时返回字符串业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,来源 IP 白名单修改成功时固定为 0。0
oneOf#1.msgstring enum是来源 IP 白名单写入并提交后返回的确认消息。修改成功
oneOf#1.datastring enum是来源 IP 白名单修改成功时没有额外业务数据,固定为 null。
oneOf#2.codeinteger enum是成功状态码,API Key 凭证重置成功时固定为 0。0
oneOf#2.msgstring enum是新凭证写入并使旧凭证失效后返回的确认消息。重置成功
oneOf#2.dataobject是重置后立即生效的新 API Key 凭证对。
oneOf#2.data.api_keystring是重置后新生成的 16 位访问标识。
oneOf#2.data.api_secretstring是与新 API Key 配对的 30 位明文密钥。
oneOf#3.codestring enum是业务错误码:`api-key-2` 表示目标用户未开通 API Key,`api-key-3` 表示某个 IP 地址无效,`api-key-5` 表示白名单超过 10 个地址,`message-27` 表示普通用户尝试操作指定用户,`login_required` 表示认证无效。api-key-2 | api-key-3 | api-key-5 | message-27 | login_required
oneOf#3.msgstring是与业务错误码对应的中文配置、IP、权限或认证失败原因。
oneOf#3.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"ip":"string","uid":0}' \ 'https://master.example.com/v1/api-key'
用户 API / 账户资料

账户资料

当前用户资料、概览和实名认证。

接口列表

GET
/v1/user
获取当前用户信息 — 获取当前登录用户的账户资料、实名认证与企业认证状态、二次认证设置、余额和用户组。身份证姓名和号码会脱敏后返回。未登录时不能访问。
POST
/v1/user
创建用户 — 注册普通用户。是否开放注册,以及用户名、邮箱、手机和 QQ 是否必填、是否需要邮箱或手机验证码,均由系统的注册配置决定。无论配置如何,必须同意注册协议并提供符合
PUT
/v1/user
更新当前用户信息 — 更新当前登录用户的账户资料、登录安全设置或密码。未登录不能操作。修改手机号或邮箱时分别必须提供针对新号码或新邮箱的验证码;用户名只能在当前用户名为空时设置一次,
GET
/v1/user/certify
查询实名认证状态 — 查询当前登录用户的个人实名认证或二次实名认证结果。认证已通过时立即返回通过状态;尚未通过时,接口会依据用户保存的认证方式向支付宝或微信认证服务查询并同步认证结果
POST
/v1/user/certify
发起个人或企业实名认证 — 为当前登录用户发起个人实名认证、二次实名认证或企业实名认证。个人认证可能直接通过,也可能返回第三方认证跳转地址;企业认证要求先完成法人个人认证,并由系统调用已配
GET
/v1/user/overview
获取当前用户控制台概览 — 返回当前登录用户在控制台首页展示的资源和账户概览,包括有效用户套餐数量、即将续费数量、余额、实名认证状态、域名、证书和四层转发端口统计。
用户 API / 账户资料 / 获取当前用户信息

GET获取当前用户信息

GET /v1/user

获取当前登录用户的账户资料、实名认证与企业认证状态、二次认证设置、余额和用户组。身份证姓名和号码会脱敏后返回。未登录时不能访问。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“获取成功!”、`data` 为当前用户资料;未登录时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。获取成功!
dataobject是当前登录用户资料。
data.idinteger是用户 ID。
data.namestring是用户名。
data.emailstring否邮箱地址。
data.phonestring否手机号。
data.qqstring否QQ 号。
data.balancenumber是账户余额。
data.create_atstring否注册时间,格式为 YYYY-MM-DD HH:mm:ss。
data.user_groupinteger否用户组 ID。
data.group_namestring否用户组名称。
data.cert_idinteger否实名认证证书 ID。
data.cert_namestring否脱敏后的实名姓名。
data.cert_nostring否脱敏后的证件号码。
data.cert_verifiedinteger enum是个人实名认证状态。0 | 1
data.id_auth_waystring否实名认证方式。
data.company_auth_enableinteger enum否系统是否启用企业认证。0 | 1
data.company_namestring否企业名称。
data.company_credit_codestring否统一社会信用代码。
data.company_verifiedinteger enum否企业认证状态。0 | 1
data.auth2_enableinteger enum否是否启用二次认证。0 | 1
data.auth2_verifiedinteger enum否当前二次认证是否已验证。0 | 1
data.auth2_end_atstring否二次认证有效截止时间。
data.auth2_expire_actionstring否二次认证过期处理动作。
data.login_captchastring否登录二次验证方式。
data.white_ipstring否登录 IP 白名单。

响应示例

{ "code": 0, "msg": "获取成功!", "data": { "id": 0, "name": "string", "email": "string", "phone": "string", "qq": "string", "balance": 0, "create_at": "string", "user_group": 0, "group_name": "string", "cert_id": 0, "cert_name": "string", "cert_no": "string", "cert_verified": 0, "id_auth_way": "string", "company_auth_enable": 0, "company_name": "string", "company_credit_code": "string", "company_verified": 0, "auth2_enable": 0, "auth2_verified": 0, "auth2_end_at": "string", "auth2_expire_action": "string", "login_captcha": "string", "white_ip": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user'
用户 API / 账户资料 / 创建用户

POST创建用户

POST /v1/user

注册普通用户。是否开放注册,以及用户名、邮箱、手机和 QQ 是否必填、是否需要邮箱或手机验证码,均由系统的注册配置决定。无论配置如何,必须同意注册协议并提供符合规则的密码。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
usernamestring否当系统要求用户名时必填。仅允许中文、英文字母与数字,不能是手机号,且必须唯一。demo_user
emailstring(email)否当系统要求邮箱时必填,且必须唯一;若系统配置邮箱验证,需同时提供 `captcha`。demo@example.invalid
phonestring否当系统要求手机号时必填,且必须唯一;若系统配置手机验证,需同时提供 `phone_captcha`。13800000000
qqstring否当系统要求 QQ 时必填,必须为合法 QQ 号。10001
captchastring否邮箱验证码;仅在系统启用必填邮箱且要求邮箱验证时必填。123456
phone_captchastring否手机验证码;仅在系统启用必填手机且要求手机验证时必填。123456
accept_agreementinteger enum是必填。必须为 1,表示同意注册协议。1
passwordstring(password)是必填。至少 6 位,且必须同时包含英文字母和数字。Demo123456

请求体示例

{ "username": "demo_user", "email": "demo@example.invalid", "phone": "13800000000", "captcha": "123456", "phone_captcha": "123456", "accept_agreement": 1, "password": "Demo123456" }

响应

HTTP 200

请求已被处理。注册成功时 `code` 为 0、`msg` 为“注册成功!”、`data` 为 null;注册关闭、字段缺失、格式错误、账号重复或验证码无效时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。注册成功!
datastring是注册成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "注册成功!", "data": null }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"username":"demo_user","email":"demo@example.invalid","phone":"13800000000","captcha":"123456","phone_captcha":"123456","accept_agreement":1,"password":"Demo123456"}' \ 'https://master.example.com/v1/user'
用户 API / 账户资料 / 更新当前用户信息

PUT更新当前用户信息

PUT /v1/user

更新当前登录用户的账户资料、登录安全设置或密码。未登录不能操作。修改手机号或邮箱时分别必须提供针对新号码或新邮箱的验证码;用户名只能在当前用户名为空时设置一次,之后不可修改。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring否用户名。仅当当前用户名为空时可设置一次;只允许中文、英文字母与数字,且不能重复或为手机号。
phonestring否新手机号,必须合法且未被其他用户使用;传入时必须同时提供 `phone_captcha`。13800000000
phone_captchastring否修改手机号时必填。发送到新手机号的验证码。123456
emailstring(email)否新邮箱,必须合法且未被其他用户使用;传入时必须同时提供 `captcha`。new@example.invalid
captchastring否修改邮箱时必填。发送到新邮箱的验证码。123456
qqstring否新 QQ 号,必须为合法 QQ 号。10001
white_ipstring否登录 IP 白名单,多个 IP 使用空白字符分隔;可传空字符串清空。192.0.2.10 198.51.100.20
login_captchastring enum否登录二次验证码方式;空字符串表示关闭。`sms` 要求系统允许且已绑定手机,`email` 要求系统允许且已绑定邮箱。email
passwordstring(password)否新密码,至少 6 位且必须同时包含英文字母与数字。NewPass123

请求体示例

{ "email": "new@example.invalid", "captcha": "123456", "white_ip": "192.0.2.10", "login_captcha": "email" }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“修改成功”、`data` 为 null;未登录、验证码错误、资料重复或格式不正确时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。修改成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "修改成功", "data": null }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"email":"new@example.invalid","captcha":"123456","white_ip":"192.0.2.10","login_captcha":"email"}' \ 'https://master.example.com/v1/user'
用户 API / 账户资料 / 查询实名认证状态

GET查询实名认证状态

GET /v1/user/certify

查询当前登录用户的个人实名认证或二次实名认证结果。认证已通过时立即返回通过状态;尚未通过时,接口会依据用户保存的认证方式向支付宝或微信认证服务查询并同步认证结果。调用前用户必须已填写姓名和身份证号码,并已存在认证流水号。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

响应

HTTP 200

请求已被处理。成功时 data.passed 为 T;姓名或身份证为空、找不到认证流水号、未配置实名认证服务或认证服务返回失败时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
dataobject是实名认证查询结果。
data.passedstring enum是认证通过标志;成功时固定为 T。T

响应示例

{ "code": 0, "data": { "passed": "T" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user/certify'
用户 API / 账户资料 / 发起个人或企业实名认证

POST发起个人或企业实名认证

POST /v1/user/certify

为当前登录用户发起个人实名认证、二次实名认证或企业实名认证。个人认证可能直接通过,也可能返回第三方认证跳转地址;企业认证要求先完成法人个人认证,并由系统调用已配置的企业认证服务完成校验。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
verify_typestring enum否认证类型。personal_auth 为个人或二次个人认证;company_auth 为企业认证。未传时为 personal_auth。personal_auth
cert_namestring否个人认证时使用的姓名;必须为中文姓名。二次认证时必须与首次认证姓名一致。张三
cert_nostring否个人认证时使用的中国居民身份证号码。二次认证时必须与首次认证身份证号码一致。110101199001011234
company_credit_codestring否企业认证必填。企业统一社会信用代码,必须通过格式校验。91110000100000000X
company_namestring否企业认证必填。企业名称;会进行 XSS 过滤。示例科技有限公司

请求体示例

{ "verify_type": "personal_auth", "cert_name": "张三", "cert_no": "110101199001011234" }

响应

HTTP 200

请求已被处理。个人认证直接通过或企业认证成功时 data 为 null;需要跳转第三方认证时 data 为认证地址;身份信息无效、重复认证、认证服务未配置或企业信息校验失败时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。获取认证地址成功
datastring是需要第三方个人认证时为认证跳转地址;认证直接通过时为 null;失败时为空字符串。https://verify.example.invalid/session/demo

响应示例

{ "code": 0, "msg": "获取认证地址成功", "data": "https://verify.example.invalid/session/demo" }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"verify_type":"personal_auth","cert_name":"张三","cert_no":"110101199001011234"}' \ 'https://master.example.com/v1/user/certify'
用户 API / 账户资料 / 获取当前用户控制台概览

GET获取当前用户控制台概览

GET /v1/user/overview

返回当前登录用户在控制台首页展示的资源和账户概览,包括有效用户套餐数量、即将续费数量、余额、实名认证状态、域名、证书和四层转发端口统计。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

响应

HTTP 200

请求已被处理。成功时 data 为当前用户概览数据。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是成功时为空字符串。
dataobject是当前用户的资源与账户概览。
data.uidinteger是当前登录用户 ID。12
data.user_package_countinteger是未到期的用户套餐数量。1
data.renewinteger是将在 24 小时内到期或已到期的用户套餐数量。0
data.balancenumber是账户余额,单位为元。98.5
data.cert_verifiedinteger enum是个人实名认证是否通过。1
data.auth2_enableinteger enum是是否启用二次实名认证。0
data.auth2_verifiedinteger enum是二次实名认证是否通过。0
data.domain_countinteger是当前用户全部域名数量。6
data.cert_countinteger是具有私钥的证书数量。2
data.stream_port_countinteger是当前用户全部四层转发监听端口总数。3

响应示例

{ "code": 0, "msg": "", "data": { "uid": 12, "user_package_count": 1, "renew": 0, "balance": 98.5, "cert_verified": 1, "auth2_enable": 0, "auth2_verified": 0, "domain_count": 6, "cert_count": 2, "stream_port_count": 3 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user/overview'
用户 API / 用户默认配置

用户默认配置

用户默认配置

接口列表

GET
/v1/user-configs
查询用户配置列表 — 分页查询用户默认配置。普通用户只能查看自己的配置;管理员可通过 `uid` 筛选指定用户。可按配置类型、启用状态和配置项名称精确筛选,结果按配置 ID 倒序返回
POST
/v1/user-configs
新增用户配置 — 创建用户默认配置。配置项由 `type`、`name` 和作用域唯一确定;`value` 为字符串,其内容按配置类型和名称进行服务端校验。默认作用域为全局,默认
PUT
/v1/user-configs
批量更新用户配置 — 更新一个或多个用户配置。请求体可为单个对象或对象数组,单个对象会转换为数组。每个对象必须提供已有配置 ID;`name` 与 `type` 在更新时仍参与值和唯
DELETE
/v1/user-configs/{config_id}
删除用户配置 — 删除一个或多个用户配置。路径参数支持单个配置 ID 或英文逗号分隔的多个 ID;每个 ID 必须为数字且配置必须存在。普通用户只能删除自己的配置,管理员可删除其
PUT
/v1/user-configs/{config_id}
更新指定用户配置 — 更新一个用户配置。路径中的 `config_id` 会覆盖请求体 ID,请求体必须是 JSON 对象。普通用户只能更新自己的配置;管理员可更新其他用户配置。更新
用户 API / 用户默认配置 / 查询用户配置列表

GET查询用户配置列表

GET /v1/user-configs

分页查询用户默认配置。普通用户只能查看自己的配置;管理员可通过 `uid` 筛选指定用户。可按配置类型、启用状态和配置项名称精确筛选,结果按配置 ID 倒序返回。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger否页码,必须为数字;未传时为 1。1
limitqueryinteger否每页数量,必须为数字;未传时为 10,传 0 表示不分页。10
typequerystring否按配置类型筛选:`site` 为网站默认配置,`stream` 为四层转发默认配置。site
enablequeryinteger否按启用状态筛选;仅当传入非空值时生效。1
namequerystring否按配置项名称精确筛选。proxy_cache
uidqueryinteger否管理员可选。按归属用户 ID 筛选;普通用户不能借此查看其他用户。12

响应

HTTP 200

请求已被处理。成功时返回配置列表与总数;页码或每页数量格式错误时仍返回 HTTP 200,并给出业务错误码。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
countinteger是符合筛选条件的配置总数。1
dataarray是用户配置列表。
dataarray<object>否用户配置列表。
data[].idinteger是用户配置 ID。
data[].uidinteger是归属用户 ID。
data[].usernamestring否归属用户名。
data[].namestring是配置项名称。
data[].valuestring是配置值,具体格式由配置项名称和类型决定。
data[].typestring是配置类型:site 或 stream。
data[].scope_namestring是作用域名称,例如 global、group。
data[].scope_idinteger是作用域 ID。
data[].site_group_namestring否当作用域为网站分组时对应的网站分组名称。
data[].stream_group_namestring否当作用域为转发组时对应的转发组名称。
data[].enableinteger enum是启用状态。0 | 1
data[].create_atstring否创建时间。
data[].update_atstring否更新时间。

响应示例

{ "code": 0, "count": 1, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-configs'
用户 API / 用户默认配置 / 新增用户配置

POST新增用户配置

POST /v1/user-configs

创建用户默认配置。配置项由 `type`、`name` 和作用域唯一确定;`value` 为字符串,其内容按配置类型和名称进行服务端校验。默认作用域为全局,默认启用。普通用户创建自己的配置;管理员可通过 `uid` 为指定用户创建。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring是必填。配置项名称;会进行 XSS 过滤,并决定 `value` 的具体校验规则。proxy_cache
valuestring是必填。配置值字符串;例如 `proxy_cache` 要求 JSON 数组,`white_ip`/`black_ip` 为 IP/CIDR 列表,`block_time`/`white_time` 为 601 至 604800 秒。其他名称也按服务端对应规则验证。[]
typestring enum是必填。配置类型:网站、四层转发或证书。site
scope_namestring enum否作用域名称;未传时为 `global`。`group` 表示按网站组或转发组生效。global
scope_idinteger否作用域 ID;全局作用域固定为 0。分组作用域时,site 类型必须是现有网站组 ID,stream 类型必须是现有转发组 ID。0
enableinteger enum否是否启用;未传时为 1。1
uidinteger否管理员专用。指定配置归属用户 ID。12

请求体示例

{ "name": "proxy_cache", "value": "[]", "type": "site", "scope_name": "global", "scope_id": 0, "enable": 1 }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“用户配置添加成功”、`data` 为新建配置 ID;名称、值、作用域无效或配置重复时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。用户配置添加成功
datainteger是成功时的新建配置 ID;失败时为空字符串。9

响应示例

{ "code": 0, "msg": "用户配置添加成功", "data": 9 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"proxy_cache","value":"[]","type":"site","scope_name":"global","scope_id":0,"enable":1}' \ 'https://master.example.com/v1/user-configs'
用户 API / 用户默认配置 / 批量更新用户配置

PUT批量更新用户配置

PUT /v1/user-configs

更新一个或多个用户配置。请求体可为单个对象或对象数组,单个对象会转换为数组。每个对象必须提供已有配置 ID;`name` 与 `type` 在更新时仍参与值和唯一性校验,但数据库只更新 value、作用域和启用状态。普通用户只能操作自己的配置,管理员可操作其他用户配置。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
oneOf#1.idinteger是必填。用户配置 ID。
oneOf#1.namestring否配置项名称;更新时不写入数据库,但用于校验 value 与配置唯一性。未传时使用原名称。
oneOf#1.valuestring否配置值;按 name 与 type 的服务端规则校验。未传时使用原值。
oneOf#1.typestring enum否配置类型;更新时不写入数据库,但用于校验。未传时使用原类型。site | stream | cert
oneOf#1.scope_namestring enum否作用域名称;全局作用域强制 scope_id 为 0。global | group
oneOf#1.scope_idinteger否作用域 ID;分组作用域时必须存在对应的网站组或转发组。
oneOf#1.enableinteger enum否启用状态。0 | 1
oneOf#1.uidinteger否管理员专用。指定操作用户;不会改变已有配置的归属。
oneOf#2array<object>否批量更新对象数组。
oneOf#2[].idinteger是用户配置 ID。
oneOf#2[].valuestring否配置值。
oneOf#2[].scope_namestring否作用域名称。
oneOf#2[].scope_idinteger否作用域 ID。
oneOf#2[].enableinteger enum否启用状态。0 | 1

请求体示例

{ "id": 9, "value": "[]", "enable": 1 }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“更新用户配置成功”、`data` 为 null;请求格式、配置 ID、配置值、作用域或权限不正确时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。更新用户配置成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "更新用户配置成功", "data": null }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"id":9,"value":"[]","enable":1}' \ 'https://master.example.com/v1/user-configs'
用户 API / 用户默认配置 / 删除用户配置

DELETE删除用户配置

DELETE /v1/user-configs/{config_id}

删除一个或多个用户配置。路径参数支持单个配置 ID 或英文逗号分隔的多个 ID;每个 ID 必须为数字且配置必须存在。普通用户只能删除自己的配置,管理员可删除其他用户配置;任一项校验失败时整次删除会回滚。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
config_idpathstring是要删除的用户配置 ID,或以英文逗号分隔的 ID 列表;每一项必须是数字。9,10

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“用户配置删除成功”、`data` 为 null;ID 无效、配置不存在或无权限时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。用户配置删除成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "用户配置删除成功", "data": null }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-configs/{config_id}'
用户 API / 用户默认配置 / 更新指定用户配置

PUT更新指定用户配置

PUT /v1/user-configs/{config_id}

更新一个用户配置。路径中的 `config_id` 会覆盖请求体 ID,请求体必须是 JSON 对象。普通用户只能更新自己的配置;管理员可更新其他用户配置。更新时配置值与作用域会重新校验,名称与类型不写入数据库但仍用于校验。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
config_idpathinteger是要更新的用户配置 ID,必须存在且当前用户有权限操作。9

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring否配置项名称;更新时不写入数据库,但用于 value 校验和配置唯一性检查。未传时使用原名称。
valuestring否配置值;按照 name 与 type 对应的服务端规则校验。未传时使用原值。
typestring enum否配置类型;更新时不写入数据库,但用于 value 校验。未传时使用原类型。site | stream | cert
scope_namestring enum否作用域名称;global 时 scope_id 固定为 0。global | group
scope_idinteger否作用域 ID;分组作用域必须存在对应的网站组或转发组。
enableinteger enum否启用状态。0 | 1
uidinteger否管理员专用。指定操作用户;不会改变已有配置的归属。

请求体示例

{ "value": "[]", "enable": 1 }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“更新用户配置成功”、`data` 为 null;配置不存在、请求体非对象、值或作用域无效、无权限时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。更新用户配置成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "更新用户配置成功", "data": null }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"value":"[]","enable":1}' \ 'https://master.example.com/v1/user-configs/{config_id}'
用户 API / 网站与安全 / 配置模板

配置模板

网站和业务配置模板。

接口列表

GET
/v1/configs
查询系统配置列表 — 查询主控配置记录列表,仅管理员可调用。可按作用域名称、作用域 ID、配置类型和配置名称组合筛选;scope_name 支持用英文逗号传入多个值。返回配置原始 v
PUT
/v1/configs
新增或更新主控配置 — 按“作用域 + 类型 + 名称”创建或更新主控配置。服务端会将 value 转为字符串保存,并按具体 type、name 校验值;Nginx、错误页、OpenR
DELETE
/v1/configs/{config_id}
删除指定非全局主控配置 — 删除路径复合标识对应的 region 或 node 作用域配置。全局配置不能通过此接口删除;即使未找到记录,符合格式的删除请求仍会成功返回。删除 nginx_c
GET
/v1/configs/{config_id}
查询单项主控配置 — 按作用域、类型和名称组成的复合标识读取一条主控配置。登录用户只可读取 site 类型的 clean_url、clean_dir、ip-unlock-max-li
PUT
/v1/configs/{config_id}
按标识新增或更新主控配置 — 从路径复合标识取得 scope_name、scope_id、type、name,并以请求体的 value、enable 写入配置。路径中不存在的配置会被创建,已
GET
/v1/site-sys-config
获取站点系统配置 — 读取全局 OpenResty 配置中供站点使用的默认临时白名单时长和封禁时长。接口要求登录,不区分普通用户与管理员。
用户 API / 网站与安全 / 配置模板 / 查询系统配置列表

GET查询系统配置列表

GET /v1/configs

查询主控配置记录列表,仅管理员可调用。可按作用域名称、作用域 ID、配置类型和配置名称组合筛选;scope_name 支持用英文逗号传入多个值。返回配置原始 value 字符串,不会按配置类型自动解析 JSON。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
scope_namequerystring否配置作用域名称;可传 global、region、node,多个值使用英文逗号分隔。
scope_idqueryinteger(int64)否作用域实体 ID,精确筛选;global 配置通常使用 0。
typequerystring否配置类型,精确筛选,例如 system、site 或 nginx_config。
namequerystring否配置名称,精确筛选。

响应

HTTP 200

业务结果通过 HTTP 200 返回。管理员认证成功时返回全部匹配配置;普通用户、认证失效时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,配置列表查询成功时固定为 0。0
oneOf#1.msgstring enum是配置列表查询成功时固定为空字符串。
oneOf#1.dataarray是按数据库查询顺序返回的配置记录数组。
oneOf#1.dataarray<object>否按数据库查询顺序返回的配置记录数组。
oneOf#1.data[].namestring是配置名称;与 scope_name、scope_id、type 共同唯一定位一条配置。
oneOf#1.data[].valuestring是配置原始值,JSON 配置仍以字符串返回。
oneOf#1.data[].typestring是配置类型;用于区分 system、site、nginx_config、error_page 等配置处理逻辑。
oneOf#1.data[].scope_idinteger(int64)是配置作用域实体 ID。
oneOf#1.data[].scope_namestring是配置作用域名称。
oneOf#1.data[].create_atstring是配置创建时间,数据库 datetime 序列化值。
oneOf#1.data[].update_atstring是配置最后更新时间,数据库 datetime 序列化值。
oneOf#1.data[].enableinteger enum是配置启用状态:1 启用,0 禁用。0 | 1
oneOf#1.data[].task_idinteger(int64)是最近一次配置同步任务 ID,没有任务时为 null。
oneOf#1.data[].entity_namestring是region 或 node 作用域关联实体名称,global 作用域通常为空字符串。
oneOf#2.codestring enum是config-274 表示需要管理员权限,login_required 表示认证无效。config-274 | login_required
oneOf#2.msgstring是权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/configs'
用户 API / 网站与安全 / 配置模板 / 新增或更新主控配置

PUT新增或更新主控配置

PUT /v1/configs

按“作用域 + 类型 + 名称”创建或更新主控配置。服务端会将 value 转为字符串保存,并按具体 type、name 校验值;Nginx、错误页、OpenResty、默认端口和节点配置等变更会创建节点同步任务。仅管理员可调用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
scope_namestring enum是配置作用域:global 为全局,region 为指定区域,node 为指定节点。global | region | node
scope_idoneOf是作用域实体 ID。global 通常传 0;region、node 分别传对应的区域或节点 ID。
scope_id(oneOf#1)integer(int64)否
scope_id(oneOf#2)string否
typestring是配置类型。必须以小写字母开头,后续仅可包含小写字母和下划线,例如 system、site、nginx_config。
namestring是配置名称。必须以小写字母开头,后续仅可包含小写字母、数字、下划线和连字符。
valueoneOf是配置值,必填且可为空字符串。服务端以 str(value) 保存;要求 JSON 的配置必须传入 JSON 文本字符串,而不是 JSON 对象。具体允许值取决于 type 和 name。
value(oneOf#1)string否
value(oneOf#2)integer否
value(oneOf#3)number否
value(oneOf#4)boolean否
enableinteger enum否可选启用状态:1 启用,0 禁用。未传时新建记录默认启用,更新记录保持原状态。0 | 1

请求体示例

{ "scope_name": "global", "scope_id": 0, "type": "system", "name": "captcha_type", "value": "{\"email\":\"native\",\"phone\":\"\"}", "enable": 1 }

响应

HTTP 200

业务结果仍使用 HTTP 200 返回。成功时确认配置已写入;参数、权限或具体配置值校验失败时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是配置写入成功提示。更新config成功
oneOf#1.datastring enum是成功时固定为空字符串。
oneOf#2.codestring是业务错误码,例如 config-2 至 config-38、config-200、config-236 至 config-300,或管理员权限错误 config-275。
oneOf#2.msgstring是参数、权限或配置值校验失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"scope_name":"global","scope_id":0,"type":"system","name":"captcha_type","value":"{\"email\":\"native\",\"phone\":\"\"}","enable":1}' \ 'https://master.example.com/v1/configs'
用户 API / 网站与安全 / 配置模板 / 删除指定非全局主控配置

DELETE删除指定非全局主控配置

DELETE /v1/configs/{config_id}

删除路径复合标识对应的 region 或 node 作用域配置。全局配置不能通过此接口删除;即使未找到记录,符合格式的删除请求仍会成功返回。删除 nginx_config、error_page、openresty_config 或 site.listen-default-http-80 时会创建对应范围的节点同步任务。仅管理员可调用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
config_idpathstring是复合配置标识,必须为 {scope_name}-{scope_id}-{type}-{name} 四段;scope_name 只能是 region 或 node,scope_id 必须为数字。type 和 name 分别遵循服务端的小写命名规则。

响应

HTTP 200

业务结果使用 HTTP 200 返回。删除执行成功时不区分记录是否原本存在;管理员权限、全局作用域或标识格式不符合要求时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是配置删除成功提示。删除config成功
oneOf#1.datastring enum是成功时固定为空字符串。
oneOf#2.codestring enum是全局配置禁止删除、标识校验失败、管理员权限不足或认证失效的业务错误码。config-193 | config-194 | config-195 | config-196 | config-197 | config-198 | config-272 | login_required
oneOf#2.msgstring是删除前校验或权限失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/configs/{config_id}'
用户 API / 网站与安全 / 配置模板 / 查询单项主控配置

GET查询单项主控配置

GET /v1/configs/{config_id}

按作用域、类型和名称组成的复合标识读取一条主控配置。登录用户只可读取 site 类型的 clean_url、clean_dir、ip-unlock-max-limit、ip-unlock-max-per-limit、pre_cache_url,以及 system 类型的 recharge;其余标识要求管理员身份。普通用户读取 recharge 时不会取得支付密钥,仅取得默认支付方式和转账说明。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
config_idpathstring是复合配置标识,格式为 {scope_name}-{scope_id}-{type}-{name}。服务端以前三个连字符切分,因此 name 可以包含连字符,例如 global-0-system-recharge。

响应

HTTP 200

业务结果使用 HTTP 200 返回。记录不存在时 data 为 null;普通用户读取充值配置时返回脱敏后的支付配置,权限不足或认证失效时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring是详情读取成功时固定为 null。
oneOf#1.dataoneOf是按配置名称与当前账户权限返回的配置记录或脱敏支付配置。
oneOf#1.data(oneOf#1).namestring是配置名称。
oneOf#1.data(oneOf#1).valuestring是数据库保存的原始配置值;JSON 配置仍以 JSON 文本字符串返回。
oneOf#1.data(oneOf#1).typestring是配置类型。
oneOf#1.data(oneOf#1).scope_idinteger(int64)是配置作用域实体 ID。
oneOf#1.data(oneOf#1).scope_namestring是配置作用域名称。
oneOf#1.data(oneOf#1).create_atstring是配置创建时间。
oneOf#1.data(oneOf#1).update_atstring是配置最后更新时间。
oneOf#1.data(oneOf#1).enableinteger enum是配置启用状态:1 启用,0 禁用。0 | 1
oneOf#1.data(oneOf#1).task_idinteger(int64)是最近一次配置同步任务 ID;没有同步任务时为 null。
oneOf#1.data(oneOf#1).statestring是关联同步任务的当前状态;无任务时为 null。
oneOf#1.data(oneOf#1).retstring是关联同步任务的返回内容;无任务时为 null。
oneOf#1.data(oneOf#1).task_typestring是关联同步任务类型;无任务时为 null。
oneOf#1.data(oneOf#2).default-paystring是默认支付渠道标识。
oneOf#1.data(oneOf#2).transferobject是转账支付的公开配置。
oneOf#1.data(oneOf#2).transfer.stateboolean是转账支付启用状态。
oneOf#1.data(oneOf#2).transfer.datastring是转账支付说明或数据。
oneOf#1.data(oneOf#2).wxpayobject是脱敏后的微信支付配置。
oneOf#1.data(oneOf#2).wxpay.stateboolean是微信支付启用状态。
oneOf#1.data(oneOf#2).wxpay.subtypestring是微信支付子类型;未配置时为空字符串。
oneOf#1.data(oneOf#2).alipayobject是脱敏后的支付宝配置。
oneOf#1.data(oneOf#2).alipay.stateboolean是支付宝启用状态。
oneOf#1.data(oneOf#2).alipay.subtypestring是支付宝支付子类型;未配置时为空字符串。
oneOf#2.codestring enum是config-273 表示需要管理员权限;login_required 表示认证无效。config-273 | login_required
oneOf#2.msgstring是权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": null }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/configs/{config_id}'
用户 API / 网站与安全 / 配置模板 / 按标识新增或更新主控配置

PUT按标识新增或更新主控配置

PUT /v1/configs/{config_id}

从路径复合标识取得 scope_name、scope_id、type、name,并以请求体的 value、enable 写入配置。路径中不存在的配置会被创建,已存在的配置会更新;请求体中的同名定位字段会被路径值覆盖。具体 type、name 可能触发同步任务和额外校验。仅管理员可调用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
config_idpathstring是复合配置标识,格式为 {scope_name}-{scope_id}-{type}-{name}。服务端以前三个连字符切分,因此 name 可包含连字符。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
valueoneOf是配置值。服务端会转为字符串保存;需要 JSON 的配置必须传 JSON 文本字符串。
value(oneOf#1)string否
value(oneOf#2)integer否
value(oneOf#3)number否
value(oneOf#4)boolean否
enableinteger enum否可选启用状态:1 启用,0 禁用;省略时新建配置默认启用,更新配置保持原状态。0 | 1

请求体示例

{ "value": "{\"email\":\"native\",\"phone\":\"\"}", "enable": 1 }

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时表示配置已写入;路径格式、管理员权限或配置值校验失败时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是配置写入成功提示。更新config成功
oneOf#1.datastring enum是成功时固定为空字符串。
oneOf#2.codestring是业务错误码,例如管理员权限错误 config-275 或配置值校验错误 config-2 至 config-300。
oneOf#2.msgstring是路径、权限或配置值校验失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"value":"{\"email\":\"native\",\"phone\":\"\"}","enable":1}' \ 'https://master.example.com/v1/configs/{config_id}'
用户 API / 网站与安全 / 配置模板 / 获取站点系统配置

GET获取站点系统配置

GET /v1/site-sys-config

读取全局 OpenResty 配置中供站点使用的默认临时白名单时长和封禁时长。接口要求登录,不区分普通用户与管理员。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

响应

HTTP 200

成功或未登录均返回 HTTP 200。成功时 `msg` 为 null。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是成功时固定为 null。
oneOf#1.dataobject是网站 CC 防护的默认白名单与封禁时间配置。
oneOf#1.data.white_timeinteger是默认临时白名单时长,单位为秒。21600
oneOf#1.data.block_timeinteger是默认封禁时长,单位为秒。3600
oneOf#2.codestring enum是未登录时的业务错误码。login_required
oneOf#2.msgstring是认证失败原因。
oneOf#2.datastring enum是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "white_time": 21600, "block_time": 3600 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/site-sys-config'
用户 API / 网站与安全 / 网站管理

网站管理

网站的创建、查询、更新和删除。

接口列表

GET
/v1/sites
查询网站列表 — 按条件分页查询网站,默认按网站 ID 倒序返回。普通用户始终只查询自己的网站;管理员可查询全部或以 `uid` 筛选指定用户。`action=export` 时
POST
/v1/sites
创建网站 — 为当前登录用户创建一个或多个七层网站。请求体可以是单个网站对象,也可以是网站对象数组;每个对象必须提供域名和至少一个可用源站。未提供的监听、回源及安全配置由当前
PUT
/v1/sites
批量更新网站 — 批量更新网站配置。请求体可为单个对象或对象数组;单个对象会被转换为数组处理。每个对象必须包含已有网站的 `id`,仅传入需要修改的字段。普通用户只能更新自己的网
DELETE
/v1/sites/{site_id}
删除网站 — 删除一个或多个网站。路径参数可使用单个网站 ID,也可使用英文逗号分隔的多个 ID。每个网站都必须存在、属于当前用户(否则需管理员权限)、处于禁用状态,且没有未
GET
/v1/sites/{site_id}
获取网站详情 — 获取指定网站的完整配置、套餐、线路和任务状态。普通用户只能读取自己的网站;读取其他用户的网站需要管理员权限。配置类字段按数据库原值返回,其中多项为 JSON 字
PUT
/v1/sites/{site_id}
更新指定网站 — 更新一个网站的指定配置。路径中的 `site_id` 会强制写入请求对象,客户端传入的同名字段会被覆盖;请求体必须是 JSON 对象而非数组。仅传需要修改的字段
用户 API / 网站与安全 / 网站管理 / 查询网站列表

GET查询网站列表

GET /v1/sites

按条件分页查询网站,默认按网站 ID 倒序返回。普通用户始终只查询自己的网站;管理员可查询全部或以 `uid` 筛选指定用户。`action=export` 时不分页并返回 CSV 下载,而非 JSON。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger否页码,必须为数字,默认 1。
limitqueryinteger否每页条数,必须为数字,默认 10;传 0 时不分页。导出模式会忽略该值。
domainquerystring否按网站域名字段进行包含匹配。example.invalid
domainsquerystring否按域名精确匹配网站域名列表中的完整项;服务端会校验域名格式。example.invalid
backend_ipquerystring否按回源配置 JSON 中包含的源站 IP 文本筛选。192.0.2.10
groupqueryinteger否网站组 ID 筛选。
idquerystring否网站 ID 列表,以英文逗号分隔;每项必须是数字。101,102
uidqueryinteger否仅管理员有效:按网站所属用户 ID 筛选。
user_packagequeryinteger否按用户套餐 ID 筛选。
packagequeryinteger否按基础套餐 ID 筛选。
regionqueryinteger否按区域 ID 筛选。
node_groupqueryinteger否按主线路组 ID 筛选。
cname_domainqueryinteger否按站点 CNAME 域名配置 ID 筛选。
cname_hostnamequerystring否按站点 CNAME 主机名前缀精确筛选。
http_listen_portqueryinteger否按 HTTP 监听端口筛选,必须是有效端口。
https_listen_portqueryinteger否按 HTTPS 监听端口筛选,必须是有效端口。
https_enablequerystring否非空时按 HTTPS 是否启用筛选:`1` 为已启用,其他非空值为未启用。
enablequerystring否非空时按网站是否启用筛选:`1` 为启用,其他非空值为停用。
is_default_serverquerystring否非空时按是否默认站点筛选:`1` 为默认,其他非空值为非默认。
sync_statequerystring否按网站同步任务状态精确筛选。pending
statequerystring否按网站业务状态精确筛选。normal
actionquerystring否返回方式:`search` 返回 JSON 列表(默认);`export` 返回全部匹配项的 CSV 文件。

响应

HTTP 200

`search` 成功时返回 JSON;`export` 成功时返回 CSV。参数或认证错误仍返回 HTTP 200 的 JSON 业务错误。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.countinteger是匹配网站总数,未受分页影响。
oneOf#1.dataarray是当前页网站记录。JSON 配置字段保持数据库存储的 JSON 文本,调用方需自行解析。
oneOf#1.dataarray<object>否当前页网站记录。JSON 配置字段保持数据库存储的 JSON 文本,调用方需自行解析。
oneOf#1.data[].idinteger否网站 ID。
oneOf#1.data[].uidinteger否所属用户 ID。
oneOf#1.data[].namestring否所属用户用户名。
oneOf#1.data[].user_packageinteger否用户套餐 ID。
oneOf#1.data[].package_idinteger否基础套餐 ID。
oneOf#1.data[].package_namestring否用户套餐名称。
oneOf#1.data[].region_idinteger否区域 ID。
oneOf#1.data[].region_namestring否区域名称。
oneOf#1.data[].node_group_idinteger否主线路组 ID。
oneOf#1.data[].node_group_namestring否主线路组名称。
oneOf#1.data[].backup_node_groupinteger否备用线路组 ID。
oneOf#1.data[].backup_node_group_namestring否备用线路组名称。
oneOf#1.data[].domainstring否网站域名列表,使用空白字符分隔。
oneOf#1.data[].cname_hostnamestring否站点 CNAME 主机名前缀。
oneOf#1.data[].cname_domainstring否站点 CNAME 域名。
oneOf#1.data[].cname_modestring否CNAME 使用模式。
oneOf#1.data[].up_cname_hostnamestring否用户套餐 CNAME 主机名前缀。
oneOf#1.data[].up_cname_domainstring否用户套餐 CNAME 域名。
oneOf#1.data[].record_idstring否DNS 记录 ID。
oneOf#1.data[].http_listenstring否HTTP 监听配置 JSON 文本。
oneOf#1.data[].https_listenstring否HTTPS 监听配置 JSON 文本。
oneOf#1.data[].backendstring否源站列表配置 JSON 文本。
oneOf#1.data[].backend_protocolstring否回源协议。
oneOf#1.data[].backend_http_portstring否回源 HTTP 端口。
oneOf#1.data[].backend_https_portstring否回源 HTTPS 端口。
oneOf#1.data[].backend_port_mappinginteger否是否跟随监听端口进行端口映射:1 为是。
oneOf#1.data[].backend_hoststring否回源 Host 配置。
oneOf#1.data[].balance_waystring否负载均衡方式。
oneOf#1.data[].enableinteger否是否启用:1 为启用,0 为停用。
oneOf#1.data[].site_statestring否网站业务状态。
oneOf#1.data[].statestring否网站状态字段。
oneOf#1.data[].sync_statestring否同步任务状态。
oneOf#1.data[].cname_statestring否CNAME 同步任务状态。
oneOf#1.data[].task_idinteger否网站同步任务 ID。
oneOf#1.data[].cname_task_idinteger否CNAME 任务 ID。
oneOf#1.data[].dependstring否同步任务依赖任务 ID 列表。
oneOf#1.data[].groupsstring否所属网站组 ID 聚合字符串,以英文逗号分隔。
oneOf#1.data[].group_namestring否所属网站组名称聚合字符串,以英文逗号分隔。
oneOf#1.data[].aclstring否ACL 配置。
oneOf#1.data[].cc_default_rulestring否默认 CC 规则 ID。
oneOf#1.data[].cc_switchstring否CC 自动切换配置 JSON 文本。
oneOf#1.data[].extra_cc_rulestring否附加 CC 规则配置 JSON 文本。
oneOf#1.data[].block_proxyinteger否是否拦截代理访问:1 为拦截。
oneOf#1.data[].block_regionstring否地区拦截配置。
oneOf#1.data[].spider_allowstring否爬虫放行配置。
oneOf#1.data[].corsstring否CORS 配置 JSON 文本。
oneOf#1.data[].gzip_enableinteger否是否启用 Gzip:1 为启用。
oneOf#1.data[].gzip_typesstring否Gzip MIME 类型配置。
oneOf#1.data[].health_checkstring否健康检查配置 JSON 文本。
oneOf#1.data[].hotlinkstring否防盗链配置 JSON 文本。
oneOf#1.data[].proxy_cachestring否代理缓存配置 JSON 文本。
oneOf#1.data[].proxy_http_versionstring否回源 HTTP 版本。
oneOf#1.data[].proxy_ssl_protocolsstring否回源 TLS 协议配置。
oneOf#1.data[].proxy_timeoutstring否代理超时配置。
oneOf#1.data[].post_size_limitstring否请求体大小限制。
oneOf#1.data[].rangeinteger否是否支持 Range:1 为支持。
oneOf#1.data[].url_rewritestring否URL 重写配置 JSON 文本。
oneOf#1.data[].websocket_enableinteger否是否启用 WebSocket:1 为启用。
oneOf#1.data[].enable_backup_groupinteger否是否启用备用线路组:1 为启用。
oneOf#1.data[].ups_keepaliveinteger否是否启用回源长连接。
oneOf#1.data[].ups_keepalive_connstring否回源长连接数量。
oneOf#1.data[].ups_keepalive_timeoutstring否回源长连接空闲超时。
oneOf#1.data[].acme_proxy_to_orgininteger否ACME 请求是否回源:1 为是。
oneOf#1.data[].create_atstring否创建时间。
oneOf#1.data[].create_at2string否格式化创建时间,`YYYY-MM-DD HH:mm:ss`。
oneOf#1.data[].update_atstring否更新时间。
oneOf#1.data[].update_at2string否格式化更新时间,`YYYY-MM-DD HH:mm:ss`。
oneOf#1.data[].end_atstring否用户套餐到期时间,`YYYY-MM-DD HH:mm:ss`。
oneOf#1.data[].versioninteger否网站配置版本。
oneOf#2.codestring enum是页码/分页、端口、域名、ID、action 参数或认证失败的业务错误码。site-128 | site-129 | site-172 | site-173 | site-327 | site-369 | site-373 | login_required
oneOf#2.msgstring是错误原因。
oneOf#2.datastring enum是错误响应中的固定空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/sites'
用户 API / 网站与安全 / 网站管理 / 创建网站

POST创建网站

POST /v1/sites

为当前登录用户创建一个或多个七层网站。请求体可以是单个网站对象,也可以是网站对象数组;每个对象必须提供域名和至少一个可用源站。未提供的监听、回源及安全配置由当前区域和用户默认配置补齐。管理员可额外指定归属用户、套餐、区域和线路。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
oneOf#1.domainstring是必填。网站域名,多个域名以空白字符分隔;会转为小写,不能重复,且受单站与套餐域名配额限制。
oneOf#1.backendarray是必填。源站列表,至少一个源站状态为 `up`,且地址不得重复。
oneOf#1.backendarray<object>否必填。源站列表,至少一个源站状态为 `up`,且地址不得重复。
oneOf#1.backend[].addrstring是必填。源站 IPv4、IPv6 或域名。
oneOf#1.backend[].weightinteger否源站权重;新建省略时默认为 1。
oneOf#1.backend[].statestring enum否源站状态;新建省略时默认为 `up`。up | down | backup
oneOf#1.user_packageinteger否用户套餐 ID;当前用户有多个套餐时必须指定。
oneOf#1.http_listenobject否HTTP 监听;与 HTTPS 至少启用一个。
oneOf#1.http_listen.portstring否空白分隔的监听端口;省略时使用默认端口。
oneOf#1.https_listenobject否HTTPS 监听;需要已启用的证书,或与 `auto_cert=1` 一起使用。
oneOf#1.https_listen.portstring否空白分隔的 HTTPS 监听端口。
oneOf#1.https_listen.certinteger否证书 ID。
oneOf#1.https_listen.hstsinteger enum否是否启用 HSTS。0 | 1
oneOf#1.https_listen.http2integer enum否是否启用 HTTP/2。0 | 1
oneOf#1.https_listen.http3integer enum否是否启用 HTTP/3。0 | 1
oneOf#1.https_listen.force_ssl_enableinteger enum否是否强制跳转 HTTPS。0 | 1
oneOf#1.https_listen.force_ssl_portstring否强制跳转的 HTTPS 端口。
oneOf#1.auto_certinteger enum否是否自动申请证书。0 | 1
oneOf#1.balance_waystring enum否负载均衡方式。ip_hash | rr
oneOf#1.backend_protocolstring enum否回源协议。follow | http | https
oneOf#1.backend_http_portinteger否HTTP 回源端口。
oneOf#1.backend_https_portinteger否HTTPS 回源端口。
oneOf#1.proxy_timeoutinteger否回源读取超时秒数。
oneOf#1.proxy_connect_timeoutinteger否回源连接超时秒数。
oneOf#1.health_checkobject否源站健康检查配置。
oneOf#1.health_check.enableinteger enum否是否启用检查。0 | 1
oneOf#1.health_check.hoststring否检查请求的 Host。
oneOf#1.health_check.pathstring否检查路径,必须以 `/` 开头。
oneOf#1.proxy_cacheinteger enum否是否启用代理缓存。0 | 1
oneOf#1.gzip_enableinteger enum否是否启用 Gzip。0 | 1
oneOf#1.websocket_enableinteger enum否是否启用 WebSocket 代理。0 | 1
oneOf#1.aclinteger否ACL ID;传 null 或 0 表示不绑定。ACL 必须已启用且属于当前目标用户,否则要求管理员权限。12
oneOf#1.acme_proxy_to_orgininteger enum否是否将 `/.well-known/acme-challenge/` 请求回源:1 开启,0 关闭。1
oneOf#1.backend_hoststring否回源 Host。允许 `$host`、`$host:$server_port`,或合法域名/IP及可选端口。$host
oneOf#1.backend_port_mappinginteger enum否是否按客户端访问协议和端口进行回源端口映射。1
oneOf#1.backup_node_groupinteger否管理员专用。备用线路组 ID;必须与区域匹配且不能与主线路组相同。22
oneOf#1.black_ipstring否网站黑名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。198.51.100.0/24
oneOf#1.block_proxyinteger enum否是否拦截被识别为代理的客户端。1
oneOf#1.block_regionstring否按两字母小写国家/地区代码拦截,多个值以逗号分隔;空字符串表示关闭。us,jp
oneOf#1.block_timeinteger否自动黑名单持续时间,单位秒;非空时必须大于 600 且不超过 604800。3600
oneOf#1.cc_default_ruleinteger否默认 CC 规则 ID;规则必须存在且启用,使用其他用户的非内置规则需要管理员权限。10002
oneOf#1.cc_switchobject否CC 规则自动切换配置;空对象表示关闭。{"rule":10002,"switch":100,"enable":1}
oneOf#1.cc_switch.ruleinteger是切换后的 CC 规则 ID。10002
oneOf#1.cc_switch.switchinteger是触发切换的请求阈值。100
oneOf#1.cc_switch.enableinteger enum否是否启用自动切换。1
oneOf#1.cname_hostnamestring否管理员专用。网站 CNAME 主机名;各标签必须合法且在系统内唯一。site-a1b2c3
oneOf#1.condition_backendarray否按请求条件选择源站的规则列表。[{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}]
oneOf#1.condition_backendarray<object>否按请求条件选择源站的规则列表。[{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}]
oneOf#1.condition_backend[].matcherarray是全部匹配条件。
oneOf#1.condition_backend[].matcherarray<object>否全部匹配条件。
oneOf#1.condition_backend[].matcher[].itemstring是匹配项。req_uri
oneOf#1.condition_backend[].matcher[].opstring enum是匹配操作符。contain
oneOf#1.condition_backend[].matcher[].valuestring是匹配值;服务端会去除空行和首尾空白。/api/
oneOf#1.condition_backend[].backendarray是命中后使用的源站列表。
oneOf#1.condition_backend[].backendarray<object>否命中后使用的源站列表。
oneOf#1.condition_backend[].backend[].addrstring是源站 IPv4、IPv6 或域名。198.51.100.10
oneOf#1.condition_backend[].backend[].weightinteger否源站权重。1
oneOf#1.condition_backend[].backend[].statestring enum否源站状态。up
oneOf#1.cookie_domainstring否Cookie Domain;允许空字符串,非空时必须是合法域名。example.invalid
oneOf#1.corsobject否跨域响应配置。{"enable":1,"allow_origin":"*","allow_methods":"GET POST OPTIONS","allow_headers":"Content-Type","expose_headers":"Content-Length","allow_credentials":0,"max_age":"1728000"}
oneOf#1.cors.enableinteger enum是是否启用 CORS。1
oneOf#1.cors.allow_originstring是Access-Control-Allow-Origin 值。*
oneOf#1.cors.allow_methodsstring是允许的方法,空格分隔。GET POST OPTIONS
oneOf#1.cors.allow_headersstring是允许的请求头,空格分隔。Content-Type Authorization
oneOf#1.cors.expose_headersstring是允许浏览器读取的响应头。Content-Length
oneOf#1.cors.allow_credentialsinteger enum是是否允许携带凭证。1
oneOf#1.cors.max_agestring是预检结果缓存秒数;服务端要求传数字字符串。1728000
oneOf#1.dns_apiinteger否DNS API 凭据 ID;必须属于目标用户。传 null 表示不绑定。8
oneOf#1.enableinteger enum否网站启用状态:1 启用,0 禁用。1
oneOf#1.enable_ipv6integer enum否是否启用 IPv6 CNAME;仅按网站生成 CNAME 且系统存在 IPv6 节点时可用。1
oneOf#1.extra_cc_rulearray否网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。[{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}]
oneOf#1.extra_cc_rulearray<object>否网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。[{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}]
oneOf#1.groupsstring否网站分组 ID,多个 ID 使用逗号分隔;空字符串表示不加入分组。3,8
oneOf#1.gzip_typesstring否启用 Gzip 的 MIME 类型,使用空格分隔;每项只能含字母、数字及 `/ - + . * _`。text/plain text/css application/json
oneOf#1.hotlinkobject否防盗链配置。{"enable":1,"domain":"www.example.invalid","allow_empty":0,"scope_type":"all","scope_content":""}
oneOf#1.hotlink.enableinteger enum是是否启用防盗链。1
oneOf#1.hotlink.domainstring是允许的来源域名,使用空格分隔;空值仅允许本站域名。www.example.invalid
oneOf#1.hotlink.allow_emptyinteger enum是是否允许空 Referer。1
oneOf#1.hotlink.scope_typestring enum否生效范围。all
oneOf#1.hotlink.scope_contentstring否非 all 范围的匹配内容。/static/
oneOf#1.is_default_serverinteger enum否管理员专用。是否作为线路范围内的默认站点;同一节点的监听端口不能与其它默认站点冲突。1
oneOf#1.l2_config_idinteger否管理员专用。L2 配置 ID;必须存在、与网站区域一致并已绑定 L2 节点。9
oneOf#1.l2_statestring enum否管理员专用。L2 模式。inherit
oneOf#1.log_req_bodyinteger enum否管理员专用。是否记录请求体。1
oneOf#1.log_req_body_max_sizeinteger否管理员专用。记录请求体的最大 KiB;不能超过 2048,也不能超过全局 client_body_buffer_size。16
oneOf#1.log_req_headerinteger enum否管理员专用。是否记录请求头。1
oneOf#1.log_resp_headerinteger enum否管理员专用。是否记录响应头。1
oneOf#1.node_group_idinteger否管理员专用。主线路组 ID;必须属于目标区域;按套餐生成 CNAME 时不能单独指定。21
oneOf#1.page_403string否自定义 403 错误页 HTML;空字符串使用默认页面。<h1>Forbidden</h1>
oneOf#1.page_404string否自定义 404 错误页 HTML;空字符串使用默认页面。<h1>Not Found</h1>
oneOf#1.page_500string否自定义 500 错误页 HTML;空字符串使用默认页面。<h1>Server Error</h1>
oneOf#1.page_502string否自定义 502 错误页 HTML;空字符串使用默认页面。<h1>Bad Gateway</h1>
oneOf#1.page_504string否自定义 504 错误页 HTML;空字符串使用默认页面。<h1>Gateway Timeout</h1>
oneOf#1.post_size_limitstring否POST 请求体大小限制。可使用纯数字或 b/k/m/g 单位,大小写均可;空字符串表示采用默认配置。10m
oneOf#1.proxy_authobject否回源 Basic Auth 配置。{"enable":1,"username":"origin-user","password":"REDACTED"}
oneOf#1.proxy_auth.enableinteger enum是是否启用回源认证。1
oneOf#1.proxy_auth.usernamestring否认证用户名。origin-user
oneOf#1.proxy_auth.passwordstring否认证密码。REDACTED
oneOf#1.proxy_http_versionstring enum否回源 HTTP 协议版本。1.1
oneOf#1.proxy_ssl_protocolsstring否允许的回源 TLS/SSL 协议,多个值使用空格分隔。TLSv1.2 TLSv1.3
oneOf#1.rangeinteger enum否是否启用分段回源。1
oneOf#1.recv_real_timeinteger enum否是否实时向客户端返回上游响应数据。1
oneOf#1.region_idinteger否管理员专用。区域 ID;主、备用线路组必须属于该区域。6
oneOf#1.req_headerarray否添加或覆盖的回源请求头。[{"name":"X-Origin","value":"cdnfly"}]
oneOf#1.req_headerarray<object>否添加或覆盖的回源请求头。[{"name":"X-Origin","value":"cdnfly"}]
oneOf#1.req_header[].namestring是请求头名称,必须以英文字母开头。X-Example
oneOf#1.req_header[].valuestring是请求头值,去除首尾空白后不能为空。example-value
oneOf#1.resp_headerarray否添加或覆盖的客户端响应头。[{"name":"X-Cache","value":"cdnfly"}]
oneOf#1.resp_headerarray<object>否添加或覆盖的客户端响应头。[{"name":"X-Cache","value":"cdnfly"}]
oneOf#1.resp_header[].namestring是请求头名称,必须以英文字母开头。X-Example
oneOf#1.resp_header[].valuestring是请求头值,去除首尾空白后不能为空。example-value
oneOf#1.send_real_timeinteger enum否是否实时向上游发送客户端请求数据。1
oneOf#1.spider_allowstring enum否搜索引擎爬虫访问策略;空字符串表示不单独设置。allow
oneOf#1.spider_to_sipstring否搜索引擎专用回源 IP;空字符串表示关闭。仅按网站生成 CNAME 且 DNS 服务支持对应线路时可用。198.51.100.20
oneOf#1.statestring enum否管理员专用。网站业务状态。200
oneOf#1.uidinteger否管理员专用。创建时指定网站所属用户;更新转移网站时与 new_uid 配合,作为目标套餐归属校验用户。12
oneOf#1.ups_keepaliveinteger enum否是否启用上游 Keepalive。1
oneOf#1.ups_keepalive_conninteger否每个 worker 保留的上游 Keepalive 连接数。16
oneOf#1.ups_keepalive_timeoutinteger否上游 Keepalive 空闲超时秒数。60
oneOf#1.url_rewritearray否URL 重定向规则。[{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}]
oneOf#1.url_rewritearray<object>否URL 重定向规则。[{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}]
oneOf#1.url_rewrite[].hoststring是匹配 Host,不含 http:// 或 https://。www.example.invalid
oneOf#1.url_rewrite[].matchstring是URI 匹配表达式。/(.*)
oneOf#1.url_rewrite[].redirectstring是重定向目标;可使用 `$1` 或受支持的 Nginx 变量。https://example.invalid/$1
oneOf#1.url_rewrite[].codestring enum是重定向方式。301
oneOf#1.url_rewrite[].user_agentstring否User-Agent 匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].refererstring否Referer 匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].country_codestring否国家代码匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].accept_languagestring否Accept-Language 匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].provincestring否省份匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].citystring否城市匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].ispstring否运营商匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].asnumberstring否ASN 匹配;省略时为 `.*`。.*
oneOf#1.white_ipstring否网站白名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。203.0.113.10
oneOf#1.white_timeinteger否自动白名单持续时间,单位秒;非空时不超过 604800。3600
oneOf#2array<object>否批量创建;数组中的每个元素独立按网站创建规则校验。
oneOf#2[].domainstring是必填。网站域名,多个域名以空白字符分隔;会转为小写,不能重复,且受单站与套餐域名配额限制。
oneOf#2[].backendarray是必填。源站列表,至少一个源站状态为 `up`,且地址不得重复。
oneOf#2[].backendarray<object>否必填。源站列表,至少一个源站状态为 `up`,且地址不得重复。
oneOf#2[].backend[].addrstring是必填。源站 IPv4、IPv6 或域名。
oneOf#2[].backend[].weightinteger否源站权重;新建省略时默认为 1。
oneOf#2[].backend[].statestring enum否源站状态;新建省略时默认为 `up`。up | down | backup
oneOf#2[].user_packageinteger否用户套餐 ID;当前用户有多个套餐时必须指定。
oneOf#2[].http_listenobject否HTTP 监听;与 HTTPS 至少启用一个。
oneOf#2[].http_listen.portstring否空白分隔的监听端口;省略时使用默认端口。
oneOf#2[].https_listenobject否HTTPS 监听;需要已启用的证书,或与 `auto_cert=1` 一起使用。
oneOf#2[].https_listen.portstring否空白分隔的 HTTPS 监听端口。
oneOf#2[].https_listen.certinteger否证书 ID。
oneOf#2[].https_listen.hstsinteger enum否是否启用 HSTS。0 | 1
oneOf#2[].https_listen.http2integer enum否是否启用 HTTP/2。0 | 1
oneOf#2[].https_listen.http3integer enum否是否启用 HTTP/3。0 | 1
oneOf#2[].https_listen.force_ssl_enableinteger enum否是否强制跳转 HTTPS。0 | 1
oneOf#2[].https_listen.force_ssl_portstring否强制跳转的 HTTPS 端口。
oneOf#2[].auto_certinteger enum否是否自动申请证书。0 | 1
oneOf#2[].balance_waystring enum否负载均衡方式。ip_hash | rr
oneOf#2[].backend_protocolstring enum否回源协议。follow | http | https
oneOf#2[].backend_http_portinteger否HTTP 回源端口。
oneOf#2[].backend_https_portinteger否HTTPS 回源端口。
oneOf#2[].proxy_timeoutinteger否回源读取超时秒数。
oneOf#2[].proxy_connect_timeoutinteger否回源连接超时秒数。
oneOf#2[].health_checkobject否源站健康检查配置。
oneOf#2[].health_check.enableinteger enum否是否启用检查。0 | 1
oneOf#2[].health_check.hoststring否检查请求的 Host。
oneOf#2[].health_check.pathstring否检查路径,必须以 `/` 开头。
oneOf#2[].proxy_cacheinteger enum否是否启用代理缓存。0 | 1
oneOf#2[].gzip_enableinteger enum否是否启用 Gzip。0 | 1
oneOf#2[].websocket_enableinteger enum否是否启用 WebSocket 代理。0 | 1
oneOf#2[].aclinteger否ACL ID;传 null 或 0 表示不绑定。ACL 必须已启用且属于当前目标用户,否则要求管理员权限。12
oneOf#2[].acme_proxy_to_orgininteger enum否是否将 `/.well-known/acme-challenge/` 请求回源:1 开启,0 关闭。1
oneOf#2[].backend_hoststring否回源 Host。允许 `$host`、`$host:$server_port`,或合法域名/IP及可选端口。$host
oneOf#2[].backend_port_mappinginteger enum否是否按客户端访问协议和端口进行回源端口映射。1
oneOf#2[].backup_node_groupinteger否管理员专用。备用线路组 ID;必须与区域匹配且不能与主线路组相同。22
oneOf#2[].black_ipstring否网站黑名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。198.51.100.0/24
oneOf#2[].block_proxyinteger enum否是否拦截被识别为代理的客户端。1
oneOf#2[].block_regionstring否按两字母小写国家/地区代码拦截,多个值以逗号分隔;空字符串表示关闭。us,jp
oneOf#2[].block_timeinteger否自动黑名单持续时间,单位秒;非空时必须大于 600 且不超过 604800。3600
oneOf#2[].cc_default_ruleinteger否默认 CC 规则 ID;规则必须存在且启用,使用其他用户的非内置规则需要管理员权限。10002
oneOf#2[].cc_switchobject否CC 规则自动切换配置;空对象表示关闭。{"rule":10002,"switch":100,"enable":1}
oneOf#2[].cc_switch.ruleinteger是切换后的 CC 规则 ID。10002
oneOf#2[].cc_switch.switchinteger是触发切换的请求阈值。100
oneOf#2[].cc_switch.enableinteger enum否是否启用自动切换。1
oneOf#2[].cname_hostnamestring否管理员专用。网站 CNAME 主机名;各标签必须合法且在系统内唯一。site-a1b2c3
oneOf#2[].condition_backendarray否按请求条件选择源站的规则列表。[{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}]
oneOf#2[].condition_backendarray<object>否按请求条件选择源站的规则列表。[{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}]
oneOf#2[].condition_backend[].matcherarray是全部匹配条件。
oneOf#2[].condition_backend[].matcherarray<object>否全部匹配条件。
oneOf#2[].condition_backend[].matcher[].itemstring是匹配项。req_uri
oneOf#2[].condition_backend[].matcher[].opstring enum是匹配操作符。contain
oneOf#2[].condition_backend[].matcher[].valuestring是匹配值;服务端会去除空行和首尾空白。/api/
oneOf#2[].condition_backend[].backendarray是命中后使用的源站列表。
oneOf#2[].condition_backend[].backendarray<object>否命中后使用的源站列表。
oneOf#2[].condition_backend[].backend[].addrstring是源站 IPv4、IPv6 或域名。198.51.100.10
oneOf#2[].condition_backend[].backend[].weightinteger否源站权重。1
oneOf#2[].condition_backend[].backend[].statestring enum否源站状态。up
oneOf#2[].cookie_domainstring否Cookie Domain;允许空字符串,非空时必须是合法域名。example.invalid
oneOf#2[].corsobject否跨域响应配置。{"enable":1,"allow_origin":"*","allow_methods":"GET POST OPTIONS","allow_headers":"Content-Type","expose_headers":"Content-Length","allow_credentials":0,"max_age":"1728000"}
oneOf#2[].cors.enableinteger enum是是否启用 CORS。1
oneOf#2[].cors.allow_originstring是Access-Control-Allow-Origin 值。*
oneOf#2[].cors.allow_methodsstring是允许的方法,空格分隔。GET POST OPTIONS
oneOf#2[].cors.allow_headersstring是允许的请求头,空格分隔。Content-Type Authorization
oneOf#2[].cors.expose_headersstring是允许浏览器读取的响应头。Content-Length
oneOf#2[].cors.allow_credentialsinteger enum是是否允许携带凭证。1
oneOf#2[].cors.max_agestring是预检结果缓存秒数;服务端要求传数字字符串。1728000
oneOf#2[].dns_apiinteger否DNS API 凭据 ID;必须属于目标用户。传 null 表示不绑定。8
oneOf#2[].enableinteger enum否网站启用状态:1 启用,0 禁用。1
oneOf#2[].enable_ipv6integer enum否是否启用 IPv6 CNAME;仅按网站生成 CNAME 且系统存在 IPv6 节点时可用。1
oneOf#2[].extra_cc_rulearray否网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。[{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}]
oneOf#2[].extra_cc_rulearray<object>否网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。[{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}]
oneOf#2[].groupsstring否网站分组 ID,多个 ID 使用逗号分隔;空字符串表示不加入分组。3,8
oneOf#2[].gzip_typesstring否启用 Gzip 的 MIME 类型,使用空格分隔;每项只能含字母、数字及 `/ - + . * _`。text/plain text/css application/json
oneOf#2[].hotlinkobject否防盗链配置。{"enable":1,"domain":"www.example.invalid","allow_empty":0,"scope_type":"all","scope_content":""}
oneOf#2[].hotlink.enableinteger enum是是否启用防盗链。1
oneOf#2[].hotlink.domainstring是允许的来源域名,使用空格分隔;空值仅允许本站域名。www.example.invalid
oneOf#2[].hotlink.allow_emptyinteger enum是是否允许空 Referer。1
oneOf#2[].hotlink.scope_typestring enum否生效范围。all
oneOf#2[].hotlink.scope_contentstring否非 all 范围的匹配内容。/static/
oneOf#2[].is_default_serverinteger enum否管理员专用。是否作为线路范围内的默认站点;同一节点的监听端口不能与其它默认站点冲突。1
oneOf#2[].l2_config_idinteger否管理员专用。L2 配置 ID;必须存在、与网站区域一致并已绑定 L2 节点。9
oneOf#2[].l2_statestring enum否管理员专用。L2 模式。inherit
oneOf#2[].log_req_bodyinteger enum否管理员专用。是否记录请求体。1
oneOf#2[].log_req_body_max_sizeinteger否管理员专用。记录请求体的最大 KiB;不能超过 2048,也不能超过全局 client_body_buffer_size。16
oneOf#2[].log_req_headerinteger enum否管理员专用。是否记录请求头。1
oneOf#2[].log_resp_headerinteger enum否管理员专用。是否记录响应头。1
oneOf#2[].node_group_idinteger否管理员专用。主线路组 ID;必须属于目标区域;按套餐生成 CNAME 时不能单独指定。21
oneOf#2[].page_403string否自定义 403 错误页 HTML;空字符串使用默认页面。<h1>Forbidden</h1>
oneOf#2[].page_404string否自定义 404 错误页 HTML;空字符串使用默认页面。<h1>Not Found</h1>
oneOf#2[].page_500string否自定义 500 错误页 HTML;空字符串使用默认页面。<h1>Server Error</h1>
oneOf#2[].page_502string否自定义 502 错误页 HTML;空字符串使用默认页面。<h1>Bad Gateway</h1>
oneOf#2[].page_504string否自定义 504 错误页 HTML;空字符串使用默认页面。<h1>Gateway Timeout</h1>
oneOf#2[].post_size_limitstring否POST 请求体大小限制。可使用纯数字或 b/k/m/g 单位,大小写均可;空字符串表示采用默认配置。10m
oneOf#2[].proxy_authobject否回源 Basic Auth 配置。{"enable":1,"username":"origin-user","password":"REDACTED"}
oneOf#2[].proxy_auth.enableinteger enum是是否启用回源认证。1
oneOf#2[].proxy_auth.usernamestring否认证用户名。origin-user
oneOf#2[].proxy_auth.passwordstring否认证密码。REDACTED
oneOf#2[].proxy_http_versionstring enum否回源 HTTP 协议版本。1.1
oneOf#2[].proxy_ssl_protocolsstring否允许的回源 TLS/SSL 协议,多个值使用空格分隔。TLSv1.2 TLSv1.3
oneOf#2[].rangeinteger enum否是否启用分段回源。1
oneOf#2[].recv_real_timeinteger enum否是否实时向客户端返回上游响应数据。1
oneOf#2[].region_idinteger否管理员专用。区域 ID;主、备用线路组必须属于该区域。6
oneOf#2[].req_headerarray否添加或覆盖的回源请求头。[{"name":"X-Origin","value":"cdnfly"}]
oneOf#2[].req_headerarray<object>否添加或覆盖的回源请求头。[{"name":"X-Origin","value":"cdnfly"}]
oneOf#2[].req_header[].namestring是请求头名称,必须以英文字母开头。X-Example
oneOf#2[].req_header[].valuestring是请求头值,去除首尾空白后不能为空。example-value
oneOf#2[].resp_headerarray否添加或覆盖的客户端响应头。[{"name":"X-Cache","value":"cdnfly"}]
oneOf#2[].resp_headerarray<object>否添加或覆盖的客户端响应头。[{"name":"X-Cache","value":"cdnfly"}]
oneOf#2[].resp_header[].namestring是请求头名称,必须以英文字母开头。X-Example
oneOf#2[].resp_header[].valuestring是请求头值,去除首尾空白后不能为空。example-value
oneOf#2[].send_real_timeinteger enum否是否实时向上游发送客户端请求数据。1
oneOf#2[].spider_allowstring enum否搜索引擎爬虫访问策略;空字符串表示不单独设置。allow
oneOf#2[].spider_to_sipstring否搜索引擎专用回源 IP;空字符串表示关闭。仅按网站生成 CNAME 且 DNS 服务支持对应线路时可用。198.51.100.20
oneOf#2[].statestring enum否管理员专用。网站业务状态。200
oneOf#2[].uidinteger否管理员专用。创建时指定网站所属用户;更新转移网站时与 new_uid 配合,作为目标套餐归属校验用户。12
oneOf#2[].ups_keepaliveinteger enum否是否启用上游 Keepalive。1
oneOf#2[].ups_keepalive_conninteger否每个 worker 保留的上游 Keepalive 连接数。16
oneOf#2[].ups_keepalive_timeoutinteger否上游 Keepalive 空闲超时秒数。60
oneOf#2[].url_rewritearray否URL 重定向规则。[{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}]
oneOf#2[].url_rewritearray<object>否URL 重定向规则。[{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}]
oneOf#2[].url_rewrite[].hoststring是匹配 Host,不含 http:// 或 https://。www.example.invalid
oneOf#2[].url_rewrite[].matchstring是URI 匹配表达式。/(.*)
oneOf#2[].url_rewrite[].redirectstring是重定向目标;可使用 `$1` 或受支持的 Nginx 变量。https://example.invalid/$1
oneOf#2[].url_rewrite[].codestring enum是重定向方式。301
oneOf#2[].url_rewrite[].user_agentstring否User-Agent 匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].refererstring否Referer 匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].country_codestring否国家代码匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].accept_languagestring否Accept-Language 匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].provincestring否省份匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].citystring否城市匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].ispstring否运营商匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].asnumberstring否ASN 匹配;省略时为 `.*`。.*
oneOf#2[].white_ipstring否网站白名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。203.0.113.10
oneOf#2[].white_timeinteger否自动白名单持续时间,单位秒;非空时不超过 604800。3600

请求体示例

{ "domain": "www.example.invalid api.example.invalid", "backend": [ { "addr": "198.51.100.10", "weight": 1, "state": "up" } ], "http_listen": { "port": "80" }, "backend_protocol": "http" }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0,`msg` 为“网站添加成功”,`data` 为新建网站 ID 组成的逗号分隔字符串;即使业务校验失败也返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0,失败时为对应的 site-* 错误码。0
msgstring是处理结果说明。网站添加成功
datastring是成功时为本次新建的网站 ID,多个 ID 使用英文逗号连接;失败时为空字符串。101,102

响应示例

{ "code": 0, "msg": "网站添加成功", "data": "101,102" }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"domain":"www.example.invalid api.example.invalid","backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}],"http_listen":{"port":"80"},"backend_protocol":"http"}' \ 'https://master.example.com/v1/sites'
用户 API / 网站与安全 / 网站管理 / 批量更新网站

PUT批量更新网站

PUT /v1/sites

批量更新网站配置。请求体可为单个对象或对象数组;单个对象会被转换为数组处理。每个对象必须包含已有网站的 `id`,仅传入需要修改的字段。普通用户只能更新自己的网站;管理员才能修改其他用户网站、归属用户、套餐、区域、线路和 CNAME 相关字段。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
oneOf#1.idinteger是必填。要更新的网站 ID,必须存在且当前用户有权限操作。
oneOf#1.domainstring否网站域名,多个域名以空白字符分隔;会转为小写且不得重复。修改后重新校验套餐配额、区域内域名和域名端口唯一性。
oneOf#1.backendarray否源站列表。每项地址必须为 IPv4、IPv6 或域名,地址不可重复,至少保留一个 `up` 状态源站。
oneOf#1.backendarray<object>否源站列表。每项地址必须为 IPv4、IPv6 或域名,地址不可重复,至少保留一个 `up` 状态源站。
oneOf#1.backend[].addrstring是源站地址。
oneOf#1.backend[].weightinteger是源站权重。
oneOf#1.backend[].statestring enum是源站状态。up | down | backup
oneOf#1.user_packageinteger否用户套餐 ID;必须属于网站归属用户且可用。变更套餐会重新同步相关线路与配置。
oneOf#1.new_uidinteger否管理员专用。将网站转移到指定用户;同时必须传入 `user_package`。
oneOf#1.uidinteger否管理员专用。指定本次套餐与资源校验所使用的用户 ID。
oneOf#1.http_listenobject否HTTP 监听配置;与 HTTPS 至少保留一个。
oneOf#1.http_listen.portstring否空白分隔的监听端口;每个端口必须有效、未占用且在区域允许范围内。
oneOf#1.https_listenobject否HTTPS 监听配置。
oneOf#1.https_listen.portstring否空白分隔的 HTTPS 监听端口。
oneOf#1.https_listen.certinteger否已启用证书 ID。
oneOf#1.https_listen.hstsinteger enum否是否启用 HSTS。0 | 1
oneOf#1.https_listen.http2integer enum否是否启用 HTTP/2。0 | 1
oneOf#1.https_listen.http3integer enum否是否启用 HTTP/3。0 | 1
oneOf#1.https_listen.ocsp_staplinginteger enum否是否启用 OCSP Stapling。0 | 1
oneOf#1.https_listen.force_ssl_enableinteger enum否是否强制跳转 HTTPS。0 | 1
oneOf#1.https_listen.force_ssl_portstring否强制跳转目标端口,必须在 HTTPS 监听端口中。
oneOf#1.https_listen.ssl_protocolsstring否允许的 TLS 协议,使用空白字符分隔。
oneOf#1.https_listen.ssl_ciphersstring否TLS 密码套件。
oneOf#1.https_listen.ssl_prefer_server_ciphersstring enum否是否优先使用服务端密码套件。on | off
oneOf#1.balance_waystring enum否负载均衡方式。`ip_hash` 不支持备用源站。ip_hash | rr
oneOf#1.backend_protocolstring enum否回源协议。follow | http | https
oneOf#1.backend_http_portinteger否HTTP 回源端口。
oneOf#1.backend_https_portinteger否HTTPS 回源端口。
oneOf#1.backend_port_mappinginteger enum否是否使用访问端口作为回源端口。0 | 1
oneOf#1.proxy_timeoutinteger否回源读取超时,单位秒。
oneOf#1.proxy_connect_timeoutinteger否回源连接超时,单位秒。
oneOf#1.health_checkobject否健康检查配置。
oneOf#1.health_check.enableinteger enum否是否启用健康检查。0 | 1
oneOf#1.health_check.hoststring否检查请求域名。
oneOf#1.health_check.pathstring否检查路径,必须以 `/` 开头。
oneOf#1.proxy_authobject否回源认证配置。
oneOf#1.proxy_auth.enableboolean否是否启用认证。
oneOf#1.proxy_auth.usernamestring否认证用户名。
oneOf#1.proxy_auth.passwordstring否认证密码。
oneOf#1.proxy_cacheinteger enum否是否启用代理缓存。0 | 1
oneOf#1.gzip_enableinteger enum否是否启用 Gzip。0 | 1
oneOf#1.gzip_typesstring否Gzip MIME 类型。
oneOf#1.websocket_enableinteger enum否是否启用 WebSocket 代理。0 | 1
oneOf#1.enableinteger enum否网站启用状态。0 | 1
oneOf#1.statestring否网站处理状态。
oneOf#1.cname_modestring enum否CNAME 使用方式;切换会触发相应同步任务。package | site
oneOf#1.cname_domaininteger否管理员专用。CNAME 域名配置 ID。
oneOf#1.cname_hostnamestring否管理员专用。网站 CNAME 主机名,必须唯一且合法。
oneOf#1.region_idinteger否管理员专用。区域 ID。
oneOf#1.node_group_idinteger否管理员专用。主线路组 ID;CNAME 按套餐时不能单独修改。
oneOf#1.backup_node_groupinteger否管理员专用。备用线路组 ID;不能与主线路组相同。
oneOf#1.aclinteger否ACL ID;传 null 或 0 表示不绑定。ACL 必须已启用且属于当前目标用户,否则要求管理员权限。12
oneOf#1.acme_proxy_to_orgininteger enum否是否将 `/.well-known/acme-challenge/` 请求回源:1 开启,0 关闭。1
oneOf#1.backend_hoststring否回源 Host。允许 `$host`、`$host:$server_port`,或合法域名/IP及可选端口。$host
oneOf#1.black_ipstring否网站黑名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。198.51.100.0/24
oneOf#1.block_proxyinteger enum否是否拦截被识别为代理的客户端。1
oneOf#1.block_regionstring否按两字母小写国家/地区代码拦截,多个值以逗号分隔;空字符串表示关闭。us,jp
oneOf#1.block_timeinteger否自动黑名单持续时间,单位秒;非空时必须大于 600 且不超过 604800。3600
oneOf#1.cc_default_ruleinteger否默认 CC 规则 ID;规则必须存在且启用,使用其他用户的非内置规则需要管理员权限。10002
oneOf#1.cc_switchobject否CC 规则自动切换配置;空对象表示关闭。{"rule":10002,"switch":100,"enable":1}
oneOf#1.cc_switch.ruleinteger是切换后的 CC 规则 ID。10002
oneOf#1.cc_switch.switchinteger是触发切换的请求阈值。100
oneOf#1.cc_switch.enableinteger enum否是否启用自动切换。1
oneOf#1.condition_backendarray否按请求条件选择源站的规则列表。[{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}]
oneOf#1.condition_backendarray<object>否按请求条件选择源站的规则列表。[{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}]
oneOf#1.condition_backend[].matcherarray是全部匹配条件。
oneOf#1.condition_backend[].matcherarray<object>否全部匹配条件。
oneOf#1.condition_backend[].matcher[].itemstring是匹配项。req_uri
oneOf#1.condition_backend[].matcher[].opstring enum是匹配操作符。contain
oneOf#1.condition_backend[].matcher[].valuestring是匹配值;服务端会去除空行和首尾空白。/api/
oneOf#1.condition_backend[].backendarray是命中后使用的源站列表。
oneOf#1.condition_backend[].backendarray<object>否命中后使用的源站列表。
oneOf#1.condition_backend[].backend[].addrstring是源站 IPv4、IPv6 或域名。198.51.100.10
oneOf#1.condition_backend[].backend[].weightinteger否源站权重。1
oneOf#1.condition_backend[].backend[].statestring enum否源站状态。up
oneOf#1.cookie_domainstring否Cookie Domain;允许空字符串,非空时必须是合法域名。example.invalid
oneOf#1.corsobject否跨域响应配置。{"enable":1,"allow_origin":"*","allow_methods":"GET POST OPTIONS","allow_headers":"Content-Type","expose_headers":"Content-Length","allow_credentials":0,"max_age":"1728000"}
oneOf#1.cors.enableinteger enum是是否启用 CORS。1
oneOf#1.cors.allow_originstring是Access-Control-Allow-Origin 值。*
oneOf#1.cors.allow_methodsstring是允许的方法,空格分隔。GET POST OPTIONS
oneOf#1.cors.allow_headersstring是允许的请求头,空格分隔。Content-Type Authorization
oneOf#1.cors.expose_headersstring是允许浏览器读取的响应头。Content-Length
oneOf#1.cors.allow_credentialsinteger enum是是否允许携带凭证。1
oneOf#1.cors.max_agestring是预检结果缓存秒数;服务端要求传数字字符串。1728000
oneOf#1.dns_apiinteger否DNS API 凭据 ID;必须属于目标用户。传 null 表示不绑定。8
oneOf#1.enable_ipv6integer enum否是否启用 IPv6 CNAME;仅按网站生成 CNAME 且系统存在 IPv6 节点时可用。1
oneOf#1.extra_cc_rulearray否网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。[{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}]
oneOf#1.extra_cc_rulearray<object>否网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。[{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}]
oneOf#1.groupsstring否网站分组 ID,多个 ID 使用逗号分隔;空字符串表示不加入分组。3,8
oneOf#1.hotlinkobject否防盗链配置。{"enable":1,"domain":"www.example.invalid","allow_empty":0,"scope_type":"all","scope_content":""}
oneOf#1.hotlink.enableinteger enum是是否启用防盗链。1
oneOf#1.hotlink.domainstring是允许的来源域名,使用空格分隔;空值仅允许本站域名。www.example.invalid
oneOf#1.hotlink.allow_emptyinteger enum是是否允许空 Referer。1
oneOf#1.hotlink.scope_typestring enum否生效范围。all
oneOf#1.hotlink.scope_contentstring否非 all 范围的匹配内容。/static/
oneOf#1.is_default_serverinteger enum否管理员专用。是否作为线路范围内的默认站点;同一节点的监听端口不能与其它默认站点冲突。1
oneOf#1.l2_config_idinteger否管理员专用。L2 配置 ID;必须存在、与网站区域一致并已绑定 L2 节点。9
oneOf#1.l2_statestring enum否管理员专用。L2 模式。inherit
oneOf#1.log_req_bodyinteger enum否管理员专用。是否记录请求体。1
oneOf#1.log_req_body_max_sizeinteger否管理员专用。记录请求体的最大 KiB;不能超过 2048,也不能超过全局 client_body_buffer_size。16
oneOf#1.log_req_headerinteger enum否管理员专用。是否记录请求头。1
oneOf#1.log_resp_headerinteger enum否管理员专用。是否记录响应头。1
oneOf#1.page_403string否自定义 403 错误页 HTML;空字符串使用默认页面。<h1>Forbidden</h1>
oneOf#1.page_404string否自定义 404 错误页 HTML;空字符串使用默认页面。<h1>Not Found</h1>
oneOf#1.page_500string否自定义 500 错误页 HTML;空字符串使用默认页面。<h1>Server Error</h1>
oneOf#1.page_502string否自定义 502 错误页 HTML;空字符串使用默认页面。<h1>Bad Gateway</h1>
oneOf#1.page_504string否自定义 504 错误页 HTML;空字符串使用默认页面。<h1>Gateway Timeout</h1>
oneOf#1.post_size_limitstring否POST 请求体大小限制。可使用纯数字或 b/k/m/g 单位,大小写均可;空字符串表示采用默认配置。10m
oneOf#1.proxy_http_versionstring enum否回源 HTTP 协议版本。1.1
oneOf#1.proxy_ssl_protocolsstring否允许的回源 TLS/SSL 协议,多个值使用空格分隔。TLSv1.2 TLSv1.3
oneOf#1.rangeinteger enum否是否启用分段回源。1
oneOf#1.recv_real_timeinteger enum否是否实时向客户端返回上游响应数据。1
oneOf#1.req_headerarray否添加或覆盖的回源请求头。[{"name":"X-Origin","value":"cdnfly"}]
oneOf#1.req_headerarray<object>否添加或覆盖的回源请求头。[{"name":"X-Origin","value":"cdnfly"}]
oneOf#1.req_header[].namestring是请求头名称,必须以英文字母开头。X-Example
oneOf#1.req_header[].valuestring是请求头值,去除首尾空白后不能为空。example-value
oneOf#1.resp_headerarray否添加或覆盖的客户端响应头。[{"name":"X-Cache","value":"cdnfly"}]
oneOf#1.resp_headerarray<object>否添加或覆盖的客户端响应头。[{"name":"X-Cache","value":"cdnfly"}]
oneOf#1.resp_header[].namestring是请求头名称,必须以英文字母开头。X-Example
oneOf#1.resp_header[].valuestring是请求头值,去除首尾空白后不能为空。example-value
oneOf#1.send_real_timeinteger enum否是否实时向上游发送客户端请求数据。1
oneOf#1.spider_allowstring enum否搜索引擎爬虫访问策略;空字符串表示不单独设置。allow
oneOf#1.spider_to_sipstring否搜索引擎专用回源 IP;空字符串表示关闭。仅按网站生成 CNAME 且 DNS 服务支持对应线路时可用。198.51.100.20
oneOf#1.ups_keepaliveinteger enum否是否启用上游 Keepalive。1
oneOf#1.ups_keepalive_conninteger否每个 worker 保留的上游 Keepalive 连接数。16
oneOf#1.ups_keepalive_timeoutinteger否上游 Keepalive 空闲超时秒数。60
oneOf#1.url_rewritearray否URL 重定向规则。[{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}]
oneOf#1.url_rewritearray<object>否URL 重定向规则。[{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}]
oneOf#1.url_rewrite[].hoststring是匹配 Host,不含 http:// 或 https://。www.example.invalid
oneOf#1.url_rewrite[].matchstring是URI 匹配表达式。/(.*)
oneOf#1.url_rewrite[].redirectstring是重定向目标;可使用 `$1` 或受支持的 Nginx 变量。https://example.invalid/$1
oneOf#1.url_rewrite[].codestring enum是重定向方式。301
oneOf#1.url_rewrite[].user_agentstring否User-Agent 匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].refererstring否Referer 匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].country_codestring否国家代码匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].accept_languagestring否Accept-Language 匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].provincestring否省份匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].citystring否城市匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].ispstring否运营商匹配;省略时为 `.*`。.*
oneOf#1.url_rewrite[].asnumberstring否ASN 匹配;省略时为 `.*`。.*
oneOf#1.white_ipstring否网站白名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。203.0.113.10
oneOf#1.white_timeinteger否自动白名单持续时间,单位秒;非空时不超过 604800。3600
oneOf#2array<object>否批量更新对象数组;每个元素独立按相同规则校验和更新。
oneOf#2[].idinteger是必填。要更新的网站 ID,必须存在且当前用户有权限操作。
oneOf#2[].domainstring否网站域名,多个域名以空白字符分隔;会转为小写且不得重复。修改后重新校验套餐配额、区域内域名和域名端口唯一性。
oneOf#2[].backendarray否源站列表。每项地址必须为 IPv4、IPv6 或域名,地址不可重复,至少保留一个 `up` 状态源站。
oneOf#2[].backendarray<object>否源站列表。每项地址必须为 IPv4、IPv6 或域名,地址不可重复,至少保留一个 `up` 状态源站。
oneOf#2[].backend[].addrstring是源站地址。
oneOf#2[].backend[].weightinteger是源站权重。
oneOf#2[].backend[].statestring enum是源站状态。up | down | backup
oneOf#2[].user_packageinteger否用户套餐 ID;必须属于网站归属用户且可用。变更套餐会重新同步相关线路与配置。
oneOf#2[].new_uidinteger否管理员专用。将网站转移到指定用户;同时必须传入 `user_package`。
oneOf#2[].uidinteger否管理员专用。指定本次套餐与资源校验所使用的用户 ID。
oneOf#2[].http_listenobject否HTTP 监听配置;与 HTTPS 至少保留一个。
oneOf#2[].http_listen.portstring否空白分隔的监听端口;每个端口必须有效、未占用且在区域允许范围内。
oneOf#2[].https_listenobject否HTTPS 监听配置。
oneOf#2[].https_listen.portstring否空白分隔的 HTTPS 监听端口。
oneOf#2[].https_listen.certinteger否已启用证书 ID。
oneOf#2[].https_listen.hstsinteger enum否是否启用 HSTS。0 | 1
oneOf#2[].https_listen.http2integer enum否是否启用 HTTP/2。0 | 1
oneOf#2[].https_listen.http3integer enum否是否启用 HTTP/3。0 | 1
oneOf#2[].https_listen.ocsp_staplinginteger enum否是否启用 OCSP Stapling。0 | 1
oneOf#2[].https_listen.force_ssl_enableinteger enum否是否强制跳转 HTTPS。0 | 1
oneOf#2[].https_listen.force_ssl_portstring否强制跳转目标端口,必须在 HTTPS 监听端口中。
oneOf#2[].https_listen.ssl_protocolsstring否允许的 TLS 协议,使用空白字符分隔。
oneOf#2[].https_listen.ssl_ciphersstring否TLS 密码套件。
oneOf#2[].https_listen.ssl_prefer_server_ciphersstring enum否是否优先使用服务端密码套件。on | off
oneOf#2[].balance_waystring enum否负载均衡方式。`ip_hash` 不支持备用源站。ip_hash | rr
oneOf#2[].backend_protocolstring enum否回源协议。follow | http | https
oneOf#2[].backend_http_portinteger否HTTP 回源端口。
oneOf#2[].backend_https_portinteger否HTTPS 回源端口。
oneOf#2[].backend_port_mappinginteger enum否是否使用访问端口作为回源端口。0 | 1
oneOf#2[].proxy_timeoutinteger否回源读取超时,单位秒。
oneOf#2[].proxy_connect_timeoutinteger否回源连接超时,单位秒。
oneOf#2[].health_checkobject否健康检查配置。
oneOf#2[].health_check.enableinteger enum否是否启用健康检查。0 | 1
oneOf#2[].health_check.hoststring否检查请求域名。
oneOf#2[].health_check.pathstring否检查路径,必须以 `/` 开头。
oneOf#2[].proxy_authobject否回源认证配置。
oneOf#2[].proxy_auth.enableboolean否是否启用认证。
oneOf#2[].proxy_auth.usernamestring否认证用户名。
oneOf#2[].proxy_auth.passwordstring否认证密码。
oneOf#2[].proxy_cacheinteger enum否是否启用代理缓存。0 | 1
oneOf#2[].gzip_enableinteger enum否是否启用 Gzip。0 | 1
oneOf#2[].gzip_typesstring否Gzip MIME 类型。
oneOf#2[].websocket_enableinteger enum否是否启用 WebSocket 代理。0 | 1
oneOf#2[].enableinteger enum否网站启用状态。0 | 1
oneOf#2[].statestring否网站处理状态。
oneOf#2[].cname_modestring enum否CNAME 使用方式;切换会触发相应同步任务。package | site
oneOf#2[].cname_domaininteger否管理员专用。CNAME 域名配置 ID。
oneOf#2[].cname_hostnamestring否管理员专用。网站 CNAME 主机名,必须唯一且合法。
oneOf#2[].region_idinteger否管理员专用。区域 ID。
oneOf#2[].node_group_idinteger否管理员专用。主线路组 ID;CNAME 按套餐时不能单独修改。
oneOf#2[].backup_node_groupinteger否管理员专用。备用线路组 ID;不能与主线路组相同。
oneOf#2[].aclinteger否ACL ID;传 null 或 0 表示不绑定。ACL 必须已启用且属于当前目标用户,否则要求管理员权限。12
oneOf#2[].acme_proxy_to_orgininteger enum否是否将 `/.well-known/acme-challenge/` 请求回源:1 开启,0 关闭。1
oneOf#2[].backend_hoststring否回源 Host。允许 `$host`、`$host:$server_port`,或合法域名/IP及可选端口。$host
oneOf#2[].black_ipstring否网站黑名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。198.51.100.0/24
oneOf#2[].block_proxyinteger enum否是否拦截被识别为代理的客户端。1
oneOf#2[].block_regionstring否按两字母小写国家/地区代码拦截,多个值以逗号分隔;空字符串表示关闭。us,jp
oneOf#2[].block_timeinteger否自动黑名单持续时间,单位秒;非空时必须大于 600 且不超过 604800。3600
oneOf#2[].cc_default_ruleinteger否默认 CC 规则 ID;规则必须存在且启用,使用其他用户的非内置规则需要管理员权限。10002
oneOf#2[].cc_switchobject否CC 规则自动切换配置;空对象表示关闭。{"rule":10002,"switch":100,"enable":1}
oneOf#2[].cc_switch.ruleinteger是切换后的 CC 规则 ID。10002
oneOf#2[].cc_switch.switchinteger是触发切换的请求阈值。100
oneOf#2[].cc_switch.enableinteger enum否是否启用自动切换。1
oneOf#2[].condition_backendarray否按请求条件选择源站的规则列表。[{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}]
oneOf#2[].condition_backendarray<object>否按请求条件选择源站的规则列表。[{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}]
oneOf#2[].condition_backend[].matcherarray是全部匹配条件。
oneOf#2[].condition_backend[].matcherarray<object>否全部匹配条件。
oneOf#2[].condition_backend[].matcher[].itemstring是匹配项。req_uri
oneOf#2[].condition_backend[].matcher[].opstring enum是匹配操作符。contain
oneOf#2[].condition_backend[].matcher[].valuestring是匹配值;服务端会去除空行和首尾空白。/api/
oneOf#2[].condition_backend[].backendarray是命中后使用的源站列表。
oneOf#2[].condition_backend[].backendarray<object>否命中后使用的源站列表。
oneOf#2[].condition_backend[].backend[].addrstring是源站 IPv4、IPv6 或域名。198.51.100.10
oneOf#2[].condition_backend[].backend[].weightinteger否源站权重。1
oneOf#2[].condition_backend[].backend[].statestring enum否源站状态。up
oneOf#2[].cookie_domainstring否Cookie Domain;允许空字符串,非空时必须是合法域名。example.invalid
oneOf#2[].corsobject否跨域响应配置。{"enable":1,"allow_origin":"*","allow_methods":"GET POST OPTIONS","allow_headers":"Content-Type","expose_headers":"Content-Length","allow_credentials":0,"max_age":"1728000"}
oneOf#2[].cors.enableinteger enum是是否启用 CORS。1
oneOf#2[].cors.allow_originstring是Access-Control-Allow-Origin 值。*
oneOf#2[].cors.allow_methodsstring是允许的方法,空格分隔。GET POST OPTIONS
oneOf#2[].cors.allow_headersstring是允许的请求头,空格分隔。Content-Type Authorization
oneOf#2[].cors.expose_headersstring是允许浏览器读取的响应头。Content-Length
oneOf#2[].cors.allow_credentialsinteger enum是是否允许携带凭证。1
oneOf#2[].cors.max_agestring是预检结果缓存秒数;服务端要求传数字字符串。1728000
oneOf#2[].dns_apiinteger否DNS API 凭据 ID;必须属于目标用户。传 null 表示不绑定。8
oneOf#2[].enable_ipv6integer enum否是否启用 IPv6 CNAME;仅按网站生成 CNAME 且系统存在 IPv6 节点时可用。1
oneOf#2[].extra_cc_rulearray否网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。[{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}]
oneOf#2[].extra_cc_rulearray<object>否网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。[{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}]
oneOf#2[].groupsstring否网站分组 ID,多个 ID 使用逗号分隔;空字符串表示不加入分组。3,8
oneOf#2[].hotlinkobject否防盗链配置。{"enable":1,"domain":"www.example.invalid","allow_empty":0,"scope_type":"all","scope_content":""}
oneOf#2[].hotlink.enableinteger enum是是否启用防盗链。1
oneOf#2[].hotlink.domainstring是允许的来源域名,使用空格分隔;空值仅允许本站域名。www.example.invalid
oneOf#2[].hotlink.allow_emptyinteger enum是是否允许空 Referer。1
oneOf#2[].hotlink.scope_typestring enum否生效范围。all
oneOf#2[].hotlink.scope_contentstring否非 all 范围的匹配内容。/static/
oneOf#2[].is_default_serverinteger enum否管理员专用。是否作为线路范围内的默认站点;同一节点的监听端口不能与其它默认站点冲突。1
oneOf#2[].l2_config_idinteger否管理员专用。L2 配置 ID;必须存在、与网站区域一致并已绑定 L2 节点。9
oneOf#2[].l2_statestring enum否管理员专用。L2 模式。inherit
oneOf#2[].log_req_bodyinteger enum否管理员专用。是否记录请求体。1
oneOf#2[].log_req_body_max_sizeinteger否管理员专用。记录请求体的最大 KiB;不能超过 2048,也不能超过全局 client_body_buffer_size。16
oneOf#2[].log_req_headerinteger enum否管理员专用。是否记录请求头。1
oneOf#2[].log_resp_headerinteger enum否管理员专用。是否记录响应头。1
oneOf#2[].page_403string否自定义 403 错误页 HTML;空字符串使用默认页面。<h1>Forbidden</h1>
oneOf#2[].page_404string否自定义 404 错误页 HTML;空字符串使用默认页面。<h1>Not Found</h1>
oneOf#2[].page_500string否自定义 500 错误页 HTML;空字符串使用默认页面。<h1>Server Error</h1>
oneOf#2[].page_502string否自定义 502 错误页 HTML;空字符串使用默认页面。<h1>Bad Gateway</h1>
oneOf#2[].page_504string否自定义 504 错误页 HTML;空字符串使用默认页面。<h1>Gateway Timeout</h1>
oneOf#2[].post_size_limitstring否POST 请求体大小限制。可使用纯数字或 b/k/m/g 单位,大小写均可;空字符串表示采用默认配置。10m
oneOf#2[].proxy_http_versionstring enum否回源 HTTP 协议版本。1.1
oneOf#2[].proxy_ssl_protocolsstring否允许的回源 TLS/SSL 协议,多个值使用空格分隔。TLSv1.2 TLSv1.3
oneOf#2[].rangeinteger enum否是否启用分段回源。1
oneOf#2[].recv_real_timeinteger enum否是否实时向客户端返回上游响应数据。1
oneOf#2[].req_headerarray否添加或覆盖的回源请求头。[{"name":"X-Origin","value":"cdnfly"}]
oneOf#2[].req_headerarray<object>否添加或覆盖的回源请求头。[{"name":"X-Origin","value":"cdnfly"}]
oneOf#2[].req_header[].namestring是请求头名称,必须以英文字母开头。X-Example
oneOf#2[].req_header[].valuestring是请求头值,去除首尾空白后不能为空。example-value
oneOf#2[].resp_headerarray否添加或覆盖的客户端响应头。[{"name":"X-Cache","value":"cdnfly"}]
oneOf#2[].resp_headerarray<object>否添加或覆盖的客户端响应头。[{"name":"X-Cache","value":"cdnfly"}]
oneOf#2[].resp_header[].namestring是请求头名称,必须以英文字母开头。X-Example
oneOf#2[].resp_header[].valuestring是请求头值,去除首尾空白后不能为空。example-value
oneOf#2[].send_real_timeinteger enum否是否实时向上游发送客户端请求数据。1
oneOf#2[].spider_allowstring enum否搜索引擎爬虫访问策略;空字符串表示不单独设置。allow
oneOf#2[].spider_to_sipstring否搜索引擎专用回源 IP;空字符串表示关闭。仅按网站生成 CNAME 且 DNS 服务支持对应线路时可用。198.51.100.20
oneOf#2[].ups_keepaliveinteger enum否是否启用上游 Keepalive。1
oneOf#2[].ups_keepalive_conninteger否每个 worker 保留的上游 Keepalive 连接数。16
oneOf#2[].ups_keepalive_timeoutinteger否上游 Keepalive 空闲超时秒数。60
oneOf#2[].url_rewritearray否URL 重定向规则。[{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}]
oneOf#2[].url_rewritearray<object>否URL 重定向规则。[{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}]
oneOf#2[].url_rewrite[].hoststring是匹配 Host,不含 http:// 或 https://。www.example.invalid
oneOf#2[].url_rewrite[].matchstring是URI 匹配表达式。/(.*)
oneOf#2[].url_rewrite[].redirectstring是重定向目标;可使用 `$1` 或受支持的 Nginx 变量。https://example.invalid/$1
oneOf#2[].url_rewrite[].codestring enum是重定向方式。301
oneOf#2[].url_rewrite[].user_agentstring否User-Agent 匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].refererstring否Referer 匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].country_codestring否国家代码匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].accept_languagestring否Accept-Language 匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].provincestring否省份匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].citystring否城市匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].ispstring否运营商匹配;省略时为 `.*`。.*
oneOf#2[].url_rewrite[].asnumberstring否ASN 匹配;省略时为 `.*`。.*
oneOf#2[].white_ipstring否网站白名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。203.0.113.10
oneOf#2[].white_timeinteger否自动白名单持续时间,单位秒;非空时不超过 604800。3600

请求体示例

{ "id": 101, "backend": [ { "addr": "198.51.100.20", "weight": 1, "state": "up" } ], "proxy_timeout": 60 }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“更新网站成功”、`data` 为 null;业务校验失败同样返回 HTTP 200,并在 `code` 与 `msg` 中说明原因。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0,失败时为对应的 site-* 错误码。0
msgstring是处理结果说明。更新网站成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "更新网站成功", "data": null }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"id":101,"backend":[{"addr":"198.51.100.20","weight":1,"state":"up"}],"proxy_timeout":60}' \ 'https://master.example.com/v1/sites'
用户 API / 网站与安全 / 网站管理 / 删除网站

DELETE删除网站

DELETE /v1/sites/{site_id}

删除一个或多个网站。路径参数可使用单个网站 ID,也可使用英文逗号分隔的多个 ID。每个网站都必须存在、属于当前用户(否则需管理员权限)、处于禁用状态,且没有未完成的网站同步任务;任一项目不满足条件时整个请求会回滚。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
site_idpathstring是要删除的网站 ID,或以英文逗号分隔的网站 ID 列表;每一项必须是数字。101,102

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“网站删除成功”、`data` 为 null;即使 ID 无效、网站不存在、网站未禁用、任务未完成或无权限,也返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。网站删除成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "网站删除成功", "data": null }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/sites/{site_id}'
用户 API / 网站与安全 / 网站管理 / 获取网站详情

GET获取网站详情

GET /v1/sites/{site_id}

获取指定网站的完整配置、套餐、线路和任务状态。普通用户只能读取自己的网站;读取其他用户的网站需要管理员权限。配置类字段按数据库原值返回,其中多项为 JSON 字符串,调用方需要自行解析。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
site_idpathinteger是要查询的网站 ID,必须是当前用户的网站;管理员可查询任意已有网站。

响应

HTTP 200

请求已被处理。成功时 `code` 为 0,`data` 为网站详情;网站不存在或无权限时仍返回 HTTP 200 并提供业务错误码。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是成功时为空字符串,失败时为错误说明。
dataobject是网站详情。JSON 配置字段以字符串形式返回。
data.idinteger是网站 ID。
data.uidinteger是网站归属用户 ID。
data.namestring否归属用户名。
data.domainstring是网站域名,多个域名以空白字符分隔。
data.backendstring是源站列表的 JSON 字符串;每项包含 addr、weight、state。
data.backend_hoststring否回源 Host 配置。
data.backend_protocolstring否回源协议:follow、http 或 https。
data.backend_http_portinteger否HTTP 回源端口。
data.backend_https_portinteger否HTTPS 回源端口。
data.backend_port_mappinginteger否是否启用回源端口映射。
data.balance_waystring否负载均衡方式。
data.http_listenstring否HTTP 监听配置的 JSON 字符串。
data.https_listenstring否HTTPS 监听配置的 JSON 字符串。
data.user_packageinteger是使用的用户套餐 ID。
data.package_idinteger否底层套餐 ID。
data.package_namestring否用户套餐名称。
data.end_atstring否用户套餐到期时间,格式为 YYYY-MM-DD HH:mm:ss。
data.region_idinteger否区域 ID。
data.region_namestring否区域名称。
data.node_group_idinteger否主线路组 ID。
data.node_group_namestring否主线路组名称。
data.node_group_ipv6integer enum否主线路组是否含 IPv6 节点。0 | 1
data.backup_node_groupinteger否备用线路组 ID。
data.backup_node_group_namestring否备用线路组名称。
data.cname_modestring否CNAME 使用方式。
data.cname_hostnamestring否网站 CNAME 主机名。
data.cname_domainstring否网站 CNAME 域名。
data.up_cname_domainstring否套餐 CNAME 域名。
data.up_cname_hostnamestring否套餐 CNAME 主机名。
data.enableinteger enum是网站是否启用。0 | 1
data.site_statestring是网站当前状态。
data.sync_statestring否网站同步任务状态。
data.cname_statestring否CNAME 任务状态。
data.task_idinteger否网站同步任务 ID。
data.cname_task_idinteger否CNAME 任务 ID。
data.groupsstring否网站分组 ID 的逗号分隔字符串。
data.group_namestring否网站分组名称的逗号分隔字符串。
data.health_checkstring否健康检查配置的 JSON 字符串。
data.proxy_timeoutinteger否回源读取超时秒数。
data.proxy_connect_timeoutinteger否回源连接超时秒数。
data.proxy_authstring否回源认证配置的 JSON 字符串。
data.proxy_cacheinteger否是否启用代理缓存。
data.proxy_http_versionstring否回源 HTTP 版本。
data.proxy_ssl_protocolsstring否回源 TLS 协议配置。
data.gzip_enableinteger否是否启用 Gzip。
data.gzip_typesstring否Gzip MIME 类型。
data.websocket_enableinteger否是否启用 WebSocket。
data.corsstring否跨域配置的 JSON 字符串。
data.hotlinkstring否防盗链配置的 JSON 字符串。
data.aclstring否访问控制列表配置。
data.black_ipstring否IP 黑名单配置。
data.white_ipstring否IP 白名单配置。
data.block_proxyinteger否是否拦截代理请求。
data.block_regionstring否地域拦截配置。
data.cc_default_rulestring否默认 CC 防护规则 ID。
data.cc_switchstring否CC 开关配置的 JSON 字符串。
data.condition_backendstring否条件回源配置的 JSON 字符串。
data.extra_cc_rulestring否附加 CC 规则配置。
data.req_headerstring否请求头改写配置。
data.resp_headerstring否响应头改写配置。
data.url_rewritestring否URL 重写配置。
data.page_403string否403 页面配置。
data.page_404string否404 页面配置。
data.page_500string否500 页面配置。
data.page_502string否502 页面配置。
data.page_504string否504 页面配置。
data.create_at2string否创建时间,格式为 YYYY-MM-DD HH:mm:ss。
data.update_at2string否更新时间,格式为 YYYY-MM-DD HH:mm:ss。
data.versioninteger否配置版本号。

响应示例

{ "code": 0, "msg": "", "data": { "id": 0, "uid": 0, "name": "string", "domain": "string", "backend": "string", "backend_host": "string", "backend_protocol": "string", "backend_http_port": 0, "backend_https_port": 0, "backend_port_mapping": 0, "balance_way": "string", "http_listen": "string", "https_listen": "string", "user_package": 0, "package_id": 0, "package_name": "string", "end_at": "string", "region_id": 0, "region_name": "string", "node_group_id": 0, "node_group_name": "string", "node_group_ipv6": 0, "backup_node_group": 0, "backup_node_group_name": "string", "cname_mode": "string", "cname_hostname": "string", "cname_domain": "string", "up_cname_domain": "string", "up_cname_hostname": "string", "enable": 0, "site_state": "string", "sync_state": "string", "cname_state": "string", "task_id": 0, "cname_task_id": 0, "groups": "string", "group_name": "string", "health_check": "string", "proxy_timeout": 0, "proxy_connect_timeout": 0, "proxy_auth": "string", "proxy_cache": 0, "proxy_http_version": "string", "proxy_ssl_protocols": "string", "gzip_enable": 0, "gzip_types": "string", "websocket_enable": 0, "cors": "string", "hotlink": "string", "acl": "string", "black_ip": "string", "white_ip": "string", "block_proxy": 0, "block_region": "string", "cc_default_rule": "string", "cc_switch": "string", "condition_backend": "string", "extra_cc_rule": "string", "req_header": "string", "resp_header": "string", "url_rewrite": "string", "page_403": "string", "page_404": "string", "page_500": "string", "page_502": "string", "page_504": "string", "create_at2": "string", "update_at2": "string", "version": 0 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/sites/{site_id}'
用户 API / 网站与安全 / 网站管理 / 更新指定网站

PUT更新指定网站

PUT /v1/sites/{site_id}

更新一个网站的指定配置。路径中的 `site_id` 会强制写入请求对象,客户端传入的同名字段会被覆盖;请求体必须是 JSON 对象而非数组。仅传需要修改的字段。普通用户仅能更新自己的网站,涉及归属用户、套餐、区域、线路和 CNAME 资源的字段仅管理员可用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
site_idpathinteger是要更新的网站 ID;必须存在,且当前用户必须拥有该网站或具备管理员权限。

请求体

请求体必填。

Content-Type:application/json

单网站更新对象;`id` 由路径参数注入,不能用请求体更换目标网站。

字段类型必填说明示例
domainstring否网站域名,多个域名以空白字符分隔。修改时会转小写,并校验域名、主域名、区域内域名及端口唯一性。
backendarray否完整源站列表;至少包含一个状态为 `up` 的源站。
backendarray<object>否完整源站列表;至少包含一个状态为 `up` 的源站。
backend[].addrstring是源站 IPv4、IPv6 或域名。
backend[].weightinteger是源站权重。
backend[].statestring enum是源站状态。up | down | backup
user_packageinteger否用户套餐 ID;套餐必须属于网站归属用户且处于可用状态。
new_uidinteger否管理员专用。将网站转移至指定用户;同时必须设置 `user_package`。
http_listenobject否HTTP 监听配置。
http_listen.portstring否空白分隔的端口;每项必须有效、允许且未占用。
https_listenobject否HTTPS 监听配置。
https_listen.portstring否空白分隔的 HTTPS 端口。
https_listen.certinteger否已启用证书 ID。
https_listen.hstsinteger enum否是否启用 HSTS。0 | 1
https_listen.http2integer enum否是否启用 HTTP/2。0 | 1
https_listen.http3integer enum否是否启用 HTTP/3。0 | 1
https_listen.ocsp_staplinginteger enum否是否启用 OCSP Stapling。0 | 1
https_listen.force_ssl_enableinteger enum否是否强制 HTTPS。0 | 1
https_listen.force_ssl_portstring否强制跳转目标 HTTPS 端口。
https_listen.ssl_protocolsstring否TLS 协议列表。
https_listen.ssl_ciphersstring否TLS 密码套件。
https_listen.ssl_prefer_server_ciphersstring enum否是否优先服务端密码套件。on | off
balance_waystring enum否负载均衡方式。ip_hash | rr
backend_protocolstring enum否回源协议。follow | http | https
backend_http_portinteger否HTTP 回源端口。
backend_https_portinteger否HTTPS 回源端口。
backend_port_mappinginteger enum否是否将访问端口映射到回源端口。0 | 1
proxy_timeoutinteger否回源读取超时秒数。
proxy_connect_timeoutinteger否回源连接超时秒数。
proxy_authobject否回源认证配置。
proxy_auth.enableboolean否是否启用认证。
proxy_auth.usernamestring否认证用户名。
proxy_auth.passwordstring否认证密码。
health_checkobject否健康检查配置。
health_check.enableinteger enum否是否启用。0 | 1
health_check.hoststring否检查域名。
health_check.pathstring否检查路径,须以 `/` 开头。
proxy_cacheinteger enum否是否启用代理缓存。0 | 1
gzip_enableinteger enum否是否启用 Gzip。0 | 1
gzip_typesstring否Gzip MIME 类型列表。
websocket_enableinteger enum否是否启用 WebSocket。0 | 1
enableinteger enum否网站启用状态。0 | 1
statestring否网站状态。
groupsstring否网站分组 ID,多个 ID 以英文逗号分隔;传空字符串可移除全部分组。
cname_modestring enum否CNAME 使用方式。package | site
cname_domaininteger否管理员专用。CNAME 域名配置 ID。
cname_hostnamestring否管理员专用。CNAME 主机名。
region_idinteger否管理员专用。区域 ID。
node_group_idinteger否管理员专用。主线路组 ID。
backup_node_groupinteger否管理员专用。备用线路组 ID;可传空值清除。
aclstring否访问控制列表配置。
black_ipstring否IP 黑名单配置。
white_ipstring否IP 白名单配置。
corsobject否跨域配置。
cors.enableinteger enum否是否启用跨域。0 | 1
hotlinkobject否防盗链配置。
hotlink.enableinteger enum否是否启用防盗链。0 | 1
url_rewritestring否URL 重写配置。
acme_proxy_to_orgininteger enum否是否将 `/.well-known/acme-challenge/` 请求回源:1 开启,0 关闭。1
backend_hoststring否回源 Host。允许 `$host`、`$host:$server_port`,或合法域名/IP及可选端口。$host
block_proxyinteger enum否是否拦截被识别为代理的客户端。1
block_regionstring否按两字母小写国家/地区代码拦截,多个值以逗号分隔;空字符串表示关闭。us,jp
block_timeinteger否自动黑名单持续时间,单位秒;非空时必须大于 600 且不超过 604800。3600
cc_default_ruleinteger否默认 CC 规则 ID;规则必须存在且启用,使用其他用户的非内置规则需要管理员权限。10002
cc_switchobject否CC 规则自动切换配置;空对象表示关闭。{"rule":10002,"switch":100,"enable":1}
cc_switch.ruleinteger是切换后的 CC 规则 ID。10002
cc_switch.switchinteger是触发切换的请求阈值。100
cc_switch.enableinteger enum否是否启用自动切换。1
condition_backendarray否按请求条件选择源站的规则列表。[{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}]
condition_backendarray<object>否按请求条件选择源站的规则列表。[{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}]
condition_backend[].matcherarray是全部匹配条件。
condition_backend[].matcherarray<object>否全部匹配条件。
condition_backend[].matcher[].itemstring是匹配项。req_uri
condition_backend[].matcher[].opstring enum是匹配操作符。contain
condition_backend[].matcher[].valuestring是匹配值;服务端会去除空行和首尾空白。/api/
condition_backend[].backendarray是命中后使用的源站列表。
condition_backend[].backendarray<object>否命中后使用的源站列表。
condition_backend[].backend[].addrstring是源站 IPv4、IPv6 或域名。198.51.100.10
condition_backend[].backend[].weightinteger否源站权重。1
condition_backend[].backend[].statestring enum否源站状态。up
cookie_domainstring否Cookie Domain;允许空字符串,非空时必须是合法域名。example.invalid
dns_apiinteger否DNS API 凭据 ID;必须属于目标用户。传 null 表示不绑定。8
enable_ipv6integer enum否是否启用 IPv6 CNAME;仅按网站生成 CNAME 且系统存在 IPv6 节点时可用。1
extra_cc_rulearray否网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。[{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}]
extra_cc_rulearray<object>否网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。[{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}]
is_default_serverinteger enum否管理员专用。是否作为线路范围内的默认站点;同一节点的监听端口不能与其它默认站点冲突。1
l2_config_idinteger否管理员专用。L2 配置 ID;必须存在、与网站区域一致并已绑定 L2 节点。9
l2_statestring enum否管理员专用。L2 模式。inherit
log_req_bodyinteger enum否管理员专用。是否记录请求体。1
log_req_body_max_sizeinteger否管理员专用。记录请求体的最大 KiB;不能超过 2048,也不能超过全局 client_body_buffer_size。16
log_req_headerinteger enum否管理员专用。是否记录请求头。1
log_resp_headerinteger enum否管理员专用。是否记录响应头。1
page_403string否自定义 403 错误页 HTML;空字符串使用默认页面。<h1>Forbidden</h1>
page_404string否自定义 404 错误页 HTML;空字符串使用默认页面。<h1>Not Found</h1>
page_500string否自定义 500 错误页 HTML;空字符串使用默认页面。<h1>Server Error</h1>
page_502string否自定义 502 错误页 HTML;空字符串使用默认页面。<h1>Bad Gateway</h1>
page_504string否自定义 504 错误页 HTML;空字符串使用默认页面。<h1>Gateway Timeout</h1>
post_size_limitstring否POST 请求体大小限制。可使用纯数字或 b/k/m/g 单位,大小写均可;空字符串表示采用默认配置。10m
proxy_http_versionstring enum否回源 HTTP 协议版本。1.1
proxy_ssl_protocolsstring否允许的回源 TLS/SSL 协议,多个值使用空格分隔。TLSv1.2 TLSv1.3
rangeinteger enum否是否启用分段回源。1
recv_real_timeinteger enum否是否实时向客户端返回上游响应数据。1
req_headerarray否添加或覆盖的回源请求头。[{"name":"X-Origin","value":"cdnfly"}]
req_headerarray<object>否添加或覆盖的回源请求头。[{"name":"X-Origin","value":"cdnfly"}]
req_header[].namestring是请求头名称,必须以英文字母开头。X-Example
req_header[].valuestring是请求头值,去除首尾空白后不能为空。example-value
resp_headerarray否添加或覆盖的客户端响应头。[{"name":"X-Cache","value":"cdnfly"}]
resp_headerarray<object>否添加或覆盖的客户端响应头。[{"name":"X-Cache","value":"cdnfly"}]
resp_header[].namestring是请求头名称,必须以英文字母开头。X-Example
resp_header[].valuestring是请求头值,去除首尾空白后不能为空。example-value
send_real_timeinteger enum否是否实时向上游发送客户端请求数据。1
spider_allowstring enum否搜索引擎爬虫访问策略;空字符串表示不单独设置。allow
spider_to_sipstring否搜索引擎专用回源 IP;空字符串表示关闭。仅按网站生成 CNAME 且 DNS 服务支持对应线路时可用。198.51.100.20
uidinteger否管理员专用。创建时指定网站所属用户;更新转移网站时与 new_uid 配合,作为目标套餐归属校验用户。12
ups_keepaliveinteger enum否是否启用上游 Keepalive。1
ups_keepalive_conninteger否每个 worker 保留的上游 Keepalive 连接数。16
ups_keepalive_timeoutinteger否上游 Keepalive 空闲超时秒数。60
white_timeinteger否自动白名单持续时间,单位秒;非空时不超过 604800。3600

请求体示例

{ "backend": [ { "addr": "198.51.100.20", "weight": 1, "state": "up" } ], "proxy_timeout": 60, "enable": 1 }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“更新网站成功”、`data` 为 null;字段校验、网站不存在或权限不足时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。更新网站成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "更新网站成功", "data": null }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"backend":[{"addr":"198.51.100.20","weight":1,"state":"up"}],"proxy_timeout":60,"enable":1}' \ 'https://master.example.com/v1/sites/{site_id}'
用户 API / 网站与安全 / 网站分组

网站分组

网站分组

接口列表

GET
/v1/site-groups
查询网站组列表 — 分页查询网站组,按网站组 ID 倒序返回。普通用户仅查询自己的网站组;管理员可查询全部,或通过 `uid` 查询指定用户的网站组。
POST
/v1/site-groups
新增网站组 — 创建网站组。默认归属当前登录用户,并先按当前用户的网站关联资源配额检查网站组数量;管理员可通过 `uid` 指定网站组归属用户。网站组名称在同一归属用户下必须唯
DELETE
/v1/site-groups/{group_id}
删除网站组 — 删除一个或多个网站组。路径参数支持英文逗号分隔多个网站组 ID。当前用户可删除自己的网站组;删除其他用户的网站组需要管理员权限。每个目标网站组必须不存在关联网站
GET
/v1/site-groups/{group_id}
获取网站组详情 — 获取当前登录用户的一条网站组。服务端以网站组 ID 和当前登录用户 ID 联合查询;即使管理员登录,也不能通过此详情路径读取其他用户的网站组。
PUT
/v1/site-groups/{group_id}
更新网站组 — 更新指定网站组。路径中的网站组 ID 会覆盖请求体 ID;未提供的字段保持原值,至少应有一个字段发生变化。网站组不属于当前用户时需要管理员权限。注意:请求体 `
用户 API / 网站与安全 / 网站分组 / 查询网站组列表

GET查询网站组列表

GET /v1/site-groups

分页查询网站组,按网站组 ID 倒序返回。普通用户仅查询自己的网站组;管理员可查询全部,或通过 `uid` 查询指定用户的网站组。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger否页码,必须为数字;默认 1。1
limitqueryinteger否每页条数,必须为数字;默认 10。传 0 时不分页。10
uidqueryinteger否仅管理员有效:按网站组所属用户 ID 精确筛选。普通用户传入后仍只返回自己的记录。12

响应

HTTP 200

查询成功时不含 `msg` 字段;参数或认证错误仍返回 HTTP 200。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.countinteger是筛选后的网站组总数,未受分页影响。1
oneOf#1.dataarray是当前页网站组记录。
oneOf#1.dataarray<object>否当前页网站组记录。
oneOf#1.data[].idinteger是网站组 ID。
oneOf#1.data[].uidinteger是网站组所属用户 ID。
oneOf#1.data[].namestring是网站组名称。
oneOf#1.data[].desstring是网站组备注。
oneOf#1.data[].usernamestring是所属用户的用户名,由用户表关联得到。
oneOf#2.codestring enum是页码/分页条数格式错误或未登录时的业务错误码。site_group-4 | site_group-5 | login_required
oneOf#2.msgstring是错误原因。page参数格式不正确
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "count": 1, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/site-groups'
用户 API / 网站与安全 / 网站分组 / 新增网站组

POST新增网站组

POST /v1/site-groups

创建网站组。默认归属当前登录用户,并先按当前用户的网站关联资源配额检查网站组数量;管理员可通过 `uid` 指定网站组归属用户。网站组名称在同一归属用户下必须唯一。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring是网站组名称,不能为空;服务端会进行 XSS 过滤,且在归属用户下必须唯一。生产网站
desstring否网站组备注;服务端会进行 XSS 过滤,未传时保存为空字符串。主要业务站点
uidinteger否仅管理员可传。创建后的网站组归属用户 ID;未传时使用当前登录用户 ID。12

请求体示例

{ "name": "生产网站", "des": "主要业务站点", "uid": 12 }

响应

HTTP 200

网站组创建成功,`data` 为新记录的自增 ID。 未登录、维护模式限制、网站组配额已满、非管理员指定 uid 或名称校验失败时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`site_group-8`、`site_group-9`、`site_group-11`、`site_group-12` 或 `site_group-17`。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。网站组添加成功
oneOf#1.datainteger是新创建网站组的自增 ID。21
oneOf#2.codestring是业务错误码。site_group-8
oneOf#2.msgstring是错误原因。当前添加的网站组已超限
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "网站组添加成功", "data": 21 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"生产网站","des":"主要业务站点","uid":12}' \ 'https://master.example.com/v1/site-groups'
用户 API / 网站与安全 / 网站分组 / 删除网站组

DELETE删除网站组

DELETE /v1/site-groups/{group_id}

删除一个或多个网站组。路径参数支持英文逗号分隔多个网站组 ID。当前用户可删除自己的网站组;删除其他用户的网站组需要管理员权限。每个目标网站组必须不存在关联网站,任一检查失败都会回滚本次批量删除。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
group_idpathstring是一个网站组 ID,或以英文逗号分隔的多个网站组 ID。21,22

响应

HTTP 200

网站组删除成功。 未登录、维护模式限制、网站组不存在、删除他人网站组权限不足或网站组仍关联网站时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`site_group-1`、`site_group-2` 或 `site_group-15`。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。网站组删除成功
oneOf#1.datastring是该操作未返回已删除的网站组数据。
oneOf#2.codestring是业务错误码。site_group-2
oneOf#2.msgstring是错误原因。当前网站组已有网站,请先移除再操作
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "网站组删除成功", "data": "string" }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/site-groups/{group_id}'
用户 API / 网站与安全 / 网站分组 / 获取网站组详情

GET获取网站组详情

GET /v1/site-groups/{group_id}

获取当前登录用户的一条网站组。服务端以网站组 ID 和当前登录用户 ID 联合查询;即使管理员登录,也不能通过此详情路径读取其他用户的网站组。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
group_idpathinteger是网站组 ID。21

响应

HTTP 200

成功、未登录和网站组不存在/无权访问均返回 HTTP 200。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是成功时为空字符串。
oneOf#1.dataobject是网站组记录。
oneOf#1.data.idinteger是网站组 ID。
oneOf#1.data.uidinteger是网站组所属用户 ID。
oneOf#1.data.namestring是网站组名称。
oneOf#1.data.desstring是网站组备注。
oneOf#2.codestring enum是网站组不存在、无权访问或未登录时的业务错误码。site_group-3 | login_required
oneOf#2.msgstring是错误原因。网站组不存在
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "", "data": { "id": 0, "uid": 0, "name": "string", "des": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/site-groups/{group_id}'
用户 API / 网站与安全 / 网站分组 / 更新网站组

PUT更新网站组

PUT /v1/site-groups/{group_id}

更新指定网站组。路径中的网站组 ID 会覆盖请求体 ID;未提供的字段保持原值,至少应有一个字段发生变化。网站组不属于当前用户时需要管理员权限。注意:请求体 `uid` 仅供管理员进行名称唯一性校验,不会修改网站组的实际归属用户。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
group_idpathinteger是要更新的网站组 ID。21

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring否网站组名称;传入时不能为空、经 XSS 过滤,并必须在用于校验的归属用户下唯一。生产网站(新版)
desstring否网站组备注;服务端会进行 XSS 过滤,空字符串可清空。主要业务站点
uidinteger否仅管理员可传。该值只参与 `name` 的唯一性校验,不会写入网站组,也不会改变其实际归属用户。12

请求体示例

{ "name": "生产网站(新版)", "des": "主要业务站点", "uid": 12 }

响应

HTTP 200

网站组更新成功。 未登录、维护模式限制、网站组不存在、跨用户更新权限不足、名称校验失败或没有变更时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`site_group-6`、`site_group-7`、`site_group-9`、`site_group-11`、`site_group-14`、`site_group-16` 或 `site_group-17`。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。更新网站组成功
oneOf#1.datastring是该操作未返回更新后的网站组对象。
oneOf#2.codestring是业务错误码。site_group-14
oneOf#2.msgstring是错误原因。数据未更改
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "更新网站组成功", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"生产网站(新版)","des":"主要业务站点","uid":12}' \ 'https://master.example.com/v1/site-groups/{group_id}'
用户 API / 网站与安全 / 域名管理

域名管理

域名检查和域名解析信息。

接口列表

POST
/v1/cname-check
批量检查域名 CNAME — 检查多个域名是否解析到指定 CNAME。请求体是以业务标识为键的 JSON 对象,每个值包含待检查的 domain 和目标 cname;服务端逐项查询 CNAM
GET
/v1/domains
查询网站域名与 DNS 同步状态 — 分页查询网站绑定的域名及其 CNAME、DNS API 和同步任务状态,按域名记录 ID 倒序返回。普通用户只可查询自己的域名,管理员可用 uid 查询指定用户
POST
/v1/domains
批量创建域名 DNS 记录同步任务 — 为一个或多个现有网站域名创建“域名 DNS 记录同步”任务并将 task_id 写回域名记录。请求体必须是数组;普通用户只能同步自己的域名,管理员可用每项 ui
用户 API / 网站与安全 / 域名管理 / 批量检查域名 CNAME

POST批量检查域名 CNAME

POST /v1/cname-check

检查多个域名是否解析到指定 CNAME。请求体是以业务标识为键的 JSON 对象,每个值包含待检查的 domain 和目标 cname;服务端逐项查询 CNAME,目标不直接匹配时还会跟随一层 CNAME 链再次比较。通配符域名会按通配符检查域名进行解析。返回对象保留输入键并以布尔值表示每项是否匹配。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

键为调用方业务标识、值为 domain/cname 检查参数的对象;每个键都会在响应中返回对应布尔结果。

响应

HTTP 200

业务结果通过 HTTP 200 返回。请求格式正确时返回每个输入键对应的 CNAME 匹配布尔值;请求体不是对象、系统维护或认证失效时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,CNAME 检查完成时固定为 0。0
oneOf#1.msgstring enum是检查成功时固定为空字符串。
oneOf#1.dataobject是以请求键为属性名的检查结果;true 表示 DNS CNAME 直接或经一层别名链匹配,false 表示不匹配或 DNS 查询失败。
oneOf#2.codestring enum是业务错误码:cname_check-1 表示请求体不是字典对象,maintain 表示当前禁止写操作,login_required 表示认证无效。cname_check-1 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文请求格式、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": {} }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ 'https://master.example.com/v1/cname-check'
用户 API / 网站与安全 / 域名管理 / 查询网站域名与 DNS 同步状态

GET查询网站域名与 DNS 同步状态

GET /v1/domains

分页查询网站绑定的域名及其 CNAME、DNS API 和同步任务状态,按域名记录 ID 倒序返回。普通用户只可查询自己的域名,管理员可用 uid 查询指定用户。domain 使用包含匹配;limit=0 时返回全部匹配记录。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,默认 1。服务端仅校验其为数字;分页偏移按 (page - 1) × limit 计算。
limitqueryinteger(int32)否每页记录数,默认 10;传 0 时取消 SQL limit。
uidqueryinteger(int64)否仅管理员可用:筛选网站所属用户 ID。普通用户提供该参数不会改变查询范围。
domainquerystring否按域名进行包含匹配,不是精确匹配。
site_idqueryinteger(int64)否精确筛选所属网站 ID。
dnsapi_statequerystring否DNS API 设置状态:set 仅返回已设置 s.dns_api 的网站域名,not_set 仅返回未设置的。其他值不会增加筛选条件。
task_statequerystring否精确筛选关联域名 DNS 同步任务的 state 值。

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功响应含 code、count、data,不含 msg 字段;分页参数或认证失败时返回业务错误封装。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.countinteger(int64)是当前权限和筛选条件下的域名记录总数。
oneOf#1.dataarray是当前页域名记录,按 domain.id 倒序排列。
oneOf#1.dataarray<object>否当前页域名记录,按 domain.id 倒序排列。
oneOf#1.data[].usernamestring是网站所属用户登录名。
oneOf#1.data[].uidinteger(int64)是网站所属用户 ID。
oneOf#1.data[].idinteger(int64)是域名记录 ID。
oneOf#1.data[].site_idinteger(int64)是所属网站 ID。
oneOf#1.data[].domainstring是网站绑定的域名。
oneOf#1.data[].cnamestring是根据网站 cname_mode 及其 CNAME 域名配置计算出的完整 CNAME 目标。
oneOf#1.data[].dns_apiinteger(int64)是网站关联的 DNS API 凭据 ID;null 表示尚未设置。
oneOf#1.data[].statestring是关联域名 DNS 同步任务状态;无任务时为 null。
oneOf#1.data[].retstring是关联域名 DNS 同步任务返回内容;无任务时为 null。
oneOf#2.codestring enum是分页参数错误或认证失效的业务错误码。domain-2 | domain-3 | login_required
oneOf#2.msgstring是分页参数或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/domains'
用户 API / 网站与安全 / 域名管理 / 批量创建域名 DNS 记录同步任务

POST批量创建域名 DNS 记录同步任务

POST /v1/domains

为一个或多个现有网站域名创建“域名 DNS 记录同步”任务并将 task_id 写回域名记录。请求体必须是数组;普通用户只能同步自己的域名,管理员可用每项 uid 指定或代管用户。每个域名必须已配置 DNS API,否则不会创建同步任务。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

需要创建 DNS 记录同步任务的域名项数组。空数组按服务端会直接成功返回但不会创建任务。

字段类型必填说明示例
(root)array<object>否需要创建 DNS 记录同步任务的域名项数组。空数组按服务端会直接成功返回但不会创建任务。[{"id":9001},{"id":9002}]
[].idoneOf是要同步的 domain 记录 ID。
[].id(oneOf#1)integer(int64)否
[].id(oneOf#2)string否
[].uidinteger(int64)否可选域名所属用户 ID。仅管理员可提交;用于代管指定用户的域名。

请求体示例

[ { "id": 9001 }, { "id": 9002 } ]

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时表示所有请求项的同步任务已发送,data 为 null;请求体格式、域名 ID/归属、DNS API 配置、权限或认证失败时返回业务错误码,并回滚本次批量操作。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是全部域名同步任务发送成功提示。任务发送成功
oneOf#1.dataobject是成功时固定为 null。
oneOf#2.codestring enum是请求体格式、域名 ID/归属、DNS API 配置、管理员权限或认证失败的业务错误码。domain-1 | domain-4 | domain-5 | domain-6 | domain-7 | domain-8 | domain-9 | login_required
oneOf#2.msgstring是批量同步任务创建失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": {} }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '[{"id":9001},{"id":9002}]' \ 'https://master.example.com/v1/domains'
用户 API / 网站与安全 / 证书管理

证书管理

TLS 证书管理。

接口列表

GET
/v1/certs
查询证书列表 — 按当前身份查询证书列表,并可组合分页、域名、所属用户、证书 ID、名称、备注、类型、DNS API、到期天数、启用状态、同步状态、签发状态和可用性条件。普通用户
POST
/v1/certs
添加一个或多个证书 — 创建一个或多个证书记录;请求体可以是单个 JSON 对象,也可以是对象数组,数组中的全部证书在同一个数据库事务中处理。普通用户证书归属于当前账号,管理员可以通过
PUT
/v1/certs
批量更新证书 — 在一个数据库事务中更新一个或多个证书;请求体可以是单个对象或对象数组,服务端会将单对象包装成数组处理。每个更新对象必须带证书 id,任一对象不存在、越权或校验失
DELETE
/v1/certs/{cert_id}
删除一个或多个证书 — 删除路径中指定的一个或多个证书,多个 ID 使用英文逗号分隔并在同一事务中处理。普通用户只能删除自己的证书,管理员可删除其他用户证书。每个证书必须已禁用,且关联
GET
/v1/certs/{cert_id}
获取证书详情或下载证书包 — 按证书 ID 获取证书原始详情。普通请求返回包含证书 PEM 和私钥 PEM 的 JSON 记录;传入查询参数 action=download 时改为下载 gz
PUT
/v1/certs/{cert_id}
更新指定证书 — 按路径证书 ID 更新一条证书。请求体必须是 JSON 对象,路径 ID 会覆盖请求体中可能存在的 id;单条接口不接受数组。名称、备注、类型、DNS API、
用户 API / 网站与安全 / 证书管理 / 查询证书列表

GET查询证书列表

GET /v1/certs

按当前身份查询证书列表,并可组合分页、域名、所属用户、证书 ID、名称、备注、类型、DNS API、到期天数、启用状态、同步状态、签发状态和可用性条件。普通用户始终只返回自己的证书,即使传入 `uid` 也不会扩大数据范围;管理员可查看全部用户并用 `uid` 精确筛选。结果按证书 ID 倒序排列,`limit=0` 返回全部匹配记录。列表只返回管理和任务状态摘要,不返回证书 PEM 正文或私钥。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,从 1 开始;仅含十进制数字,省略时为 1。`limit=0` 时仍会校验该值,但不参与截取结果。
limitqueryinteger(int32)否每页数量,仅含十进制数字;省略时为 10,传 0 时取消分页并返回全部匹配记录。
domainquerystring否域名关键字,对证书的空格分隔域名文本执行包含匹配。
domainsquerystring否精确匹配多个证书域名,一行一个域名;每项必须是合法域名或至少三级的通配符域名。服务端去除普通空格后按换行等剩余空白拆分,并匹配证书域名列表中的完整项。
uidqueryinteger(int64)否证书所属用户 ID。管理员传入时按该用户精确筛选;普通用户传入时会被忽略,结果仍固定为当前用户的数据。
idqueryinteger(int64)否证书 ID,精确匹配。
namequerystring否证书名称关键字,执行包含匹配。
desquerystring否证书备注关键字,执行包含匹配。
typequerystring否证书来源类型,精确匹配:`custom` 为用户上传,`lets` 为 Let's Encrypt,`zerossl` 为 ZeroSSL,`buypass` 为 BuyPass。
dnsapiqueryinteger(int64)否签发证书所使用的 DNS API 配置 ID,精确匹配。
expirequeryinteger(int32)否到期阈值天数,返回到期时间早于“当前时间加该天数”的证书;0 表示已经到期,也接受负整数以查询更早到期的记录。
enablequeryinteger否证书启用状态:1 表示启用,0 表示禁用。
sync_statequerystring否证书同步任务状态。`done` 同时匹配同步任务已完成和没有同步任务的证书;其他值仅匹配对应任务状态。
issue_statequerystring否自动证书签发任务状态。`failed` 同时匹配已停用的签发任务和状态为 failed 的任务;其他值要求任务仍启用且状态精确匹配。
validquerystring否可用性筛选开关;传任意非空值都会启用。启用后只返回证书已启用,且没有签发任务或签发任务状态为 done 的记录;该条件不检查同步任务状态,建议传 1。

响应

HTTP 200

业务结果通过 HTTP 200 返回。查询成功时返回匹配总数和当前页证书摘要;页码、每页数量或精确域名列表格式错误,以及认证失效时返回字符串业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,列表查询成功时固定为 0。0
oneOf#1.countinteger(int64)是应用全部筛选条件后的记录总数,不受当前页和每页数量限制。
oneOf#1.dataarray是按证书 ID 倒序排列的当前页证书摘要;`limit=0` 时包含全部匹配记录。
oneOf#1.dataarray<object>否按证书 ID 倒序排列的当前页证书摘要;`limit=0` 时包含全部匹配记录。
oneOf#1.data[].idinteger(int64)是证书唯一 ID。
oneOf#1.data[].namestring是用于识别该证书记录的显示名称。
oneOf#1.data[].desstring是证书备注,可为空字符串。
oneOf#1.data[].dnsapiinteger(int64)是自动签发所使用的 DNS API 配置 ID;未指定时为 null。
oneOf#1.data[].auto_renewinteger enum是是否自动续签:1 表示启用,0 表示关闭;主要用于自动签发证书。0 | 1
oneOf#1.data[].typestring enum是证书来源类型,用于区分用户上传和不同自动签发机构。custom | lets | zerossl | buypass
oneOf#1.data[].domainstring是证书覆盖的域名,多个域名使用空格分隔;尚未取得域名信息时可能为 null。
oneOf#1.data[].start_timestring是数据库返回的证书生效时间;未签发或未解析出时间时为 null。非空值由 JSON 序列化器输出为 HTTP 日期字符串。
oneOf#1.data[].expire_time2string是证书到期时间,格式为 `YYYY-MM-DD HH:mm:ss`;未签发或未解析出时间时为 null。
oneOf#1.data[].create_at2string是证书记录创建时间,格式为 `YYYY-MM-DD HH:mm:ss`;历史记录没有时间时为 null。
oneOf#1.data[].update_atstring是数据库返回的最后更新时间;历史记录没有时间时为 null。非空值由 JSON 序列化器输出为 HTTP 日期字符串。
oneOf#1.data[].enableinteger enum是证书启用状态:1 表示启用,0 表示禁用。0 | 1
oneOf#1.data[].issue_statestring enum是签发任务状态;自定义证书或没有关联签发任务时为 null。pending | process | failed | done |
oneOf#1.data[].sync_statestring enum是最近一次证书同步任务状态;没有关联同步任务时为 null。pending | process | failed | done |
oneOf#1.data[].uidinteger(int64)是证书所属用户 ID。
oneOf#1.data[].usernamestring是证书所属用户名;关联用户名称不可用时为 null。
oneOf#1.data[].task_enableinteger enum是签发任务是否仍启用:1 表示启用,0 表示已停用;没有签发任务时为 null。0 | 1 |
oneOf#1.data[].task_retstring是签发任务返回信息或失败原因;任务没有返回内容时为 null。
oneOf#1.data[].retry_at2string是签发任务下次重试时间,格式为 `YYYY-MM-DD HH:mm:ss`;没有计划重试时为 null。
oneOf#2.codestring enum是业务错误码:`cert-34` 表示 page 不是数字,`cert-35` 表示 limit 不是数字,`cert-44` 表示 `domains` 中存在无效域名,`login_required` 表示认证无效。cert-34 | cert-35 | cert-44 | login_required
oneOf#2.msgstring是与业务错误码对应的中文分页参数、域名格式或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/certs'
用户 API / 网站与安全 / 证书管理 / 添加一个或多个证书

POST添加一个或多个证书

POST /v1/certs

创建一个或多个证书记录;请求体可以是单个 JSON 对象,也可以是对象数组,数组中的全部证书在同一个数据库事务中处理。普通用户证书归属于当前账号,管理员可以通过 `uid` 指定所属用户。`custom` 表示上传已有证书和私钥,`lets`、`zerossl`、`buypass` 表示自动签发;自动签发证书创建后会立即建立签发任务。任一证书校验失败时整个批次回滚,不会保留已插入的部分记录。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
oneOf#1.uidinteger(int64)否证书所属用户 ID;省略时使用当前登录用户,仅管理员可指定,否则返回 `cert-48`。
oneOf#1.namestring是证书显示名称;服务端会过滤可执行的 HTML,处理后不得为空,同一所属用户下不可重复,并只保存处理后前 200 个字符。创建时必填。
oneOf#1.desstring否证书备注;服务端会过滤可执行的 HTML,省略时保存为空字符串。
oneOf#1.typestring enum否证书类型:`custom` 为上传证书,`lets` 为 Let's Encrypt,`zerossl` 为 ZeroSSL,`buypass` 为 BuyPass。省略时读取全局或用户证书默认配置。custom | lets | zerossl | buypass
oneOf#1.dnsapioneOf否自动签发所使用的 DNS API 配置 ID;可显式传 null 表示不使用,非空时必须是已存在的 DNS API。通配符自动证书必须指定非空 DNS API。省略时读取用户默认配置。
oneOf#1.dnsapi(oneOf#1)integer否
oneOf#1.dnsapi(oneOf#2)string否
oneOf#1.dnsapi(oneOf#3)string否
oneOf#1.domainstring否自动签发证书的域名,类型为 `lets`、`zerossl` 或 `buypass` 时必填并会转为小写;通配符域名还必须配合 DNS API。`custom` 类型不会采用该字段,而是从证书的 SAN/CN 中解析域名。
oneOf#1.keystring(password)否上传证书的私钥 PEM;`custom` 类型必填,服务端会去除首尾空白、校验末尾 PEM 分隔符并验证与证书匹配。其他类型通常省略。示例不得填入真实私钥。
oneOf#1.certstring否上传证书链 PEM;`custom` 类型必填,服务端会解析每个证书并验证有效性。其他类型通常省略。示例不得填入真实证书内容。
oneOf#2array<object>否批量证书创建对象数组;数组可以为空,空数组会提交一个不含证书的空批次并返回空数据字符串。数组中任一对象校验失败时整批回滚。
oneOf#2[].uidinteger(int64)否证书所属用户 ID;省略时使用当前登录用户,仅管理员可指定,否则返回 `cert-48`。
oneOf#2[].namestring是证书显示名称;服务端会过滤可执行的 HTML,处理后不得为空,同一所属用户下不可重复,并只保存处理后前 200 个字符。创建时必填。
oneOf#2[].desstring否证书备注;服务端会过滤可执行的 HTML,省略时保存为空字符串。
oneOf#2[].typestring enum否证书类型:`custom` 为上传证书,`lets` 为 Let's Encrypt,`zerossl` 为 ZeroSSL,`buypass` 为 BuyPass。省略时读取全局或用户证书默认配置。custom | lets | zerossl | buypass
oneOf#2[].dnsapioneOf否自动签发所使用的 DNS API 配置 ID;可显式传 null 表示不使用,非空时必须是已存在的 DNS API。通配符自动证书必须指定非空 DNS API。省略时读取用户默认配置。
oneOf#2[].dnsapi(oneOf#1)integer否
oneOf#2[].dnsapi(oneOf#2)string否
oneOf#2[].dnsapi(oneOf#3)string否
oneOf#2[].domainstring否自动签发证书的域名,类型为 `lets`、`zerossl` 或 `buypass` 时必填并会转为小写;通配符域名还必须配合 DNS API。`custom` 类型不会采用该字段,而是从证书的 SAN/CN 中解析域名。
oneOf#2[].keystring(password)否上传证书的私钥 PEM;`custom` 类型必填,服务端会去除首尾空白、校验末尾 PEM 分隔符并验证与证书匹配。其他类型通常省略。示例不得填入真实私钥。
oneOf#2[].certstring否上传证书链 PEM;`custom` 类型必填,服务端会解析每个证书并验证有效性。其他类型通常省略。示例不得填入真实证书内容。

请求体示例

{ "uid": 0, "name": "string", "des": "string", "type": "string", "dnsapi": null, "domain": "string", "key": "YOUR_PASSWORD", "cert": "string" }

响应

HTTP 200

业务结果通过 HTTP 200 返回。全部证书校验并提交后返回创建结果;配额、套餐、名称、类型、DNS API、域名、PEM、管理员归属、证书有效性、参数状态、兼容性更新字段、系统维护或认证校验失败时返回字符串业务错误码,整个批次事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,所有证书创建并提交后固定为 0。0
oneOf#1.msgstring enum是证书创建批次成功后返回的确认消息。证书添加成功
oneOf#1.datastring是正常创建时为新证书 ID 的英文逗号分隔字符串;空数组时为空字符串。若兼容性地传入 `id` 触发更新逻辑,内容可能是更新差异 JSON 字符串。
oneOf#2.codestring enum是业务错误码:6、7 表示兼容性 ID 格式错误或记录不存在;8、23 表示证书数量超限或普通用户未购买有效套餐;9、11、12 表示名称为空、重复或缺失;14、15 表示证书类型为空或无效;17、18 表示 DNS API 格式错误或不存在;19、21、22 表示自动证书域名为空、通配符缺少 DNS API 或域名未提供;25、26、27、28、29、40、41、43、46 表示私钥/证书缺失、格式、解析、匹配或域名提取失败;30、31、42、45 表示启用、自动续签或强制禁用参数无效;32 表示证书仍被网站使用且未强制禁用;38、39 表示重新签发仅支持已有自动证书或不能在创建时使用;48、49 表示管理员专属归属字段或目标证书权限不足;`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cert-6 | cert-7 | cert-8 | cert-9 | cert-11 | cert-12 | cert-14 | cert-15 | cert-17 | cert-18 | cert-19 | cert-21 | cert-22 | cert-23 | cert-25 | cert-26 | cert-27 | cert-28 | cert-29 | cert-30 | cert-31 | cert-32 | cert-38 | cert-39 | cert-40 | cert-41 | cert-42 | cert-43 | cert-45 | cert-46 | cert-48 | cert-49 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文配额、套餐、字段、证书材料、权限、任务状态、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"uid":0,"name":"string","des":"string","type":"string","dnsapi":null,"domain":"string","key":"YOUR_PASSWORD","cert":"string"}' \ 'https://master.example.com/v1/certs'
用户 API / 网站与安全 / 证书管理 / 批量更新证书

PUT批量更新证书

PUT /v1/certs

在一个数据库事务中更新一个或多个证书;请求体可以是单个对象或对象数组,服务端会将单对象包装成数组处理。每个更新对象必须带证书 id,任一对象不存在、越权或校验失败时整批回滚。支持修改名称、备注、类型、DNS API、域名、证书材料、启用/续签状态和重新签发;自动证书变化可能创建签发及同步任务,禁用正在使用的证书时可用 force_disable=1 同时关闭关联网站 HTTPS 并创建网站同步任务。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
oneOf#1.idoneOf是要更新的证书 ID;必须是数字或数字字符串,记录必须存在,跨用户更新需要管理员身份。
oneOf#1.id(oneOf#1)integer否
oneOf#1.id(oneOf#2)string否
oneOf#1.uidinteger(int64)否兼容性所属用户上下文字段;仅管理员可传,用于校验目标证书所属用户,不会转移证书。
oneOf#1.namestring否新的证书名称;服务端过滤 HTML、校验同一用户下唯一,并保存处理后前 200 个字符,省略时保持原值。
oneOf#1.desstring否新的证书备注;服务端过滤 HTML,可传空字符串清空备注,省略时保持原值。
oneOf#1.typestring enum否新的证书类型;由 custom 切换到自动类型会创建签发任务,由自动类型切换为 custom 会结束旧签发任务,省略时保持原类型。custom | lets | zerossl | buypass
oneOf#1.dnsapioneOf否新的 DNS API 配置 ID;非空时必须对应已有 DNS API,传 null 可清除,省略时保持原值。
oneOf#1.dnsapi(oneOf#1)integer否
oneOf#1.dnsapi(oneOf#2)string否
oneOf#1.dnsapi(oneOf#3)string否
oneOf#1.domainstring否自动证书的新域名;自动类型下转为小写并触发重新签发,通配符必须指定 DNS API,省略时保持原值。custom 类型会从上传证书 SAN/CN 重新解析。
oneOf#1.keystring(password)否新的自上传证书私钥 PEM;仅 custom 类型校验末尾格式和证书匹配,内容变化且证书在使用时创建同步任务。示例不得使用真实私钥。
oneOf#1.certstring否新的自上传证书链 PEM;仅 custom 类型解析并校验证书,内容变化且证书在使用时可能创建同步任务。示例不得使用真实证书。
oneOf#1.force_disableinteger enum否禁用正在被网站使用的证书时的强制标志:0 返回 cert-32,1 清空关联网站 HTTPS 配置并创建网站同步任务。0 | 1
oneOf#1.auto_renewinteger enum否自动续签状态:1 启用,0 关闭;省略时保持原值。0 | 1
oneOf#1.enableinteger enum否证书启用状态:1 启用,0 禁用;禁用会创建证书删除任务,省略时保持原值。0 | 1
oneOf#1.reissueoneOf否重新签发开关;字段存在即触发重新签发,目标必须是 lets、zerossl 或 buypass 类型。
oneOf#1.reissue(oneOf#1)boolean否
oneOf#1.reissue(oneOf#2)integer否
oneOf#2array<object>否批量证书更新对象数组;每项都必须包含 id,任一项失败时整批回滚。
oneOf#2[].idoneOf是要更新的证书 ID;必须是数字或数字字符串,记录必须存在,跨用户更新需要管理员身份。
oneOf#2[].id(oneOf#1)integer否
oneOf#2[].id(oneOf#2)string否
oneOf#2[].uidinteger(int64)否兼容性所属用户上下文字段;仅管理员可传,用于校验目标证书所属用户,不会转移证书。
oneOf#2[].namestring否新的证书名称;服务端过滤 HTML、校验同一用户下唯一,并保存处理后前 200 个字符,省略时保持原值。
oneOf#2[].desstring否新的证书备注;服务端过滤 HTML,可传空字符串清空备注,省略时保持原值。
oneOf#2[].typestring enum否新的证书类型;由 custom 切换到自动类型会创建签发任务,由自动类型切换为 custom 会结束旧签发任务,省略时保持原类型。custom | lets | zerossl | buypass
oneOf#2[].dnsapioneOf否新的 DNS API 配置 ID;非空时必须对应已有 DNS API,传 null 可清除,省略时保持原值。
oneOf#2[].dnsapi(oneOf#1)integer否
oneOf#2[].dnsapi(oneOf#2)string否
oneOf#2[].dnsapi(oneOf#3)string否
oneOf#2[].domainstring否自动证书的新域名;自动类型下转为小写并触发重新签发,通配符必须指定 DNS API,省略时保持原值。custom 类型会从上传证书 SAN/CN 重新解析。
oneOf#2[].keystring(password)否新的自上传证书私钥 PEM;仅 custom 类型校验末尾格式和证书匹配,内容变化且证书在使用时创建同步任务。示例不得使用真实私钥。
oneOf#2[].certstring否新的自上传证书链 PEM;仅 custom 类型解析并校验证书,内容变化且证书在使用时可能创建同步任务。示例不得使用真实证书。
oneOf#2[].force_disableinteger enum否禁用正在被网站使用的证书时的强制标志:0 返回 cert-32,1 清空关联网站 HTTPS 配置并创建网站同步任务。0 | 1
oneOf#2[].auto_renewinteger enum否自动续签状态:1 启用,0 关闭;省略时保持原值。0 | 1
oneOf#2[].enableinteger enum否证书启用状态:1 启用,0 禁用;禁用会创建证书删除任务,省略时保持原值。0 | 1
oneOf#2[].reissueoneOf否重新签发开关;字段存在即触发重新签发,目标必须是 lets、zerossl 或 buypass 类型。
oneOf#2[].reissue(oneOf#1)boolean否
oneOf#2[].reissue(oneOf#2)integer否

请求体示例

{ "id": null, "uid": 0, "name": "string", "des": "string", "type": "string", "dnsapi": null, "domain": "string", "key": "YOUR_PASSWORD", "cert": "string", "force_disable": 0, "auto_renew": 0, "enable": 0, "reissue": null }

响应

HTTP 200

业务结果通过 HTTP 200 返回。全部证书更新并提交后返回确认消息;请求体格式、目标证书、名称、类型、DNS API、域名、PEM、权限、启用/续签、重新签发、网站引用、系统维护或认证校验失败时返回字符串业务错误码,整个批次事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,所有证书更新并提交后固定为 0。0
oneOf#1.msgstring enum是证书更新批次成功后返回的确认消息。更新证书成功
oneOf#1.datastring enum是更新成功时没有额外业务数据,固定为 null。
oneOf#2.codestring enum是业务错误码:5 表示详情请求体不是对象;6、7 表示证书 ID 格式错误或记录不存在;9、11 表示名称为空或重复;14、15 表示类型为空或无效;17、18 表示 DNS API 格式错误或不存在;19、21 表示自动证书域名为空或通配符缺少 DNS API;25、27、29、40、41、43、46 表示私钥或证书缺失、格式、匹配、解析或域名提取失败;30、31 表示启用状态无效;32 表示证书仍被网站使用且未强制禁用;36 表示批量请求不是数组;38、39 表示重新签发目标类型或更新状态不正确;42 表示自动续签无效;45 表示强制禁用参数无效;48、49 表示管理员归属字段或目标证书权限不足;maintain 表示当前禁止写操作,login_required 表示认证无效。cert-5 | cert-6 | cert-7 | cert-9 | cert-11 | cert-14 | cert-15 | cert-17 | cert-18 | cert-19 | cert-21 | cert-25 | cert-27 | cert-29 | cert-30 | cert-31 | cert-32 | cert-36 | cert-38 | cert-39 | cert-40 | cert-41 | cert-42 | cert-43 | cert-45 | cert-46 | cert-48 | cert-49 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文请求格式、目标记录、字段、证书材料、网站引用、权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"id":null,"uid":0,"name":"string","des":"string","type":"string","dnsapi":null,"domain":"string","key":"YOUR_PASSWORD","cert":"string","force_disable":0,"auto_renew":0,"enable":0,"reissue":null}' \ 'https://master.example.com/v1/certs'
用户 API / 网站与安全 / 证书管理 / 删除一个或多个证书

DELETE删除一个或多个证书

DELETE /v1/certs/{cert_id}

删除路径中指定的一个或多个证书,多个 ID 使用英文逗号分隔并在同一事务中处理。普通用户只能删除自己的证书,管理员可删除其他用户证书。每个证书必须已禁用,且关联任务为空或状态为 done;任一目标失败时整批回滚。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
cert_idpathstring是要删除的证书 ID;多个 ID 按 10021,10022 形式用英文逗号连接,每段必须为十进制数字。

响应

HTTP 200

业务结果通过 HTTP 200 返回。全部目标删除并提交后返回确认消息;ID、记录、权限、启用状态、任务状态、维护或认证校验失败返回业务错误码,事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是删除成功状态码,固定为 0。0
oneOf#1.msgstring enum是证书删除批次成功消息。证书删除成功
oneOf#1.datastring enum是删除成功时固定为 null。
oneOf#2.codestring enum是业务错误码:1 表示 ID 格式错误,2 表示证书不存在,3 表示证书仍启用,4 表示证书任务尚未完成,47 表示普通用户删除其他用户证书,maintain 和 login_required 表示维护或认证失败。cert-1 | cert-2 | cert-3 | cert-4 | cert-47 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文 ID、记录、状态、权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/certs/{cert_id}'
用户 API / 网站与安全 / 证书管理 / 获取证书详情或下载证书包

GET获取证书详情或下载证书包

GET /v1/certs/{cert_id}

按证书 ID 获取证书原始详情。普通请求返回包含证书 PEM 和私钥 PEM 的 JSON 记录;传入查询参数 action=download 时改为下载 gzip 压缩包,包内包含以证书域名命名的 .pem 和 .key 文件。普通用户只能读取自己的证书,管理员可读取其他用户证书;该接口会返回私钥,调用方必须在安全环境中使用并妥善保管响应。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
cert_idpathinteger(int64)是要读取的证书 ID;路由只接受十进制整数。
actionquerystring否下载动作开关;传 download 返回 gzip 证书包,省略或传其他值返回 JSON 详情。

响应

HTTP 200

业务结果通过 HTTP 200 返回;普通请求返回 JSON 详情,action=download 返回二进制 gzip 压缩包。记录不存在、读取其他用户证书且当前身份不是管理员或认证失效时,JSON 分支返回字符串业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,证书详情读取成功时固定为 0。0
oneOf#1.msgstring enum是详情读取成功时没有提示,JSON 序列化为 null。
oneOf#1.dataobject是数据库证书详情记录,包含证书和私钥敏感字段。
oneOf#1.data.idinteger(int64)是证书唯一 ID。
oneOf#1.data.uidinteger(int64)是证书所属用户 ID。
oneOf#1.data.namestring是证书显示名称。 具体说明
oneOf#1.data.desstring是证书备注,可为空字符串。
oneOf#1.data.typestring enum是证书来源类型。 具体说明custom | lets | zerossl | buypass
oneOf#1.data.domainstring是证书覆盖的域名,多个域名以空格分隔;未解析时为 null。
oneOf#1.data.dnsapiinteger(int64)是自动签发使用的 DNS API ID;未指定时为 null。
oneOf#1.data.certstring是证书链 PEM 原文;此字段包含敏感材料,示例不得使用真实证书。
oneOf#1.data.keystring(password)是证书私钥 PEM 原文;此字段是敏感凭据,示例不得使用真实私钥。
oneOf#1.data.start_timestring是证书生效时间,格式为 YYYY-MM-DD HH:mm:ss;未签发时为 null。
oneOf#1.data.expire_timestring是证书到期时间,格式为 YYYY-MM-DD HH:mm:ss;未签发时为 null。
oneOf#1.data.auto_renewinteger enum是自动续签状态:1 启用,0 关闭。0 | 1
oneOf#1.data.create_atstring是证书记录创建时间,格式为 YYYY-MM-DD HH:mm:ss。
oneOf#1.data.update_atstring是证书记录最后更新时间,格式为 YYYY-MM-DD HH:mm:ss。
oneOf#1.data.enableinteger enum是证书启用状态:1 启用,0 禁用。0 | 1
oneOf#1.data.task_idinteger(int64)是最近一次证书同步或删除任务 ID;没有任务时为 null。
oneOf#1.data.issue_task_idinteger(int64)是自动签发任务 ID;自上传证书没有签发任务时为 null。
oneOf#1.data.versioninteger(int64)是证书配置版本号,每次更新递增。
oneOf#2.codestring enum是业务错误码:cert-33 表示证书不存在,cert-50 表示当前用户无权读取其他用户证书,login_required 表示认证无效。cert-33 | cert-50 | login_required
oneOf#2.msgstring是与业务错误码对应的中文记录不存在、权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "id": 0, "uid": 0, "name": "string", "des": "string", "type": "string", "domain": "string", "dnsapi": 0, "cert": "string", "key": "YOUR_PASSWORD", "start_time": "string", "expire_time": "string", "auto_renew": 0, "create_at": "string", "update_at": "string", "enable": 0, "task_id": 0, "issue_task_id": 0, "version": 0 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/certs/{cert_id}'
用户 API / 网站与安全 / 证书管理 / 更新指定证书

PUT更新指定证书

PUT /v1/certs/{cert_id}

按路径证书 ID 更新一条证书。请求体必须是 JSON 对象,路径 ID 会覆盖请求体中可能存在的 id;单条接口不接受数组。名称、备注、类型、DNS API、域名、证书材料、启用/续签和重新签发字段均可按需提供,未提供字段保持原值。普通用户只能更新自己的证书,管理员可更新其他用户证书;任一校验失败返回 HTTP 200 业务错误。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
cert_idpathinteger(int64)是要更新的证书 ID;路由只接受十进制整数,并覆盖请求体中的 id。

请求体

请求体必填。

Content-Type:application/json

指定证书的部分更新对象;路径 ID 为唯一目标。

字段类型必填说明示例
uidinteger(int64)否兼容性所属用户上下文,仅管理员可传;不会转移证书。
namestring否新的证书名称;过滤 HTML、检查同用户唯一并保存前 200 个字符,省略时保持原值。
desstring否新的证书备注,可传空字符串清空,省略时保持原值。
typestring enum否新的证书类型;自动类型切换会建立签发任务,省略时保持原类型。custom | lets | zerossl | buypass
dnsapioneOf否新的 DNS API ID;非空时必须存在,null 清除,省略时保持原值。
dnsapi(oneOf#1)integer否
dnsapi(oneOf#2)string否
dnsapi(oneOf#3)string否
domainstring否自动证书的新域名;自动类型下转小写并触发签发,通配符需 DNS API,custom 类型从 PEM SAN/CN 解析。
keystring(password)否custom 类型的新私钥 PEM;校验格式和证书匹配,示例不得使用真实私钥。
certstring否custom 类型的新证书链 PEM;校验解析,示例不得使用真实证书。
force_disableinteger enum否禁用在用证书的强制标志;0 返回 cert-32,1 同时关闭关联网站 HTTPS 并同步。0 | 1
auto_renewinteger enum否自动续签状态,1 启用、0 关闭,省略时保持原值。0 | 1
enableinteger enum否证书启用状态,1 启用、0 禁用;禁用会创建证书删除任务。0 | 1
reissueoneOf否字段存在即重新签发;目标必须是 lets、zerossl 或 buypass 自动证书。
reissue(oneOf#1)boolean否
reissue(oneOf#2)integer否

请求体示例

{ "uid": 0, "name": "string", "des": "string", "type": "string", "dnsapi": null, "domain": "string", "key": "YOUR_PASSWORD", "cert": "string", "force_disable": 0, "auto_renew": 0, "enable": 0, "reissue": null }

响应

HTTP 200

业务结果通过 HTTP 200 返回。更新成功返回确认消息;对象格式、证书记录、字段、证书材料、网站引用、权限、任务和认证校验失败返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是更新成功状态码,固定为 0。0
oneOf#1.msgstring enum是证书更新成功消息。更新证书成功
oneOf#1.datastring enum是更新成功时固定为 null。
oneOf#2.codestring enum是业务错误码:5 表示请求体不是对象;6、7 表示 ID 格式错误或证书不存在;9、11、14、15、17、18、19、21 表示名称、类型、DNS API 或域名校验失败;25、27、29、40、41、43、46 表示证书材料、匹配、解析或域名提取失败;30、31、32 表示启用状态或在用证书限制;38、39 表示重新签发限制;42、45 表示续签或强制禁用参数无效;48、49 表示管理员字段或目标权限不足;maintain 和 login_required 表示维护或认证失败。cert-5 | cert-6 | cert-7 | cert-9 | cert-11 | cert-14 | cert-15 | cert-17 | cert-18 | cert-19 | cert-21 | cert-25 | cert-27 | cert-29 | cert-30 | cert-31 | cert-32 | cert-38 | cert-39 | cert-40 | cert-41 | cert-42 | cert-43 | cert-45 | cert-46 | cert-48 | cert-49 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文字段、权限、任务或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"uid":0,"name":"string","des":"string","type":"string","dnsapi":null,"domain":"string","key":"YOUR_PASSWORD","cert":"string","force_disable":0,"auto_renew":0,"enable":0,"reissue":null}' \ 'https://master.example.com/v1/certs/{cert_id}'
用户 API / 网站与安全 / DNS 管理

DNS 管理

DNS 服务商凭证管理。

接口列表

GET
/v1/dnsapis
查询 DNS API 列表 — 分页查询 DNS 服务商凭据记录,按 ID 倒序返回。普通用户只能读取自己的记录并忽略 uid 筛选;管理员可用 uid 查询指定用户的记录。响应会直接返回数据
POST
/v1/dnsapis
创建 DNS 服务商凭据 — 创建用于证书 DNS 验证和网站 DNS 操作的服务商凭据。默认归属当前登录用户;管理员可通过 uid 为指定用户创建。每种服务商类型要求不同的 auth 键。
DELETE
/v1/dnsapis/{api_id}
删除一个或多个 DNS 服务商凭据 — 按路径中的 DNS API ID 删除凭据。支持以英文逗号传入多个 ID;普通用户只能删除自己的记录,管理员可删除其他用户记录。任一记录无效、被证书或网站引用、
GET
/v1/dnsapis/{api_id}
获取自己的 DNS 服务商凭据详情 — 按 ID 读取当前登录用户自己创建的 DNS API 凭据。查询条件始终同时匹配 id 和当前用户 ID,因此管理员也不能通过该接口读取其他用户的详情;记录不存
PUT
/v1/dnsapis/{api_id}
更新 DNS 服务商凭据 — 更新指定 DNS API 凭据的已提交字段;路径 api_id 会覆盖请求体中的 id。普通用户只能更新自己的记录,管理员可以更新任意记录;管理员可额外传 ui
用户 API / 网站与安全 / DNS 管理 / 查询 DNS API 列表

GET查询 DNS API 列表

GET /v1/dnsapis

分页查询 DNS 服务商凭据记录,按 ID 倒序返回。普通用户只能读取自己的记录并忽略 uid 筛选;管理员可用 uid 查询指定用户的记录。响应会直接返回数据库保存的 auth 文本,应避免在不可信环境展示或记录。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,默认 1。服务端仅校验其为数字;分页偏移按 (page - 1) × limit 计算。
limitqueryinteger(int32)否每页记录数,默认 10;传 0 时取消 SQL limit 并返回全部记录。
uidqueryinteger(int64)否仅管理员可用:筛选指定所属用户 ID。普通用户提供该参数不会改变查询范围。

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功响应含 code、count、data,不含 msg 字段;分页参数或认证失败时返回业务错误封装。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.countinteger(int64)是当前权限与 uid 条件下的 DNS API 记录总数。
oneOf#1.dataarray是当前页 DNS API 记录,按 id 倒序排列。
oneOf#1.dataarray<object>否当前页 DNS API 记录,按 id 倒序排列。
oneOf#1.data[].idinteger(int64)是DNS API 记录 ID。
oneOf#1.data[].uidinteger(int64)是凭据所属用户 ID。
oneOf#1.data[].namestring是用户定义的 DNS API 名称。
oneOf#1.data[].desstring是凭据备注。
oneOf#1.data[].typestring是DNS 服务商类型,例如 CloudFlare、Aliyun 或 DNSPod.cn。
oneOf#1.data[].usernamestring是所属用户登录名;关联用户不存在时为 null。
oneOf#1.data[].authstring是数据库保存的 DNS 服务商鉴权 JSON 文本,包含 API Token、密钥或账号等敏感信息。服务端实际会返回此字段;文档示例已脱敏。
oneOf#2.codestring enum是分页参数错误或认证失效的业务错误码。dnsapi-5 | dnsapi-6 | login_required
oneOf#2.msgstring是分页参数或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/dnsapis'
用户 API / 网站与安全 / DNS 管理 / 创建 DNS 服务商凭据

POST创建 DNS 服务商凭据

POST /v1/dnsapis

创建用于证书 DNS 验证和网站 DNS 操作的服务商凭据。默认归属当前登录用户;管理员可通过 uid 为指定用户创建。每种服务商类型要求不同的 auth 键。服务端将 DNS.COM 列入可选类型但没有额外的 auth 键校验,仍需提供非空对象。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
uidinteger(int64)否可选所属用户 ID。仅管理员可提交;省略时使用当前登录用户。
namestring是凭据名称。服务端会过滤 XSS;同一所属用户下不能重名。
desstring否可选备注。服务端会过滤 XSS;省略时保存为空字符串。
typestring enum是DNS 服务商类型。该值决定 auth 所需的键;DNS.COM 当前服务端仅校验 auth 为非空对象。huaweicloud.com | CloudFlare | DNSPod.cn | DNSPod.com | GoDaddy.com | Aliyun | cloudns.net | Name.com | Namecheap | jdcloud.com | dnsdun | DNS.LA | Namesilo.com | DNS.COM
authobject是服务商鉴权对象,字段值为凭据文本,必须脱敏保存和传输。所需键:CloudFlare=CF_Key、CF_Email;DNSPod.cn=DP_Id、DP_Key;DNSPod.com=DPI_Id、DPI_Key;GoDaddy.com=GD_Key、GD_Secret;Aliyun=Ali_Key、Ali_Secret;cloudns.net=CLOUDNS_SUB_AUTH_ID、CLOUDNS_AUTH_PASSWORD;Name.com=Namecom_Username、Namecom_Token;Namecheap=NAMECHEAP_USERNAME、NAMECHEAP_API_KEY、NAMECHEAP_SOURCEIP;jdcloud.com=JD_ACCESS_KEY_ID、JD_ACCESS_KEY_SECRET;dnsdun=Dnsdun_uid、Dnsdun_api_key;huaweicloud.com=huaweicloud_access_key_id、huaweicloud_serect_access_key(源代码键名如此拼写);DNS.LA=LA_Ak、LA_Sk;Namesilo.com=Namesilo_Key;DNS.COM 仅要求非空对象。

请求体示例

{ "name": "生产 Cloudflare", "des": "自动签发证书", "type": "CloudFlare", "auth": { "CF_Email": "admin@example.invalid", "CF_Key": "REDACTED" } }

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时 data 为新 DNS API ID;配额、字段、服务商鉴权键、管理员权限或认证校验失败时返回字符串业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是创建成功提示。dnsapi添加成功
oneOf#1.datainteger(int64)是新建 DNS API 记录 ID。
oneOf#2.codestring是业务错误码,包括配额/字段/鉴权键校验错误 dnsapi-9 至 dnsapi-38、管理员权限错误 dnsapi-36 及认证错误 login_required。
oneOf#2.msgstring是配额、字段、服务商鉴权键、权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": 0 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"生产 Cloudflare","des":"自动签发证书","type":"CloudFlare","auth":{"CF_Email":"admin@example.invalid","CF_Key":"REDACTED"}}' \ 'https://master.example.com/v1/dnsapis'
用户 API / 网站与安全 / DNS 管理 / 删除一个或多个 DNS 服务商凭据

DELETE删除一个或多个 DNS 服务商凭据

DELETE /v1/dnsapis/{api_id}

按路径中的 DNS API ID 删除凭据。支持以英文逗号传入多个 ID;普通用户只能删除自己的记录,管理员可删除其他用户记录。任一记录无效、被证书或网站引用、被设置为证书默认 DNS API 时均拒绝删除并回滚本次事务。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
api_idpathstring是要删除的一个或多个 DNS API 记录 ID,多个 ID 使用英文逗号分隔。

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时 data 为 null;ID 格式、记录、归属、引用关系、默认配置、权限或认证校验失败时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是删除成功提示。dnsapi删除成功
oneOf#1.dataobject是成功时固定为 null。
oneOf#2.codestring enum是ID 格式/记录/引用/默认配置/管理员权限或认证失败的业务错误码。dnsapi-1 | dnsapi-2 | dnsapi-3 | dnsapi-32 | dnsapi-34 | dnsapi-35 | login_required
oneOf#2.msgstring是删除前校验失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": {} }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/dnsapis/{api_id}'
用户 API / 网站与安全 / DNS 管理 / 获取自己的 DNS 服务商凭据详情

GET获取自己的 DNS 服务商凭据详情

GET /v1/dnsapis/{api_id}

按 ID 读取当前登录用户自己创建的 DNS API 凭据。查询条件始终同时匹配 id 和当前用户 ID,因此管理员也不能通过该接口读取其他用户的详情;记录不存在或不归属当前用户时均返回 dnsapi-4。响应包含敏感 auth JSON 文本。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
api_idpathinteger(int64)是要读取的 DNS API 记录 ID。

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时返回 dnsapi 表完整记录;记录不存在、不归属当前用户或认证失效时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是详情读取成功时固定为空字符串。
oneOf#1.dataobject是dnsapi 表的完整凭据记录。
oneOf#1.data.idinteger(int64)是DNS API 记录 ID。
oneOf#1.data.uidinteger(int64)是凭据所属用户 ID,固定为当前登录用户。
oneOf#1.data.namestring是用户定义的凭据名称。
oneOf#1.data.desstring是凭据备注。
oneOf#1.data.typestring是DNS 服务商类型。
oneOf#1.data.authstring是数据库保存的服务商鉴权 JSON 文本,含敏感 Token、密钥或账号信息。文档示例已脱敏。
oneOf#2.codestring enum是记录不存在/不归属当前用户或认证失效的业务错误码。dnsapi-4 | login_required
oneOf#2.msgstring是读取或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "id": 0, "uid": 0, "name": "string", "des": "string", "type": "string", "auth": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/dnsapis/{api_id}'
用户 API / 网站与安全 / DNS 管理 / 更新 DNS 服务商凭据

PUT更新 DNS 服务商凭据

PUT /v1/dnsapis/{api_id}

更新指定 DNS API 凭据的已提交字段;路径 api_id 会覆盖请求体中的 id。普通用户只能更新自己的记录,管理员可以更新任意记录;管理员可额外传 uid 进行归属校验。所有业务字段可选,未提交字段保持原值,且没有实际变更时接口仍成功返回。若提交 auth,服务端按当前或提交后的 type 校验所需服务商键。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
api_idpathinteger(int64)是要更新的 DNS API 记录 ID。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
uidinteger(int64)否可选所属用户 ID。仅管理员可提交;更新时实际归属仍须与现有记录一致,否则要求管理员权限。
namestring否可选新凭据名称。服务端过滤 XSS;提供时不能为空且同一所属用户下不能重名。
desstring否可选新备注。服务端过滤 XSS;可传空字符串清空。
typestring enum否可选新 DNS 服务商类型。仅改 type 而不提交 auth 时,服务端不会重新校验原有 auth。huaweicloud.com | CloudFlare | DNSPod.cn | DNSPod.com | GoDaddy.com | Aliyun | cloudns.net | Name.com | Namecheap | jdcloud.com | dnsdun | DNS.LA | Namesilo.com | DNS.COM
authobject否可选新服务商鉴权对象。提交时按当前或新 type 校验键:CloudFlare=CF_Key、CF_Email;DNSPod.cn=DP_Id、DP_Key;DNSPod.com=DPI_Id、DPI_Key;GoDaddy.com=GD_Key、GD_Secret;Aliyun=Ali_Key、Ali_Secret;cloudns.net=CLOUDNS_SUB_AUTH_ID、CLOUDNS_AUTH_PASSWORD;Name.com=Namecom_Username、Namecom_Token;Namecheap=NAMECHEAP_USERNAME、NAMECHEAP_API_KEY、NAMECHEAP_SOURCEIP;jdcloud.com=JD_ACCESS_KEY_ID、JD_ACCESS_KEY_SECRET;dnsdun=Dnsdun_uid、Dnsdun_api_key;huaweicloud.com=huaweicloud_access_key_id、huaweicloud_serect_access_key;DNS.LA=LA_Ak、LA_Sk;Namesilo.com=Namesilo_Key;DNS.COM 仅要求非空对象。所有值均为敏感凭据。

请求体示例

{ "name": "生产 Cloudflare(新)", "auth": { "CF_Email": "admin@example.invalid", "CF_Key": "REDACTED" } }

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时 data 为 null(包括没有实际字段变化时);记录、归属、字段、鉴权键、管理员权限或认证校验失败时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是更新成功提示。更新dnsapi成功
oneOf#1.dataobject是成功时固定为 null。
oneOf#2.codestring是业务错误码,包括记录/归属/字段/鉴权键错误 dnsapi-7 至 dnsapi-38、管理员权限错误 dnsapi-36、dnsapi-37 及认证错误 login_required。
oneOf#2.msgstring是记录、归属、字段、鉴权键、权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": {} }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"生产 Cloudflare(新)","auth":{"CF_Email":"admin@example.invalid","CF_Key":"REDACTED"}}' \ 'https://master.example.com/v1/dnsapis/{api_id}'
用户 API / 网站与安全 / 访问控制

访问控制

ACL 访问控制规则。

接口列表

GET
/v1/acls
分页查询 ACL 列表 — 分页查询当前身份可见的网站 ACL 规则集。普通用户始终只返回自己的 ACL;管理员默认可查看全部用户的数据,并可通过 `uid` 限定所属用户。可按 ACL
POST
/v1/acls
创建 ACL — 创建一组可供网站引用的 ACL 访问控制规则。接口会校验当前用户可创建的 ACL 数量、同一用户下的名称唯一性、默认动作以及每条匹配规则;规则数量上限由系统配置
PUT
/v1/acls
批量更新 ACL — 在一个事务中批量更新一个或多个 ACL。请求体必须是非空数组,每个元素通过 `id` 指定目标 ACL,并只提交需要修改的字段;普通用户只能更新自己的 ACL,
DELETE
/v1/acls/{acl_id}
删除一个或多个 ACL — 删除一个 ACL,或使用英文逗号分隔的 ID 一次删除多个 ACL。服务端会逐个确认 ID 格式、资源存在性、所属权限、启用状态和关联任务状态;所有目标 ACL
GET
/v1/acls/{acl_id}
获取 ACL 详情 — 根据 ACL ID 获取当前登录用户拥有的一条 ACL 完整配置。服务端同时使用路径中的 `acl_id` 和当前登录用户 ID 查询,因此目标 ACL 不属于
PUT
/v1/acls/{acl_id}
更新单个 ACL — 根据路径中的 ACL ID 局部更新一条 ACL。请求体必须是 JSON 对象,只需提交要修改的字段;服务端会将路径 `acl_id` 作为真实目标 ID,即使
用户 API / 网站与安全 / 访问控制 / 分页查询 ACL 列表

GET分页查询 ACL 列表

GET /v1/acls

分页查询当前身份可见的网站 ACL 规则集。普通用户始终只返回自己的 ACL;管理员默认可查看全部用户的数据,并可通过 `uid` 限定所属用户。可按 ACL ID、名称、启用状态和任务状态筛选,结果按 ACL ID 倒序排列。响应中的 `data` 字段是序列化后的 ACL 规则 JSON 字符串,调用方需要在使用规则内容前再次解析。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,从 1 开始;省略时为 1。`limit=0` 时该参数不影响返回范围。
limitqueryinteger(int32)否每页返回的 ACL 数量,省略时为 10;传 0 表示不分页并返回全部匹配记录。
enablequeryinteger否按启用状态精确筛选:1 表示已启用,0 表示已禁用。
uidqueryinteger(int64)否按 ACL 所属用户 ID 精确筛选,仅管理员身份生效;普通用户传入该参数也只会返回自己的数据。
idqueryinteger(int64)否按 ACL ID 精确筛选列表。
namequerystring否按 ACL 名称进行包含匹配。
statequerystring否按关联任务状态筛选。传 `done` 时同时包含任务已完成和未关联任务的 ACL;其它值按任务状态精确匹配。

响应

HTTP 200

请求始终通过 HTTP 200 返回。成功时给出匹配总数和当前页 ACL 列表;页码或每页数量格式错误、登录态失效时,通过字符串 `code` 和 `msg` 返回业务错误。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,列表查询成功时固定为 0。0
oneOf#1.countinteger(int64)是符合筛选条件的 ACL 总数,不受当前页 `limit` 限制。
oneOf#1.dataarray是当前页的 ACL 记录,按 ACL ID 从大到小排列。
oneOf#1.dataarray<object>否当前页的 ACL 记录,按 ACL ID 从大到小排列。
oneOf#1.data[].idinteger(int64)是ACL 的唯一 ID。
oneOf#1.data[].uidinteger(int64)是ACL 所属用户的 ID。
oneOf#1.data[].namestring是ACL 名称,同一用户下不可重名。
oneOf#1.data[].desstring是ACL 的备注说明,可为空字符串。
oneOf#1.data[].default_actionstring enum是所有 ACL 规则均未匹配时执行的默认动作。reject | allow
oneOf#1.data[].reject_codestring enum是拒绝请求时使用的响应方式:403 表示直接拒绝,302 表示重定向。403 | 302
oneOf#1.data[].redirect_urlstring是`reject_code` 为 302 时使用的重定向地址,否则通常为空字符串。
oneOf#1.data[].datastring是序列化后的 ACL 规则 JSON 数组;每条规则包含动作、匹配条件,并可包含拒绝代码和跳转地址。
oneOf#1.data[].create_atstring是ACL 的数据库创建时间;历史数据未记录时为 null。
oneOf#1.data[].update_atstring是ACL 的数据库最后更新时间;历史数据未记录时为 null。
oneOf#1.data[].enableinteger enum是ACL 启用状态:1 表示启用,0 表示禁用。0 | 1
oneOf#1.data[].task_idinteger(int64)是最近一次 ACL 同步或删除任务的 ID;没有关联任务时为 null。
oneOf#1.data[].versioninteger(int64)是ACL 配置版本号,每次更新时递增。
oneOf#1.data[].statestring是关联任务的当前状态;没有关联任务时为 null。
oneOf#1.data[].create_at2string是格式化为 `YYYY-MM-DD HH:mm:ss` 的创建时间,供界面展示。
oneOf#1.data[].update_at2string是格式化为 `YYYY-MM-DD HH:mm:ss` 的最后更新时间,供界面展示。
oneOf#1.data[].usernamestring是ACL 所属用户的名称。
oneOf#2.codestring是业务错误码,例如 `acl-31` 表示 page 格式错误、`acl-32` 表示 limit 格式错误、`login_required` 表示登录态无效。
oneOf#2.msgstring是与业务错误码对应的中文错误原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/acls'
用户 API / 网站与安全 / 访问控制 / 创建 ACL

POST创建 ACL

POST /v1/acls

创建一组可供网站引用的 ACL 访问控制规则。接口会校验当前用户可创建的 ACL 数量、同一用户下的名称唯一性、默认动作以及每条匹配规则;规则数量上限由系统配置 `acl-max-limit` 决定。普通用户只能为自己创建 ACL;管理员可通过 `uid` 指定所属用户。创建成功后 ACL 会保存为独立配置并返回新 ACL ID。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring是ACL 名称;不能为空,且在所属用户的 ACL 中必须唯一。
desstring否ACL 的备注说明;省略时保存为空字符串。
default_actionstring enum是所有 ACL 规则均未匹配时执行的默认动作:`reject` 拒绝请求,`allow` 放行请求。reject | allow
reject_codestring enum否默认动作拒绝请求时的响应方式;403 表示直接拒绝,302 表示重定向。403 | 302
redirect_urlstring否`reject_code` 为 302 时必填的重定向地址;使用 403 时可省略。
dataarray是按顺序执行的 ACL 规则数组;条目数不得超过系统配置的 `acl-max-limit`。
dataarray<object>否按顺序执行的 ACL 规则数组;条目数不得超过系统配置的 `acl-max-limit`。
data[].acl_actionstring enum是该条规则匹配后执行的动作:`reject` 拒绝请求,`allow` 放行请求。reject | allow
data[].acl_codestring enum否该条规则执行 `reject` 时使用的响应方式;省略时为 403。403 | 302
data[].acl_urlstring否该条规则的 `acl_code` 为 302 时必填的重定向地址。
data[].acl_matcherarray是该条 ACL 规则的匹配条件;每个条件由匹配项、操作符和值组成。
data[].acl_matcherarray<object>否该条 ACL 规则的匹配条件;每个条件由匹配项、操作符和值组成。
data[].acl_matcher[].itemstring enum是要检查的请求或客户端属性,例如 `ip`、`host`、`uri`、国家代码或 TLS 指纹。count404 | uniq_ua | header | ip | host | accept_language | user_agent | referer | uri | req_uri | req_method | country_iso_code | asnumber | province | city | isp | protocol | tls_fp | uniq_tls_fp | server_port
data[].acl_matcher[].opstring enum是匹配操作符;`ip_range` 和 `!ip_range` 用于判断 IP 是否属于指定 CIDR 范围。> | = | != | !contain | contain | prefix | suffix | regex | !regex | exists | !exists | ip_range | !ip_range
data[].acl_matcher[].valuestring否参与匹配的值。服务端会移除空行并转为小写;IP 范围操作符使用空白分隔一个或多个 CIDR。
enableinteger enum否新 ACL 的启用状态:1 表示启用,0 表示禁用;省略时启用。0 | 1
uidinteger(int64)否新 ACL 的所属用户 ID,仅管理员可传;普通用户传入时返回管理员权限错误。

请求体示例

{ "name": "string", "des": "string", "default_action": "string", "reject_code": "string", "redirect_url": "string", "data": [], "enable": 0, "uid": 0 }

响应

HTTP 200

请求始终通过 HTTP 200 返回。创建成功时返回新 ACL ID;配额、名称、默认动作、重定向配置或嵌套匹配规则不合法时,通过字符串 `code` 和 `msg` 返回具体业务错误。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,ACL 创建成功时固定为 0。0
oneOf#1.msgstring enum是ACL 创建成功时返回的确认消息。ACL添加成功
oneOf#1.datainteger(int64)是新创建 ACL 的唯一 ID。
oneOf#2.codestring是业务错误码。常见值包括配额超限 `acl-8`、名称错误 `acl-9/acl-11/acl-12`、默认动作错误 `acl-14/acl-15/acl-16`、规则错误 `acl-17` 至 `acl-25`、缺少规则 `acl-26`、启用状态错误 `acl-27/acl-28`、重定向错误 `acl-35` 至 `acl-40` 以及管理员权限错误 `acl-43`。
oneOf#2.msgstring是与业务错误码对应的中文校验失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": 0 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"string","des":"string","default_action":"string","reject_code":"string","redirect_url":"string","data":[],"enable":0,"uid":0}' \ 'https://master.example.com/v1/acls'
用户 API / 网站与安全 / 访问控制 / 批量更新 ACL

PUT批量更新 ACL

PUT /v1/acls

在一个事务中批量更新一个或多个 ACL。请求体必须是非空数组,每个元素通过 `id` 指定目标 ACL,并只提交需要修改的字段;普通用户只能更新自己的 ACL,管理员可更新其他用户的 ACL。任一元素校验失败都会回滚整批修改。修改已被网站引用且处于启用状态的 ACL 时会创建同步任务;禁用 ACL 时会创建删除任务,但正在被网站引用的 ACL 不允许直接禁用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

要批量更新的 ACL 数组;所有元素在同一个数据库事务中处理。

字段类型必填说明示例
(root)array<object>否要批量更新的 ACL 数组;所有元素在同一个数据库事务中处理。
[].idinteger(int64)是要更新的 ACL ID;目标必须存在且当前身份有权管理。
[].namestring否新的 ACL 名称;不能为空,且在 ACL 所属用户下必须唯一。
[].desstring否新的 ACL 备注说明,可设置为空字符串。
[].default_actionstring enum否所有规则均未匹配时执行的新默认动作:`reject` 拒绝请求,`allow` 放行请求。reject | allow
[].reject_codestring enum否默认拒绝动作使用的新响应方式;403 表示直接拒绝,302 表示重定向。403 | 302
[].redirect_urlstring否新的默认重定向地址;最终 `reject_code` 为 302 时不能为空。
[].dataarray否替换现有配置的完整 ACL 规则数组;条目数不得超过系统配置的 `acl-max-limit`。
[].dataarray<object>否替换现有配置的完整 ACL 规则数组;条目数不得超过系统配置的 `acl-max-limit`。
[].data[].acl_actionstring enum是该条规则匹配后执行的动作:`reject` 拒绝请求,`allow` 放行请求。reject | allow
[].data[].acl_codestring enum否该条规则执行 `reject` 时使用的响应方式;省略时为 403。403 | 302
[].data[].acl_urlstring否该条规则的 `acl_code` 为 302 时必填的重定向地址。
[].data[].acl_matcherarray是该条 ACL 规则的新匹配条件;每个条件由匹配项、操作符和值组成。
[].data[].acl_matcherarray<object>否该条 ACL 规则的新匹配条件;每个条件由匹配项、操作符和值组成。
[].data[].acl_matcher[].itemstring enum是要检查的请求或客户端属性,例如 `ip`、`host`、`uri`、国家代码或 TLS 指纹。count404 | uniq_ua | header | ip | host | accept_language | user_agent | referer | uri | req_uri | req_method | country_iso_code | asnumber | province | city | isp | protocol | tls_fp | uniq_tls_fp | server_port
[].data[].acl_matcher[].opstring enum是匹配操作符;`ip_range` 和 `!ip_range` 用于判断 IP 是否属于指定 CIDR 范围。> | = | != | !contain | contain | prefix | suffix | regex | !regex | exists | !exists | ip_range | !ip_range
[].data[].acl_matcher[].valuestring否参与匹配的值。服务端会移除空行并转为小写;IP 范围操作符使用空白分隔一个或多个 CIDR。
[].enableinteger enum否更新后的启用状态:1 表示启用,0 表示禁用。禁用前 ACL 不能仍被网站引用。0 | 1
[].uidinteger(int64)否仅管理员可传,用于按指定用户执行名称和网站引用校验;该字段不会转移 ACL 的所属用户。

请求体示例

[ { "id": 0, "name": "string", "des": "string", "default_action": "string", "reject_code": "string", "redirect_url": "string", "data": [], "enable": 0, "uid": 0 } ]

响应

HTTP 200

请求始终通过 HTTP 200 返回。整批更新成功时返回确认消息;请求体不是数组、ACL 不存在或无权限、字段或嵌套规则校验失败、ACL 仍被网站引用而尝试禁用时,通过字符串 `code` 和 `msg` 返回业务错误,且本批次修改全部回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,整批 ACL 更新成功时固定为 0。0
oneOf#1.msgstring enum是整批 ACL 更新并提交事务后返回的确认消息。更新ACL成功
oneOf#1.datastring enum是批量更新成功时没有额外业务数据,固定为 null。
oneOf#2.codestring是业务错误码。常见值包括请求体格式错误 `acl-33`、ID 错误或资源不存在 `acl-6/acl-7`、权限错误 `acl-42/acl-43`、名称错误 `acl-9/acl-11`、默认动作错误 `acl-14/acl-15`、规则错误 `acl-17` 至 `acl-25`、启用状态错误 `acl-27/acl-28/acl-29` 以及重定向错误 `acl-35` 至 `acl-40`。
oneOf#2.msgstring是与业务错误码对应的中文校验失败或权限错误原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '[{"id":0,"name":"string","des":"string","default_action":"string","reject_code":"string","redirect_url":"string","data":[],"enable":0,"uid":0}]' \ 'https://master.example.com/v1/acls'
用户 API / 网站与安全 / 访问控制 / 删除一个或多个 ACL

DELETE删除一个或多个 ACL

DELETE /v1/acls/{acl_id}

删除一个 ACL,或使用英文逗号分隔的 ID 一次删除多个 ACL。服务端会逐个确认 ID 格式、资源存在性、所属权限、启用状态和关联任务状态;所有目标 ACL 必须已禁用,并且关联任务为空或状态为 `done`。普通用户只能删除自己的 ACL,管理员可以删除其他用户的 ACL。整批操作共用一个事务,任一 ACL 校验失败都会回滚此前的删除。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
acl_idpathstring是要删除的 ACL ID;批量删除时使用英文逗号连接多个正整数,例如 `1,2,3`。

响应

HTTP 200

请求始终通过 HTTP 200 返回。全部 ACL 删除并提交事务后返回确认消息;任一 ID 格式错误、ACL 不存在、当前身份无权删除、ACL 尚未禁用或关联任务仍在处理时,通过字符串 `code` 和 `msg` 返回业务错误,整批删除会回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,全部目标 ACL 删除成功时固定为 0。0
oneOf#1.msgstring enum是全部目标 ACL 删除并提交事务后返回的确认消息。ACL删除成功
oneOf#1.datastring enum是删除成功时没有额外业务数据,固定为 null。
oneOf#2.codestring enum是业务错误码:`acl-1` 表示 ID 格式错误,`acl-2` 表示 ACL 不存在,`acl-3` 表示 ACL 尚未禁用,`acl-4` 表示关联任务仍在处理,`acl-41` 表示普通用户尝试删除他人 ACL,`login_required` 表示登录态无效。acl-1 | acl-2 | acl-3 | acl-4 | acl-41 | login_required
oneOf#2.msgstring是与业务错误码对应的中文格式、资源状态或权限错误原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/acls/{acl_id}'
用户 API / 网站与安全 / 访问控制 / 获取 ACL 详情

GET获取 ACL 详情

GET /v1/acls/{acl_id}

根据 ACL ID 获取当前登录用户拥有的一条 ACL 完整配置。服务端同时使用路径中的 `acl_id` 和当前登录用户 ID 查询,因此目标 ACL 不属于当前账号时与不存在时返回相同错误;管理员身份也不会绕过这项所属用户限制。返回内容是 ACL 表中的原始配置,不包含列表接口联表提供的任务状态、用户名或格式化时间字段。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
acl_idpathinteger(int64)是要查询的 ACL ID,目标 ACL 必须属于当前登录用户。

响应

HTTP 200

请求通过 HTTP 200 返回。查询成功时返回 ACL 的完整持久化字段;ACL 不存在或不属于当前登录用户时返回业务错误 `acl-30`,登录态无效时返回 `login_required`。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,查询到 ACL 时固定为 0。0
oneOf#1.msgstring enum是详情查询成功时没有额外提示,固定为空字符串。
oneOf#1.dataobject是当前登录用户拥有的 ACL 完整配置。
oneOf#1.data.idinteger(int64)是ACL 的唯一 ID。
oneOf#1.data.uidinteger(int64)是ACL 所属用户的 ID,与当前登录用户 ID 一致。
oneOf#1.data.namestring是ACL 名称,同一用户下不可重名。
oneOf#1.data.desstring是ACL 的备注说明,可为空字符串。
oneOf#1.data.default_actionstring enum是所有 ACL 规则均未匹配时执行的默认动作。reject | allow
oneOf#1.data.reject_codestring enum是默认拒绝动作的响应方式:403 表示直接拒绝,302 表示重定向。403 | 302
oneOf#1.data.redirect_urlstring是`reject_code` 为 302 时使用的重定向地址,否则通常为空字符串。
oneOf#1.data.datastring是序列化后的 ACL 规则 JSON 数组;使用规则前需要再次解析该字符串。
oneOf#1.data.create_atstring是ACL 的数据库创建时间;历史数据未记录时为 null。
oneOf#1.data.update_atstring是ACL 的数据库最后更新时间;历史数据未记录时为 null。
oneOf#1.data.enableinteger enum是ACL 启用状态:1 表示启用,0 表示禁用。0 | 1
oneOf#1.data.task_idinteger(int64)是最近一次 ACL 同步或删除任务的 ID;没有关联任务时为 null。
oneOf#1.data.versioninteger(int64)是ACL 配置版本号,每次更新时递增。
oneOf#2.codestring enum是业务错误码:`acl-30` 表示 ACL 不存在或无权查看,`login_required` 表示登录态无效。acl-30 | login_required
oneOf#2.msgstring是与业务错误码对应的中文错误原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "id": 0, "uid": 0, "name": "string", "des": "string", "default_action": "string", "reject_code": "string", "redirect_url": "string", "data": "string", "create_at": "string", "update_at": "string", "enable": 0, "task_id": 0, "version": 0 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/acls/{acl_id}'
用户 API / 网站与安全 / 访问控制 / 更新单个 ACL

PUT更新单个 ACL

PUT /v1/acls/{acl_id}

根据路径中的 ACL ID 局部更新一条 ACL。请求体必须是 JSON 对象,只需提交要修改的字段;服务端会将路径 `acl_id` 作为真实目标 ID,即使请求体包含 `id` 也会被路径值覆盖。普通用户只能更新自己的 ACL,管理员可更新其他用户的 ACL。修改已被网站引用且处于启用状态的 ACL 时会创建同步任务;禁用 ACL 时会创建删除任务,但仍被网站引用的 ACL 不允许直接禁用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
acl_idpathinteger(int64)是要更新的 ACL ID;目标必须存在且当前身份有权管理。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
idinteger(int64)否兼容字段;如传入会被忽略,实际目标始终由路径中的 `acl_id` 决定。
namestring否新的 ACL 名称;不能为空,且在 ACL 所属用户下必须唯一。
desstring否新的 ACL 备注说明,可设置为空字符串。
default_actionstring enum否所有规则均未匹配时执行的新默认动作:`reject` 拒绝请求,`allow` 放行请求。reject | allow
reject_codestring enum否默认拒绝动作使用的新响应方式;403 表示直接拒绝,302 表示重定向。403 | 302
redirect_urlstring否新的默认重定向地址;最终 `reject_code` 为 302 时不能为空。
dataarray否替换现有配置的完整 ACL 规则数组;条目数不得超过系统配置的 `acl-max-limit`。
dataarray<object>否替换现有配置的完整 ACL 规则数组;条目数不得超过系统配置的 `acl-max-limit`。
data[].acl_actionstring enum是该条规则匹配后执行的动作:`reject` 拒绝请求,`allow` 放行请求。reject | allow
data[].acl_codestring enum否该条规则执行 `reject` 时使用的响应方式;省略时为 403。403 | 302
data[].acl_urlstring否该条规则的 `acl_code` 为 302 时必填的重定向地址。
data[].acl_matcherarray是该条 ACL 规则的新匹配条件;每个条件由匹配项、操作符和值组成。
data[].acl_matcherarray<object>否该条 ACL 规则的新匹配条件;每个条件由匹配项、操作符和值组成。
data[].acl_matcher[].itemstring enum是要检查的请求或客户端属性,例如 `ip`、`host`、`uri`、国家代码或 TLS 指纹。count404 | uniq_ua | header | ip | host | accept_language | user_agent | referer | uri | req_uri | req_method | country_iso_code | asnumber | province | city | isp | protocol | tls_fp | uniq_tls_fp | server_port
data[].acl_matcher[].opstring enum是匹配操作符;`ip_range` 和 `!ip_range` 用于判断 IP 是否属于指定 CIDR 范围。> | = | != | !contain | contain | prefix | suffix | regex | !regex | exists | !exists | ip_range | !ip_range
data[].acl_matcher[].valuestring否参与匹配的值。服务端会移除空行并转为小写;IP 范围操作符使用空白分隔一个或多个 CIDR。
enableinteger enum否更新后的启用状态:1 表示启用,0 表示禁用。禁用前 ACL 不能仍被网站引用。0 | 1
uidinteger(int64)否仅管理员可传,用于按指定用户执行名称和网站引用校验;该字段不会转移 ACL 的所属用户。

请求体示例

{ "id": 0, "name": "string", "des": "string", "default_action": "string", "reject_code": "string", "redirect_url": "string", "data": [], "enable": 0, "uid": 0 }

响应

HTTP 200

请求始终通过 HTTP 200 返回。单条 ACL 更新成功时返回确认消息;请求体不是对象、ACL 不存在或无权限、字段或嵌套规则校验失败、ACL 仍被网站引用而尝试禁用时,通过字符串 `code` 和 `msg` 返回业务错误,当前更新事务会回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,ACL 更新成功时固定为 0。0
oneOf#1.msgstring enum是ACL 更新并提交事务后返回的确认消息。更新ACL成功
oneOf#1.datastring enum是单条更新成功时没有额外业务数据,固定为 null。
oneOf#2.codestring是业务错误码。常见值包括请求体格式错误 `acl-5`、ID 错误或资源不存在 `acl-6/acl-7`、权限错误 `acl-42/acl-43`、名称错误 `acl-9/acl-11`、默认动作错误 `acl-14/acl-15`、规则错误 `acl-17` 至 `acl-25`、启用状态错误 `acl-27/acl-28/acl-29` 以及重定向错误 `acl-35` 至 `acl-40`。
oneOf#2.msgstring是与业务错误码对应的中文校验失败或权限错误原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"id":0,"name":"string","des":"string","default_action":"string","reject_code":"string","redirect_url":"string","data":[],"enable":0,"uid":0}' \ 'https://master.example.com/v1/acls/{acl_id}'
用户 API / 网站与安全 / CC 防护

CC 防护

CC 匹配、过滤和规则管理。

接口列表

GET
/v1/cc-filters
分页查询 CC 过滤器列表 — 分页查询当前身份可见的 CC 过滤器。普通用户始终只返回归属于自己的过滤器;管理员默认可查看全部用户及系统内置过滤器,并可按所属用户筛选。接口支持按过滤器 ID
POST
/v1/cc-filters
创建 CC 过滤器 — 为当前登录用户创建一个 CC 过滤器,创建前会按照当前账号的网站数量和系统配置检查可创建的站点关联对象配额;同一所属用户下过滤器名称不可重复。普通用户只能创建归
PUT
/v1/cc-filters
批量更新 CC 过滤器 — 在一个数据库事务中批量更新一个或多个 CC 过滤器,每个数组元素必须指定过滤器 ID,只修改该元素中明确提供且被服务端支持的字段。普通用户只能更新归属于自己的自
DELETE
/v1/cc-filters/{filter_id}
删除一个或多个 CC 过滤器 — 删除路径中指定的一个或多个 CC 过滤器,多个 ID 使用英文逗号分隔并在同一个数据库事务中处理。普通用户只能删除归属于自己的自定义过滤器,管理员可以删除系统内
GET
/v1/cc-filters/{filter_id}
获取 CC 过滤器详情 — 按 ID 获取一条 CC 过滤器的原始配置记录。系统内置过滤器仅管理员身份可以读取;用户自定义过滤器仅允许其所属用户读取,管理员身份本身不会绕过自定义过滤器的所
PUT
/v1/cc-filters/{filter_id}
更新单个 CC 过滤器 — 按路径 ID 更新一条 CC 过滤器,只修改 JSON 对象中明确提供且被服务端支持的字段;JSON 对象内的 `id` 即使存在也会被路径参数覆盖。普通用户只
GET
/v1/cc-matchs
分页查询 CC 匹配器列表 — 分页查询当前身份可见的 CC 请求匹配器。普通用户始终只返回归属于自己的匹配器;管理员默认可查看全部用户及系统内置匹配器,并可按所属用户筛选。接口支持按匹配器
POST
/v1/cc-matchs
创建 CC 匹配器 — 为当前登录用户创建一个 CC 请求匹配器,创建前会按照当前账号的网站数量和系统配置检查可创建的站点关联对象配额;同一所属用户下匹配器名称不可重复。普通用户只能创
PUT
/v1/cc-matchs
批量更新 CC 匹配器 — 在一个数据库事务中批量更新一个或多个 CC 请求匹配器,每个数组元素必须指定匹配器 ID,只修改该元素中明确提供且被服务端支持的字段。普通用户只能更新归属于自己
DELETE
/v1/cc-matchs/{match_id}
删除一个或多个 CC 匹配器 — 删除路径中指定的一个或多个 CC 请求匹配器,多个 ID 使用英文逗号分隔并在同一个数据库事务中处理。普通用户只能删除归属于自己的自定义匹配器,管理员可以删除系
GET
/v1/cc-matchs/{match_id}
获取 CC 匹配器详情 — 按 ID 获取一条 CC 请求匹配器的原始配置记录。系统内置匹配器仅管理员身份可以读取;用户自定义匹配器仅允许其所属用户读取,管理员身份本身不会绕过自定义匹配器
PUT
/v1/cc-matchs/{match_id}
更新单个 CC 匹配器 — 按路径 ID 更新一条 CC 请求匹配器,只修改 JSON 对象中明确提供且被服务端支持的字段;JSON 对象内的 `id` 即使存在也会被路径参数覆盖。普通用
GET
/v1/cc-rules
分页查询 CC 规则组列表 — 分页查询当前身份可见的 CC 规则组。默认情况下普通用户只返回自己创建的规则组,管理员返回全部规则组或通过 `uid` 限定所属用户;传 `internal_s
POST
/v1/cc-rules
创建 CC 规则组 — 为当前登录用户创建一个 CC 规则组,创建前会按当前账号的网站数量和系统配置检查站点关联对象配额;同一所属用户下规则组名称不可重复。普通用户只能创建归属于自己的
PUT
/v1/cc-rules
批量更新 CC 规则组 — 在一个数据库事务中批量更新一个或多个 CC 规则组。请求体必须是数组,每个元素必须指定规则组 ID;名称、排序、备注、规则步骤、定向可见用户、启用状态和前台显示
DELETE
/v1/cc-rules/{rule_id}
删除一个或多个 CC 规则组 — 删除路径中指定的一个或多个 CC 规则组,多个 ID 使用英文逗号分隔并在同一个数据库事务中处理。普通用户只能删除归属于自己的自定义规则组,管理员可以删除系统内
GET
/v1/cc-rules/{rule_id}
获取 CC 规则组详情 — 按 ID 获取一条 CC 规则组的原始配置记录。系统内置规则组仅管理员身份可以读取;用户自定义规则组仅允许其所属用户读取,管理员身份本身不会绕过自定义规则组的所
PUT
/v1/cc-rules/{rule_id}
更新指定 CC 规则组 — 按路径 ID 更新一条 CC 规则组。请求体必须是 JSON 对象,路径中的 `rule_id` 是唯一目标标识;即使请求体包含 `id`,服务端也会用路径 I
用户 API / 网站与安全 / CC 防护 / 分页查询 CC 过滤器列表

GET分页查询 CC 过滤器列表

GET /v1/cc-filters

分页查询当前身份可见的 CC 过滤器。普通用户始终只返回归属于自己的过滤器;管理员默认可查看全部用户及系统内置过滤器,并可按所属用户筛选。接口支持按过滤器 ID、名称、启用状态和是否为内置过滤器筛选,结果按过滤器 ID 倒序排列;系统保留的 10020 号过滤器始终不会出现在列表中。响应中的 `extra` 是序列化后的过滤器扩展配置 JSON 字符串,需要调用方再次解析。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,从 1 开始;省略时为 1。只能传十进制非负整数字符串,非数字值返回 `cc_filter-33`;`limit=0` 时该参数不影响返回范围。
limitqueryinteger(int32)否每页返回的过滤器数量,省略时为 10;传 0 表示不分页并返回全部匹配记录。非数字值返回 `cc_filter-34`。
uidqueryinteger(int64)否按过滤器所属用户 ID 精确筛选,仅管理员身份生效;普通用户传入该参数时仍只返回自己的过滤器。
internalqueryinteger否按是否为系统内置过滤器精确筛选:1 表示内置,0 表示用户自定义。使用该筛选条件要求管理员身份,普通用户传入时返回 `cc_filter-59`。
enablequeryinteger否按启用状态精确筛选:1 表示已启用,0 表示已禁用。
idqueryinteger(int64)否按 CC 过滤器 ID 精确筛选列表;系统保留的 10020 号过滤器即使匹配也不会返回。
namequerystring否按过滤器名称进行包含匹配。

响应

HTTP 200

请求通过 HTTP 200 返回。成功时给出匹配总数和当前页过滤器列表;页码或每页数量格式错误、普通用户筛选内置过滤器或认证失效时,通过字符串 `code` 和 `msg` 返回业务错误。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,列表查询成功时固定为 0。0
oneOf#1.countinteger(int64)是符合身份范围及筛选条件的过滤器总数,不受当前页 `limit` 限制。
oneOf#1.dataarray是当前页的 CC 过滤器记录,按过滤器 ID 从大到小排列。
oneOf#1.dataarray<object>否当前页的 CC 过滤器记录,按过滤器 ID 从大到小排列。
oneOf#1.data[].idinteger(int64)是CC 过滤器的唯一 ID。
oneOf#1.data[].uidinteger(int64)是过滤器所属用户的 ID;不归属于具体用户的系统内置过滤器可为 null。
oneOf#1.data[].c.uidinteger(int64)是查询结果中因再次选择所属用户列而生成的重复字段,值与 `uid` 相同;系统内置过滤器可为 null。
oneOf#1.data[].namestring是过滤器名称,同一用户下不可重名。
oneOf#1.data[].desstring是过滤器备注,可为空字符串。
oneOf#1.data[].typestring enum是过滤器实现类型,决定触发后采用的限速、验证、跳转或 URL 鉴权行为。easy_click_filter | easy_slide_filter | req_rate | 302_challenge | browser_verify_auto | slide_filter | captcha_filter | click_filter | url_auth | delay_jump_filter | rotate_filter
oneOf#1.data[].within_secondinteger(int32)是请求统计窗口的秒数。
oneOf#1.data[].max_reqinteger(int32)是统计窗口内允许的最大请求数。
oneOf#1.data[].max_req_per_uriinteger(int32)是`req_rate` 类型下同一 URI 在统计窗口内允许的最大请求数;其他类型通常为 0。
oneOf#1.data[].extrastring是序列化后的扩展配置 JSON。`url_auth` 类型包含模式、密钥、签名参数名、时间容差及签名可用次数;其他类型通常为 `{}`。
oneOf#1.data[].create_atstring是数据库返回的过滤器创建时间;历史记录未保存时间时为 null。
oneOf#1.data[].update_atstring是数据库返回的过滤器最后更新时间;历史记录未保存时间时为 null。
oneOf#1.data[].internalinteger enum是是否为系统内置过滤器:1 表示内置,0 表示用户自定义。0 | 1
oneOf#1.data[].enableinteger enum是过滤器启用状态:1 表示启用,0 表示禁用。0 | 1
oneOf#1.data[].task_idinteger(int64)是最近一次过滤器同步或删除任务的 ID;没有关联任务时为 null。
oneOf#1.data[].versioninteger(int64)是过滤器配置版本号,修改过滤器时递增。
oneOf#1.data[].statestring是关联任务的当前状态;过滤器没有关联任务时为 null。
oneOf#1.data[].create_at2string是格式化为 `YYYY-MM-DD HH:mm:ss` 的创建时间;原始创建时间为 null 时也为 null。
oneOf#1.data[].update_at2string是格式化为 `YYYY-MM-DD HH:mm:ss` 的最后更新时间;原始更新时间为 null 时也为 null。
oneOf#1.data[].usernamestring是过滤器所属用户的名称;不归属于具体用户的系统内置过滤器为 null。
oneOf#2.codestring enum是业务错误码:`cc_filter-33` 表示 page 不是数字,`cc_filter-34` 表示 limit 不是数字,`cc_filter-59` 表示当前身份无权筛选内置过滤器,`login_required` 表示认证无效。cc_filter-33 | cc_filter-34 | cc_filter-59 | login_required
oneOf#2.msgstring是与业务错误码对应的中文参数、权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/cc-filters'
用户 API / 网站与安全 / CC 防护 / 创建 CC 过滤器

POST创建 CC 过滤器

POST /v1/cc-filters

为当前登录用户创建一个 CC 过滤器,创建前会按照当前账号的网站数量和系统配置检查可创建的站点关联对象配额;同一所属用户下过滤器名称不可重复。普通用户只能创建归属于自己的自定义过滤器,管理员可通过请求体指定所属用户或创建系统内置过滤器。`req_rate` 类型必须配置单 URI 请求上限,`url_auth` 类型必须配置 URL 鉴权参数;其他类型的扩展配置会以空对象保存。新增过滤器固定以启用状态和版本 1 写入。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
internalqueryinteger否兼容性权限检查参数。传 1 时要求管理员身份,否则返回 `cc_filter-55`;该查询参数本身不会把新过滤器标记为内置,创建内置过滤器应同时在 JSON 请求体中传 `internal: 1`。

请求体

请求体必填。

Content-Type:application/json

创建 CC 过滤器的 JSON 对象;未识别字段不会参与创建逻辑。

字段类型必填说明示例
oneOf#1.typestring enum否请求频率限制类型,要求同时提供单 URI 请求上限。req_rate
oneOf#2.typestring enum否URL 鉴权类型,要求同时提供符合所选模式的扩展配置。url_auth
oneOf#2.extraoneOf是根据 `mode` 选择 TypeA 或 TypeB 的 URL 鉴权配置。
oneOf#2.extra(oneOf#1).modestring enum是URL 鉴权模式;TypeA 从独立的时间戳查询参数读取签名时间。TypeA
oneOf#2.extra(oneOf#1).keystring是计算 URL 签名使用的密钥,长度必须为 16 至 32 个字符。
oneOf#2.extra(oneOf#1).sign_namestring是请求 URL 中承载签名值的查询参数名,不能为空。
oneOf#2.extra(oneOf#1).time_namestring是TypeA 模式下承载签名时间戳的查询参数名,不能为空。
oneOf#2.extra(oneOf#1).time_diffoneOf是签名时间与服务端时间允许的最大秒数差,必须为不超过 3600 的非负整数。
oneOf#2.extra(oneOf#1).time_diff(oneOf#1)integer否
oneOf#2.extra(oneOf#1).time_diff(oneOf#2)string否
oneOf#2.extra(oneOf#1).sign_use_timesoneOf是同一签名允许使用的次数,必须为非负整数或仅含十进制数字的字符串。
oneOf#2.extra(oneOf#1).sign_use_times(oneOf#1)integer否
oneOf#2.extra(oneOf#1).sign_use_times(oneOf#2)string否
oneOf#2.extra(oneOf#2).modestring enum是URL 鉴权模式;TypeB 不要求独立的时间戳参数名。TypeB
oneOf#2.extra(oneOf#2).keystring是计算 URL 签名使用的密钥,长度必须为 16 至 32 个字符。
oneOf#2.extra(oneOf#2).sign_namestring是请求 URL 中承载签名值的查询参数名,不能为空。
oneOf#2.extra(oneOf#2).time_diffoneOf是签名时间与服务端时间允许的最大秒数差,必须为不超过 3600 的非负整数。
oneOf#2.extra(oneOf#2).time_diff(oneOf#1)integer否
oneOf#2.extra(oneOf#2).time_diff(oneOf#2)string否
oneOf#2.extra(oneOf#2).sign_use_timesoneOf是同一签名允许使用的次数,必须为非负整数或仅含十进制数字的字符串。
oneOf#2.extra(oneOf#2).sign_use_times(oneOf#1)integer否
oneOf#2.extra(oneOf#2).sign_use_times(oneOf#2)string否
oneOf#3.typestring enum否无需额外条件字段的验证、跳转或轮转过滤器类型。easy_click_filter | easy_slide_filter | 302_challenge | browser_verify_auto | slide_filter | captcha_filter | click_filter | delay_jump_filter | rotate_filter

请求体示例

{ "type": "string" }

响应

HTTP 200

业务结果通过 HTTP 200 返回。创建成功时返回新过滤器 ID;配额不足、名称或阈值不合法、类型条件字段缺失、URL 鉴权配置错误、管理员专属字段越权、系统维护或认证失效时返回字符串业务错误码,数据库事务会回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,过滤器创建并提交事务后固定为 0。0
oneOf#1.msgstring enum是过滤器记录创建成功后返回的确认消息。过滤器添加成功
oneOf#1.datainteger(int64)是数据库为新 CC 过滤器生成的唯一 ID。
oneOf#2.codestring enum是业务错误码:10 表示创建数量超过站点关联对象配额;11、13、14 表示名称为空、重复或缺失;16 至 18 表示类型为空、无效或缺失;19 至 27 表示统计窗口、总请求上限或单 URI 上限为空、格式错误或缺失;28、29 表示 enable 为空或超出 0/1;36 至 50 表示 URL 鉴权扩展配置缺失或无效,其中 49 表示 internal 超出 0/1;55 至 57 表示普通用户使用管理员专属参数;`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cc_filter-10 | cc_filter-11 | cc_filter-13 | cc_filter-14 | cc_filter-16 | cc_filter-17 | cc_filter-18 | cc_filter-19 | cc_filter-20 | cc_filter-21 | cc_filter-22 | cc_filter-23 | cc_filter-24 | cc_filter-25 | cc_filter-26 | cc_filter-27 | cc_filter-28 | cc_filter-29 | cc_filter-36 | cc_filter-37 | cc_filter-38 | cc_filter-39 | cc_filter-40 | cc_filter-41 | cc_filter-42 | cc_filter-43 | cc_filter-44 | cc_filter-45 | cc_filter-46 | cc_filter-47 | cc_filter-48 | cc_filter-49 | cc_filter-50 | cc_filter-55 | cc_filter-56 | cc_filter-57 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文配额、字段校验、URL 鉴权、权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": 0 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"type":"string"}' \ 'https://master.example.com/v1/cc-filters'
用户 API / 网站与安全 / CC 防护 / 批量更新 CC 过滤器

PUT批量更新 CC 过滤器

PUT /v1/cc-filters

在一个数据库事务中批量更新一个或多个 CC 过滤器,每个数组元素必须指定过滤器 ID,只修改该元素中明确提供且被服务端支持的字段。普通用户只能更新归属于自己的自定义过滤器,管理员可更新其他用户或系统内置过滤器。任一元素不存在、越权或校验失败时整个批次都会回滚;成功时所有目标过滤器的版本号均递增并刷新更新时间,即使某个元素除 ID 外没有其他字段。修改正在使用的关键配置或系统内置过滤器时会创建节点同步任务;禁用过滤器时如仍被 CC 规则引用则拒绝,否则创建节点删除任务。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

待批量更新的 CC 过滤器对象数组;空数组不会修改记录,非数组请求返回 `cc_filter-35`。

字段类型必填说明示例
(root)array<object>否待批量更新的 CC 过滤器对象数组;空数组不会修改记录,非数组请求返回 `cc_filter-35`。
[].idoneOf是要更新的 CC 过滤器 ID;接受正整数或仅含十进制数字的字符串,记录必须存在且当前身份必须有权更新。
[].id(oneOf#1)integer否
[].id(oneOf#2)string否
[].namestring否新的过滤器名称;服务端会过滤可执行的 HTML 内容,处理后不得为空,并且在校验所属用户下不可与其他过滤器重名。
[].desstring否新的过滤器备注;服务端会过滤可执行的 HTML 内容,可传空字符串清空备注。
[].typestring enum否新的过滤器实现类型;省略时沿用当前类型。更改该字段属于关键配置变更,过滤器正在使用或属于系统内置时会触发节点同步任务。easy_click_filter | easy_slide_filter | req_rate | 302_challenge | browser_verify_auto | slide_filter | captcha_filter | click_filter | url_auth | delay_jump_filter | rotate_filter
[].within_secondoneOf否新的请求统计窗口秒数;接受非负整数或仅含十进制数字的字符串,省略时保持原值。
[].within_second(oneOf#1)integer否
[].within_second(oneOf#2)string否
[].max_reqoneOf否新的统计窗口总请求上限;接受非负整数或仅含十进制数字的字符串,省略时保持原值。
[].max_req(oneOf#1)integer否
[].max_req(oneOf#2)string否
[].max_req_per_urioneOf否新的单 URI 请求上限。仅目标更新后的类型为 `req_rate` 时校验并写入,必须为非负整数或十进制数字字符串;其他类型会忽略该字段。
[].max_req_per_uri(oneOf#1)integer否
[].max_req_per_uri(oneOf#2)string否
[].extraobject否新的扩展配置。仅目标更新后的类型为 `url_auth` 时校验并序列化写入,要求 `mode`、`key`、`sign_name`、`time_diff`、`sign_use_times`,TypeA 还要求 `time_name`;其他类型会忽略该字段,附加键会随对象保存。
[].extra.modestring enum否URL 鉴权模式;TypeA 还要求 `time_name`,TypeB 不要求独立的时间戳参数名。TypeA | TypeB
[].extra.keystring否计算 URL 签名使用的密钥,长度必须为 16 至 32 个字符。
[].extra.sign_namestring否请求 URL 中承载签名值的查询参数名,不能为空。
[].extra.time_namestring否TypeA 模式下承载签名时间戳的查询参数名;TypeA 必填且不能为空。
[].extra.time_diffoneOf否签名时间与服务端时间允许的最大秒数差,必须为不超过 3600 的非负整数。
[].extra.time_diff(oneOf#1)integer否
[].extra.time_diff(oneOf#2)string否
[].extra.sign_use_timesoneOf否同一签名允许使用的次数,必须为非负整数或仅含十进制数字的字符串。
[].extra.sign_use_times(oneOf#1)integer否
[].extra.sign_use_times(oneOf#2)string否
[].enableinteger enum否新的启用状态:1 表示启用,0 表示禁用。禁用前会检查所有当前用户及系统 CC 规则,仍被引用时返回 `cc_filter-30`。0 | 1
[].uidinteger(int64)否兼容性管理员字段,用作本次名称唯一性和 CC 规则引用检查的用户上下文;仅管理员可传。该字段不会修改过滤器数据库中的所属用户,不能用于转移过滤器。
[].internalinteger enum否兼容性处理标记,1 要求管理员身份并会按内置过滤器流程决定同步任务。该字段不会改写数据库中已有的内置状态,不能用于把普通过滤器转换为内置过滤器或反向转换。0 | 1

请求体示例

[ { "id": null, "name": "string", "des": "string", "type": "string", "within_second": null, "max_req": null, "max_req_per_uri": null, "extra": { "mode": "string", "key": "YOUR_KEY", "sign_name": "string", "time_name": "string", "time_diff": null, "sign_use_times": null }, "enable": 0, "uid": 0, "internal": 0 } ]

响应

HTTP 200

业务结果通过 HTTP 200 返回。全部元素更新并提交后返回确认消息;请求体格式、过滤器 ID、访问权限、更新字段、URL 鉴权配置或禁用前引用检查失败,以及系统维护或认证失效时返回字符串业务错误码,整个批次事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,整个批次更新并提交后固定为 0。0
oneOf#1.msgstring enum是所有过滤器更新成功后返回的确认消息。更新过滤器成功
oneOf#1.datastring enum是批量更新成功时没有额外业务数据,固定为 null。
oneOf#2.codestring enum是业务错误码:7、8 表示过滤器 ID 格式错误或记录不存在;11、13 表示名称为空或重复;16、17 表示类型为空或无效;19、20、22、23、25、26 表示统计窗口或请求上限为空、格式错误;28 至 30 表示启用状态无效或过滤器仍被 CC 规则引用;35 表示请求体不是数组;37 至 50 表示 URL 鉴权配置或 internal 标记无效;53、54 表示普通用户尝试更新内置或其他用户的过滤器;56、57 表示普通用户使用管理员专属字段;`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cc_filter-7 | cc_filter-8 | cc_filter-11 | cc_filter-13 | cc_filter-16 | cc_filter-17 | cc_filter-19 | cc_filter-20 | cc_filter-22 | cc_filter-23 | cc_filter-25 | cc_filter-26 | cc_filter-28 | cc_filter-29 | cc_filter-30 | cc_filter-35 | cc_filter-37 | cc_filter-38 | cc_filter-39 | cc_filter-40 | cc_filter-41 | cc_filter-42 | cc_filter-43 | cc_filter-44 | cc_filter-45 | cc_filter-46 | cc_filter-47 | cc_filter-48 | cc_filter-49 | cc_filter-50 | cc_filter-53 | cc_filter-54 | cc_filter-56 | cc_filter-57 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文请求格式、记录、字段校验、引用冲突、权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '[{"id":null,"name":"string","des":"string","type":"string","within_second":null,"max_req":null,"max_req_per_uri":null,"extra":{"mode":"string","key":"YOUR_KEY","sign_name":"string","time_name":"string","time_diff":null,"sign_use_times":null},"enable":0,"uid":0,"internal":0}]' \ 'https://master.example.com/v1/cc-filters'
用户 API / 网站与安全 / CC 防护 / 删除一个或多个 CC 过滤器

DELETE删除一个或多个 CC 过滤器

DELETE /v1/cc-filters/{filter_id}

删除路径中指定的一个或多个 CC 过滤器,多个 ID 使用英文逗号分隔并在同一个数据库事务中处理。普通用户只能删除归属于自己的自定义过滤器,管理员可以删除系统内置过滤器及其他用户的过滤器。每个目标必须已经禁用;如果仍有关联的同步或删除任务,该任务状态必须为 `done`。任一 ID 格式错误、记录不存在、越权、仍启用或任务未完成时,整个批次回滚,不会保留部分删除结果。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
filter_idpathstring是要删除的 CC 过滤器 ID;删除多个过滤器时按 `10021,10022` 形式使用英文逗号连接,每一段都必须是十进制数字。

响应

HTTP 200

业务结果通过 HTTP 200 返回。全部目标通过检查、删除并提交后返回确认消息;ID 格式、记录存在性、权限、启用状态或关联任务状态不符合要求,以及系统维护或认证失效时返回字符串业务错误码,整个批次事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,所有目标过滤器删除并提交后固定为 0。0
oneOf#1.msgstring enum是整个删除批次成功提交后返回的确认消息。过滤器删除成功
oneOf#1.datastring enum是删除成功时没有额外业务数据,固定为 null。
oneOf#2.codestring enum是业务错误码:`cc_filter-1` 表示某段 ID 不是数字,`cc_filter-2` 表示过滤器不存在,`cc_filter-4` 表示过滤器仍处于启用状态,`cc_filter-5` 表示关联任务尚未完成,`cc_filter-51` 表示非管理员删除内置过滤器,`cc_filter-52` 表示普通用户删除其他用户的过滤器,`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cc_filter-1 | cc_filter-2 | cc_filter-4 | cc_filter-5 | cc_filter-51 | cc_filter-52 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文 ID、记录、状态、权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/cc-filters/{filter_id}'
用户 API / 网站与安全 / CC 防护 / 获取 CC 过滤器详情

GET获取 CC 过滤器详情

GET /v1/cc-filters/{filter_id}

按 ID 获取一条 CC 过滤器的原始配置记录。系统内置过滤器仅管理员身份可以读取;用户自定义过滤器仅允许其所属用户读取,管理员身份本身不会绕过自定义过滤器的所有者校验。返回的是 `cc_filter` 记录本身,不包含列表接口联表得到的任务状态、用户名或格式化时间字段;`extra` 为序列化后的扩展配置 JSON 字符串,使用前需要再次解析。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
filter_idpathinteger(int64)是要查询的 CC 过滤器 ID;路由只接受十进制整数。

响应

HTTP 200

业务结果通过 HTTP 200 返回。过滤器存在且当前身份有读取权限时返回完整原始配置;记录不存在、读取内置过滤器时不是管理员、读取其他用户的自定义过滤器或认证失效时返回字符串业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,过滤器详情读取成功时固定为 0。0
oneOf#1.msgstring enum是详情读取成功时没有附加提示,固定为空字符串。
oneOf#1.dataobject是数据库中的 CC 过滤器原始配置记录。
oneOf#1.data.idinteger(int64)是CC 过滤器的唯一 ID。
oneOf#1.data.uidinteger(int64)是过滤器所属用户的 ID;系统内置过滤器不归属于具体用户时为 null。
oneOf#1.data.namestring是过滤器名称,同一所属用户下不可重名。
oneOf#1.data.desstring是过滤器备注,可为空字符串。
oneOf#1.data.typestring enum是过滤器实现类型,决定达到请求阈值后采用的防护行为。easy_click_filter | easy_slide_filter | req_rate | 302_challenge | browser_verify_auto | slide_filter | captcha_filter | click_filter | url_auth | delay_jump_filter | rotate_filter
oneOf#1.data.within_secondinteger(int32)是请求统计窗口的秒数。
oneOf#1.data.max_reqinteger(int32)是统计窗口内允许的最大请求数。
oneOf#1.data.max_req_per_uriinteger(int32)是`req_rate` 类型下同一 URI 在统计窗口内允许的最大请求数;其他类型通常为 0。
oneOf#1.data.extrastring是序列化后的扩展配置 JSON。`url_auth` 类型包含 URL 鉴权模式及签名参数,其他类型通常为 `{}`。
oneOf#1.data.create_atstring是数据库返回的过滤器创建时间;历史记录未保存时间时为 null。
oneOf#1.data.update_atstring是数据库返回的过滤器最后更新时间;历史记录未保存时间时为 null。
oneOf#1.data.internalinteger enum是是否为系统内置过滤器:1 表示内置,0 表示用户自定义。0 | 1
oneOf#1.data.enableinteger enum是过滤器启用状态:1 表示启用,0 表示禁用。0 | 1
oneOf#1.data.task_idinteger(int64)是最近一次过滤器同步或删除任务的 ID;没有关联任务时为 null。
oneOf#1.data.versioninteger(int64)是过滤器配置版本号,每次更新时递增。
oneOf#2.codestring enum是业务错误码:`cc_filter-31` 表示过滤器不存在,`cc_filter-32` 表示当前用户不是自定义过滤器的所有者,`cc_filter-58` 表示非管理员尝试读取系统内置过滤器,`login_required` 表示认证无效。cc_filter-31 | cc_filter-32 | cc_filter-58 | login_required
oneOf#2.msgstring是与业务错误码对应的中文记录不存在、所有权、管理员权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "id": 0, "uid": 0, "name": "string", "des": "string", "type": "string", "within_second": 0, "max_req": 0, "max_req_per_uri": 0, "extra": "string", "create_at": "string", "update_at": "string", "internal": 0, "enable": 0, "task_id": 0, "version": 0 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/cc-filters/{filter_id}'
用户 API / 网站与安全 / CC 防护 / 更新单个 CC 过滤器

PUT更新单个 CC 过滤器

PUT /v1/cc-filters/{filter_id}

按路径 ID 更新一条 CC 过滤器,只修改 JSON 对象中明确提供且被服务端支持的字段;JSON 对象内的 `id` 即使存在也会被路径参数覆盖。普通用户只能更新归属于自己的自定义过滤器,管理员可更新其他用户或系统内置过滤器。成功更新时配置版本号必定递增并刷新更新时间,即使请求体为空对象。修改正在使用的关键配置或系统内置过滤器时会创建节点同步任务;禁用过滤器时如仍被 CC 规则引用则拒绝,否则创建节点删除任务。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
filter_idpathinteger(int64)是要更新的 CC 过滤器 ID;路由只接受十进制整数,记录必须存在且当前身份必须有权更新。

请求体

请求体必填。

Content-Type:application/json

单个过滤器的更新对象;可以为空对象,此时只递增版本并刷新更新时间。请求体必须是 JSON 对象,数组、标量或空 JSON 返回 `cc_filter-6`;未识别字段不写入记录,`id` 字段由路径参数覆盖。

字段类型必填说明示例
namestring否新的过滤器名称;服务端会过滤可执行的 HTML 内容,处理后不得为空,并且在校验所属用户下不可与其他过滤器重名。
desstring否新的过滤器备注;服务端会过滤可执行的 HTML 内容,可传空字符串清空备注。
typestring enum否新的过滤器实现类型;省略时沿用当前类型。更改该字段属于关键配置变更,过滤器正在使用或属于系统内置时会触发节点同步任务。easy_click_filter | easy_slide_filter | req_rate | 302_challenge | browser_verify_auto | slide_filter | captcha_filter | click_filter | url_auth | delay_jump_filter | rotate_filter
within_secondoneOf否新的请求统计窗口秒数;接受非负整数或仅含十进制数字的字符串,省略时保持原值。
within_second(oneOf#1)integer否
within_second(oneOf#2)string否
max_reqoneOf否新的统计窗口总请求上限;接受非负整数或仅含十进制数字的字符串,省略时保持原值。
max_req(oneOf#1)integer否
max_req(oneOf#2)string否
max_req_per_urioneOf否新的单 URI 请求上限。仅目标更新后的类型为 `req_rate` 时校验并写入,必须为非负整数或十进制数字字符串;其他类型会忽略该字段。
max_req_per_uri(oneOf#1)integer否
max_req_per_uri(oneOf#2)string否
extraobject否新的扩展配置。仅目标更新后的类型为 `url_auth` 时校验并序列化写入,要求 `mode`、`key`、`sign_name`、`time_diff`、`sign_use_times`,TypeA 还要求 `time_name`;其他类型会忽略该字段,附加键会随对象保存。
extra.modestring enum否URL 鉴权模式;TypeA 还要求 `time_name`,TypeB 不要求独立的时间戳参数名。TypeA | TypeB
extra.keystring否计算 URL 签名使用的密钥,长度必须为 16 至 32 个字符。
extra.sign_namestring否请求 URL 中承载签名值的查询参数名,不能为空。
extra.time_namestring否TypeA 模式下承载签名时间戳的查询参数名;TypeA 必填且不能为空。
extra.time_diffoneOf否签名时间与服务端时间允许的最大秒数差,必须为不超过 3600 的非负整数。
extra.time_diff(oneOf#1)integer否
extra.time_diff(oneOf#2)string否
extra.sign_use_timesoneOf否同一签名允许使用的次数,必须为非负整数或仅含十进制数字的字符串。
extra.sign_use_times(oneOf#1)integer否
extra.sign_use_times(oneOf#2)string否
enableinteger enum否新的启用状态:1 表示启用,0 表示禁用。禁用前会检查所有当前用户及系统 CC 规则,仍被引用时返回 `cc_filter-30`。0 | 1
uidinteger(int64)否兼容性管理员字段,用作本次名称唯一性和 CC 规则引用检查的用户上下文;仅管理员可传。该字段不会修改过滤器数据库中的所属用户,不能用于转移过滤器。
internalinteger enum否兼容性处理标记,1 要求管理员身份并会按内置过滤器流程决定同步任务。该字段不会改写数据库中已有的内置状态,不能用于转换过滤器归类。0 | 1

请求体示例

{ "name": "string", "des": "string", "type": "string", "within_second": null, "max_req": null, "max_req_per_uri": null, "extra": { "mode": "string", "key": "YOUR_KEY", "sign_name": "string", "time_name": "string", "time_diff": null, "sign_use_times": null }, "enable": 0, "uid": 0, "internal": 0 }

响应

HTTP 200

业务结果通过 HTTP 200 返回。目标过滤器更新并提交后返回确认消息;请求体不是对象、过滤器不存在、访问权限不足、更新字段或 URL 鉴权配置无效、禁用时仍被引用,以及系统维护或认证失效时返回字符串业务错误码,更新事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,过滤器更新并提交后固定为 0。0
oneOf#1.msgstring enum是目标过滤器更新成功后返回的确认消息。更新过滤器成功
oneOf#1.datastring enum是单个过滤器更新成功时没有额外业务数据,固定为 null。
oneOf#2.codestring enum是业务错误码:6 表示请求体不是 JSON 对象,8 表示过滤器不存在;11、13 表示名称为空或重复;16、17 表示类型为空或无效;19、20、22、23、25、26 表示统计窗口或请求上限为空、格式错误;28 至 30 表示启用状态无效或过滤器仍被 CC 规则引用;37 至 50 表示 URL 鉴权配置或 internal 标记无效;53、54 表示普通用户尝试更新内置或其他用户的过滤器;56、57 表示普通用户使用管理员专属字段;`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cc_filter-6 | cc_filter-8 | cc_filter-11 | cc_filter-13 | cc_filter-16 | cc_filter-17 | cc_filter-19 | cc_filter-20 | cc_filter-22 | cc_filter-23 | cc_filter-25 | cc_filter-26 | cc_filter-28 | cc_filter-29 | cc_filter-30 | cc_filter-37 | cc_filter-38 | cc_filter-39 | cc_filter-40 | cc_filter-41 | cc_filter-42 | cc_filter-43 | cc_filter-44 | cc_filter-45 | cc_filter-46 | cc_filter-47 | cc_filter-48 | cc_filter-49 | cc_filter-50 | cc_filter-53 | cc_filter-54 | cc_filter-56 | cc_filter-57 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文请求格式、记录、字段校验、引用冲突、权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"string","des":"string","type":"string","within_second":null,"max_req":null,"max_req_per_uri":null,"extra":{"mode":"string","key":"YOUR_KEY","sign_name":"string","time_name":"string","time_diff":null,"sign_use_times":null},"enable":0,"uid":0,"internal":0}' \ 'https://master.example.com/v1/cc-filters/{filter_id}'
用户 API / 网站与安全 / CC 防护 / 分页查询 CC 匹配器列表

GET分页查询 CC 匹配器列表

GET /v1/cc-matchs

分页查询当前身份可见的 CC 请求匹配器。普通用户始终只返回归属于自己的匹配器;管理员默认可查看全部用户及系统内置匹配器,并可按所属用户筛选。接口支持按匹配器 ID、名称、启用状态和是否为内置匹配器筛选,结果按匹配器 ID 倒序排列;系统保留的 10020 号记录始终不会出现在列表中。响应中的 `data` 是序列化 JSON 字符串:`{}` 表示匹配全部请求,其他记录通常是由匹配项、操作符和值组成的条件数组。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,从 1 开始;省略时为 1。只能传十进制非负整数字符串,非数字值返回 `cc_match-28`;`limit=0` 时该参数不影响返回范围。
limitqueryinteger(int32)否每页返回的匹配器数量,省略时为 10;传 0 表示不分页并返回全部匹配记录。非数字值返回 `cc_match-29`。
uidqueryinteger(int64)否按匹配器所属用户 ID 精确筛选,仅管理员身份生效;普通用户传入该参数时仍只返回自己的匹配器。
internalqueryinteger否按是否为系统内置匹配器精确筛选:1 表示内置,0 表示用户自定义。使用该筛选条件要求管理员身份,普通用户传入时返回 `cc_match-42`。
enablequeryinteger否按启用状态精确筛选:1 表示已启用,0 表示已禁用。
idqueryinteger(int64)否按 CC 匹配器 ID 精确筛选列表;系统保留的 10020 号记录即使匹配也不会返回。
namequerystring否按匹配器名称进行包含匹配。

响应

HTTP 200

请求通过 HTTP 200 返回。成功时给出符合身份范围及筛选条件的总数和当前页匹配器列表;页码或每页数量格式错误、普通用户筛选内置匹配器或认证失效时,通过字符串 `code` 和 `msg` 返回业务错误。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,列表查询成功时固定为 0。0
oneOf#1.countinteger(int64)是符合身份范围及筛选条件的匹配器总数,不受当前页 `limit` 限制。
oneOf#1.dataarray是当前页的 CC 匹配器记录,按匹配器 ID 从大到小排列。
oneOf#1.dataarray<object>否当前页的 CC 匹配器记录,按匹配器 ID 从大到小排列。
oneOf#1.data[].idinteger(int64)是CC 匹配器的唯一 ID。
oneOf#1.data[].uidinteger(int64)是匹配器所属用户的 ID;不归属于具体用户的系统内置匹配器可为 null。
oneOf#1.data[].c.uidinteger(int64)是查询结果中因再次选择所属用户列而生成的重复字段,值与 `uid` 相同;系统内置匹配器可为 null。
oneOf#1.data[].namestring是匹配器名称,同一用户下不可重名。
oneOf#1.data[].desstring是匹配器备注,可为空字符串。
oneOf#1.data[].datastring是序列化后的匹配规则 JSON。`{}` 表示匹配全部请求;条件数组中的每项包含 `item`、`op` 和规范化后的 `value`。
oneOf#1.data[].create_atstring是数据库返回的匹配器创建时间;历史记录未保存时间时为 null。
oneOf#1.data[].update_atstring是数据库返回的匹配器最后更新时间;历史记录未保存时间时为 null。
oneOf#1.data[].internalinteger enum是是否为系统内置匹配器:1 表示内置,0 表示用户自定义。0 | 1
oneOf#1.data[].enableinteger enum是匹配器启用状态:1 表示启用,0 表示禁用。0 | 1
oneOf#1.data[].task_idinteger(int64)是最近一次匹配器同步或删除任务的 ID;没有关联任务时为 null。
oneOf#1.data[].versioninteger(int64)是匹配器配置版本号,每次更新时递增。
oneOf#1.data[].statestring是关联任务的当前状态;匹配器没有关联任务时为 null。
oneOf#1.data[].create_at2string是格式化为 `YYYY-MM-DD HH:mm:ss` 的创建时间;原始创建时间为 null 时也为 null。
oneOf#1.data[].update_at2string是格式化为 `YYYY-MM-DD HH:mm:ss` 的最后更新时间;原始更新时间为 null 时也为 null。
oneOf#1.data[].usernamestring是匹配器所属用户的名称;不归属于具体用户的系统内置匹配器为 null。
oneOf#2.codestring enum是业务错误码:`cc_match-28` 表示 page 不是数字,`cc_match-29` 表示 limit 不是数字,`cc_match-42` 表示当前身份无权筛选内置匹配器,`login_required` 表示认证无效。cc_match-28 | cc_match-29 | cc_match-42 | login_required
oneOf#2.msgstring是与业务错误码对应的中文参数、权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/cc-matchs'
用户 API / 网站与安全 / CC 防护 / 创建 CC 匹配器

POST创建 CC 匹配器

POST /v1/cc-matchs

为当前登录用户创建一个 CC 请求匹配器,创建前会按照当前账号的网站数量和系统配置检查可创建的站点关联对象配额;同一所属用户下匹配器名称不可重复。普通用户只能创建归属于自己的自定义匹配器,管理员可通过 JSON 对象指定所属用户或创建系统内置匹配器。省略 `data` 时保存 `{}`,表示匹配全部请求;提供 `data` 时必须是条件数组,服务端会去除值中的空行和首尾空白并转换为小写。新增匹配器固定以启用状态和版本 1 写入。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
internalqueryinteger否兼容性权限检查参数,只接受 0 或 1。传 1 时要求管理员身份,否则返回 `cc_match-38`;该查询参数本身不会把新匹配器标记为内置,创建内置匹配器应在 JSON 对象中传 `internal: 1`。

请求体

请求体必填。

Content-Type:application/json

创建 CC 匹配器的 JSON 对象;未识别的顶层字段不会参与创建逻辑。

字段类型必填说明示例
namestring是匹配器名称;服务端会过滤可执行的 HTML 内容,且要求处理后的名称非空、在所属用户下唯一。
desstring否匹配器备注;服务端会过滤可执行的 HTML 内容,省略时保存为空字符串。
dataarray否请求匹配条件数组。省略整个字段时保存 `{}` 并匹配全部请求;提供时可为空数组,每项按 `item`、`op` 和 `value` 进行校验及规范化。
dataarray<object>否请求匹配条件数组。省略整个字段时保存 `{}` 并匹配全部请求;提供时可为空数组,每项按 `item`、`op` 和 `value` 进行校验及规范化。
data[].itemstring enum是匹配项:支持 404 次数、唯一 UA、自定义请求头、客户端 IP、主机名、带参数或不带参数的 URI、请求方法、User-Agent、Referer、国家代码、ASN、省市、运营商、协议、Accept-Language、TLS 指纹、唯一 TLS 指纹和访问端口。count404 | uniq_ua | header | ip | host | req_uri | req_method | uri | user_agent | referer | country_iso_code | asnumber | province | city | isp | protocol | accept_language | tls_fp | uniq_tls_fp | server_port
data[].opstring enum是匹配操作符,依次支持大于、等于、不等于、不包含、包含、前缀、后缀、正则匹配、正则不匹配、存在、不存在、位于 IP 网段和不位于 IP 网段。> | = | != | !contain | contain | prefix | suffix | regex | !regex | exists | !exists | ip_range | !ip_range
data[].valuestring否匹配值,省略时补为空字符串。服务端会去除首尾空白和空行并转为小写;`ip_range` 与 `!ip_range` 可用空白分隔多个 IP/CIDR,且每项都会校验格式;`exists` 与 `!exists` 通常使用空字符串。
data[].value2string否随条件原样保存的补充参数;管理界面将其用于 `header` 的自定义请求头名称,以及 `count404`、`uniq_ua` 等统计匹配项的统计秒数。
uidinteger(int64)否新匹配器所属用户的 ID;省略时为当前登录用户,仅管理员可指定该字段,否则返回 `cc_match-39`。
internalinteger enum否是否创建为系统内置匹配器:1 表示内置,0 表示用户自定义;省略时为 0,传 1 要求管理员身份,否则返回 `cc_match-40`。0 | 1
enableinteger enum否兼容性输入字段,只接受 0 或 1;新增记录最终固定以启用状态 1 保存,即使这里传 0 也不会创建禁用记录。0 | 1

请求体示例

{ "name": "string", "des": "string", "data": [], "uid": 0, "internal": 0, "enable": 0 }

响应

HTTP 200

业务结果通过 HTTP 200 返回。创建成功时返回新匹配器 ID;配额不足、查询或 JSON 内置标记无效、名称校验失败、条件数组及其匹配项/操作符/值不合法、管理员专属字段越权、系统维护或认证失效时返回字符串业务错误码,数据库事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,匹配器创建并提交事务后固定为 0。0
oneOf#1.msgstring enum是匹配器记录创建成功后返回的确认消息。匹配器添加成功
oneOf#1.datainteger(int64)是数据库为新 CC 匹配器生成的唯一 ID。
oneOf#2.codestring enum是业务错误码:10 表示创建数量超过站点关联对象配额;11、13、14 表示名称为空、重复或缺失;17 表示 data 不是数组,18、19 表示匹配项或操作符无效,20 表示需要字符串的匹配值类型错误,21 表示 IP/CIDR 格式错误;23、24 表示 enable 为空或超出 0/1;31、33 表示查询参数或 JSON 内的 internal 超出 0/1;38 至 40 表示普通用户使用管理员专属参数;`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cc_match-10 | cc_match-11 | cc_match-13 | cc_match-14 | cc_match-17 | cc_match-18 | cc_match-19 | cc_match-20 | cc_match-21 | cc_match-23 | cc_match-24 | cc_match-31 | cc_match-33 | cc_match-38 | cc_match-39 | cc_match-40 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文配额、名称、匹配条件、状态、权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": 0 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"string","des":"string","data":[],"uid":0,"internal":0,"enable":0}' \ 'https://master.example.com/v1/cc-matchs'
用户 API / 网站与安全 / CC 防护 / 批量更新 CC 匹配器

PUT批量更新 CC 匹配器

PUT /v1/cc-matchs

在一个数据库事务中批量更新一个或多个 CC 请求匹配器,每个数组元素必须指定匹配器 ID,只修改该元素中明确提供且被服务端支持的字段。普通用户只能更新归属于自己的自定义匹配器,管理员可更新其他用户或系统内置匹配器。任一元素不存在、越权或校验失败时整个批次都会回滚;成功时所有目标匹配器的版本号均递增并刷新更新时间,即使某个元素除 ID 外没有其他字段。修改正在被 CC 规则引用的匹配条件或系统内置匹配器时会创建节点同步任务;禁用匹配器时如仍被引用则拒绝,否则创建节点删除任务。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

待批量更新的 CC 匹配器对象数组;空数组不会修改记录,非数组请求返回 `cc_match-30`。

字段类型必填说明示例
(root)array<object>否待批量更新的 CC 匹配器对象数组;空数组不会修改记录,非数组请求返回 `cc_match-30`。
[].idoneOf是要更新的 CC 匹配器 ID;接受正整数或仅含十进制数字的字符串,记录必须存在且当前身份必须有权更新。
[].id(oneOf#1)integer否
[].id(oneOf#2)string否
[].namestring否新的匹配器名称;服务端会过滤可执行的 HTML 内容,处理后不得为空,并且在校验所属用户下不可与其他匹配器重名。
[].desstring否新的匹配器备注;服务端会过滤可执行的 HTML 内容,可传空字符串清空备注。
[].dataarray否新的请求匹配条件数组;可为空数组。服务端会逐项校验,并将每项 `value` 去除首尾空白和空行后转换为小写再保存。
[].dataarray<object>否新的请求匹配条件数组;可为空数组。服务端会逐项校验,并将每项 `value` 去除首尾空白和空行后转换为小写再保存。
[].data[].itemstring enum是匹配项:支持 404 次数、唯一 UA、自定义请求头、客户端 IP、主机名、URI、请求方法、User-Agent、Referer、地理与 ASN 信息、协议、语言、TLS 指纹和访问端口。count404 | uniq_ua | header | ip | host | req_uri | req_method | uri | user_agent | referer | country_iso_code | asnumber | province | city | isp | protocol | accept_language | tls_fp | uniq_tls_fp | server_port
[].data[].opstring enum是匹配操作符,支持大小比较、包含、前后缀、正则、存在性以及 IP 网段包含或排除判断。> | = | != | !contain | contain | prefix | suffix | regex | !regex | exists | !exists | ip_range | !ip_range
[].data[].valuestring否匹配值,省略时补为空字符串;服务端会移除首尾空白和空行并转为小写。IP 网段操作符可用空白分隔多个 IP/CIDR,且每项都会校验格式。
[].data[].value2string否随条件原样保存的补充参数;管理界面将其用于自定义请求头名称或统计匹配项的统计秒数。
[].enableinteger enum否新的启用状态:1 表示启用,0 表示禁用。禁用前会检查当前用户及系统 CC 规则,仍被引用时返回 `cc_match-25`。0 | 1
[].uidinteger(int64)否兼容性管理员字段,用作本次名称唯一性和 CC 规则引用检查的用户上下文;仅管理员可传。该字段不会修改匹配器数据库中的所属用户,不能用于转移匹配器。
[].internalinteger enum否兼容性处理标记,1 要求管理员身份并会按内置匹配器流程决定同步任务。该字段不会改写数据库中已有的内置状态,不能用于转换匹配器归类。0 | 1

请求体示例

[ { "id": null, "name": "string", "des": "string", "data": [], "enable": 0, "uid": 0, "internal": 0 } ]

响应

HTTP 200

业务结果通过 HTTP 200 返回。全部元素更新并提交后返回确认消息;请求体格式、匹配器 ID、访问权限、名称、条件数组、匹配项、操作符、值、启用状态或禁用前引用检查失败,以及系统维护或认证失效时返回字符串业务错误码,整个批次事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,整个批次更新并提交后固定为 0。0
oneOf#1.msgstring enum是所有匹配器更新成功后返回的确认消息。更新匹配器成功
oneOf#1.datastring enum是批量更新成功时没有额外业务数据,固定为 null。
oneOf#2.codestring enum是业务错误码:7、8 表示匹配器 ID 格式错误或记录不存在;11、13 表示名称为空或重复;17 表示 data 不是数组,18、19 表示匹配项或操作符无效,20 表示需要字符串的值类型错误,21 表示 IP/CIDR 格式错误;23 至 25 表示启用状态无效或匹配器仍被 CC 规则引用;30 表示请求体不是数组,33 表示 internal 超出 0/1;36、37 表示普通用户更新内置或其他用户的匹配器,39、40 表示普通用户使用管理员专属字段;`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cc_match-7 | cc_match-8 | cc_match-11 | cc_match-13 | cc_match-17 | cc_match-18 | cc_match-19 | cc_match-20 | cc_match-21 | cc_match-23 | cc_match-24 | cc_match-25 | cc_match-30 | cc_match-33 | cc_match-36 | cc_match-37 | cc_match-39 | cc_match-40 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文请求格式、记录、名称、匹配条件、引用冲突、权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '[{"id":null,"name":"string","des":"string","data":[],"enable":0,"uid":0,"internal":0}]' \ 'https://master.example.com/v1/cc-matchs'
用户 API / 网站与安全 / CC 防护 / 删除一个或多个 CC 匹配器

DELETE删除一个或多个 CC 匹配器

DELETE /v1/cc-matchs/{match_id}

删除路径中指定的一个或多个 CC 请求匹配器,多个 ID 使用英文逗号分隔并在同一个数据库事务中处理。普通用户只能删除归属于自己的自定义匹配器,管理员可以删除系统内置匹配器及其他用户的匹配器。每个目标必须已经禁用;如果仍有关联的同步或删除任务,该任务状态必须为 `done`。任一 ID 格式错误、记录不存在、越权、仍启用或任务未完成时,整个批次回滚,不会保留部分删除结果。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
match_idpathstring是要删除的 CC 匹配器 ID;删除多个匹配器时按 `10021,10022` 形式使用英文逗号连接,每一段都必须是十进制数字。

响应

HTTP 200

业务结果通过 HTTP 200 返回。全部目标通过检查、删除并提交后返回确认消息;ID 格式、记录存在性、权限、启用状态或关联任务状态不符合要求,以及系统维护或认证失效时返回字符串业务错误码,整个批次事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,所有目标匹配器删除并提交后固定为 0。0
oneOf#1.msgstring enum是整个删除批次成功提交后返回的确认消息。匹配器删除成功
oneOf#1.datastring enum是删除成功时没有额外业务数据,固定为 null。
oneOf#2.codestring enum是业务错误码:`cc_match-1` 表示某段 ID 不是数字,`cc_match-2` 表示匹配器不存在,`cc_match-4` 表示匹配器仍处于启用状态,`cc_match-5` 表示关联任务尚未完成,`cc_match-34` 表示非管理员删除内置匹配器,`cc_match-35` 表示普通用户删除其他用户的匹配器,`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cc_match-1 | cc_match-2 | cc_match-4 | cc_match-5 | cc_match-34 | cc_match-35 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文 ID、记录、状态、权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/cc-matchs/{match_id}'
用户 API / 网站与安全 / CC 防护 / 获取 CC 匹配器详情

GET获取 CC 匹配器详情

GET /v1/cc-matchs/{match_id}

按 ID 获取一条 CC 请求匹配器的原始配置记录。系统内置匹配器仅管理员身份可以读取;用户自定义匹配器仅允许其所属用户读取,管理员身份本身不会绕过自定义匹配器的所有者校验。返回的是 `cc_match` 记录本身,不包含列表接口联表得到的任务状态、用户名或格式化时间字段;`data` 为序列化后的匹配条件 JSON 字符串,使用前需要再次解析。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
match_idpathinteger(int64)是要查询的 CC 匹配器 ID;路由只接受十进制整数。

响应

HTTP 200

业务结果通过 HTTP 200 返回。匹配器存在且当前身份有读取权限时返回完整原始配置;记录不存在、读取内置匹配器时不是管理员、读取其他用户的自定义匹配器或认证失效时返回字符串业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,匹配器详情读取成功时固定为 0。0
oneOf#1.msgstring enum是详情读取成功时没有附加提示,固定为空字符串。
oneOf#1.dataobject是数据库中的 CC 匹配器原始配置记录。
oneOf#1.data.idinteger(int64)是CC 匹配器的唯一 ID。
oneOf#1.data.uidinteger(int64)是匹配器所属用户的 ID;系统内置匹配器不归属于具体用户时为 null。
oneOf#1.data.namestring是匹配器名称,同一所属用户下不可重名。
oneOf#1.data.desstring是匹配器备注,可为空字符串。
oneOf#1.data.datastring是序列化后的匹配条件 JSON。`{}` 表示匹配全部请求;条件数组中的每项包含 `item`、`op`、规范化后的 `value`,并可包含补充参数。
oneOf#1.data.create_atstring是数据库返回的匹配器创建时间;历史记录未保存时间时为 null。
oneOf#1.data.update_atstring是数据库返回的匹配器最后更新时间;历史记录未保存时间时为 null。
oneOf#1.data.internalinteger enum是是否为系统内置匹配器:1 表示内置,0 表示用户自定义。0 | 1
oneOf#1.data.enableinteger enum是匹配器启用状态:1 表示启用,0 表示禁用。0 | 1
oneOf#1.data.task_idinteger(int64)是最近一次匹配器同步或删除任务的 ID;没有关联任务时为 null。
oneOf#1.data.versioninteger(int64)是匹配器配置版本号,每次更新时递增。
oneOf#2.codestring enum是业务错误码:`cc_match-26` 表示匹配器不存在,`cc_match-27` 表示当前用户不是自定义匹配器的所有者,`cc_match-41` 表示非管理员尝试读取系统内置匹配器,`login_required` 表示认证无效。cc_match-26 | cc_match-27 | cc_match-41 | login_required
oneOf#2.msgstring是与业务错误码对应的中文记录不存在、所有权、管理员权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "id": 0, "uid": 0, "name": "string", "des": "string", "data": "string", "create_at": "string", "update_at": "string", "internal": 0, "enable": 0, "task_id": 0, "version": 0 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/cc-matchs/{match_id}'
用户 API / 网站与安全 / CC 防护 / 更新单个 CC 匹配器

PUT更新单个 CC 匹配器

PUT /v1/cc-matchs/{match_id}

按路径 ID 更新一条 CC 请求匹配器,只修改 JSON 对象中明确提供且被服务端支持的字段;JSON 对象内的 `id` 即使存在也会被路径参数覆盖。普通用户只能更新归属于自己的自定义匹配器,管理员可更新其他用户或系统内置匹配器。成功更新时配置版本号必定递增并刷新更新时间,即使请求体为空对象。修改正在被 CC 规则引用的匹配条件或系统内置匹配器时会创建节点同步任务;禁用匹配器时如仍被引用则拒绝,否则创建节点删除任务。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
match_idpathinteger(int64)是要更新的 CC 匹配器 ID;路由只接受十进制整数,记录必须存在且当前身份必须有权更新。

请求体

请求体必填。

Content-Type:application/json

单个匹配器的更新对象;可以为空对象,此时只递增版本并刷新更新时间。必须提供 JSON 对象,数组、标量或空 JSON 返回 `cc_match-6`;未识别字段不写入记录,`id` 字段由路径参数覆盖。

字段类型必填说明示例
namestring否新的匹配器名称;服务端会过滤可执行的 HTML 内容,处理后不得为空,并且在校验所属用户下不可与其他匹配器重名。
desstring否新的匹配器备注;服务端会过滤可执行的 HTML 内容,可传空字符串清空备注。
dataarray否新的请求匹配条件数组;可为空数组。服务端会逐项校验,并将每项 `value` 去除首尾空白和空行后转换为小写再保存。
dataarray<object>否新的请求匹配条件数组;可为空数组。服务端会逐项校验,并将每项 `value` 去除首尾空白和空行后转换为小写再保存。
data[].itemstring enum是匹配项:支持 404 次数、唯一 UA、自定义请求头、客户端 IP、主机名、URI、请求方法、User-Agent、Referer、地理与 ASN 信息、协议、语言、TLS 指纹和访问端口。count404 | uniq_ua | header | ip | host | req_uri | req_method | uri | user_agent | referer | country_iso_code | asnumber | province | city | isp | protocol | accept_language | tls_fp | uniq_tls_fp | server_port
data[].opstring enum是匹配操作符,支持大于、相等、包含、前后缀、正则、存在性以及 IP 网段包含或排除判断。> | = | != | !contain | contain | prefix | suffix | regex | !regex | exists | !exists | ip_range | !ip_range
data[].valuestring否匹配值,省略时补为空字符串;服务端会移除首尾空白和空行并转为小写。IP 网段操作符可用空白分隔多个 IP/CIDR,且每项都会校验格式。
data[].value2string否随条件原样保存的补充参数;管理界面将其用于自定义请求头名称或统计匹配项的统计秒数。
enableinteger enum否新的启用状态:1 表示启用,0 表示禁用。禁用前会检查当前用户及系统 CC 规则,仍被引用时返回 `cc_match-25`。0 | 1
uidinteger(int64)否兼容性管理员字段,用作本次名称唯一性和 CC 规则引用检查的用户上下文;仅管理员可传。该字段不会修改匹配器数据库中的所属用户,不能用于转移匹配器。
internalinteger enum否兼容性处理标记,1 要求管理员身份并会按内置匹配器流程决定同步任务。该字段不会改写数据库中已有的内置状态,不能用于转换匹配器归类。0 | 1

请求体示例

{ "name": "string", "des": "string", "data": [], "enable": 0, "uid": 0, "internal": 0 }

响应

HTTP 200

业务结果通过 HTTP 200 返回。目标匹配器更新并提交后返回确认消息;请求体不是对象、匹配器不存在、访问权限不足、名称或匹配条件无效、禁用时仍被引用,以及系统维护或认证失效时返回字符串业务错误码,更新事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,匹配器更新并提交后固定为 0。0
oneOf#1.msgstring enum是目标匹配器更新成功后返回的确认消息。更新匹配器成功
oneOf#1.datastring enum是单个匹配器更新成功时没有额外业务数据,固定为 null。
oneOf#2.codestring enum是业务错误码:6 表示请求体不是 JSON 对象,8 表示匹配器不存在;11、13 表示名称为空或重复;17 表示 data 不是数组,18、19 表示匹配项或操作符无效,20 表示需要字符串的值类型错误,21 表示 IP/CIDR 格式错误;23 至 25 表示启用状态无效或匹配器仍被 CC 规则引用;33 表示 internal 超出 0/1;36、37 表示普通用户更新内置或其他用户的匹配器,39、40 表示普通用户使用管理员专属字段;`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cc_match-6 | cc_match-8 | cc_match-11 | cc_match-13 | cc_match-17 | cc_match-18 | cc_match-19 | cc_match-20 | cc_match-21 | cc_match-23 | cc_match-24 | cc_match-25 | cc_match-33 | cc_match-36 | cc_match-37 | cc_match-39 | cc_match-40 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文请求格式、记录、名称、匹配条件、引用冲突、权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"string","des":"string","data":[],"enable":0,"uid":0,"internal":0}' \ 'https://master.example.com/v1/cc-matchs/{match_id}'
用户 API / 网站与安全 / CC 防护 / 分页查询 CC 规则组列表

GET分页查询 CC 规则组列表

GET /v1/cc-rules

分页查询当前身份可见的 CC 规则组。默认情况下普通用户只返回自己创建的规则组,管理员返回全部规则组或通过 `uid` 限定所属用户;传 `internal_self=1` 时改为返回全局可见的内置规则、目标用户自己的规则以及 `show_to` 明确授权给该用户的规则。接口还支持按规则组 ID、名称、启用状态、前台显示状态和是否内置筛选,系统保留的 10020 号记录始终不会返回。结果先按 `sort` 升序,再按创建时间倒序排列;`data` 为序列化后的规则步骤 JSON 数组。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,从 1 开始;省略时为 1。只能传十进制非负整数字符串,非数字值返回 `cc_rule-30`;`limit=0` 时该参数不影响返回范围。
limitqueryinteger(int32)否每页返回的规则组数量,省略时为 10;传 0 表示不分页并返回全部匹配记录。非数字值返回 `cc_rule-31`。
uidqueryinteger(int64)否目标用户 ID。未使用 `internal_self` 时按所属用户精确筛选;使用 `internal_self=1` 时作为可见性计算的目标用户。该参数仅管理员可用,普通用户传入时返回 `cc_rule-382`。
internal_selfqueryinteger否传 1 时返回全局内置规则、目标用户自己的规则以及 `show_to` 中包含目标用户 ID 的规则;省略 `uid` 时目标用户为当前登录用户。
internalqueryinteger否按是否为系统内置规则组精确筛选:1 表示内置,0 表示用户自定义。该筛选条件仅管理员可用,普通用户传入时返回 `cc_rule-383`。
enablequeryinteger否按启用状态精确筛选:1 表示已启用,0 表示已禁用。
is_showqueryinteger否按前台显示状态精确筛选:1 表示展示给可见用户,0 表示不在前台选择列表中展示。
idqueryinteger(int64)否按 CC 规则组 ID 精确筛选;系统保留的 10020 号记录即使匹配也不会返回。
namequerystring否按规则组名称进行包含匹配。

响应

HTTP 200

请求通过 HTTP 200 返回。成功时给出符合可见性及筛选条件的总数和当前页规则组列表;普通用户指定目标用户或筛选内置状态、页码或每页数量格式错误、认证失效时,通过字符串 `code` 和 `msg` 返回业务错误。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,列表查询成功时固定为 0。0
oneOf#1.countinteger(int64)是符合可见性及筛选条件的规则组总数,不受当前页 `limit` 限制。
oneOf#1.dataarray是当前页的 CC 规则组记录,按排序值升序、相同排序值按创建时间倒序排列。
oneOf#1.dataarray<object>否当前页的 CC 规则组记录,按排序值升序、相同排序值按创建时间倒序排列。
oneOf#1.data[].idinteger(int64)是CC 规则组的唯一 ID。
oneOf#1.data[].sortinteger(int32)是规则组排序值,数值越小越靠前。
oneOf#1.data[].uidinteger(int64)是规则组所属用户的 ID;不归属于具体用户的系统内置规则可为 null。
oneOf#1.data[].c.uidinteger(int64)是查询结果中因再次选择所属用户列而生成的重复字段,值与 `uid` 相同;系统内置规则可为 null。
oneOf#1.data[].namestring是规则组名称,同一用户下不可重名。
oneOf#1.data[].desstring是规则组备注,可为空字符串。
oneOf#1.data[].datastring是序列化后的规则步骤 JSON 数组。每步包含执行模式、匹配器 ID、动作、启用状态、第一过滤器 ID,并可包含第二过滤器及用于界面显示的名称。
oneOf#1.data[].show_tostring是允许看到该规则组的用户 ID 列表,多个 ID 使用英文逗号分隔;空字符串表示未指定定向用户,内置规则此时对所有用户全局可见。
oneOf#1.data[].create_atstring是数据库返回的规则组创建时间;历史记录未保存时间时为 null。
oneOf#1.data[].update_atstring是数据库返回的规则组最后更新时间;历史记录未保存时间时为 null。
oneOf#1.data[].internalinteger enum是是否为系统内置规则组:1 表示内置,0 表示用户自定义。0 | 1
oneOf#1.data[].enableinteger enum是规则组启用状态:1 表示启用,0 表示禁用。0 | 1
oneOf#1.data[].is_showinteger enum是前台显示状态:1 表示展示,0 表示隐藏。0 | 1
oneOf#1.data[].task_idinteger(int64)是最近一次规则组同步或删除任务的 ID;没有关联任务时为 null。
oneOf#1.data[].versioninteger(int64)是规则组配置版本号,每次更新时递增。
oneOf#1.data[].statestring是关联任务的当前状态;规则组没有关联任务时为 null。
oneOf#1.data[].create_at2string是格式化为 `YYYY-MM-DD HH:mm:ss` 的创建时间;原始创建时间为 null 时也为 null。
oneOf#1.data[].update_at2string是格式化为 `YYYY-MM-DD HH:mm:ss` 的最后更新时间;原始更新时间为 null 时也为 null。
oneOf#1.data[].usernamestring是规则组所属用户的名称;不归属于具体用户的系统内置规则为 null。
oneOf#2.codestring enum是业务错误码:`cc_rule-30` 表示 page 不是数字,`cc_rule-31` 表示 limit 不是数字,`cc_rule-382` 表示普通用户指定目标用户,`cc_rule-383` 表示普通用户筛选内置状态,`login_required` 表示认证无效。cc_rule-30 | cc_rule-31 | cc_rule-382 | cc_rule-383 | login_required
oneOf#2.msgstring是与业务错误码对应的中文参数、权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/cc-rules'
用户 API / 网站与安全 / CC 防护 / 创建 CC 规则组

POST创建 CC 规则组

POST /v1/cc-rules

为当前登录用户创建一个 CC 规则组,创建前会按当前账号的网站数量和系统配置检查站点关联对象配额;同一所属用户下规则组名称不可重复。普通用户只能创建归属于自己的自定义规则组,管理员可指定所属用户、创建系统内置规则或设置定向可见用户。每个规则步骤必须指定执行模式、动作、已启用的匹配器和第一过滤器,可选第二过滤器;步骤数量不得超过运行时配置 `cc-rule-max-limit`,初始安装值为 5。记录创建成功后会立即创建节点同步任务,规则组可按请求以启用或禁用状态创建。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
internalqueryinteger否兼容性权限检查参数。传 1 时要求管理员身份,否则返回 `cc_rule-377`;该查询参数本身不会把新规则组标记为内置,创建内置规则应在 JSON 对象中传 `internal: 1`。

请求体

请求体必填。

Content-Type:application/json

创建 CC 规则组的 JSON 对象;未识别的顶层字段不会参与创建逻辑。

字段类型必填说明示例
namestring是规则组名称;服务端会过滤可执行的 HTML 内容,且要求处理后的名称非空、在所属用户下唯一。
sortoneOf否规则组排序值,数值越小越靠前;接受非负整数或仅含十进制数字的字符串,省略时为 100。
sort(oneOf#1)integer否
sort(oneOf#2)string否
desstring否规则组备注;服务端会过滤可执行的 HTML 内容,省略时保存为空字符串。
dataarray是按顺序执行的 CC 规则步骤数组,可为空数组;元素数量不得超过系统配置 `cc-rule-max-limit`,初始安装值为 5。
dataarray<object>否按顺序执行的 CC 规则步骤数组,可为空数组;元素数量不得超过系统配置 `cc-rule-max-limit`,初始安装值为 5。
data[].modestring enum是步骤命中后的流程模式:`break` 表示执行后结束该规则组,`continue` 表示继续评估后续步骤。break | continue
data[].actionstring enum是步骤动作:`block` 执行所选过滤器防护,`log` 记录命中行为。block | log
data[].matcheroneOf是用于判断该步骤是否命中的 CC 匹配器 ID;接受整数或数字字符串,目标匹配器必须存在且处于启用状态,服务端最终保存为字符串。
data[].matcher(oneOf#1)integer否
data[].matcher(oneOf#2)string否
data[].filter1oneOf是步骤使用的第一 CC 过滤器 ID;接受整数或数字字符串,目标过滤器必须存在且处于启用状态,服务端最终保存为字符串。
data[].filter1(oneOf#1)integer否
data[].filter1(oneOf#2)string否
data[].filter2oneOf否可选的第二 CC 过滤器 ID;省略或空字符串表示不使用第二过滤器,非空时必须是已启用过滤器的整数或数字字符串。
data[].filter2(oneOf#1)integer否
data[].filter2(oneOf#2)string否
data[].stateoneOf否该规则步骤是否启用;省略时为 true,也接受 0 或 1。
data[].state(oneOf#1)boolean否
data[].state(oneOf#2)integer否
data[].matcher_namestring否匹配器名称快照,仅供界面展示;服务端不据此查找匹配器,会与步骤一起原样保存。
data[].filter1_namestring否第一过滤器名称快照,仅供界面展示;服务端不据此查找过滤器,会与步骤一起原样保存。
data[].filter2_namestring否第二过滤器名称快照,仅供界面展示;没有第二过滤器时通常为空字符串。
show_tooneOf否允许看到该规则组的用户 ID,多个 ID 使用英文逗号分隔;空字符串表示未指定定向用户。仅管理员可设置,每个 ID 都必须对应现有用户。
show_to(oneOf#1)integer否
show_to(oneOf#2)string否
uidinteger(int64)否新规则组所属用户的 ID;省略时为当前登录用户,仅管理员可指定该字段,否则返回 `cc_rule-378`。
internaloneOf否是否创建为系统内置规则组:true 或 1 表示内置,false 或 0 表示用户自定义;省略时为 0,创建内置规则要求管理员身份。
internal(oneOf#1)boolean否
internal(oneOf#2)integer否
enableoneOf否规则组初始启用状态;true 或 1 表示启用,false 或 0 表示禁用,省略时启用。
enable(oneOf#1)boolean否
enable(oneOf#2)integer否
is_showoneOf否规则组初始前台显示状态;true 或 1 表示展示,false 或 0 表示隐藏,省略时展示。
is_show(oneOf#1)boolean否
is_show(oneOf#2)integer否

请求体示例

{ "name": "string", "sort": null, "des": "string", "data": [], "show_to": null, "uid": 0, "internal": null, "enable": null, "is_show": null }

响应

HTTP 200

业务结果通过 HTTP 200 返回。规则组、关联同步任务创建并提交后返回新规则组 ID;配额、名称、排序、步骤数量或结构、模式、动作、匹配器、过滤器、步骤状态、定向用户、启用/显示状态、管理员专属字段、系统维护或认证校验失败时返回字符串业务错误码,事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,规则组及同步任务创建并提交后固定为 0。0
oneOf#1.msgstring enum是CC 规则组创建成功后返回的确认消息。cc规则添加成功
oneOf#1.datainteger(int64)是数据库为新 CC 规则组生成的唯一 ID。
oneOf#2.codestring enum是业务错误码:10 表示创建数量超过站点关联对象配额;11、13、14 表示名称为空、重复或缺失;17、18、24 表示 data 类型错误、步骤过多或缺失;19 至 23 表示动作、引用对象、步骤状态或第二过滤器无效;25、26 表示 enable 为空或无效;33 至 35-2 表示步骤缺少 action、matcher、filter1 或其 ID 格式错误;36、37 表示排序为空或不是数字;38、39 表示 is_show 为空或无效;41、41-1 表示定向用户不存在或格式错误;42 表示 internal 无效;371、372 表示 mode 缺失或无效;377 至 380 表示普通用户使用管理员专属参数;`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cc_rule-10 | cc_rule-11 | cc_rule-13 | cc_rule-14 | cc_rule-17 | cc_rule-18 | cc_rule-19 | cc_rule-20 | cc_rule-21 | cc_rule-22 | cc_rule-23 | cc_rule-24 | cc_rule-25 | cc_rule-26 | cc_rule-33 | cc_rule-34 | cc_rule-34-1 | cc_rule-35 | cc_rule-35-1 | cc_rule-35-2 | cc_rule-36 | cc_rule-37 | cc_rule-38 | cc_rule-39 | cc_rule-41 | cc_rule-41-1 | cc_rule-42 | cc_rule-371 | cc_rule-372 | cc_rule-377 | cc_rule-378 | cc_rule-379 | cc_rule-380 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文配额、字段、规则步骤、引用对象、可见性、权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": 0 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"string","sort":null,"des":"string","data":[],"show_to":null,"uid":0,"internal":null,"enable":null,"is_show":null}' \ 'https://master.example.com/v1/cc-rules'
用户 API / 网站与安全 / CC 防护 / 批量更新 CC 规则组

PUT批量更新 CC 规则组

PUT /v1/cc-rules

在一个数据库事务中批量更新一个或多个 CC 规则组。请求体必须是数组,每个元素必须指定规则组 ID;名称、排序、备注、规则步骤、定向可见用户、启用状态和前台显示状态均为可选字段,只更新明确提供的字段。普通用户只能更新归属于自己的自定义规则组,管理员可更新其他用户或系统内置规则组;任一元素不存在、越权或校验失败时整个批次回滚。每个成功处理的规则组都会递增版本号并刷新更新时间,即使该元素除 ID 外未提供其他可写字段。修改已启用且被网站使用的规则步骤会创建节点同步任务;禁用规则组前必须确认其未被网站、全局默认值、用户默认值、防火墙默认页规则或自动规则切换引用,禁用成功时会创建节点删除任务。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

待更新的 CC 规则组对象数组,可传空数组;非数组请求返回 `cc_rule-32`。数组中任一对象失败时整个事务回滚。

字段类型必填说明示例
(root)array<object>否待更新的 CC 规则组对象数组,可传空数组;非数组请求返回 `cc_rule-32`。数组中任一对象失败时整个事务回滚。
[].idoneOf是要更新的 CC 规则组 ID;接受正整数或仅含十进制数字的字符串。记录必须存在,普通用户只能操作归属于自己的非系统规则组。
[].id(oneOf#1)integer否
[].id(oneOf#2)string否
[].namestring否新的规则组名称;服务端会过滤可执行的 HTML 内容,处理后不得为空,并且在校验所属用户下不可与其他规则组重名。省略时保持原名称。
[].sortoneOf否新的排序值,数值越小越靠前;接受非负整数或仅含十进制数字的字符串,省略时保持原值。
[].sort(oneOf#1)integer否
[].sort(oneOf#2)string否
[].desstring否新的规则组备注;服务端会过滤可执行的 HTML 内容,可传空字符串清空备注,省略时保持原值。
[].dataarray否替换当前完整规则步骤的数组,可为空数组;元素数量不得超过运行时配置 `cc-rule-max-limit`,初始安装值为 5。若规则组已启用且正被网站使用,修改步骤会创建节点同步任务。
[].dataarray<object>否替换当前完整规则步骤的数组,可为空数组;元素数量不得超过运行时配置 `cc-rule-max-limit`,初始安装值为 5。若规则组已启用且正被网站使用,修改步骤会创建节点同步任务。
[].data[].modestring enum是步骤命中后的流程模式:`break` 表示执行后结束该规则组,`continue` 表示继续评估后续步骤。break | continue
[].data[].actionstring enum是步骤动作:`block` 执行所选过滤器防护,`log` 记录命中行为。block | log
[].data[].matcheroneOf是用于判断该步骤是否命中的 CC 匹配器 ID;接受整数或数字字符串,目标匹配器必须存在且处于启用状态,服务端最终保存为字符串。
[].data[].matcher(oneOf#1)integer否
[].data[].matcher(oneOf#2)string否
[].data[].filter1oneOf是步骤使用的第一 CC 过滤器 ID;接受整数或数字字符串,目标过滤器必须存在且处于启用状态,服务端最终保存为字符串。
[].data[].filter1(oneOf#1)integer否
[].data[].filter1(oneOf#2)string否
[].data[].filter2oneOf否可选的第二 CC 过滤器 ID;省略或空字符串表示不使用第二过滤器,非空时必须是已启用过滤器的整数或数字字符串。
[].data[].filter2(oneOf#1)integer否
[].data[].filter2(oneOf#2)string否
[].data[].stateoneOf否该规则步骤是否启用;省略时为 true,也接受 0 或 1。
[].data[].state(oneOf#1)boolean否
[].data[].state(oneOf#2)integer否
[].data[].matcher_namestring否匹配器名称快照,仅供界面展示;服务端不据此查找匹配器,会与步骤一起原样保存。
[].data[].filter1_namestring否第一过滤器名称快照,仅供界面展示;服务端不据此查找过滤器,会与步骤一起原样保存。
[].data[].filter2_namestring否第二过滤器名称快照,仅供界面展示;没有第二过滤器时通常为空字符串。
[].show_tooneOf否新的定向可见用户 ID,多个 ID 使用英文逗号分隔;空字符串表示不指定定向用户。仅管理员可修改,每个 ID 都必须对应现有用户。
[].show_to(oneOf#1)integer否
[].show_to(oneOf#2)string否
[].uidinteger(int64)否兼容性管理员字段,用作本次名称唯一性校验的用户上下文;仅管理员可传。该字段不会修改规则组数据库中的所属用户,不能用于转移规则组。
[].internaloneOf否兼容性处理标记;1 或 true 要求管理员身份,并会按系统规则流程决定同步任务。该字段不会改写已有规则组的系统内置状态,不能用于转换规则组类型。
[].internal(oneOf#1)boolean否
[].internal(oneOf#2)integer否
[].enableoneOf否新的启用状态:true 或 1 表示启用,false 或 0 表示禁用。禁用前要求规则组未被网站或任何默认配置引用,且 ID 不得小于 10020;满足条件后会为非系统规则创建节点删除任务。
[].enable(oneOf#1)boolean否
[].enable(oneOf#2)integer否
[].is_showoneOf否新的前台显示状态:true 或 1 表示展示,false 或 0 表示隐藏;省略时保持原值。
[].is_show(oneOf#1)boolean否
[].is_show(oneOf#2)integer否

请求体示例

[ { "id": null, "name": "string", "sort": null, "des": "string", "data": [], "show_to": null, "uid": 0, "internal": null, "enable": null, "is_show": null } ]

响应

HTTP 200

业务结果通过 HTTP 200 返回。全部规则组更新并提交后返回确认消息;请求体格式、规则组 ID、访问权限、名称、排序、规则步骤、引用的匹配器或过滤器、定向用户、启用/显示状态、禁用前引用检查、系统维护或认证校验失败时返回字符串业务错误码,整个批次事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,整个批次更新并提交后固定为 0。0
oneOf#1.msgstring enum是所有规则组更新成功后返回的确认消息。更新cc规则成功
oneOf#1.datastring enum是批量更新成功时没有额外业务数据,固定为 null。
oneOf#2.codestring enum是业务错误码:7、8 表示规则组 ID 格式错误或记录不存在;11、13 表示名称为空或重复;17、18 表示 data 类型错误或步骤过多;19 至 23 表示动作、引用对象、步骤状态或第二过滤器无效;25、26 表示 enable 为空或无效;27、40、43 至 46 表示规则组仍被网站或默认配置引用,或属于不可禁用的保留规则;32 表示请求体不是数组;33 至 35-2 表示步骤缺少 action、matcher、filter1 或其 ID 格式错误;36、37 表示排序为空或不是数字;38、39 表示 is_show 为空或无效;41、41-1 表示定向用户不存在或格式错误;42 表示 internal 无效;371、372 表示 mode 缺失或无效;375、376、378 至 380 表示当前身份无权更新目标或使用管理员专属字段;`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cc_rule-7 | cc_rule-8 | cc_rule-11 | cc_rule-13 | cc_rule-17 | cc_rule-18 | cc_rule-19 | cc_rule-20 | cc_rule-21 | cc_rule-22 | cc_rule-23 | cc_rule-25 | cc_rule-26 | cc_rule-27 | cc_rule-32 | cc_rule-33 | cc_rule-34 | cc_rule-34-1 | cc_rule-35 | cc_rule-35-1 | cc_rule-35-2 | cc_rule-36 | cc_rule-37 | cc_rule-38 | cc_rule-39 | cc_rule-40 | cc_rule-41 | cc_rule-41-1 | cc_rule-42 | cc_rule-43 | cc_rule-44 | cc_rule-45 | cc_rule-46 | cc_rule-371 | cc_rule-372 | cc_rule-375 | cc_rule-376 | cc_rule-378 | cc_rule-379 | cc_rule-380 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文请求格式、目标记录、字段校验、规则步骤、引用关系、禁用限制、访问权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '[{"id":null,"name":"string","sort":null,"des":"string","data":[],"show_to":null,"uid":0,"internal":null,"enable":null,"is_show":null}]' \ 'https://master.example.com/v1/cc-rules'
用户 API / 网站与安全 / CC 防护 / 删除一个或多个 CC 规则组

DELETE删除一个或多个 CC 规则组

DELETE /v1/cc-rules/{rule_id}

删除路径中指定的一个或多个 CC 规则组,多个 ID 使用英文逗号分隔并在同一个数据库事务中处理。普通用户只能删除归属于自己的自定义规则组,管理员可以删除系统内置规则组及其他用户的规则组。每个目标必须已经禁用;如果仍有关联的同步或删除任务,该任务状态必须为 `done`。任一 ID 格式错误、记录不存在、越权、仍启用或任务未完成时,整个批次回滚,不会保留部分删除结果。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
rule_idpathstring是要删除的 CC 规则组 ID;删除多个规则组时按 `10021,10022` 形式使用英文逗号连接,每一段都必须是十进制数字。

响应

HTTP 200

业务结果通过 HTTP 200 返回。全部目标通过检查、删除并提交后返回确认消息;ID 格式、记录存在性、权限、启用状态或关联任务状态不符合要求,以及系统维护或认证失效时返回字符串业务错误码,整个批次事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,所有目标规则组删除并提交后固定为 0。0
oneOf#1.msgstring enum是整个删除批次成功提交后返回的确认消息。cc规则删除成功
oneOf#1.datastring enum是删除成功时没有额外业务数据,固定为 null。
oneOf#2.codestring enum是业务错误码:`cc_rule-1` 表示某段 ID 不是数字,`cc_rule-2` 表示规则组不存在,`cc_rule-4` 表示规则组仍处于启用状态,`cc_rule-5` 表示关联任务尚未完成,`cc_rule-373` 表示非管理员删除系统内置规则组,`cc_rule-374` 表示普通用户删除其他用户的自定义规则组,`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cc_rule-1 | cc_rule-2 | cc_rule-4 | cc_rule-5 | cc_rule-373 | cc_rule-374 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文 ID、记录、状态、权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/cc-rules/{rule_id}'
用户 API / 网站与安全 / CC 防护 / 获取 CC 规则组详情

GET获取 CC 规则组详情

GET /v1/cc-rules/{rule_id}

按 ID 获取一条 CC 规则组的原始配置记录。系统内置规则组仅管理员身份可以读取;用户自定义规则组仅允许其所属用户读取,管理员身份本身不会绕过自定义规则组的所有者校验。返回的是 `cc_rule` 记录本身,不包含列表接口联表得到的任务状态、用户名或格式化时间字段;`data` 为序列化后的规则步骤 JSON 字符串,使用前需要再次解析。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
rule_idpathinteger(int64)是要查询的 CC 规则组 ID;路由只接受十进制整数。

响应

HTTP 200

业务结果通过 HTTP 200 返回。规则组存在且当前身份有读取权限时返回完整原始配置;记录不存在、读取系统内置规则组时不是管理员、读取其他用户的自定义规则组或认证失效时返回字符串业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,规则组详情读取成功时固定为 0。0
oneOf#1.msgstring enum是详情读取成功时没有附加提示,固定为空字符串。
oneOf#1.dataobject是数据库中的 CC 规则组原始配置记录。
oneOf#1.data.idinteger(int64)是CC 规则组的唯一 ID。
oneOf#1.data.sortinteger(int32)是规则组排序值,数值越小越靠前。
oneOf#1.data.uidinteger(int64)是规则组所属用户的 ID;历史或系统内置记录不归属于具体用户时可能为 null。
oneOf#1.data.namestring是规则组名称,同一所属用户下不可重名。
oneOf#1.data.desstring是规则组备注,可为空字符串。
oneOf#1.data.datastring是序列化后的规则步骤 JSON 数组。每个步骤包含 `mode`、`action`、`matcher`、`filter1`,并可包含 `filter2`、`state` 及界面展示用名称;客户端需要再次进行 JSON 解析。
oneOf#1.data.show_tostring是允许看到该规则组的定向用户 ID,多个 ID 使用英文逗号分隔;空字符串表示未指定定向用户。
oneOf#1.data.create_atstring是数据库返回的规则组创建时间;历史记录未保存时间时为 null。
oneOf#1.data.update_atstring是数据库返回的规则组最后更新时间;历史记录未保存时间时为 null。
oneOf#1.data.internalinteger enum是是否为系统内置规则组:1 表示内置,0 表示用户自定义。0 | 1
oneOf#1.data.enableinteger enum是规则组启用状态:1 表示启用,0 表示禁用。0 | 1
oneOf#1.data.is_showinteger enum是规则组前台显示状态:1 表示展示,0 表示隐藏。0 | 1
oneOf#1.data.task_idinteger(int64)是最近一次规则组同步或删除任务的 ID;没有关联任务时为 null。
oneOf#1.data.versioninteger(int64)是规则组配置版本号,每次更新时递增。
oneOf#2.codestring enum是业务错误码:`cc_rule-28` 表示规则组不存在,`cc_rule-29` 表示当前账号不是自定义规则组的所有者,`cc_rule-381` 表示非管理员尝试读取系统内置规则组,`login_required` 表示认证无效。cc_rule-28 | cc_rule-29 | cc_rule-381 | login_required
oneOf#2.msgstring是与业务错误码对应的中文记录不存在、所有权、管理员权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "id": 0, "sort": 0, "uid": 0, "name": "string", "des": "string", "data": "string", "show_to": "string", "create_at": "string", "update_at": "string", "internal": 0, "enable": 0, "is_show": 0, "task_id": 0, "version": 0 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/cc-rules/{rule_id}'
用户 API / 网站与安全 / CC 防护 / 更新指定 CC 规则组

PUT更新指定 CC 规则组

PUT /v1/cc-rules/{rule_id}

按路径 ID 更新一条 CC 规则组。请求体必须是 JSON 对象,路径中的 `rule_id` 是唯一目标标识;即使请求体包含 `id`,服务端也会用路径 ID 覆盖。名称、排序、备注、规则步骤、定向可见用户、启用状态和前台显示状态均为可选字段,只更新明确提供的字段。普通用户只能更新归属于自己的自定义规则组,管理员可更新其他用户或系统内置规则组。传入空对象也会递增版本号并刷新更新时间。修改已启用且被网站使用的规则步骤会创建节点同步任务;禁用前必须确认规则组未被网站、全局默认值、用户默认值、防火墙默认页规则或自动规则切换引用,禁用成功时会创建节点删除任务。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
rule_idpathinteger(int64)是要更新的 CC 规则组 ID;路由只接受十进制整数,并会覆盖请求体中可能存在的 `id`。

请求体

请求体必填。

Content-Type:application/json

指定规则组的部分更新对象,可为空对象;请求体中的 `id` 和未识别字段不会决定目标或写入规则组记录。

字段类型必填说明示例
namestring否新的规则组名称;服务端会过滤可执行的 HTML 内容,处理后不得为空,并且在校验所属用户下不可与其他规则组重名。省略时保持原名称。
sortoneOf否新的排序值,数值越小越靠前;接受非负整数或仅含十进制数字的字符串,省略时保持原值。
sort(oneOf#1)integer否
sort(oneOf#2)string否
desstring否新的规则组备注;服务端会过滤可执行的 HTML 内容,可传空字符串清空备注,省略时保持原值。
dataarray否替换当前完整规则步骤的数组,可为空数组;元素数量不得超过运行时配置 `cc-rule-max-limit`,初始安装值为 5。若规则组已启用且正被网站使用,修改步骤会创建节点同步任务。
dataarray<object>否替换当前完整规则步骤的数组,可为空数组;元素数量不得超过运行时配置 `cc-rule-max-limit`,初始安装值为 5。若规则组已启用且正被网站使用,修改步骤会创建节点同步任务。
data[].modestring enum是步骤命中后的流程模式:`break` 表示执行后结束该规则组,`continue` 表示继续评估后续步骤。break | continue
data[].actionstring enum是步骤动作:`block` 执行所选过滤器防护,`log` 记录命中行为。block | log
data[].matcheroneOf是用于判断该步骤是否命中的 CC 匹配器 ID;接受整数或数字字符串,目标匹配器必须存在且处于启用状态,服务端最终保存为字符串。
data[].matcher(oneOf#1)integer否
data[].matcher(oneOf#2)string否
data[].filter1oneOf是步骤使用的第一 CC 过滤器 ID;接受整数或数字字符串,目标过滤器必须存在且处于启用状态,服务端最终保存为字符串。
data[].filter1(oneOf#1)integer否
data[].filter1(oneOf#2)string否
data[].filter2oneOf否可选的第二 CC 过滤器 ID;省略或空字符串表示不使用第二过滤器,非空时必须是已启用过滤器的整数或数字字符串。
data[].filter2(oneOf#1)integer否
data[].filter2(oneOf#2)string否
data[].stateoneOf否该规则步骤是否启用;省略时为 true,也接受 0 或 1。
data[].state(oneOf#1)boolean否
data[].state(oneOf#2)integer否
data[].matcher_namestring否匹配器名称快照,仅供界面展示;服务端不据此查找匹配器,会与步骤一起原样保存。
data[].filter1_namestring否第一过滤器名称快照,仅供界面展示;服务端不据此查找过滤器,会与步骤一起原样保存。
data[].filter2_namestring否第二过滤器名称快照,仅供界面展示;没有第二过滤器时通常为空字符串。
show_tooneOf否新的定向可见用户 ID,多个 ID 使用英文逗号分隔;空字符串表示不指定定向用户。仅管理员可修改,每个 ID 都必须对应现有用户。
show_to(oneOf#1)integer否
show_to(oneOf#2)string否
uidinteger(int64)否兼容性管理员字段,用作本次名称唯一性校验的用户上下文;仅管理员可传。该字段不会修改规则组数据库中的所属用户,不能用于转移规则组。
internaloneOf否兼容性处理标记;1 或 true 要求管理员身份,并会按系统规则流程决定同步任务。该字段不会改写已有规则组的系统内置状态,不能用于转换规则组类型。
internal(oneOf#1)boolean否
internal(oneOf#2)integer否
enableoneOf否新的启用状态:true 或 1 表示启用,false 或 0 表示禁用。禁用前要求规则组未被网站或任何默认配置引用,且 ID 不得小于 10020;满足条件后会为非系统规则创建节点删除任务。
enable(oneOf#1)boolean否
enable(oneOf#2)integer否
is_showoneOf否新的前台显示状态:true 或 1 表示展示,false 或 0 表示隐藏;省略时保持原值。
is_show(oneOf#1)boolean否
is_show(oneOf#2)integer否

请求体示例

{ "name": "string", "sort": null, "des": "string", "data": [], "show_to": null, "uid": 0, "internal": null, "enable": null, "is_show": null }

响应

HTTP 200

业务结果通过 HTTP 200 返回。目标规则组更新并提交后返回确认消息;请求体格式、目标记录、访问权限、名称、排序、规则步骤、引用的匹配器或过滤器、定向用户、启用/显示状态、禁用前引用检查、系统维护或认证校验失败时返回字符串业务错误码,事务回滚。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,规则组更新并提交后固定为 0。0
oneOf#1.msgstring enum是规则组更新成功后返回的确认消息。更新cc规则成功
oneOf#1.datastring enum是更新成功时没有额外业务数据,固定为 null。
oneOf#2.codestring enum是业务错误码:6 表示请求体不是 JSON 对象;8 表示规则组不存在;11、13 表示名称为空或重复;17、18 表示 data 类型错误或步骤过多;19 至 23 表示动作、引用对象、步骤状态或第二过滤器无效;25、26 表示 enable 为空或无效;27、40、43 至 46 表示规则组仍被网站或默认配置引用,或属于不可禁用的保留规则;33 至 35-2 表示步骤缺少 action、matcher、filter1 或其 ID 格式错误;36、37 表示排序为空或不是数字;38、39 表示 is_show 为空或无效;41、41-1 表示定向用户不存在或格式错误;42 表示 internal 无效;371、372 表示 mode 缺失或无效;375、376、378 至 380 表示当前身份无权更新目标或使用管理员专属字段;`maintain` 表示当前禁止写操作,`login_required` 表示认证无效。cc_rule-6 | cc_rule-8 | cc_rule-11 | cc_rule-13 | cc_rule-17 | cc_rule-18 | cc_rule-19 | cc_rule-20 | cc_rule-21 | cc_rule-22 | cc_rule-23 | cc_rule-25 | cc_rule-26 | cc_rule-27 | cc_rule-33 | cc_rule-34 | cc_rule-34-1 | cc_rule-35 | cc_rule-35-1 | cc_rule-35-2 | cc_rule-36 | cc_rule-37 | cc_rule-38 | cc_rule-39 | cc_rule-40 | cc_rule-41 | cc_rule-41-1 | cc_rule-42 | cc_rule-43 | cc_rule-44 | cc_rule-45 | cc_rule-46 | cc_rule-371 | cc_rule-372 | cc_rule-375 | cc_rule-376 | cc_rule-378 | cc_rule-379 | cc_rule-380 | maintain | login_required
oneOf#2.msgstring是与业务错误码对应的中文请求格式、目标记录、字段校验、规则步骤、引用关系、禁用限制、访问权限、维护状态或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"string","sort":null,"des":"string","data":[],"show_to":null,"uid":0,"internal":null,"enable":null,"is_show":null}' \ 'https://master.example.com/v1/cc-rules/{rule_id}'
用户 API / 套餐与交易 / 套餐目录

套餐目录

可购买套餐、套餐分组和升级包。

接口列表

GET
/v1/package-groups
查询套餐组列表 — 分页查询套餐组,并按排序值升序返回。普通登录用户仅能看到 `enable` 为 1 的套餐组;管理员可查看全部套餐组。
POST
/v1/package-groups
创建套餐组 — 以管理员身份创建套餐组。套餐组名称在系统内必须唯一;未提供的备注保存为空字符串,排序默认 100,启用状态默认启用。
DELETE
/v1/package-groups/{group_id}
删除套餐组 — 以管理员身份删除一个或多个套餐组。路径参数支持英文逗号分隔多个套餐组 ID;每个套餐组必须存在且未关联任何套餐,任一校验失败都会回滚本次删除。
GET
/v1/package-groups/{group_id}
获取套餐组详情 — 按 ID 获取套餐组详情。接口仅要求登录,查询时不按 `enable` 过滤,因此普通用户也可读取已停用套餐组的详情。
PUT
/v1/package-groups/{group_id}
更新套餐组 — 以管理员身份更新套餐组。路径中的套餐组 ID 会覆盖请求体中的同名字段;未提供的字段保持原值,至少应提交一个与原值不同的字段。
GET
/v1/package-ups
查询套餐升级规则 — 分页查询套餐升级规则,按升级包 ID 倒序返回。普通用户仅能看到已启用的规则:未传 `upid` 时只返回未绑定基础套餐的规则,传入 `upid` 时返回未绑定
POST
/v1/package-ups
创建套餐升级规则 — 以管理员身份创建套餐升级规则。名称必须唯一;普通资源类型必须提供增加数量,`custom_cc_rule` 类型的数量由服务端强制设为 1。金额以系统最小货币单
DELETE
/v1/package-ups/{package_id}
删除套餐升级规则 — 以管理员身份删除一个或多个套餐升级规则。路径参数支持英文逗号分隔多个规则 ID;每条规则必须存在且未被任何用户套餐升级记录引用,任一检查失败都会回滚本次操作。
GET
/v1/package-ups/{package_id}
获取套餐升级详情 — 按 ID 获取套餐升级规则详情。任何登录用户都可读取启用规则;停用规则仅管理员可读取。
PUT
/v1/package-ups/{package_id}
更新套餐升级规则 — 以管理员身份更新一条升级规则。请求体必须是 JSON 对象,路径中的规则 ID 会覆盖请求体 ID。服务端每次都会更新 `update_at`,因此空对象也会成
GET
/v1/packages
查询套餐列表 — 分页查询套餐,按排序值升序返回。普通用户仅能查询已启用的非专属套餐;传 `mine` 时仅查询 `owner` 包含当前用户 ID 的专属套餐。管理员可查看全部
POST
/v1/packages
创建套餐 — 以管理员身份创建套餐。主线路组必须属于所选区域且至少配置一条启用线路;CNAME 域名必须存在;套餐名称必须唯一,并必须选择至少一个套餐组。创建成功后会同步该区
PUT
/v1/packages
批量更新套餐 — 以管理员身份批量更新套餐。请求体必须为 JSON 数组,每个元素必须包含现有套餐 ID;未提供的字段保持原值。服务端每次都会更新各套餐的 `update_at`
DELETE
/v1/packages/{package_id}
删除套餐 — 以管理员身份删除一个或多个套餐。路径参数支持英文逗号分隔多个套餐 ID;每条套餐必须存在且未被任何用户套餐引用。删除时会同时移除套餐与套餐组的关联,任一检查失败
GET
/v1/packages/{package_id}
获取套餐详情 — 获取一条套餐记录。普通用户只能读取启用套餐,管理员可读取停用套餐。传入 `duration` 时,服务端会按当前登录用户的有效折扣和可用优惠码试算该周期价格,并
PUT
/v1/packages/{package_id}
更新指定套餐 — 以管理员身份更新一条套餐。请求体必须为 JSON 对象;路径中的套餐 ID 会覆盖请求体中的 ID。未提供的字段保持原值,且服务端每次都会更新 `update_
用户 API / 套餐与交易 / 套餐目录 / 查询套餐组列表

GET查询套餐组列表

GET /v1/package-groups

分页查询套餐组,并按排序值升序返回。普通登录用户仅能看到 `enable` 为 1 的套餐组;管理员可查看全部套餐组。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger否页码,必须为非负数字字符串或数字;默认 1。1
limitqueryinteger否每页返回条数,必须为非负数字;默认 10。传 0 时不使用分页限制。10

响应

HTTP 200

查询成功时不含 `msg` 字段;参数或认证错误仍返回 HTTP 200。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.countinteger是筛选后的套餐组总数,未受分页影响。2
oneOf#1.dataarray是当前页套餐组记录,按 `sort` 升序排列。
oneOf#1.dataarray<object>否当前页套餐组记录,按 `sort` 升序排列。
oneOf#1.data[].idinteger是套餐组 ID。
oneOf#1.data[].namestring是套餐组名称。
oneOf#1.data[].desstring是套餐组备注。
oneOf#1.data[].sortinteger是展示排序值,数值越小越靠前。
oneOf#1.data[].enableinteger enum是是否启用:1 为启用,0 为停用。0 | 1
oneOf#1.data[].create_atstring是创建时间,由数据库日期时间字段序列化返回。
oneOf#1.data[].update_atstring是最后更新时间,由数据库日期时间字段序列化返回;新建记录可能为 null。
oneOf#2.codestring enum是页码/分页条数格式错误或未登录时的业务错误码。package_group-4 | package_group-5 | login_required
oneOf#2.msgstring是错误原因。page参数格式不正确
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "count": 2, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/package-groups'
用户 API / 套餐与交易 / 套餐目录 / 创建套餐组

POST创建套餐组

POST /v1/package-groups

以管理员身份创建套餐组。套餐组名称在系统内必须唯一;未提供的备注保存为空字符串,排序默认 100,启用状态默认启用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring是套餐组名称,不能为空且必须唯一。标准套餐
desstring否套餐组备注;未传时保存为空字符串。适用于普通网站
sortinteger否展示排序值;未传或传空值时为 100,数值越小越靠前。100
enableinteger enum否是否启用:1 为启用,0 为停用;未传时为 1。1

请求体示例

{ "name": "标准套餐", "des": "适用于普通网站", "sort": 100, "enable": 1 }

响应

HTTP 200

套餐组创建成功,`data` 为新记录的自增 ID。 未登录、维护模式限制、非管理员或字段校验失败时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package_group-18`、`package_group-9`、`package_group-11`、`package_group-12`、`package_group-13`、`package_group-15` 或 `package_group-16`。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。套餐组添加成功
oneOf#1.datainteger是新创建套餐组的自增 ID。3
oneOf#2.codestring是业务错误码。package_group-11
oneOf#2.msgstring是错误原因。套餐组名称 标准套餐已存在
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "套餐组添加成功", "data": 3 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"标准套餐","des":"适用于普通网站","sort":100,"enable":1}' \ 'https://master.example.com/v1/package-groups'
用户 API / 套餐与交易 / 套餐目录 / 删除套餐组

DELETE删除套餐组

DELETE /v1/package-groups/{group_id}

以管理员身份删除一个或多个套餐组。路径参数支持英文逗号分隔多个套餐组 ID;每个套餐组必须存在且未关联任何套餐,任一校验失败都会回滚本次删除。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
group_idpathstring是一个套餐组 ID,或以英文逗号分隔的多个套餐组 ID。3,4

响应

HTTP 200

套餐组删除成功。 未登录、维护模式限制、非管理员、套餐组不存在或套餐组仍关联套餐时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package_group-17`、`package_group-1` 或 `package_group-2`。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。套餐组删除成功
oneOf#1.datastring是该操作未返回已删除的套餐组数据。
oneOf#2.codestring是业务错误码。package_group-2
oneOf#2.msgstring是错误原因。当前套餐组已有套餐,请先移除再操作
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "套餐组删除成功", "data": "string" }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/package-groups/{group_id}'
用户 API / 套餐与交易 / 套餐目录 / 获取套餐组详情

GET获取套餐组详情

GET /v1/package-groups/{group_id}

按 ID 获取套餐组详情。接口仅要求登录,查询时不按 `enable` 过滤,因此普通用户也可读取已停用套餐组的详情。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
group_idpathinteger是套餐组 ID。3

响应

HTTP 200

成功、未登录和套餐组不存在均返回 HTTP 200。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是成功时为空字符串。
oneOf#1.dataobject是套餐组记录。
oneOf#1.data.idinteger是套餐组 ID。
oneOf#1.data.namestring是套餐组名称。
oneOf#1.data.desstring是套餐组备注。
oneOf#1.data.sortinteger是展示排序值。
oneOf#1.data.enableinteger enum是是否启用:1 为启用,0 为停用。0 | 1
oneOf#1.data.create_atstring是创建时间,由数据库日期时间字段序列化返回。
oneOf#1.data.update_atstring是最后更新时间,由数据库日期时间字段序列化返回;可能为 null。
oneOf#2.codestring enum是套餐组不存在或未登录时的业务错误码。package_group-3 | login_required
oneOf#2.msgstring是错误原因。套餐组不存在
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "", "data": { "id": 0, "name": "string", "des": "string", "sort": 0, "enable": 0, "create_at": "string", "update_at": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/package-groups/{group_id}'
用户 API / 套餐与交易 / 套餐目录 / 更新套餐组

PUT更新套餐组

PUT /v1/package-groups/{group_id}

以管理员身份更新套餐组。路径中的套餐组 ID 会覆盖请求体中的同名字段;未提供的字段保持原值,至少应提交一个与原值不同的字段。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
group_idpathinteger是要更新的套餐组 ID。3

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring否套餐组名称;传入时不能为空且必须与其他套餐组名称不同。标准套餐(新版)
desstring否套餐组备注;允许传空字符串清空。适用于普通网站
sortinteger否展示排序值;传空值时更新为 100,数值越小越靠前。80
enableinteger enum否是否启用:1 为启用,0 为停用。1

请求体示例

{ "name": "标准套餐(新版)", "des": "适用于普通网站", "sort": 80, "enable": 1 }

响应

HTTP 200

套餐组更新成功。 鉴权或字段校验失败时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package_group-18`、`package_group-6`、`package_group-7`、`package_group-9`、`package_group-11`、`package_group-13`、`package_group-14`、`package_group-15` 或 `package_group-16`。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。更新套餐组成功
oneOf#1.datastring是该操作未返回更新后的套餐组对象。
oneOf#2.codestring是业务错误码。package_group-14
oneOf#2.msgstring是错误原因。数据未更改
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "更新套餐组成功", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"标准套餐(新版)","des":"适用于普通网站","sort":80,"enable":1}' \ 'https://master.example.com/v1/package-groups/{group_id}'
用户 API / 套餐与交易 / 套餐目录 / 查询套餐升级规则

GET查询套餐升级规则

GET /v1/package-ups

分页查询套餐升级规则,按升级包 ID 倒序返回。普通用户仅能看到已启用的规则:未传 `upid` 时只返回未绑定基础套餐的规则,传入 `upid` 时返回未绑定规则及绑定到该用户套餐所用基础套餐的规则。管理员可查看全部,并可用 `enable` 筛选。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger否页码,必须为数字;默认 1。1
limitqueryinteger否每页条数,必须为数字;默认 10。传 0 时不分页。10
enablequeryinteger否仅管理员有效:按是否启用筛选。普通用户始终只查询启用规则。1
upidqueryinteger否仅普通用户使用的用户套餐 ID。传入后依据该用户套餐的基础套餐匹配可用升级规则;未传或为空时仅返回未绑定基础套餐的规则。管理员忽略此参数。101

响应

HTTP 200

查询成功时不含 `msg` 字段;参数或认证错误仍返回 HTTP 200。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.countinteger是筛选后的升级规则总数,未受分页影响。1
oneOf#1.dataarray是当前页升级规则。
oneOf#1.dataarray<object>否当前页升级规则。
oneOf#1.data[].idinteger是升级规则 ID。
oneOf#1.data[].namestring是升级规则名称。
oneOf#1.data[].desstring是升级规则备注。
oneOf#1.data[].typestring enum是可升级的资源类型。traffic | domain | main_domain | http_port | stream_port | custom_cc_rule
oneOf#1.data[].amountinteger是本规则增加的资源数量;自定义 CC 规则类型固定为 1。
oneOf#1.data[].bind_packagestring是可使用该规则的基础套餐 ID 列表,使用英文逗号分隔;空字符串表示不限制基础套餐。
oneOf#1.data[].priceinteger是升级价格,以系统最小货币单位保存。
oneOf#1.data[].create_atstring是创建时间,由数据库日期时间字段序列化返回。
oneOf#1.data[].update_atstring是最后更新时间,由数据库日期时间字段序列化返回。
oneOf#1.data[].enableinteger enum是是否启用:1 为启用,0 为停用。0 | 1
oneOf#1.data[].create_at2string是格式化创建时间,格式为 `YYYY-MM-DD HH:mm:ss`。
oneOf#2.codestring enum是页码/分页条数格式错误、用户套餐不存在或未登录时的业务错误码。package_up-21 | package_up-22 | package_up-26 | login_required
oneOf#2.msgstring是错误原因。upid:101不存在
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "count": 1, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/package-ups'
用户 API / 套餐与交易 / 套餐目录 / 创建套餐升级规则

POST创建套餐升级规则

POST /v1/package-ups

以管理员身份创建套餐升级规则。名称必须唯一;普通资源类型必须提供增加数量,`custom_cc_rule` 类型的数量由服务端强制设为 1。金额以系统最小货币单位保存。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
oneOf#1.namestring是升级规则名称,不能为空且必须唯一。
oneOf#1.desstring否升级规则备注;服务端会进行 XSS 过滤,未传时保存为空字符串。
oneOf#1.typestring enum是要增加的资源类型。traffic | domain | main_domain | http_port | stream_port
oneOf#1.amountinteger是增加的资源数量,必须为非负整数。
oneOf#1.bind_packagestring否可使用该规则的基础套餐 ID 列表,以英文逗号分隔;未传或空字符串表示不限制基础套餐。
oneOf#1.priceinteger是升级价格,必须为非负整数,单位为系统最小货币单位。
oneOf#1.enableinteger enum否是否启用:1 为启用,0 为停用;未传时为 1。0 | 1
oneOf#2.namestring是升级规则名称,不能为空且必须唯一。
oneOf#2.desstring否升级规则备注;服务端会进行 XSS 过滤,未传时保存为空字符串。
oneOf#2.typestring enum是增加自定义 CC 规则数量。custom_cc_rule
oneOf#2.amountinteger否可省略;服务端会忽略传值并固定保存为 1。
oneOf#2.bind_packagestring否可使用该规则的基础套餐 ID 列表,以英文逗号分隔;未传或空字符串表示不限制基础套餐。
oneOf#2.priceinteger是升级价格,必须为非负整数,单位为系统最小货币单位。
oneOf#2.enableinteger enum否是否启用:1 为启用,0 为停用;未传时为 1。0 | 1

请求体示例

{ "name": "string", "des": "string", "type": "string", "amount": 0, "bind_package": "string", "price": 0, "enable": 0 }

响应

HTTP 200

升级规则创建成功,`data` 为新记录的自增 ID。 未登录、维护模式限制、非管理员或字段校验失败时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package_up-29`、`package_up-5`、`package_up-7`、`package_up-8`、`package_up-10`、`package_up-11`、`package_up-12`、`package_up-13`、`package_up-14`、`package_up-15`、`package_up-16`、`package_up-17`、`package_up-18`、`package_up-19`、`package_up-25` 或 `package_up-27`。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。升级包添加成功
oneOf#1.datainteger是新创建升级规则的自增 ID。8
oneOf#2.codestring是业务错误码。package_up-25
oneOf#2.msgstring是错误原因。指定的套餐id:11不存在
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "升级包添加成功", "data": 8 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"string","des":"string","type":"string","amount":0,"bind_package":"string","price":0,"enable":0}' \ 'https://master.example.com/v1/package-ups'
用户 API / 套餐与交易 / 套餐目录 / 删除套餐升级规则

DELETE删除套餐升级规则

DELETE /v1/package-ups/{package_id}

以管理员身份删除一个或多个套餐升级规则。路径参数支持英文逗号分隔多个规则 ID;每条规则必须存在且未被任何用户套餐升级记录引用,任一检查失败都会回滚本次操作。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathstring是一个升级规则 ID,或以英文逗号分隔的多个升级规则 ID。8,9

响应

HTTP 200

升级规则删除成功。 未登录、维护模式限制、非管理员、规则不存在或规则仍在使用时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package_up-28`、`package_up-1` 或 `package_up-2`。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。升级包删除成功
oneOf#1.datastring是该操作未返回已删除规则的数据。
oneOf#2.codestring是业务错误码。package_up-2
oneOf#2.msgstring是错误原因;在用时会包含引用记录 ID。此升级包已经在用,user_package_up id301
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "升级包删除成功", "data": "string" }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/package-ups/{package_id}'
用户 API / 套餐与交易 / 套餐目录 / 获取套餐升级详情

GET获取套餐升级详情

GET /v1/package-ups/{package_id}

按 ID 获取套餐升级规则详情。任何登录用户都可读取启用规则;停用规则仅管理员可读取。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是升级规则 ID。8

响应

HTTP 200

成功、未登录、停用规则无权访问及规则不存在均返回 HTTP 200。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是成功时为空字符串。
oneOf#1.dataobject是升级规则记录。
oneOf#1.data.idinteger是升级规则 ID。
oneOf#1.data.namestring是升级规则名称。
oneOf#1.data.desstring是升级规则备注。
oneOf#1.data.typestring enum是可升级的资源类型。traffic | domain | main_domain | http_port | stream_port | custom_cc_rule
oneOf#1.data.amountinteger是增加的资源数量。
oneOf#1.data.bind_packagestring是可使用该规则的基础套餐 ID 列表,使用英文逗号分隔;空字符串表示不限制。
oneOf#1.data.priceinteger是升级价格,单位为系统最小货币单位。
oneOf#1.data.create_atstring是创建时间,由数据库日期时间字段序列化返回。
oneOf#1.data.update_atstring是最后更新时间,由数据库日期时间字段序列化返回。
oneOf#1.data.enableinteger enum是是否启用:1 为启用,0 为停用。0 | 1
oneOf#2.codestring enum是规则不存在、读取停用规则时非管理员或未登录时的业务错误码。package_up-20 | package_up-30 | login_required
oneOf#2.msgstring是错误原因。需要管理员权限
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "", "data": { "id": 0, "name": "string", "des": "string", "type": "string", "amount": 0, "bind_package": "string", "price": 0, "create_at": "string", "update_at": "string", "enable": 0 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/package-ups/{package_id}'
用户 API / 套餐与交易 / 套餐目录 / 更新套餐升级规则

PUT更新套餐升级规则

PUT /v1/package-ups/{package_id}

以管理员身份更新一条升级规则。请求体必须是 JSON 对象,路径中的规则 ID 会覆盖请求体 ID。服务端每次都会更新 `update_at`,因此空对象也会成功。注意:传入 `type` 会被校验并参与数量处理,但当前服务端不会将新的 `type` 写入数据库。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是要更新的升级规则 ID。8

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring否升级规则名称;传入时不能为空、经 XSS 过滤且必须与其他规则名称不同。增加流量包(新版)
desstring否升级规则备注;传入时经 XSS 过滤,可传空字符串清空。增加月流量额度
typestring enum否资源类型。当前服务端会校验该值,但不会把更新后的类型保存到数据库;传 `custom_cc_rule` 时会把本次的 `amount` 强制设为 1。traffic
amountinteger否增加的资源数量;传入时必须为非负整数。若同时传 `type: custom_cc_rule`,服务端固定保存为 1。200
bind_packagestring否可使用该规则的基础套餐 ID 列表,以英文逗号分隔;传入的每个 ID 必须存在,空字符串可清空绑定限制。11,12
priceinteger否升级价格;传入时必须为非负整数,单位为系统最小货币单位。1200
enableinteger enum否是否启用:1 为启用,0 为停用。1

请求体示例

{ "name": "增加流量包(新版)", "des": "增加月流量额度", "type": "traffic", "amount": 200, "bind_package": "11,12", "price": 1200, "enable": 1 }

响应

HTTP 200

升级规则更新成功。 鉴权、请求体类型或字段校验失败时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package_up-23`、`package_up-29`、`package_up-3`、`package_up-4`、`package_up-5`、`package_up-7`、`package_up-10`、`package_up-11`、`package_up-13`、`package_up-14`、`package_up-15`、`package_up-16`、`package_up-18`、`package_up-19` 或 `package_up-25`。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。更新升级包成功
oneOf#1.datastring是该操作未返回更新后的升级规则对象。
oneOf#2.codestring是业务错误码。package_up-23
oneOf#2.msgstring是错误原因。需要字典格式
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "更新升级包成功", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"增加流量包(新版)","des":"增加月流量额度","type":"traffic","amount":200,"bind_package":"11,12","price":1200,"enable":1}' \ 'https://master.example.com/v1/package-ups/{package_id}'
用户 API / 套餐与交易 / 套餐目录 / 查询套餐列表

GET查询套餐列表

GET /v1/packages

分页查询套餐,按排序值升序返回。普通用户仅能查询已启用的非专属套餐;传 `mine` 时仅查询 `owner` 包含当前用户 ID 的专属套餐。管理员可查看全部,并可按启用状态筛选。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger否页码,必须为数字;默认 1。1
limitqueryinteger否每页条数,必须为数字;默认 10。传 0 时不分页。10
enablequeryinteger否仅管理员有效:按是否启用筛选。普通用户固定只查询启用套餐。1
groupqueryinteger否套餐组 ID;筛选归属该套餐组的套餐。3
region_idqueryinteger否区域 ID;精确筛选套餐所属区域。1
minequerystring否传任意非空值时,仅查询 `owner` 逗号列表包含当前登录用户 ID 的专属套餐;未传时普通用户只查询 `owner` 为空的套餐。1

响应

HTTP 200

查询成功时不含 `msg` 字段;参数或认证错误仍返回 HTTP 200。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.countinteger是筛选后的套餐总数,未受分页影响。1
oneOf#1.dataarray是当前页套餐记录。
oneOf#1.dataarray<object>否当前页套餐记录。
oneOf#1.data[].idinteger否套餐 ID。
oneOf#1.data[].namestring否套餐名称。
oneOf#1.data[].desstring否套餐备注。
oneOf#1.data[].region_idinteger否所属区域 ID。
oneOf#1.data[].region_namestring否所属区域名称。
oneOf#1.data[].node_group_idinteger否主线路组 ID。
oneOf#1.data[].node_group_namestring否主线路组名称。
oneOf#1.data[].backup_node_groupinteger否备用线路组 ID。
oneOf#1.data[].backup_node_group_namestring否备用线路组名称。
oneOf#1.data[].cname_domaininteger否CNAME 域名配置 ID。
oneOf#1.data[].cname_hostname2string否备用 CNAME 主机名。
oneOf#1.data[].cname_modestring否CNAME 模式。
oneOf#1.data[].trafficinteger否套餐流量额度。
oneOf#1.data[].bandwidthstring否带宽限制值。
oneOf#1.data[].connectioninteger否连接数限制。
oneOf#1.data[].domaininteger否可添加域名数量限制。
oneOf#1.data[].main_domaininteger否主域名数量限制。
oneOf#1.data[].http_portinteger否HTTP 端口数量限制。
oneOf#1.data[].stream_portinteger否四层转发端口数量限制。
oneOf#1.data[].custom_cc_ruleinteger enum否是否允许自定义 CC 规则:1 为允许,0 为不允许。0 | 1
oneOf#1.data[].websocketinteger enum否是否支持 WebSocket:1 为支持,0 为不支持。0 | 1
oneOf#1.data[].http3integer enum否是否支持 HTTP/3:1 为支持,0 为不支持。0 | 1
oneOf#1.data[].l2_stateinteger enum否是否启用二层调度能力:1 为启用,0 为停用。0 | 1
oneOf#1.data[].cc_protectstring否CC 防护能力说明。
oneOf#1.data[].ddos_protectstring否DDoS 防护能力说明。
oneOf#1.data[].expirestring否套餐停售或有效期截止时间,由数据库日期时间字段序列化返回。
oneOf#1.data[].expire2string否格式化截止时间,格式为 `YYYY-MM-DD HH:mm:ss`。
oneOf#1.data[].buy_num_limitinteger否可购买数量限制。
oneOf#1.data[].backend_ip_limitstring否源站 IP 限制配置文本。
oneOf#1.data[].id_verifyinteger enum否是否要求实名认证:1 为要求,0 为不要求。0 | 1
oneOf#1.data[].before_exp_days_renewinteger否到期前允许续费的提前天数。
oneOf#1.data[].month_priceinteger否月付价格,单位为系统最小货币单位。
oneOf#1.data[].quarter_priceinteger否季付价格,单位为系统最小货币单位。
oneOf#1.data[].year_priceinteger否年付价格,单位为系统最小货币单位。
oneOf#1.data[].create_atstring否创建时间,由数据库日期时间字段序列化返回。
oneOf#1.data[].create_at2string否格式化创建时间,格式为 `YYYY-MM-DD HH:mm:ss`。
oneOf#1.data[].update_atstring否最后更新时间,由数据库日期时间字段序列化返回。
oneOf#1.data[].sortinteger否展示排序值,数值越小越靠前。
oneOf#1.data[].ownerstring否专属用户 ID 列表,使用英文逗号分隔;空值表示非专属套餐。
oneOf#1.data[].enableinteger enum否是否启用:1 为启用,0 为停用。0 | 1
oneOf#1.data[].groupsstring否套餐所属套餐组 ID 的聚合字符串,使用英文逗号分隔;未分组时为 null。
oneOf#2.codestring enum是页码/分页条数格式错误或未登录时的业务错误码。package-38 | package-39 | login_required
oneOf#2.msgstring是错误原因。page参数格式不正确
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "count": 1, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/packages'
用户 API / 套餐与交易 / 套餐目录 / 创建套餐

POST创建套餐

POST /v1/packages

以管理员身份创建套餐。主线路组必须属于所选区域且至少配置一条启用线路;CNAME 域名必须存在;套餐名称必须唯一,并必须选择至少一个套餐组。创建成功后会同步该区域的 OpenResty 配置。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring是套餐名称;不能为空、经 XSS 过滤且必须唯一。标准套餐
desstring否套餐备注;经 XSS 过滤,未传时保存为空字符串。适用于普通网站
cc_protectstring否CC 防护能力说明;经 XSS 过滤,未传时为空字符串。基础防护
ddos_protectstring否DDoS 防护能力说明;经 XSS 过滤,未传时为空字符串。基础防护
region_idinteger是套餐所属区域 ID,必须提供数字。1
node_group_idinteger是主线路组 ID;必须存在、属于 `region_id`,且至少有一条启用的解析线路。2
backup_node_groupinteger否备用线路组 ID;可省略或传空值。传入时必须存在、属于同一区域、已配置启用解析线路,且不得与主线路组相同。4
cname_domaininteger是CNAME 域名配置 ID,必须存在。1
cname_hostname2string否备用 CNAME 主机名;会转换为小写,非空时必须是合法主机名。未传时为空字符串。backup.cdn.example.invalid
cname_modestring enum否CNAME 使用模式;未传时为 `site`。site
trafficinteger否流量额度;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。100
bandwidthstring否带宽限制;可为 `-1` 表示不限,或数字加 `Mbps`/`Gbps`,如 `10Mbps`。未传时为 `-1`。10Mbps
connectioninteger否连接数限制;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。1000
domaininteger否可添加域名数量;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。10
main_domaininteger否可添加主域名数量;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。1
http_portinteger否HTTP 端口数量;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。2
stream_portinteger否四层转发端口数量;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。0
custom_cc_ruleinteger enum否是否允许自定义 CC 规则:1 为允许,0 为不允许;未传时为 0。1
websocketinteger enum否是否支持 WebSocket:1 为支持,0 为不支持;未传时为 0。1
http3integer enum否是否支持 HTTP/3:1 为支持,0 为不支持;未传时为 0。1
l2_stateinteger enum否是否启用二层调度能力:1 为启用,0 为停用;未传时为 0。0
expirestring否套餐截止时间,非空时必须为合法日期时间;传空值或未传时保存为 null。2026-12-31 23:59:59
buy_num_limitinteger否单用户购买数量限制;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。1
backend_ip_limitstring否源站 IP/CIDR 限制列表,每行一个合法 IPv4/IPv6 CIDR;未传时保存为 null。192.0.2.0/24 2001:db8::/32
id_verifyinteger enum否是否要求实名认证:1 为要求,0 为不要求;未传时为 0。0
before_exp_days_renewinteger否到期前允许续费的提前天数;非负整数表示天数,`-1` 表示不限,未传时为 `-1`。7
sortinteger否展示排序值;未传或传空值时为 100,数值越小越靠前。100
ownerstring否专属用户 ID 列表,以英文逗号分隔;每个 ID 必须对应现有用户。未传时为 null,表示非专属套餐。12,13
month_priceinteger是月付价格,必须为非负整数,单位为系统最小货币单位。1000
quarter_priceinteger是季付价格,必须为非负整数,单位为系统最小货币单位。2700
year_priceinteger是年付价格,必须为非负整数,单位为系统最小货币单位。10000
enableinteger enum否是否启用:1 为启用,0 为停用;未传时为 1。1
groupsstring是套餐组 ID 列表,以英文逗号分隔;不能为空,列表中的每一项必须是数字。3,4

请求体示例

{ "name": "标准套餐", "des": "适用于普通网站", "cc_protect": "基础防护", "ddos_protect": "基础防护", "region_id": 1, "node_group_id": 2, "backup_node_group": 4, "cname_domain": 1, "cname_hostname2": "backup.cdn.example.invalid", "cname_mode": "site", "traffic": 100, "bandwidth": "10Mbps", "connection": 1000, "domain": 10, "main_domain": 1, "http_port": 2, "stream_port": 0, "custom_cc_rule": 1, "websocket": 1, "http3": 1, "l2_state": 0, "expire": "2026-12-31 23:59:59", "buy_num_limit": 1, "backend_ip_limit": "192.0.2.0/24\n2001:db8::/32", "id_verify": 0, "before_exp_days_renew": 7, "sort": 100, "owner": "12,13", "month_price": 1000, "quarter_price": 2700, "year_price": 10000, "enable": 1, "groups": "3,4" }

响应

HTTP 200

套餐创建成功,`data` 为新套餐的自增 ID。 未登录、维护模式限制、非管理员或任一关联/字段校验失败时仍返回 HTTP 200。错误码以 `package-` 为前缀,例如:名称或价格必填/格式错误、区域和线路组不匹配、线路未配置解析、CNAME 不存在、套餐组未选择、备用线路组非法、源站 IP/CIDR 格式错误、专属用户不存在等。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。套餐添加成功
oneOf#1.datainteger是新创建套餐的自增 ID。11
oneOf#2.codestring是业务错误码,可能为 `login_required`、`maintain`、`package-91` 或具体参数校验的 `package-*` 代码。package-72
oneOf#2.msgstring是错误原因。指定的线路组不属于当前所选区域
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "套餐添加成功", "data": 11 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"标准套餐","des":"适用于普通网站","cc_protect":"基础防护","ddos_protect":"基础防护","region_id":1,"node_group_id":2,"backup_node_group":4,"cname_domain":1,"cname_hostname2":"backup.cdn.example.invalid","cname_mode":"site","traffic":100,"bandwidth":"10Mbps","connection":1000,"domain":10,"main_domain":1,"http_port":2,"stream_port":0,"custom_cc_rule":1,"websocket":1,"http3":1,"l2_state":0,"expire":"2026-12-31 23:59:59","buy_num_limit":1,"backend_ip_limit":"192.0.2.0/24\n2001:db8::/32","id_verify":0,"before_exp_days_renew":7,"sort":100,"owner":"12,13","month_price":1000,"quarter_price":2700,"year_price":10000,"enable":1,"groups":"3,4"}' \ 'https://master.example.com/v1/packages'
用户 API / 套餐与交易 / 套餐目录 / 批量更新套餐

PUT批量更新套餐

PUT /v1/packages

以管理员身份批量更新套餐。请求体必须为 JSON 数组,每个元素必须包含现有套餐 ID;未提供的字段保持原值。服务端每次都会更新各套餐的 `update_at`,即仅传 ID 也会成功。可选 `sync-item` 用于将指定配置同步到使用该套餐的用户套餐、网站和四层转发。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

要更新的套餐列表;每个元素独立校验并在同一事务中处理。

字段类型必填说明示例
(root)array<object>否要更新的套餐列表;每个元素独立校验并在同一事务中处理。
[].idinteger是要更新的现有套餐 ID。11
[].namestring否套餐名称;传入时经 XSS 过滤,不能为空且必须唯一。
[].desstring否套餐备注;传入时经 XSS 过滤,空字符串可清空。
[].cc_protectstring否CC 防护能力说明;传入时经 XSS 过滤。
[].ddos_protectstring否DDoS 防护能力说明;传入时经 XSS 过滤。
[].region_idinteger否所属区域 ID;若同时更新主或备用线路组,必须与其所属区域一致。
[].node_group_idinteger否主线路组 ID;传入时必须存在并属于所选区域。
[].backup_node_groupinteger否备用线路组 ID;空值可清除。非空时必须存在、属于同一区域、配置启用解析线路且不同于主线路组。
[].cname_domaininteger否CNAME 域名配置 ID;传入时必须存在。
[].cname_hostname2string否备用 CNAME 主机名;会转换为小写,非空时必须为合法主机名。
[].cname_modestring enum否CNAME 使用模式。site | package
[].trafficinteger否流量额度;非负整数为限制值,`-1` 表示不限。
[].bandwidthstring否带宽限制;可为 `-1`,或数字加 `Mbps`/`Gbps`,如 `10Mbps`。
[].connectioninteger否连接数限制;非负整数为限制值,`-1` 表示不限。
[].domaininteger否域名数量限制;非负整数为限制值,`-1` 表示不限。
[].main_domaininteger否主域名数量限制;非负整数为限制值,`-1` 表示不限。
[].http_portinteger否HTTP 端口数量限制;非负整数为限制值,`-1` 表示不限。
[].stream_portinteger否四层转发端口数量限制;非负整数为限制值,`-1` 表示不限。
[].custom_cc_ruleinteger enum否是否允许自定义 CC 规则:1 为允许,0 为不允许。0 | 1
[].websocketinteger enum否是否支持 WebSocket:1 为支持,0 为不支持。0 | 1
[].http3integer enum否是否支持 HTTP/3:1 为支持,0 为不支持。0 | 1
[].l2_stateinteger enum否是否启用二层调度能力:1 为启用,0 为停用。0 | 1
[].expirestring否套餐截止时间;非空时必须为合法日期时间,空值可清除。
[].buy_num_limitinteger否单用户购买数量限制;非负整数为限制值,`-1` 表示不限。
[].backend_ip_limitstring否源站 IP/CIDR 限制列表,每行一个合法 IPv4/IPv6 CIDR;空字符串可清空。
[].id_verifyinteger enum否是否要求实名认证:1 为要求,0 为不要求。0 | 1
[].before_exp_days_renewinteger否到期前允许续费的提前天数;非负整数表示天数,`-1` 表示不限。
[].sortinteger否展示排序值;传空值时更新为 100。
[].ownerstring否专属用户 ID 列表,以英文逗号分隔;每项必须对应现有用户,空字符串可清空。
[].month_priceinteger否月付价格;传入时必须为非负整数,单位为系统最小货币单位。
[].quarter_priceinteger否季付价格;传入时必须为非负整数,单位为系统最小货币单位。
[].year_priceinteger否年付价格;传入时必须为非负整数,单位为系统最小货币单位。
[].enableinteger enum否是否启用:1 为启用,0 为停用。0 | 1
[].groupsstring否替换套餐所属套餐组的数字 ID 列表,以英文逗号分隔。省略时保留既有套餐组。
[].sync-itemstring否要同步到使用该套餐的用户套餐的字段列表,以英文逗号分隔。仅支持 `name`、`node_group_id`、`cname_domain`、`cname_mode`、`traffic`、`domain`、`main_domain`、`http_port`、`stream_port`、`custom_cc_rule`、`websocket`、`month_price`、`quarter_price`、`year_price`、`bandwidth`、`connection`、`http3`。

请求体示例

[ { "id": 11, "name": "string", "des": "string", "cc_protect": "string", "ddos_protect": "string", "region_id": 0, "node_group_id": 0, "backup_node_group": 0, "cname_domain": 0, "cname_hostname2": "string", "cname_mode": "string", "traffic": 0, "bandwidth": "string", "connection": 0, "domain": 0, "main_domain": 0, "http_port": 0, "stream_port": 0, "custom_cc_rule": 0, "websocket": 0, "http3": 0, "l2_state": 0, "expire": "string", "buy_num_limit": 0, "backend_ip_limit": "string", "id_verify": 0, "before_exp_days_renew": 0, "sort": 0, "owner": "string", "month_price": 0, "quarter_price": 0, "year_price": 0, "enable": 0, "groups": "string", "sync-item": "string" } ]

响应

HTTP 200

批量更新成功。 未登录、维护模式限制、非管理员、请求体不是数组或任何套餐的关联/字段校验失败时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package-41`、`package-91` 及具体校验的 `package-*` 代码。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。更新套餐成功
oneOf#1.datastring是该操作未返回更新后的套餐对象。
oneOf#2.codestring是业务错误码。package-41
oneOf#2.msgstring是错误原因。需要列表格式
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "更新套餐成功", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '[{"id":11,"name":"string","des":"string","cc_protect":"string","ddos_protect":"string","region_id":0,"node_group_id":0,"backup_node_group":0,"cname_domain":0,"cname_hostname2":"string","cname_mode":"string","traffic":0,"bandwidth":"string","connection":0,"domain":0,"main_domain":0,"http_port":0,"stream_port":0,"custom_cc_rule":0,"websocket":0,"http3":0,"l2_state":0,"expire":"string","buy_num_limit":0,"backend_ip_limit":"string","id_verify":0,"before_exp_days_renew":0,"sort":0,"owner":"string","month_price":0,"quarter_price":0,"year_price":0,"enable":0,"groups":"string","sync-item":"string"}]' \ 'https://master.example.com/v1/packages'
用户 API / 套餐与交易 / 套餐目录 / 删除套餐

DELETE删除套餐

DELETE /v1/packages/{package_id}

以管理员身份删除一个或多个套餐。路径参数支持英文逗号分隔多个套餐 ID;每条套餐必须存在且未被任何用户套餐引用。删除时会同时移除套餐与套餐组的关联,任一检查失败都会回滚本次操作。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathstring是一个套餐 ID,或以英文逗号分隔的多个套餐 ID。11,12

响应

HTTP 200

套餐删除成功。服务端会将请求的 `package_id` 原样写入 `msg`,而非返回固定成功文案。 未登录、维护模式限制、非管理员、ID 格式错误、套餐不存在或套餐仍被用户套餐使用时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package-90`、`package-1`、`package-2` 或 `package-3`。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是原样回显请求中的套餐 ID 字符串。11,12
oneOf#1.datastring是该操作未返回已删除套餐的数据。
oneOf#2.codestring是业务错误码。package-3
oneOf#2.msgstring是错误原因;套餐被使用时会包含引用的用户套餐 ID。用户套餐101在用此套餐,不允许删除
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "11,12", "data": "string" }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/packages/{package_id}'
用户 API / 套餐与交易 / 套餐目录 / 获取套餐详情

GET获取套餐详情

GET /v1/packages/{package_id}

获取一条套餐记录。普通用户只能读取启用套餐,管理员可读取停用套餐。传入 `duration` 时,服务端会按当前登录用户的有效折扣和可用优惠码试算该周期价格,并在返回数据中附加价格字段。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是套餐 ID。11
durationquerystring否购买周期。传入后触发当前用户的价格试算。month
coupon_codequerystring否优惠码;仅在传入 `duration` 时用于价格试算。存在有效用户折扣时不会与优惠码叠加,原因通过响应中的 `err` 返回。REDACTED_COUPON

响应

HTTP 200

成功、未登录、套餐不存在、普通用户查询停用套餐及周期参数非法均返回 HTTP 200。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是成功时为空字符串。
oneOf#1.dataobject是套餐记录;指定 `duration` 时会额外包含 `orgin_price`、`new_price` 和 `err`。
oneOf#1.data.idinteger否套餐 ID。
oneOf#1.data.namestring否套餐名称。
oneOf#1.data.desstring否套餐备注。
oneOf#1.data.region_idinteger否所属区域 ID。
oneOf#1.data.node_group_idinteger否主线路组 ID。
oneOf#1.data.backup_node_groupinteger否备用线路组 ID。
oneOf#1.data.cname_domaininteger否CNAME 域名配置 ID。
oneOf#1.data.cname_hostname2string否备用 CNAME 主机名。
oneOf#1.data.cname_modestring否CNAME 使用模式。
oneOf#1.data.trafficinteger否流量额度;`-1` 表示不限。
oneOf#1.data.bandwidthstring否带宽限制值;`-1` 表示不限。
oneOf#1.data.connectioninteger否连接数限制;`-1` 表示不限。
oneOf#1.data.domaininteger否域名数量限制;`-1` 表示不限。
oneOf#1.data.main_domaininteger否主域名数量限制;`-1` 表示不限。
oneOf#1.data.http_portinteger否HTTP 端口数量限制;`-1` 表示不限。
oneOf#1.data.stream_portinteger否四层转发端口数量限制;`-1` 表示不限。
oneOf#1.data.custom_cc_ruleinteger enum否是否允许自定义 CC 规则:1 为允许。0 | 1
oneOf#1.data.websocketinteger enum否是否支持 WebSocket:1 为支持。0 | 1
oneOf#1.data.http3integer enum否是否支持 HTTP/3:1 为支持。0 | 1
oneOf#1.data.l2_stateinteger enum否是否启用二层调度能力:1 为启用。0 | 1
oneOf#1.data.cc_protectstring否CC 防护能力说明。
oneOf#1.data.ddos_protectstring否DDoS 防护能力说明。
oneOf#1.data.expirestring否套餐截止时间,由数据库日期时间字段序列化返回。
oneOf#1.data.buy_num_limitinteger否单用户购买数量限制;`-1` 表示不限。
oneOf#1.data.backend_ip_limitstring否源站 IP/CIDR 限制配置文本。
oneOf#1.data.id_verifyinteger enum否是否要求实名认证:1 为要求。0 | 1
oneOf#1.data.before_exp_days_renewinteger否到期前允许续费的提前天数;`-1` 表示不限。
oneOf#1.data.month_priceinteger否月付价格,单位为系统最小货币单位。
oneOf#1.data.quarter_priceinteger否季付价格,单位为系统最小货币单位。
oneOf#1.data.year_priceinteger否年付价格,单位为系统最小货币单位。
oneOf#1.data.create_atstring否创建时间,由数据库日期时间字段序列化返回。
oneOf#1.data.update_atstring否最后更新时间,由数据库日期时间字段序列化返回。
oneOf#1.data.sortinteger否展示排序值。
oneOf#1.data.ownerstring否专属用户 ID 列表,使用英文逗号分隔。
oneOf#1.data.enableinteger enum否是否启用:1 为启用,0 为停用。0 | 1
oneOf#1.data.orgin_priceinteger否仅传 `duration` 时返回:所选周期的原始价格,单位为系统最小货币单位。
oneOf#1.data.new_priceinteger否仅传 `duration` 时返回:应用有效折扣或优惠码后的所选周期试算价格,单位为系统最小货币单位。
oneOf#1.data.errstring否仅传 `duration` 时返回:优惠码或折扣不能应用时的原因;无错误时为 null。
oneOf#2.codestring enum是周期参数非法、套餐不存在、普通用户无权查询停用套餐或未登录时的业务错误码。package-83 | package-36 | package-37 | login_required
oneOf#2.msgstring是错误原因。无权限查询
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "", "data": { "id": 0, "name": "string", "des": "string", "region_id": 0, "node_group_id": 0, "backup_node_group": 0, "cname_domain": 0, "cname_hostname2": "string", "cname_mode": "string", "traffic": 0, "bandwidth": "string", "connection": 0, "domain": 0, "main_domain": 0, "http_port": 0, "stream_port": 0, "custom_cc_rule": 0, "websocket": 0, "http3": 0, "l2_state": 0, "cc_protect": "string", "ddos_protect": "string", "expire": "string", "buy_num_limit": 0, "backend_ip_limit": "string", "id_verify": 0, "before_exp_days_renew": 0, "month_price": 0, "quarter_price": 0, "year_price": 0, "create_at": "string", "update_at": "string", "sort": 0, "owner": "string", "enable": 0, "orgin_price": 0, "new_price": 0, "err": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/packages/{package_id}'
用户 API / 套餐与交易 / 套餐目录 / 更新指定套餐

PUT更新指定套餐

PUT /v1/packages/{package_id}

以管理员身份更新一条套餐。请求体必须为 JSON 对象;路径中的套餐 ID 会覆盖请求体中的 ID。未提供的字段保持原值,且服务端每次都会更新 `update_at`,因此空对象也会成功。`sync-item` 可将指定配置同步到使用该套餐的用户套餐、网站和四层转发。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是要更新的套餐 ID。11

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring否套餐名称;传入时经 XSS 过滤,不能为空且必须唯一。
desstring否套餐备注;传入时经 XSS 过滤,空字符串可清空。
cc_protectstring否CC 防护能力说明;传入时经 XSS 过滤。
ddos_protectstring否DDoS 防护能力说明;传入时经 XSS 过滤。
region_idinteger否所属区域 ID;若更新线路组,必须与其所属区域一致。
node_group_idinteger否主线路组 ID;传入时必须存在并属于所选区域。
backup_node_groupinteger否备用线路组 ID;空值可清除。非空时必须存在、属于同一区域、配置启用解析线路且不同于主线路组。
cname_domaininteger否CNAME 域名配置 ID;传入时必须存在。
cname_hostname2string否备用 CNAME 主机名;会转换为小写,非空时必须为合法主机名。
cname_modestring enum否CNAME 使用模式。site | package
trafficinteger否流量额度;非负整数为限制值,`-1` 表示不限。
bandwidthstring否带宽限制;可为 `-1`,或数字加 `Mbps`/`Gbps`,如 `10Mbps`。
connectioninteger否连接数限制;非负整数为限制值,`-1` 表示不限。
domaininteger否域名数量限制;非负整数为限制值,`-1` 表示不限。
main_domaininteger否主域名数量限制;非负整数为限制值,`-1` 表示不限。
http_portinteger否HTTP 端口数量限制;非负整数为限制值,`-1` 表示不限。
stream_portinteger否四层转发端口数量限制;非负整数为限制值,`-1` 表示不限。
custom_cc_ruleinteger enum否是否允许自定义 CC 规则:1 为允许,0 为不允许。0 | 1
websocketinteger enum否是否支持 WebSocket:1 为支持,0 为不支持。0 | 1
http3integer enum否是否支持 HTTP/3:1 为支持,0 为不支持。0 | 1
l2_stateinteger enum否是否启用二层调度能力:1 为启用,0 为停用。0 | 1
expirestring否套餐截止时间;非空时必须为合法日期时间,空值可清除。
buy_num_limitinteger否单用户购买数量限制;非负整数为限制值,`-1` 表示不限。
backend_ip_limitstring否源站 IP/CIDR 限制列表,每行一个合法 IPv4/IPv6 CIDR;空字符串可清空。
id_verifyinteger enum否是否要求实名认证:1 为要求,0 为不要求。0 | 1
before_exp_days_renewinteger否到期前允许续费的提前天数;非负整数表示天数,`-1` 表示不限。
sortinteger否展示排序值;传空值时更新为 100。
ownerstring否专属用户 ID 列表,以英文逗号分隔;每项必须对应现有用户,空字符串可清空。
month_priceinteger否月付价格;传入时必须为非负整数,单位为系统最小货币单位。
quarter_priceinteger否季付价格;传入时必须为非负整数,单位为系统最小货币单位。
year_priceinteger否年付价格;传入时必须为非负整数,单位为系统最小货币单位。
enableinteger enum否是否启用:1 为启用,0 为停用。0 | 1
groupsstring否替换套餐所属套餐组的数字 ID 列表,以英文逗号分隔;省略时保留既有套餐组。
sync-itemstring否要同步到使用该套餐的用户套餐的字段列表,以英文逗号分隔。仅支持 `name`、`node_group_id`、`cname_domain`、`cname_mode`、`traffic`、`domain`、`main_domain`、`http_port`、`stream_port`、`custom_cc_rule`、`websocket`、`month_price`、`quarter_price`、`year_price`、`bandwidth`、`connection`、`http3`。

请求体示例

{ "name": "string", "des": "string", "cc_protect": "string", "ddos_protect": "string", "region_id": 0, "node_group_id": 0, "backup_node_group": 0, "cname_domain": 0, "cname_hostname2": "string", "cname_mode": "string", "traffic": 0, "bandwidth": "string", "connection": 0, "domain": 0, "main_domain": 0, "http_port": 0, "stream_port": 0, "custom_cc_rule": 0, "websocket": 0, "http3": 0, "l2_state": 0, "expire": "string", "buy_num_limit": 0, "backend_ip_limit": "string", "id_verify": 0, "before_exp_days_renew": 0, "sort": 0, "owner": "string", "month_price": 0, "quarter_price": 0, "year_price": 0, "enable": 0, "groups": "string", "sync-item": "string" }

响应

HTTP 200

套餐更新成功。 未登录、维护模式限制、非管理员、请求体不是对象或任何关联/字段校验失败时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package-40`、`package-91` 及具体校验的 `package-*` 代码。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。更新套餐成功
oneOf#1.datastring是该操作未返回更新后的套餐对象。
oneOf#2.codestring是业务错误码。package-40
oneOf#2.msgstring是错误原因。需要字典格式
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "更新套餐成功", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"string","des":"string","cc_protect":"string","ddos_protect":"string","region_id":0,"node_group_id":0,"backup_node_group":0,"cname_domain":0,"cname_hostname2":"string","cname_mode":"string","traffic":0,"bandwidth":"string","connection":0,"domain":0,"main_domain":0,"http_port":0,"stream_port":0,"custom_cc_rule":0,"websocket":0,"http3":0,"l2_state":0,"expire":"string","buy_num_limit":0,"backend_ip_limit":"string","id_verify":0,"before_exp_days_renew":0,"sort":0,"owner":"string","month_price":0,"quarter_price":0,"year_price":0,"enable":0,"groups":"string","sync-item":"string"}' \ 'https://master.example.com/v1/packages/{package_id}'
用户 API / 套餐与交易 / 用户套餐

用户套餐

当前用户套餐、用量和升级。

接口列表

GET
/v1/user-package/{package_id}/upgrades
查询套餐升级选项 — 分页查询指定用户套餐已购买的升级包。普通用户只能查询自己的用户套餐;管理员可查询任意用户套餐。结果按升级记录 ID 倒序返回。
POST
/v1/user-package/{package_id}/upgrades
创建套餐升级 — 为指定用户套餐购买或增加升级包数量。请求体必须是对象。普通用户只能操作自己的套餐:系统会校验升级包是否绑定当前基础套餐、套餐剩余时间不少于一天,并按剩余天数、可
PUT
/v1/user-package/{package_id}/upgrades
更新套餐升级 — 调整指定用户套餐中已购买升级包的数量。请求体必须为对象。普通用户仅能操作自己的套餐,且只能把已存在升级包的数量减少到大于 0 且小于当前数量的值;减少后系统会校
DELETE
/v1/user-package/{package_id}/upgrades/{package_up_id}
删除套餐升级 — 从指定用户套餐移除一个升级包。普通用户只能操作自己的套餐;删除前会检查移除后流量、域名、主域名、HTTP/转发端口和自定义 CC 规则等已用资源是否仍有足够额度
GET
/v1/user-package/{package_id}/upgrades/{package_up_id}
获取套餐升级详情 — 试算指定用户套餐购买升级包的价格。服务端按套餐剩余天数、当前用户组适用折扣和请求数量计算原月价、折后月价、原价及实付价;套餐已过期或剩余不足一天时不能试算。
GET
/v1/user-package/{package_id}/usage
查询套餐用量 — 查询指定用户套餐当前已使用的域名、主域名、HTTP 非标准端口、四层转发端口和流量。普通用户只能查询自己的套餐;管理员可查询任意用户套餐。
GET
/v1/user-packages
查询用户套餐 — 分页查询用户已购买的基础套餐。普通用户只能查询自己的套餐;管理员可按用户、套餐、到期时间、CNAME、流量超额和启用状态筛选。默认按 ID 倒序,可按到期时间升
POST
/v1/user-packages
创建用户套餐 — 购买并创建一个用户套餐。普通用户为自己购买时会校验套餐可购资格、购买次数、实名认证、套餐状态,并按 `duration`、可用折扣和优惠码计算价格后扣除余额、创
DELETE
/v1/user-packages/{package_id}
删除指定用户套餐 — 删除一个用户套餐及其已购买的升级包。普通用户只能删除自己的套餐。默认删除模式要求套餐没有关联网站和四层转发;传入 `force` 会同时删除关联网站、四层转发及
GET
/v1/user-packages/{package_id}
获取用户套餐详情 — 获取用户套餐详情。可选传入 `duration` 试算续费价格,或传入 `to_package` 试算更换至另一基础套餐的差价;可同时传入优惠码参与续费价格计算
PUT
/v1/user-packages/{package_id}
更新指定用户套餐 — 更新一个已购买套餐的名称、线路、CNAME、资源额度、开关或到期时间,也可通过 `duration` 为套餐续费。普通用户只能更新自己的套餐中无需管理员权限的字
用户 API / 套餐与交易 / 用户套餐 / 查询套餐升级选项

GET查询套餐升级选项

GET /v1/user-package/{package_id}/upgrades

分页查询指定用户套餐已购买的升级包。普通用户只能查询自己的用户套餐;管理员可查询任意用户套餐。结果按升级记录 ID 倒序返回。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是用户套餐 ID;必须存在且当前用户有权限查看。8
pagequeryinteger否页码,必须为数字;未传时为 1。1
limitqueryinteger否每页数量,必须为数字;未传时为 10,传 0 表示不分页。10

响应

HTTP 200

请求已被处理。成功时返回升级包记录列表和总数;套餐无权限、页码或每页数量格式错误时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
countinteger是该用户套餐已购买升级包记录总数。1
dataarray是用户套餐升级包记录。
dataarray<object>否用户套餐升级包记录。
data[].idinteger是用户套餐升级记录 ID。
data[].uidinteger是归属用户 ID。
data[].user_packageinteger是用户套餐 ID。
data[].package_upinteger是升级包定义 ID。
data[].amountinteger是当前购买数量。
data[].package_up_namestring是升级包名称。
data[].typestring是升级资源类型,例如 traffic、domain、http_port。
data[].package_up_amountinteger是每单位升级包提供的资源数量。

响应示例

{ "code": 0, "count": 1, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-package/{package_id}/upgrades'
用户 API / 套餐与交易 / 用户套餐 / 创建套餐升级

POST创建套餐升级

POST /v1/user-package/{package_id}/upgrades

为指定用户套餐购买或增加升级包数量。请求体必须是对象。普通用户只能操作自己的套餐:系统会校验升级包是否绑定当前基础套餐、套餐剩余时间不少于一天,并按剩余天数、可用折扣和数量计算价格后从账户余额扣款,同时创建已付款订单。管理员操作时不执行该余额扣款流程。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是要升级的用户套餐 ID,必须存在且当前用户有权限操作。8

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
package_upinteger是必填。升级包定义 ID,必须存在。普通用户购买时,若升级包绑定基础套餐,当前用户套餐必须在绑定范围内。3
amountinteger否购买数量,必须为数字;未传时为 1。若已有同一升级包,会在当前数量上累加。2

请求体示例

{ "package_up": 3, "amount": 2 }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“升级包添加成功”、`data` 为 null;套餐或升级包不存在、权限不足、套餐到期、余额不足或升级包不适用时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。升级包添加成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "升级包添加成功", "data": null }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"package_up":3,"amount":2}' \ 'https://master.example.com/v1/user-package/{package_id}/upgrades'
用户 API / 套餐与交易 / 用户套餐 / 更新套餐升级

PUT更新套餐升级

PUT /v1/user-package/{package_id}/upgrades

调整指定用户套餐中已购买升级包的数量。请求体必须为对象。普通用户仅能操作自己的套餐,且只能把已存在升级包的数量减少到大于 0 且小于当前数量的值;减少后系统会校验流量、域名、端口及自定义 CC 规则等已用资源是否仍有足够额度。管理员不受普通用户的资源减少限制。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是要调整的用户套餐 ID,必须存在且当前用户有权限操作。8

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
package_upinteger是必填。要调整的升级包定义 ID,必须存在且已关联当前用户套餐。3
amountinteger是必填。调整后的总数量。普通用户必须小于当前数量且大于 0;管理员可按实现规则调整。1

请求体示例

{ "package_up": 3, "amount": 1 }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“升级包修改成功”、`data` 为 null;请求体格式、套餐、升级包、数量、权限或资源余量不符合要求时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。升级包修改成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "升级包修改成功", "data": null }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"package_up":3,"amount":1}' \ 'https://master.example.com/v1/user-package/{package_id}/upgrades'
用户 API / 套餐与交易 / 用户套餐 / 删除套餐升级

DELETE删除套餐升级

DELETE /v1/user-package/{package_id}/upgrades/{package_up_id}

从指定用户套餐移除一个升级包。普通用户只能操作自己的套餐;删除前会检查移除后流量、域名、主域名、HTTP/转发端口和自定义 CC 规则等已用资源是否仍有足够额度。管理员不执行该普通用户资源余量检查。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是用户套餐 ID,必须存在且当前用户有权限操作。8
package_up_idpathinteger是要移除的升级包定义 ID,必须存在。3

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“升级包删除成功”、`data` 为 null;套餐或升级包不存在、无权限、或移除后资源不足时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。升级包删除成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "升级包删除成功", "data": null }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-package/{package_id}/upgrades/{package_up_id}'
用户 API / 套餐与交易 / 用户套餐 / 获取套餐升级详情

GET获取套餐升级详情

GET /v1/user-package/{package_id}/upgrades/{package_up_id}

试算指定用户套餐购买升级包的价格。服务端按套餐剩余天数、当前用户组适用折扣和请求数量计算原月价、折后月价、原价及实付价;套餐已过期或剩余不足一天时不能试算。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是用户套餐 ID。8
package_up_idpathinteger是要试算的升级包定义 ID。3
amountqueryinteger否试算数量;未传时为 1。该值参与价格计算。2

响应

HTTP 200

请求已被处理。成功时 `data` 为按剩余天数计算的价格试算结果;套餐已过期或套餐剩余时间不足一天时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是成功时为空字符串,失败时为错误说明。
dataobject是升级包价格试算结果。
data.orgin_month_pricenumber是升级包原月价。
data.new_month_pricenumber是应用当前用户可用折扣后的月价。
data.orgin_pricenumber是按剩余天数和数量计算的原始应付金额。
data.pricenumber是按折后月价、剩余天数和数量计算的实际应付金额。
data.daysinteger是用于计费的套餐剩余天数;超过半天按一天计。
data.amountinteger是参与本次试算的数量。

响应示例

{ "code": 0, "msg": "", "data": { "orgin_month_price": 0, "new_month_price": 0, "orgin_price": 0, "price": 0, "days": 0, "amount": 0 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-package/{package_id}/upgrades/{package_up_id}'
用户 API / 套餐与交易 / 用户套餐 / 查询套餐用量

GET查询套餐用量

GET /v1/user-package/{package_id}/usage

查询指定用户套餐当前已使用的域名、主域名、HTTP 非标准端口、四层转发端口和流量。普通用户只能查询自己的套餐;管理员可查询任意用户套餐。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是要查询用量的用户套餐 ID,必须存在且当前用户有权限查看。8

响应

HTTP 200

请求已被处理。成功时返回套餐资源用量;套餐不存在或无权限时仍返回 HTTP 200。该接口成功响应不包含 `msg` 或 `count` 字段。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
dataobject是用户套餐当前资源用量。
data.domain_usageinteger是已使用域名数量。
data.main_domain_usageinteger是已使用主域名数量。
data.http_port_usageinteger是已使用 HTTP 非标准端口数量。
data.stream_port_usageinteger是已使用四层转发端口数量。
data.traffic_usageinteger是已使用流量,单位由服务端用量统计函数确定。

响应示例

{ "code": 0, "data": { "domain_usage": 0, "main_domain_usage": 0, "http_port_usage": 0, "stream_port_usage": 0, "traffic_usage": 0 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-package/{package_id}/usage'
用户 API / 套餐与交易 / 用户套餐 / 查询用户套餐

GET查询用户套餐

GET /v1/user-packages

分页查询用户已购买的基础套餐。普通用户只能查询自己的套餐;管理员可按用户、套餐、到期时间、CNAME、流量超额和启用状态筛选。默认按 ID 倒序,可按到期时间升序。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger否页码,必须为数字;未传时为 1。1
limitqueryinteger否每页数量,必须为数字;未传时为 10,传 0 表示不分页。10
uidqueryinteger否管理员可选。按套餐归属用户 ID 筛选;普通用户不能借此查看其他用户。12
expirequeryinteger否按即将到期筛选:返回结束时间早于当前时间加此天数的套餐。7
user_packagequerystring否按用户套餐 ID 或套餐名称包含文本筛选。8
base_packagequeryinteger否按基础套餐定义 ID 筛选。2
cname_hostnamequerystring否按套餐 CNAME 主机名精确筛选。demo.example.invalid
order_byquerystring否排序字段:`id` 为 ID 倒序,`end_at` 为到期时间升序。end_at
traffic_exceedqueryinteger否按流量超额状态筛选。1
enablequeryinteger否按套餐启用状态筛选。1

响应

HTTP 200

请求已被处理。成功时返回用户套餐列表和总数;页码、每页数量、uid 或排序字段无效时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
countinteger是符合筛选条件的用户套餐总数。1
dataarray是用户套餐列表。
dataarray<object>否用户套餐列表。
data[].idinteger是用户套餐 ID。
data[].uidinteger是归属用户 ID。
data[].user_namestring否归属用户名。
data[].namestring否用户套餐名称。
data[].user_package_namestring否用户套餐名称的别名。
data[].packageinteger是基础套餐定义 ID。
data[].package_namestring否基础套餐名称。
data[].start_at2string是套餐生效时间。
data[].end_at2string是套餐到期时间。
data[].traffic_usageinteger否已使用流量。
data[].traffic_upgradeinteger否已购买流量升级包带来的总增量。
data[].traffic_exceedinteger否是否流量超额。
data[].enableinteger enum是套餐启用状态。0 | 1
data[].enable_ipv6integer enum否是否启用 IPv6。0 | 1
data[].cname_hostnamestring否套餐 CNAME 主机名。
data[].cname_domaininteger否套餐 CNAME 域名配置 ID。
data[].region_idinteger否区域 ID。
data[].node_group_idinteger否线路组 ID。

响应示例

{ "code": 0, "count": 1, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-packages'
用户 API / 套餐与交易 / 用户套餐 / 创建用户套餐

POST创建用户套餐

POST /v1/user-packages

购买并创建一个用户套餐。普通用户为自己购买时会校验套餐可购资格、购买次数、实名认证、套餐状态,并按 `duration`、可用折扣和优惠码计算价格后扣除余额、创建订单;管理员可为指定用户分配套餐,并可覆盖套餐资源额度与价格。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
packageinteger是必填。要购买的基础套餐定义 ID,必须存在。2
namestring是必填。用户套餐名称;会进行 XSS 过滤。我的标准套餐
durationstring enum否购买期限;普通用户购买时用于计算价格。month
coupon_codestring否可选。购买基础套餐时使用的优惠码。WELCOME10
enable_ipv6integer enum否是否启用 IPv6;未传时为 1。0 | 1
uidinteger否管理员专用。指定套餐归属用户 ID。
cname_hostnamestring否管理员专用。自定义套餐 CNAME 主机名;必须唯一且合法。
trafficinteger否管理员专用。流量额度;-1 表示不限。
bandwidthstring否管理员专用。带宽额度;-1 表示不限,其他值为数字加 Mbps 或 Gbps。
connectioninteger否管理员专用。连接数额度;-1 表示不限。
domaininteger否管理员专用。域名数量额度;-1 表示不限。
main_domaininteger否管理员专用。主域名数量额度;-1 表示不限。
http_portinteger否管理员专用。HTTP 非标准端口额度;-1 表示不限。
stream_portinteger否管理员专用。四层转发端口额度;-1 表示不限。
custom_cc_ruleinteger enum否管理员专用。是否允许自定义 CC 规则。0 | 1
websocketinteger enum否管理员专用。是否允许 WebSocket。0 | 1
http3integer enum否管理员专用。是否允许 HTTP/3。0 | 1
month_priceinteger否管理员专用。月付价格。
quarter_priceinteger否管理员专用。季付价格。
year_priceinteger否管理员专用。年付价格。
end_atstring否管理员专用。到期时间,格式 YYYY-MM-DD HH:mm:ss。
enableinteger enum否管理员专用。套餐启用状态。0 | 1
reasonstring enum否管理员禁用套餐时必填的禁用原因。到期 | 流量用完 | 锁定

请求体示例

{ "package": 2, "name": "我的标准套餐", "duration": "month", "coupon_code": "WELCOME10", "enable_ipv6": 1 }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“套餐添加成功”、`data` 为新建用户套餐 ID;套餐不存在、无购买权限、实名不足、余额不足或参数不合法时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。套餐添加成功
datainteger是成功时的新建用户套餐 ID;失败时为空字符串。8

响应示例

{ "code": 0, "msg": "套餐添加成功", "data": 8 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"package":2,"name":"我的标准套餐","duration":"month","coupon_code":"WELCOME10","enable_ipv6":1}' \ 'https://master.example.com/v1/user-packages'
用户 API / 套餐与交易 / 用户套餐 / 删除指定用户套餐

DELETE删除指定用户套餐

DELETE /v1/user-packages/{package_id}

删除一个用户套餐及其已购买的升级包。普通用户只能删除自己的套餐。默认删除模式要求套餐没有关联网站和四层转发;传入 `force` 会同时删除关联网站、四层转发及其部分关联数据,但仍不允许删除未到期且存在网站或四层转发的套餐。若这是该用户唯一套餐,强制删除还会删除该用户的证书、DNS API、访问控制、CC 规则、分组、任务和消息发送配置。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是要删除的用户套餐 ID。套餐必须存在,普通用户只能删除自己的套餐。8
forcequerystring否可选。传任意非空值启用强制删除:删除套餐关联的网站、四层转发及关联缓存和分组数据。未到期且仍有关联网站或四层转发时,强制删除会被拒绝。1

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“用户套餐删除成功”、`data` 为 null;套餐不存在、无权限、有关联资源或不满足强制删除条件时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。用户套餐删除成功
datastring是本接口成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "用户套餐删除成功", "data": null }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-packages/{package_id}'
用户 API / 套餐与交易 / 用户套餐 / 获取用户套餐详情

GET获取用户套餐详情

GET /v1/user-packages/{package_id}

获取用户套餐详情。可选传入 `duration` 试算续费价格,或传入 `to_package` 试算更换至另一基础套餐的差价;可同时传入优惠码参与续费价格计算。普通用户只能查看自己的套餐,管理员可查看任意套餐。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是要查询的用户套餐 ID,必须存在且当前用户有权限查看。8
durationquerystring否可选。传入后返回该期限的续费及已购升级包价格试算。month
coupon_codequerystring否可选。续费试算时使用的优惠码;不可用时返回业务错误。WELCOME10
to_packagequeryinteger否可选。目标基础套餐 ID;传入后返回更换套餐的周期、当前价格、新套餐价格与差价试算。3

响应

HTTP 200

请求已被处理。成功时 `data` 为用户套餐详情,并按请求可选附加续费或换套餐试算字段;套餐不存在、无权限或优惠码不可用时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是成功时为空字符串,失败时为错误说明。
dataobject是用户套餐详情与可选价格试算结果。
data.idinteger是用户套餐 ID。
data.uidinteger是归属用户 ID。
data.packageinteger是基础套餐定义 ID。
data.package_namestring否基础套餐名称。
data.namestring是用户套餐名称。
data.start_at2string是生效时间。
data.end_at2string是到期时间。
data.traffic_reset_timestring是下一次流量重置时间。
data.traffic_usageinteger否已使用流量。
data.trafficinteger否流量额度,-1 表示不限。
data.enableinteger enum否启用状态。0 | 1
data.reasonstring否禁用原因。
data.cname_hostnamestring否套餐 CNAME 主机名。
data.basic_pricenumber否续费试算中的基础套餐价格,仅传 duration 时返回。
data.up_pricenumber否续费试算中的升级包价格,仅传 duration 时返回。
data.total_pricenumber否续费试算总价,仅传 duration 时返回。
data.orgin_pricenumber否续费试算原价,仅传 duration 时返回。
data.periodstring否换套餐试算的当前计费周期,仅传 to_package 时返回。
data.curr_pricenumber否换套餐试算的当前套餐价格。
data.new_pricenumber否换套餐试算的新套餐价格。
data.diff_pricenumber否换套餐试算的应补或应退差价。
data.remain_daysinteger否换套餐试算使用的剩余天数。

响应示例

{ "code": 0, "msg": "", "data": { "id": 0, "uid": 0, "package": 0, "package_name": "string", "name": "string", "start_at2": "string", "end_at2": "string", "traffic_reset_time": "string", "traffic_usage": 0, "traffic": 0, "enable": 0, "reason": "string", "cname_hostname": "string", "basic_price": 0, "up_price": 0, "total_price": 0, "orgin_price": 0, "period": "string", "curr_price": 0, "new_price": 0, "diff_price": 0, "remain_days": 0 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-packages/{package_id}'
用户 API / 套餐与交易 / 用户套餐 / 更新指定用户套餐

PUT更新指定用户套餐

PUT /v1/user-packages/{package_id}

更新一个已购买套餐的名称、线路、CNAME、资源额度、开关或到期时间,也可通过 `duration` 为套餐续费。普通用户只能更新自己的套餐中无需管理员权限的字段;资源额度、价格、CNAME 主机名、到期时间及启用状态仅管理员可改。传入 `package` 时执行更换基础套餐并立即完成,不能与其他修改字段组合处理。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是要更新的用户套餐 ID。套餐必须存在;普通用户只能操作自己的套餐。8

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
uidinteger否管理员专用。指定续费、优惠和余额处理所使用的用户 ID;必须存在。该字段不会转移用户套餐归属。12
packageinteger否更换目标基础套餐定义 ID。不能与当前套餐相同;传入后立即执行换套餐,其他请求字段不会继续处理。3
namestring否套餐显示名称;会进行 XSS 过滤。我的标准套餐
durationstring enum否续费期限。续费会按套餐及已购升级包价格扣除当前用户余额并延长到期时间;管理员续费不扣费。month
coupon_codestring否续费时使用的优惠码;仅在同时传入 duration 时参与价格计算。WELCOME10
region_idinteger否区域 ID。更新时线路组必须属于该区域;变更会同步使用套餐 CNAME 的网站和四层转发。1
node_group_idinteger否主线路组 ID,不能为空,且必须属于当前区域。2
backup_node_groupinteger否备用线路组 ID;传空值可清除。若设置,必须属于当前区域且不能与主线路组相同。3
cname_domaininteger否CNAME 域名配置 ID,必须存在。变更会更新套餐及相关网站、四层转发的 CNAME 记录。4
cname_modestring enum否CNAME 归属模式:site 为网站或转发各自使用 CNAME,package 为跟随用户套餐。package
cname_hostnamestring否管理员专用。套餐 CNAME 主机名;每个以点分隔的标签都必须是合法主机名,且在用户套餐中唯一。user-12.example.invalid
trafficinteger否管理员专用。流量额度;-1 表示不限。提高额度或改为不限时会解除流量超额状态。100
bandwidthstring否管理员专用。带宽额度;-1 表示不限,其他值必须为数字加 Mbps 或 Gbps。100Mbps
connectioninteger否管理员专用。并发连接数额度;-1 表示不限。1000
domaininteger否管理员专用。域名数量额度;-1 表示不限。10
main_domaininteger否管理员专用。主域名数量额度;-1 表示不限。5
http_portinteger否管理员专用。HTTP 非标准端口数量额度;-1 表示不限。3
stream_portinteger否管理员专用。四层转发端口数量额度;-1 表示不限。2
custom_cc_ruleinteger enum否管理员专用。是否允许自定义 CC 规则。1
websocketinteger enum否管理员专用。是否允许 WebSocket。1
http3integer enum否管理员专用。是否允许 HTTP/3。1
enable_ipv6integer enum否是否启用 IPv6;变更会创建 CNAME 更新任务。1
month_priceinteger否管理员专用。用户套餐的月付价格。1000
quarter_priceinteger否管理员专用。用户套餐的季付价格。2700
year_priceinteger否管理员专用。用户套餐的年付价格。10000
end_atstring否管理员专用。直接设置到期时间,格式 YYYY-MM-DD HH:mm:ss。2026-12-31 23:59:59
enableinteger enum否管理员专用。套餐启用状态;设为 0 时必须同时提供 reason,设为 1 会恢复相关网站和转发。1
reasonstring enum否当 enable 为 0 时必填,表示禁用原因。锁定
sync-itemstring否可选。将套餐配置同步到关联网站和四层转发的项目。可传 cname_mode,或以英文逗号组合 node_group_id、cname_domain、cname_mode。node_group_id,cname_domain

请求体示例

{ "name": "我的标准套餐", "node_group_id": 2, "backup_node_group": 3, "cname_mode": "package", "enable_ipv6": 1 }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“更新用户套餐成功”、`data` 为 null;套餐不存在、无权限、字段格式错误、套餐资源不匹配、未到续费时间或余额不足时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。更新用户套餐成功
datastring是本接口成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "更新用户套餐成功", "data": null }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"我的标准套餐","node_group_id":2,"backup_node_group":3,"cname_mode":"package","enable_ipv6":1}' \ 'https://master.example.com/v1/user-packages/{package_id}'
用户 API / 套餐与交易 / 流量包

流量包

流量包

接口列表

GET
/v1/traffic-packages
查询流量套餐 — 分页查询流量包。普通用户只能看到已启用的流量包;管理员可通过 `enable` 查询指定启用状态。结果按流量包 ID 倒序返回,并带出可绑定套餐名称。
POST
/v1/traffic-packages
创建流量套餐 — 创建流量包。该操作要求管理员权限。流量包名称全局唯一,额度使用 `GB`、`TB` 或 `PB` 单位;可选地限制为只能绑定指定基础套餐。
PUT
/v1/traffic-packages
批量更新流量套餐 — 批量更新流量包。该接口要求管理员权限,且请求体必须是对象数组;每个对象必须提供已有流量包的 `id`,仅传需要修改的字段。单个对象会被拒绝。
DELETE
/v1/traffic-packages/{package_id}
删除流量套餐 — 删除一个或多个流量包。该操作要求管理员权限;路径参数支持单个 ID 或英文逗号分隔的多个 ID。每个流量包必须存在,且不能仍被任何用户流量包引用;任一项目不满足
GET
/v1/traffic-packages/{package_id}
获取流量套餐详情 — 获取单个流量包详情,并按当前登录用户和可选优惠券计算实际售价 `new_price`。普通用户不能查询已禁用流量包;管理员可查询任意已有流量包。
PUT
/v1/traffic-packages/{package_id}
更新流量套餐 — 更新指定流量包。该操作要求管理员权限;路径中的 `package_id` 会写入请求对象,客户端不能通过请求体更换更新目标。请求体必须是单个 JSON 对象,仅
用户 API / 套餐与交易 / 流量包 / 查询流量套餐

GET查询流量套餐

GET /v1/traffic-packages

分页查询流量包。普通用户只能看到已启用的流量包;管理员可通过 `enable` 查询指定启用状态。结果按流量包 ID 倒序返回,并带出可绑定套餐名称。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger否页码,必须为数字;未传时为 1。1
limitqueryinteger否每页数量,必须为数字;未传时为 10,传 0 表示不分页。10
enablequeryinteger否管理员可选。按启用状态筛选;普通用户始终仅返回启用的流量包。1

响应

HTTP 200

请求已被处理。成功时返回流量包列表和总数;页码或每页数量格式错误时也返回 HTTP 200,并在业务码中说明原因。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
countinteger是符合筛选条件的流量包总数。2
dataarray是流量包列表。
dataarray<object>否流量包列表。
data[].idinteger是流量包 ID。
data[].namestring是流量包名称。
data[].desstring否备注。
data[].amountstring是流量额度,格式为数字加 GB、TB 或 PB。
data[].bind_packagestring否可绑定套餐 ID 的逗号分隔字符串。
data[].bind_package_namestring否可绑定套餐名称的逗号分隔字符串。
data[].valid_daysinteger是流量包有效天数。
data[].priceinteger是价格,单位为系统最小货币单位。
data[].enableinteger enum是启用状态。0 | 1
data[].create_atstring否创建时间,格式为 YYYY-MM-DD HH:mm:ss。

响应示例

{ "code": 0, "count": 2, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/traffic-packages'
用户 API / 套餐与交易 / 流量包 / 创建流量套餐

POST创建流量套餐

POST /v1/traffic-packages

创建流量包。该操作要求管理员权限。流量包名称全局唯一,额度使用 `GB`、`TB` 或 `PB` 单位;可选地限制为只能绑定指定基础套餐。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring是必填。流量包名称;会进行 XSS 过滤,且必须全局唯一。100GB 流量包
desstring否可选。流量包备注;会进行 XSS 过滤,未传时为空字符串。月度加油包
amountstring是必填。流量额度,格式为非负数字加 `GB`、`TB` 或 `PB`,例如 `100GB`。100GB
bind_packagestring否可选。允许绑定此流量包的基础套餐 ID,多个 ID 用英文逗号分隔;每个 ID 必须存在。未传时不限制基础套餐。1,2
valid_daysinteger是必填。流量包有效天数,必须为大于 0 的数字。30
pricenumber是必填。售价,必须为不小于 0 的数值。10.5
enableinteger enum否是否启用;未传时为 1。1

请求体示例

{ "name": "100GB 流量包", "des": "月度加油包", "amount": "100GB", "bind_package": "1,2", "valid_days": 30, "price": 10.5, "enable": 1 }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“流量包添加成功”、`data` 为新建流量包 ID;权限不足和字段校验失败仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。流量包添加成功
datainteger是成功时的新建流量包 ID;失败时为空字符串。5

响应示例

{ "code": 0, "msg": "流量包添加成功", "data": 5 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"100GB 流量包","des":"月度加油包","amount":"100GB","bind_package":"1,2","valid_days":30,"price":10.5,"enable":1}' \ 'https://master.example.com/v1/traffic-packages'
用户 API / 套餐与交易 / 流量包 / 批量更新流量套餐

PUT批量更新流量套餐

PUT /v1/traffic-packages

批量更新流量包。该接口要求管理员权限,且请求体必须是对象数组;每个对象必须提供已有流量包的 `id`,仅传需要修改的字段。单个对象会被拒绝。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

流量包更新对象数组。

字段类型必填说明示例
(root)array<object>否流量包更新对象数组。[{"id":5,"price":12.5,"enable":1}]
[].idinteger是必填。要更新的流量包 ID,必须存在。
[].namestring否流量包名称;会进行 XSS 过滤,且必须全局唯一。
[].desstring否备注;会进行 XSS 过滤,可传空字符串。
[].amountstring否流量额度,格式为数字加 GB、TB 或 PB。
[].bind_packagestring否可绑定基础套餐 ID,多个 ID 以英文逗号分隔;每个 ID 必须存在。
[].valid_daysinteger否有效天数,必须大于 0。
[].pricenumber否售价,不得小于 0。
[].enableinteger enum否启用状态。0 | 1

请求体示例

[ { "id": 5, "price": 12.5, "enable": 1 } ]

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“更新流量包成功”、`data` 为 null;请求体不是数组、流量包不存在、权限不足或字段校验失败时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。更新流量包成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "更新流量包成功", "data": null }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '[{"id":5,"price":12.5,"enable":1}]' \ 'https://master.example.com/v1/traffic-packages'
用户 API / 套餐与交易 / 流量包 / 删除流量套餐

DELETE删除流量套餐

DELETE /v1/traffic-packages/{package_id}

删除一个或多个流量包。该操作要求管理员权限;路径参数支持单个 ID 或英文逗号分隔的多个 ID。每个流量包必须存在,且不能仍被任何用户流量包引用;任一项目不满足条件时整次删除会回滚。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathstring是要删除的流量包 ID,或以英文逗号分隔的 ID 列表;每一项必须是数字。5,6

响应

HTTP 200

请求已被处理。成功时 `code` 为 0,`msg` 为已删除的 ID 字符串,`data` 为 null;权限不足、ID 无效、流量包不存在或仍被用户流量包使用时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是成功时为请求中已删除的流量包 ID 字符串。5,6
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "5,6", "data": null }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/traffic-packages/{package_id}'
用户 API / 套餐与交易 / 流量包 / 获取流量套餐详情

GET获取流量套餐详情

GET /v1/traffic-packages/{package_id}

获取单个流量包详情,并按当前登录用户和可选优惠券计算实际售价 `new_price`。普通用户不能查询已禁用流量包;管理员可查询任意已有流量包。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是要查询的流量包 ID,必须存在。5
coupon_codequerystring否可选。用于计算当前用户购买该流量包后的实际价格;无效或不可用优惠券会返回业务错误。WELCOME10

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`data` 为流量包详情及计算后的 `new_price`;流量包不存在、普通用户查询禁用项或优惠券不可用时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是成功时为空字符串,失败时为错误说明。
dataobject是流量包详情。
data.idinteger是流量包 ID。
data.namestring是流量包名称。
data.desstring否备注。
data.amountstring是流量额度,格式为数字加 GB、TB 或 PB。
data.bind_packagestring否可绑定基础套餐 ID 列表。
data.valid_daysinteger是有效天数。
data.pricenumber是原始售价。
data.new_pricenumber是针对当前用户及 coupon_code 计算后的实际售价。
data.enableinteger enum是启用状态。0 | 1
data.create_atstring否创建时间。
data.update_atstring否更新时间。

响应示例

{ "code": 0, "msg": "", "data": { "id": 0, "name": "string", "des": "string", "amount": "string", "bind_package": "string", "valid_days": 0, "price": 0, "new_price": 0, "enable": 0, "create_at": "string", "update_at": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/traffic-packages/{package_id}'
用户 API / 套餐与交易 / 流量包 / 更新流量套餐

PUT更新流量套餐

PUT /v1/traffic-packages/{package_id}

更新指定流量包。该操作要求管理员权限;路径中的 `package_id` 会写入请求对象,客户端不能通过请求体更换更新目标。请求体必须是单个 JSON 对象,仅传需要修改的字段。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是要更新的流量包 ID,必须存在。5

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring否流量包名称;会进行 XSS 过滤,且必须全局唯一。未传时保持原值。
desstring否备注;会进行 XSS 过滤,可传空字符串。
amountstring否流量额度,格式为数字加 GB、TB 或 PB。
bind_packagestring否可绑定基础套餐 ID,多个 ID 以英文逗号分隔;每个 ID 必须存在。
valid_daysinteger否有效天数,必须大于 0。
pricenumber否售价,不得小于 0。
enableinteger enum否启用状态。0 | 1

请求体示例

{ "price": 12.5, "valid_days": 60, "enable": 1 }

响应

HTTP 200

请求已被处理。成功时 `code` 为 0、`msg` 为“更新流量包成功”、`data` 为 null;权限不足、流量包不存在、请求体格式错误或字段校验失败时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。更新流量包成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "更新流量包成功", "data": null }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"price":12.5,"valid_days":60,"enable":1}' \ 'https://master.example.com/v1/traffic-packages/{package_id}'
用户 API / 套餐与交易 / 用户流量包

用户流量包

当前用户流量包和用量。

接口列表

GET
/v1/user-traffic-package/usage
查询用户流量套餐用量 — 按时间统计一个用户流量套餐已消耗的流量。普通用户只能查询自己的流量套餐;管理员可查询任意用户。可选按关联的用户套餐过滤。未同时指定时间范围时,接口根据已有用量记
GET
/v1/user-traffic-packages
查询用户流量套餐列表 — 分页查询已购买的用户流量套餐。普通用户只能查看自己的流量套餐;管理员可按归属用户、流量套餐定义和启用状态筛选。结果按用户流量套餐 ID 倒序返回。
POST
/v1/user-traffic-packages
购买或分配用户流量套餐 — 购买一个流量套餐并创建用户流量套餐记录。普通用户只能为自己购买已启用的流量套餐,系统会校验绑定基础套餐、优惠码和账户余额,并按流量套餐有效天数设置到期时间;管理
DELETE
/v1/user-traffic-packages/{package_id}
删除用户流量套餐 — 删除一个或多个用户流量套餐及其全部流量用量记录。该操作仅管理员可执行;路径参数支持单个 ID 或英文逗号分隔的多个 ID。每个 ID 必须为数字且对应的用户流量
GET
/v1/user-traffic-packages/{package_id}
获取用户流量套餐详情 — 获取一个已购买流量套餐的详情。普通用户只能查看自己的流量套餐;管理员可查看任意用户的流量套餐。
PUT
/v1/user-traffic-packages/{package_id}
更新指定用户流量套餐 — 更新一个用户流量套餐的名称、适用基础套餐、流量总量、到期时间或启用状态。路径接口请求体必须是对象。所有实际可修改字段均要求管理员权限;启用状态设为禁用时必须提供
用户 API / 套餐与交易 / 用户流量包 / 查询用户流量套餐用量

GET查询用户流量套餐用量

GET /v1/user-traffic-package/usage

按时间统计一个用户流量套餐已消耗的流量。普通用户只能查询自己的流量套餐;管理员可查询任意用户。可选按关联的用户套餐过滤。未同时指定时间范围时,接口根据已有用量记录跨度自动按小时、天或月汇总。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
user_traffic_packagequeryinteger是必填。要统计的用户流量套餐 ID;必须存在,且当前用户拥有该套餐或具有管理员权限。21
user_packagequeryinteger否可选。仅统计关联到指定用户套餐 ID 的流量消耗记录。8
startquerystring否可选。统计开始时间,格式 YYYY-MM-DD HH:mm:ss;如提供必须同时提供 end。2026-01-01 00:00:00
endquerystring否可选。统计结束时间,格式 YYYY-MM-DD HH:mm:ss;查询范围为 time 大于等于 start 且小于 end,必须不早于 start。2026-01-08 00:00:00

响应

HTTP 200

请求已被处理。成功时 data 为按时间分组的流量用量数组;流量套餐不存在、无权限、时间范围不完整或时间格式无效时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
dataarray是按统计粒度汇总的流量用量。时间跨度小于 7 天按时间点汇总,少于 180 天按天汇总,其他情况按月汇总。
dataarray<object>否按统计粒度汇总的流量用量。时间跨度小于 7 天按时间点汇总,少于 180 天按天汇总,其他情况按月汇总。
data[].datestring是统计时间标签,格式随统计跨度为 YYYY-MM-DD HH:mm:ss、YYYY-MM-DD 或 YYYY-MM。2026-01-01
data[].valueinteger是该时间分组内的流量消耗总值。1073741824

响应示例

{ "code": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-traffic-package/usage'
用户 API / 套餐与交易 / 用户流量包 / 查询用户流量套餐列表

GET查询用户流量套餐列表

GET /v1/user-traffic-packages

分页查询已购买的用户流量套餐。普通用户只能查看自己的流量套餐;管理员可按归属用户、流量套餐定义和启用状态筛选。结果按用户流量套餐 ID 倒序返回。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger否页码,必须为数字;未传时为 1。1
limitqueryinteger否每页数量,必须为数字;未传时为 10,传 0 表示不分页。10
uidqueryinteger否管理员可选。按归属用户 ID 筛选;普通用户始终只能查询自己的流量套餐。12
traffic_package_idqueryinteger否按流量套餐定义 ID 筛选,必须为数字。3
enablequeryinteger否按用户流量套餐启用状态筛选。1

响应

HTTP 200

请求已被处理。成功时返回用户流量套餐列表及总数;页码、每页数量、用户 ID 或流量套餐 ID 格式无效时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
countinteger是符合筛选条件的用户流量套餐总数。1
dataarray是用户流量套餐列表。
dataarray<object>否用户流量套餐列表。
data[].idinteger是用户流量套餐 ID。21
data[].uidinteger是归属用户 ID。12
data[].user_namestring否归属用户名。demo
data[].namestring是用户流量套餐名称。100 GB 加油包
data[].traffic_package_idinteger是流量套餐定义 ID。3
data[].bind_packagestring否适用的基础套餐定义 ID,以英文逗号分隔;为空表示不限制。2,3
data[].bind_package_namestring否适用基础套餐名称的聚合结果。标准套餐,专业套餐
data[].amountstring是购买流量总量,单位为 GB、TB 或 PB。100GB
data[].usageinteger是已使用流量。1073741824
data[].pricenumber否实际购买价格。10
data[].orgin_pricenumber否优惠前购买价格。12
data[].expirestring是流量套餐到期时间,格式 YYYY-MM-DD HH:mm:ss。2026-12-31 23:59:59
data[].create_atstring否创建时间,格式 YYYY-MM-DD HH:mm:ss。2026-01-01 00:00:00
data[].enableinteger enum是启用状态。1
data[].reasonstring否禁用原因;启用时通常为空。null

响应示例

{ "code": 0, "count": 1, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-traffic-packages'
用户 API / 套餐与交易 / 用户流量包 / 购买或分配用户流量套餐

POST购买或分配用户流量套餐

POST /v1/user-traffic-packages

购买一个流量套餐并创建用户流量套餐记录。普通用户只能为自己购买已启用的流量套餐,系统会校验绑定基础套餐、优惠码和账户余额,并按流量套餐有效天数设置到期时间;管理员可为指定用户分配套餐并覆盖名称、适用套餐、流量总量、到期时间及启用状态。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
traffic_package_idinteger是必填。要购买或分配的流量套餐定义 ID,必须存在且已启用。3
coupon_codestring否可选。购买时使用的优惠码;系统会验证该优惠码是否适用于此流量套餐。TRAFFIC10
uidinteger否管理员专用。指定流量套餐归属的用户 ID,必须存在;未传时归属当前用户。12
namestring否管理员专用。用户流量套餐显示名称;未传时使用流量套餐定义名称,内容会进行 XSS 过滤。客户专属 100 GB 加油包
bind_packagestring否管理员专用。适用的基础套餐定义 ID,以英文逗号分隔;每个 ID 必须存在。空字符串表示不限制基础套餐。2,3
amountstring否管理员专用。流量总量,必须为数字加 GB、TB 或 PB,例如 50GB。100GB
expirestring否管理员专用。到期时间,格式 YYYY-MM-DD HH:mm:ss;未传时由流量套餐定义的有效天数计算。2026-12-31 23:59:59
enableinteger enum否管理员专用。启用状态;未传时为 1。设为 0 时必须同时传入 reason。1
reasonstring否管理员专用。当 enable 为 0 时必填,记录禁用原因。人工锁定

请求体示例

{ "traffic_package_id": 3, "coupon_code": "TRAFFIC10" }

响应

HTTP 200

请求已被处理。成功时 code 为 0、msg 为“用户流量包添加成功”、data 为新建用户流量套餐 ID;流量套餐不可用、绑定套餐不满足、优惠码无效或余额不足时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。用户流量包添加成功
datainteger是成功时的新建用户流量套餐 ID;失败时为空字符串。21

响应示例

{ "code": 0, "msg": "用户流量包添加成功", "data": 21 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"traffic_package_id":3,"coupon_code":"TRAFFIC10"}' \ 'https://master.example.com/v1/user-traffic-packages'
用户 API / 套餐与交易 / 用户流量包 / 删除用户流量套餐

DELETE删除用户流量套餐

DELETE /v1/user-traffic-packages/{package_id}

删除一个或多个用户流量套餐及其全部流量用量记录。该操作仅管理员可执行;路径参数支持单个 ID 或英文逗号分隔的多个 ID。每个 ID 必须为数字且对应的用户流量套餐必须存在。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathstring是要删除的用户流量套餐 ID,或以英文逗号分隔的 ID 列表;每一项必须为数字。21,22

响应

HTTP 200

请求已被处理。成功时 code 为 0、msg 为请求中删除的 ID 字符串、data 为 null;权限不足、ID 格式无效或流量套餐不存在时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是成功时为请求中删除的用户流量套餐 ID 字符串。21,22
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "21,22", "data": null }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-traffic-packages/{package_id}'
用户 API / 套餐与交易 / 用户流量包 / 获取用户流量套餐详情

GET获取用户流量套餐详情

GET /v1/user-traffic-packages/{package_id}

获取一个已购买流量套餐的详情。普通用户只能查看自己的流量套餐;管理员可查看任意用户的流量套餐。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是要查询的用户流量套餐 ID,必须存在且当前用户有权限查看。21

响应

HTTP 200

请求已被处理。成功时 data 为用户流量套餐详情;套餐不存在或无权限时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是成功时为空字符串,失败时为错误说明。
dataobject是用户流量套餐详情。
data.idinteger是用户流量套餐 ID。21
data.uidinteger是归属用户 ID。12
data.namestring是用户流量套餐名称。100 GB 加油包
data.traffic_package_idinteger是流量套餐定义 ID。3
data.bind_packagestring否适用的基础套餐定义 ID,以英文逗号分隔;为空表示不限制。2,3
data.amountstring是购买流量总量,单位为 GB、TB 或 PB。100GB
data.usageinteger是已使用流量。1073741824
data.pricenumber否实际购买价格。10
data.orgin_pricenumber否优惠前购买价格。12
data.expirestring是到期时间。2026-12-31 23:59:59
data.create_atstring否创建时间。2026-01-01 00:00:00
data.enableinteger enum是启用状态。1
data.reasonstring否禁用原因;启用时通常为空。null

响应示例

{ "code": 0, "msg": "", "data": { "id": 21, "uid": 12, "name": "100 GB 加油包", "traffic_package_id": 3, "bind_package": "2,3", "amount": "100GB", "usage": 1073741824, "price": 10, "orgin_price": 12, "expire": "2026-12-31 23:59:59", "create_at": "2026-01-01 00:00:00", "enable": 1, "reason": null } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/user-traffic-packages/{package_id}'
用户 API / 套餐与交易 / 用户流量包 / 更新指定用户流量套餐

PUT更新指定用户流量套餐

PUT /v1/user-traffic-packages/{package_id}

更新一个用户流量套餐的名称、适用基础套餐、流量总量、到期时间或启用状态。路径接口请求体必须是对象。所有实际可修改字段均要求管理员权限;启用状态设为禁用时必须提供禁用原因。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
package_idpathinteger是要更新的用户流量套餐 ID,必须存在。21

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
traffic_package_idinteger否可选。用于校验流量套餐定义存在且已启用;当前更新逻辑不会据此修改已购流量套餐的定义 ID。3
namestring否管理员专用。用户流量套餐名称;内容会进行 XSS 过滤。客户专属 100 GB 加油包
bind_packagestring否管理员专用。适用的基础套餐定义 ID,以英文逗号分隔;每个 ID 必须存在。空字符串表示不限制基础套餐。2,3
amountstring否管理员专用。流量总量,必须为数字加 GB、TB 或 PB。200GB
expirestring否管理员专用。到期时间,格式 YYYY-MM-DD HH:mm:ss。2026-12-31 23:59:59
enableinteger enum否管理员专用。启用状态;设为 0 时必须同时传入 reason。1
reasonstring否管理员专用。当 enable 为 0 时必填,记录禁用原因。人工锁定

请求体示例

{ "amount": "200GB", "expire": "2026-12-31 23:59:59", "enable": 1 }

响应

HTTP 200

请求已被处理。成功时 code 为 0、msg 为“更新用户流量包成功”、data 为 null;套餐不存在、权限不足、字段格式无效、适用基础套餐不存在或禁用时未提供原因仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。更新用户流量包成功
datastring是成功时为 null;失败时为空字符串。null

响应示例

{ "code": 0, "msg": "更新用户流量包成功", "data": null }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"amount":"200GB","expire":"2026-12-31 23:59:59","enable":1}' \ 'https://master.example.com/v1/user-traffic-packages/{package_id}'
用户 API / 套餐与交易 / 优惠与折扣

优惠与折扣

优惠码、折扣和使用记录。

接口列表

GET
/v1/coupons
查询优惠码列表 — 分页查询优惠码管理记录,按 ID 倒序返回。该接口需要登录且仅管理员可调用;不提供额外筛选条件。limit=0 时不执行 SQL 分页限制并返回全部记录。
POST
/v1/coupons
创建优惠码 — 创建可用于基础套餐或流量包订单的优惠码。名称和兑换字符必须全局唯一;coupon_type 为 discount 时必须提供 discount_value,为
DELETE
/v1/coupons/{coupon_id}
删除一个或多个优惠码 — 按路径中的优惠码 ID 删除记录。路由使用字符串参数,支持以英文逗号传入多个 ID;服务端逐个确认记录存在,任一记录不存在时返回 coupon-1 并回滚本次删
GET
/v1/coupons/{coupon_id}
获取优惠码详情 — 按优惠码 ID 读取完整数据库记录。该接口需要登录且仅管理员可调用;不存在的优惠码返回 coupon-2 业务错误。
PUT
/v1/coupons/{coupon_id}
更新优惠码 — 更新指定优惠码的已提交字段;路径 coupon_id 会覆盖请求体中的 id。所有业务字段均可选,未提交的字段保持原值,但请求必须实际改变至少一个字段,否则返回
GET
/v1/discounts
查询折扣列表 — 分页查询全局折扣规则,按 priority 升序返回。该接口需要登录且仅管理员可调用;不支持额外筛选。limit=0 时取消 SQL 分页限制并返回全部记录。
POST
/v1/discounts
创建折扣规则 — 创建按用户分组、套餐类别和有效时间生效的折扣规则。dis_type=discount 时必须提供 discount_value;dis_type=price 时
DELETE
/v1/discounts/{discount_id}
删除一个或多个折扣规则 — 按路径中的折扣规则 ID 删除记录。路由使用字符串参数,支持以英文逗号传入多个 ID;服务端逐个确认记录存在,任一记录不存在时返回 discount-1 并回滚
GET
/v1/discounts/{discount_id}
获取折扣规则详情 — 按折扣规则 ID 读取 discount 表完整记录。该接口需要登录且仅管理员可调用;不存在的记录返回 discount-2 业务错误。
PUT
/v1/discounts/{discount_id}
更新折扣规则 — 更新指定折扣规则的已提交字段;路径 discount_id 会覆盖请求体中的 id。所有业务字段均可选,未提交字段保持原值,但请求必须实际改变至少一个字段,否则
用户 API / 套餐与交易 / 优惠与折扣 / 查询优惠码列表

GET查询优惠码列表

GET /v1/coupons

分页查询优惠码管理记录,按 ID 倒序返回。该接口需要登录且仅管理员可调用;不提供额外筛选条件。limit=0 时不执行 SQL 分页限制并返回全部记录。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,默认 1。服务端仅校验其为数字;当 limit 不为 0 时偏移量按 (page - 1) × limit 计算。
limitqueryinteger(int32)否每页记录数,默认 10。传 0 时取消 SQL limit 并返回全部记录。

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功响应含 code、count、data,不含 msg 字段;权限、认证或分页参数失败时返回 code、msg、data 业务错误封装。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.countinteger(int64)是符合查询条件的优惠码总数,未受分页限制影响。
oneOf#1.dataarray是当前页优惠码记录,按 id 倒序排列。
oneOf#1.dataarray<object>否当前页优惠码记录,按 id 倒序排列。
oneOf#1.data[].idinteger(int64)是优惠码记录 ID。
oneOf#1.data[].namestring是优惠码管理名称。
oneOf#1.data[].desstring是优惠码备注。
oneOf#1.data[].codestring是用户兑换时提交的唯一优惠码字符。
oneOf#1.data[].catestring是适用类别,使用英文逗号组合 package(基础套餐)和 traffic(流量包)。
oneOf#1.data[].coupon_typestring enum是优惠方式:discount 按折扣值计价,price 使用固定优惠价格。discount | price
oneOf#1.data[].price_gtinteger(int64)是可选的原始价格门槛;订单原价不得低于该值才可使用。
oneOf#1.data[].discount_valuenumber(double)是coupon_type 为 discount 时使用的折扣值。
oneOf#1.data[].price_valueinteger(int64)是coupon_type 为 price 时使用的固定优惠价格。
oneOf#1.data[].persist_discountinteger enum是是否在后续续费中持续使用优惠:1 是,0 否。0 | 1
oneOf#1.data[].max_timesinteger(int64)是最多可使用次数;null 表示不设置次数上限。
oneOf#1.data[].used_timesinteger(int64)是当前已使用次数。
oneOf#1.data[].packagestring是适用的基础套餐 ID,多个 ID 使用英文逗号分隔;空字符串表示不限定。
oneOf#1.data[].traffic_packagestring是适用的流量包 ID,多个 ID 使用英文逗号分隔;空字符串表示不限定。
oneOf#1.data[].start_atstring是可选生效起始时间,格式 YYYY-MM-DD HH:mm:ss。
oneOf#1.data[].end_atstring是可选失效时间,格式 YYYY-MM-DD HH:mm:ss。
oneOf#1.data[].enableinteger enum是启用状态:1 启用,0 禁用。0 | 1
oneOf#1.data[].create_atstring是优惠码创建时间,格式 YYYY-MM-DD HH:mm:ss。
oneOf#2.codestring enum是分页参数格式错误、管理员权限不足或认证失效的业务错误码。coupon-3 | coupon-4 | coupon-35 | login_required
oneOf#2.msgstring是分页参数、权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/coupons'
用户 API / 套餐与交易 / 优惠与折扣 / 创建优惠码

POST创建优惠码

POST /v1/coupons

创建可用于基础套餐或流量包订单的优惠码。名称和兑换字符必须全局唯一;coupon_type 为 discount 时必须提供 discount_value,为 price 时必须提供 price_value。该接口需要登录且仅管理员可调用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring是优惠码管理名称,不能为空且必须全局唯一。
desstring否可选备注;省略时保存为空字符串。
codestring是用户兑换时提交的优惠码字符,不能为空且必须全局唯一。
coupon_typestring enum是优惠方式:discount 按折扣值计价,price 使用固定优惠价格。discount | price
catestring是生效类别,使用英文逗号组合 package(基础套餐)和 traffic(流量包);不能为空。
price_gtoneOf否可选订单原价门槛。省略、null 或空值表示不限制;提供时必须为整数。
price_gt(oneOf#1)integer(int64)否
price_gt(oneOf#2)string否
discount_valueoneOf否折扣值。coupon_type=discount 时必填,服务端接受整数或单个小数点的数字文本;其他类型可省略。
discount_value(oneOf#1)number(double)否
discount_value(oneOf#2)string否
price_valueoneOf否固定优惠价格。coupon_type=price 时必填,且只能为整数;其他类型可省略。
price_value(oneOf#1)integer(int64)否
price_value(oneOf#2)string否
max_timesoneOf否可选最大使用次数。省略、null 或空值表示不限制;提供时必须为整数。
max_times(oneOf#1)integer(int64)否
max_times(oneOf#2)string否
packagestring否可选适用基础套餐 ID 列表,多个 ID 用英文逗号分隔;每个 ID 必须存在。省略时为空字符串。
traffic_packagestring否可选适用流量包 ID 列表,多个 ID 用英文逗号分隔;每个 ID 必须存在。省略时为空字符串。
start_atstring否可选生效开始时间,格式 YYYY-MM-DD HH:mm:ss;省略、null 或空值表示立即可用。
end_atstring否可选失效时间,格式 YYYY-MM-DD HH:mm:ss;省略、null 或空值表示不设置结束时间。
enableinteger enum否可选启用状态:1 启用,0 禁用;省略时默认为 1。0 | 1
persist_discountinteger enum否可选续费持续优惠标记:1 表示后续续费继续享受此优惠,0 表示仅当前购买;省略时默认为 1。0 | 1

请求体示例

{ "name": "新用户九折", "des": "仅限指定基础套餐", "code": "WELCOME10", "coupon_type": "discount", "cate": "package", "discount_value": 0.9, "package": "1,2", "max_times": 100, "enable": 1, "persist_discount": 0 }

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时 data 为新优惠码 ID;字段、套餐引用、时间、权限或优惠方式校验失败时返回字符串业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是创建成功提示。优惠码添加成功
oneOf#1.datainteger(int64)是新建优惠码记录 ID。
oneOf#2.codestring是业务错误码,包括字段校验错误 coupon-7 至 coupon-34、管理员权限错误 coupon-37 及认证错误 login_required。
oneOf#2.msgstring是字段、套餐引用、时间、权限或优惠方式校验失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": 0 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"新用户九折","des":"仅限指定基础套餐","code":"WELCOME10","coupon_type":"discount","cate":"package","discount_value":0.9,"package":"1,2","max_times":100,"enable":1,"persist_discount":0}' \ 'https://master.example.com/v1/coupons'
用户 API / 套餐与交易 / 优惠与折扣 / 删除一个或多个优惠码

DELETE删除一个或多个优惠码

DELETE /v1/coupons/{coupon_id}

按路径中的优惠码 ID 删除记录。路由使用字符串参数,支持以英文逗号传入多个 ID;服务端逐个确认记录存在,任一记录不存在时返回 coupon-1 并回滚本次删除。该接口需要登录且仅管理员可调用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
coupon_idpathstring是要删除的一个或多个优惠码 ID,多个 ID 使用英文逗号分隔。

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时 data 为 null;任一优惠码不存在、管理员权限不足或认证失效时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是删除成功提示。优惠码删除成功
oneOf#1.dataobject是成功时固定为 null。
oneOf#2.codestring enum是优惠码不存在、管理员权限不足或认证失效的业务错误码。coupon-1 | coupon-36 | login_required
oneOf#2.msgstring是记录或权限校验失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": {} }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/coupons/{coupon_id}'
用户 API / 套餐与交易 / 优惠与折扣 / 获取优惠码详情

GET获取优惠码详情

GET /v1/coupons/{coupon_id}

按优惠码 ID 读取完整数据库记录。该接口需要登录且仅管理员可调用;不存在的优惠码返回 coupon-2 业务错误。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
coupon_idpathinteger(int64)是要读取的优惠码记录 ID。

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时返回 coupon 表完整记录;记录不存在、管理员权限不足或认证失效时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是详情读取成功时固定为空字符串。
oneOf#1.dataobject是coupon 表的完整优惠码记录。
oneOf#1.data.idinteger(int64)是优惠码记录 ID。
oneOf#1.data.namestring是优惠码管理名称。
oneOf#1.data.desstring是优惠码备注。
oneOf#1.data.codestring是用户兑换时提交的唯一优惠码字符。
oneOf#1.data.catestring是适用类别,以英文逗号组合 package 和 traffic。
oneOf#1.data.coupon_typestring enum是优惠方式:discount 为折扣,price 为固定价格。discount | price
oneOf#1.data.price_gtinteger(int64)是可选订单原价门槛。
oneOf#1.data.discount_valuenumber(double)是discount 方式使用的折扣值。
oneOf#1.data.price_valueinteger(int64)是price 方式使用的固定优惠价格。
oneOf#1.data.persist_discountinteger enum是续费是否持续享受优惠:1 是,0 否。0 | 1
oneOf#1.data.max_timesinteger(int64)是最多可使用次数;null 表示不限制。
oneOf#1.data.used_timesinteger(int64)是已使用次数。
oneOf#1.data.packagestring是适用基础套餐 ID 列表,多个 ID 用英文逗号分隔。
oneOf#1.data.traffic_packagestring是适用流量包 ID 列表,多个 ID 用英文逗号分隔。
oneOf#1.data.start_atstring是生效开始时间;数据库 datetime 经 JSON 序列化后返回。
oneOf#1.data.end_atstring是失效时间;数据库 datetime 经 JSON 序列化后返回。
oneOf#1.data.enableinteger enum是启用状态:1 启用,0 禁用。0 | 1
oneOf#1.data.create_atstring是创建时间;数据库 datetime 经 JSON 序列化后返回。
oneOf#2.codestring enum是优惠码不存在、管理员权限不足或认证失效的业务错误码。coupon-2 | coupon-35 | login_required
oneOf#2.msgstring是读取或权限失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "id": 0, "name": "string", "des": "string", "code": "string", "cate": "string", "coupon_type": "string", "price_gt": 0, "discount_value": 0, "price_value": 0, "persist_discount": 0, "max_times": 0, "used_times": 0, "package": "string", "traffic_package": "string", "start_at": "string", "end_at": "string", "enable": 0, "create_at": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/coupons/{coupon_id}'
用户 API / 套餐与交易 / 优惠与折扣 / 更新优惠码

PUT更新优惠码

PUT /v1/coupons/{coupon_id}

更新指定优惠码的已提交字段;路径 coupon_id 会覆盖请求体中的 id。所有业务字段均可选,未提交的字段保持原值,但请求必须实际改变至少一个字段,否则返回 coupon-29。coupon_type 与 discount_value、price_value 的组合仍须满足对应优惠方式的校验。该接口需要登录且仅管理员可调用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
coupon_idpathinteger(int64)是要更新的优惠码记录 ID。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring否可选的新管理名称;提供时不能为空且必须全局唯一。
desstring否可选的新备注;可传空字符串清空。
codestring否可选的新兑换字符;提供时不能为空且必须全局唯一。
coupon_typestring enum否可选的新优惠方式。变为 discount 时必须有有效 discount_value,变为 price 时必须有有效 price_value。discount | price
catestring否可选生效类别,以英文逗号组合 package 和 traffic。
price_gtoneOf否可选订单原价门槛;传 null 或空值清除门槛,非空值必须为整数。
price_gt(oneOf#1)integer(int64)否
price_gt(oneOf#2)string否
discount_valueoneOf否可选折扣值。当前或更新后的 coupon_type=discount 时必须保持有效非空数值。
discount_value(oneOf#1)number(double)否
discount_value(oneOf#2)string否
price_valueoneOf否可选固定优惠价格。当前或更新后的 coupon_type=price 时必须保持有效非空整数。
price_value(oneOf#1)integer(int64)否
price_value(oneOf#2)string否
max_timesoneOf否可选最大使用次数;传 null 或空值取消次数上限。
max_times(oneOf#1)integer(int64)否
max_times(oneOf#2)string否
packagestring否可选基础套餐 ID 列表;多个 ID 用英文逗号分隔,非空时每个 ID 都必须存在。
traffic_packagestring否可选流量包 ID 列表;多个 ID 用英文逗号分隔,非空时每个 ID 都必须存在。
start_atstring否可选生效开始时间;传 null 或空值清除,非空时格式为 YYYY-MM-DD HH:mm:ss。
end_atstring否可选失效时间;传 null 或空值清除,非空时格式为 YYYY-MM-DD HH:mm:ss。
enableinteger enum否可选启用状态:1 启用,0 禁用。0 | 1
persist_discountinteger enum否可选续费持续优惠标记:1 继续享受优惠,0 仅当前购买。0 | 1

请求体示例

{ "name": "新用户八五折", "discount_value": 0.85, "max_times": 200, "enable": 1 }

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时 data 为 null;优惠码不存在、字段/套餐/时间校验失败、没有实际变更、权限不足或认证失效时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是更新成功提示。更新优惠码成功
oneOf#1.dataobject是成功时固定为 null。
oneOf#2.codestring是业务错误码,包括记录/字段校验错误 coupon-5 至 coupon-34、管理员权限错误 coupon-37 及认证错误 login_required。
oneOf#2.msgstring是记录、字段、套餐、时间、无变更或权限失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": {} }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"新用户八五折","discount_value":0.85,"max_times":200,"enable":1}' \ 'https://master.example.com/v1/coupons/{coupon_id}'
用户 API / 套餐与交易 / 优惠与折扣 / 查询折扣列表

GET查询折扣列表

GET /v1/discounts

分页查询全局折扣规则,按 priority 升序返回。该接口需要登录且仅管理员可调用;不支持额外筛选。limit=0 时取消 SQL 分页限制并返回全部记录。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,默认 1。服务端仅校验其为数字;分页偏移按 (page - 1) × limit 计算。
limitqueryinteger(int32)否每页记录数,默认 10;传 0 时返回全部记录。

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功响应含 code、count、data,不含 msg 字段;分页参数、管理员权限或认证失败时返回业务错误封装。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.countinteger(int64)是折扣规则总数,未受分页限制影响。
oneOf#1.dataarray是当前页折扣规则,按 priority 从小到大排列。
oneOf#1.dataarray<object>否当前页折扣规则,按 priority 从小到大排列。
oneOf#1.data[].idinteger(int64)是折扣规则 ID。
oneOf#1.data[].namestring是折扣规则名称。
oneOf#1.data[].desstring是规则备注。
oneOf#1.data[].user_groupstring是适用用户分组 ID,多个 ID 用英文逗号分隔;空字符串表示不限定。
oneOf#1.data[].catestring enum是规则适用对象:基础套餐、升级包或流量包。package | package_up | traffic
oneOf#1.data[].packagestring是适用基础套餐 ID 列表,多个 ID 用英文逗号分隔。
oneOf#1.data[].package_upstring是适用升级包 ID 列表,多个 ID 用英文逗号分隔。
oneOf#1.data[].traffic_packagestring是适用流量包 ID 列表,多个 ID 用英文逗号分隔。
oneOf#1.data[].dis_typestring enum是折扣类型:discount 使用折扣值,price 使用月/季/年固定价格。discount | price
oneOf#1.data[].discount_valuenumber(double)是dis_type=discount 时使用的折扣值。
oneOf#1.data[].month_priceinteger(int64)是dis_type=price 时的月付固定价格。
oneOf#1.data[].quarter_priceinteger(int64)是dis_type=price 时的季付固定价格。
oneOf#1.data[].year_priceinteger(int64)是dis_type=price 时的年付固定价格。
oneOf#1.data[].start_atstring是可选开始生效时间。
oneOf#1.data[].end_atstring是可选结束生效时间。
oneOf#1.data[].priorityinteger(int32)是规则优先级,数值越小越先匹配。
oneOf#1.data[].enableinteger enum是启用状态:1 启用,0 禁用。0 | 1
oneOf#1.data[].create_atstring是规则创建时间。
oneOf#2.codestring enum是分页参数错误、管理员权限不足或认证失效的业务错误码。discount-3 | discount-4 | discount-34 | login_required
oneOf#2.msgstring是分页参数、权限或认证失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/discounts'
用户 API / 套餐与交易 / 优惠与折扣 / 创建折扣规则

POST创建折扣规则

POST /v1/discounts

创建按用户分组、套餐类别和有效时间生效的折扣规则。dis_type=discount 时必须提供 discount_value;dis_type=price 时必须同时提供 month_price、quarter_price、year_price。该接口需要登录且仅管理员可调用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring是折扣规则名称,不能为空且必须全局唯一。
desstring否可选备注;省略时保存为空字符串。
user_groupstring否可选适用用户分组 ID 列表,多个 ID 用英文逗号分隔;非空时每个 ID 都必须存在。省略时不限定用户分组。
catestring enum否可选适用类别:基础套餐、升级包或流量包。省略时保存为空字符串。package | package_up | traffic
packagestring否可选基础套餐 ID 列表,多个 ID 用英文逗号分隔;非空时每个 ID 都必须存在。
package_upstring否可选升级包 ID 列表,多个 ID 用英文逗号分隔;非空时每个 ID 都必须存在。
traffic_packagestring否可选流量包 ID 列表,多个 ID 用英文逗号分隔;非空时每个 ID 都必须存在。
dis_typestring enum是价格方式:discount 使用 discount_value;price 使用月、季、年固定价格。discount | price
discount_valueoneOf否折扣值。dis_type=discount 时必填,接受整数或单个小数点数字文本;其他方式可省略。
discount_value(oneOf#1)number(double)否
discount_value(oneOf#2)string否
month_priceoneOf否月付固定价格。dis_type=price 时必填且必须为整数;其他方式可省略。
month_price(oneOf#1)integer(int64)否
month_price(oneOf#2)string否
quarter_priceoneOf否季付固定价格。dis_type=price 时必填且必须为整数;其他方式可省略。
quarter_price(oneOf#1)integer(int64)否
quarter_price(oneOf#2)string否
year_priceoneOf否年付固定价格。dis_type=price 时必填且必须为整数;其他方式可省略。
year_price(oneOf#1)integer(int64)否
year_price(oneOf#2)string否
start_atstring否可选开始生效时间,格式 YYYY-MM-DD HH:mm:ss;省略、null 或空值表示立即生效。
end_atstring否可选结束生效时间,格式 YYYY-MM-DD HH:mm:ss;省略、null 或空值表示不设置结束时间。
enableinteger enum否可选启用状态:1 启用,0 禁用;省略时默认为 1。0 | 1
priorityoneOf否可选优先级,必须为数字;数值越小越先匹配,省略时默认为 100。
priority(oneOf#1)integer(int32)否
priority(oneOf#2)string否

请求体示例

{ "name": "新用户九折", "des": "基础套餐活动", "cate": "package", "package": "1,2", "dis_type": "discount", "discount_value": 0.9, "enable": 1, "priority": 100 }

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时 data 为新折扣规则 ID;字段、引用套餐/分组、时间、权限或价格方式校验失败时返回字符串业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是创建成功提示。折扣添加成功
oneOf#1.datainteger(int64)是新建折扣规则 ID。
oneOf#2.codestring是业务错误码,包括字段校验错误 discount-7 至 discount-33、管理员权限错误 discount-36 及认证错误 login_required。
oneOf#2.msgstring是字段、引用对象、时间、权限或价格方式校验失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": 0 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"新用户九折","des":"基础套餐活动","cate":"package","package":"1,2","dis_type":"discount","discount_value":0.9,"enable":1,"priority":100}' \ 'https://master.example.com/v1/discounts'
用户 API / 套餐与交易 / 优惠与折扣 / 删除一个或多个折扣规则

DELETE删除一个或多个折扣规则

DELETE /v1/discounts/{discount_id}

按路径中的折扣规则 ID 删除记录。路由使用字符串参数,支持以英文逗号传入多个 ID;服务端逐个确认记录存在,任一记录不存在时返回 discount-1 并回滚本次删除。该接口需要登录且仅管理员可调用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
discount_idpathstring是要删除的一个或多个折扣规则 ID,多个 ID 使用英文逗号分隔。

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时 data 为 null;任一折扣规则不存在、管理员权限不足或认证失效时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是删除成功提示。折扣删除成功
oneOf#1.dataobject是成功时固定为 null。
oneOf#2.codestring enum是折扣规则不存在、管理员权限不足或认证失效的业务错误码。discount-1 | discount-35 | login_required
oneOf#2.msgstring是记录或权限校验失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": {} }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/discounts/{discount_id}'
用户 API / 套餐与交易 / 优惠与折扣 / 获取折扣规则详情

GET获取折扣规则详情

GET /v1/discounts/{discount_id}

按折扣规则 ID 读取 discount 表完整记录。该接口需要登录且仅管理员可调用;不存在的记录返回 discount-2 业务错误。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
discount_idpathinteger(int64)是要读取的折扣规则 ID。

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时返回 discount 表完整记录;记录不存在、管理员权限不足或认证失效时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是详情读取成功时固定为空字符串。
oneOf#1.dataobject是discount 表的完整折扣规则记录。
oneOf#1.data.idinteger(int64)是折扣规则 ID。
oneOf#1.data.namestring是折扣规则名称。
oneOf#1.data.desstring是规则备注。
oneOf#1.data.user_groupstring是适用用户分组 ID 列表。
oneOf#1.data.catestring enum是适用对象类别。package | package_up | traffic
oneOf#1.data.packagestring是适用基础套餐 ID 列表。
oneOf#1.data.package_upstring是适用升级包 ID 列表。
oneOf#1.data.traffic_packagestring是适用流量包 ID 列表。
oneOf#1.data.dis_typestring enum是价格方式。discount | price
oneOf#1.data.discount_valuenumber(double)是discount 方式使用的折扣值。
oneOf#1.data.month_priceinteger(int64)是price 方式使用的月付固定价格。
oneOf#1.data.quarter_priceinteger(int64)是price 方式使用的季付固定价格。
oneOf#1.data.year_priceinteger(int64)是price 方式使用的年付固定价格。
oneOf#1.data.start_atstring是生效开始时间;数据库 datetime 经 JSON 序列化后返回。
oneOf#1.data.end_atstring是生效结束时间;数据库 datetime 经 JSON 序列化后返回。
oneOf#1.data.priorityinteger(int32)是优先级,数值越小越先匹配。
oneOf#1.data.enableinteger enum是启用状态:1 启用,0 禁用。0 | 1
oneOf#1.data.create_atstring是创建时间;数据库 datetime 经 JSON 序列化后返回。
oneOf#2.codestring enum是规则不存在、管理员权限不足或认证失效的业务错误码。discount-2 | discount-34 | login_required
oneOf#2.msgstring是读取或权限失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "id": 0, "name": "string", "des": "string", "user_group": "string", "cate": "string", "package": "string", "package_up": "string", "traffic_package": "string", "dis_type": "string", "discount_value": 0, "month_price": 0, "quarter_price": 0, "year_price": 0, "start_at": "string", "end_at": "string", "priority": 0, "enable": 0, "create_at": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/discounts/{discount_id}'
用户 API / 套餐与交易 / 优惠与折扣 / 更新折扣规则

PUT更新折扣规则

PUT /v1/discounts/{discount_id}

更新指定折扣规则的已提交字段;路径 discount_id 会覆盖请求体中的 id。所有业务字段均可选,未提交字段保持原值,但请求必须实际改变至少一个字段,否则返回 discount-32。更新后的 dis_type 仍决定折扣值或月/季/年价格的必填组合。该接口需要登录且仅管理员可调用。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
discount_idpathinteger(int64)是要更新的折扣规则 ID。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
namestring否可选的新规则名称;提供时不能为空且必须全局唯一。
desstring否可选的新备注;可传空字符串清空。
user_groupstring否可选适用用户分组 ID 列表;多个 ID 用英文逗号分隔,非空时每个 ID 必须存在。
catestring enum否可选适用类别。package | package_up | traffic
packagestring否可选基础套餐 ID 列表;非空时每个 ID 必须存在。
package_upstring否可选升级包 ID 列表;非空时每个 ID 必须存在。
traffic_packagestring否可选流量包 ID 列表;非空时每个 ID 必须存在。
dis_typestring enum否可选价格方式。更新后为 discount 时必须保留有效 discount_value;为 price 时必须保留有效月、季、年价格。discount | price
discount_valueoneOf否可选折扣值。当前或更新后的 dis_type=discount 时必须保持有效非空数值。
discount_value(oneOf#1)number(double)否
discount_value(oneOf#2)string否
month_priceoneOf否可选月付固定价格。当前或更新后的 dis_type=price 时必须保持有效非空整数。
month_price(oneOf#1)integer(int64)否
month_price(oneOf#2)string否
quarter_priceoneOf否可选季付固定价格。当前或更新后的 dis_type=price 时必须保持有效非空整数。
quarter_price(oneOf#1)integer(int64)否
quarter_price(oneOf#2)string否
year_priceoneOf否可选年付固定价格。当前或更新后的 dis_type=price 时必须保持有效非空整数。
year_price(oneOf#1)integer(int64)否
year_price(oneOf#2)string否
start_atstring否可选开始生效时间;传 null 或空值清除,非空时格式为 YYYY-MM-DD HH:mm:ss。
end_atstring否可选结束生效时间;传 null 或空值清除,非空时格式为 YYYY-MM-DD HH:mm:ss。
enableinteger enum否可选启用状态:1 启用,0 禁用。0 | 1
priorityoneOf否可选优先级,必须为数字;数值越小越先匹配。
priority(oneOf#1)integer(int32)否
priority(oneOf#2)string否

请求体示例

{ "name": "新用户八五折", "discount_value": 0.85, "priority": 50, "enable": 1 }

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时 data 为 null;记录不存在、字段/引用对象/时间校验失败、无实际变更、权限不足或认证失效时返回业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是更新成功提示。更新折扣成功
oneOf#1.dataobject是成功时固定为 null。
oneOf#2.codestring是业务错误码,包括记录/字段校验错误 discount-5 至 discount-33、管理员权限错误 discount-36 及认证错误 login_required。
oneOf#2.msgstring是记录、字段、引用对象、时间、无变更或权限失败原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": {} }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"name":"新用户八五折","discount_value":0.85,"priority":50,"enable":1}' \ 'https://master.example.com/v1/discounts/{discount_id}'
用户 API / 套餐与交易 / 订单

订单

订单

接口列表

GET
/v1/order/count
按时间分组统计订单金额 — 按订单创建时间的日、月或年分组,统计每组订单金额。接口要求登录。普通用户固定统计自身订单;管理员可传 uid 统计指定用户或不传 uid 统计全量。`count
GET
/v1/orders
查询订单列表 — 分页查询订单,按订单 ID 倒序返回。接口要求登录。普通用户仅查询自身订单;管理员可传 uid 查询指定用户,或不传 uid 查询全部。`total` 为匹配订
POST
/v1/orders
创建订单 — 以管理员身份为指定用户人工创建一条订单记录。接口会校验用户是否存在;订单金额以系统最小货币单位保存,订单说明会经过 XSS 过滤。
DELETE
/v1/orders/{order_id}
删除订单 — 以管理员身份删除一个或多个订单。路径参数使用英文逗号分隔多个订单 ID;服务端会逐个确认订单存在,并在同一事务中执行删除。
GET
/v1/orders/{order_id}
获取订单详情 — 获取当前登录用户的一条订单。服务端始终以订单 ID 和当前登录用户 ID 联合查询;即使管理员登录,也不能通过此接口查看其他用户的订单。
PUT
/v1/orders/{order_id}
更新订单 — 以管理员身份更新指定订单。路径中的订单 ID 会覆盖请求体中的同名字段;未传的可更新字段保持原值,至少应提供一个与原值不同的字段。订单说明会经过 XSS 过滤。
用户 API / 套餐与交易 / 订单 / 按时间分组统计订单金额

GET按时间分组统计订单金额

GET /v1/order/count

按订单创建时间的日、月或年分组,统计每组订单金额。接口要求登录。普通用户固定统计自身订单;管理员可传 uid 统计指定用户或不传 uid 统计全量。`count` 是匹配的时间分组数量,不是订单总数量。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
group_byquerystring否时间分组粒度,默认 day。
typequerystring否订单类型精确筛选,服务端不限制枚举。
statequerystring否订单状态精确筛选。
startquerystring否创建时间下界;只有同时传 end 才生效,直接由数据库比较。2026-01-01 00:00:00
endquerystring否创建时间上界(不含);只有同时传 start 才生效。2026-02-01 00:00:00
uidqueryinteger否仅管理员有效:用户 ID 筛选,普通用户传入时被忽略。12
pagequeryinteger否分组结果页码,默认 1。服务端未额外校验格式。
limitqueryinteger否每页分组数,默认 10;传字符串 0 时不分页。服务端未额外校验格式。

响应

HTTP 200

成功和业务错误均返回 HTTP 200。金额在数据库中以分存储,接口按 `amount / 100` 求和、截断到两位小数并以字符串返回。

字段类型必填说明示例
oneOf#1.codeinteger enum是订单金额分组统计查询成功时固定为 0。0
oneOf#1.countinteger是未分页的时间分组数量。
oneOf#1.dataarray是当前页分组金额,未显式指定排序。
oneOf#1.dataarray<object>否当前页分组金额,未显式指定排序。
oneOf#1.data[].timestring是按 group_by 格式化的时间键:YYYY-MM-DD、YYYY-MM 或 YYYY。
oneOf#1.data[].sumstring是该时间组金额总和,单位为元,截断两位小数。12.34
oneOf#2.codestring enum是state 非法、group_by 非法或认证失败的业务错误码。order-5 | order-6 | login_required
oneOf#2.msgstring是订单状态、统计粒度或认证失败的具体原因。
oneOf#2.datastring enum是发生业务错误时固定返回空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/order/count'
用户 API / 套餐与交易 / 订单 / 查询订单列表

GET查询订单列表

GET /v1/orders

分页查询订单,按订单 ID 倒序返回。接口要求登录。普通用户仅查询自身订单;管理员可传 uid 查询指定用户,或不传 uid 查询全部。`total` 为匹配订单 amount 的总和,保持数据库以分为单位的整数值。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger否页码,必须为数字,默认 1。
limitqueryinteger否每页条数,必须为数字,默认 10;传 0 时不分页。
uidqueryinteger否仅管理员有效:用户 ID 精确筛选。12
typequerystring否订单类型精确筛选。
statequerystring否订单状态精确筛选。
startquerystring否创建时间下界,直接交给数据库比较。2026-01-01 00:00:00
endquerystring否创建时间上界(不含),直接交给数据库比较。2026-02-01 00:00:00

响应

HTTP 200

成功及参数/认证错误均返回 HTTP 200。列表成功响应不含 msg。

字段类型必填说明示例
oneOf#1.codeinteger enum是订单列表查询成功时固定为 0。0
oneOf#1.countinteger是未分页的匹配订单数。
oneOf#1.totalinteger是匹配订单 amount 总和,单位为分;无订单时数据库可能返回 null。
oneOf#1.dataarray是当前页订单。
oneOf#1.dataarray<object>否当前页订单。
oneOf#1.data[].idinteger是订单 ID。
oneOf#1.data[].uidinteger是订单所属用户 ID。
oneOf#1.data[].typestring是订单类型。
oneOf#1.data[].desstring是订单描述。
oneOf#1.data[].datastring是订单业务数据文本。
oneOf#1.data[].amountinteger是订单金额,单位为分。
oneOf#1.data[].real_amountinteger是实付金额,单位为分。
oneOf#1.data[].pay_typestring是付款方式。
oneOf#1.data[].mch_order_nostring是商户订单号。
oneOf#1.data[].transaction_idstring是支付交易号。
oneOf#1.data[].statestring是订单状态。
oneOf#1.data[].create_atstring是格式化创建时间,YYYY-MM-DD HH:mm:ss。
oneOf#1.data[].pay_atstring是格式化付款时间,YYYY-MM-DD HH:mm:ss。
oneOf#2.codestring enum是page/limit 格式、state 非法或认证失败的业务错误码。order-1 | order-2 | order-4 | login_required
oneOf#2.msgstring是分页参数、订单状态或认证失败的具体原因。
oneOf#2.datastring enum是发生业务错误时固定返回空字符串。

响应示例

{ "code": 0, "count": 0, "total": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/orders'
用户 API / 套餐与交易 / 订单 / 创建订单

POST创建订单

POST /v1/orders

以管理员身份为指定用户人工创建一条订单记录。接口会校验用户是否存在;订单金额以系统最小货币单位保存,订单说明会经过 XSS 过滤。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
uidinteger是订单所属用户 ID;必须对应现有用户。12
typestring是订单类型,由调用方按业务场景填写。充值
desstring否订单说明;服务端会进行 XSS 过滤。未传时保存为空字符串。账户余额充值
create_atstring(date-time)否订单创建时间,格式为 `YYYY-MM-DD HH:mm:ss`;未传时服务端尝试使用当前时间。2026-07-28 10:30:00
pay_atstring(date-time)否付款时间,格式为 `YYYY-MM-DD HH:mm:ss`;未传时使用当前时间。2026-07-28 10:30:00
amountinteger否订单应付金额,可为负数;以系统最小货币单位保存。未传时为 0。10000
real_amountinteger否订单实付金额,可为负数;以系统最小货币单位保存。未传时为 0。10000
pay_typestring是付款方式。manual
mch_order_nostring否支付渠道的商户订单号;未传时保存为空字符串。MANUAL-20260728-0001
transaction_idstring否支付渠道交易流水号;未传时保存为空字符串。TXN-20260728-0001
statestring否订单状态;未传时默认为“已付款”。已付款

请求体示例

{ "uid": 12, "type": "充值", "des": "账户余额充值", "create_at": "2026-07-28 10:30:00", "pay_at": "2026-07-28 10:30:00", "amount": 10000, "real_amount": 10000, "pay_type": "manual", "mch_order_no": "MANUAL-20260728-0001", "transaction_id": "TXN-20260728-0001", "state": "已付款" }

响应

HTTP 200

订单创建成功,`data` 为新订单的自增 ID。 鉴权失败或参数校验失败时仍返回 HTTP 200,`code` 可能为 `login_required`、`admin_required`、`order-4`、`order-5`、`order-6`、`order-7`、`order-8`、`order-9`、`order-10`、`order-11` 或 `order-13`。

字段类型必填说明示例
oneOf#1.codeinteger是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。订单添加成功
oneOf#1.datainteger是新创建订单的自增 ID。1201
oneOf#2.codestring是业务错误码。order-5
oneOf#2.msgstring是错误原因。用户ID 12不存在
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "订单添加成功", "data": 1201 }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"uid":12,"type":"充值","des":"账户余额充值","create_at":"2026-07-28 10:30:00","pay_at":"2026-07-28 10:30:00","amount":10000,"real_amount":10000,"pay_type":"manual","mch_order_no":"MANUAL-20260728-0001","transaction_id":"TXN-20260728-0001","state":"已付款"}' \ 'https://master.example.com/v1/orders'
用户 API / 套餐与交易 / 订单 / 删除订单

DELETE删除订单

DELETE /v1/orders/{order_id}

以管理员身份删除一个或多个订单。路径参数使用英文逗号分隔多个订单 ID;服务端会逐个确认订单存在,并在同一事务中执行删除。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
order_idpathstring是一个订单 ID,或以英文逗号分隔的多个订单 ID。501,502

响应

HTTP 200

指定订单删除成功后返回的标准业务响应。 未登录、非管理员、维护模式限制或订单不存在时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`order-15` 或 `order-1`。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。订单删除成功
oneOf#1.datastring是该操作未返回订单对象。
oneOf#2.codestring是业务错误码。order-1
oneOf#2.msgstring是错误原因。订单不存在
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "订单删除成功", "data": "string" }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/orders/{order_id}'
用户 API / 套餐与交易 / 订单 / 获取订单详情

GET获取订单详情

GET /v1/orders/{order_id}

获取当前登录用户的一条订单。服务端始终以订单 ID 和当前登录用户 ID 联合查询;即使管理员登录,也不能通过此接口查看其他用户的订单。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
order_idpathinteger是要查询的订单 ID。501

响应

HTTP 200

成功、未登录和订单不存在/无权限均返回 HTTP 200。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。获取成功
oneOf#1.dataobject是订单记录。
oneOf#1.data.idinteger是订单 ID。
oneOf#1.data.uidinteger是订单所属用户 ID。
oneOf#1.data.typestring是订单类型。
oneOf#1.data.desstring是订单说明。
oneOf#1.data.datastring是订单关联的业务数据文本。
oneOf#1.data.create_atstring是订单创建时间;由数据库日期时间字段序列化返回。
oneOf#1.data.pay_atstring是订单付款时间;由数据库日期时间字段序列化返回。
oneOf#1.data.amountinteger是订单应付金额,单位为系统最小货币单位。
oneOf#1.data.real_amountinteger是订单实付金额,单位为系统最小货币单位。
oneOf#1.data.pay_typestring是付款方式。
oneOf#1.data.mch_order_nostring是支付渠道商户订单号。
oneOf#1.data.transaction_idstring是支付渠道交易流水号。
oneOf#1.data.statestring是订单状态。
oneOf#2.codestring enum是订单不存在、无权访问或未登录时的业务错误码。order-3 | login_required
oneOf#2.msgstring是错误原因。订单不存在或无权限
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "获取成功", "data": { "id": 0, "uid": 0, "type": "string", "des": "string", "data": "string", "create_at": "string", "pay_at": "string", "amount": 0, "real_amount": 0, "pay_type": "string", "mch_order_no": "string", "transaction_id": "string", "state": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/orders/{order_id}'
用户 API / 套餐与交易 / 订单 / 更新订单

PUT更新订单

PUT /v1/orders/{order_id}

以管理员身份更新指定订单。路径中的订单 ID 会覆盖请求体中的同名字段;未传的可更新字段保持原值,至少应提供一个与原值不同的字段。订单说明会经过 XSS 过滤。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
order_idpathinteger是要更新的订单 ID。501

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
uidinteger否订单所属用户 ID;传入时必须对应现有用户。12
typestring否订单类型;传入时不能为空。充值
desstring否订单说明;服务端会进行 XSS 过滤。账户余额充值
create_atstring(date-time)否订单创建时间,格式为 `YYYY-MM-DD HH:mm:ss`。2026-07-28 10:30:00
pay_atstring(date-time)否订单付款时间,格式为 `YYYY-MM-DD HH:mm:ss`。2026-07-28 10:30:00
amountinteger否订单应付金额,可为负数;以系统最小货币单位保存。10000
real_amountinteger否订单实付金额,可为负数;以系统最小货币单位保存。10000
pay_typestring否付款方式;传入时不能为空。manual
mch_order_nostring否支付渠道商户订单号。MANUAL-20260728-0001
transaction_idstring否支付渠道交易流水号。TXN-20260728-0001
statestring否订单状态。已付款

请求体示例

{ "uid": 12, "type": "充值", "des": "账户余额充值", "create_at": "2026-07-28 10:30:00", "pay_at": "2026-07-28 10:30:00", "amount": 10000, "real_amount": 10000, "pay_type": "manual", "mch_order_no": "MANUAL-20260728-0001", "transaction_id": "TXN-20260728-0001", "state": "已付款" }

响应

HTTP 200

订单字段更新成功后返回的标准业务响应。 鉴权或校验失败时仍返回 HTTP 200。`code` 可能为 `login_required`、`admin_required`、`order-2`、`order-3`、`order-4`、`order-5`、`order-7`、`order-9`、`order-10`、`order-12` 或 `order-13`。

字段类型必填说明示例
oneOf#1.codeinteger enum是业务状态码;0 表示成功。0
oneOf#1.msgstring是业务提示。更新订单成功
oneOf#1.datastring是该操作未返回订单对象。
oneOf#2.codestring是业务错误码。order-12
oneOf#2.msgstring是错误原因。数据未更改
oneOf#2.datastring是错误响应中的固定空字符串。

响应示例

{ "code": 0, "msg": "更新订单成功", "data": "string" }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"uid":12,"type":"充值","des":"账户余额充值","create_at":"2026-07-28 10:30:00","pay_at":"2026-07-28 10:30:00","amount":10000,"real_amount":10000,"pay_type":"manual","mch_order_no":"MANUAL-20260728-0001","transaction_id":"TXN-20260728-0001","state":"已付款"}' \ 'https://master.example.com/v1/orders/{order_id}'
用户 API / 套餐与交易 / 支付

支付

支付

接口列表

POST
/v1/alipay/preorder
创建支付宝充值预订单 — 为当前登录用户创建支付宝余额充值预订单。充值金额必须以字符串提交,可使用整数或最多两位小数;服务端会根据系统充值限制检查实名认证或企业认证状态,并按后台配置的支
POST
/v1/wxpay/preorder
创建微信充值预支付订单 — 为当前登录用户创建余额充值订单,并按后台配置调用原生微信支付、CodePay 或 Cccyun 微信支付渠道。系统会根据充值限制要求个人实名认证、二次实名认证或
用户 API / 套餐与交易 / 支付 / 创建支付宝充值预订单

POST创建支付宝充值预订单

POST /v1/alipay/preorder

为当前登录用户创建支付宝余额充值预订单。充值金额必须以字符串提交,可使用整数或最多两位小数;服务端会根据系统充值限制检查实名认证或企业认证状态,并按后台配置的支付宝通道生成支付地址或易支付提交参数。接口会同时创建一条金额以分为单位、状态为“未付款”的充值订单;只有后续支付回调验签成功后才会增加账户余额。不同支付通道返回的数据结构不同,调用方应按返回字段选择跳转或表单提交方式。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
amountstring是充值金额,单位为元。必须是非负数字字符串,可不带小数或保留一至两位小数;不接受负号、千位分隔符或超过两位小数。

请求体示例

{ "amount": "string" }

响应

HTTP 200

业务结果通过 HTTP 200 返回。创建成功时,官方支付宝和码支付通道返回支付地址、系统订单 ID 及通道实收金额,易支付通道返回需要提交到支付网关的签名表单字段;金额格式、认证限制、通道未开通或支付网关下单失败时返回字符串业务错误码。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,充值预订单创建成功时固定为 0。0
oneOf#1.msgstring enum是充值预订单写入并取得支付地址后返回的确认消息。订单创建成功
oneOf#1.dataobject是官方支付宝 PC、面对面付或码支付通道的预下单结果。
oneOf#1.data.qr_code_urlstring是支付地址。PC 通道返回带签名参数的支付宝跳转 URL,面对面付或码支付通道返回可生成二维码的支付内容。
oneOf#1.data.order_idinteger(int64)是本系统创建的未付款充值订单 ID。
oneOf#1.data.moneyoneOf是支付通道确认的实收金额;码支付通道返回字符串或数字,官方支付宝通道尚未确认实收金额时为 null。
oneOf#1.data.money(oneOf#1)string否
oneOf#1.data.money(oneOf#2)number(double)否
oneOf#1.data.money(oneOf#3)string否
oneOf#2.codeinteger enum是成功状态码,易支付预订单创建成功时固定为 0。0
oneOf#2.msgstring enum是易支付预订单写入并生成签名参数后返回的确认消息。订单创建成功
oneOf#2.dataobject是客户端需要以表单方式提交给易支付网关的完整参数。
oneOf#2.data.urlstring是客户端应提交支付表单的易支付网关地址,已包含 `/submit.php`。
oneOf#2.data.pidstring是后台配置的易支付商户 ID。
oneOf#2.data.typestring enum是易支付通道类型,支付宝充值固定为 `alipay`。alipay
oneOf#2.data.out_trade_nostring是发送给易支付网关的商户订单号,以 `cy` 开头,并与本系统未付款订单关联。
oneOf#2.data.notify_urlstring是支付完成后由易支付服务器调用的异步通知地址。
oneOf#2.data.return_urlstring是支付完成后浏览器跳回的前端地址。
oneOf#2.data.namestring是支付网关展示的订单名称,由系统名称和“余额充值”组成。
oneOf#2.data.moneystring是提交给易支付网关的充值金额字符串,与请求中的 `amount` 一致。
oneOf#2.data.sitenamestring是支付网关展示的站点名称,取自系统名称配置。
oneOf#2.data.signstring是按字段名排序并拼接商户密钥后计算的 MD5 签名。
oneOf#2.data.sign_typestring enum是易支付表单使用的签名算法,固定为 `MD5`。MD5
oneOf#3.codestring enum是业务错误码:`-1` 表示支付宝未开通,`-2` 至 `-8` 表示金额缺失或格式错误,`-9` 表示支付宝面对面付下单失败,`-10` 表示码支付网关失败,`-11` 表示未满足实名认证限制,`-12` 表示未满足企业认证限制,`login_required` 表示登录态无效。alipay_pre_order-1 | alipay_pre_order-2 | alipay_pre_order-3 | alipay_pre_order-4 | alipay_pre_order-5 | alipay_pre_order-6 | alipay_pre_order-7 | alipay_pre_order-8 | alipay_pre_order-9 | alipay_pre_order-10 | alipay_pre_order-11 | alipay_pre_order-12 | login_required
oneOf#3.msgstring是与业务错误码对应的中文金额、认证状态、通道配置或支付网关错误原因。
oneOf#3.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "qr_code_url": "string", "order_id": 0, "money": null } }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"amount":"string"}' \ 'https://master.example.com/v1/alipay/preorder'
用户 API / 套餐与交易 / 支付 / 创建微信充值预支付订单

POST创建微信充值预支付订单

POST /v1/wxpay/preorder

为当前登录用户创建余额充值订单,并按后台配置调用原生微信支付、CodePay 或 Cccyun 微信支付渠道。系统会根据充值限制要求个人实名认证、二次实名认证或企业认证;成功后订单状态为未付款,支付回调到账后才会增加余额。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
amountstring是必填。充值金额,必须是非负数字字符串;可带小数点,且最多两位小数。10.00

请求体示例

{ "amount": "10.00" }

响应

HTTP 200

请求已被处理。成功时返回支付二维码、支付网关表单参数或订单 ID;金额格式无效、未开通微信支付、未满足认证限制或第三方下单失败时仍返回 HTTP 200。

字段类型必填说明示例
codeinteger是业务状态码;成功为 0。0
msgstring是处理结果说明。订单创建成功
dataobject是支付渠道返回的预支付数据。原生微信和 CodePay 返回 code_url、order_id、money;Cccyun 返回提交支付网关所需参数。
data.code_urlstring否原生微信或 CodePay 的付款二维码链接。weixin://wxpay/bizpayurl?pr=demo
data.order_idinteger否本系统创建的充值订单 ID;Cccyun 渠道不返回该字段。101
data.moneystring否CodePay 或 Cccyun 返回的支付金额;原生微信支付通常为 null。10.00
data.urlstring否Cccyun 支付网关提交地址。https://pay.example.invalid/submit.php
data.pidstring否Cccyun 商户标识。demo-merchant
data.typestring否Cccyun 支付方式,固定为 wxpay。wxpay
data.out_trade_nostring否商户订单号。cy202601010001
data.notify_urlstring否支付回调地址。https://master.example.invalid/v1/wxpay/notify
data.return_urlstring否付款完成后的返回地址。https://master.example.invalid/pay-result
data.namestring否订单商品名称。Cdnfly余额充值
data.sitenamestring否站点名称。Cdnfly
data.signstring否Cccyun 请求签名。sanitized-signature
data.sign_typestring否签名算法,固定为 MD5。MD5

响应示例

{ "code": 0, "msg": "订单创建成功", "data": { "code_url": "weixin://wxpay/bizpayurl?pr=demo", "order_id": 101, "money": "10.00", "url": "https://pay.example.invalid/submit.php", "pid": "demo-merchant", "type": "wxpay", "out_trade_no": "cy202601010001", "notify_url": "https://master.example.invalid/v1/wxpay/notify", "return_url": "https://master.example.invalid/pay-result", "name": "Cdnfly余额充值", "sitename": "Cdnfly", "sign": "sanitized-signature", "sign_type": "MD5" } }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"amount":"10.00"}' \ 'https://master.example.com/v1/wxpay/preorder'
用户 API / 转发与数据 / 网站监控

网站监控

网站访问、安全和实时监控。

接口列表

GET
/v1/monitor/site/access-log
查询网站访问日志 — 查询 Elasticsearch 中的网站 HTTP 访问日志,按时间倒序返回。接口要求登录。普通用户固定只能查询自己的 uid 和名下域名;管理员可通过 ui
GET
/v1/monitor/site/access-log/{id}
获取访问日志请求详情 — 按 Elasticsearch 文档 ID 获取访问日志的请求头、响应头和请求体。接口要求登录。普通用户仅能读取日志中 uid 与自身相同的记录;管理员可读取任
GET
/v1/monitor/site/blackip
查询网站黑名单 IP — 查询日志库中仍有效(`exp &gt;= 当前 Unix 时间戳`)的网站黑名单 IP,按创建时间倒序返回。接口要求登录。普通用户固定按自身 uid 过滤;管理
GET
/v1/monitor/site/blackip-count
按网站统计黑名单记录数 — 按 `site_id` 聚合黑名单日志的文档数。接口要求登录且不接受查询参数。普通用户仅聚合自身 uid 的记录,管理员聚合全部记录。注意:该接口不筛选 `ex
GET
/v1/monitor/site/download-access-log/{job_id}
下载已生成的访问日志文件 — 下载由 `POST /v1/jobs` 的 `down_http_access_log` 任务生成的 gzip 访问日志。接口要求登录,仅任务创建者可下载;关联
GET
/v1/monitor/site/history-blackip
查询历史黑名单记录 — 分页查询 MySQL `black_ip` 表的历史黑名单,包含已过期记录,按创建时间倒序返回。接口要求登录。普通用户仅能查询自身 uid;管理员可查询全量或用
GET
/v1/monitor/site/realtime
查询网站实时监控时间序列 — 按时间窗口聚合网站 HTTP 访问日志的带宽、流量、请求量、QPS、缓存命中率、4xx/5xx 状态码或源站指标。接口要求登录。普通用户固定查询自身 uid,且
GET
/v1/monitor/site/top
查询网站访问 Top 排行榜 — 按 IP、国家、省份、运营商、URL、域名端口、TLS 指纹或 Referer 聚合访问日志。需要登录;普通用户仅查询自己的 uid 且传入域名必须属于自己,管
用户 API / 转发与数据 / 网站监控 / 查询网站访问日志

GET查询网站访问日志

GET /v1/monitor/site/access-log

查询 Elasticsearch 中的网站 HTTP 访问日志,按时间倒序返回。接口要求登录。普通用户固定只能查询自己的 uid 和名下域名;管理员可通过 uid 查询指定用户,或不传 uid 查询全部用户。`start` 与 `end` 必填,时区固定按 +08:00 解释。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
startquerystring是查询起始时间(含),格式 `YYYY-MM-DD HH:mm:ss`。2026-01-01 00:00:00
endquerystring是查询结束时间(不含),格式 `YYYY-MM-DD HH:mm:ss`。2026-01-01 01:00:00
hostquerystring否空格分隔的网站域名。普通用户的每个域名必须属于自己;通配符网站可匹配对应子域名。www.example.invalid api.example.invalid
server_portquerystring否源站服务端口,必须为合法端口。443
addrquerystring否客户端 IP 精确筛选,必须为合法 IP。192.0.2.10
uidqueryinteger否仅管理员有效:用户 ID 精确筛选。普通用户传入时被忽略。管理员未传时不添加 uid 筛选。12
req_uriquerystring否请求 URI,必须以 `/` 开头。匹配方式由 uri_match_type 决定。/assets/app.js
uri_match_typequerystring否URI 匹配方式:`exact` 精确匹配(默认);`prefix` 以前缀匹配并将 URI 转小写、去除末尾 `/`。
statusquerystring否三位 HTTP 状态码精确筛选。200
node_idquerystring否节点 ID(日志字段 nid),必须为数字。1001
cache_statusquerystring否缓存状态精确筛选。
methodquerystring否HTTP 方法精确筛选,仅允许 1 至 10 个英文字母。GET
tls_fpquerystring否JA4 TLS 指纹,必须为 36 个字母、数字或下划线。t13d4907h2_0d8feac7bc37_7395dae3b2f3
countryquerystring否国家名称精确筛选。
provincequerystring否省份名称精确筛选。
cityquerystring否城市名称精确筛选。
ispquerystring否运营商名称精确筛选。
refererquerystring否Referer 精确筛选。
pagequeryinteger否页码,默认 1。服务端最多查询前 1000 条,超过范围时会调整页码。
limitqueryinteger否每页条数,默认 10;服务端会将超过 100 的值压缩为 100。
get_countquerystring否任意非空值均启用仅计数模式;启用时不返回日志数组。1

响应

HTTP 200

成功、筛选参数错误和认证/网站归属错误均返回 HTTP 200。普通查询的总数由日志库返回,查询体设置 `track_total_hits=1000`。

字段类型必填说明示例
oneOf#1.codeinteger enum是仅统计匹配数量时成功状态固定为 0。0
oneOf#1.datainteger是仅 get_count 非空时返回的匹配日志数量。
oneOf#2.codeinteger enum是访问日志列表查询成功时固定为 0。0
oneOf#2.countinteger是当前筛选条件下日志库返回的匹配总数。
oneOf#2.dataarray是当前页日志,按 time 倒序。
oneOf#2.dataarray<object>否当前页日志,按 time 倒序。
oneOf#2.data[]._idstring是日志文档 ID。
oneOf#2.data[].tls_fpstring是TLS 指纹,缺失时为空字符串。
oneOf#2.data[].host2string是附加 Host 字段,缺失时为空字符串。
oneOf#2.data[].countrystring是国家,缺失时为空字符串。
oneOf#2.data[].provincestring是省份,缺失时为空字符串。
oneOf#2.data[].citystring是城市,缺失时为空字符串。
oneOf#2.data[].nidstring是节点 ID。
oneOf#2.data[].statusstring是HTTP 状态码。
oneOf#2.data[].protocolstring是请求协议。
oneOf#2.data[].addrstring是客户端 IP。
oneOf#2.data[].bytes_sentinteger是响应发送字节数。
oneOf#2.data[].cache_statusstring是缓存状态。
oneOf#2.data[].up_resp_timeobject是上游响应耗时,保持日志库原始类型。
oneOf#2.data[].hoststring是请求 Host。
oneOf#2.data[].server_portobject是源站端口;日志缺失时为空字符串。
oneOf#2.data[].refererstring是Referer。
oneOf#2.data[].user_agentstring是User-Agent。
oneOf#2.data[].content_typestring是响应 Content-Type。
oneOf#2.data[].timestring是日志时间字段。
oneOf#2.data[].req_uristring是请求 URI。
oneOf#2.data[].up_recvobject是上游接收字节数,保持日志库原始类型。
oneOf#2.data[].methodstring是HTTP 方法。
oneOf#2.data[].timestampobject是Elasticsearch sort 时间戳,保持原始类型。
oneOf#2.data[].sipstring是源站 IP,缺失时为空字符串。
oneOf#2.data[].l1_cache_statusstring是一级缓存状态,缺失时为空字符串。
oneOf#2.data[].l2_cache_statusstring是二级缓存状态,缺失时为空字符串。
oneOf#2.data[].l2_ipstring是二级节点 IP,缺失时为空字符串。
oneOf#2.data[].latobject是纬度,缺失时为空字符串。
oneOf#2.data[].lngobject是经度,缺失时为空字符串。
oneOf#2.data[].ispstring是运营商,缺失时为空字符串。
oneOf#3.codestring enum是时间、域名归属、IP、状态码、缓存状态、URI、端口、节点、方法、URI 匹配方式、TLS 指纹或认证失败的业务错误码。access_log-1 | access_log-2 | access_log-3 | access_log-4 | access_log-5 | access_log-6 | access_log-7 | access_log-9 | access_log-10 | access_log-11 | access_log-12 | access_log-13 | login_required
oneOf#3.msgstring是访问日志查询参数校验或认证失败的具体原因。
oneOf#3.datastring enum是发生业务错误时固定返回空字符串。

响应示例

{ "code": 0, "data": 0 }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/monitor/site/access-log'
用户 API / 转发与数据 / 网站监控 / 获取访问日志请求详情

GET获取访问日志请求详情

GET /v1/monitor/site/access-log/{id}

按 Elasticsearch 文档 ID 获取访问日志的请求头、响应头和请求体。接口要求登录。普通用户仅能读取日志中 uid 与自身相同的记录;管理员可读取任何记录。当前服务端直接取查询结果首项,日志 ID 不存在时没有标准业务错误封装,可能返回服务端异常。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
idpathstring是访问日志 Elasticsearch 文档 ID。

响应

HTTP 200

成功和普通用户越权均使用 HTTP 200。缺失的 `req_header`、`resp_header` 或 `req_body` 统一返回空字符串。

字段类型必填说明示例
oneOf#1.codeinteger enum是0 表示查询成功。0
oneOf#1.msgstring enum是成功时固定为空字符串。
oneOf#1.dataobject是指定访问日志记录中保存的原始请求与响应内容。
oneOf#1.data.req_headeroneOf是日志原始请求头;字段未记录时为空字符串。对象形式的键为 HTTP 头名称、值为对应头值。
oneOf#1.data.req_header(oneOf#1)string否
oneOf#1.data.resp_headeroneOf是日志原始响应头;字段未记录时为空字符串。对象形式的键为 HTTP 头名称、值为对应头值。
oneOf#1.data.resp_header(oneOf#1)string否
oneOf#1.data.req_bodystring是日志原始请求体;字段未记录时为空字符串。
oneOf#2.codestring enum是普通用户访问其他用户日志或认证失败时返回。access_log_detail-1 | login_required
oneOf#2.msgstring是权限不足或认证失败的具体原因。
oneOf#2.datastring enum是业务错误时为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "req_header": null, "resp_header": null, "req_body": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/monitor/site/access-log/{id}'
用户 API / 转发与数据 / 网站监控 / 查询网站黑名单 IP

GET查询网站黑名单 IP

GET /v1/monitor/site/blackip

查询日志库中仍有效(`exp &gt;= 当前 Unix 时间戳`)的网站黑名单 IP,按创建时间倒序返回。接口要求登录。普通用户固定按自身 uid 过滤;管理员不加 uid 限制。传 `action=export` 时不返回 JSON,而下载去重后的 IP 文本。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger否页码,必须为数字,默认 1。
limitqueryinteger否每页条数,必须为数字,默认 10;服务端将超过 300 的值压缩为 300。
ipquerystring否黑名单 IP 精确筛选,服务端不额外校验格式。192.0.2.10
filter_namequerystring否黑名单日志字段 `filter` 的精确筛选值;名称历史上保留为 filter_name,通常为 CC 过滤器 ID。8
site_idquerystring否网站 ID 精确筛选,服务端不额外校验格式。123
actionquerystring否传 `export` 时导出全部匹配的唯一 IP,每行一个;其他值按普通 JSON 查询处理。

响应

HTTP 200

普通查询成功时返回 JSON;导出成功时返回 text/plain 附件 `black_ip.txt`。日志查询异常、分页参数错误或认证失败仍可返回 HTTP 200 的业务错误封装。

字段类型必填说明示例
oneOf#1.codeinteger enum是黑名单列表查询成功时固定为 0。0
oneOf#1.countinteger是所有匹配且未过期的记录总数。
oneOf#1.dataarray是当前页黑名单记录。
oneOf#1.dataarray<object>否当前页黑名单记录。
oneOf#1.data[].positionstring是黑名单位置描述;日志未记录时为空字符串。
oneOf#1.data[].site_idstring是日志中的网站 ID 原始值。
oneOf#1.data[].ipstring是被封禁 IP。
oneOf#1.data[].fnamestring是日志中的 filter 原始值,通常为 CC 过滤器 ID。
oneOf#1.data[].domainstring是网站域名;无法解析网站时回退为 site_id 原始值。
oneOf#1.data[].namestring是关联 CC 过滤器名称;无法解析时为 null。
oneOf#1.data[].create_atobject是黑名单创建时间,保持日志库原始类型。
oneOf#1.data[].expobject是过期时间,Unix 时间戳,保持日志库原始类型。
oneOf#2.codestring enum是page/limit 格式、日志库查询错误或认证失败的业务错误码。black_ip-1 | black_ip-2 | black_ip-3 | login_required
oneOf#2.msgstring是筛选参数、日志查询或认证失败的具体原因。
oneOf#2.datastring enum是发生业务错误时固定返回空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/monitor/site/blackip'
用户 API / 转发与数据 / 网站监控 / 按网站统计黑名单记录数

GET按网站统计黑名单记录数

GET /v1/monitor/site/blackip-count

按 `site_id` 聚合黑名单日志的文档数。接口要求登录且不接受查询参数。普通用户仅聚合自身 uid 的记录,管理员聚合全部记录。注意:该接口不筛选 `exp`,因此计数可能包含已过期黑名单;日志库 terms 聚合最多返回 100 个网站桶。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

响应

HTTP 200

成功时返回 HTTP 200 的统计数组。当前服务端未对日志库查询异常做业务错误转换。

字段类型必填说明示例
codeinteger enum是0 表示聚合成功。0
countinteger是返回的网站聚合桶数量,不是黑名单总记录数。
dataarray是按日志库 terms 聚合返回的网站统计,最多 100 项。
dataarray<object>否按日志库 terms 聚合返回的网站统计,最多 100 项。
data[].site_idobject是日志中的网站 ID 原始值,类型由日志库决定。
data[].countinteger是该网站对应的黑名单日志文档数,包含已过期记录。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/monitor/site/blackip-count'
用户 API / 转发与数据 / 网站监控 / 下载已生成的访问日志文件

GET下载已生成的访问日志文件

GET /v1/monitor/site/download-access-log/{job_id}

下载由 `POST /v1/jobs` 的 `down_http_access_log` 任务生成的 gzip 访问日志。接口要求登录,仅任务创建者可下载;关联 task 状态必须为 `done`,且临时下载文件尚未被清理。成功下载时文件名优先使用任务数据中 host 的第一个域名加 job ID。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
job_idpathinteger是访问日志下载任务(job)ID。

响应

HTTP 200

下载成功时返回 gzip 二进制附件;响应的 Content-Disposition 文件名为 `{host}-{job_id}.log.gz` 或 `{job_id}.log.gz`。

字段类型必填说明示例
(root)string(binary)否gzip 压缩的访问日志文件。

HTTP 403

任务存在但不属于当前登录用户。响应为中文纯文本 `无权限`。

字段类型必填说明示例
(root)string否

HTTP 404

任务不存在、任务尚未完成或已生成文件被清理。响应为中文纯文本。

字段类型必填说明示例
(root)string否

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/monitor/site/download-access-log/{job_id}'
用户 API / 转发与数据 / 网站监控 / 查询历史黑名单记录

GET查询历史黑名单记录

GET /v1/monitor/site/history-blackip

分页查询 MySQL `black_ip` 表的历史黑名单,包含已过期记录,按创建时间倒序返回。接口要求登录。普通用户仅能查询自身 uid;管理员可查询全量或用 uid 筛选指定用户。时间条件仅在 start 与 end 同时传入时生效。传 `action=export` 时返回全部匹配记录的去重 IP 纯文本。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger否页码,必须为数字,默认 1。
limitqueryinteger否每页条数,必须为数字,默认 10。action=export 时服务端忽略该值并查询全部。
uidqueryinteger否仅管理员有效:按黑名单所属用户 ID 精确筛选;普通用户传入时仍仅查询自身。12
ipquerystring否黑名单 IP 精确筛选。192.0.2.10
site_idqueryinteger否网站 ID 精确筛选。123
startquerystring否创建时间下界;只有同时传 end 才生效,直接交给数据库比较。2026-01-01 00:00:00
endquerystring否创建时间上界(不含);只有同时传 start 才生效,直接交给数据库比较。2026-01-02 00:00:00
actionquerystring否传 export 时下载所有匹配 IP 的去重文本;其他值按普通查询处理。

响应

HTTP 200

普通查询返回 JSON;导出返回 text/plain 附件。

字段类型必填说明示例
codeinteger enum是历史黑名单列表查询成功时固定为 0。0
countinteger是未应用分页前的匹配历史记录总数。
dataarray是当前页历史黑名单。
dataarray<object>否当前页历史黑名单。
data[].site_idinteger是网站 ID。
data[].ipstring是被封禁 IP。
data[].filterstring是关联 CC 过滤器 ID 原始值。
data[].uidinteger是黑名单所属用户 ID。
data[].expobject是过期时间,保持数据库原始类型。
data[].create_atstring(date-time)是创建时间。
data[].positionstring是黑名单位置描述。
data[].auto_unlockinteger enum是自动解锁标记的数据库布尔值。0 | 1
data[].domainstring是关联网站域名;网站不存在时为空。
data[].fnamestring是关联 CC 过滤器名称;过滤器不存在时为空。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/monitor/site/history-blackip'
用户 API / 转发与数据 / 网站监控 / 查询网站实时监控时间序列

GET查询网站实时监控时间序列

GET /v1/monitor/site/realtime

按时间窗口聚合网站 HTTP 访问日志的带宽、流量、请求量、QPS、缓存命中率、4xx/5xx 状态码或源站指标。接口要求登录。普通用户固定查询自身 uid,且所传域名必须属于自己;管理员不加 uid 限制。服务端按查询跨度自动使用 1 分钟(少于 6 小时)、2 分钟(6 至 12 小时)或 5 分钟(12 小时及以上)桶,跨度超过 50 小时会拒绝。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
typequerystring是监控指标类型。
startquerystring是开始时间(含),格式 `YYYY-MM-DD HH:mm:ss`,按 +08:00 解释。2026-01-01 00:00:00
endquerystring是结束时间(不含),格式 `YYYY-MM-DD HH:mm:ss`。2026-01-01 01:00:00
domainquerystring否空格分隔的网站域名精确筛选。普通用户每个域名都必须属于自己。www.example.invalid api.example.invalid
server_portquerystring否源站端口精确筛选,必须为合法端口。443

响应

HTTP 200

成功及参数、域名权限错误均返回 HTTP 200。日志库未返回聚合时 data 为空数组。时间戳为 Elasticsearch date_histogram 桶键(通常为 Unix 毫秒时间戳)。

字段类型必填说明示例
oneOf#1.codeinteger enum是网站实时指标查询成功时固定为 0。0
oneOf#1.msgstring enum是实时指标查询成功时固定为空字符串。
oneOf#1.dataarray是除 status-4xx/status-5xx 外,元素为 [时间戳, 指标值]。bandwidth 和 backend-bandwidth 为每秒字节数;traffic/backend-traffic 为字节总量;req 为请求数;qps 为每秒请求数;backend-resp-time 为平均源站响应时间;两个缓存类型为 0 至 100 的命中百分比。状态码类型时元素改为分组对象。
oneOf#1.dataarray<object>否除 status-4xx/status-5xx 外,元素为 [时间戳, 指标值]。bandwidth 和 backend-bandwidth 为每秒字节数;traffic/backend-traffic 为字节总量;req 为请求数;qps 为每秒请求数;backend-resp-time 为平均源站响应时间;两个缓存类型为 0 至 100 的命中百分比。状态码类型时元素改为分组对象。
oneOf#1.data[](oneOf#1)array<object>否
oneOf#1.data[](oneOf#1)[](oneOf#1)integer否桶时间戳。
oneOf#1.data[](oneOf#1)[](oneOf#2)number否指标值。
oneOf#1.data[](oneOf#2).namestring是4xx 或 5xx HTTP 状态码。
oneOf#1.data[](oneOf#2).valuearray是该状态码完整时间序列。
oneOf#1.data[](oneOf#2).valuearray<array>否该状态码完整时间序列。
oneOf#2.codestring enum是缺少/不支持指标、缺少时间、域名无权限、日期格式、跨度超过限制、端口错误或认证失败的业务错误码。realtime-1 | realtime-2 | realtime-3 | realtime-5 | realtime-6 | realtime-7 | realtime-8 | realtime-9 | realtime-11 | login_required
oneOf#2.msgstring是实时指标参数、权限或时间范围校验失败的具体原因。
oneOf#2.datastring enum是发生业务错误时固定返回空字符串。

响应示例

{ "code": 0, "msg": "string", "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/monitor/site/realtime'
用户 API / 转发与数据 / 网站监控 / 查询网站访问 Top 排行榜

GET查询网站访问 Top 排行榜

GET /v1/monitor/site/top

按 IP、国家、省份、运营商、URL、域名端口、TLS 指纹或 Referer 聚合访问日志。需要登录;普通用户仅查询自己的 uid 且传入域名必须属于自己,管理员查询全量。榜单条数由系统 `res_rank_size` 配置决定。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
typequerystring是排行维度。
recent_timequerystring否最近时间窗口;提供时忽略 start/end,仅支持 10m、30m、60m。
startquerystring否自定义开始时间(含);未传 recent_time 时与 end 一同必填,格式 YYYY-MM-DD HH:mm:ss,跨度不超过 1.5 小时。2026-01-01 00:00:00
endquerystring否自定义结束时间(不含);未传 recent_time 时与 start 一同必填。2026-01-01 01:00:00
domainquerystring否空格分隔域名筛选;普通用户只能传自身域名。www.example.invalid
server_portquerystring否源站端口精确筛选,必须为合法端口。443
ccquerystring否攻击流量模式:0(默认)全部流量;1 仅统计窗口内出现过 HTTP 444 的 IP。管理员生成攻击 IP 候选集时不应用域名和端口筛选。

响应

HTTP 200

成功、参数和域名权限错误均返回 HTTP 200。日志库异常或无聚合时成功返回空数组。

字段类型必填说明示例
oneOf#1.codeinteger enum是网站资源排行查询成功时固定为 0。0
oneOf#1.msgstring enum是网站资源排行查询成功时固定为空字符串。
oneOf#1.dataarray是排行数据。
oneOf#1.dataarray<object>否排行数据。
oneOf#1.data[].trafficnumber是bytes_sent 总和。
oneOf#1.data[].up_recvnumber是up_recv 总和。
oneOf#1.data[].countinteger是请求文档数。
oneOf#1.data[].resstring是资源值:IP、地理字段、运营商、URL、域名端口、TLS 指纹或 Referer,由 type 决定。
oneOf#2.codestring enum是域名权限、类型、时间、recent_time、端口或认证失败的业务错误码。monitor_top-1 | monitor_top-2 | monitor_top-3 | monitor_top-4 | monitor_top-5 | monitor_top-6 | monitor_top-7 | monitor_top-8 | monitor_top-9 | login_required
oneOf#2.msgstring是排行类型、时间范围、域名权限或认证失败的具体原因。
oneOf#2.datastring enum是发生业务错误时固定返回空字符串。

响应示例

{ "code": 0, "msg": "string", "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/monitor/site/top'
用户 API / 转发与数据 / 用量统计

用量统计

套餐与流量用量统计。

接口列表

GET
/v1/monitor/usage
查询资源用量时间序列 — 按小时或按天聚合带宽、流量、请求数或黑名单数量。接口要求登录。普通用户固定查询自身 uid;管理员可选 uid 查询指定用户或全量。未指定 `res` 时从套餐
GET
/v1/monitor/usage-count
查询套餐用量汇总 — 从 `res_count_package` 套餐汇总表计算指定日期范围内的峰值带宽、流量、请求数及黑名单数。接口要求登录。普通用户固定查询自身 uid;管理员可
用户 API / 转发与数据 / 用量统计 / 查询资源用量时间序列

GET查询资源用量时间序列

GET /v1/monitor/usage

按小时或按天聚合带宽、流量、请求数或黑名单数量。接口要求登录。普通用户固定查询自身 uid;管理员可选 uid 查询指定用户或全量。未指定 `res` 时从套餐汇总表查询,指定 `res` 时从资源明细表查询。普通用户没有任何 user_package 时直接成功返回空数组。时间范围达到 7 天时按天汇总,否则按小时汇总。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
typequerystring是用量指标。
startquerystring(date)是开始日期(含),格式 YYYY-MM-DD。2026-01-01
endquerystring(date)是结束日期(不含),格式 YYYY-MM-DD。2026-01-08
uidqueryinteger否仅管理员有效:用户 ID 筛选;普通用户传入时被忽略。12
resquerystring否空格分隔的资源标识。提供后改从 res_count 明细表查询并按这些 res 精确过滤;未提供时从 res_count_package 套餐汇总表查询。www.example.invalid
user_packagequerystring否空格分隔的用户套餐 ID,仅允许数字。101 102
catequerystring否服务类别筛选。

响应

HTTP 200

成功与参数/认证错误均返回 HTTP 200。普通指标返回 data 数组;带宽返回相同 data 并额外带有 max_value、max_95_value。跨 7 天以上查询带宽时,按天结果是当天各小时汇总带宽的最大值,而非总和。

字段类型必填说明示例
oneOf#1.codeinteger enum是按小时或天查询用量序列成功时固定为 0。0
oneOf#1.msgstring enum是用量序列查询成功时固定为空字符串。
oneOf#1.dataarray是时间序列。
oneOf#1.dataarray<object>否时间序列。
oneOf#1.data[].datestring是小时查询格式 YYYY-MM-DD HH:00:00,天查询格式 YYYY-MM-DD。
oneOf#1.data[].valuenumber是聚合指标值。
oneOf#2.codeinteger enum是带宽统计用量查询成功时固定为 0。0
oneOf#2.msgstring enum是带宽统计用量查询成功时固定为空字符串。
oneOf#2.dataarray是带宽统计模式下按小时返回的用量序列。
oneOf#2.dataarray<object>否带宽统计模式下按小时返回的用量序列。
oneOf#2.data[].datestring是带宽统计小时,格式为 YYYY-MM-DD HH:00:00。
oneOf#2.data[].valuenumber是该小时聚合得到的带宽用量数值。
oneOf#2.max_valuenumber是仅 bandwidth:所有小时汇总值中的最大值。
oneOf#2.max_95_valuenumber是仅 bandwidth:服务端按降序索引 `len*5/100+1` 取得的 95 值。
oneOf#3.codestring enum是type、日期、cate、套餐 ID 或认证失败的业务错误码。monitor-site-usage-1 | monitor-site-usage-2 | monitor-site-usage-3 | monitor-site-usage-4 | monitor-site-usage-7 | monitor-site-usage-8 | monitor-site-usage-9 | login_required
oneOf#3.msgstring是用量类型、日期、统计粒度、套餐标识或认证失败的具体原因。
oneOf#3.datastring enum是发生业务错误时固定返回空字符串。

响应示例

{ "code": 0, "msg": "string", "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/monitor/usage'
用户 API / 转发与数据 / 用量统计 / 查询套餐用量汇总

GET查询套餐用量汇总

GET /v1/monitor/usage-count

从 `res_count_package` 套餐汇总表计算指定日期范围内的峰值带宽、流量、请求数及黑名单数。接口要求登录。普通用户固定查询自身 uid;管理员可用 uid 查询指定用户或不传 uid 查询全部。带宽值为范围内按小时汇总后的最大值,其余三个值为范围内总和。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
startquerystring(date)是开始日期(含),格式 YYYY-MM-DD。2026-01-01
endquerystring(date)是结束日期(不含),格式 YYYY-MM-DD。2026-01-08
uidqueryinteger否仅管理员有效:按用户 ID 统计。普通用户传入时被忽略。12

响应

HTTP 200

成功、日期参数错误和认证错误均返回 HTTP 200。范围内没有匹配记录时四项数值均为 0。

字段类型必填说明示例
oneOf#1.codeinteger enum是网站用量汇总查询成功时固定为 0。0
oneOf#1.msgstring enum是网站用量汇总查询成功时固定为空字符串。
oneOf#1.dataobject是指定时间范围内网站带宽、流量、请求和黑名单汇总值。
oneOf#1.data.bandwidth_valuenumber是范围内小时带宽汇总的最大值。
oneOf#1.data.traffic_valuenumber是范围内流量总和。
oneOf#1.data.req_valuenumber是范围内请求数总和。
oneOf#1.data.blackip_valuenumber是范围内黑名单计数总和。
oneOf#2.codestring enum是缺少/格式错误日期或认证失败的业务错误码。monitor-usage-count-2 | monitor-usage-count-3 | monitor-usage-count-7 | monitor-usage-count-8 | login_required
oneOf#2.msgstring是日期参数格式错误或认证失败的具体原因。
oneOf#2.datastring enum是发生业务错误时固定返回空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "bandwidth_value": 0, "traffic_value": 0, "req_value": 0, "blackip_value": 0 } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/monitor/usage-count'
用户 API / 转发与数据 / 消息

消息

消息

接口列表

GET
/v1/messages
查询消息列表与当前用户阅读状态 — 分页查询站内消息摘要和当前查询用户的已读状态,按 sort 降序、消息 ID 降序返回。普通用户只可查询展示中的、按当前服务端 receive 条件归属自己的消
POST
/v1/messages
创建站内消息 — 以当前管理员身份创建一条或多条站内消息。仅管理员可调用;发布者自动取当前登录用户,不能由请求指定。请求可为一个消息对象或非空消息对象数组,服务端依次创建并返回逗
POST
/v1/messages/read
标记消息已读 — 将一条或多条消息标记为当前登录用户已读。接口要求登录。对同一消息重复调用不会新增重复已读记录;服务端只校验消息是否存在,不会额外校验消息是否属于当前用户可见范围
GET
/v1/messages/sub
查询当前用户的消息订阅设置 — 查询当前登录用户的消息订阅记录。接口要求登录,不支持筛选参数;每条记录对应一个消息类型的邮件和短信接收开关。没有订阅记录时返回空数组。
PUT
/v1/messages/sub
更新当前用户的消息订阅开关 — 更新当前登录用户已有消息类型订阅记录的邮件或短信开关。接口要求登录,请求可为单个对象或对象数组。每一项都必须提供 `msg_type`;`phone`、`ema
DELETE
/v1/messages/{message_id}
删除一条或多条消息 — 删除指定消息及其全部 `message_read` 已读记录。接口要求管理员身份。路径参数是字符串,可传单个消息 ID 或用英文逗号分隔多个 ID;服务端逐个验
GET
/v1/messages/{message_id}
获取消息完整详情 — 按 ID 返回 `message` 表的完整消息记录(包含正文及发送状态字段)。接口要求登录。若消息指定了 `receive` 且其值不是当前用户 ID,则仅管
PUT
/v1/messages/{message_id}
更新指定消息 — 更新指定消息的可编辑字段。接口要求管理员身份,路径中的 `message_id` 会覆盖请求体可能携带的 `id`。请求体必须为对象;所有业务字段均可省略,空对
用户 API / 转发与数据 / 消息 / 查询消息列表与当前用户阅读状态

GET查询消息列表与当前用户阅读状态

GET /v1/messages

分页查询站内消息摘要和当前查询用户的已读状态,按 sort 降序、消息 ID 降序返回。普通用户只可查询展示中的、按当前服务端 receive 条件归属自己的消息;管理员可查询全部消息,也可用 receive 切换为指定接收用户视角。列表响应不包含消息正文 content,正文需通过 GET /v1/messages/{message_id} 获取。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,默认 1。服务端仅校验为数字,分页偏移为 (page - 1) × limit。
limitqueryinteger(int32)否每页记录数,默认 10;传 0 时返回全部匹配记录。
typequerystring否精确筛选消息类型。当前消息创建接口只允许 announcement;服务端对非 announcement 类型会在普通用户或指定 receive 时额外按接收用户过滤。announcement
receivequeryinteger(int64)否仅管理员可用。指定消息接收用户 ID,并按该用户视角关联已读状态;普通用户传入会被拒绝。
is_showqueryinteger否仅管理员有效:精确筛选展示状态,必须为数字。普通用户始终只查询 is_show=1 的消息。
user_package_idqueryinteger(int64)否精确筛选关联的用户套餐 ID。
site_idqueryinteger(int64)否精确筛选关联的网站 ID。

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功响应包含 code、count、data,不含 msg;页码、每页数量、is_show 格式或 receive 权限错误时返回业务错误封装。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.countinteger(int64)是当前权限和筛选条件下、未应用分页前的消息总数。
oneOf#1.dataarray是当前页消息摘要,按 sort 降序、id 降序排列。
oneOf#1.dataarray<object>否当前页消息摘要,按 sort 降序、id 降序排列。
oneOf#1.data[].user_package_idinteger(int64)否关联的用户套餐 ID;未关联时为 null。
oneOf#1.data[].site_idinteger(int64)否关联的网站 ID;未关联时为 null。
oneOf#1.data[].receiveinteger(int64)否消息指定接收用户 ID;null 表示未指定单个接收者。
oneOf#1.data[].uidinteger(int64)否当前查询用户在 message_read 中的用户 ID;非 null 表示该用户已读此消息,null 表示未读。
oneOf#1.data[].idinteger(int64)是消息 ID。
oneOf#1.data[].typestring是消息类型。
oneOf#1.data[].titlestring是消息标题。
oneOf#1.data[].is_showboolean是是否在消息列表中展示。
oneOf#1.data[].is_redboolean是是否使用红色强调样式。
oneOf#1.data[].is_boldboolean是是否使用粗体强调样式。
oneOf#1.data[].urlstring是外部消息跳转地址;非外部消息通常为空字符串。
oneOf#1.data[].is_externalboolean是是否为外部链接消息;为 true 时客户端应使用 url,不使用正文。
oneOf#1.data[].is_popupboolean是是否要求客户端以弹窗方式展示。
oneOf#1.data[].sortinteger(int32)是排序值,值越大越靠前。
oneOf#1.data[].create_at2string是格式化后的创建时间,格式为 YYYY-MM-DD HH:mm:ss。
oneOf#1.data[].update_at2string是格式化后的更新时间,格式为 YYYY-MM-DD HH:mm:ss。
oneOf#2.codestring enum是page、limit、is_show 参数错误,receive 需要管理员权限或认证失败的业务错误码。message-19 | message-20 | message-21 | message-33 | login_required
oneOf#2.msgstring是具体错误原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/messages'
用户 API / 转发与数据 / 消息 / 创建站内消息

POST创建站内消息

POST /v1/messages

以当前管理员身份创建一条或多条站内消息。仅管理员可调用;发布者自动取当前登录用户,不能由请求指定。请求可为一个消息对象或非空消息对象数组,服务端依次创建并返回逗号分隔的消息 ID。当前实现仅允许消息类型 announcement。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
oneOf#1.typestring enum是必填。消息类型,当前仅支持 announcement。announcement
oneOf#1.titlestring是必填。消息标题,不能为空。
oneOf#1.contentstring否普通消息必填。站内消息正文;当 is_external=1 时可以省略,服务端保存为空字符串。
oneOf#1.is_externalinteger enum否是否为外部链接消息:0 为站内正文消息,1 为外部链接消息。为 1 时 url 必填。0 | 1
oneOf#1.urlstring否外部链接消息必填。跳转地址;普通消息可省略,默认空字符串。
oneOf#1.is_showinteger enum否是否展示:1 为展示,0 为隐藏。0 | 1
oneOf#1.is_redinteger enum否是否使用红色强调样式:1 为使用,0 为不使用。0 | 1
oneOf#1.is_boldinteger enum否是否使用粗体强调样式:1 为使用,0 为不使用。0 | 1
oneOf#1.is_popupinteger enum否是否要求客户端弹窗展示:1 为是,0 为否。0 | 1
oneOf#1.sortinteger(int32)否排序值,值越大越靠前;未提供时默认 100。服务端要求仅含数字。
oneOf#2array<object>否批量创建消息的对象数组。服务端按数组顺序创建,返回的 ID 顺序与此一致。
oneOf#2[].typestring enum是消息类型。announcement
oneOf#2[].titlestring是非空消息标题。
oneOf#2[].contentstring否非外部消息的正文。
oneOf#2[].is_externalinteger enum否外部消息标记,1 时必须提供 url。0 | 1
oneOf#2[].urlstring否外部消息跳转地址。
oneOf#2[].is_showinteger enum否展示标记。0 | 1
oneOf#2[].is_redinteger enum否红色样式标记。0 | 1
oneOf#2[].is_boldinteger enum否粗体样式标记。0 | 1
oneOf#2[].is_popupinteger enum否弹窗展示标记。0 | 1
oneOf#2[].sortinteger否排序值。

请求体示例

{ "type": "string", "title": "string", "content": "string", "is_external": 0, "url": "string", "is_show": 0, "is_red": 0, "is_bold": 0, "is_popup": 0, "sort": 0 }

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时 data 为逗号分隔的新增消息 ID;非管理员、请求格式、字段校验或外部链接/正文条件不满足时返回业务错误封装。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是创建成功提示。消息添加成功
oneOf#1.datastring是新建消息 ID,批量创建时以英文逗号分隔。
oneOf#2.codestring enum是非管理员、数据格式、消息类型、标题、正文、样式标记、排序值或外部链接校验失败的业务错误码。message-1 | message-8 | message-9 | message-10 | message-11 | message-12 | message-14 | message-15 | message-16 | message-17 | message-22 | message-23 | message-24 | message-25 | message-26 | message-29
oneOf#2.msgstring是具体错误原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": "string" }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"type":"string","title":"string","content":"string","is_external":0,"url":"string","is_show":0,"is_red":0,"is_bold":0,"is_popup":0,"sort":0}' \ 'https://master.example.com/v1/messages'
用户 API / 转发与数据 / 消息 / 标记消息已读

POST标记消息已读

POST /v1/messages/read

将一条或多条消息标记为当前登录用户已读。接口要求登录。对同一消息重复调用不会新增重复已读记录;服务端只校验消息是否存在,不会额外校验消息是否属于当前用户可见范围。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
oneOf#1.idinteger是要标记已读的消息 ID。服务端检查该消息记录存在。101
oneOf#2array<object>否批量标记的消息对象数组。服务端允许空数组并直接返回成功;实际调用应至少提供一个对象。
oneOf#2[].idinteger是消息 ID。101

请求体示例

{ "id": 101 }

响应

HTTP 200

成功及业务错误均返回 HTTP 200。缺少消息 ID 或消息不存在时,响应会保留现有的 code 与 msg 字段取值顺序,调用方应同时依据两字段处理失败结果。

字段类型必填说明示例
oneOf#1.codeinteger enum是0 表示全部消息均已标记。0
oneOf#1.msgstring enum是成功提示。消息已读
oneOf#1.dataobject是成功时为 null。
oneOf#2.codestring enum是缺少 ID、消息不存在或认证失败的实际业务错误标识;前两种值来自服务端的参数顺序。请提供id | 找不到此消息 | login_required
oneOf#2.msgstring enum是实际业务错误消息;前两种为服务端写入的错误标识。message_read-2 | message_read-3 | 需要登录
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": {} }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"id":101}' \ 'https://master.example.com/v1/messages/read'
用户 API / 转发与数据 / 消息 / 查询当前用户的消息订阅设置

GET查询当前用户的消息订阅设置

GET /v1/messages/sub

查询当前登录用户的消息订阅记录。接口要求登录,不支持筛选参数;每条记录对应一个消息类型的邮件和短信接收开关。没有订阅记录时返回空数组。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

响应

HTTP 200

成功与认证错误均返回 HTTP 200。成功时 `data` 为当前用户的 `message_sub` 表记录数组。

字段类型必填说明示例
oneOf#1.codeinteger enum是0 表示查询成功。0
oneOf#1.msgstring enum是成功提示。获取订阅成功
oneOf#1.dataarray是当前用户的订阅记录;表中没有匹配记录时为空数组。
oneOf#1.dataarray<object>否当前用户的订阅记录;表中没有匹配记录时为空数组。
oneOf#1.data[].uidinteger是订阅所属用户 ID,固定为当前登录用户。12
oneOf#1.data[].msg_typestring是订阅的消息类型。announcement
oneOf#1.data[].phoneinteger enum是短信订阅开关的数据库布尔值:1 开启,0 关闭;未设置时为空。0 | 1
oneOf#1.data[].emailinteger enum是邮件订阅开关的数据库布尔值:1 开启,0 关闭;未设置时为空。0 | 1
oneOf#2.codestring enum是未登录或登录会话无效时的业务错误码。login_required
oneOf#2.msgstring是认证失败原因。
oneOf#2.datastring enum是业务错误时为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/messages/sub'
用户 API / 转发与数据 / 消息 / 更新当前用户的消息订阅开关

PUT更新当前用户的消息订阅开关

PUT /v1/messages/sub

更新当前登录用户已有消息类型订阅记录的邮件或短信开关。接口要求登录,请求可为单个对象或对象数组。每一项都必须提供 `msg_type`;`phone`、`email` 可任选或同时提供。服务端仅执行 UPDATE:若当前用户没有对应订阅记录,请求仍成功但不会新增记录。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
oneOf#1.msg_typestring是要更新的消息类型;服务端不限制枚举值,必须与已有订阅记录的类型匹配才会实际更新。announcement
oneOf#1.phoneinteger enum否可选。短信订阅开关:1 开启,0 关闭。0 | 1
oneOf#1.emailinteger enum否可选。邮件订阅开关:1 开启,0 关闭。0 | 1
oneOf#2array<object>否批量更新对象数组。服务端允许空数组并返回成功;实际调用应至少提交一项。
oneOf#2[].msg_typestring是消息类型。
oneOf#2[].phoneinteger enum否短信订阅开关。0 | 1
oneOf#2[].emailinteger enum否邮件订阅开关。0 | 1

请求体示例

{ "msg_type": "announcement", "phone": 0, "email": 0 }

响应

HTTP 200

成功及业务错误均返回 HTTP 200。注意:当前服务端中三个 `client_error` 调用的参数顺序与通用约定相反,缺少 `msg_type` 或开关值非法时,中文原因出现在 `code`,错误标识出现在 `msg`。

字段类型必填说明示例
oneOf#1.codeinteger enum是0 表示处理完成。0
oneOf#1.msgstring enum是成功提示。订阅已更新
oneOf#1.dataobject是成功时为 null,不返回更新后的订阅记录。
oneOf#2.codestring enum是缺少消息类型、phone/email 值非法或认证失败的实际错误标识;前三种来自服务端的参数顺序。请提供msg_type | phone值错误 | email值错误 | login_required
oneOf#2.msgstring enum是实际错误消息;前三种为服务端写入的错误标识。message_sub-2 | message_sub-4 | message_sub-6 | 需要登录
oneOf#2.datastring enum是业务错误时为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": {} }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"msg_type":"announcement","phone":0,"email":0}' \ 'https://master.example.com/v1/messages/sub'
用户 API / 转发与数据 / 消息 / 删除一条或多条消息

DELETE删除一条或多条消息

DELETE /v1/messages/{message_id}

删除指定消息及其全部 `message_read` 已读记录。接口要求管理员身份。路径参数是字符串,可传单个消息 ID 或用英文逗号分隔多个 ID;服务端逐个验证 ID 格式和消息存在性,任一项失败时整个事务回滚。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
message_idpathstring是单个消息 ID,或英文逗号分隔的多个消息 ID。每个值必须是数字且对应现有消息。

响应

HTTP 200

成功和业务错误均返回 HTTP 200。成功时不返回已删除 ID 列表;参数格式错误、消息不存在或权限不足时返回业务错误。

字段类型必填说明示例
oneOf#1.codeinteger enum是0 表示所有指定消息均已删除。0
oneOf#1.msgstring enum是成功提示。消息删除成功
oneOf#1.dataobject是成功时为 null。
oneOf#2.codestring enum是分别表示某个 ID 非数字、消息不存在或需要管理员权限。message-4 | message-5 | message-30
oneOf#2.msgstring是具体错误原因。
oneOf#2.datastring enum是业务错误时为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": {} }

调用示例

curl -X DELETE \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/messages/{message_id}'
用户 API / 转发与数据 / 消息 / 获取消息完整详情

GET获取消息完整详情

GET /v1/messages/{message_id}

按 ID 返回 `message` 表的完整消息记录(包含正文及发送状态字段)。接口要求登录。若消息指定了 `receive` 且其值不是当前用户 ID,则仅管理员可查看;服务端不额外检查 `is_show`,因此已登录用户可读取未指定接收者的隐藏消息详情。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
message_idpathinteger是消息 ID。路由只匹配整数;不存在时返回业务错误。

响应

HTTP 200

成功、消息不存在、接收者权限不足及认证错误均返回 HTTP 200。成功响应的 `msg` 固定为空字符串。

字段类型必填说明示例
oneOf#1.codeinteger enum是0 表示查询成功。0
oneOf#1.msgstring enum是详情查询成功时固定为空字符串。
oneOf#1.dataobject是消息表完整记录。布尔数据库字段按 0/1 数值返回。
oneOf#1.data.idinteger是消息 ID。
oneOf#1.data.typestring是消息类型,例如 announcement。
oneOf#1.data.pub_userinteger是发布者用户 ID。
oneOf#1.data.receiveinteger是指定接收用户 ID;为空表示未指定单个接收者。
oneOf#1.data.titlestring是消息标题。
oneOf#1.data.contentstring是站内消息正文;外部链接消息通常为空字符串。
oneOf#1.data.phone_contentstring是短信发送正文。
oneOf#1.data.templ_idstring是消息发送模板 ID。
oneOf#1.data.templ_parastring是模板参数文本。
oneOf#1.data.event_idstring是关联事件标识。
oneOf#1.data.user_package_idinteger是关联用户套餐 ID。
oneOf#1.data.site_idinteger是关联网站 ID。
oneOf#1.data.is_showinteger enum是展示标记:1 展示,0 隐藏。0 | 1
oneOf#1.data.is_redinteger enum是红色标题标记。0 | 1
oneOf#1.data.is_boldinteger enum是粗体标题标记。0 | 1
oneOf#1.data.is_externalinteger enum是外部链接标记:1 使用 url,0 使用 content。0 | 1
oneOf#1.data.is_popupinteger enum是弹窗显示标记。0 | 1
oneOf#1.data.email_need_sendinteger enum是是否需要发送邮件通知。0 | 1
oneOf#1.data.phone_need_sendinteger enum是是否需要发送短信通知。0 | 1
oneOf#1.data.email_is_sentinteger enum是邮件是否已发送。0 | 1
oneOf#1.data.phone_is_sentinteger enum是短信是否已发送。0 | 1
oneOf#1.data.urlstring是外部消息跳转地址。
oneOf#1.data.sortinteger是排序值。
oneOf#1.data.create_atstring(date-time)是消息创建时间。
oneOf#1.data.update_atstring(date-time)是消息更新时间。
oneOf#2.codestring enum是分别表示消息不存在、指定接收者消息需要管理员权限或认证失败。message-18 | message-32 | login_required
oneOf#2.msgstring是具体错误原因。
oneOf#2.datastring enum是业务错误时为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": { "id": 0, "type": "string", "pub_user": 0, "receive": 0, "title": "string", "content": "string", "phone_content": "string", "templ_id": "string", "templ_para": "string", "event_id": "string", "user_package_id": 0, "site_id": 0, "is_show": 0, "is_red": 0, "is_bold": 0, "is_external": 0, "is_popup": 0, "email_need_send": 0, "phone_need_send": 0, "email_is_sent": 0, "phone_is_sent": 0, "url": "string", "sort": 0, "create_at": "string", "update_at": "string" } }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/messages/{message_id}'
用户 API / 转发与数据 / 消息 / 更新指定消息

PUT更新指定消息

PUT /v1/messages/{message_id}

更新指定消息的可编辑字段。接口要求管理员身份,路径中的 `message_id` 会覆盖请求体可能携带的 `id`。请求体必须为对象;所有业务字段均可省略,空对象也会成功并只更新 `update_at`。更新后的站内消息必须保有非空 `content`,外部链接消息必须保有非空 `url`。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
message_idpathinteger是要更新的消息 ID,必须存在。

请求体

请求体必填。

Content-Type:application/json

更新字段。`id` 即使传入也会被路径参数替换,建议不要传。所有下列字段均为可选;未传字段保留原值。

字段类型必填说明示例
idinteger否会被路径 `message_id` 覆盖,不应依赖该值。
typestring enum否可选消息类型;提供时只能为 announcement。announcement
titlestring否可选的新标题;提供时不能为空。维护时间调整
contentstring否可选站内正文。消息最终为非外部链接时必须非空。维护窗口已调整为 01:00 至 02:00。
is_externalinteger enum否可选外部链接标记:1 时最终 url 必须非空;0 时最终 content 必须非空。0 | 1
urlstring否可选外部链接地址。消息最终为外部链接时必须非空。https://www.example.invalid/notice
is_showinteger enum否可选展示标记:1 展示,0 隐藏。0 | 1
is_redinteger enum否可选红色标题样式标记。0 | 1
is_boldinteger enum否可选粗体标题样式标记。0 | 1
is_popupinteger enum否可选弹窗展示标记。0 | 1
sortinteger否可选排序值;服务端要求数字。200

请求体示例

{ "id": 0, "type": "string", "title": "维护时间调整", "content": "维护窗口已调整为 01:00 至 02:00。", "is_external": 0, "url": "https://www.example.invalid/notice", "is_show": 0, "is_red": 0, "is_bold": 0, "is_popup": 0, "sort": 200 }

响应

HTTP 200

成功和业务错误均返回 HTTP 200。更新成功时 `data` 为 null;路径消息不存在、字段校验失败、最终正文/链接条件不满足或非管理员访问时返回业务错误。

字段类型必填说明示例
oneOf#1.codeinteger enum是0 表示更新成功。0
oneOf#1.msgstring enum是成功提示。更新消息成功
oneOf#1.dataobject是成功时为 null。
oneOf#2.codestring enum是请求体非对象、消息不存在、类型/标题/样式/排序错误、外链 URL 或站内正文为空、管理员权限不足等业务错误码。message-2 | message-6 | message-7 | message-8 | message-9 | message-11 | message-15 | message-16 | message-17 | message-22 | message-23 | message-24 | message-25 | message-26 | message-31
oneOf#2.msgstring是具体错误原因。
oneOf#2.datastring enum是业务错误时为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": {} }

调用示例

curl -X PUT \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"id":0,"type":"string","title":"维护时间调整","content":"维护窗口已调整为 01:00 至 02:00。","is_external":0,"url":"https://www.example.invalid/notice","is_show":0,"is_red":0,"is_bold":0,"is_popup":0,"sort":200}' \ 'https://master.example.com/v1/messages/{message_id}'
用户 API / 转发与数据 / 任务

任务

任务

接口列表

GET
/v1/jobs
查询当前用户的任务申请记录 — 分页查询当前登录用户创建的任务申请及其关联执行任务状态,按任务申请 ID 倒序返回。可按任务类型、两个业务索引字段和创建时间筛选,limit=0 时返回全部匹配
POST
/v1/jobs
提交异步业务任务 — 提交缓存刷新或预热、IP 解锁、白名单清理、网站访问日志下载等异步任务。需要登录。请求可为一个任务对象或非空任务对象数组;服务端依次校验并在同一事务中创建全部任
用户 API / 转发与数据 / 任务 / 查询当前用户的任务申请记录

GET查询当前用户的任务申请记录

GET /v1/jobs

分页查询当前登录用户创建的任务申请及其关联执行任务状态,按任务申请 ID 倒序返回。可按任务类型、两个业务索引字段和创建时间筛选,limit=0 时返回全部匹配记录。注意:当 type 精确传 backup 时,服务端使用独立查询条件,不再按当前用户 ID 限制结果;该行为按当前 Python 主控实现保留。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,默认 1。服务端仅校验为数字,分页偏移为 (page - 1) × limit。
limitqueryinteger(int32)否每页记录数,默认 10。传字符串 0 时不附加 SQL limit,返回全部匹配记录。
typequerystring否任务类型筛选。可用逗号分隔多个仅含字母、数字、下划线或连字符的类型,例如 clean_url,unlock_ip;精确值 backup 使用特殊查询逻辑,不按当前用户 ID 过滤。clean_url,pre_cache_url
key1querystring否精确筛选任务申请的 key1 字段。该字段由创建任务时的具体业务类型写入,例如缓存任务的域名。
key2querystring否精确筛选任务申请的 key2 字段。该字段由创建任务时的具体业务类型写入,例如缓存任务的 URL。
startquerystring否创建时间下限,筛选 create_at 大于或等于该值。服务端直接将值交给数据库比较,不在接口层校验格式。2026-01-01 00:00:00
endquerystring否创建时间上限(不含),筛选 create_at 小于该值。服务端直接将值交给数据库比较,不在接口层校验格式。2026-01-02 00:00:00

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功响应包含 code、count、data,不含 msg;分页参数、type 格式不正确或登录失效时返回统一业务错误封装。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.countinteger(int64)是当前筛选条件下、未应用分页前的任务申请总数。
oneOf#1.dataarray是当前页任务申请记录,按 job.id 倒序排列。
oneOf#1.dataarray<object>否当前页任务申请记录,按 job.id 倒序排列。
oneOf#1.data[].enableinteger否关联 task 的启用标记;没有关联执行任务时为 null。
oneOf#1.data[].idinteger(int64)是任务申请(job)ID。
oneOf#1.data[].uidinteger(int64)是创建该任务申请的用户 ID。
oneOf#1.data[].typestring是任务类型,例如 clean_url、clean_dir、pre_cache_url、cancel_task、unlock_ip、clean_white_ip 或 down_http_access_log。
oneOf#1.data[].key1string否任务业务索引字段 1,具体含义取决于任务类型。
oneOf#1.data[].key2string否任务业务索引字段 2,具体含义取决于任务类型。
oneOf#1.data[].datastring是创建任务时保存的 JSON 文本;接口不解析该字段,具体键由任务类型决定。
oneOf#1.data[].create_atstring(date-time)是数据库返回的任务申请创建时间。
oneOf#1.data[].task_idinteger(int64)是关联 task 的 ID。
oneOf#1.data[].create_at2string是格式化后的任务申请创建时间,格式为 YYYY-MM-DD HH:mm:ss。
oneOf#1.data[].end_atstring(date-time)否关联 task 的结束时间;任务未结束或无关联任务时为 null。
oneOf#1.data[].statestring否关联 task 的执行状态,例如 pending、running、success 或 failed;无关联任务时为 null。
oneOf#1.data[].retstring否关联 task 的返回内容或错误信息;无返回内容时为 null。
oneOf#1.data[].progressstring否关联 task 的进度文本;无进度信息时为 null。
oneOf#2.codestring enum是page 或 limit 格式错误、type 含非法字符或认证失败的业务错误码。job-21 | job-22 | job-41 | login_required
oneOf#2.msgstring是具体错误原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/jobs'
用户 API / 转发与数据 / 任务 / 提交异步业务任务

POST提交异步业务任务

POST /v1/jobs

提交缓存刷新或预热、IP 解锁、白名单清理、网站访问日志下载等异步任务。需要登录。请求可为一个任务对象或非空任务对象数组;服务端依次校验并在同一事务中创建全部任务,任一项失败会回滚。任务结果和执行状态可通过 GET /v1/jobs 查询。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求体

请求体必填。

Content-Type:application/json

字段类型必填说明示例
oneOf#1.typestring enum是任务类型:clean_url 刷新 URL,clean_dir 刷新目录,pre_cache_url 预热 URL,cancel_task 使用与缓存任务相同的 URL 校验流程,unlock_ip 解锁 IP,clean_white_ip 清理网站白名单 IP,down_http_access_log 申请下载网站访问日志。clean_url | clean_dir | pre_cache_url | cancel_task | unlock_ip | clean_white_ip | down_http_access_log
oneOf#1.dataobject是任务参数对象。字段是否必填由 type 决定:缓存类任务必须提供 url;IP 解锁和白名单清理必须提供 site_id;访问日志下载必须提供 start 和 end。
oneOf#1.data.urlstring(uri)否clean_url、clean_dir、pre_cache_url 或 cancel_task 必填。必须是 HTTP/HTTPS URL,域名必须属于当前用户或调用者为管理员;clean_dir 的 URL 必须以 / 结尾。
oneOf#1.data.site_idinteger(int64)否unlock_ip 或 clean_white_ip 必填。网站 ID;非管理员只能操作自己的网站。unlock_ip 可传 0 表示不绑定具体网站。
oneOf#1.data.ipstring否unlock_ip 可选。以空白字符分隔的一个或多个待解锁 IP,每个必须是合法 IP;未提供时服务端使用 __all__ 表示解锁全部。单次数量受系统 ip-unlock-max-per-limit 配置限制。
oneOf#1.data.key1string否unlock_ip 或 clean_white_ip 可选的业务索引字段名。前端通常传 site_id,服务端会取 data[key1] 写入任务 key1。
oneOf#1.data.key2string否unlock_ip 或 clean_white_ip 可选的第二业务索引字段名。服务端会取 data[key2] 写入任务 key2。
oneOf#1.data.startstring否down_http_access_log 必填。日志开始时间,格式必须为 YYYY-MM-DD HH:mm:ss。
oneOf#1.data.endstring否down_http_access_log 必填。日志结束时间,格式必须为 YYYY-MM-DD HH:mm:ss;结束与开始的间隔不得超过 25 小时。
oneOf#1.data.hoststring否down_http_access_log 可选。以空白字符分隔的域名筛选;非管理员提供的每个域名都必须属于自己。
oneOf#1.data.addrstring否down_http_access_log 可选。按客户端 IP 筛选,提供时必须为合法 IP。
oneOf#1.data.req_uristring否down_http_access_log 可选。按请求 URI 筛选,提供时必须以 / 开头。
oneOf#1.data.statusstring否down_http_access_log 可选。按三位 HTTP 状态码筛选。
oneOf#1.data.cache_statusstring enum否down_http_access_log 可选。缓存状态筛选,只允许 HIT 或 MISS。HIT | MISS
oneOf#1.data.server_portstring否down_http_access_log 可选。按源端口筛选,提供时必须为数字。
oneOf#1.data.node_idstring否down_http_access_log 可选。按节点 ID 筛选,提供时必须为数字。
oneOf#2array<object>否批量提交的任务对象数组。服务端按数组顺序处理,成功响应 data 中的任务 ID 与此顺序一致。
oneOf#2[].typestring enum是任务类型。clean_url | clean_dir | pre_cache_url | cancel_task | unlock_ip | clean_white_ip | down_http_access_log
oneOf#2[].dataobject是任务参数。缓存类使用 url;IP 类使用 site_id、ip、key1/key2;日志下载使用 start/end 及可选筛选字段。
oneOf#2[].data.urlstring否缓存类任务必填的 HTTP/HTTPS URL;clean_dir 必须以 / 结尾。
oneOf#2[].data.site_idinteger(int64)否IP 解锁或白名单清理任务必填的网站 ID。
oneOf#2[].data.ipstring否IP 解锁任务可选的空白分隔 IP 列表。
oneOf#2[].data.key1string否可选业务索引字段名,常用值 site_id。
oneOf#2[].data.key2string否可选第二业务索引字段名。
oneOf#2[].data.startstring否日志下载必填开始时间,YYYY-MM-DD HH:mm:ss。
oneOf#2[].data.endstring否日志下载必填结束时间,YYYY-MM-DD HH:mm:ss,时间范围最多 25 小时。
oneOf#2[].data.hoststring否日志下载可选域名筛选。
oneOf#2[].data.addrstring否日志下载可选 IP 筛选。
oneOf#2[].data.req_uristring否日志下载可选 URI 筛选,必须以 / 开头。
oneOf#2[].data.statusstring否日志下载可选三位状态码。
oneOf#2[].data.cache_statusstring enum否日志下载可选缓存状态。HIT | MISS
oneOf#2[].data.server_portstring否日志下载可选数字端口。
oneOf#2[].data.node_idstring否日志下载可选数字节点 ID。

请求体示例

{ "type": "string", "data": { "url": "string", "site_id": 0, "ip": "string", "key1": "YOUR_KEY1", "key2": "YOUR_KEY2", "start": "string", "end": "string", "host": "string", "addr": "string", "req_uri": "string", "status": "string", "cache_status": "string", "server_port": "string", "node_id": "string" } }

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功时返回新建任务申请 ID 的字符串数组;请求格式、任务类型、业务对象归属、限额或参数校验失败时返回业务错误封装。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.msgstring enum是提交成功提示。添加成功
oneOf#1.dataarray是已创建的 job ID 字符串数组,与请求任务顺序一致。
oneOf#1.dataarray<string>否已创建的 job ID 字符串数组,与请求任务顺序一致。
oneOf#2.codestring enum是请求格式、任务类型、任务参数、资源归属、每日限额或登录状态相关的业务错误码。job-1 | job-2 | job-3 | job-5 | job-6 | job-9 | job-15 | job-17 | job-18 | job-19 | job-20 | job-25 | job-26 | job-27 | job-29 | job-30 | job-31 | job-32 | job-33 | job-34 | job-35 | job-36 | job-37 | job-38 | job-39 | job-40 | job-42 | job-43 | job-44 | job-45 | job-46 | job-47 | job-48 | login_required
oneOf#2.msgstring是具体错误原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "msg": "string", "data": [] }

调用示例

curl -X POST \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{"type":"string","data":{"url":"string","site_id":0,"ip":"string","key1":"YOUR_KEY1","key2":"YOUR_KEY2","start":"string","end":"string","host":"string","addr":"string","req_uri":"string","status":"string","cache_status":"string","server_port":"string","node_id":"string"}}' \ 'https://master.example.com/v1/jobs'
用户 API / 转发与数据 / 日志

日志

用户登录和操作日志。

接口列表

GET
/v1/log/login
查询登录日志 — 分页查询登录记录,按日志 ID 倒序返回。普通用户只能查看自己的记录;管理员可查看所有记录,或使用 uid 仅查看指定用户。支持按登录 IP、成功状态和创建时间
GET
/v1/log/op
查询操作日志 — 分页查询资源新增、更新和删除等操作日志,按日志 ID 倒序返回。普通用户只能查看自己的操作;管理员可查询全部日志或用 uid 筛选指定用户。支持按 IP、时间、
用户 API / 转发与数据 / 日志 / 查询登录日志

GET查询登录日志

GET /v1/log/login

分页查询登录记录,按日志 ID 倒序返回。普通用户只能查看自己的记录;管理员可查看所有记录,或使用 uid 仅查看指定用户。支持按登录 IP、成功状态和创建时间筛选,limit=0 时返回全部匹配记录。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,默认 1。服务端仅校验为数字,分页偏移为 (page - 1) × limit。
limitqueryinteger(int32)否每页记录数,默认 10;传 0 时不附加 SQL limit,返回全部匹配记录。
uidqueryinteger(int64)否仅管理员有效:精确筛选用户 ID。普通用户传入该参数仍只会查询自己的登录日志。
ipquerystring否按登录 IP 进行包含匹配,不要求完整 IP。198.51.100
successquerystring否精确筛选登录结果。通常传 1 查询成功记录,传 0 查询失败记录;服务端直接将非空值交给数据库比较,不在接口层校验取值。
startquerystring否创建时间下限,筛选 create_at 大于或等于该值。服务端直接交给数据库比较。2026-01-01 00:00:00
endquerystring否创建时间上限(不含),筛选 create_at 小于该值。服务端直接交给数据库比较。2026-01-02 00:00:00

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功响应含 code、count、data,不含 msg;页码、每页数量或认证失败时返回业务错误封装。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.countinteger(int64)是当前权限和筛选条件下、未应用分页前的登录日志总数。
oneOf#1.dataarray是当前页登录日志,按 id 倒序排列。
oneOf#1.dataarray<object>否当前页登录日志,按 id 倒序排列。
oneOf#1.data[].idinteger(int64)是登录日志 ID。
oneOf#1.data[].uidinteger(int64)是尝试登录的用户 ID;无法对应用户时为 null。
oneOf#1.data[].ipstring是客户端登录 IP 地址。
oneOf#1.data[].ip_locationstring是服务端根据 IP 记录的地理位置,格式通常为 国家-省份-城市。
oneOf#1.data[].successinteger enum是登录结果的数据库布尔值:1 为成功,0 为失败;数据库字段为空时为 null。0 | 1
oneOf#1.data[].create_atstring是格式化后的登录时间,格式为 YYYY-MM-DD HH:mm:ss。
oneOf#1.data[].create_at2string是与 create_at 相同的格式化登录时间字段,兼容前端展示。
oneOf#2.codestring enum是page 格式错误、limit 格式错误或认证失败的业务错误码。log_login-1 | log_login-2 | login_required
oneOf#2.msgstring是具体错误原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/log/login'
用户 API / 转发与数据 / 日志 / 查询操作日志

GET查询操作日志

GET /v1/log/op

分页查询资源新增、更新和删除等操作日志,按日志 ID 倒序返回。普通用户只能查看自己的操作;管理员可查询全部日志或用 uid 筛选指定用户。支持按 IP、时间、资源类别、操作动作、操作对象和变更内容筛选,limit=0 时返回全部匹配记录。

鉴权

除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。

请求参数

名称位置类型必填说明示例
pagequeryinteger(int32)否页码,默认 1。服务端仅校验为数字,分页偏移为 (page - 1) × limit。
limitqueryinteger(int32)否每页记录数,默认 10;传 0 时不附加 SQL limit,返回全部匹配记录。
uidqueryinteger(int64)否仅管理员有效:精确筛选操作用户 ID。普通用户提供此参数仍只查询自己的日志。
ipquerystring否按客户端 IP 进行包含匹配,不要求完整 IP。198.51.100
startquerystring否创建时间下限,筛选 create_at 大于或等于该值。服务端直接交给数据库比较。2026-01-01 00:00:00
endquerystring否创建时间上限(不含),筛选 create_at 小于该值。服务端直接交给数据库比较。2026-01-02 00:00:00
typequerystring否精确筛选资源类别,即日志中的 type,例如 网站、任务、证书或 ACL。
actionquerystring否精确筛选操作动作。通用写入逻辑使用 新增、更新、删除。
contentquerystring否按操作对象内容进行包含匹配,例如资源 ID 或以逗号分隔的资源 ID。
diffquerystring否按字段变更内容进行包含匹配。该字段通常保存更新前后差异的文本或 JSON 文本。

响应

HTTP 200

业务结果使用 HTTP 200 返回。成功响应含 code、count、data,不含 msg;页码、每页数量或认证失败时返回统一业务错误封装。

字段类型必填说明示例
oneOf#1.codeinteger enum是成功状态码,固定为 0。0
oneOf#1.countinteger(int64)是当前权限和筛选条件下、未应用分页前的日志总数。
oneOf#1.dataarray是当前页操作日志,按 id 倒序排列。
oneOf#1.dataarray<object>否当前页操作日志,按 id 倒序排列。
oneOf#1.data[].idinteger(int64)是操作日志 ID。
oneOf#1.data[].uidinteger(int64)是执行操作的用户 ID。
oneOf#1.data[].typestring是资源类别,例如 网站、任务、证书、ACL。
oneOf#1.data[].actionstring是操作动作,通用写入逻辑为 新增、更新 或 删除。
oneOf#1.data[].contentstring是被操作对象的标识文本,通常为资源 ID 或逗号分隔的资源 ID。
oneOf#1.data[].diffstring是字段变更详情文本或 JSON 文本;新增、删除操作通常为空。
oneOf#1.data[].ipstring是执行操作的客户端 IP。
oneOf#1.data[].ip_locationstring是服务端根据 IP 记录的地理位置,格式通常为 国家-省份-城市。
oneOf#1.data[].create_atstring(date-time)是数据库返回的操作创建时间。
oneOf#1.data[].processstring是操作处理标记;通用新增、更新、删除写入时为空字符串。
oneOf#1.data[].create_at2string是格式化后的操作时间,格式为 YYYY-MM-DD HH:mm:ss。
oneOf#2.codestring enum是page 格式错误、limit 格式错误或认证失败的业务错误码。log_op-1 | log_op-2 | login_required
oneOf#2.msgstring是具体错误原因。
oneOf#2.datastring enum是业务错误时固定为空字符串。

响应示例

{ "code": 0, "count": 0, "data": [] }

调用示例

curl \ -H 'api-key: YOUR_API_KEY' \ -H 'api-secret: YOUR_API_SECRET' \ 'https://master.example.com/v1/log/op'
用户 API / Schemas

Schemas

本组包含以下接口,点击卡片进入详情。

接口列表

ApiResponse
ApiResponse
用户 API / Schemas / ApiResponse

ApiResponse

用户 API 通用响应封装结构。

字段

字段类型必填说明示例
codeoneOf是0 表示成功;字符串表示业务错误码。0
code(oneOf#1)integer否
code(oneOf#2)string否
msgstring是结果说明。
dataobject是业务数据;结构以具体接口示例为准。
countinteger(int64)否分页查询的总记录数。