不死鸟 CDN 文档中心
把你的域名接入不死鸟 CDN,最快 5 分钟完成。下面是最常用的入口,照着做即可。
接入过程中有任何疑问,随时通过 Telegram @cdnbsn 联系客服。
把你的域名接入不死鸟 CDN,最快 5 分钟完成。下面是最常用的入口,照着做即可。
接入过程中有任何疑问,随时通过 Telegram @cdnbsn 联系客服。
接入只需准备好以下 3 样东西。有疑问随时联系客服。
domain.com、a.domain.com)和泛域名(*.domain.com)。👉 接入前可用域名查询工具检查健康状况,并参考 《域名保护小技巧》。
你网站的真实服务器地址,需在国内可正常访问。被墙的 IP 接入后同样无法访问。
三项就绪后,即可前往 开始接入。
整个流程共 4 步,最快 5 分钟 完成。开始前请确认已满足准备条件。
全程在 控制台 内操作,请先登录。
进入 网站管理 → 我的网站 → 新增,填写域名和源站 IP。多个域名用空格隔开,可一次性添加。


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

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

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

解析生效时间由域名服务商决定,快则几秒、慢则几小时,请耐心等待。
用 Cloudflare 或其他一些海外解析平台给根域名(@)做 CNAME 时,往往会触发 CNAME 拉平(CNAME Flattening / ALIAS):解析结果被提前解析成固定 IP。这样一来,国内访客本来应走到香港 CN2 高防节点,却可能被拉到美国等海外节点,访问会异常缓慢。
解决方法:
www 或其他子域名),只给该二级域名做 CNAME。gname.com、dynadot.com 等平台购买 / 解析域名——这些平台不会把 CNAME 拉平,根域名可正常指向不死鸟 CDN 的 CNAME。用 Cloudflare 或其他一些海外解析平台给根域名(@)做 CNAME 时,往往会触发 CNAME 拉平(CNAME Flattening / ALIAS):解析结果被提前解析成固定 IP。这样一来,国内访客本来应走到香港 CN2 高防节点,却可能被拉到美国等海外节点,访问会异常缓慢。
解决方法:
www 或其他子域名),只给该二级域名做 CNAME。gname.com、dynadot.com 等平台购买 / 解析域名——这些平台不会把 CNAME 拉平,根域名可正常指向不死鸟 CDN 的 CNAME。根据你是否已有证书,二选一:
情况 A:没有证书(推荐)
在控制台 一键申请 免费证书,平台自动续期、无需手动维护。
⚠️ 申请前需确保所有域名解析都已生效,否则无法签发。


绝大多数是域名解析未正确配置导致。可在 网站管理 → 证书管理 查看状态;确认解析无误后,编辑证书切换签发机构再点「重签」。
情况 B:已有证书
前往 网站管理 → 证书管理,上传并选用你的证书。


最后:打开 HTTPS 开关

域名已成功接入 CDN!
以上为快速接入配置,缓存、防御等均使用平台预设,开箱即用。如有特殊需求,可在控制台按需调整。
网站接入后,防护默认为关闭。一旦遇到突发强力 CC 攻击,源站可能因扛不住海量请求而宕机。建议接入完成后开启自动切换策略,让平台在攻击来临时自动启用人机验证。
推荐配置如下:

CC 规则不固定,可按网站实际需求自行调整。更多说明见 《自定义 CC 规则》。
50x 基本都是回源异常。按下面顺序逐一排查,绝大多数能快速定位。
先在未套 CDN 的情况下直接访问源站。如果源服务本身就打不开,套上 CDN 当然也访问不了——先把源站修好。
概率较小,等几分钟再试。
如果用了宝塔等控制面板并开了防御,会挡住 CDN 回源。套 CDN 后,宝塔的基础防御可以关闭,防御工作交给 CDN 承担;如需保留防御,则要给 CDN 回源 IP 开白名单。
详见 《宝塔部署接入须知》。未使用宝塔的,请排查服务器防火墙是否拦截了 CDN 回源。
前往 网站管理 → 监控统计 → 黑名单 IP,查看是否有本机 IP 在内。若在,则是误封,先解除该 IP。这说明当前防御规则不适合你的业务,建议切换为 默认-宽松,提升-50-旋转图片,可满足绝大部分需求。
部分小厂商的低质量服务器 IP 容易进运营商黑名单,被拉黑后会不定时无法连通,需等待恢复。
同样适用于其他类宝塔的面板控制工具。接入前请逐项检查。
宝塔站点支持通配符绑定,确保绑定的域名包含了在 CDN 平台添加的域名。
若宝塔未配置强制 HTTPS 回源,此步可跳过。若宝塔配置了 SSL 且强制 HTTPS 访问,则 CDN 需走 HTTPS 443 回源,否则会报 50x;443 回源需在 CDN 平台配置证书。
关闭宝塔的「强制 SSL 访问」,让 CDN 走 80 端口回源。80 回源比 443 更快、配置项更少。证书安全由 CDN 承担,可在平台一键配置并自动续期。
某些服务会改动 Nginx 配置文件。若套 CDN 后无法访问,也需排查此处。未改动过则默认没问题。
套上 CDN 后速度一般不会变慢。如果慢或一直加载中,多半是某处出了问题。
最常见的原因是加载第三方资源时等待过久,导致页面渲染卡住。例如下面这个案例:

案例中 jquery、layer 加载失败,而页面渲染依赖这两个库,于是白屏。可单独访问这些库的源地址,大概率也是失败或很慢。
案例原本使用 Staticfile 源:
cdn.staticfile.org/layer/3.1.1/layer.min.jscdn.staticfile.org/jquery/1.12.4/jquery.min.js换成 360 的源试试:
lib.baomitu.com/jquery/1.12.4/jquery.min.jslib.baomitu.com/layer/3.1.1/layer.min.js已知 Staticfile、BootCDN 存在访问慢的情况,请按需更换合适的源。若担心第三方不稳定,可把工具库放进项目中加载(public 静态资源方式)。
如仍无法解决,请联系客服协助。
回调是第三方服务合法请求你的服务器。CDN 默认可能拦截这类请求,需要手动放行、告诉 CDN 它是合法的。



匹配条件很多,原理都一样——按你的实际需求配置即可。
很多场景需要实时传输,例如镜像站中的 AI 聊天。实时传输(含流式传输)需要开启 WebSocket。

每个站点的技术实现不同,开了不一定立刻生效。检查缓存内容,移除 JS 缓存,一般即可解决。
访问时浏览器提示此信息,需手动点击确认后才能继续。

这是站点内存在 HTTPS 向 HTTP 跳转 导致,触发了浏览器的安全机制。需在站点内处理好全程 HTTPS 访问,避免回退到 HTTP。
平台可抵御绝大多数 CC 攻击。规则不固定,按网站需求自行配置。

正常添加网站后防护默认关闭,遇到突发强力 CC 攻击会导致源站被打宕机。建议开启自动切换(阈值一般 50 即可),并提升到「点击验证 / 滑块验证 / 旋转图片」之一。当请求量超过阈值时,访客会被要求执行所设规则。
域名是网站的门面,也是最容易被攻击的环节,保护好域名至关重要。
注:国内备案域名出现以下情况的概率很低,多见于境外 IP。
域名异常分为被墙、被污染、被劫持、被运营商禁用等多种行为。下面介绍最常见的几种:
域名被墙必有原因,被拉入 GFW 黑名单后放出的可能性极低。首先确认站点内容不存在非法内容。
在确认无非法内容的前提下,可多备域名用引导页分发,或从技术上彻底拦死爬虫。也可做 301 跳转,将旧域名永久跳转到新域名(有专门服务,价格较高)。
与站点内容无关。表现为:查询自己域名解析时出现一堆陌生的乱解析记录,访问到的也不是自己的站点(通常是非法内容)。
已知在 GoDaddy、Cloudflare 购买的域名风险较高(未列出的不代表一定安全)。如未购买其高级保护服务,强烈建议把 DNS 解析配置到 腾讯 DNSPod(推荐) 或阿里万网等国内大厂,默认自带防护。
市面上有些"黑科技"号称可解决,未经实测。
建议把 DNS 解析迁回国内,有条件的可购买高级服务并开启 DNSSEC。
较出名的是移动屏蔽("墙中墙",GFW 不墙但移动墙)。套 CDN 不一定能 100% 解决,判定过程很复杂,只能尝试。它和被墙一样分 IP 被墙与域名被墙,需先确认再想办法。地方运营商禁用(如某些地区电信常年无法访问)基本无解;某些地区短期解析到 0.0.0.0 或解析失败,多为当地运营商拦截,一般会恢复,可用网络拨测工具查看解析情况。
做好反爬虫,保证站内无非法内容——运营商不会无缘无故禁用。
都不易解决。可尝试拨打国家反诈中心要求解封:010-67825170。苏州地区可在微信搜索"苏州市反通信网络诈骗中心",进入「封停申述 → 网站域名」填写申述表提交。
域名被污染后内容被替换成非法内容,而被污染域名不发生跳转、域名仍是你的,于是 GFW 误判该域名为非法站点并拉黑——这是一连串动作连带导致的。
这种情况建议直接放弃该域名。
如果你的域名很好,务必保护好,否则后悔莫及。
HSTS 是 IETF 推行的一种 Web 安全协议。网站采用 HSTS 后,用户访问时无需手动输入 HTTPS,浏览器会自动以 HTTPS 访问,从而始终走加密链接,保护数据传输安全。
307 Redirect Internal 响应码)。如果是 HTTPS 站点,建议开启。
不死鸟 CDN 默认未开启该选项(因为并非所有站点都需要 HTTPS 访问),需在站点配置中手动开启。
更新了源站内容、但 CDN 还在返回旧版本?用刷新清掉旧缓存、让 CDN 重新拉取最新内容;用预热提前把资源缓存到节点,提升首次访问速度。
入口:网站管理 → 对应站点 → 刷新预热。
支持三种粒度,按需选择:
https://你的域名/app.apk。https://你的域名/static/。提交后,节点会清除对应缓存,下次访问时重新回源拉取最新内容。
更新了图片、JS、安装包等已被缓存的资源后,记得刷新对应 URL,否则在缓存有效期内用户仍会看到旧版本。
避免频繁做全站刷新——会导致大量回源、瞬时拉高回源带宽。优先用按 URL / 按目录精确刷新。
提前把指定 URL 的资源缓存到各节点,用户首次访问即命中、无需等待回源。适合新发布的大文件(如新版 apk、活动素材)提前铺好。
平台默认缓存规则已覆盖常见文件类型。若你的站点有特殊需求,可自定义规则,精细控制哪些资源缓存、缓存多久。
入口:网站编辑 → 缓存配置。
jpg|png|mp4|apk。/static/。带登录态的页面、API 接口等动态内容应设为不缓存或缓存时间极短,否则用户可能看到他人页面或过期数据。
缓存规则从上到下匹配,匹配到即停止,注意排列顺序。
ACL 用于精细控制"谁能访问你的站点"。可针对 IP、域名、User-Agent、URL 等设置放行或封禁,多条规则可自由组合,实现复杂的访问策略。
入口:我的网站 → 安全配置(添加过滤规则)。
IP / IP 段、域名、User-Agent、URL、请求方法等,多条条件可组合使用。
规则从上到下匹配。放行规则要放在封禁规则之前,否则合法请求可能先被封禁规则拦掉。
如果你有多台源服务器,可在 CDN 配置多个源站,实现负载均衡与故障自动切换,提升稳定性与承载能力。
入口:网站编辑 → 源站设置。
多个源站的内容应保持一致,否则不同用户可能从不同源拿到不一样的结果。
回源相关报错(50x)排查见 《页面访问 50x 错误》。
在控制台可实时查看站点的关键指标,并下载访问日志用于排查问题。
入口:网站管理 → 监控统计 / 访问日志。
命中率偏低说明缓存效果不佳,可结合 《自定义缓存规则》 优化;回源质量差则可能是源站或线路问题。
不死鸟CDN 支持 JA4 TLS 指纹识别:根据客户端在 TLS 握手时暴露的特征来辨认它是谁,再配合 URI、请求头等维度一起判断,让防护从「认 IP」升级到「认客户端」。在控制台里,它对应 CC 匹配器中的两个匹配项:TLS指纹 和 独立TLS指纹数量。

| 短板 | 说明 |
|---|---|
| IP 太好换 | 代理池、VPN 能轻松拿到大量 IP,按 IP 限速基本拦不住。 |
| 容易误伤 | 公司、学校等场景里很多人共用一个出口 IP,按 IP 限速会把真实用户一起封掉。 |
| 绕过成本低 | 代理 IP 很便宜,攻击者换一批就能绕开封禁,防守方疲于追赶。 |
IP 只能说明请求「从哪里来」,说明不了「是谁发的」。要区分正常用户和攻击者,需要更深一层的特征。
JA4 根据 TLS 握手中的参数(TLS 版本、加密套件、扩展列表等)算出一个指纹字符串。它由客户端程序本身决定,换 IP 一般不会变:同一款攻击工具不管走多少代理,指纹往往一样;而真实浏览器的指纹与脚本工具明显不同。
| 对比项 | IP 地址 | JA4 指纹 |
|---|---|---|
| 能否代表身份 | 弱,可共享、可更换 | 强,跟客户端程序绑定 |
| 伪造难度 | 低,挂代理 / VPN 即可 | 高,需要改 TLS 底层实现 |
| NAT 后的多个用户 | 无法区分 | 能区分不同客户端 |
在 统计分析 → 访问日志 / 拉黑日志 中观察请求量异常的指纹:攻击者怎么换 IP 都没用,只要还用同一个工具,指纹就不会变。
把 请求URI / 请求URI(不带参数) 作为匹配条件,可以按路径设置不同强度的防护,例如对 /api/login 收紧,对 /static/ 放宽。
结合 请求头、浏览器UA、独立UA数量、国家代码、AS号码 等匹配项,可以识别缺少正常请求头的自动化工具,构建更贴合业务的规则。
统计同一个 IP 出现过多少种不同的指纹。正常用户一般只有 1~2 种,如果一个 IP 短时间内冒出 3 种以上,很可能是代理池或在随机伪造客户端。
在 CC规则 → 匹配器 → 添加匹配器(或网站的 安全设置 → 自定义规则)中,可以使用下面两个匹配项:
直接匹配客户端的 JA4 指纹值,精确识别并处理已知的恶意客户端。
| 配置项 | 填写 |
|---|---|
| 匹配项 | TLS指纹 |
| 操作符 | 等于、不等于、包含、不包含、前缀、后缀、正则匹配等 |
| 匹配值 | JA4 指纹字符串(从日志中复制),一行一个 |
| 动作 | 在规则组中选 拉黑 / 只记录,或在自定义规则中选验证类过滤 |
1. 在日志中找到异常指纹 → 2. 复制指纹字符串 → 3. 添加匹配器,匹配项选「TLS指纹」、操作符选「等于」,粘贴指纹 → 4. 在规则组里引用该匹配器,动作选「拉黑」。攻击者换再多 IP,只要用的是同一个工具,就会被拦下。
统计某个 IP 在一段时间内出现的不同指纹数量,用来发现代理池攻击。阈值设得明显高于正常访客即可,具体可用的操作符以控制台该匹配项为准。
设置「独立TLS指纹数量 大于 3 → 拉黑」。正常用户通常只有 1 个指纹,一个 IP 出现 3 个以上不同指纹,就是典型的代理池 / 攻击工具特征。
只靠一个维度总有盲区,多个维度组合起来才能形成立体防御:
TLS指纹 等于 可疑指纹 + 请求URI 前缀 /api/。TLS指纹 等于 已确认的恶意指纹。建议分三个阶段逐步上线,避免一次性开启造成误拦:
新规则的动作先设为 只记录,只写日志不拦截,在 统计分析 → 访问日志 / 拉黑日志 中摸清正常用户的指纹分布和请求频率。重点留意 APP、支付回调、搜索引擎爬虫、监控探针等非浏览器客户端,必要时先加放行规则。
根据观察结果,把规则逐步改为验证类过滤或 拉黑。先处理最明显的异常(比如某一个指纹占了绝大部分攻击流量)。
定期更新恶意指纹清单,调整统计周期和阈值。建议配合双过滤器:JA4 指纹做第一道筛选,传统验证兜底。攻击工具升级后指纹可能变化,记得复查。
TLS 指纹只存在于 HTTPS 请求中,使用前请确认网站已开启 HTTPS(见 第八章 和 3.2 HTTPS 设置)。不要把 Chrome、Safari 等常见浏览器的指纹加入封禁,否则会大面积误伤正常访客。
遇到攻击需要协助分析指纹,可联系 Telegram @cdnbsn。
调用需要身份验证的用户 API 时,可使用以下两种方式之一。
API 密钥长期有效,适合服务端程序、自动化任务等不便频繁登录的场景。
在用户后台的「账户中心 → API密钥」中开启后,可以获得 API Key 和 API Secret。调用 API 时,必须同时发送以下两个请求头:
api-key:填写 API Keyapi-secret:填写 API Secret请将示例中的主控域名、YOUR_API_KEY 和 YOUR_API_SECRET 替换为实际值。API Secret 仅在可信环境中保存和使用,不要写入前端代码或公开仓库。
Access Token 有有效期,适合登录后的临时调用。先通过登录接口获取令牌,再通过 access-token 请求头调用其他 API。
account 可以填写用户名、手机号或邮箱地址。登录成功后,响应的 data.access_token 即为访问令牌。
下文各接口页的调用示例统一使用 https://master.example.com 作为主控域名占位,接入时请替换为你的实际主控地址。
验证码、注册信息和公共配置。
GET /v1/common/captcha
生成一次性图形验证码图片。响应为 image/gif 二进制内容,并通过 code Cookie 返回加密验证码数据;Cookie 中的验证码有效期为 60 秒。该公共接口不要求登录,客户端应保存 Cookie 并在后续需要验证码的请求中携带。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
成功返回 GIF 图像,同时通过 Set-Cookie 写入加密验证码 Cookie。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
(root) | string(binary) | 否 | 验证码 GIF 图片二进制内容。 | |
GET /v1/common/captcha-type
获取登录/注册页面所需的验证码类型配置。接口读取系统 captcha_type 配置,并补充腾讯云验证码 appid、带有效期的加密 appid 令牌以及极验 captcha_id;未配置第三方验证码时对应字段为空字符串。该公共接口不要求登录。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
业务结果通过 HTTP 200 返回。成功时返回配置对象;系统维护或认证状态不影响该公共 GET 接口,数据库配置读取异常则不会生成业务错误响应。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer enum | 是 | 成功状态码,验证码配置读取成功时固定为 0。 | 0 |
msg | string enum | 是 | 配置读取成功时固定为空字符串。 | |
data | object | 是 | 系统验证码类型配置及服务端补充的第三方验证码参数。 | |
data.email | string | 是 | 邮箱验证码方式配置值,例如空字符串表示未启用。 | |
data.phone | string | 是 | 手机验证码方式配置值,例如 native 表示内置方式。 | |
data.appid | string | 是 | 腾讯云验证码 AppID;未配置时为空字符串。 | |
data.appid_encrypt | string | 是 | 使用腾讯云密钥加密的短期 AppID 参数;未配置时为空字符串,示例使用占位值。 | |
data.geetest_captcha_id | string | 是 | 极验验证码 captcha_id;未配置时为空字符串。 | |
GET /v1/common/menu
根据当前登录账号类型返回面板侧边栏菜单。管理员返回内置管理员菜单,普通用户读取用户菜单 JSON;菜单节点可包含名称、标题、图标、跳转地址、隐藏侧栏标记和嵌套子菜单。该接口需要登录,响应不包含业务分页信息。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
业务结果通过 HTTP 200 返回。认证成功时返回当前账号可见菜单数组;认证失效时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,菜单读取成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 菜单读取成功时固定为空字符串。 | |
oneOf#1.data | array | 是 | 当前账号可见的菜单节点,数组顺序决定面板显示顺序。 | |
oneOf#1.data | array<object> | 否 | 当前账号可见的菜单节点,数组顺序决定面板显示顺序。 | |
oneOf#1.data[].name | string | 否 | 菜单节点内部名称,用于前端路由或权限识别。 | |
oneOf#1.data[].title | string | 否 | 菜单显示标题。 具体说明 | |
oneOf#1.data[].icon | string | 否 | 菜单图标名称,可省略。 | |
oneOf#1.data[].jump | string | 否 | 点击菜单时使用的前端跳转地址,可省略。 | |
oneOf#1.data[].hideSider | boolean | 否 | 是否隐藏侧边栏,可省略。 | |
oneOf#1.data[].list | array | 否 | 嵌套子菜单节点,可省略。 | |
oneOf#1.data[].list | array<object> | 否 | 嵌套子菜单节点,可省略。 | |
oneOf#2.code | string enum | 是 | login_required 表示认证无效。 | login_required |
oneOf#2.msg | string | 是 | 认证失败原因。 具体说明 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/common/menu2
根据当前登录账号类型返回新版面板的侧边栏和顶部菜单。管理员与普通用户使用不同的侧边栏集合,但顶部菜单固定包含首页和日志入口。侧边栏节点使用 path、title、header、icon、children 和可选 auth;其中 auth 为 ['hidden'] 时表示该路由不在菜单中直接展示。该接口需要登录。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
业务结果通过 HTTP 200 返回。认证成功时返回 sider 和 header 菜单数组;认证失效时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,菜单读取成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 菜单读取成功时固定为空字符串。 | |
oneOf#1.data | object | 是 | 新版面板菜单集合。 | |
oneOf#1.data.sider | array | 是 | 侧边栏菜单节点数组。 | |
oneOf#1.data.sider | array<object> | 否 | 侧边栏菜单节点数组。 | |
oneOf#1.data.sider[].path | string | 是 | 前端页面路由,例如 /dashboard/site 或 /site/list。 | |
oneOf#1.data.sider[].title | string | 是 | 该侧边栏菜单项在面板中的显示名称。 | |
oneOf#1.data.sider[].header | string | 是 | 该菜单所属顶部导航标识,例如 home 或 system。 | |
oneOf#1.data.sider[].icon | string | 是 | 该侧边栏菜单项使用的前端图标名称。 | |
oneOf#1.data.sider[].auth | array | 否 | 可选的菜单展示控制标记;当前服务端中 ["hidden"] 表示隐藏该路由菜单项。 | |
oneOf#1.data.sider[].auth | array<string> | 否 | 可选的菜单展示控制标记;当前服务端中 ["hidden"] 表示隐藏该路由菜单项。 | |
oneOf#1.data.sider[].children | array | 否 | 可选的子菜单列表;子节点使用与父节点相同的 path、title 和可选 auth 字段。 | |
oneOf#1.data.sider[].children | array<object> | 否 | 可选的子菜单列表;子节点使用与父节点相同的 path、title 和可选 auth 字段。 | |
oneOf#1.data.sider[].children[].path | string | 是 | 子菜单对应的前端页面路由。 | |
oneOf#1.data.sider[].children[].title | string | 是 | 该子菜单项在面板中的显示名称。 | |
oneOf#1.data.sider[].children[].auth | array | 否 | 可选的菜单展示控制标记。 | |
oneOf#1.data.sider[].children[].auth | array<string> | 否 | 可选的菜单展示控制标记。 | |
oneOf#1.data.header | array | 是 | 顶部菜单节点数组。 | |
oneOf#1.data.header | array<object> | 否 | 顶部菜单节点数组。 | |
oneOf#1.data.header[].path | string | 否 | 前端页面路由;服务端固定返回 /dashboard/ 或 /log。 | |
oneOf#1.data.header[].title | string | 否 | 顶部菜单显示标题;服务端固定为首页或日志。 | |
oneOf#1.data.header[].icon | string | 否 | 顶部菜单图标名称。 | |
oneOf#1.data.header[].hideSider | boolean | 否 | 进入该顶部页面后是否隐藏左侧菜单栏。 | |
oneOf#1.data.header[].name | string | 否 | 顶部菜单内部标识;服务端固定为 home 或 system。 | |
oneOf#2.code | string enum | 是 | login_required 表示认证无效。 | login_required |
oneOf#2.msg | string | 是 | 认证失败原因。 具体说明 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/common/register-info
获取公开注册页面使用的字段要求和用户协议。配置由系统 register_require JSON 与 user_agreement JSON 合并返回;该公共接口不要求登录。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
配置读取成功时返回注册字段规则和用户协议;数据库配置读取异常不会转换为业务错误响应。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer enum | 是 | 成功状态码,注册配置读取成功时固定为 0。 | 0 |
msg | string enum | 是 | 配置读取成功时固定为空字符串。 | |
data | object | 是 | 公开注册字段要求及用户协议配置。 | |
data.username | object | 是 | 用户名注册规则。 | |
data.username.need | integer enum | 是 | 是否要求注册用户名:1 要求,0 不要求。 | 0 | 1 |
data.email | object | 是 | 邮箱注册规则。 具体说明 | |
data.email.need | integer enum | 是 | 是否要求填写邮箱。 | 0 | 1 |
data.email.verify | integer enum | 是 | 是否要求邮箱验证。 | 0 | 1 |
data.phone | object | 是 | 手机号注册规则。 | |
data.phone.need | integer enum | 是 | 是否要求填写手机号。 | 0 | 1 |
data.phone.verify | integer enum | 是 | 是否要求手机验证。 | 0 | 1 |
data.qq | object | 是 | QQ 注册规则。 | |
data.qq.need | integer enum | 是 | 是否要求填写 QQ。 | 0 | 1 |
data.user_agreement | object | 是 | 用户协议内容。 具体说明 | |
data.user_agreement.title | string | 是 | 用户协议显示标题。 | |
data.user_agreement.data | string | 是 | 用户协议、法律声明和隐私政策正文。 | |
GET /v1/common/sysinfo
读取系统展示配置并返回控制台标题、页脚版权、页脚链接和系统名称。该公共接口不要求登录,配置内容由管理员在系统设置中维护。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
配置读取成功时返回系统展示信息;数据库配置读取异常不会转换为业务错误响应。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer enum | 是 | 成功状态码,系统信息读取成功时固定为 0。 | 0 |
msg | string enum | 是 | 系统信息读取成功时固定为空字符串。 | |
data | object | 是 | 系统前端展示信息对象。服务端直接透传 system_info 配置;除已列字段外,管理员保存的其他展示配置也可能出现。 | |
data.footer_copyright | string | 是 | 前端页脚显示的版权文本。 | |
data.footer_link | string | 是 | 前端页脚链接配置:每行一个链接,行内以“显示名|URL”分隔。 | |
data.user_console_title | string | 是 | 用户控制台标题。 | |
data.admin_console_title | string | 是 | 管理员控制台标题。 | |
data.sys_name | string | 是 | 系统名称,供登录、注册等公开页面展示。 | |
data.js_code | string | 否 | 可选的前端注入 JavaScript 配置,例如统计或客服脚本。 | |
data.sub_title | string | 否 | 可选的公开页面副标题。 | |
登录、密码重置、验证码和登录策略。
POST /v1/email-captcha
向指定邮箱发送 6 位验证码,用于注册、找回密码或邮箱验证。该公共接口不要求登录。收件人可由 account 指定的已启用账号解析,或直接由 email 指定;两种方式不能混用。系统会按 captcha_type.email 配置校验原生图形验证码、腾讯云验证码或极验验证码;同一客户端 IP 在 60 秒内最多成功发送一次。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
code | cookie | string | 否 | 当系统邮箱验证码类型为 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 配置决定。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
account | string | 否 | 可选。已启用用户的邮箱、用户名或手机号;服务端据此取得该用户已配置的邮箱。提供时不能为空,且账号必须存在并已设置邮箱。 | |
email | string(email) | 否 | 未提供 account 时必填。直接接收验证码的邮箱地址,必须为合法邮箱格式。 | |
check_exist | integer enum | 否 | 未提供 account 时必填。邮箱存在性要求:0 表示邮箱必须不存在(通常用于注册);1 表示邮箱必须是已启用用户的邮箱(通常用于找回密码)。 | 0 | 1 |
code | string | 否 | 当 captcha_type.email 为 native 时必填。GET /v1/common/captcha 返回的图形验证码文本,按不区分大小写方式与 code Cookie 中的值比对;同一图形验证码一分钟内不能重复用于发送邮件。 | |
ticket | string | 否 | 当 captcha_type.email 为 qcloud 时必填。腾讯云验证码返回的票据。 | |
randstr | string | 否 | 当 captcha_type.email 为 qcloud 时必填。腾讯云验证码返回的随机字符串。 | |
lot_number | string | 否 | 当 captcha_type.email 为 geetest 时必填。极验验证结果中的 lot_number。 | |
captcha_output | string | 否 | 当 captcha_type.email 为 geetest 时必填。极验验证结果中的 captcha_output。 | |
pass_token | string | 否 | 当 captcha_type.email 为 geetest 时必填。极验验证结果中的 pass_token。 | |
gen_time | string | 否 | 当 captcha_type.email 为 geetest 时必填。极验验证结果中的 gen_time。 | |
业务结果始终使用 HTTP 200 返回。发送成功时 data 为 null;参数、收件人、验证码平台校验、频率限制和邮件发送失败均在同一响应中以业务错误码表示。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 发送成功提示。 | 发送成功! |
oneOf#1.data | string | 是 | 成功时为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 具体错误原因,例如邮箱已存在、验证码错误、请等待 60 秒后再获取或邮件发送失败。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
POST /v1/login
使用用户名、邮箱或手机号和密码登录,成功后返回 access_token。后续需要登录的接口应将该值放入 access-token 请求头。该接口本身不要求令牌。服务端会按客户端 IP 统计最近一小时失败次数:达到系统配置的封禁阈值将拒绝登录;达到图形验证码阈值且最近三次均未成功时,必须完成图形验证码校验。用户还可能配置邮件或短信登录验证码、登录 IP 白名单和登录域名限制。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
code | cookie | string | 否 | 仅当该客户端 IP 触发图形验证码登录校验时必填。携带 GET /v1/common/captcha 写入的 code Cookie;服务端会验证其加密内容和过期时间。未触发图形验证码时不使用该 Cookie。 | <encrypted-captcha-cookie> |
请求体必填。
Content-Type:application/json
登录凭据。code 仅在服务器要求图形验证码时使用;captcha 仅在用户已启用邮件或短信登录验证码时使用。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
account | string | 是 | 必填。用户名、邮箱地址或手机号;不能为空,且必须符合其中一种格式。 | |
password | string(password) | 是 | 必填。用户密码明文;服务端使用保存的 bcrypt 哈希验证。 | |
code | string | 否 | 条件必填。当当前 IP 达到系统图形验证码阈值且最近三次登录均未成功时,填写 GET /v1/common/captcha 图片中的验证码;与 code Cookie 中的值不区分大小写比较。 | |
captcha | string | 否 | 条件必填。当该用户的 login_captcha 配置为 email 或 sms 时,填写已发送的邮件验证码或短信验证码。 | |
业务结果始终使用 HTTP 200 返回。成功时 data 返回令牌及用户身份;凭据、验证码、用户状态、IP/域名限制或系统授权检查失败时返回业务错误封装。密码错误会被记入登录日志。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 登录成功提示。 | 登录成功! |
oneOf#1.data | object | 是 | 登录成功后的会话和用户身份。 | |
oneOf#1.data.access_token | string | 是 | 加密会话令牌。后续请求以 access-token 请求头携带,实际有效期由系统 login_session_valid_time 配置决定。 | |
oneOf#1.data.username | string | 是 | 登录用户的用户名。 | |
oneOf#1.data.uid | integer(int64) | 是 | 登录用户 ID。 | |
oneOf#1.data.type | integer enum | 是 | 用户类型:1 为管理员,2 为普通用户。 | 1 | 2 |
oneOf#2.code | string 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.msg | string | 是 | 具体错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
POST /v1/phone-captcha
向手机号码发送 4 位数字验证码。该公共接口不要求登录。手机号可由 `account` 指定的已启用账号解析,或直接由 `phone` 指定;两种方式不能混用。系统按 `captcha_type.phone` 配置校验原生图形验证码、腾讯云验证码或极验验证码;同一客户端 IP 在 60 秒内最多发送一次。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
code | cookie | string | 否 | 当系统手机验证码类型为 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` 配置决定。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
account | string | 否 | 可选。已启用用户的邮箱、用户名或手机号;服务端据此取得该用户已配置的手机号。提供时不能为空,账号必须存在且已设置手机号。 | |
phone | string | 否 | 未提供 `account` 时必填。直接接收验证码的手机号码,必须符合服务端手机号格式校验。 | 13800138000 |
check_exist | integer enum | 否 | 未提供 `account` 时必填。手机号存在性要求:0 表示手机号必须不存在(通常用于注册);1 表示手机号必须属于已启用用户(通常用于找回密码)。 | 0 |
code | string | 否 | 当 `captcha_type.phone` 为 native 时必填。GET /v1/common/captcha 返回的图形验证码文本,按不区分大小写方式与 `code` Cookie 中的值比对;同一图形验证码一分钟内不能重复用于发送短信。 | |
ticket | string | 否 | 当 `captcha_type.phone` 为 qcloud 时必填。腾讯云验证码返回的票据。 | |
randstr | string | 否 | 当 `captcha_type.phone` 为 qcloud 时必填。腾讯云验证码返回的随机字符串。 | |
lot_number | string | 否 | 当 `captcha_type.phone` 为 geetest 时必填。极验验证结果中的 `lot_number`。 | |
captcha_output | string | 否 | 当 `captcha_type.phone` 为 geetest 时必填。极验验证结果中的 `captcha_output`。 | |
pass_token | string | 否 | 当 `captcha_type.phone` 为 geetest 时必填。极验验证结果中的 `pass_token`。 | |
gen_time | string | 否 | 当 `captcha_type.phone` 为 geetest 时必填。极验验证结果中的 `gen_time`。 | |
发送成功时 `data` 为 null;参数、账号/手机号、验证码平台校验、频率限制和短信发送失败均使用 HTTP 200 的业务错误响应。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 发送成功提示。 | 发送成功! |
oneOf#1.data | string | 是 | 成功时为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 具体错误原因,例如手机号已存在、验证码错误、请等待 60 秒后再获取或短信发送失败。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
POST /v1/reset-pass
通过已启用账号的邮箱验证码或手机验证码重置密码。该公共接口不要求登录。邮箱方式会在更新密码前向该邮箱发送包含新密码的重置成功邮件;邮件发送失败时本次重置会回滚。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.reset_by | string enum | 是 | 使用邮箱验证码重置密码。 | email |
oneOf#1.email | string(email) | 是 | 已启用用户的邮箱地址;必须存在。 | |
oneOf#1.captcha | string | 是 | 发送到该邮箱的验证码;由服务端校验有效性和时效。 | |
oneOf#1.password | string(password) | 是 | 新密码,至少 6 位,且必须同时包含英文字母和数字。 | |
oneOf#2.reset_by | string enum | 是 | 使用手机验证码重置密码。 | phone |
oneOf#2.phone | string | 是 | 已启用用户的手机号码;必须符合服务端手机号格式且已存在。 | |
oneOf#2.phone_captcha | string | 是 | 发送到该手机号的验证码;由服务端校验有效性和时效。 | |
oneOf#2.password | string(password) | 是 | 新密码,至少 6 位,且必须同时包含英文字母和数字。 | |
重置成功时 `data` 为 null;参数、账号、验证码、密码强度和邮件发送失败均通过 HTTP 200 的业务错误响应返回。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 重置成功提示。 | 重置成功! |
oneOf#1.data | string | 是 | 成功时为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 具体错误原因,例如验证码错误、账号不存在或密码不符合强度要求。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/user/login-policy
按账号查询登录时需要使用的验证码策略,以及该账号已脱敏的邮箱和手机号。账号可为已启用用户的用户名、邮箱或手机号;接口不需要登录。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
account | query | string | 是 | 必填。登录账号,可填写用户名、邮箱或手机号;必须对应已启用用户。 | demo |
请求已被处理。成功时返回登录验证码设置及脱敏联系方式;未提供账号或账号不存在时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 获取成功! |
data | object | 是 | 账号的登录策略和脱敏联系方式。 | |
data.login_captcha | integer | 是 | 登录是否需要验证码的账号设置值。 | 1 |
data.email | string | 是 | 脱敏后的邮箱地址:邮箱用户名仅保留前两个字符,其余以四个星号替代。 | de****@example.invalid |
data.phone | string | 是 | 脱敏后的手机号:保留前 3 位和后 4 位,中间以四个星号替代。 | 138****1234 |
用户 API Key 与 Secret 管理。
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。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
uid | query | integer(int64) | 否 | 要关闭 API Key 的用户 ID。省略时关闭当前登录用户的密钥;仅管理员可指定其他用户。 | |
业务结果通过 HTTP 200 返回。API Key 配置删除并提交后返回确认消息;目标用户未开通、普通用户尝试指定 `uid` 或认证无效时返回字符串业务错误码,删除事务会回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,API Key 配置删除成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | API Key 配置删除并提交事务后返回的确认消息。 | api_key关闭成功 |
oneOf#1.data | string enum | 是 | 关闭成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string enum | 是 | 业务错误码:`api-key-4` 表示目标用户尚未开通 API Key,`message-28` 表示普通用户尝试关闭指定用户的密钥,`login_required` 表示登录态或 API Key 认证无效。 | api-key-4 | message-28 | login_required |
oneOf#2.msg | string | 是 | 与业务错误码对应的中文未开通、权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
uid | query | integer(int64) | 否 | 要查询 API Key 的用户 ID。省略时查询当前登录用户;仅管理员可指定其他用户,普通用户传入该参数会返回权限错误。 | |
业务结果通过 HTTP 200 返回。查询成功时 `data` 为完整 API Key 记录;目标用户尚未开通时 `data` 为 null;普通用户尝试指定 `uid` 或登录凭证无效时返回字符串业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 查询完成时的成功状态码,固定为 0,包括用户尚未开通 API Key 的情况。 | 0 |
oneOf#1.msg | string enum | 是 | API Key 查询完成时返回的确认消息。 | 获取成功 |
oneOf#1.data | oneOf | 是 | 目标用户的完整 API Key 配置;尚未开通 API Key 时为 null。 | |
oneOf#1.data(oneOf#1).id | integer(int64) | 是 | API Key 配置记录的唯一 ID。 | |
oneOf#1.data(oneOf#1).uid | integer(int64) | 是 | 该 API Key 所属用户的 ID。 | |
oneOf#1.data(oneOf#1).api_key | string | 是 | 调用 API 时通过 `api-key` 请求头提交的 16 位访问标识。 | |
oneOf#1.data(oneOf#1).api_secret | string | 是 | 与 API Key 配对、通过 `api-secret` 请求头提交的 30 位明文密钥。 | |
oneOf#1.data(oneOf#1).api_ip | string | 是 | 允许使用该密钥的来源 IP 白名单,多个地址以竖线 `|` 分隔;null 或空字符串表示不限制来源 IP。 | |
oneOf#1.data(oneOf#2) | string | 否 | | |
oneOf#2.code | string enum | 是 | 业务错误码:`task-5` 表示普通用户尝试查询指定用户的 API Key,`login_required` 表示登录态或 API Key 认证无效。 | task-5 | login_required |
oneOf#2.msg | string | 是 | 与业务错误码对应的中文权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
uid | integer(int64) | 否 | 要开通 API Key 的用户 ID。省略请求体或该字段时为当前登录用户;仅管理员可指定其他用户。 | |
业务结果通过 HTTP 200 返回。开通成功时返回新生成的 API Key 和 API Secret;目标用户已有密钥、普通用户尝试指定 `uid` 或登录认证无效时返回字符串业务错误码,创建事务会回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,API Key 开通成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | API Key 记录创建并提交后返回的确认消息。 | api key开通成功 |
oneOf#1.data | object | 是 | 新开通的 API Key 凭证对。 | |
oneOf#1.data.api_key | string | 是 | 新生成的 16 位访问标识,调用 API 时通过 `api-key` 请求头提交。 | |
oneOf#1.data.api_secret | string | 是 | 与 API Key 配对的新生成 30 位明文密钥,调用 API 时通过 `api-secret` 请求头提交。 | |
oneOf#2.code | string enum | 是 | 业务错误码:`api-key-1` 表示目标用户已经开通 API Key,`task-6` 表示普通用户尝试为指定用户开通,`login_required` 表示登录态或 API Key 认证无效。 | api-key-1 | task-6 | login_required |
oneOf#2.msg | string | 是 | 与业务错误码对应的中文重复开通、权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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.ip | string | 是 | 允许使用该 API Key 的来源 IP 白名单,最多 10 个 IPv4 或 IPv6 地址,多个地址以竖线 `|` 分隔;空字符串或 null 表示清除限制。 | |
oneOf#1.uid | integer(int64) | 否 | 要修改 API Key 的用户 ID;省略时为当前登录用户,仅管理员可指定其他用户。 | |
oneOf#2.reset | boolean enum | 是 | 传 true 重新生成 API Key 和 API Secret;服务端以字段是否存在触发重置。 | true |
oneOf#2.uid | integer(int64) | 否 | 要重置 API Key 的用户 ID;省略时为当前登录用户,仅管理员可指定其他用户。 | |
业务结果通过 HTTP 200 返回。IP 白名单修改成功时返回空业务数据;凭证重置成功时返回新 API Key 和 API Secret;目标用户未开通、IP 数量或格式不合法、普通用户指定 `uid` 或认证无效时返回字符串业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,来源 IP 白名单修改成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 来源 IP 白名单写入并提交后返回的确认消息。 | 修改成功 |
oneOf#1.data | string enum | 是 | 来源 IP 白名单修改成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | integer enum | 是 | 成功状态码,API Key 凭证重置成功时固定为 0。 | 0 |
oneOf#2.msg | string enum | 是 | 新凭证写入并使旧凭证失效后返回的确认消息。 | 重置成功 |
oneOf#2.data | object | 是 | 重置后立即生效的新 API Key 凭证对。 | |
oneOf#2.data.api_key | string | 是 | 重置后新生成的 16 位访问标识。 | |
oneOf#2.data.api_secret | string | 是 | 与新 API Key 配对的 30 位明文密钥。 | |
oneOf#3.code | string 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.msg | string | 是 | 与业务错误码对应的中文配置、IP、权限或认证失败原因。 | |
oneOf#3.data | string enum | 是 | 业务错误时固定为空字符串。 | |
当前用户资料、概览和实名认证。
GET /v1/user
获取当前登录用户的账户资料、实名认证与企业认证状态、二次认证设置、余额和用户组。身份证姓名和号码会脱敏后返回。未登录时不能访问。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求已被处理。成功时 `code` 为 0、`msg` 为“获取成功!”、`data` 为当前用户资料;未登录时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 获取成功! |
data | object | 是 | 当前登录用户资料。 | |
data.id | integer | 是 | 用户 ID。 | |
data.name | string | 是 | 用户名。 | |
data.email | string | 否 | 邮箱地址。 | |
data.phone | string | 否 | 手机号。 | |
data.qq | string | 否 | QQ 号。 | |
data.balance | number | 是 | 账户余额。 | |
data.create_at | string | 否 | 注册时间,格式为 YYYY-MM-DD HH:mm:ss。 | |
data.user_group | integer | 否 | 用户组 ID。 | |
data.group_name | string | 否 | 用户组名称。 | |
data.cert_id | integer | 否 | 实名认证证书 ID。 | |
data.cert_name | string | 否 | 脱敏后的实名姓名。 | |
data.cert_no | string | 否 | 脱敏后的证件号码。 | |
data.cert_verified | integer enum | 是 | 个人实名认证状态。 | 0 | 1 |
data.id_auth_way | string | 否 | 实名认证方式。 | |
data.company_auth_enable | integer enum | 否 | 系统是否启用企业认证。 | 0 | 1 |
data.company_name | string | 否 | 企业名称。 | |
data.company_credit_code | string | 否 | 统一社会信用代码。 | |
data.company_verified | integer enum | 否 | 企业认证状态。 | 0 | 1 |
data.auth2_enable | integer enum | 否 | 是否启用二次认证。 | 0 | 1 |
data.auth2_verified | integer enum | 否 | 当前二次认证是否已验证。 | 0 | 1 |
data.auth2_end_at | string | 否 | 二次认证有效截止时间。 | |
data.auth2_expire_action | string | 否 | 二次认证过期处理动作。 | |
data.login_captcha | string | 否 | 登录二次验证方式。 | |
data.white_ip | string | 否 | 登录 IP 白名单。 | |
POST /v1/user
注册普通用户。是否开放注册,以及用户名、邮箱、手机和 QQ 是否必填、是否需要邮箱或手机验证码,均由系统的注册配置决定。无论配置如何,必须同意注册协议并提供符合规则的密码。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
username | string | 否 | 当系统要求用户名时必填。仅允许中文、英文字母与数字,不能是手机号,且必须唯一。 | demo_user |
email | string(email) | 否 | 当系统要求邮箱时必填,且必须唯一;若系统配置邮箱验证,需同时提供 `captcha`。 | demo@example.invalid |
phone | string | 否 | 当系统要求手机号时必填,且必须唯一;若系统配置手机验证,需同时提供 `phone_captcha`。 | 13800000000 |
qq | string | 否 | 当系统要求 QQ 时必填,必须为合法 QQ 号。 | 10001 |
captcha | string | 否 | 邮箱验证码;仅在系统启用必填邮箱且要求邮箱验证时必填。 | 123456 |
phone_captcha | string | 否 | 手机验证码;仅在系统启用必填手机且要求手机验证时必填。 | 123456 |
accept_agreement | integer enum | 是 | 必填。必须为 1,表示同意注册协议。 | 1 |
password | string(password) | 是 | 必填。至少 6 位,且必须同时包含英文字母和数字。 | Demo123456 |
请求已被处理。注册成功时 `code` 为 0、`msg` 为“注册成功!”、`data` 为 null;注册关闭、字段缺失、格式错误、账号重复或验证码无效时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 注册成功! |
data | string | 是 | 注册成功时为 null;失败时为空字符串。 | null |
PUT /v1/user
更新当前登录用户的账户资料、登录安全设置或密码。未登录不能操作。修改手机号或邮箱时分别必须提供针对新号码或新邮箱的验证码;用户名只能在当前用户名为空时设置一次,之后不可修改。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 否 | 用户名。仅当当前用户名为空时可设置一次;只允许中文、英文字母与数字,且不能重复或为手机号。 | |
phone | string | 否 | 新手机号,必须合法且未被其他用户使用;传入时必须同时提供 `phone_captcha`。 | 13800000000 |
phone_captcha | string | 否 | 修改手机号时必填。发送到新手机号的验证码。 | 123456 |
email | string(email) | 否 | 新邮箱,必须合法且未被其他用户使用;传入时必须同时提供 `captcha`。 | new@example.invalid |
captcha | string | 否 | 修改邮箱时必填。发送到新邮箱的验证码。 | 123456 |
qq | string | 否 | 新 QQ 号,必须为合法 QQ 号。 | 10001 |
white_ip | string | 否 | 登录 IP 白名单,多个 IP 使用空白字符分隔;可传空字符串清空。 | 192.0.2.10 198.51.100.20 |
login_captcha | string enum | 否 | 登录二次验证码方式;空字符串表示关闭。`sms` 要求系统允许且已绑定手机,`email` 要求系统允许且已绑定邮箱。 | email |
password | string(password) | 否 | 新密码,至少 6 位且必须同时包含英文字母与数字。 | NewPass123 |
请求已被处理。成功时 `code` 为 0、`msg` 为“修改成功”、`data` 为 null;未登录、验证码错误、资料重复或格式不正确时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 修改成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
GET /v1/user/certify
查询当前登录用户的个人实名认证或二次实名认证结果。认证已通过时立即返回通过状态;尚未通过时,接口会依据用户保存的认证方式向支付宝或微信认证服务查询并同步认证结果。调用前用户必须已填写姓名和身份证号码,并已存在认证流水号。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求已被处理。成功时 data.passed 为 T;姓名或身份证为空、找不到认证流水号、未配置实名认证服务或认证服务返回失败时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
data | object | 是 | 实名认证查询结果。 | |
data.passed | string enum | 是 | 认证通过标志;成功时固定为 T。 | T |
POST /v1/user/certify
为当前登录用户发起个人实名认证、二次实名认证或企业实名认证。个人认证可能直接通过,也可能返回第三方认证跳转地址;企业认证要求先完成法人个人认证,并由系统调用已配置的企业认证服务完成校验。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
verify_type | string enum | 否 | 认证类型。personal_auth 为个人或二次个人认证;company_auth 为企业认证。未传时为 personal_auth。 | personal_auth |
cert_name | string | 否 | 个人认证时使用的姓名;必须为中文姓名。二次认证时必须与首次认证姓名一致。 | 张三 |
cert_no | string | 否 | 个人认证时使用的中国居民身份证号码。二次认证时必须与首次认证身份证号码一致。 | 110101199001011234 |
company_credit_code | string | 否 | 企业认证必填。企业统一社会信用代码,必须通过格式校验。 | 91110000100000000X |
company_name | string | 否 | 企业认证必填。企业名称;会进行 XSS 过滤。 | 示例科技有限公司 |
请求已被处理。个人认证直接通过或企业认证成功时 data 为 null;需要跳转第三方认证时 data 为认证地址;身份信息无效、重复认证、认证服务未配置或企业信息校验失败时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 获取认证地址成功 |
data | string | 是 | 需要第三方个人认证时为认证跳转地址;认证直接通过时为 null;失败时为空字符串。 | https://verify.example.invalid/session/demo |
GET /v1/user/overview
返回当前登录用户在控制台首页展示的资源和账户概览,包括有效用户套餐数量、即将续费数量、余额、实名认证状态、域名、证书和四层转发端口统计。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求已被处理。成功时 data 为当前用户概览数据。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 成功时为空字符串。 | |
data | object | 是 | 当前用户的资源与账户概览。 | |
data.uid | integer | 是 | 当前登录用户 ID。 | 12 |
data.user_package_count | integer | 是 | 未到期的用户套餐数量。 | 1 |
data.renew | integer | 是 | 将在 24 小时内到期或已到期的用户套餐数量。 | 0 |
data.balance | number | 是 | 账户余额,单位为元。 | 98.5 |
data.cert_verified | integer enum | 是 | 个人实名认证是否通过。 | 1 |
data.auth2_enable | integer enum | 是 | 是否启用二次实名认证。 | 0 |
data.auth2_verified | integer enum | 是 | 二次实名认证是否通过。 | 0 |
data.domain_count | integer | 是 | 当前用户全部域名数量。 | 6 |
data.cert_count | integer | 是 | 具有私钥的证书数量。 | 2 |
data.stream_port_count | integer | 是 | 当前用户全部四层转发监听端口总数。 | 3 |
用户默认配置
GET /v1/user-configs
分页查询用户默认配置。普通用户只能查看自己的配置;管理员可通过 `uid` 筛选指定用户。可按配置类型、启用状态和配置项名称精确筛选,结果按配置 ID 倒序返回。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer | 否 | 页码,必须为数字;未传时为 1。 | 1 |
limit | query | integer | 否 | 每页数量,必须为数字;未传时为 10,传 0 表示不分页。 | 10 |
type | query | string | 否 | 按配置类型筛选:`site` 为网站默认配置,`stream` 为四层转发默认配置。 | site |
enable | query | integer | 否 | 按启用状态筛选;仅当传入非空值时生效。 | 1 |
name | query | string | 否 | 按配置项名称精确筛选。 | proxy_cache |
uid | query | integer | 否 | 管理员可选。按归属用户 ID 筛选;普通用户不能借此查看其他用户。 | 12 |
请求已被处理。成功时返回配置列表与总数;页码或每页数量格式错误时仍返回 HTTP 200,并给出业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
count | integer | 是 | 符合筛选条件的配置总数。 | 1 |
data | array | 是 | 用户配置列表。 | |
data | array<object> | 否 | 用户配置列表。 | |
data[].id | integer | 是 | 用户配置 ID。 | |
data[].uid | integer | 是 | 归属用户 ID。 | |
data[].username | string | 否 | 归属用户名。 | |
data[].name | string | 是 | 配置项名称。 | |
data[].value | string | 是 | 配置值,具体格式由配置项名称和类型决定。 | |
data[].type | string | 是 | 配置类型:site 或 stream。 | |
data[].scope_name | string | 是 | 作用域名称,例如 global、group。 | |
data[].scope_id | integer | 是 | 作用域 ID。 | |
data[].site_group_name | string | 否 | 当作用域为网站分组时对应的网站分组名称。 | |
data[].stream_group_name | string | 否 | 当作用域为转发组时对应的转发组名称。 | |
data[].enable | integer enum | 是 | 启用状态。 | 0 | 1 |
data[].create_at | string | 否 | 创建时间。 | |
data[].update_at | string | 否 | 更新时间。 | |
POST /v1/user-configs
创建用户默认配置。配置项由 `type`、`name` 和作用域唯一确定;`value` 为字符串,其内容按配置类型和名称进行服务端校验。默认作用域为全局,默认启用。普通用户创建自己的配置;管理员可通过 `uid` 为指定用户创建。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 是 | 必填。配置项名称;会进行 XSS 过滤,并决定 `value` 的具体校验规则。 | proxy_cache |
value | string | 是 | 必填。配置值字符串;例如 `proxy_cache` 要求 JSON 数组,`white_ip`/`black_ip` 为 IP/CIDR 列表,`block_time`/`white_time` 为 601 至 604800 秒。其他名称也按服务端对应规则验证。 | [] |
type | string enum | 是 | 必填。配置类型:网站、四层转发或证书。 | site |
scope_name | string enum | 否 | 作用域名称;未传时为 `global`。`group` 表示按网站组或转发组生效。 | global |
scope_id | integer | 否 | 作用域 ID;全局作用域固定为 0。分组作用域时,site 类型必须是现有网站组 ID,stream 类型必须是现有转发组 ID。 | 0 |
enable | integer enum | 否 | 是否启用;未传时为 1。 | 1 |
uid | integer | 否 | 管理员专用。指定配置归属用户 ID。 | 12 |
请求已被处理。成功时 `code` 为 0、`msg` 为“用户配置添加成功”、`data` 为新建配置 ID;名称、值、作用域无效或配置重复时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 用户配置添加成功 |
data | integer | 是 | 成功时的新建配置 ID;失败时为空字符串。 | 9 |
PUT /v1/user-configs
更新一个或多个用户配置。请求体可为单个对象或对象数组,单个对象会转换为数组。每个对象必须提供已有配置 ID;`name` 与 `type` 在更新时仍参与值和唯一性校验,但数据库只更新 value、作用域和启用状态。普通用户只能操作自己的配置,管理员可操作其他用户配置。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.id | integer | 是 | 必填。用户配置 ID。 | |
oneOf#1.name | string | 否 | 配置项名称;更新时不写入数据库,但用于校验 value 与配置唯一性。未传时使用原名称。 | |
oneOf#1.value | string | 否 | 配置值;按 name 与 type 的服务端规则校验。未传时使用原值。 | |
oneOf#1.type | string enum | 否 | 配置类型;更新时不写入数据库,但用于校验。未传时使用原类型。 | site | stream | cert |
oneOf#1.scope_name | string enum | 否 | 作用域名称;全局作用域强制 scope_id 为 0。 | global | group |
oneOf#1.scope_id | integer | 否 | 作用域 ID;分组作用域时必须存在对应的网站组或转发组。 | |
oneOf#1.enable | integer enum | 否 | 启用状态。 | 0 | 1 |
oneOf#1.uid | integer | 否 | 管理员专用。指定操作用户;不会改变已有配置的归属。 | |
oneOf#2 | array<object> | 否 | 批量更新对象数组。 | |
oneOf#2[].id | integer | 是 | 用户配置 ID。 | |
oneOf#2[].value | string | 否 | 配置值。 | |
oneOf#2[].scope_name | string | 否 | 作用域名称。 | |
oneOf#2[].scope_id | integer | 否 | 作用域 ID。 | |
oneOf#2[].enable | integer enum | 否 | 启用状态。 | 0 | 1 |
请求已被处理。成功时 `code` 为 0、`msg` 为“更新用户配置成功”、`data` 为 null;请求格式、配置 ID、配置值、作用域或权限不正确时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 更新用户配置成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
DELETE /v1/user-configs/{config_id}
删除一个或多个用户配置。路径参数支持单个配置 ID 或英文逗号分隔的多个 ID;每个 ID 必须为数字且配置必须存在。普通用户只能删除自己的配置,管理员可删除其他用户配置;任一项校验失败时整次删除会回滚。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
config_id | path | string | 是 | 要删除的用户配置 ID,或以英文逗号分隔的 ID 列表;每一项必须是数字。 | 9,10 |
请求已被处理。成功时 `code` 为 0、`msg` 为“用户配置删除成功”、`data` 为 null;ID 无效、配置不存在或无权限时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 用户配置删除成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
PUT /v1/user-configs/{config_id}
更新一个用户配置。路径中的 `config_id` 会覆盖请求体 ID,请求体必须是 JSON 对象。普通用户只能更新自己的配置;管理员可更新其他用户配置。更新时配置值与作用域会重新校验,名称与类型不写入数据库但仍用于校验。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
config_id | path | integer | 是 | 要更新的用户配置 ID,必须存在且当前用户有权限操作。 | 9 |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 否 | 配置项名称;更新时不写入数据库,但用于 value 校验和配置唯一性检查。未传时使用原名称。 | |
value | string | 否 | 配置值;按照 name 与 type 对应的服务端规则校验。未传时使用原值。 | |
type | string enum | 否 | 配置类型;更新时不写入数据库,但用于 value 校验。未传时使用原类型。 | site | stream | cert |
scope_name | string enum | 否 | 作用域名称;global 时 scope_id 固定为 0。 | global | group |
scope_id | integer | 否 | 作用域 ID;分组作用域必须存在对应的网站组或转发组。 | |
enable | integer enum | 否 | 启用状态。 | 0 | 1 |
uid | integer | 否 | 管理员专用。指定操作用户;不会改变已有配置的归属。 | |
请求已被处理。成功时 `code` 为 0、`msg` 为“更新用户配置成功”、`data` 为 null;配置不存在、请求体非对象、值或作用域无效、无权限时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 更新用户配置成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
本组包含以下接口,点击卡片进入详情。
网站和业务配置模板。
GET /v1/configs
查询主控配置记录列表,仅管理员可调用。可按作用域名称、作用域 ID、配置类型和配置名称组合筛选;scope_name 支持用英文逗号传入多个值。返回配置原始 value 字符串,不会按配置类型自动解析 JSON。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
scope_name | query | string | 否 | 配置作用域名称;可传 global、region、node,多个值使用英文逗号分隔。 | |
scope_id | query | integer(int64) | 否 | 作用域实体 ID,精确筛选;global 配置通常使用 0。 | |
type | query | string | 否 | 配置类型,精确筛选,例如 system、site 或 nginx_config。 | |
name | query | string | 否 | 配置名称,精确筛选。 | |
业务结果通过 HTTP 200 返回。管理员认证成功时返回全部匹配配置;普通用户、认证失效时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,配置列表查询成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 配置列表查询成功时固定为空字符串。 | |
oneOf#1.data | array | 是 | 按数据库查询顺序返回的配置记录数组。 | |
oneOf#1.data | array<object> | 否 | 按数据库查询顺序返回的配置记录数组。 | |
oneOf#1.data[].name | string | 是 | 配置名称;与 scope_name、scope_id、type 共同唯一定位一条配置。 | |
oneOf#1.data[].value | string | 是 | 配置原始值,JSON 配置仍以字符串返回。 | |
oneOf#1.data[].type | string | 是 | 配置类型;用于区分 system、site、nginx_config、error_page 等配置处理逻辑。 | |
oneOf#1.data[].scope_id | integer(int64) | 是 | 配置作用域实体 ID。 | |
oneOf#1.data[].scope_name | string | 是 | 配置作用域名称。 | |
oneOf#1.data[].create_at | string | 是 | 配置创建时间,数据库 datetime 序列化值。 | |
oneOf#1.data[].update_at | string | 是 | 配置最后更新时间,数据库 datetime 序列化值。 | |
oneOf#1.data[].enable | integer enum | 是 | 配置启用状态:1 启用,0 禁用。 | 0 | 1 |
oneOf#1.data[].task_id | integer(int64) | 是 | 最近一次配置同步任务 ID,没有任务时为 null。 | |
oneOf#1.data[].entity_name | string | 是 | region 或 node 作用域关联实体名称,global 作用域通常为空字符串。 | |
oneOf#2.code | string enum | 是 | config-274 表示需要管理员权限,login_required 表示认证无效。 | config-274 | login_required |
oneOf#2.msg | string | 是 | 权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
PUT /v1/configs
按“作用域 + 类型 + 名称”创建或更新主控配置。服务端会将 value 转为字符串保存,并按具体 type、name 校验值;Nginx、错误页、OpenResty、默认端口和节点配置等变更会创建节点同步任务。仅管理员可调用。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
scope_name | string enum | 是 | 配置作用域:global 为全局,region 为指定区域,node 为指定节点。 | global | region | node |
scope_id | oneOf | 是 | 作用域实体 ID。global 通常传 0;region、node 分别传对应的区域或节点 ID。 | |
scope_id(oneOf#1) | integer(int64) | 否 | | |
scope_id(oneOf#2) | string | 否 | | |
type | string | 是 | 配置类型。必须以小写字母开头,后续仅可包含小写字母和下划线,例如 system、site、nginx_config。 | |
name | string | 是 | 配置名称。必须以小写字母开头,后续仅可包含小写字母、数字、下划线和连字符。 | |
value | oneOf | 是 | 配置值,必填且可为空字符串。服务端以 str(value) 保存;要求 JSON 的配置必须传入 JSON 文本字符串,而不是 JSON 对象。具体允许值取决于 type 和 name。 | |
value(oneOf#1) | string | 否 | | |
value(oneOf#2) | integer | 否 | | |
value(oneOf#3) | number | 否 | | |
value(oneOf#4) | boolean | 否 | | |
enable | integer enum | 否 | 可选启用状态:1 启用,0 禁用。未传时新建记录默认启用,更新记录保持原状态。 | 0 | 1 |
业务结果仍使用 HTTP 200 返回。成功时确认配置已写入;参数、权限或具体配置值校验失败时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 配置写入成功提示。 | 更新config成功 |
oneOf#1.data | string enum | 是 | 成功时固定为空字符串。 | |
oneOf#2.code | string | 是 | 业务错误码,例如 config-2 至 config-38、config-200、config-236 至 config-300,或管理员权限错误 config-275。 | |
oneOf#2.msg | string | 是 | 参数、权限或配置值校验失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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_id | path | string | 是 | 复合配置标识,必须为 {scope_name}-{scope_id}-{type}-{name} 四段;scope_name 只能是 region 或 node,scope_id 必须为数字。type 和 name 分别遵循服务端的小写命名规则。 | |
业务结果使用 HTTP 200 返回。删除执行成功时不区分记录是否原本存在;管理员权限、全局作用域或标识格式不符合要求时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 配置删除成功提示。 | 删除config成功 |
oneOf#1.data | string enum | 是 | 成功时固定为空字符串。 | |
oneOf#2.code | string enum | 是 | 全局配置禁止删除、标识校验失败、管理员权限不足或认证失效的业务错误码。 | config-193 | config-194 | config-195 | config-196 | config-197 | config-198 | config-272 | login_required |
oneOf#2.msg | string | 是 | 删除前校验或权限失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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_id | path | string | 是 | 复合配置标识,格式为 {scope_name}-{scope_id}-{type}-{name}。服务端以前三个连字符切分,因此 name 可以包含连字符,例如 global-0-system-recharge。 | |
业务结果使用 HTTP 200 返回。记录不存在时 data 为 null;普通用户读取充值配置时返回脱敏后的支付配置,权限不足或认证失效时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string | 是 | 详情读取成功时固定为 null。 | |
oneOf#1.data | oneOf | 是 | 按配置名称与当前账户权限返回的配置记录或脱敏支付配置。 | |
oneOf#1.data(oneOf#1).name | string | 是 | 配置名称。 | |
oneOf#1.data(oneOf#1).value | string | 是 | 数据库保存的原始配置值;JSON 配置仍以 JSON 文本字符串返回。 | |
oneOf#1.data(oneOf#1).type | string | 是 | 配置类型。 | |
oneOf#1.data(oneOf#1).scope_id | integer(int64) | 是 | 配置作用域实体 ID。 | |
oneOf#1.data(oneOf#1).scope_name | string | 是 | 配置作用域名称。 | |
oneOf#1.data(oneOf#1).create_at | string | 是 | 配置创建时间。 | |
oneOf#1.data(oneOf#1).update_at | string | 是 | 配置最后更新时间。 | |
oneOf#1.data(oneOf#1).enable | integer enum | 是 | 配置启用状态:1 启用,0 禁用。 | 0 | 1 |
oneOf#1.data(oneOf#1).task_id | integer(int64) | 是 | 最近一次配置同步任务 ID;没有同步任务时为 null。 | |
oneOf#1.data(oneOf#1).state | string | 是 | 关联同步任务的当前状态;无任务时为 null。 | |
oneOf#1.data(oneOf#1).ret | string | 是 | 关联同步任务的返回内容;无任务时为 null。 | |
oneOf#1.data(oneOf#1).task_type | string | 是 | 关联同步任务类型;无任务时为 null。 | |
oneOf#1.data(oneOf#2).default-pay | string | 是 | 默认支付渠道标识。 | |
oneOf#1.data(oneOf#2).transfer | object | 是 | 转账支付的公开配置。 | |
oneOf#1.data(oneOf#2).transfer.state | boolean | 是 | 转账支付启用状态。 | |
oneOf#1.data(oneOf#2).transfer.data | string | 是 | 转账支付说明或数据。 | |
oneOf#1.data(oneOf#2).wxpay | object | 是 | 脱敏后的微信支付配置。 | |
oneOf#1.data(oneOf#2).wxpay.state | boolean | 是 | 微信支付启用状态。 | |
oneOf#1.data(oneOf#2).wxpay.subtype | string | 是 | 微信支付子类型;未配置时为空字符串。 | |
oneOf#1.data(oneOf#2).alipay | object | 是 | 脱敏后的支付宝配置。 | |
oneOf#1.data(oneOf#2).alipay.state | boolean | 是 | 支付宝启用状态。 | |
oneOf#1.data(oneOf#2).alipay.subtype | string | 是 | 支付宝支付子类型;未配置时为空字符串。 | |
oneOf#2.code | string enum | 是 | config-273 表示需要管理员权限;login_required 表示认证无效。 | config-273 | login_required |
oneOf#2.msg | string | 是 | 权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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_id | path | string | 是 | 复合配置标识,格式为 {scope_name}-{scope_id}-{type}-{name}。服务端以前三个连字符切分,因此 name 可包含连字符。 | |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
value | oneOf | 是 | 配置值。服务端会转为字符串保存;需要 JSON 的配置必须传 JSON 文本字符串。 | |
value(oneOf#1) | string | 否 | | |
value(oneOf#2) | integer | 否 | | |
value(oneOf#3) | number | 否 | | |
value(oneOf#4) | boolean | 否 | | |
enable | integer enum | 否 | 可选启用状态:1 启用,0 禁用;省略时新建配置默认启用,更新配置保持原状态。 | 0 | 1 |
业务结果使用 HTTP 200 返回。成功时表示配置已写入;路径格式、管理员权限或配置值校验失败时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 配置写入成功提示。 | 更新config成功 |
oneOf#1.data | string enum | 是 | 成功时固定为空字符串。 | |
oneOf#2.code | string | 是 | 业务错误码,例如管理员权限错误 config-275 或配置值校验错误 config-2 至 config-300。 | |
oneOf#2.msg | string | 是 | 路径、权限或配置值校验失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/site-sys-config
读取全局 OpenResty 配置中供站点使用的默认临时白名单时长和封禁时长。接口要求登录,不区分普通用户与管理员。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
成功或未登录均返回 HTTP 200。成功时 `msg` 为 null。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 成功时固定为 null。 | |
oneOf#1.data | object | 是 | 网站 CC 防护的默认白名单与封禁时间配置。 | |
oneOf#1.data.white_time | integer | 是 | 默认临时白名单时长,单位为秒。 | 21600 |
oneOf#1.data.block_time | integer | 是 | 默认封禁时长,单位为秒。 | 3600 |
oneOf#2.code | string enum | 是 | 未登录时的业务错误码。 | login_required |
oneOf#2.msg | string | 是 | 认证失败原因。 | |
oneOf#2.data | string enum | 是 | 错误响应中的固定空字符串。 | |
网站的创建、查询、更新和删除。
GET /v1/sites
按条件分页查询网站,默认按网站 ID 倒序返回。普通用户始终只查询自己的网站;管理员可查询全部或以 `uid` 筛选指定用户。`action=export` 时不分页并返回 CSV 下载,而非 JSON。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer | 否 | 页码,必须为数字,默认 1。 | |
limit | query | integer | 否 | 每页条数,必须为数字,默认 10;传 0 时不分页。导出模式会忽略该值。 | |
domain | query | string | 否 | 按网站域名字段进行包含匹配。 | example.invalid |
domains | query | string | 否 | 按域名精确匹配网站域名列表中的完整项;服务端会校验域名格式。 | example.invalid |
backend_ip | query | string | 否 | 按回源配置 JSON 中包含的源站 IP 文本筛选。 | 192.0.2.10 |
group | query | integer | 否 | 网站组 ID 筛选。 | |
id | query | string | 否 | 网站 ID 列表,以英文逗号分隔;每项必须是数字。 | 101,102 |
uid | query | integer | 否 | 仅管理员有效:按网站所属用户 ID 筛选。 | |
user_package | query | integer | 否 | 按用户套餐 ID 筛选。 | |
package | query | integer | 否 | 按基础套餐 ID 筛选。 | |
region | query | integer | 否 | 按区域 ID 筛选。 | |
node_group | query | integer | 否 | 按主线路组 ID 筛选。 | |
cname_domain | query | integer | 否 | 按站点 CNAME 域名配置 ID 筛选。 | |
cname_hostname | query | string | 否 | 按站点 CNAME 主机名前缀精确筛选。 | |
http_listen_port | query | integer | 否 | 按 HTTP 监听端口筛选,必须是有效端口。 | |
https_listen_port | query | integer | 否 | 按 HTTPS 监听端口筛选,必须是有效端口。 | |
https_enable | query | string | 否 | 非空时按 HTTPS 是否启用筛选:`1` 为已启用,其他非空值为未启用。 | |
enable | query | string | 否 | 非空时按网站是否启用筛选:`1` 为启用,其他非空值为停用。 | |
is_default_server | query | string | 否 | 非空时按是否默认站点筛选:`1` 为默认,其他非空值为非默认。 | |
sync_state | query | string | 否 | 按网站同步任务状态精确筛选。 | pending |
state | query | string | 否 | 按网站业务状态精确筛选。 | normal |
action | query | string | 否 | 返回方式:`search` 返回 JSON 列表(默认);`export` 返回全部匹配项的 CSV 文件。 | |
`search` 成功时返回 JSON;`export` 成功时返回 CSV。参数或认证错误仍返回 HTTP 200 的 JSON 业务错误。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.count | integer | 是 | 匹配网站总数,未受分页影响。 | |
oneOf#1.data | array | 是 | 当前页网站记录。JSON 配置字段保持数据库存储的 JSON 文本,调用方需自行解析。 | |
oneOf#1.data | array<object> | 否 | 当前页网站记录。JSON 配置字段保持数据库存储的 JSON 文本,调用方需自行解析。 | |
oneOf#1.data[].id | integer | 否 | 网站 ID。 | |
oneOf#1.data[].uid | integer | 否 | 所属用户 ID。 | |
oneOf#1.data[].name | string | 否 | 所属用户用户名。 | |
oneOf#1.data[].user_package | integer | 否 | 用户套餐 ID。 | |
oneOf#1.data[].package_id | integer | 否 | 基础套餐 ID。 | |
oneOf#1.data[].package_name | string | 否 | 用户套餐名称。 | |
oneOf#1.data[].region_id | integer | 否 | 区域 ID。 | |
oneOf#1.data[].region_name | string | 否 | 区域名称。 | |
oneOf#1.data[].node_group_id | integer | 否 | 主线路组 ID。 | |
oneOf#1.data[].node_group_name | string | 否 | 主线路组名称。 | |
oneOf#1.data[].backup_node_group | integer | 否 | 备用线路组 ID。 | |
oneOf#1.data[].backup_node_group_name | string | 否 | 备用线路组名称。 | |
oneOf#1.data[].domain | string | 否 | 网站域名列表,使用空白字符分隔。 | |
oneOf#1.data[].cname_hostname | string | 否 | 站点 CNAME 主机名前缀。 | |
oneOf#1.data[].cname_domain | string | 否 | 站点 CNAME 域名。 | |
oneOf#1.data[].cname_mode | string | 否 | CNAME 使用模式。 | |
oneOf#1.data[].up_cname_hostname | string | 否 | 用户套餐 CNAME 主机名前缀。 | |
oneOf#1.data[].up_cname_domain | string | 否 | 用户套餐 CNAME 域名。 | |
oneOf#1.data[].record_id | string | 否 | DNS 记录 ID。 | |
oneOf#1.data[].http_listen | string | 否 | HTTP 监听配置 JSON 文本。 | |
oneOf#1.data[].https_listen | string | 否 | HTTPS 监听配置 JSON 文本。 | |
oneOf#1.data[].backend | string | 否 | 源站列表配置 JSON 文本。 | |
oneOf#1.data[].backend_protocol | string | 否 | 回源协议。 | |
oneOf#1.data[].backend_http_port | string | 否 | 回源 HTTP 端口。 | |
oneOf#1.data[].backend_https_port | string | 否 | 回源 HTTPS 端口。 | |
oneOf#1.data[].backend_port_mapping | integer | 否 | 是否跟随监听端口进行端口映射:1 为是。 | |
oneOf#1.data[].backend_host | string | 否 | 回源 Host 配置。 | |
oneOf#1.data[].balance_way | string | 否 | 负载均衡方式。 | |
oneOf#1.data[].enable | integer | 否 | 是否启用:1 为启用,0 为停用。 | |
oneOf#1.data[].site_state | string | 否 | 网站业务状态。 | |
oneOf#1.data[].state | string | 否 | 网站状态字段。 | |
oneOf#1.data[].sync_state | string | 否 | 同步任务状态。 | |
oneOf#1.data[].cname_state | string | 否 | CNAME 同步任务状态。 | |
oneOf#1.data[].task_id | integer | 否 | 网站同步任务 ID。 | |
oneOf#1.data[].cname_task_id | integer | 否 | CNAME 任务 ID。 | |
oneOf#1.data[].depend | string | 否 | 同步任务依赖任务 ID 列表。 | |
oneOf#1.data[].groups | string | 否 | 所属网站组 ID 聚合字符串,以英文逗号分隔。 | |
oneOf#1.data[].group_name | string | 否 | 所属网站组名称聚合字符串,以英文逗号分隔。 | |
oneOf#1.data[].acl | string | 否 | ACL 配置。 | |
oneOf#1.data[].cc_default_rule | string | 否 | 默认 CC 规则 ID。 | |
oneOf#1.data[].cc_switch | string | 否 | CC 自动切换配置 JSON 文本。 | |
oneOf#1.data[].extra_cc_rule | string | 否 | 附加 CC 规则配置 JSON 文本。 | |
oneOf#1.data[].block_proxy | integer | 否 | 是否拦截代理访问:1 为拦截。 | |
oneOf#1.data[].block_region | string | 否 | 地区拦截配置。 | |
oneOf#1.data[].spider_allow | string | 否 | 爬虫放行配置。 | |
oneOf#1.data[].cors | string | 否 | CORS 配置 JSON 文本。 | |
oneOf#1.data[].gzip_enable | integer | 否 | 是否启用 Gzip:1 为启用。 | |
oneOf#1.data[].gzip_types | string | 否 | Gzip MIME 类型配置。 | |
oneOf#1.data[].health_check | string | 否 | 健康检查配置 JSON 文本。 | |
oneOf#1.data[].hotlink | string | 否 | 防盗链配置 JSON 文本。 | |
oneOf#1.data[].proxy_cache | string | 否 | 代理缓存配置 JSON 文本。 | |
oneOf#1.data[].proxy_http_version | string | 否 | 回源 HTTP 版本。 | |
oneOf#1.data[].proxy_ssl_protocols | string | 否 | 回源 TLS 协议配置。 | |
oneOf#1.data[].proxy_timeout | string | 否 | 代理超时配置。 | |
oneOf#1.data[].post_size_limit | string | 否 | 请求体大小限制。 | |
oneOf#1.data[].range | integer | 否 | 是否支持 Range:1 为支持。 | |
oneOf#1.data[].url_rewrite | string | 否 | URL 重写配置 JSON 文本。 | |
oneOf#1.data[].websocket_enable | integer | 否 | 是否启用 WebSocket:1 为启用。 | |
oneOf#1.data[].enable_backup_group | integer | 否 | 是否启用备用线路组:1 为启用。 | |
oneOf#1.data[].ups_keepalive | integer | 否 | 是否启用回源长连接。 | |
oneOf#1.data[].ups_keepalive_conn | string | 否 | 回源长连接数量。 | |
oneOf#1.data[].ups_keepalive_timeout | string | 否 | 回源长连接空闲超时。 | |
oneOf#1.data[].acme_proxy_to_orgin | integer | 否 | ACME 请求是否回源:1 为是。 | |
oneOf#1.data[].create_at | string | 否 | 创建时间。 | |
oneOf#1.data[].create_at2 | string | 否 | 格式化创建时间,`YYYY-MM-DD HH:mm:ss`。 | |
oneOf#1.data[].update_at | string | 否 | 更新时间。 | |
oneOf#1.data[].update_at2 | string | 否 | 格式化更新时间,`YYYY-MM-DD HH:mm:ss`。 | |
oneOf#1.data[].end_at | string | 否 | 用户套餐到期时间,`YYYY-MM-DD HH:mm:ss`。 | |
oneOf#1.data[].version | integer | 否 | 网站配置版本。 | |
oneOf#2.code | string enum | 是 | 页码/分页、端口、域名、ID、action 参数或认证失败的业务错误码。 | site-128 | site-129 | site-172 | site-173 | site-327 | site-369 | site-373 | login_required |
oneOf#2.msg | string | 是 | 错误原因。 | |
oneOf#2.data | string enum | 是 | 错误响应中的固定空字符串。 | |
POST /v1/sites
为当前登录用户创建一个或多个七层网站。请求体可以是单个网站对象,也可以是网站对象数组;每个对象必须提供域名和至少一个可用源站。未提供的监听、回源及安全配置由当前区域和用户默认配置补齐。管理员可额外指定归属用户、套餐、区域和线路。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.domain | string | 是 | 必填。网站域名,多个域名以空白字符分隔;会转为小写,不能重复,且受单站与套餐域名配额限制。 | |
oneOf#1.backend | array | 是 | 必填。源站列表,至少一个源站状态为 `up`,且地址不得重复。 | |
oneOf#1.backend | array<object> | 否 | 必填。源站列表,至少一个源站状态为 `up`,且地址不得重复。 | |
oneOf#1.backend[].addr | string | 是 | 必填。源站 IPv4、IPv6 或域名。 | |
oneOf#1.backend[].weight | integer | 否 | 源站权重;新建省略时默认为 1。 | |
oneOf#1.backend[].state | string enum | 否 | 源站状态;新建省略时默认为 `up`。 | up | down | backup |
oneOf#1.user_package | integer | 否 | 用户套餐 ID;当前用户有多个套餐时必须指定。 | |
oneOf#1.http_listen | object | 否 | HTTP 监听;与 HTTPS 至少启用一个。 | |
oneOf#1.http_listen.port | string | 否 | 空白分隔的监听端口;省略时使用默认端口。 | |
oneOf#1.https_listen | object | 否 | HTTPS 监听;需要已启用的证书,或与 `auto_cert=1` 一起使用。 | |
oneOf#1.https_listen.port | string | 否 | 空白分隔的 HTTPS 监听端口。 | |
oneOf#1.https_listen.cert | integer | 否 | 证书 ID。 | |
oneOf#1.https_listen.hsts | integer enum | 否 | 是否启用 HSTS。 | 0 | 1 |
oneOf#1.https_listen.http2 | integer enum | 否 | 是否启用 HTTP/2。 | 0 | 1 |
oneOf#1.https_listen.http3 | integer enum | 否 | 是否启用 HTTP/3。 | 0 | 1 |
oneOf#1.https_listen.force_ssl_enable | integer enum | 否 | 是否强制跳转 HTTPS。 | 0 | 1 |
oneOf#1.https_listen.force_ssl_port | string | 否 | 强制跳转的 HTTPS 端口。 | |
oneOf#1.auto_cert | integer enum | 否 | 是否自动申请证书。 | 0 | 1 |
oneOf#1.balance_way | string enum | 否 | 负载均衡方式。 | ip_hash | rr |
oneOf#1.backend_protocol | string enum | 否 | 回源协议。 | follow | http | https |
oneOf#1.backend_http_port | integer | 否 | HTTP 回源端口。 | |
oneOf#1.backend_https_port | integer | 否 | HTTPS 回源端口。 | |
oneOf#1.proxy_timeout | integer | 否 | 回源读取超时秒数。 | |
oneOf#1.proxy_connect_timeout | integer | 否 | 回源连接超时秒数。 | |
oneOf#1.health_check | object | 否 | 源站健康检查配置。 | |
oneOf#1.health_check.enable | integer enum | 否 | 是否启用检查。 | 0 | 1 |
oneOf#1.health_check.host | string | 否 | 检查请求的 Host。 | |
oneOf#1.health_check.path | string | 否 | 检查路径,必须以 `/` 开头。 | |
oneOf#1.proxy_cache | integer enum | 否 | 是否启用代理缓存。 | 0 | 1 |
oneOf#1.gzip_enable | integer enum | 否 | 是否启用 Gzip。 | 0 | 1 |
oneOf#1.websocket_enable | integer enum | 否 | 是否启用 WebSocket 代理。 | 0 | 1 |
oneOf#1.acl | integer | 否 | ACL ID;传 null 或 0 表示不绑定。ACL 必须已启用且属于当前目标用户,否则要求管理员权限。 | 12 |
oneOf#1.acme_proxy_to_orgin | integer enum | 否 | 是否将 `/.well-known/acme-challenge/` 请求回源:1 开启,0 关闭。 | 1 |
oneOf#1.backend_host | string | 否 | 回源 Host。允许 `$host`、`$host:$server_port`,或合法域名/IP及可选端口。 | $host |
oneOf#1.backend_port_mapping | integer enum | 否 | 是否按客户端访问协议和端口进行回源端口映射。 | 1 |
oneOf#1.backup_node_group | integer | 否 | 管理员专用。备用线路组 ID;必须与区域匹配且不能与主线路组相同。 | 22 |
oneOf#1.black_ip | string | 否 | 网站黑名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。 | 198.51.100.0/24 |
oneOf#1.block_proxy | integer enum | 否 | 是否拦截被识别为代理的客户端。 | 1 |
oneOf#1.block_region | string | 否 | 按两字母小写国家/地区代码拦截,多个值以逗号分隔;空字符串表示关闭。 | us,jp |
oneOf#1.block_time | integer | 否 | 自动黑名单持续时间,单位秒;非空时必须大于 600 且不超过 604800。 | 3600 |
oneOf#1.cc_default_rule | integer | 否 | 默认 CC 规则 ID;规则必须存在且启用,使用其他用户的非内置规则需要管理员权限。 | 10002 |
oneOf#1.cc_switch | object | 否 | CC 规则自动切换配置;空对象表示关闭。 | {"rule":10002,"switch":100,"enable":1} |
oneOf#1.cc_switch.rule | integer | 是 | 切换后的 CC 规则 ID。 | 10002 |
oneOf#1.cc_switch.switch | integer | 是 | 触发切换的请求阈值。 | 100 |
oneOf#1.cc_switch.enable | integer enum | 否 | 是否启用自动切换。 | 1 |
oneOf#1.cname_hostname | string | 否 | 管理员专用。网站 CNAME 主机名;各标签必须合法且在系统内唯一。 | site-a1b2c3 |
oneOf#1.condition_backend | array | 否 | 按请求条件选择源站的规则列表。 | [{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}] |
oneOf#1.condition_backend | array<object> | 否 | 按请求条件选择源站的规则列表。 | [{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}] |
oneOf#1.condition_backend[].matcher | array | 是 | 全部匹配条件。 | |
oneOf#1.condition_backend[].matcher | array<object> | 否 | 全部匹配条件。 | |
oneOf#1.condition_backend[].matcher[].item | string | 是 | 匹配项。 | req_uri |
oneOf#1.condition_backend[].matcher[].op | string enum | 是 | 匹配操作符。 | contain |
oneOf#1.condition_backend[].matcher[].value | string | 是 | 匹配值;服务端会去除空行和首尾空白。 | /api/ |
oneOf#1.condition_backend[].backend | array | 是 | 命中后使用的源站列表。 | |
oneOf#1.condition_backend[].backend | array<object> | 否 | 命中后使用的源站列表。 | |
oneOf#1.condition_backend[].backend[].addr | string | 是 | 源站 IPv4、IPv6 或域名。 | 198.51.100.10 |
oneOf#1.condition_backend[].backend[].weight | integer | 否 | 源站权重。 | 1 |
oneOf#1.condition_backend[].backend[].state | string enum | 否 | 源站状态。 | up |
oneOf#1.cookie_domain | string | 否 | Cookie Domain;允许空字符串,非空时必须是合法域名。 | example.invalid |
oneOf#1.cors | object | 否 | 跨域响应配置。 | {"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.enable | integer enum | 是 | 是否启用 CORS。 | 1 |
oneOf#1.cors.allow_origin | string | 是 | Access-Control-Allow-Origin 值。 | * |
oneOf#1.cors.allow_methods | string | 是 | 允许的方法,空格分隔。 | GET POST OPTIONS |
oneOf#1.cors.allow_headers | string | 是 | 允许的请求头,空格分隔。 | Content-Type Authorization |
oneOf#1.cors.expose_headers | string | 是 | 允许浏览器读取的响应头。 | Content-Length |
oneOf#1.cors.allow_credentials | integer enum | 是 | 是否允许携带凭证。 | 1 |
oneOf#1.cors.max_age | string | 是 | 预检结果缓存秒数;服务端要求传数字字符串。 | 1728000 |
oneOf#1.dns_api | integer | 否 | DNS API 凭据 ID;必须属于目标用户。传 null 表示不绑定。 | 8 |
oneOf#1.enable | integer enum | 否 | 网站启用状态:1 启用,0 禁用。 | 1 |
oneOf#1.enable_ipv6 | integer enum | 否 | 是否启用 IPv6 CNAME;仅按网站生成 CNAME 且系统存在 IPv6 节点时可用。 | 1 |
oneOf#1.extra_cc_rule | array | 否 | 网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。 | [{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}] |
oneOf#1.extra_cc_rule | array<object> | 否 | 网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。 | [{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}] |
oneOf#1.groups | string | 否 | 网站分组 ID,多个 ID 使用逗号分隔;空字符串表示不加入分组。 | 3,8 |
oneOf#1.gzip_types | string | 否 | 启用 Gzip 的 MIME 类型,使用空格分隔;每项只能含字母、数字及 `/ - + . * _`。 | text/plain text/css application/json |
oneOf#1.hotlink | object | 否 | 防盗链配置。 | {"enable":1,"domain":"www.example.invalid","allow_empty":0,"scope_type":"all","scope_content":""} |
oneOf#1.hotlink.enable | integer enum | 是 | 是否启用防盗链。 | 1 |
oneOf#1.hotlink.domain | string | 是 | 允许的来源域名,使用空格分隔;空值仅允许本站域名。 | www.example.invalid |
oneOf#1.hotlink.allow_empty | integer enum | 是 | 是否允许空 Referer。 | 1 |
oneOf#1.hotlink.scope_type | string enum | 否 | 生效范围。 | all |
oneOf#1.hotlink.scope_content | string | 否 | 非 all 范围的匹配内容。 | /static/ |
oneOf#1.is_default_server | integer enum | 否 | 管理员专用。是否作为线路范围内的默认站点;同一节点的监听端口不能与其它默认站点冲突。 | 1 |
oneOf#1.l2_config_id | integer | 否 | 管理员专用。L2 配置 ID;必须存在、与网站区域一致并已绑定 L2 节点。 | 9 |
oneOf#1.l2_state | string enum | 否 | 管理员专用。L2 模式。 | inherit |
oneOf#1.log_req_body | integer enum | 否 | 管理员专用。是否记录请求体。 | 1 |
oneOf#1.log_req_body_max_size | integer | 否 | 管理员专用。记录请求体的最大 KiB;不能超过 2048,也不能超过全局 client_body_buffer_size。 | 16 |
oneOf#1.log_req_header | integer enum | 否 | 管理员专用。是否记录请求头。 | 1 |
oneOf#1.log_resp_header | integer enum | 否 | 管理员专用。是否记录响应头。 | 1 |
oneOf#1.node_group_id | integer | 否 | 管理员专用。主线路组 ID;必须属于目标区域;按套餐生成 CNAME 时不能单独指定。 | 21 |
oneOf#1.page_403 | string | 否 | 自定义 403 错误页 HTML;空字符串使用默认页面。 | <h1>Forbidden</h1> |
oneOf#1.page_404 | string | 否 | 自定义 404 错误页 HTML;空字符串使用默认页面。 | <h1>Not Found</h1> |
oneOf#1.page_500 | string | 否 | 自定义 500 错误页 HTML;空字符串使用默认页面。 | <h1>Server Error</h1> |
oneOf#1.page_502 | string | 否 | 自定义 502 错误页 HTML;空字符串使用默认页面。 | <h1>Bad Gateway</h1> |
oneOf#1.page_504 | string | 否 | 自定义 504 错误页 HTML;空字符串使用默认页面。 | <h1>Gateway Timeout</h1> |
oneOf#1.post_size_limit | string | 否 | POST 请求体大小限制。可使用纯数字或 b/k/m/g 单位,大小写均可;空字符串表示采用默认配置。 | 10m |
oneOf#1.proxy_auth | object | 否 | 回源 Basic Auth 配置。 | {"enable":1,"username":"origin-user","password":"REDACTED"} |
oneOf#1.proxy_auth.enable | integer enum | 是 | 是否启用回源认证。 | 1 |
oneOf#1.proxy_auth.username | string | 否 | 认证用户名。 | origin-user |
oneOf#1.proxy_auth.password | string | 否 | 认证密码。 | REDACTED |
oneOf#1.proxy_http_version | string enum | 否 | 回源 HTTP 协议版本。 | 1.1 |
oneOf#1.proxy_ssl_protocols | string | 否 | 允许的回源 TLS/SSL 协议,多个值使用空格分隔。 | TLSv1.2 TLSv1.3 |
oneOf#1.range | integer enum | 否 | 是否启用分段回源。 | 1 |
oneOf#1.recv_real_time | integer enum | 否 | 是否实时向客户端返回上游响应数据。 | 1 |
oneOf#1.region_id | integer | 否 | 管理员专用。区域 ID;主、备用线路组必须属于该区域。 | 6 |
oneOf#1.req_header | array | 否 | 添加或覆盖的回源请求头。 | [{"name":"X-Origin","value":"cdnfly"}] |
oneOf#1.req_header | array<object> | 否 | 添加或覆盖的回源请求头。 | [{"name":"X-Origin","value":"cdnfly"}] |
oneOf#1.req_header[].name | string | 是 | 请求头名称,必须以英文字母开头。 | X-Example |
oneOf#1.req_header[].value | string | 是 | 请求头值,去除首尾空白后不能为空。 | example-value |
oneOf#1.resp_header | array | 否 | 添加或覆盖的客户端响应头。 | [{"name":"X-Cache","value":"cdnfly"}] |
oneOf#1.resp_header | array<object> | 否 | 添加或覆盖的客户端响应头。 | [{"name":"X-Cache","value":"cdnfly"}] |
oneOf#1.resp_header[].name | string | 是 | 请求头名称,必须以英文字母开头。 | X-Example |
oneOf#1.resp_header[].value | string | 是 | 请求头值,去除首尾空白后不能为空。 | example-value |
oneOf#1.send_real_time | integer enum | 否 | 是否实时向上游发送客户端请求数据。 | 1 |
oneOf#1.spider_allow | string enum | 否 | 搜索引擎爬虫访问策略;空字符串表示不单独设置。 | allow |
oneOf#1.spider_to_sip | string | 否 | 搜索引擎专用回源 IP;空字符串表示关闭。仅按网站生成 CNAME 且 DNS 服务支持对应线路时可用。 | 198.51.100.20 |
oneOf#1.state | string enum | 否 | 管理员专用。网站业务状态。 | 200 |
oneOf#1.uid | integer | 否 | 管理员专用。创建时指定网站所属用户;更新转移网站时与 new_uid 配合,作为目标套餐归属校验用户。 | 12 |
oneOf#1.ups_keepalive | integer enum | 否 | 是否启用上游 Keepalive。 | 1 |
oneOf#1.ups_keepalive_conn | integer | 否 | 每个 worker 保留的上游 Keepalive 连接数。 | 16 |
oneOf#1.ups_keepalive_timeout | integer | 否 | 上游 Keepalive 空闲超时秒数。 | 60 |
oneOf#1.url_rewrite | array | 否 | URL 重定向规则。 | [{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}] |
oneOf#1.url_rewrite | array<object> | 否 | URL 重定向规则。 | [{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}] |
oneOf#1.url_rewrite[].host | string | 是 | 匹配 Host,不含 http:// 或 https://。 | www.example.invalid |
oneOf#1.url_rewrite[].match | string | 是 | URI 匹配表达式。 | /(.*) |
oneOf#1.url_rewrite[].redirect | string | 是 | 重定向目标;可使用 `$1` 或受支持的 Nginx 变量。 | https://example.invalid/$1 |
oneOf#1.url_rewrite[].code | string enum | 是 | 重定向方式。 | 301 |
oneOf#1.url_rewrite[].user_agent | string | 否 | User-Agent 匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].referer | string | 否 | Referer 匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].country_code | string | 否 | 国家代码匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].accept_language | string | 否 | Accept-Language 匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].province | string | 否 | 省份匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].city | string | 否 | 城市匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].isp | string | 否 | 运营商匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].asnumber | string | 否 | ASN 匹配;省略时为 `.*`。 | .* |
oneOf#1.white_ip | string | 否 | 网站白名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。 | 203.0.113.10 |
oneOf#1.white_time | integer | 否 | 自动白名单持续时间,单位秒;非空时不超过 604800。 | 3600 |
oneOf#2 | array<object> | 否 | 批量创建;数组中的每个元素独立按网站创建规则校验。 | |
oneOf#2[].domain | string | 是 | 必填。网站域名,多个域名以空白字符分隔;会转为小写,不能重复,且受单站与套餐域名配额限制。 | |
oneOf#2[].backend | array | 是 | 必填。源站列表,至少一个源站状态为 `up`,且地址不得重复。 | |
oneOf#2[].backend | array<object> | 否 | 必填。源站列表,至少一个源站状态为 `up`,且地址不得重复。 | |
oneOf#2[].backend[].addr | string | 是 | 必填。源站 IPv4、IPv6 或域名。 | |
oneOf#2[].backend[].weight | integer | 否 | 源站权重;新建省略时默认为 1。 | |
oneOf#2[].backend[].state | string enum | 否 | 源站状态;新建省略时默认为 `up`。 | up | down | backup |
oneOf#2[].user_package | integer | 否 | 用户套餐 ID;当前用户有多个套餐时必须指定。 | |
oneOf#2[].http_listen | object | 否 | HTTP 监听;与 HTTPS 至少启用一个。 | |
oneOf#2[].http_listen.port | string | 否 | 空白分隔的监听端口;省略时使用默认端口。 | |
oneOf#2[].https_listen | object | 否 | HTTPS 监听;需要已启用的证书,或与 `auto_cert=1` 一起使用。 | |
oneOf#2[].https_listen.port | string | 否 | 空白分隔的 HTTPS 监听端口。 | |
oneOf#2[].https_listen.cert | integer | 否 | 证书 ID。 | |
oneOf#2[].https_listen.hsts | integer enum | 否 | 是否启用 HSTS。 | 0 | 1 |
oneOf#2[].https_listen.http2 | integer enum | 否 | 是否启用 HTTP/2。 | 0 | 1 |
oneOf#2[].https_listen.http3 | integer enum | 否 | 是否启用 HTTP/3。 | 0 | 1 |
oneOf#2[].https_listen.force_ssl_enable | integer enum | 否 | 是否强制跳转 HTTPS。 | 0 | 1 |
oneOf#2[].https_listen.force_ssl_port | string | 否 | 强制跳转的 HTTPS 端口。 | |
oneOf#2[].auto_cert | integer enum | 否 | 是否自动申请证书。 | 0 | 1 |
oneOf#2[].balance_way | string enum | 否 | 负载均衡方式。 | ip_hash | rr |
oneOf#2[].backend_protocol | string enum | 否 | 回源协议。 | follow | http | https |
oneOf#2[].backend_http_port | integer | 否 | HTTP 回源端口。 | |
oneOf#2[].backend_https_port | integer | 否 | HTTPS 回源端口。 | |
oneOf#2[].proxy_timeout | integer | 否 | 回源读取超时秒数。 | |
oneOf#2[].proxy_connect_timeout | integer | 否 | 回源连接超时秒数。 | |
oneOf#2[].health_check | object | 否 | 源站健康检查配置。 | |
oneOf#2[].health_check.enable | integer enum | 否 | 是否启用检查。 | 0 | 1 |
oneOf#2[].health_check.host | string | 否 | 检查请求的 Host。 | |
oneOf#2[].health_check.path | string | 否 | 检查路径,必须以 `/` 开头。 | |
oneOf#2[].proxy_cache | integer enum | 否 | 是否启用代理缓存。 | 0 | 1 |
oneOf#2[].gzip_enable | integer enum | 否 | 是否启用 Gzip。 | 0 | 1 |
oneOf#2[].websocket_enable | integer enum | 否 | 是否启用 WebSocket 代理。 | 0 | 1 |
oneOf#2[].acl | integer | 否 | ACL ID;传 null 或 0 表示不绑定。ACL 必须已启用且属于当前目标用户,否则要求管理员权限。 | 12 |
oneOf#2[].acme_proxy_to_orgin | integer enum | 否 | 是否将 `/.well-known/acme-challenge/` 请求回源:1 开启,0 关闭。 | 1 |
oneOf#2[].backend_host | string | 否 | 回源 Host。允许 `$host`、`$host:$server_port`,或合法域名/IP及可选端口。 | $host |
oneOf#2[].backend_port_mapping | integer enum | 否 | 是否按客户端访问协议和端口进行回源端口映射。 | 1 |
oneOf#2[].backup_node_group | integer | 否 | 管理员专用。备用线路组 ID;必须与区域匹配且不能与主线路组相同。 | 22 |
oneOf#2[].black_ip | string | 否 | 网站黑名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。 | 198.51.100.0/24 |
oneOf#2[].block_proxy | integer enum | 否 | 是否拦截被识别为代理的客户端。 | 1 |
oneOf#2[].block_region | string | 否 | 按两字母小写国家/地区代码拦截,多个值以逗号分隔;空字符串表示关闭。 | us,jp |
oneOf#2[].block_time | integer | 否 | 自动黑名单持续时间,单位秒;非空时必须大于 600 且不超过 604800。 | 3600 |
oneOf#2[].cc_default_rule | integer | 否 | 默认 CC 规则 ID;规则必须存在且启用,使用其他用户的非内置规则需要管理员权限。 | 10002 |
oneOf#2[].cc_switch | object | 否 | CC 规则自动切换配置;空对象表示关闭。 | {"rule":10002,"switch":100,"enable":1} |
oneOf#2[].cc_switch.rule | integer | 是 | 切换后的 CC 规则 ID。 | 10002 |
oneOf#2[].cc_switch.switch | integer | 是 | 触发切换的请求阈值。 | 100 |
oneOf#2[].cc_switch.enable | integer enum | 否 | 是否启用自动切换。 | 1 |
oneOf#2[].cname_hostname | string | 否 | 管理员专用。网站 CNAME 主机名;各标签必须合法且在系统内唯一。 | site-a1b2c3 |
oneOf#2[].condition_backend | array | 否 | 按请求条件选择源站的规则列表。 | [{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}] |
oneOf#2[].condition_backend | array<object> | 否 | 按请求条件选择源站的规则列表。 | [{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}] |
oneOf#2[].condition_backend[].matcher | array | 是 | 全部匹配条件。 | |
oneOf#2[].condition_backend[].matcher | array<object> | 否 | 全部匹配条件。 | |
oneOf#2[].condition_backend[].matcher[].item | string | 是 | 匹配项。 | req_uri |
oneOf#2[].condition_backend[].matcher[].op | string enum | 是 | 匹配操作符。 | contain |
oneOf#2[].condition_backend[].matcher[].value | string | 是 | 匹配值;服务端会去除空行和首尾空白。 | /api/ |
oneOf#2[].condition_backend[].backend | array | 是 | 命中后使用的源站列表。 | |
oneOf#2[].condition_backend[].backend | array<object> | 否 | 命中后使用的源站列表。 | |
oneOf#2[].condition_backend[].backend[].addr | string | 是 | 源站 IPv4、IPv6 或域名。 | 198.51.100.10 |
oneOf#2[].condition_backend[].backend[].weight | integer | 否 | 源站权重。 | 1 |
oneOf#2[].condition_backend[].backend[].state | string enum | 否 | 源站状态。 | up |
oneOf#2[].cookie_domain | string | 否 | Cookie Domain;允许空字符串,非空时必须是合法域名。 | example.invalid |
oneOf#2[].cors | object | 否 | 跨域响应配置。 | {"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.enable | integer enum | 是 | 是否启用 CORS。 | 1 |
oneOf#2[].cors.allow_origin | string | 是 | Access-Control-Allow-Origin 值。 | * |
oneOf#2[].cors.allow_methods | string | 是 | 允许的方法,空格分隔。 | GET POST OPTIONS |
oneOf#2[].cors.allow_headers | string | 是 | 允许的请求头,空格分隔。 | Content-Type Authorization |
oneOf#2[].cors.expose_headers | string | 是 | 允许浏览器读取的响应头。 | Content-Length |
oneOf#2[].cors.allow_credentials | integer enum | 是 | 是否允许携带凭证。 | 1 |
oneOf#2[].cors.max_age | string | 是 | 预检结果缓存秒数;服务端要求传数字字符串。 | 1728000 |
oneOf#2[].dns_api | integer | 否 | DNS API 凭据 ID;必须属于目标用户。传 null 表示不绑定。 | 8 |
oneOf#2[].enable | integer enum | 否 | 网站启用状态:1 启用,0 禁用。 | 1 |
oneOf#2[].enable_ipv6 | integer enum | 否 | 是否启用 IPv6 CNAME;仅按网站生成 CNAME 且系统存在 IPv6 节点时可用。 | 1 |
oneOf#2[].extra_cc_rule | array | 否 | 网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。 | [{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}] |
oneOf#2[].extra_cc_rule | array<object> | 否 | 网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。 | [{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}] |
oneOf#2[].groups | string | 否 | 网站分组 ID,多个 ID 使用逗号分隔;空字符串表示不加入分组。 | 3,8 |
oneOf#2[].gzip_types | string | 否 | 启用 Gzip 的 MIME 类型,使用空格分隔;每项只能含字母、数字及 `/ - + . * _`。 | text/plain text/css application/json |
oneOf#2[].hotlink | object | 否 | 防盗链配置。 | {"enable":1,"domain":"www.example.invalid","allow_empty":0,"scope_type":"all","scope_content":""} |
oneOf#2[].hotlink.enable | integer enum | 是 | 是否启用防盗链。 | 1 |
oneOf#2[].hotlink.domain | string | 是 | 允许的来源域名,使用空格分隔;空值仅允许本站域名。 | www.example.invalid |
oneOf#2[].hotlink.allow_empty | integer enum | 是 | 是否允许空 Referer。 | 1 |
oneOf#2[].hotlink.scope_type | string enum | 否 | 生效范围。 | all |
oneOf#2[].hotlink.scope_content | string | 否 | 非 all 范围的匹配内容。 | /static/ |
oneOf#2[].is_default_server | integer enum | 否 | 管理员专用。是否作为线路范围内的默认站点;同一节点的监听端口不能与其它默认站点冲突。 | 1 |
oneOf#2[].l2_config_id | integer | 否 | 管理员专用。L2 配置 ID;必须存在、与网站区域一致并已绑定 L2 节点。 | 9 |
oneOf#2[].l2_state | string enum | 否 | 管理员专用。L2 模式。 | inherit |
oneOf#2[].log_req_body | integer enum | 否 | 管理员专用。是否记录请求体。 | 1 |
oneOf#2[].log_req_body_max_size | integer | 否 | 管理员专用。记录请求体的最大 KiB;不能超过 2048,也不能超过全局 client_body_buffer_size。 | 16 |
oneOf#2[].log_req_header | integer enum | 否 | 管理员专用。是否记录请求头。 | 1 |
oneOf#2[].log_resp_header | integer enum | 否 | 管理员专用。是否记录响应头。 | 1 |
oneOf#2[].node_group_id | integer | 否 | 管理员专用。主线路组 ID;必须属于目标区域;按套餐生成 CNAME 时不能单独指定。 | 21 |
oneOf#2[].page_403 | string | 否 | 自定义 403 错误页 HTML;空字符串使用默认页面。 | <h1>Forbidden</h1> |
oneOf#2[].page_404 | string | 否 | 自定义 404 错误页 HTML;空字符串使用默认页面。 | <h1>Not Found</h1> |
oneOf#2[].page_500 | string | 否 | 自定义 500 错误页 HTML;空字符串使用默认页面。 | <h1>Server Error</h1> |
oneOf#2[].page_502 | string | 否 | 自定义 502 错误页 HTML;空字符串使用默认页面。 | <h1>Bad Gateway</h1> |
oneOf#2[].page_504 | string | 否 | 自定义 504 错误页 HTML;空字符串使用默认页面。 | <h1>Gateway Timeout</h1> |
oneOf#2[].post_size_limit | string | 否 | POST 请求体大小限制。可使用纯数字或 b/k/m/g 单位,大小写均可;空字符串表示采用默认配置。 | 10m |
oneOf#2[].proxy_auth | object | 否 | 回源 Basic Auth 配置。 | {"enable":1,"username":"origin-user","password":"REDACTED"} |
oneOf#2[].proxy_auth.enable | integer enum | 是 | 是否启用回源认证。 | 1 |
oneOf#2[].proxy_auth.username | string | 否 | 认证用户名。 | origin-user |
oneOf#2[].proxy_auth.password | string | 否 | 认证密码。 | REDACTED |
oneOf#2[].proxy_http_version | string enum | 否 | 回源 HTTP 协议版本。 | 1.1 |
oneOf#2[].proxy_ssl_protocols | string | 否 | 允许的回源 TLS/SSL 协议,多个值使用空格分隔。 | TLSv1.2 TLSv1.3 |
oneOf#2[].range | integer enum | 否 | 是否启用分段回源。 | 1 |
oneOf#2[].recv_real_time | integer enum | 否 | 是否实时向客户端返回上游响应数据。 | 1 |
oneOf#2[].region_id | integer | 否 | 管理员专用。区域 ID;主、备用线路组必须属于该区域。 | 6 |
oneOf#2[].req_header | array | 否 | 添加或覆盖的回源请求头。 | [{"name":"X-Origin","value":"cdnfly"}] |
oneOf#2[].req_header | array<object> | 否 | 添加或覆盖的回源请求头。 | [{"name":"X-Origin","value":"cdnfly"}] |
oneOf#2[].req_header[].name | string | 是 | 请求头名称,必须以英文字母开头。 | X-Example |
oneOf#2[].req_header[].value | string | 是 | 请求头值,去除首尾空白后不能为空。 | example-value |
oneOf#2[].resp_header | array | 否 | 添加或覆盖的客户端响应头。 | [{"name":"X-Cache","value":"cdnfly"}] |
oneOf#2[].resp_header | array<object> | 否 | 添加或覆盖的客户端响应头。 | [{"name":"X-Cache","value":"cdnfly"}] |
oneOf#2[].resp_header[].name | string | 是 | 请求头名称,必须以英文字母开头。 | X-Example |
oneOf#2[].resp_header[].value | string | 是 | 请求头值,去除首尾空白后不能为空。 | example-value |
oneOf#2[].send_real_time | integer enum | 否 | 是否实时向上游发送客户端请求数据。 | 1 |
oneOf#2[].spider_allow | string enum | 否 | 搜索引擎爬虫访问策略;空字符串表示不单独设置。 | allow |
oneOf#2[].spider_to_sip | string | 否 | 搜索引擎专用回源 IP;空字符串表示关闭。仅按网站生成 CNAME 且 DNS 服务支持对应线路时可用。 | 198.51.100.20 |
oneOf#2[].state | string enum | 否 | 管理员专用。网站业务状态。 | 200 |
oneOf#2[].uid | integer | 否 | 管理员专用。创建时指定网站所属用户;更新转移网站时与 new_uid 配合,作为目标套餐归属校验用户。 | 12 |
oneOf#2[].ups_keepalive | integer enum | 否 | 是否启用上游 Keepalive。 | 1 |
oneOf#2[].ups_keepalive_conn | integer | 否 | 每个 worker 保留的上游 Keepalive 连接数。 | 16 |
oneOf#2[].ups_keepalive_timeout | integer | 否 | 上游 Keepalive 空闲超时秒数。 | 60 |
oneOf#2[].url_rewrite | array | 否 | URL 重定向规则。 | [{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}] |
oneOf#2[].url_rewrite | array<object> | 否 | URL 重定向规则。 | [{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}] |
oneOf#2[].url_rewrite[].host | string | 是 | 匹配 Host,不含 http:// 或 https://。 | www.example.invalid |
oneOf#2[].url_rewrite[].match | string | 是 | URI 匹配表达式。 | /(.*) |
oneOf#2[].url_rewrite[].redirect | string | 是 | 重定向目标;可使用 `$1` 或受支持的 Nginx 变量。 | https://example.invalid/$1 |
oneOf#2[].url_rewrite[].code | string enum | 是 | 重定向方式。 | 301 |
oneOf#2[].url_rewrite[].user_agent | string | 否 | User-Agent 匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].referer | string | 否 | Referer 匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].country_code | string | 否 | 国家代码匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].accept_language | string | 否 | Accept-Language 匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].province | string | 否 | 省份匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].city | string | 否 | 城市匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].isp | string | 否 | 运营商匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].asnumber | string | 否 | ASN 匹配;省略时为 `.*`。 | .* |
oneOf#2[].white_ip | string | 否 | 网站白名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。 | 203.0.113.10 |
oneOf#2[].white_time | integer | 否 | 自动白名单持续时间,单位秒;非空时不超过 604800。 | 3600 |
请求已被处理。成功时 `code` 为 0,`msg` 为“网站添加成功”,`data` 为新建网站 ID 组成的逗号分隔字符串;即使业务校验失败也返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0,失败时为对应的 site-* 错误码。 | 0 |
msg | string | 是 | 处理结果说明。 | 网站添加成功 |
data | string | 是 | 成功时为本次新建的网站 ID,多个 ID 使用英文逗号连接;失败时为空字符串。 | 101,102 |
PUT /v1/sites
批量更新网站配置。请求体可为单个对象或对象数组;单个对象会被转换为数组处理。每个对象必须包含已有网站的 `id`,仅传入需要修改的字段。普通用户只能更新自己的网站;管理员才能修改其他用户网站、归属用户、套餐、区域、线路和 CNAME 相关字段。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.id | integer | 是 | 必填。要更新的网站 ID,必须存在且当前用户有权限操作。 | |
oneOf#1.domain | string | 否 | 网站域名,多个域名以空白字符分隔;会转为小写且不得重复。修改后重新校验套餐配额、区域内域名和域名端口唯一性。 | |
oneOf#1.backend | array | 否 | 源站列表。每项地址必须为 IPv4、IPv6 或域名,地址不可重复,至少保留一个 `up` 状态源站。 | |
oneOf#1.backend | array<object> | 否 | 源站列表。每项地址必须为 IPv4、IPv6 或域名,地址不可重复,至少保留一个 `up` 状态源站。 | |
oneOf#1.backend[].addr | string | 是 | 源站地址。 | |
oneOf#1.backend[].weight | integer | 是 | 源站权重。 | |
oneOf#1.backend[].state | string enum | 是 | 源站状态。 | up | down | backup |
oneOf#1.user_package | integer | 否 | 用户套餐 ID;必须属于网站归属用户且可用。变更套餐会重新同步相关线路与配置。 | |
oneOf#1.new_uid | integer | 否 | 管理员专用。将网站转移到指定用户;同时必须传入 `user_package`。 | |
oneOf#1.uid | integer | 否 | 管理员专用。指定本次套餐与资源校验所使用的用户 ID。 | |
oneOf#1.http_listen | object | 否 | HTTP 监听配置;与 HTTPS 至少保留一个。 | |
oneOf#1.http_listen.port | string | 否 | 空白分隔的监听端口;每个端口必须有效、未占用且在区域允许范围内。 | |
oneOf#1.https_listen | object | 否 | HTTPS 监听配置。 | |
oneOf#1.https_listen.port | string | 否 | 空白分隔的 HTTPS 监听端口。 | |
oneOf#1.https_listen.cert | integer | 否 | 已启用证书 ID。 | |
oneOf#1.https_listen.hsts | integer enum | 否 | 是否启用 HSTS。 | 0 | 1 |
oneOf#1.https_listen.http2 | integer enum | 否 | 是否启用 HTTP/2。 | 0 | 1 |
oneOf#1.https_listen.http3 | integer enum | 否 | 是否启用 HTTP/3。 | 0 | 1 |
oneOf#1.https_listen.ocsp_stapling | integer enum | 否 | 是否启用 OCSP Stapling。 | 0 | 1 |
oneOf#1.https_listen.force_ssl_enable | integer enum | 否 | 是否强制跳转 HTTPS。 | 0 | 1 |
oneOf#1.https_listen.force_ssl_port | string | 否 | 强制跳转目标端口,必须在 HTTPS 监听端口中。 | |
oneOf#1.https_listen.ssl_protocols | string | 否 | 允许的 TLS 协议,使用空白字符分隔。 | |
oneOf#1.https_listen.ssl_ciphers | string | 否 | TLS 密码套件。 | |
oneOf#1.https_listen.ssl_prefer_server_ciphers | string enum | 否 | 是否优先使用服务端密码套件。 | on | off |
oneOf#1.balance_way | string enum | 否 | 负载均衡方式。`ip_hash` 不支持备用源站。 | ip_hash | rr |
oneOf#1.backend_protocol | string enum | 否 | 回源协议。 | follow | http | https |
oneOf#1.backend_http_port | integer | 否 | HTTP 回源端口。 | |
oneOf#1.backend_https_port | integer | 否 | HTTPS 回源端口。 | |
oneOf#1.backend_port_mapping | integer enum | 否 | 是否使用访问端口作为回源端口。 | 0 | 1 |
oneOf#1.proxy_timeout | integer | 否 | 回源读取超时,单位秒。 | |
oneOf#1.proxy_connect_timeout | integer | 否 | 回源连接超时,单位秒。 | |
oneOf#1.health_check | object | 否 | 健康检查配置。 | |
oneOf#1.health_check.enable | integer enum | 否 | 是否启用健康检查。 | 0 | 1 |
oneOf#1.health_check.host | string | 否 | 检查请求域名。 | |
oneOf#1.health_check.path | string | 否 | 检查路径,必须以 `/` 开头。 | |
oneOf#1.proxy_auth | object | 否 | 回源认证配置。 | |
oneOf#1.proxy_auth.enable | boolean | 否 | 是否启用认证。 | |
oneOf#1.proxy_auth.username | string | 否 | 认证用户名。 | |
oneOf#1.proxy_auth.password | string | 否 | 认证密码。 | |
oneOf#1.proxy_cache | integer enum | 否 | 是否启用代理缓存。 | 0 | 1 |
oneOf#1.gzip_enable | integer enum | 否 | 是否启用 Gzip。 | 0 | 1 |
oneOf#1.gzip_types | string | 否 | Gzip MIME 类型。 | |
oneOf#1.websocket_enable | integer enum | 否 | 是否启用 WebSocket 代理。 | 0 | 1 |
oneOf#1.enable | integer enum | 否 | 网站启用状态。 | 0 | 1 |
oneOf#1.state | string | 否 | 网站处理状态。 | |
oneOf#1.cname_mode | string enum | 否 | CNAME 使用方式;切换会触发相应同步任务。 | package | site |
oneOf#1.cname_domain | integer | 否 | 管理员专用。CNAME 域名配置 ID。 | |
oneOf#1.cname_hostname | string | 否 | 管理员专用。网站 CNAME 主机名,必须唯一且合法。 | |
oneOf#1.region_id | integer | 否 | 管理员专用。区域 ID。 | |
oneOf#1.node_group_id | integer | 否 | 管理员专用。主线路组 ID;CNAME 按套餐时不能单独修改。 | |
oneOf#1.backup_node_group | integer | 否 | 管理员专用。备用线路组 ID;不能与主线路组相同。 | |
oneOf#1.acl | integer | 否 | ACL ID;传 null 或 0 表示不绑定。ACL 必须已启用且属于当前目标用户,否则要求管理员权限。 | 12 |
oneOf#1.acme_proxy_to_orgin | integer enum | 否 | 是否将 `/.well-known/acme-challenge/` 请求回源:1 开启,0 关闭。 | 1 |
oneOf#1.backend_host | string | 否 | 回源 Host。允许 `$host`、`$host:$server_port`,或合法域名/IP及可选端口。 | $host |
oneOf#1.black_ip | string | 否 | 网站黑名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。 | 198.51.100.0/24 |
oneOf#1.block_proxy | integer enum | 否 | 是否拦截被识别为代理的客户端。 | 1 |
oneOf#1.block_region | string | 否 | 按两字母小写国家/地区代码拦截,多个值以逗号分隔;空字符串表示关闭。 | us,jp |
oneOf#1.block_time | integer | 否 | 自动黑名单持续时间,单位秒;非空时必须大于 600 且不超过 604800。 | 3600 |
oneOf#1.cc_default_rule | integer | 否 | 默认 CC 规则 ID;规则必须存在且启用,使用其他用户的非内置规则需要管理员权限。 | 10002 |
oneOf#1.cc_switch | object | 否 | CC 规则自动切换配置;空对象表示关闭。 | {"rule":10002,"switch":100,"enable":1} |
oneOf#1.cc_switch.rule | integer | 是 | 切换后的 CC 规则 ID。 | 10002 |
oneOf#1.cc_switch.switch | integer | 是 | 触发切换的请求阈值。 | 100 |
oneOf#1.cc_switch.enable | integer enum | 否 | 是否启用自动切换。 | 1 |
oneOf#1.condition_backend | array | 否 | 按请求条件选择源站的规则列表。 | [{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}] |
oneOf#1.condition_backend | array<object> | 否 | 按请求条件选择源站的规则列表。 | [{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}] |
oneOf#1.condition_backend[].matcher | array | 是 | 全部匹配条件。 | |
oneOf#1.condition_backend[].matcher | array<object> | 否 | 全部匹配条件。 | |
oneOf#1.condition_backend[].matcher[].item | string | 是 | 匹配项。 | req_uri |
oneOf#1.condition_backend[].matcher[].op | string enum | 是 | 匹配操作符。 | contain |
oneOf#1.condition_backend[].matcher[].value | string | 是 | 匹配值;服务端会去除空行和首尾空白。 | /api/ |
oneOf#1.condition_backend[].backend | array | 是 | 命中后使用的源站列表。 | |
oneOf#1.condition_backend[].backend | array<object> | 否 | 命中后使用的源站列表。 | |
oneOf#1.condition_backend[].backend[].addr | string | 是 | 源站 IPv4、IPv6 或域名。 | 198.51.100.10 |
oneOf#1.condition_backend[].backend[].weight | integer | 否 | 源站权重。 | 1 |
oneOf#1.condition_backend[].backend[].state | string enum | 否 | 源站状态。 | up |
oneOf#1.cookie_domain | string | 否 | Cookie Domain;允许空字符串,非空时必须是合法域名。 | example.invalid |
oneOf#1.cors | object | 否 | 跨域响应配置。 | {"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.enable | integer enum | 是 | 是否启用 CORS。 | 1 |
oneOf#1.cors.allow_origin | string | 是 | Access-Control-Allow-Origin 值。 | * |
oneOf#1.cors.allow_methods | string | 是 | 允许的方法,空格分隔。 | GET POST OPTIONS |
oneOf#1.cors.allow_headers | string | 是 | 允许的请求头,空格分隔。 | Content-Type Authorization |
oneOf#1.cors.expose_headers | string | 是 | 允许浏览器读取的响应头。 | Content-Length |
oneOf#1.cors.allow_credentials | integer enum | 是 | 是否允许携带凭证。 | 1 |
oneOf#1.cors.max_age | string | 是 | 预检结果缓存秒数;服务端要求传数字字符串。 | 1728000 |
oneOf#1.dns_api | integer | 否 | DNS API 凭据 ID;必须属于目标用户。传 null 表示不绑定。 | 8 |
oneOf#1.enable_ipv6 | integer enum | 否 | 是否启用 IPv6 CNAME;仅按网站生成 CNAME 且系统存在 IPv6 节点时可用。 | 1 |
oneOf#1.extra_cc_rule | array | 否 | 网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。 | [{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}] |
oneOf#1.extra_cc_rule | array<object> | 否 | 网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。 | [{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}] |
oneOf#1.groups | string | 否 | 网站分组 ID,多个 ID 使用逗号分隔;空字符串表示不加入分组。 | 3,8 |
oneOf#1.hotlink | object | 否 | 防盗链配置。 | {"enable":1,"domain":"www.example.invalid","allow_empty":0,"scope_type":"all","scope_content":""} |
oneOf#1.hotlink.enable | integer enum | 是 | 是否启用防盗链。 | 1 |
oneOf#1.hotlink.domain | string | 是 | 允许的来源域名,使用空格分隔;空值仅允许本站域名。 | www.example.invalid |
oneOf#1.hotlink.allow_empty | integer enum | 是 | 是否允许空 Referer。 | 1 |
oneOf#1.hotlink.scope_type | string enum | 否 | 生效范围。 | all |
oneOf#1.hotlink.scope_content | string | 否 | 非 all 范围的匹配内容。 | /static/ |
oneOf#1.is_default_server | integer enum | 否 | 管理员专用。是否作为线路范围内的默认站点;同一节点的监听端口不能与其它默认站点冲突。 | 1 |
oneOf#1.l2_config_id | integer | 否 | 管理员专用。L2 配置 ID;必须存在、与网站区域一致并已绑定 L2 节点。 | 9 |
oneOf#1.l2_state | string enum | 否 | 管理员专用。L2 模式。 | inherit |
oneOf#1.log_req_body | integer enum | 否 | 管理员专用。是否记录请求体。 | 1 |
oneOf#1.log_req_body_max_size | integer | 否 | 管理员专用。记录请求体的最大 KiB;不能超过 2048,也不能超过全局 client_body_buffer_size。 | 16 |
oneOf#1.log_req_header | integer enum | 否 | 管理员专用。是否记录请求头。 | 1 |
oneOf#1.log_resp_header | integer enum | 否 | 管理员专用。是否记录响应头。 | 1 |
oneOf#1.page_403 | string | 否 | 自定义 403 错误页 HTML;空字符串使用默认页面。 | <h1>Forbidden</h1> |
oneOf#1.page_404 | string | 否 | 自定义 404 错误页 HTML;空字符串使用默认页面。 | <h1>Not Found</h1> |
oneOf#1.page_500 | string | 否 | 自定义 500 错误页 HTML;空字符串使用默认页面。 | <h1>Server Error</h1> |
oneOf#1.page_502 | string | 否 | 自定义 502 错误页 HTML;空字符串使用默认页面。 | <h1>Bad Gateway</h1> |
oneOf#1.page_504 | string | 否 | 自定义 504 错误页 HTML;空字符串使用默认页面。 | <h1>Gateway Timeout</h1> |
oneOf#1.post_size_limit | string | 否 | POST 请求体大小限制。可使用纯数字或 b/k/m/g 单位,大小写均可;空字符串表示采用默认配置。 | 10m |
oneOf#1.proxy_http_version | string enum | 否 | 回源 HTTP 协议版本。 | 1.1 |
oneOf#1.proxy_ssl_protocols | string | 否 | 允许的回源 TLS/SSL 协议,多个值使用空格分隔。 | TLSv1.2 TLSv1.3 |
oneOf#1.range | integer enum | 否 | 是否启用分段回源。 | 1 |
oneOf#1.recv_real_time | integer enum | 否 | 是否实时向客户端返回上游响应数据。 | 1 |
oneOf#1.req_header | array | 否 | 添加或覆盖的回源请求头。 | [{"name":"X-Origin","value":"cdnfly"}] |
oneOf#1.req_header | array<object> | 否 | 添加或覆盖的回源请求头。 | [{"name":"X-Origin","value":"cdnfly"}] |
oneOf#1.req_header[].name | string | 是 | 请求头名称,必须以英文字母开头。 | X-Example |
oneOf#1.req_header[].value | string | 是 | 请求头值,去除首尾空白后不能为空。 | example-value |
oneOf#1.resp_header | array | 否 | 添加或覆盖的客户端响应头。 | [{"name":"X-Cache","value":"cdnfly"}] |
oneOf#1.resp_header | array<object> | 否 | 添加或覆盖的客户端响应头。 | [{"name":"X-Cache","value":"cdnfly"}] |
oneOf#1.resp_header[].name | string | 是 | 请求头名称,必须以英文字母开头。 | X-Example |
oneOf#1.resp_header[].value | string | 是 | 请求头值,去除首尾空白后不能为空。 | example-value |
oneOf#1.send_real_time | integer enum | 否 | 是否实时向上游发送客户端请求数据。 | 1 |
oneOf#1.spider_allow | string enum | 否 | 搜索引擎爬虫访问策略;空字符串表示不单独设置。 | allow |
oneOf#1.spider_to_sip | string | 否 | 搜索引擎专用回源 IP;空字符串表示关闭。仅按网站生成 CNAME 且 DNS 服务支持对应线路时可用。 | 198.51.100.20 |
oneOf#1.ups_keepalive | integer enum | 否 | 是否启用上游 Keepalive。 | 1 |
oneOf#1.ups_keepalive_conn | integer | 否 | 每个 worker 保留的上游 Keepalive 连接数。 | 16 |
oneOf#1.ups_keepalive_timeout | integer | 否 | 上游 Keepalive 空闲超时秒数。 | 60 |
oneOf#1.url_rewrite | array | 否 | URL 重定向规则。 | [{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}] |
oneOf#1.url_rewrite | array<object> | 否 | URL 重定向规则。 | [{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}] |
oneOf#1.url_rewrite[].host | string | 是 | 匹配 Host,不含 http:// 或 https://。 | www.example.invalid |
oneOf#1.url_rewrite[].match | string | 是 | URI 匹配表达式。 | /(.*) |
oneOf#1.url_rewrite[].redirect | string | 是 | 重定向目标;可使用 `$1` 或受支持的 Nginx 变量。 | https://example.invalid/$1 |
oneOf#1.url_rewrite[].code | string enum | 是 | 重定向方式。 | 301 |
oneOf#1.url_rewrite[].user_agent | string | 否 | User-Agent 匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].referer | string | 否 | Referer 匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].country_code | string | 否 | 国家代码匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].accept_language | string | 否 | Accept-Language 匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].province | string | 否 | 省份匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].city | string | 否 | 城市匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].isp | string | 否 | 运营商匹配;省略时为 `.*`。 | .* |
oneOf#1.url_rewrite[].asnumber | string | 否 | ASN 匹配;省略时为 `.*`。 | .* |
oneOf#1.white_ip | string | 否 | 网站白名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。 | 203.0.113.10 |
oneOf#1.white_time | integer | 否 | 自动白名单持续时间,单位秒;非空时不超过 604800。 | 3600 |
oneOf#2 | array<object> | 否 | 批量更新对象数组;每个元素独立按相同规则校验和更新。 | |
oneOf#2[].id | integer | 是 | 必填。要更新的网站 ID,必须存在且当前用户有权限操作。 | |
oneOf#2[].domain | string | 否 | 网站域名,多个域名以空白字符分隔;会转为小写且不得重复。修改后重新校验套餐配额、区域内域名和域名端口唯一性。 | |
oneOf#2[].backend | array | 否 | 源站列表。每项地址必须为 IPv4、IPv6 或域名,地址不可重复,至少保留一个 `up` 状态源站。 | |
oneOf#2[].backend | array<object> | 否 | 源站列表。每项地址必须为 IPv4、IPv6 或域名,地址不可重复,至少保留一个 `up` 状态源站。 | |
oneOf#2[].backend[].addr | string | 是 | 源站地址。 | |
oneOf#2[].backend[].weight | integer | 是 | 源站权重。 | |
oneOf#2[].backend[].state | string enum | 是 | 源站状态。 | up | down | backup |
oneOf#2[].user_package | integer | 否 | 用户套餐 ID;必须属于网站归属用户且可用。变更套餐会重新同步相关线路与配置。 | |
oneOf#2[].new_uid | integer | 否 | 管理员专用。将网站转移到指定用户;同时必须传入 `user_package`。 | |
oneOf#2[].uid | integer | 否 | 管理员专用。指定本次套餐与资源校验所使用的用户 ID。 | |
oneOf#2[].http_listen | object | 否 | HTTP 监听配置;与 HTTPS 至少保留一个。 | |
oneOf#2[].http_listen.port | string | 否 | 空白分隔的监听端口;每个端口必须有效、未占用且在区域允许范围内。 | |
oneOf#2[].https_listen | object | 否 | HTTPS 监听配置。 | |
oneOf#2[].https_listen.port | string | 否 | 空白分隔的 HTTPS 监听端口。 | |
oneOf#2[].https_listen.cert | integer | 否 | 已启用证书 ID。 | |
oneOf#2[].https_listen.hsts | integer enum | 否 | 是否启用 HSTS。 | 0 | 1 |
oneOf#2[].https_listen.http2 | integer enum | 否 | 是否启用 HTTP/2。 | 0 | 1 |
oneOf#2[].https_listen.http3 | integer enum | 否 | 是否启用 HTTP/3。 | 0 | 1 |
oneOf#2[].https_listen.ocsp_stapling | integer enum | 否 | 是否启用 OCSP Stapling。 | 0 | 1 |
oneOf#2[].https_listen.force_ssl_enable | integer enum | 否 | 是否强制跳转 HTTPS。 | 0 | 1 |
oneOf#2[].https_listen.force_ssl_port | string | 否 | 强制跳转目标端口,必须在 HTTPS 监听端口中。 | |
oneOf#2[].https_listen.ssl_protocols | string | 否 | 允许的 TLS 协议,使用空白字符分隔。 | |
oneOf#2[].https_listen.ssl_ciphers | string | 否 | TLS 密码套件。 | |
oneOf#2[].https_listen.ssl_prefer_server_ciphers | string enum | 否 | 是否优先使用服务端密码套件。 | on | off |
oneOf#2[].balance_way | string enum | 否 | 负载均衡方式。`ip_hash` 不支持备用源站。 | ip_hash | rr |
oneOf#2[].backend_protocol | string enum | 否 | 回源协议。 | follow | http | https |
oneOf#2[].backend_http_port | integer | 否 | HTTP 回源端口。 | |
oneOf#2[].backend_https_port | integer | 否 | HTTPS 回源端口。 | |
oneOf#2[].backend_port_mapping | integer enum | 否 | 是否使用访问端口作为回源端口。 | 0 | 1 |
oneOf#2[].proxy_timeout | integer | 否 | 回源读取超时,单位秒。 | |
oneOf#2[].proxy_connect_timeout | integer | 否 | 回源连接超时,单位秒。 | |
oneOf#2[].health_check | object | 否 | 健康检查配置。 | |
oneOf#2[].health_check.enable | integer enum | 否 | 是否启用健康检查。 | 0 | 1 |
oneOf#2[].health_check.host | string | 否 | 检查请求域名。 | |
oneOf#2[].health_check.path | string | 否 | 检查路径,必须以 `/` 开头。 | |
oneOf#2[].proxy_auth | object | 否 | 回源认证配置。 | |
oneOf#2[].proxy_auth.enable | boolean | 否 | 是否启用认证。 | |
oneOf#2[].proxy_auth.username | string | 否 | 认证用户名。 | |
oneOf#2[].proxy_auth.password | string | 否 | 认证密码。 | |
oneOf#2[].proxy_cache | integer enum | 否 | 是否启用代理缓存。 | 0 | 1 |
oneOf#2[].gzip_enable | integer enum | 否 | 是否启用 Gzip。 | 0 | 1 |
oneOf#2[].gzip_types | string | 否 | Gzip MIME 类型。 | |
oneOf#2[].websocket_enable | integer enum | 否 | 是否启用 WebSocket 代理。 | 0 | 1 |
oneOf#2[].enable | integer enum | 否 | 网站启用状态。 | 0 | 1 |
oneOf#2[].state | string | 否 | 网站处理状态。 | |
oneOf#2[].cname_mode | string enum | 否 | CNAME 使用方式;切换会触发相应同步任务。 | package | site |
oneOf#2[].cname_domain | integer | 否 | 管理员专用。CNAME 域名配置 ID。 | |
oneOf#2[].cname_hostname | string | 否 | 管理员专用。网站 CNAME 主机名,必须唯一且合法。 | |
oneOf#2[].region_id | integer | 否 | 管理员专用。区域 ID。 | |
oneOf#2[].node_group_id | integer | 否 | 管理员专用。主线路组 ID;CNAME 按套餐时不能单独修改。 | |
oneOf#2[].backup_node_group | integer | 否 | 管理员专用。备用线路组 ID;不能与主线路组相同。 | |
oneOf#2[].acl | integer | 否 | ACL ID;传 null 或 0 表示不绑定。ACL 必须已启用且属于当前目标用户,否则要求管理员权限。 | 12 |
oneOf#2[].acme_proxy_to_orgin | integer enum | 否 | 是否将 `/.well-known/acme-challenge/` 请求回源:1 开启,0 关闭。 | 1 |
oneOf#2[].backend_host | string | 否 | 回源 Host。允许 `$host`、`$host:$server_port`,或合法域名/IP及可选端口。 | $host |
oneOf#2[].black_ip | string | 否 | 网站黑名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。 | 198.51.100.0/24 |
oneOf#2[].block_proxy | integer enum | 否 | 是否拦截被识别为代理的客户端。 | 1 |
oneOf#2[].block_region | string | 否 | 按两字母小写国家/地区代码拦截,多个值以逗号分隔;空字符串表示关闭。 | us,jp |
oneOf#2[].block_time | integer | 否 | 自动黑名单持续时间,单位秒;非空时必须大于 600 且不超过 604800。 | 3600 |
oneOf#2[].cc_default_rule | integer | 否 | 默认 CC 规则 ID;规则必须存在且启用,使用其他用户的非内置规则需要管理员权限。 | 10002 |
oneOf#2[].cc_switch | object | 否 | CC 规则自动切换配置;空对象表示关闭。 | {"rule":10002,"switch":100,"enable":1} |
oneOf#2[].cc_switch.rule | integer | 是 | 切换后的 CC 规则 ID。 | 10002 |
oneOf#2[].cc_switch.switch | integer | 是 | 触发切换的请求阈值。 | 100 |
oneOf#2[].cc_switch.enable | integer enum | 否 | 是否启用自动切换。 | 1 |
oneOf#2[].condition_backend | array | 否 | 按请求条件选择源站的规则列表。 | [{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}] |
oneOf#2[].condition_backend | array<object> | 否 | 按请求条件选择源站的规则列表。 | [{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}] |
oneOf#2[].condition_backend[].matcher | array | 是 | 全部匹配条件。 | |
oneOf#2[].condition_backend[].matcher | array<object> | 否 | 全部匹配条件。 | |
oneOf#2[].condition_backend[].matcher[].item | string | 是 | 匹配项。 | req_uri |
oneOf#2[].condition_backend[].matcher[].op | string enum | 是 | 匹配操作符。 | contain |
oneOf#2[].condition_backend[].matcher[].value | string | 是 | 匹配值;服务端会去除空行和首尾空白。 | /api/ |
oneOf#2[].condition_backend[].backend | array | 是 | 命中后使用的源站列表。 | |
oneOf#2[].condition_backend[].backend | array<object> | 否 | 命中后使用的源站列表。 | |
oneOf#2[].condition_backend[].backend[].addr | string | 是 | 源站 IPv4、IPv6 或域名。 | 198.51.100.10 |
oneOf#2[].condition_backend[].backend[].weight | integer | 否 | 源站权重。 | 1 |
oneOf#2[].condition_backend[].backend[].state | string enum | 否 | 源站状态。 | up |
oneOf#2[].cookie_domain | string | 否 | Cookie Domain;允许空字符串,非空时必须是合法域名。 | example.invalid |
oneOf#2[].cors | object | 否 | 跨域响应配置。 | {"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.enable | integer enum | 是 | 是否启用 CORS。 | 1 |
oneOf#2[].cors.allow_origin | string | 是 | Access-Control-Allow-Origin 值。 | * |
oneOf#2[].cors.allow_methods | string | 是 | 允许的方法,空格分隔。 | GET POST OPTIONS |
oneOf#2[].cors.allow_headers | string | 是 | 允许的请求头,空格分隔。 | Content-Type Authorization |
oneOf#2[].cors.expose_headers | string | 是 | 允许浏览器读取的响应头。 | Content-Length |
oneOf#2[].cors.allow_credentials | integer enum | 是 | 是否允许携带凭证。 | 1 |
oneOf#2[].cors.max_age | string | 是 | 预检结果缓存秒数;服务端要求传数字字符串。 | 1728000 |
oneOf#2[].dns_api | integer | 否 | DNS API 凭据 ID;必须属于目标用户。传 null 表示不绑定。 | 8 |
oneOf#2[].enable_ipv6 | integer enum | 否 | 是否启用 IPv6 CNAME;仅按网站生成 CNAME 且系统存在 IPv6 节点时可用。 | 1 |
oneOf#2[].extra_cc_rule | array | 否 | 网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。 | [{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}] |
oneOf#2[].extra_cc_rule | array<object> | 否 | 网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。 | [{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}] |
oneOf#2[].groups | string | 否 | 网站分组 ID,多个 ID 使用逗号分隔;空字符串表示不加入分组。 | 3,8 |
oneOf#2[].hotlink | object | 否 | 防盗链配置。 | {"enable":1,"domain":"www.example.invalid","allow_empty":0,"scope_type":"all","scope_content":""} |
oneOf#2[].hotlink.enable | integer enum | 是 | 是否启用防盗链。 | 1 |
oneOf#2[].hotlink.domain | string | 是 | 允许的来源域名,使用空格分隔;空值仅允许本站域名。 | www.example.invalid |
oneOf#2[].hotlink.allow_empty | integer enum | 是 | 是否允许空 Referer。 | 1 |
oneOf#2[].hotlink.scope_type | string enum | 否 | 生效范围。 | all |
oneOf#2[].hotlink.scope_content | string | 否 | 非 all 范围的匹配内容。 | /static/ |
oneOf#2[].is_default_server | integer enum | 否 | 管理员专用。是否作为线路范围内的默认站点;同一节点的监听端口不能与其它默认站点冲突。 | 1 |
oneOf#2[].l2_config_id | integer | 否 | 管理员专用。L2 配置 ID;必须存在、与网站区域一致并已绑定 L2 节点。 | 9 |
oneOf#2[].l2_state | string enum | 否 | 管理员专用。L2 模式。 | inherit |
oneOf#2[].log_req_body | integer enum | 否 | 管理员专用。是否记录请求体。 | 1 |
oneOf#2[].log_req_body_max_size | integer | 否 | 管理员专用。记录请求体的最大 KiB;不能超过 2048,也不能超过全局 client_body_buffer_size。 | 16 |
oneOf#2[].log_req_header | integer enum | 否 | 管理员专用。是否记录请求头。 | 1 |
oneOf#2[].log_resp_header | integer enum | 否 | 管理员专用。是否记录响应头。 | 1 |
oneOf#2[].page_403 | string | 否 | 自定义 403 错误页 HTML;空字符串使用默认页面。 | <h1>Forbidden</h1> |
oneOf#2[].page_404 | string | 否 | 自定义 404 错误页 HTML;空字符串使用默认页面。 | <h1>Not Found</h1> |
oneOf#2[].page_500 | string | 否 | 自定义 500 错误页 HTML;空字符串使用默认页面。 | <h1>Server Error</h1> |
oneOf#2[].page_502 | string | 否 | 自定义 502 错误页 HTML;空字符串使用默认页面。 | <h1>Bad Gateway</h1> |
oneOf#2[].page_504 | string | 否 | 自定义 504 错误页 HTML;空字符串使用默认页面。 | <h1>Gateway Timeout</h1> |
oneOf#2[].post_size_limit | string | 否 | POST 请求体大小限制。可使用纯数字或 b/k/m/g 单位,大小写均可;空字符串表示采用默认配置。 | 10m |
oneOf#2[].proxy_http_version | string enum | 否 | 回源 HTTP 协议版本。 | 1.1 |
oneOf#2[].proxy_ssl_protocols | string | 否 | 允许的回源 TLS/SSL 协议,多个值使用空格分隔。 | TLSv1.2 TLSv1.3 |
oneOf#2[].range | integer enum | 否 | 是否启用分段回源。 | 1 |
oneOf#2[].recv_real_time | integer enum | 否 | 是否实时向客户端返回上游响应数据。 | 1 |
oneOf#2[].req_header | array | 否 | 添加或覆盖的回源请求头。 | [{"name":"X-Origin","value":"cdnfly"}] |
oneOf#2[].req_header | array<object> | 否 | 添加或覆盖的回源请求头。 | [{"name":"X-Origin","value":"cdnfly"}] |
oneOf#2[].req_header[].name | string | 是 | 请求头名称,必须以英文字母开头。 | X-Example |
oneOf#2[].req_header[].value | string | 是 | 请求头值,去除首尾空白后不能为空。 | example-value |
oneOf#2[].resp_header | array | 否 | 添加或覆盖的客户端响应头。 | [{"name":"X-Cache","value":"cdnfly"}] |
oneOf#2[].resp_header | array<object> | 否 | 添加或覆盖的客户端响应头。 | [{"name":"X-Cache","value":"cdnfly"}] |
oneOf#2[].resp_header[].name | string | 是 | 请求头名称,必须以英文字母开头。 | X-Example |
oneOf#2[].resp_header[].value | string | 是 | 请求头值,去除首尾空白后不能为空。 | example-value |
oneOf#2[].send_real_time | integer enum | 否 | 是否实时向上游发送客户端请求数据。 | 1 |
oneOf#2[].spider_allow | string enum | 否 | 搜索引擎爬虫访问策略;空字符串表示不单独设置。 | allow |
oneOf#2[].spider_to_sip | string | 否 | 搜索引擎专用回源 IP;空字符串表示关闭。仅按网站生成 CNAME 且 DNS 服务支持对应线路时可用。 | 198.51.100.20 |
oneOf#2[].ups_keepalive | integer enum | 否 | 是否启用上游 Keepalive。 | 1 |
oneOf#2[].ups_keepalive_conn | integer | 否 | 每个 worker 保留的上游 Keepalive 连接数。 | 16 |
oneOf#2[].ups_keepalive_timeout | integer | 否 | 上游 Keepalive 空闲超时秒数。 | 60 |
oneOf#2[].url_rewrite | array | 否 | URL 重定向规则。 | [{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}] |
oneOf#2[].url_rewrite | array<object> | 否 | URL 重定向规则。 | [{"host":"www.example.invalid","match":"/(.*)","redirect":"https://example.invalid/$1","code":"301"}] |
oneOf#2[].url_rewrite[].host | string | 是 | 匹配 Host,不含 http:// 或 https://。 | www.example.invalid |
oneOf#2[].url_rewrite[].match | string | 是 | URI 匹配表达式。 | /(.*) |
oneOf#2[].url_rewrite[].redirect | string | 是 | 重定向目标;可使用 `$1` 或受支持的 Nginx 变量。 | https://example.invalid/$1 |
oneOf#2[].url_rewrite[].code | string enum | 是 | 重定向方式。 | 301 |
oneOf#2[].url_rewrite[].user_agent | string | 否 | User-Agent 匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].referer | string | 否 | Referer 匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].country_code | string | 否 | 国家代码匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].accept_language | string | 否 | Accept-Language 匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].province | string | 否 | 省份匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].city | string | 否 | 城市匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].isp | string | 否 | 运营商匹配;省略时为 `.*`。 | .* |
oneOf#2[].url_rewrite[].asnumber | string | 否 | ASN 匹配;省略时为 `.*`。 | .* |
oneOf#2[].white_ip | string | 否 | 网站白名单,每行可写 IP 或 CIDR;支持空行、注释和行尾注释,数量受区域配置限制。 | 203.0.113.10 |
oneOf#2[].white_time | integer | 否 | 自动白名单持续时间,单位秒;非空时不超过 604800。 | 3600 |
请求已被处理。成功时 `code` 为 0、`msg` 为“更新网站成功”、`data` 为 null;业务校验失败同样返回 HTTP 200,并在 `code` 与 `msg` 中说明原因。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0,失败时为对应的 site-* 错误码。 | 0 |
msg | string | 是 | 处理结果说明。 | 更新网站成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
DELETE /v1/sites/{site_id}
删除一个或多个网站。路径参数可使用单个网站 ID,也可使用英文逗号分隔的多个 ID。每个网站都必须存在、属于当前用户(否则需管理员权限)、处于禁用状态,且没有未完成的网站同步任务;任一项目不满足条件时整个请求会回滚。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
site_id | path | string | 是 | 要删除的网站 ID,或以英文逗号分隔的网站 ID 列表;每一项必须是数字。 | 101,102 |
请求已被处理。成功时 `code` 为 0、`msg` 为“网站删除成功”、`data` 为 null;即使 ID 无效、网站不存在、网站未禁用、任务未完成或无权限,也返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 网站删除成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
GET /v1/sites/{site_id}
获取指定网站的完整配置、套餐、线路和任务状态。普通用户只能读取自己的网站;读取其他用户的网站需要管理员权限。配置类字段按数据库原值返回,其中多项为 JSON 字符串,调用方需要自行解析。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
site_id | path | integer | 是 | 要查询的网站 ID,必须是当前用户的网站;管理员可查询任意已有网站。 | |
请求已被处理。成功时 `code` 为 0,`data` 为网站详情;网站不存在或无权限时仍返回 HTTP 200 并提供业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 成功时为空字符串,失败时为错误说明。 | |
data | object | 是 | 网站详情。JSON 配置字段以字符串形式返回。 | |
data.id | integer | 是 | 网站 ID。 | |
data.uid | integer | 是 | 网站归属用户 ID。 | |
data.name | string | 否 | 归属用户名。 | |
data.domain | string | 是 | 网站域名,多个域名以空白字符分隔。 | |
data.backend | string | 是 | 源站列表的 JSON 字符串;每项包含 addr、weight、state。 | |
data.backend_host | string | 否 | 回源 Host 配置。 | |
data.backend_protocol | string | 否 | 回源协议:follow、http 或 https。 | |
data.backend_http_port | integer | 否 | HTTP 回源端口。 | |
data.backend_https_port | integer | 否 | HTTPS 回源端口。 | |
data.backend_port_mapping | integer | 否 | 是否启用回源端口映射。 | |
data.balance_way | string | 否 | 负载均衡方式。 | |
data.http_listen | string | 否 | HTTP 监听配置的 JSON 字符串。 | |
data.https_listen | string | 否 | HTTPS 监听配置的 JSON 字符串。 | |
data.user_package | integer | 是 | 使用的用户套餐 ID。 | |
data.package_id | integer | 否 | 底层套餐 ID。 | |
data.package_name | string | 否 | 用户套餐名称。 | |
data.end_at | string | 否 | 用户套餐到期时间,格式为 YYYY-MM-DD HH:mm:ss。 | |
data.region_id | integer | 否 | 区域 ID。 | |
data.region_name | string | 否 | 区域名称。 | |
data.node_group_id | integer | 否 | 主线路组 ID。 | |
data.node_group_name | string | 否 | 主线路组名称。 | |
data.node_group_ipv6 | integer enum | 否 | 主线路组是否含 IPv6 节点。 | 0 | 1 |
data.backup_node_group | integer | 否 | 备用线路组 ID。 | |
data.backup_node_group_name | string | 否 | 备用线路组名称。 | |
data.cname_mode | string | 否 | CNAME 使用方式。 | |
data.cname_hostname | string | 否 | 网站 CNAME 主机名。 | |
data.cname_domain | string | 否 | 网站 CNAME 域名。 | |
data.up_cname_domain | string | 否 | 套餐 CNAME 域名。 | |
data.up_cname_hostname | string | 否 | 套餐 CNAME 主机名。 | |
data.enable | integer enum | 是 | 网站是否启用。 | 0 | 1 |
data.site_state | string | 是 | 网站当前状态。 | |
data.sync_state | string | 否 | 网站同步任务状态。 | |
data.cname_state | string | 否 | CNAME 任务状态。 | |
data.task_id | integer | 否 | 网站同步任务 ID。 | |
data.cname_task_id | integer | 否 | CNAME 任务 ID。 | |
data.groups | string | 否 | 网站分组 ID 的逗号分隔字符串。 | |
data.group_name | string | 否 | 网站分组名称的逗号分隔字符串。 | |
data.health_check | string | 否 | 健康检查配置的 JSON 字符串。 | |
data.proxy_timeout | integer | 否 | 回源读取超时秒数。 | |
data.proxy_connect_timeout | integer | 否 | 回源连接超时秒数。 | |
data.proxy_auth | string | 否 | 回源认证配置的 JSON 字符串。 | |
data.proxy_cache | integer | 否 | 是否启用代理缓存。 | |
data.proxy_http_version | string | 否 | 回源 HTTP 版本。 | |
data.proxy_ssl_protocols | string | 否 | 回源 TLS 协议配置。 | |
data.gzip_enable | integer | 否 | 是否启用 Gzip。 | |
data.gzip_types | string | 否 | Gzip MIME 类型。 | |
data.websocket_enable | integer | 否 | 是否启用 WebSocket。 | |
data.cors | string | 否 | 跨域配置的 JSON 字符串。 | |
data.hotlink | string | 否 | 防盗链配置的 JSON 字符串。 | |
data.acl | string | 否 | 访问控制列表配置。 | |
data.black_ip | string | 否 | IP 黑名单配置。 | |
data.white_ip | string | 否 | IP 白名单配置。 | |
data.block_proxy | integer | 否 | 是否拦截代理请求。 | |
data.block_region | string | 否 | 地域拦截配置。 | |
data.cc_default_rule | string | 否 | 默认 CC 防护规则 ID。 | |
data.cc_switch | string | 否 | CC 开关配置的 JSON 字符串。 | |
data.condition_backend | string | 否 | 条件回源配置的 JSON 字符串。 | |
data.extra_cc_rule | string | 否 | 附加 CC 规则配置。 | |
data.req_header | string | 否 | 请求头改写配置。 | |
data.resp_header | string | 否 | 响应头改写配置。 | |
data.url_rewrite | string | 否 | URL 重写配置。 | |
data.page_403 | string | 否 | 403 页面配置。 | |
data.page_404 | string | 否 | 404 页面配置。 | |
data.page_500 | string | 否 | 500 页面配置。 | |
data.page_502 | string | 否 | 502 页面配置。 | |
data.page_504 | string | 否 | 504 页面配置。 | |
data.create_at2 | string | 否 | 创建时间,格式为 YYYY-MM-DD HH:mm:ss。 | |
data.update_at2 | string | 否 | 更新时间,格式为 YYYY-MM-DD HH:mm:ss。 | |
data.version | integer | 否 | 配置版本号。 | |
PUT /v1/sites/{site_id}
更新一个网站的指定配置。路径中的 `site_id` 会强制写入请求对象,客户端传入的同名字段会被覆盖;请求体必须是 JSON 对象而非数组。仅传需要修改的字段。普通用户仅能更新自己的网站,涉及归属用户、套餐、区域、线路和 CNAME 资源的字段仅管理员可用。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
site_id | path | integer | 是 | 要更新的网站 ID;必须存在,且当前用户必须拥有该网站或具备管理员权限。 | |
请求体必填。
Content-Type:application/json
单网站更新对象;`id` 由路径参数注入,不能用请求体更换目标网站。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
domain | string | 否 | 网站域名,多个域名以空白字符分隔。修改时会转小写,并校验域名、主域名、区域内域名及端口唯一性。 | |
backend | array | 否 | 完整源站列表;至少包含一个状态为 `up` 的源站。 | |
backend | array<object> | 否 | 完整源站列表;至少包含一个状态为 `up` 的源站。 | |
backend[].addr | string | 是 | 源站 IPv4、IPv6 或域名。 | |
backend[].weight | integer | 是 | 源站权重。 | |
backend[].state | string enum | 是 | 源站状态。 | up | down | backup |
user_package | integer | 否 | 用户套餐 ID;套餐必须属于网站归属用户且处于可用状态。 | |
new_uid | integer | 否 | 管理员专用。将网站转移至指定用户;同时必须设置 `user_package`。 | |
http_listen | object | 否 | HTTP 监听配置。 | |
http_listen.port | string | 否 | 空白分隔的端口;每项必须有效、允许且未占用。 | |
https_listen | object | 否 | HTTPS 监听配置。 | |
https_listen.port | string | 否 | 空白分隔的 HTTPS 端口。 | |
https_listen.cert | integer | 否 | 已启用证书 ID。 | |
https_listen.hsts | integer enum | 否 | 是否启用 HSTS。 | 0 | 1 |
https_listen.http2 | integer enum | 否 | 是否启用 HTTP/2。 | 0 | 1 |
https_listen.http3 | integer enum | 否 | 是否启用 HTTP/3。 | 0 | 1 |
https_listen.ocsp_stapling | integer enum | 否 | 是否启用 OCSP Stapling。 | 0 | 1 |
https_listen.force_ssl_enable | integer enum | 否 | 是否强制 HTTPS。 | 0 | 1 |
https_listen.force_ssl_port | string | 否 | 强制跳转目标 HTTPS 端口。 | |
https_listen.ssl_protocols | string | 否 | TLS 协议列表。 | |
https_listen.ssl_ciphers | string | 否 | TLS 密码套件。 | |
https_listen.ssl_prefer_server_ciphers | string enum | 否 | 是否优先服务端密码套件。 | on | off |
balance_way | string enum | 否 | 负载均衡方式。 | ip_hash | rr |
backend_protocol | string enum | 否 | 回源协议。 | follow | http | https |
backend_http_port | integer | 否 | HTTP 回源端口。 | |
backend_https_port | integer | 否 | HTTPS 回源端口。 | |
backend_port_mapping | integer enum | 否 | 是否将访问端口映射到回源端口。 | 0 | 1 |
proxy_timeout | integer | 否 | 回源读取超时秒数。 | |
proxy_connect_timeout | integer | 否 | 回源连接超时秒数。 | |
proxy_auth | object | 否 | 回源认证配置。 | |
proxy_auth.enable | boolean | 否 | 是否启用认证。 | |
proxy_auth.username | string | 否 | 认证用户名。 | |
proxy_auth.password | string | 否 | 认证密码。 | |
health_check | object | 否 | 健康检查配置。 | |
health_check.enable | integer enum | 否 | 是否启用。 | 0 | 1 |
health_check.host | string | 否 | 检查域名。 | |
health_check.path | string | 否 | 检查路径,须以 `/` 开头。 | |
proxy_cache | integer enum | 否 | 是否启用代理缓存。 | 0 | 1 |
gzip_enable | integer enum | 否 | 是否启用 Gzip。 | 0 | 1 |
gzip_types | string | 否 | Gzip MIME 类型列表。 | |
websocket_enable | integer enum | 否 | 是否启用 WebSocket。 | 0 | 1 |
enable | integer enum | 否 | 网站启用状态。 | 0 | 1 |
state | string | 否 | 网站状态。 | |
groups | string | 否 | 网站分组 ID,多个 ID 以英文逗号分隔;传空字符串可移除全部分组。 | |
cname_mode | string enum | 否 | CNAME 使用方式。 | package | site |
cname_domain | integer | 否 | 管理员专用。CNAME 域名配置 ID。 | |
cname_hostname | string | 否 | 管理员专用。CNAME 主机名。 | |
region_id | integer | 否 | 管理员专用。区域 ID。 | |
node_group_id | integer | 否 | 管理员专用。主线路组 ID。 | |
backup_node_group | integer | 否 | 管理员专用。备用线路组 ID;可传空值清除。 | |
acl | string | 否 | 访问控制列表配置。 | |
black_ip | string | 否 | IP 黑名单配置。 | |
white_ip | string | 否 | IP 白名单配置。 | |
cors | object | 否 | 跨域配置。 | |
cors.enable | integer enum | 否 | 是否启用跨域。 | 0 | 1 |
hotlink | object | 否 | 防盗链配置。 | |
hotlink.enable | integer enum | 否 | 是否启用防盗链。 | 0 | 1 |
url_rewrite | string | 否 | URL 重写配置。 | |
acme_proxy_to_orgin | integer enum | 否 | 是否将 `/.well-known/acme-challenge/` 请求回源:1 开启,0 关闭。 | 1 |
backend_host | string | 否 | 回源 Host。允许 `$host`、`$host:$server_port`,或合法域名/IP及可选端口。 | $host |
block_proxy | integer enum | 否 | 是否拦截被识别为代理的客户端。 | 1 |
block_region | string | 否 | 按两字母小写国家/地区代码拦截,多个值以逗号分隔;空字符串表示关闭。 | us,jp |
block_time | integer | 否 | 自动黑名单持续时间,单位秒;非空时必须大于 600 且不超过 604800。 | 3600 |
cc_default_rule | integer | 否 | 默认 CC 规则 ID;规则必须存在且启用,使用其他用户的非内置规则需要管理员权限。 | 10002 |
cc_switch | object | 否 | CC 规则自动切换配置;空对象表示关闭。 | {"rule":10002,"switch":100,"enable":1} |
cc_switch.rule | integer | 是 | 切换后的 CC 规则 ID。 | 10002 |
cc_switch.switch | integer | 是 | 触发切换的请求阈值。 | 100 |
cc_switch.enable | integer enum | 否 | 是否启用自动切换。 | 1 |
condition_backend | array | 否 | 按请求条件选择源站的规则列表。 | [{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}] |
condition_backend | array<object> | 否 | 按请求条件选择源站的规则列表。 | [{"matcher":[{"item":"req_uri","op":"contain","value":"/api/"}],"backend":[{"addr":"198.51.100.10","weight":1,"state":"up"}]}] |
condition_backend[].matcher | array | 是 | 全部匹配条件。 | |
condition_backend[].matcher | array<object> | 否 | 全部匹配条件。 | |
condition_backend[].matcher[].item | string | 是 | 匹配项。 | req_uri |
condition_backend[].matcher[].op | string enum | 是 | 匹配操作符。 | contain |
condition_backend[].matcher[].value | string | 是 | 匹配值;服务端会去除空行和首尾空白。 | /api/ |
condition_backend[].backend | array | 是 | 命中后使用的源站列表。 | |
condition_backend[].backend | array<object> | 否 | 命中后使用的源站列表。 | |
condition_backend[].backend[].addr | string | 是 | 源站 IPv4、IPv6 或域名。 | 198.51.100.10 |
condition_backend[].backend[].weight | integer | 否 | 源站权重。 | 1 |
condition_backend[].backend[].state | string enum | 否 | 源站状态。 | up |
cookie_domain | string | 否 | Cookie Domain;允许空字符串,非空时必须是合法域名。 | example.invalid |
dns_api | integer | 否 | DNS API 凭据 ID;必须属于目标用户。传 null 表示不绑定。 | 8 |
enable_ipv6 | integer enum | 否 | 是否启用 IPv6 CNAME;仅按网站生成 CNAME 且系统存在 IPv6 节点时可用。 | 1 |
extra_cc_rule | array | 否 | 网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。 | [{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}] |
extra_cc_rule | array<object> | 否 | 网站自定义 CC 规则列表。规则结构随 matcher/filter 类型变化,服务端会逐项校验。 | [{"matcher":{"req_uri":{"operator":"contain","value":"/api/"}},"filter":{"type":"req_rate","within_second":10,"max_req":60}}] |
is_default_server | integer enum | 否 | 管理员专用。是否作为线路范围内的默认站点;同一节点的监听端口不能与其它默认站点冲突。 | 1 |
l2_config_id | integer | 否 | 管理员专用。L2 配置 ID;必须存在、与网站区域一致并已绑定 L2 节点。 | 9 |
l2_state | string enum | 否 | 管理员专用。L2 模式。 | inherit |
log_req_body | integer enum | 否 | 管理员专用。是否记录请求体。 | 1 |
log_req_body_max_size | integer | 否 | 管理员专用。记录请求体的最大 KiB;不能超过 2048,也不能超过全局 client_body_buffer_size。 | 16 |
log_req_header | integer enum | 否 | 管理员专用。是否记录请求头。 | 1 |
log_resp_header | integer enum | 否 | 管理员专用。是否记录响应头。 | 1 |
page_403 | string | 否 | 自定义 403 错误页 HTML;空字符串使用默认页面。 | <h1>Forbidden</h1> |
page_404 | string | 否 | 自定义 404 错误页 HTML;空字符串使用默认页面。 | <h1>Not Found</h1> |
page_500 | string | 否 | 自定义 500 错误页 HTML;空字符串使用默认页面。 | <h1>Server Error</h1> |
page_502 | string | 否 | 自定义 502 错误页 HTML;空字符串使用默认页面。 | <h1>Bad Gateway</h1> |
page_504 | string | 否 | 自定义 504 错误页 HTML;空字符串使用默认页面。 | <h1>Gateway Timeout</h1> |
post_size_limit | string | 否 | POST 请求体大小限制。可使用纯数字或 b/k/m/g 单位,大小写均可;空字符串表示采用默认配置。 | 10m |
proxy_http_version | string enum | 否 | 回源 HTTP 协议版本。 | 1.1 |
proxy_ssl_protocols | string | 否 | 允许的回源 TLS/SSL 协议,多个值使用空格分隔。 | TLSv1.2 TLSv1.3 |
range | integer enum | 否 | 是否启用分段回源。 | 1 |
recv_real_time | integer enum | 否 | 是否实时向客户端返回上游响应数据。 | 1 |
req_header | array | 否 | 添加或覆盖的回源请求头。 | [{"name":"X-Origin","value":"cdnfly"}] |
req_header | array<object> | 否 | 添加或覆盖的回源请求头。 | [{"name":"X-Origin","value":"cdnfly"}] |
req_header[].name | string | 是 | 请求头名称,必须以英文字母开头。 | X-Example |
req_header[].value | string | 是 | 请求头值,去除首尾空白后不能为空。 | example-value |
resp_header | array | 否 | 添加或覆盖的客户端响应头。 | [{"name":"X-Cache","value":"cdnfly"}] |
resp_header | array<object> | 否 | 添加或覆盖的客户端响应头。 | [{"name":"X-Cache","value":"cdnfly"}] |
resp_header[].name | string | 是 | 请求头名称,必须以英文字母开头。 | X-Example |
resp_header[].value | string | 是 | 请求头值,去除首尾空白后不能为空。 | example-value |
send_real_time | integer enum | 否 | 是否实时向上游发送客户端请求数据。 | 1 |
spider_allow | string enum | 否 | 搜索引擎爬虫访问策略;空字符串表示不单独设置。 | allow |
spider_to_sip | string | 否 | 搜索引擎专用回源 IP;空字符串表示关闭。仅按网站生成 CNAME 且 DNS 服务支持对应线路时可用。 | 198.51.100.20 |
uid | integer | 否 | 管理员专用。创建时指定网站所属用户;更新转移网站时与 new_uid 配合,作为目标套餐归属校验用户。 | 12 |
ups_keepalive | integer enum | 否 | 是否启用上游 Keepalive。 | 1 |
ups_keepalive_conn | integer | 否 | 每个 worker 保留的上游 Keepalive 连接数。 | 16 |
ups_keepalive_timeout | integer | 否 | 上游 Keepalive 空闲超时秒数。 | 60 |
white_time | integer | 否 | 自动白名单持续时间,单位秒;非空时不超过 604800。 | 3600 |
请求已被处理。成功时 `code` 为 0、`msg` 为“更新网站成功”、`data` 为 null;字段校验、网站不存在或权限不足时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 更新网站成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
网站分组
GET /v1/site-groups
分页查询网站组,按网站组 ID 倒序返回。普通用户仅查询自己的网站组;管理员可查询全部,或通过 `uid` 查询指定用户的网站组。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer | 否 | 页码,必须为数字;默认 1。 | 1 |
limit | query | integer | 否 | 每页条数,必须为数字;默认 10。传 0 时不分页。 | 10 |
uid | query | integer | 否 | 仅管理员有效:按网站组所属用户 ID 精确筛选。普通用户传入后仍只返回自己的记录。 | 12 |
查询成功时不含 `msg` 字段;参数或认证错误仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.count | integer | 是 | 筛选后的网站组总数,未受分页影响。 | 1 |
oneOf#1.data | array | 是 | 当前页网站组记录。 | |
oneOf#1.data | array<object> | 否 | 当前页网站组记录。 | |
oneOf#1.data[].id | integer | 是 | 网站组 ID。 | |
oneOf#1.data[].uid | integer | 是 | 网站组所属用户 ID。 | |
oneOf#1.data[].name | string | 是 | 网站组名称。 | |
oneOf#1.data[].des | string | 是 | 网站组备注。 | |
oneOf#1.data[].username | string | 是 | 所属用户的用户名,由用户表关联得到。 | |
oneOf#2.code | string enum | 是 | 页码/分页条数格式错误或未登录时的业务错误码。 | site_group-4 | site_group-5 | login_required |
oneOf#2.msg | string | 是 | 错误原因。 | page参数格式不正确 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
POST /v1/site-groups
创建网站组。默认归属当前登录用户,并先按当前用户的网站关联资源配额检查网站组数量;管理员可通过 `uid` 指定网站组归属用户。网站组名称在同一归属用户下必须唯一。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 是 | 网站组名称,不能为空;服务端会进行 XSS 过滤,且在归属用户下必须唯一。 | 生产网站 |
des | string | 否 | 网站组备注;服务端会进行 XSS 过滤,未传时保存为空字符串。 | 主要业务站点 |
uid | integer | 否 | 仅管理员可传。创建后的网站组归属用户 ID;未传时使用当前登录用户 ID。 | 12 |
网站组创建成功,`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.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 网站组添加成功 |
oneOf#1.data | integer | 是 | 新创建网站组的自增 ID。 | 21 |
oneOf#2.code | string | 是 | 业务错误码。 | site_group-8 |
oneOf#2.msg | string | 是 | 错误原因。 | 当前添加的网站组已超限 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
DELETE /v1/site-groups/{group_id}
删除一个或多个网站组。路径参数支持英文逗号分隔多个网站组 ID。当前用户可删除自己的网站组;删除其他用户的网站组需要管理员权限。每个目标网站组必须不存在关联网站,任一检查失败都会回滚本次批量删除。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
group_id | path | string | 是 | 一个网站组 ID,或以英文逗号分隔的多个网站组 ID。 | 21,22 |
网站组删除成功。 未登录、维护模式限制、网站组不存在、删除他人网站组权限不足或网站组仍关联网站时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`site_group-1`、`site_group-2` 或 `site_group-15`。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 网站组删除成功 |
oneOf#1.data | string | 是 | 该操作未返回已删除的网站组数据。 | |
oneOf#2.code | string | 是 | 业务错误码。 | site_group-2 |
oneOf#2.msg | string | 是 | 错误原因。 | 当前网站组已有网站,请先移除再操作 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
GET /v1/site-groups/{group_id}
获取当前登录用户的一条网站组。服务端以网站组 ID 和当前登录用户 ID 联合查询;即使管理员登录,也不能通过此详情路径读取其他用户的网站组。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
group_id | path | integer | 是 | 网站组 ID。 | 21 |
成功、未登录和网站组不存在/无权访问均返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 成功时为空字符串。 | |
oneOf#1.data | object | 是 | 网站组记录。 | |
oneOf#1.data.id | integer | 是 | 网站组 ID。 | |
oneOf#1.data.uid | integer | 是 | 网站组所属用户 ID。 | |
oneOf#1.data.name | string | 是 | 网站组名称。 | |
oneOf#1.data.des | string | 是 | 网站组备注。 | |
oneOf#2.code | string enum | 是 | 网站组不存在、无权访问或未登录时的业务错误码。 | site_group-3 | login_required |
oneOf#2.msg | string | 是 | 错误原因。 | 网站组不存在 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
PUT /v1/site-groups/{group_id}
更新指定网站组。路径中的网站组 ID 会覆盖请求体 ID;未提供的字段保持原值,至少应有一个字段发生变化。网站组不属于当前用户时需要管理员权限。注意:请求体 `uid` 仅供管理员进行名称唯一性校验,不会修改网站组的实际归属用户。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
group_id | path | integer | 是 | 要更新的网站组 ID。 | 21 |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 否 | 网站组名称;传入时不能为空、经 XSS 过滤,并必须在用于校验的归属用户下唯一。 | 生产网站(新版) |
des | string | 否 | 网站组备注;服务端会进行 XSS 过滤,空字符串可清空。 | 主要业务站点 |
uid | integer | 否 | 仅管理员可传。该值只参与 `name` 的唯一性校验,不会写入网站组,也不会改变其实际归属用户。 | 12 |
网站组更新成功。 未登录、维护模式限制、网站组不存在、跨用户更新权限不足、名称校验失败或没有变更时仍返回 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.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 更新网站组成功 |
oneOf#1.data | string | 是 | 该操作未返回更新后的网站组对象。 | |
oneOf#2.code | string | 是 | 业务错误码。 | site_group-14 |
oneOf#2.msg | string | 是 | 错误原因。 | 数据未更改 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
域名检查和域名解析信息。
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 返回。请求格式正确时返回每个输入键对应的 CNAME 匹配布尔值;请求体不是对象、系统维护或认证失效时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,CNAME 检查完成时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 检查成功时固定为空字符串。 | |
oneOf#1.data | object | 是 | 以请求键为属性名的检查结果;true 表示 DNS CNAME 直接或经一层别名链匹配,false 表示不匹配或 DNS 查询失败。 | |
oneOf#2.code | string enum | 是 | 业务错误码:cname_check-1 表示请求体不是字典对象,maintain 表示当前禁止写操作,login_required 表示认证无效。 | cname_check-1 | maintain | login_required |
oneOf#2.msg | string | 是 | 与业务错误码对应的中文请求格式、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/domains
分页查询网站绑定的域名及其 CNAME、DNS API 和同步任务状态,按域名记录 ID 倒序返回。普通用户只可查询自己的域名,管理员可用 uid 查询指定用户。domain 使用包含匹配;limit=0 时返回全部匹配记录。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,默认 1。服务端仅校验其为数字;分页偏移按 (page - 1) × limit 计算。 | |
limit | query | integer(int32) | 否 | 每页记录数,默认 10;传 0 时取消 SQL limit。 | |
uid | query | integer(int64) | 否 | 仅管理员可用:筛选网站所属用户 ID。普通用户提供该参数不会改变查询范围。 | |
domain | query | string | 否 | 按域名进行包含匹配,不是精确匹配。 | |
site_id | query | integer(int64) | 否 | 精确筛选所属网站 ID。 | |
dnsapi_state | query | string | 否 | DNS API 设置状态:set 仅返回已设置 s.dns_api 的网站域名,not_set 仅返回未设置的。其他值不会增加筛选条件。 | |
task_state | query | string | 否 | 精确筛选关联域名 DNS 同步任务的 state 值。 | |
业务结果使用 HTTP 200 返回。成功响应含 code、count、data,不含 msg 字段;分页参数或认证失败时返回业务错误封装。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 当前权限和筛选条件下的域名记录总数。 | |
oneOf#1.data | array | 是 | 当前页域名记录,按 domain.id 倒序排列。 | |
oneOf#1.data | array<object> | 否 | 当前页域名记录,按 domain.id 倒序排列。 | |
oneOf#1.data[].username | string | 是 | 网站所属用户登录名。 | |
oneOf#1.data[].uid | integer(int64) | 是 | 网站所属用户 ID。 | |
oneOf#1.data[].id | integer(int64) | 是 | 域名记录 ID。 | |
oneOf#1.data[].site_id | integer(int64) | 是 | 所属网站 ID。 | |
oneOf#1.data[].domain | string | 是 | 网站绑定的域名。 | |
oneOf#1.data[].cname | string | 是 | 根据网站 cname_mode 及其 CNAME 域名配置计算出的完整 CNAME 目标。 | |
oneOf#1.data[].dns_api | integer(int64) | 是 | 网站关联的 DNS API 凭据 ID;null 表示尚未设置。 | |
oneOf#1.data[].state | string | 是 | 关联域名 DNS 同步任务状态;无任务时为 null。 | |
oneOf#1.data[].ret | string | 是 | 关联域名 DNS 同步任务返回内容;无任务时为 null。 | |
oneOf#2.code | string enum | 是 | 分页参数错误或认证失效的业务错误码。 | domain-2 | domain-3 | login_required |
oneOf#2.msg | string | 是 | 分页参数或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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}] |
[].id | oneOf | 是 | 要同步的 domain 记录 ID。 | |
[].id(oneOf#1) | integer(int64) | 否 | | |
[].id(oneOf#2) | string | 否 | | |
[].uid | integer(int64) | 否 | 可选域名所属用户 ID。仅管理员可提交;用于代管指定用户的域名。 | |
业务结果使用 HTTP 200 返回。成功时表示所有请求项的同步任务已发送,data 为 null;请求体格式、域名 ID/归属、DNS API 配置、权限或认证失败时返回业务错误码,并回滚本次批量操作。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 全部域名同步任务发送成功提示。 | 任务发送成功 |
oneOf#1.data | object | 是 | 成功时固定为 null。 | |
oneOf#2.code | string enum | 是 | 请求体格式、域名 ID/归属、DNS API 配置、管理员权限或认证失败的业务错误码。 | domain-1 | domain-4 | domain-5 | domain-6 | domain-7 | domain-8 | domain-9 | login_required |
oneOf#2.msg | string | 是 | 批量同步任务创建失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
TLS 证书管理。
GET /v1/certs
按当前身份查询证书列表,并可组合分页、域名、所属用户、证书 ID、名称、备注、类型、DNS API、到期天数、启用状态、同步状态、签发状态和可用性条件。普通用户始终只返回自己的证书,即使传入 `uid` 也不会扩大数据范围;管理员可查看全部用户并用 `uid` 精确筛选。结果按证书 ID 倒序排列,`limit=0` 返回全部匹配记录。列表只返回管理和任务状态摘要,不返回证书 PEM 正文或私钥。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,从 1 开始;仅含十进制数字,省略时为 1。`limit=0` 时仍会校验该值,但不参与截取结果。 | |
limit | query | integer(int32) | 否 | 每页数量,仅含十进制数字;省略时为 10,传 0 时取消分页并返回全部匹配记录。 | |
domain | query | string | 否 | 域名关键字,对证书的空格分隔域名文本执行包含匹配。 | |
domains | query | string | 否 | 精确匹配多个证书域名,一行一个域名;每项必须是合法域名或至少三级的通配符域名。服务端去除普通空格后按换行等剩余空白拆分,并匹配证书域名列表中的完整项。 | |
uid | query | integer(int64) | 否 | 证书所属用户 ID。管理员传入时按该用户精确筛选;普通用户传入时会被忽略,结果仍固定为当前用户的数据。 | |
id | query | integer(int64) | 否 | 证书 ID,精确匹配。 | |
name | query | string | 否 | 证书名称关键字,执行包含匹配。 | |
des | query | string | 否 | 证书备注关键字,执行包含匹配。 | |
type | query | string | 否 | 证书来源类型,精确匹配:`custom` 为用户上传,`lets` 为 Let's Encrypt,`zerossl` 为 ZeroSSL,`buypass` 为 BuyPass。 | |
dnsapi | query | integer(int64) | 否 | 签发证书所使用的 DNS API 配置 ID,精确匹配。 | |
expire | query | integer(int32) | 否 | 到期阈值天数,返回到期时间早于“当前时间加该天数”的证书;0 表示已经到期,也接受负整数以查询更早到期的记录。 | |
enable | query | integer | 否 | 证书启用状态:1 表示启用,0 表示禁用。 | |
sync_state | query | string | 否 | 证书同步任务状态。`done` 同时匹配同步任务已完成和没有同步任务的证书;其他值仅匹配对应任务状态。 | |
issue_state | query | string | 否 | 自动证书签发任务状态。`failed` 同时匹配已停用的签发任务和状态为 failed 的任务;其他值要求任务仍启用且状态精确匹配。 | |
valid | query | string | 否 | 可用性筛选开关;传任意非空值都会启用。启用后只返回证书已启用,且没有签发任务或签发任务状态为 done 的记录;该条件不检查同步任务状态,建议传 1。 | |
业务结果通过 HTTP 200 返回。查询成功时返回匹配总数和当前页证书摘要;页码、每页数量或精确域名列表格式错误,以及认证失效时返回字符串业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,列表查询成功时固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 应用全部筛选条件后的记录总数,不受当前页和每页数量限制。 | |
oneOf#1.data | array | 是 | 按证书 ID 倒序排列的当前页证书摘要;`limit=0` 时包含全部匹配记录。 | |
oneOf#1.data | array<object> | 否 | 按证书 ID 倒序排列的当前页证书摘要;`limit=0` 时包含全部匹配记录。 | |
oneOf#1.data[].id | integer(int64) | 是 | 证书唯一 ID。 | |
oneOf#1.data[].name | string | 是 | 用于识别该证书记录的显示名称。 | |
oneOf#1.data[].des | string | 是 | 证书备注,可为空字符串。 | |
oneOf#1.data[].dnsapi | integer(int64) | 是 | 自动签发所使用的 DNS API 配置 ID;未指定时为 null。 | |
oneOf#1.data[].auto_renew | integer enum | 是 | 是否自动续签:1 表示启用,0 表示关闭;主要用于自动签发证书。 | 0 | 1 |
oneOf#1.data[].type | string enum | 是 | 证书来源类型,用于区分用户上传和不同自动签发机构。 | custom | lets | zerossl | buypass |
oneOf#1.data[].domain | string | 是 | 证书覆盖的域名,多个域名使用空格分隔;尚未取得域名信息时可能为 null。 | |
oneOf#1.data[].start_time | string | 是 | 数据库返回的证书生效时间;未签发或未解析出时间时为 null。非空值由 JSON 序列化器输出为 HTTP 日期字符串。 | |
oneOf#1.data[].expire_time2 | string | 是 | 证书到期时间,格式为 `YYYY-MM-DD HH:mm:ss`;未签发或未解析出时间时为 null。 | |
oneOf#1.data[].create_at2 | string | 是 | 证书记录创建时间,格式为 `YYYY-MM-DD HH:mm:ss`;历史记录没有时间时为 null。 | |
oneOf#1.data[].update_at | string | 是 | 数据库返回的最后更新时间;历史记录没有时间时为 null。非空值由 JSON 序列化器输出为 HTTP 日期字符串。 | |
oneOf#1.data[].enable | integer enum | 是 | 证书启用状态:1 表示启用,0 表示禁用。 | 0 | 1 |
oneOf#1.data[].issue_state | string enum | 是 | 签发任务状态;自定义证书或没有关联签发任务时为 null。 | pending | process | failed | done | |
oneOf#1.data[].sync_state | string enum | 是 | 最近一次证书同步任务状态;没有关联同步任务时为 null。 | pending | process | failed | done | |
oneOf#1.data[].uid | integer(int64) | 是 | 证书所属用户 ID。 | |
oneOf#1.data[].username | string | 是 | 证书所属用户名;关联用户名称不可用时为 null。 | |
oneOf#1.data[].task_enable | integer enum | 是 | 签发任务是否仍启用:1 表示启用,0 表示已停用;没有签发任务时为 null。 | 0 | 1 | |
oneOf#1.data[].task_ret | string | 是 | 签发任务返回信息或失败原因;任务没有返回内容时为 null。 | |
oneOf#1.data[].retry_at2 | string | 是 | 签发任务下次重试时间,格式为 `YYYY-MM-DD HH:mm:ss`;没有计划重试时为 null。 | |
oneOf#2.code | string enum | 是 | 业务错误码:`cert-34` 表示 page 不是数字,`cert-35` 表示 limit 不是数字,`cert-44` 表示 `domains` 中存在无效域名,`login_required` 表示认证无效。 | cert-34 | cert-35 | cert-44 | login_required |
oneOf#2.msg | string | 是 | 与业务错误码对应的中文分页参数、域名格式或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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.uid | integer(int64) | 否 | 证书所属用户 ID;省略时使用当前登录用户,仅管理员可指定,否则返回 `cert-48`。 | |
oneOf#1.name | string | 是 | 证书显示名称;服务端会过滤可执行的 HTML,处理后不得为空,同一所属用户下不可重复,并只保存处理后前 200 个字符。创建时必填。 | |
oneOf#1.des | string | 否 | 证书备注;服务端会过滤可执行的 HTML,省略时保存为空字符串。 | |
oneOf#1.type | string enum | 否 | 证书类型:`custom` 为上传证书,`lets` 为 Let's Encrypt,`zerossl` 为 ZeroSSL,`buypass` 为 BuyPass。省略时读取全局或用户证书默认配置。 | custom | lets | zerossl | buypass |
oneOf#1.dnsapi | oneOf | 否 | 自动签发所使用的 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.domain | string | 否 | 自动签发证书的域名,类型为 `lets`、`zerossl` 或 `buypass` 时必填并会转为小写;通配符域名还必须配合 DNS API。`custom` 类型不会采用该字段,而是从证书的 SAN/CN 中解析域名。 | |
oneOf#1.key | string(password) | 否 | 上传证书的私钥 PEM;`custom` 类型必填,服务端会去除首尾空白、校验末尾 PEM 分隔符并验证与证书匹配。其他类型通常省略。示例不得填入真实私钥。 | |
oneOf#1.cert | string | 否 | 上传证书链 PEM;`custom` 类型必填,服务端会解析每个证书并验证有效性。其他类型通常省略。示例不得填入真实证书内容。 | |
oneOf#2 | array<object> | 否 | 批量证书创建对象数组;数组可以为空,空数组会提交一个不含证书的空批次并返回空数据字符串。数组中任一对象校验失败时整批回滚。 | |
oneOf#2[].uid | integer(int64) | 否 | 证书所属用户 ID;省略时使用当前登录用户,仅管理员可指定,否则返回 `cert-48`。 | |
oneOf#2[].name | string | 是 | 证书显示名称;服务端会过滤可执行的 HTML,处理后不得为空,同一所属用户下不可重复,并只保存处理后前 200 个字符。创建时必填。 | |
oneOf#2[].des | string | 否 | 证书备注;服务端会过滤可执行的 HTML,省略时保存为空字符串。 | |
oneOf#2[].type | string enum | 否 | 证书类型:`custom` 为上传证书,`lets` 为 Let's Encrypt,`zerossl` 为 ZeroSSL,`buypass` 为 BuyPass。省略时读取全局或用户证书默认配置。 | custom | lets | zerossl | buypass |
oneOf#2[].dnsapi | oneOf | 否 | 自动签发所使用的 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[].domain | string | 否 | 自动签发证书的域名,类型为 `lets`、`zerossl` 或 `buypass` 时必填并会转为小写;通配符域名还必须配合 DNS API。`custom` 类型不会采用该字段,而是从证书的 SAN/CN 中解析域名。 | |
oneOf#2[].key | string(password) | 否 | 上传证书的私钥 PEM;`custom` 类型必填,服务端会去除首尾空白、校验末尾 PEM 分隔符并验证与证书匹配。其他类型通常省略。示例不得填入真实私钥。 | |
oneOf#2[].cert | string | 否 | 上传证书链 PEM;`custom` 类型必填,服务端会解析每个证书并验证有效性。其他类型通常省略。示例不得填入真实证书内容。 | |
业务结果通过 HTTP 200 返回。全部证书校验并提交后返回创建结果;配额、套餐、名称、类型、DNS API、域名、PEM、管理员归属、证书有效性、参数状态、兼容性更新字段、系统维护或认证校验失败时返回字符串业务错误码,整个批次事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,所有证书创建并提交后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 证书创建批次成功后返回的确认消息。 | 证书添加成功 |
oneOf#1.data | string | 是 | 正常创建时为新证书 ID 的英文逗号分隔字符串;空数组时为空字符串。若兼容性地传入 `id` 触发更新逻辑,内容可能是更新差异 JSON 字符串。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文配额、套餐、字段、证书材料、权限、任务状态、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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.id | oneOf | 是 | 要更新的证书 ID;必须是数字或数字字符串,记录必须存在,跨用户更新需要管理员身份。 | |
oneOf#1.id(oneOf#1) | integer | 否 | | |
oneOf#1.id(oneOf#2) | string | 否 | | |
oneOf#1.uid | integer(int64) | 否 | 兼容性所属用户上下文字段;仅管理员可传,用于校验目标证书所属用户,不会转移证书。 | |
oneOf#1.name | string | 否 | 新的证书名称;服务端过滤 HTML、校验同一用户下唯一,并保存处理后前 200 个字符,省略时保持原值。 | |
oneOf#1.des | string | 否 | 新的证书备注;服务端过滤 HTML,可传空字符串清空备注,省略时保持原值。 | |
oneOf#1.type | string enum | 否 | 新的证书类型;由 custom 切换到自动类型会创建签发任务,由自动类型切换为 custom 会结束旧签发任务,省略时保持原类型。 | custom | lets | zerossl | buypass |
oneOf#1.dnsapi | oneOf | 否 | 新的 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.domain | string | 否 | 自动证书的新域名;自动类型下转为小写并触发重新签发,通配符必须指定 DNS API,省略时保持原值。custom 类型会从上传证书 SAN/CN 重新解析。 | |
oneOf#1.key | string(password) | 否 | 新的自上传证书私钥 PEM;仅 custom 类型校验末尾格式和证书匹配,内容变化且证书在使用时创建同步任务。示例不得使用真实私钥。 | |
oneOf#1.cert | string | 否 | 新的自上传证书链 PEM;仅 custom 类型解析并校验证书,内容变化且证书在使用时可能创建同步任务。示例不得使用真实证书。 | |
oneOf#1.force_disable | integer enum | 否 | 禁用正在被网站使用的证书时的强制标志:0 返回 cert-32,1 清空关联网站 HTTPS 配置并创建网站同步任务。 | 0 | 1 |
oneOf#1.auto_renew | integer enum | 否 | 自动续签状态:1 启用,0 关闭;省略时保持原值。 | 0 | 1 |
oneOf#1.enable | integer enum | 否 | 证书启用状态:1 启用,0 禁用;禁用会创建证书删除任务,省略时保持原值。 | 0 | 1 |
oneOf#1.reissue | oneOf | 否 | 重新签发开关;字段存在即触发重新签发,目标必须是 lets、zerossl 或 buypass 类型。 | |
oneOf#1.reissue(oneOf#1) | boolean | 否 | | |
oneOf#1.reissue(oneOf#2) | integer | 否 | | |
oneOf#2 | array<object> | 否 | 批量证书更新对象数组;每项都必须包含 id,任一项失败时整批回滚。 | |
oneOf#2[].id | oneOf | 是 | 要更新的证书 ID;必须是数字或数字字符串,记录必须存在,跨用户更新需要管理员身份。 | |
oneOf#2[].id(oneOf#1) | integer | 否 | | |
oneOf#2[].id(oneOf#2) | string | 否 | | |
oneOf#2[].uid | integer(int64) | 否 | 兼容性所属用户上下文字段;仅管理员可传,用于校验目标证书所属用户,不会转移证书。 | |
oneOf#2[].name | string | 否 | 新的证书名称;服务端过滤 HTML、校验同一用户下唯一,并保存处理后前 200 个字符,省略时保持原值。 | |
oneOf#2[].des | string | 否 | 新的证书备注;服务端过滤 HTML,可传空字符串清空备注,省略时保持原值。 | |
oneOf#2[].type | string enum | 否 | 新的证书类型;由 custom 切换到自动类型会创建签发任务,由自动类型切换为 custom 会结束旧签发任务,省略时保持原类型。 | custom | lets | zerossl | buypass |
oneOf#2[].dnsapi | oneOf | 否 | 新的 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[].domain | string | 否 | 自动证书的新域名;自动类型下转为小写并触发重新签发,通配符必须指定 DNS API,省略时保持原值。custom 类型会从上传证书 SAN/CN 重新解析。 | |
oneOf#2[].key | string(password) | 否 | 新的自上传证书私钥 PEM;仅 custom 类型校验末尾格式和证书匹配,内容变化且证书在使用时创建同步任务。示例不得使用真实私钥。 | |
oneOf#2[].cert | string | 否 | 新的自上传证书链 PEM;仅 custom 类型解析并校验证书,内容变化且证书在使用时可能创建同步任务。示例不得使用真实证书。 | |
oneOf#2[].force_disable | integer enum | 否 | 禁用正在被网站使用的证书时的强制标志:0 返回 cert-32,1 清空关联网站 HTTPS 配置并创建网站同步任务。 | 0 | 1 |
oneOf#2[].auto_renew | integer enum | 否 | 自动续签状态:1 启用,0 关闭;省略时保持原值。 | 0 | 1 |
oneOf#2[].enable | integer enum | 否 | 证书启用状态:1 启用,0 禁用;禁用会创建证书删除任务,省略时保持原值。 | 0 | 1 |
oneOf#2[].reissue | oneOf | 否 | 重新签发开关;字段存在即触发重新签发,目标必须是 lets、zerossl 或 buypass 类型。 | |
oneOf#2[].reissue(oneOf#1) | boolean | 否 | | |
oneOf#2[].reissue(oneOf#2) | integer | 否 | |
业务结果通过 HTTP 200 返回。全部证书更新并提交后返回确认消息;请求体格式、目标证书、名称、类型、DNS API、域名、PEM、权限、启用/续签、重新签发、网站引用、系统维护或认证校验失败时返回字符串业务错误码,整个批次事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,所有证书更新并提交后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 证书更新批次成功后返回的确认消息。 | 更新证书成功 |
oneOf#1.data | string enum | 是 | 更新成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文请求格式、目标记录、字段、证书材料、网站引用、权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
DELETE /v1/certs/{cert_id}
删除路径中指定的一个或多个证书,多个 ID 使用英文逗号分隔并在同一事务中处理。普通用户只能删除自己的证书,管理员可删除其他用户证书。每个证书必须已禁用,且关联任务为空或状态为 done;任一目标失败时整批回滚。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
cert_id | path | string | 是 | 要删除的证书 ID;多个 ID 按 10021,10022 形式用英文逗号连接,每段必须为十进制数字。 | |
业务结果通过 HTTP 200 返回。全部目标删除并提交后返回确认消息;ID、记录、权限、启用状态、任务状态、维护或认证校验失败返回业务错误码,事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 删除成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 证书删除批次成功消息。 | 证书删除成功 |
oneOf#1.data | string enum | 是 | 删除成功时固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文 ID、记录、状态、权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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_id | path | integer(int64) | 是 | 要读取的证书 ID;路由只接受十进制整数。 | |
action | query | string | 否 | 下载动作开关;传 download 返回 gzip 证书包,省略或传其他值返回 JSON 详情。 | |
业务结果通过 HTTP 200 返回;普通请求返回 JSON 详情,action=download 返回二进制 gzip 压缩包。记录不存在、读取其他用户证书且当前身份不是管理员或认证失效时,JSON 分支返回字符串业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,证书详情读取成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 详情读取成功时没有提示,JSON 序列化为 null。 | |
oneOf#1.data | object | 是 | 数据库证书详情记录,包含证书和私钥敏感字段。 | |
oneOf#1.data.id | integer(int64) | 是 | 证书唯一 ID。 | |
oneOf#1.data.uid | integer(int64) | 是 | 证书所属用户 ID。 | |
oneOf#1.data.name | string | 是 | 证书显示名称。 具体说明 | |
oneOf#1.data.des | string | 是 | 证书备注,可为空字符串。 | |
oneOf#1.data.type | string enum | 是 | 证书来源类型。 具体说明 | custom | lets | zerossl | buypass |
oneOf#1.data.domain | string | 是 | 证书覆盖的域名,多个域名以空格分隔;未解析时为 null。 | |
oneOf#1.data.dnsapi | integer(int64) | 是 | 自动签发使用的 DNS API ID;未指定时为 null。 | |
oneOf#1.data.cert | string | 是 | 证书链 PEM 原文;此字段包含敏感材料,示例不得使用真实证书。 | |
oneOf#1.data.key | string(password) | 是 | 证书私钥 PEM 原文;此字段是敏感凭据,示例不得使用真实私钥。 | |
oneOf#1.data.start_time | string | 是 | 证书生效时间,格式为 YYYY-MM-DD HH:mm:ss;未签发时为 null。 | |
oneOf#1.data.expire_time | string | 是 | 证书到期时间,格式为 YYYY-MM-DD HH:mm:ss;未签发时为 null。 | |
oneOf#1.data.auto_renew | integer enum | 是 | 自动续签状态:1 启用,0 关闭。 | 0 | 1 |
oneOf#1.data.create_at | string | 是 | 证书记录创建时间,格式为 YYYY-MM-DD HH:mm:ss。 | |
oneOf#1.data.update_at | string | 是 | 证书记录最后更新时间,格式为 YYYY-MM-DD HH:mm:ss。 | |
oneOf#1.data.enable | integer enum | 是 | 证书启用状态:1 启用,0 禁用。 | 0 | 1 |
oneOf#1.data.task_id | integer(int64) | 是 | 最近一次证书同步或删除任务 ID;没有任务时为 null。 | |
oneOf#1.data.issue_task_id | integer(int64) | 是 | 自动签发任务 ID;自上传证书没有签发任务时为 null。 | |
oneOf#1.data.version | integer(int64) | 是 | 证书配置版本号,每次更新递增。 | |
oneOf#2.code | string enum | 是 | 业务错误码:cert-33 表示证书不存在,cert-50 表示当前用户无权读取其他用户证书,login_required 表示认证无效。 | cert-33 | cert-50 | login_required |
oneOf#2.msg | string | 是 | 与业务错误码对应的中文记录不存在、权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
PUT /v1/certs/{cert_id}
按路径证书 ID 更新一条证书。请求体必须是 JSON 对象,路径 ID 会覆盖请求体中可能存在的 id;单条接口不接受数组。名称、备注、类型、DNS API、域名、证书材料、启用/续签和重新签发字段均可按需提供,未提供字段保持原值。普通用户只能更新自己的证书,管理员可更新其他用户证书;任一校验失败返回 HTTP 200 业务错误。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
cert_id | path | integer(int64) | 是 | 要更新的证书 ID;路由只接受十进制整数,并覆盖请求体中的 id。 | |
请求体必填。
Content-Type:application/json
指定证书的部分更新对象;路径 ID 为唯一目标。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
uid | integer(int64) | 否 | 兼容性所属用户上下文,仅管理员可传;不会转移证书。 | |
name | string | 否 | 新的证书名称;过滤 HTML、检查同用户唯一并保存前 200 个字符,省略时保持原值。 | |
des | string | 否 | 新的证书备注,可传空字符串清空,省略时保持原值。 | |
type | string enum | 否 | 新的证书类型;自动类型切换会建立签发任务,省略时保持原类型。 | custom | lets | zerossl | buypass |
dnsapi | oneOf | 否 | 新的 DNS API ID;非空时必须存在,null 清除,省略时保持原值。 | |
dnsapi(oneOf#1) | integer | 否 | | |
dnsapi(oneOf#2) | string | 否 | | |
dnsapi(oneOf#3) | string | 否 | | |
domain | string | 否 | 自动证书的新域名;自动类型下转小写并触发签发,通配符需 DNS API,custom 类型从 PEM SAN/CN 解析。 | |
key | string(password) | 否 | custom 类型的新私钥 PEM;校验格式和证书匹配,示例不得使用真实私钥。 | |
cert | string | 否 | custom 类型的新证书链 PEM;校验解析,示例不得使用真实证书。 | |
force_disable | integer enum | 否 | 禁用在用证书的强制标志;0 返回 cert-32,1 同时关闭关联网站 HTTPS 并同步。 | 0 | 1 |
auto_renew | integer enum | 否 | 自动续签状态,1 启用、0 关闭,省略时保持原值。 | 0 | 1 |
enable | integer enum | 否 | 证书启用状态,1 启用、0 禁用;禁用会创建证书删除任务。 | 0 | 1 |
reissue | oneOf | 否 | 字段存在即重新签发;目标必须是 lets、zerossl 或 buypass 自动证书。 | |
reissue(oneOf#1) | boolean | 否 | | |
reissue(oneOf#2) | integer | 否 | |
业务结果通过 HTTP 200 返回。更新成功返回确认消息;对象格式、证书记录、字段、证书材料、网站引用、权限、任务和认证校验失败返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 更新成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 证书更新成功消息。 | 更新证书成功 |
oneOf#1.data | string enum | 是 | 更新成功时固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文字段、权限、任务或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
DNS 服务商凭证管理。
GET /v1/dnsapis
分页查询 DNS 服务商凭据记录,按 ID 倒序返回。普通用户只能读取自己的记录并忽略 uid 筛选;管理员可用 uid 查询指定用户的记录。响应会直接返回数据库保存的 auth 文本,应避免在不可信环境展示或记录。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,默认 1。服务端仅校验其为数字;分页偏移按 (page - 1) × limit 计算。 | |
limit | query | integer(int32) | 否 | 每页记录数,默认 10;传 0 时取消 SQL limit 并返回全部记录。 | |
uid | query | integer(int64) | 否 | 仅管理员可用:筛选指定所属用户 ID。普通用户提供该参数不会改变查询范围。 | |
业务结果使用 HTTP 200 返回。成功响应含 code、count、data,不含 msg 字段;分页参数或认证失败时返回业务错误封装。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 当前权限与 uid 条件下的 DNS API 记录总数。 | |
oneOf#1.data | array | 是 | 当前页 DNS API 记录,按 id 倒序排列。 | |
oneOf#1.data | array<object> | 否 | 当前页 DNS API 记录,按 id 倒序排列。 | |
oneOf#1.data[].id | integer(int64) | 是 | DNS API 记录 ID。 | |
oneOf#1.data[].uid | integer(int64) | 是 | 凭据所属用户 ID。 | |
oneOf#1.data[].name | string | 是 | 用户定义的 DNS API 名称。 | |
oneOf#1.data[].des | string | 是 | 凭据备注。 | |
oneOf#1.data[].type | string | 是 | DNS 服务商类型,例如 CloudFlare、Aliyun 或 DNSPod.cn。 | |
oneOf#1.data[].username | string | 是 | 所属用户登录名;关联用户不存在时为 null。 | |
oneOf#1.data[].auth | string | 是 | 数据库保存的 DNS 服务商鉴权 JSON 文本,包含 API Token、密钥或账号等敏感信息。服务端实际会返回此字段;文档示例已脱敏。 | |
oneOf#2.code | string enum | 是 | 分页参数错误或认证失效的业务错误码。 | dnsapi-5 | dnsapi-6 | login_required |
oneOf#2.msg | string | 是 | 分页参数或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
POST /v1/dnsapis
创建用于证书 DNS 验证和网站 DNS 操作的服务商凭据。默认归属当前登录用户;管理员可通过 uid 为指定用户创建。每种服务商类型要求不同的 auth 键。服务端将 DNS.COM 列入可选类型但没有额外的 auth 键校验,仍需提供非空对象。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
uid | integer(int64) | 否 | 可选所属用户 ID。仅管理员可提交;省略时使用当前登录用户。 | |
name | string | 是 | 凭据名称。服务端会过滤 XSS;同一所属用户下不能重名。 | |
des | string | 否 | 可选备注。服务端会过滤 XSS;省略时保存为空字符串。 | |
type | string 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 |
auth | object | 是 | 服务商鉴权对象,字段值为凭据文本,必须脱敏保存和传输。所需键: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 仅要求非空对象。 | |
业务结果使用 HTTP 200 返回。成功时 data 为新 DNS API ID;配额、字段、服务商鉴权键、管理员权限或认证校验失败时返回字符串业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 创建成功提示。 | dnsapi添加成功 |
oneOf#1.data | integer(int64) | 是 | 新建 DNS API 记录 ID。 | |
oneOf#2.code | string | 是 | 业务错误码,包括配额/字段/鉴权键校验错误 dnsapi-9 至 dnsapi-38、管理员权限错误 dnsapi-36 及认证错误 login_required。 | |
oneOf#2.msg | string | 是 | 配额、字段、服务商鉴权键、权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
DELETE /v1/dnsapis/{api_id}
按路径中的 DNS API ID 删除凭据。支持以英文逗号传入多个 ID;普通用户只能删除自己的记录,管理员可删除其他用户记录。任一记录无效、被证书或网站引用、被设置为证书默认 DNS API 时均拒绝删除并回滚本次事务。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
api_id | path | string | 是 | 要删除的一个或多个 DNS API 记录 ID,多个 ID 使用英文逗号分隔。 | |
业务结果使用 HTTP 200 返回。成功时 data 为 null;ID 格式、记录、归属、引用关系、默认配置、权限或认证校验失败时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 删除成功提示。 | dnsapi删除成功 |
oneOf#1.data | object | 是 | 成功时固定为 null。 | |
oneOf#2.code | string enum | 是 | ID 格式/记录/引用/默认配置/管理员权限或认证失败的业务错误码。 | dnsapi-1 | dnsapi-2 | dnsapi-3 | dnsapi-32 | dnsapi-34 | dnsapi-35 | login_required |
oneOf#2.msg | string | 是 | 删除前校验失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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_id | path | integer(int64) | 是 | 要读取的 DNS API 记录 ID。 | |
业务结果使用 HTTP 200 返回。成功时返回 dnsapi 表完整记录;记录不存在、不归属当前用户或认证失效时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 详情读取成功时固定为空字符串。 | |
oneOf#1.data | object | 是 | dnsapi 表的完整凭据记录。 | |
oneOf#1.data.id | integer(int64) | 是 | DNS API 记录 ID。 | |
oneOf#1.data.uid | integer(int64) | 是 | 凭据所属用户 ID,固定为当前登录用户。 | |
oneOf#1.data.name | string | 是 | 用户定义的凭据名称。 | |
oneOf#1.data.des | string | 是 | 凭据备注。 | |
oneOf#1.data.type | string | 是 | DNS 服务商类型。 | |
oneOf#1.data.auth | string | 是 | 数据库保存的服务商鉴权 JSON 文本,含敏感 Token、密钥或账号信息。文档示例已脱敏。 | |
oneOf#2.code | string enum | 是 | 记录不存在/不归属当前用户或认证失效的业务错误码。 | dnsapi-4 | login_required |
oneOf#2.msg | string | 是 | 读取或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
PUT /v1/dnsapis/{api_id}
更新指定 DNS API 凭据的已提交字段;路径 api_id 会覆盖请求体中的 id。普通用户只能更新自己的记录,管理员可以更新任意记录;管理员可额外传 uid 进行归属校验。所有业务字段可选,未提交字段保持原值,且没有实际变更时接口仍成功返回。若提交 auth,服务端按当前或提交后的 type 校验所需服务商键。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
api_id | path | integer(int64) | 是 | 要更新的 DNS API 记录 ID。 | |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
uid | integer(int64) | 否 | 可选所属用户 ID。仅管理员可提交;更新时实际归属仍须与现有记录一致,否则要求管理员权限。 | |
name | string | 否 | 可选新凭据名称。服务端过滤 XSS;提供时不能为空且同一所属用户下不能重名。 | |
des | string | 否 | 可选新备注。服务端过滤 XSS;可传空字符串清空。 | |
type | string 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 |
auth | object | 否 | 可选新服务商鉴权对象。提交时按当前或新 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 仅要求非空对象。所有值均为敏感凭据。 | |
业务结果使用 HTTP 200 返回。成功时 data 为 null(包括没有实际字段变化时);记录、归属、字段、鉴权键、管理员权限或认证校验失败时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 更新成功提示。 | 更新dnsapi成功 |
oneOf#1.data | object | 是 | 成功时固定为 null。 | |
oneOf#2.code | string | 是 | 业务错误码,包括记录/归属/字段/鉴权键错误 dnsapi-7 至 dnsapi-38、管理员权限错误 dnsapi-36、dnsapi-37 及认证错误 login_required。 | |
oneOf#2.msg | string | 是 | 记录、归属、字段、鉴权键、权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
ACL 访问控制规则。
GET /v1/acls
分页查询当前身份可见的网站 ACL 规则集。普通用户始终只返回自己的 ACL;管理员默认可查看全部用户的数据,并可通过 `uid` 限定所属用户。可按 ACL ID、名称、启用状态和任务状态筛选,结果按 ACL ID 倒序排列。响应中的 `data` 字段是序列化后的 ACL 规则 JSON 字符串,调用方需要在使用规则内容前再次解析。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,从 1 开始;省略时为 1。`limit=0` 时该参数不影响返回范围。 | |
limit | query | integer(int32) | 否 | 每页返回的 ACL 数量,省略时为 10;传 0 表示不分页并返回全部匹配记录。 | |
enable | query | integer | 否 | 按启用状态精确筛选:1 表示已启用,0 表示已禁用。 | |
uid | query | integer(int64) | 否 | 按 ACL 所属用户 ID 精确筛选,仅管理员身份生效;普通用户传入该参数也只会返回自己的数据。 | |
id | query | integer(int64) | 否 | 按 ACL ID 精确筛选列表。 | |
name | query | string | 否 | 按 ACL 名称进行包含匹配。 | |
state | query | string | 否 | 按关联任务状态筛选。传 `done` 时同时包含任务已完成和未关联任务的 ACL;其它值按任务状态精确匹配。 | |
请求始终通过 HTTP 200 返回。成功时给出匹配总数和当前页 ACL 列表;页码或每页数量格式错误、登录态失效时,通过字符串 `code` 和 `msg` 返回业务错误。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,列表查询成功时固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 符合筛选条件的 ACL 总数,不受当前页 `limit` 限制。 | |
oneOf#1.data | array | 是 | 当前页的 ACL 记录,按 ACL ID 从大到小排列。 | |
oneOf#1.data | array<object> | 否 | 当前页的 ACL 记录,按 ACL ID 从大到小排列。 | |
oneOf#1.data[].id | integer(int64) | 是 | ACL 的唯一 ID。 | |
oneOf#1.data[].uid | integer(int64) | 是 | ACL 所属用户的 ID。 | |
oneOf#1.data[].name | string | 是 | ACL 名称,同一用户下不可重名。 | |
oneOf#1.data[].des | string | 是 | ACL 的备注说明,可为空字符串。 | |
oneOf#1.data[].default_action | string enum | 是 | 所有 ACL 规则均未匹配时执行的默认动作。 | reject | allow |
oneOf#1.data[].reject_code | string enum | 是 | 拒绝请求时使用的响应方式:403 表示直接拒绝,302 表示重定向。 | 403 | 302 |
oneOf#1.data[].redirect_url | string | 是 | `reject_code` 为 302 时使用的重定向地址,否则通常为空字符串。 | |
oneOf#1.data[].data | string | 是 | 序列化后的 ACL 规则 JSON 数组;每条规则包含动作、匹配条件,并可包含拒绝代码和跳转地址。 | |
oneOf#1.data[].create_at | string | 是 | ACL 的数据库创建时间;历史数据未记录时为 null。 | |
oneOf#1.data[].update_at | string | 是 | ACL 的数据库最后更新时间;历史数据未记录时为 null。 | |
oneOf#1.data[].enable | integer enum | 是 | ACL 启用状态:1 表示启用,0 表示禁用。 | 0 | 1 |
oneOf#1.data[].task_id | integer(int64) | 是 | 最近一次 ACL 同步或删除任务的 ID;没有关联任务时为 null。 | |
oneOf#1.data[].version | integer(int64) | 是 | ACL 配置版本号,每次更新时递增。 | |
oneOf#1.data[].state | string | 是 | 关联任务的当前状态;没有关联任务时为 null。 | |
oneOf#1.data[].create_at2 | string | 是 | 格式化为 `YYYY-MM-DD HH:mm:ss` 的创建时间,供界面展示。 | |
oneOf#1.data[].update_at2 | string | 是 | 格式化为 `YYYY-MM-DD HH:mm:ss` 的最后更新时间,供界面展示。 | |
oneOf#1.data[].username | string | 是 | ACL 所属用户的名称。 | |
oneOf#2.code | string | 是 | 业务错误码,例如 `acl-31` 表示 page 格式错误、`acl-32` 表示 limit 格式错误、`login_required` 表示登录态无效。 | |
oneOf#2.msg | string | 是 | 与业务错误码对应的中文错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 是 | ACL 名称;不能为空,且在所属用户的 ACL 中必须唯一。 | |
des | string | 否 | ACL 的备注说明;省略时保存为空字符串。 | |
default_action | string enum | 是 | 所有 ACL 规则均未匹配时执行的默认动作:`reject` 拒绝请求,`allow` 放行请求。 | reject | allow |
reject_code | string enum | 否 | 默认动作拒绝请求时的响应方式;403 表示直接拒绝,302 表示重定向。 | 403 | 302 |
redirect_url | string | 否 | `reject_code` 为 302 时必填的重定向地址;使用 403 时可省略。 | |
data | array | 是 | 按顺序执行的 ACL 规则数组;条目数不得超过系统配置的 `acl-max-limit`。 | |
data | array<object> | 否 | 按顺序执行的 ACL 规则数组;条目数不得超过系统配置的 `acl-max-limit`。 | |
data[].acl_action | string enum | 是 | 该条规则匹配后执行的动作:`reject` 拒绝请求,`allow` 放行请求。 | reject | allow |
data[].acl_code | string enum | 否 | 该条规则执行 `reject` 时使用的响应方式;省略时为 403。 | 403 | 302 |
data[].acl_url | string | 否 | 该条规则的 `acl_code` 为 302 时必填的重定向地址。 | |
data[].acl_matcher | array | 是 | 该条 ACL 规则的匹配条件;每个条件由匹配项、操作符和值组成。 | |
data[].acl_matcher | array<object> | 否 | 该条 ACL 规则的匹配条件;每个条件由匹配项、操作符和值组成。 | |
data[].acl_matcher[].item | string 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[].op | string enum | 是 | 匹配操作符;`ip_range` 和 `!ip_range` 用于判断 IP 是否属于指定 CIDR 范围。 | > | = | != | !contain | contain | prefix | suffix | regex | !regex | exists | !exists | ip_range | !ip_range |
data[].acl_matcher[].value | string | 否 | 参与匹配的值。服务端会移除空行并转为小写;IP 范围操作符使用空白分隔一个或多个 CIDR。 | |
enable | integer enum | 否 | 新 ACL 的启用状态:1 表示启用,0 表示禁用;省略时启用。 | 0 | 1 |
uid | integer(int64) | 否 | 新 ACL 的所属用户 ID,仅管理员可传;普通用户传入时返回管理员权限错误。 | |
请求始终通过 HTTP 200 返回。创建成功时返回新 ACL ID;配额、名称、默认动作、重定向配置或嵌套匹配规则不合法时,通过字符串 `code` 和 `msg` 返回具体业务错误。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,ACL 创建成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | ACL 创建成功时返回的确认消息。 | ACL添加成功 |
oneOf#1.data | integer(int64) | 是 | 新创建 ACL 的唯一 ID。 | |
oneOf#2.code | string | 是 | 业务错误码。常见值包括配额超限 `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.msg | string | 是 | 与业务错误码对应的中文校验失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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 数组;所有元素在同一个数据库事务中处理。 | |
[].id | integer(int64) | 是 | 要更新的 ACL ID;目标必须存在且当前身份有权管理。 | |
[].name | string | 否 | 新的 ACL 名称;不能为空,且在 ACL 所属用户下必须唯一。 | |
[].des | string | 否 | 新的 ACL 备注说明,可设置为空字符串。 | |
[].default_action | string enum | 否 | 所有规则均未匹配时执行的新默认动作:`reject` 拒绝请求,`allow` 放行请求。 | reject | allow |
[].reject_code | string enum | 否 | 默认拒绝动作使用的新响应方式;403 表示直接拒绝,302 表示重定向。 | 403 | 302 |
[].redirect_url | string | 否 | 新的默认重定向地址;最终 `reject_code` 为 302 时不能为空。 | |
[].data | array | 否 | 替换现有配置的完整 ACL 规则数组;条目数不得超过系统配置的 `acl-max-limit`。 | |
[].data | array<object> | 否 | 替换现有配置的完整 ACL 规则数组;条目数不得超过系统配置的 `acl-max-limit`。 | |
[].data[].acl_action | string enum | 是 | 该条规则匹配后执行的动作:`reject` 拒绝请求,`allow` 放行请求。 | reject | allow |
[].data[].acl_code | string enum | 否 | 该条规则执行 `reject` 时使用的响应方式;省略时为 403。 | 403 | 302 |
[].data[].acl_url | string | 否 | 该条规则的 `acl_code` 为 302 时必填的重定向地址。 | |
[].data[].acl_matcher | array | 是 | 该条 ACL 规则的新匹配条件;每个条件由匹配项、操作符和值组成。 | |
[].data[].acl_matcher | array<object> | 否 | 该条 ACL 规则的新匹配条件;每个条件由匹配项、操作符和值组成。 | |
[].data[].acl_matcher[].item | string 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[].op | string enum | 是 | 匹配操作符;`ip_range` 和 `!ip_range` 用于判断 IP 是否属于指定 CIDR 范围。 | > | = | != | !contain | contain | prefix | suffix | regex | !regex | exists | !exists | ip_range | !ip_range |
[].data[].acl_matcher[].value | string | 否 | 参与匹配的值。服务端会移除空行并转为小写;IP 范围操作符使用空白分隔一个或多个 CIDR。 | |
[].enable | integer enum | 否 | 更新后的启用状态:1 表示启用,0 表示禁用。禁用前 ACL 不能仍被网站引用。 | 0 | 1 |
[].uid | integer(int64) | 否 | 仅管理员可传,用于按指定用户执行名称和网站引用校验;该字段不会转移 ACL 的所属用户。 | |
请求始终通过 HTTP 200 返回。整批更新成功时返回确认消息;请求体不是数组、ACL 不存在或无权限、字段或嵌套规则校验失败、ACL 仍被网站引用而尝试禁用时,通过字符串 `code` 和 `msg` 返回业务错误,且本批次修改全部回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,整批 ACL 更新成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 整批 ACL 更新并提交事务后返回的确认消息。 | 更新ACL成功 |
oneOf#1.data | string enum | 是 | 批量更新成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string | 是 | 业务错误码。常见值包括请求体格式错误 `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.msg | string | 是 | 与业务错误码对应的中文校验失败或权限错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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_id | path | string | 是 | 要删除的 ACL ID;批量删除时使用英文逗号连接多个正整数,例如 `1,2,3`。 | |
请求始终通过 HTTP 200 返回。全部 ACL 删除并提交事务后返回确认消息;任一 ID 格式错误、ACL 不存在、当前身份无权删除、ACL 尚未禁用或关联任务仍在处理时,通过字符串 `code` 和 `msg` 返回业务错误,整批删除会回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,全部目标 ACL 删除成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 全部目标 ACL 删除并提交事务后返回的确认消息。 | ACL删除成功 |
oneOf#1.data | string enum | 是 | 删除成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文格式、资源状态或权限错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/acls/{acl_id}
根据 ACL ID 获取当前登录用户拥有的一条 ACL 完整配置。服务端同时使用路径中的 `acl_id` 和当前登录用户 ID 查询,因此目标 ACL 不属于当前账号时与不存在时返回相同错误;管理员身份也不会绕过这项所属用户限制。返回内容是 ACL 表中的原始配置,不包含列表接口联表提供的任务状态、用户名或格式化时间字段。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
acl_id | path | integer(int64) | 是 | 要查询的 ACL ID,目标 ACL 必须属于当前登录用户。 | |
请求通过 HTTP 200 返回。查询成功时返回 ACL 的完整持久化字段;ACL 不存在或不属于当前登录用户时返回业务错误 `acl-30`,登录态无效时返回 `login_required`。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,查询到 ACL 时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 详情查询成功时没有额外提示,固定为空字符串。 | |
oneOf#1.data | object | 是 | 当前登录用户拥有的 ACL 完整配置。 | |
oneOf#1.data.id | integer(int64) | 是 | ACL 的唯一 ID。 | |
oneOf#1.data.uid | integer(int64) | 是 | ACL 所属用户的 ID,与当前登录用户 ID 一致。 | |
oneOf#1.data.name | string | 是 | ACL 名称,同一用户下不可重名。 | |
oneOf#1.data.des | string | 是 | ACL 的备注说明,可为空字符串。 | |
oneOf#1.data.default_action | string enum | 是 | 所有 ACL 规则均未匹配时执行的默认动作。 | reject | allow |
oneOf#1.data.reject_code | string enum | 是 | 默认拒绝动作的响应方式:403 表示直接拒绝,302 表示重定向。 | 403 | 302 |
oneOf#1.data.redirect_url | string | 是 | `reject_code` 为 302 时使用的重定向地址,否则通常为空字符串。 | |
oneOf#1.data.data | string | 是 | 序列化后的 ACL 规则 JSON 数组;使用规则前需要再次解析该字符串。 | |
oneOf#1.data.create_at | string | 是 | ACL 的数据库创建时间;历史数据未记录时为 null。 | |
oneOf#1.data.update_at | string | 是 | ACL 的数据库最后更新时间;历史数据未记录时为 null。 | |
oneOf#1.data.enable | integer enum | 是 | ACL 启用状态:1 表示启用,0 表示禁用。 | 0 | 1 |
oneOf#1.data.task_id | integer(int64) | 是 | 最近一次 ACL 同步或删除任务的 ID;没有关联任务时为 null。 | |
oneOf#1.data.version | integer(int64) | 是 | ACL 配置版本号,每次更新时递增。 | |
oneOf#2.code | string enum | 是 | 业务错误码:`acl-30` 表示 ACL 不存在或无权查看,`login_required` 表示登录态无效。 | acl-30 | login_required |
oneOf#2.msg | string | 是 | 与业务错误码对应的中文错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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_id | path | integer(int64) | 是 | 要更新的 ACL ID;目标必须存在且当前身份有权管理。 | |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
id | integer(int64) | 否 | 兼容字段;如传入会被忽略,实际目标始终由路径中的 `acl_id` 决定。 | |
name | string | 否 | 新的 ACL 名称;不能为空,且在 ACL 所属用户下必须唯一。 | |
des | string | 否 | 新的 ACL 备注说明,可设置为空字符串。 | |
default_action | string enum | 否 | 所有规则均未匹配时执行的新默认动作:`reject` 拒绝请求,`allow` 放行请求。 | reject | allow |
reject_code | string enum | 否 | 默认拒绝动作使用的新响应方式;403 表示直接拒绝,302 表示重定向。 | 403 | 302 |
redirect_url | string | 否 | 新的默认重定向地址;最终 `reject_code` 为 302 时不能为空。 | |
data | array | 否 | 替换现有配置的完整 ACL 规则数组;条目数不得超过系统配置的 `acl-max-limit`。 | |
data | array<object> | 否 | 替换现有配置的完整 ACL 规则数组;条目数不得超过系统配置的 `acl-max-limit`。 | |
data[].acl_action | string enum | 是 | 该条规则匹配后执行的动作:`reject` 拒绝请求,`allow` 放行请求。 | reject | allow |
data[].acl_code | string enum | 否 | 该条规则执行 `reject` 时使用的响应方式;省略时为 403。 | 403 | 302 |
data[].acl_url | string | 否 | 该条规则的 `acl_code` 为 302 时必填的重定向地址。 | |
data[].acl_matcher | array | 是 | 该条 ACL 规则的新匹配条件;每个条件由匹配项、操作符和值组成。 | |
data[].acl_matcher | array<object> | 否 | 该条 ACL 规则的新匹配条件;每个条件由匹配项、操作符和值组成。 | |
data[].acl_matcher[].item | string 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[].op | string enum | 是 | 匹配操作符;`ip_range` 和 `!ip_range` 用于判断 IP 是否属于指定 CIDR 范围。 | > | = | != | !contain | contain | prefix | suffix | regex | !regex | exists | !exists | ip_range | !ip_range |
data[].acl_matcher[].value | string | 否 | 参与匹配的值。服务端会移除空行并转为小写;IP 范围操作符使用空白分隔一个或多个 CIDR。 | |
enable | integer enum | 否 | 更新后的启用状态:1 表示启用,0 表示禁用。禁用前 ACL 不能仍被网站引用。 | 0 | 1 |
uid | integer(int64) | 否 | 仅管理员可传,用于按指定用户执行名称和网站引用校验;该字段不会转移 ACL 的所属用户。 | |
请求始终通过 HTTP 200 返回。单条 ACL 更新成功时返回确认消息;请求体不是对象、ACL 不存在或无权限、字段或嵌套规则校验失败、ACL 仍被网站引用而尝试禁用时,通过字符串 `code` 和 `msg` 返回业务错误,当前更新事务会回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,ACL 更新成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | ACL 更新并提交事务后返回的确认消息。 | 更新ACL成功 |
oneOf#1.data | string enum | 是 | 单条更新成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string | 是 | 业务错误码。常见值包括请求体格式错误 `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.msg | string | 是 | 与业务错误码对应的中文校验失败或权限错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
CC 匹配、过滤和规则管理。
GET /v1/cc-filters
分页查询当前身份可见的 CC 过滤器。普通用户始终只返回归属于自己的过滤器;管理员默认可查看全部用户及系统内置过滤器,并可按所属用户筛选。接口支持按过滤器 ID、名称、启用状态和是否为内置过滤器筛选,结果按过滤器 ID 倒序排列;系统保留的 10020 号过滤器始终不会出现在列表中。响应中的 `extra` 是序列化后的过滤器扩展配置 JSON 字符串,需要调用方再次解析。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,从 1 开始;省略时为 1。只能传十进制非负整数字符串,非数字值返回 `cc_filter-33`;`limit=0` 时该参数不影响返回范围。 | |
limit | query | integer(int32) | 否 | 每页返回的过滤器数量,省略时为 10;传 0 表示不分页并返回全部匹配记录。非数字值返回 `cc_filter-34`。 | |
uid | query | integer(int64) | 否 | 按过滤器所属用户 ID 精确筛选,仅管理员身份生效;普通用户传入该参数时仍只返回自己的过滤器。 | |
internal | query | integer | 否 | 按是否为系统内置过滤器精确筛选:1 表示内置,0 表示用户自定义。使用该筛选条件要求管理员身份,普通用户传入时返回 `cc_filter-59`。 | |
enable | query | integer | 否 | 按启用状态精确筛选:1 表示已启用,0 表示已禁用。 | |
id | query | integer(int64) | 否 | 按 CC 过滤器 ID 精确筛选列表;系统保留的 10020 号过滤器即使匹配也不会返回。 | |
name | query | string | 否 | 按过滤器名称进行包含匹配。 | |
请求通过 HTTP 200 返回。成功时给出匹配总数和当前页过滤器列表;页码或每页数量格式错误、普通用户筛选内置过滤器或认证失效时,通过字符串 `code` 和 `msg` 返回业务错误。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,列表查询成功时固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 符合身份范围及筛选条件的过滤器总数,不受当前页 `limit` 限制。 | |
oneOf#1.data | array | 是 | 当前页的 CC 过滤器记录,按过滤器 ID 从大到小排列。 | |
oneOf#1.data | array<object> | 否 | 当前页的 CC 过滤器记录,按过滤器 ID 从大到小排列。 | |
oneOf#1.data[].id | integer(int64) | 是 | CC 过滤器的唯一 ID。 | |
oneOf#1.data[].uid | integer(int64) | 是 | 过滤器所属用户的 ID;不归属于具体用户的系统内置过滤器可为 null。 | |
oneOf#1.data[].c.uid | integer(int64) | 是 | 查询结果中因再次选择所属用户列而生成的重复字段,值与 `uid` 相同;系统内置过滤器可为 null。 | |
oneOf#1.data[].name | string | 是 | 过滤器名称,同一用户下不可重名。 | |
oneOf#1.data[].des | string | 是 | 过滤器备注,可为空字符串。 | |
oneOf#1.data[].type | string 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_second | integer(int32) | 是 | 请求统计窗口的秒数。 | |
oneOf#1.data[].max_req | integer(int32) | 是 | 统计窗口内允许的最大请求数。 | |
oneOf#1.data[].max_req_per_uri | integer(int32) | 是 | `req_rate` 类型下同一 URI 在统计窗口内允许的最大请求数;其他类型通常为 0。 | |
oneOf#1.data[].extra | string | 是 | 序列化后的扩展配置 JSON。`url_auth` 类型包含模式、密钥、签名参数名、时间容差及签名可用次数;其他类型通常为 `{}`。 | |
oneOf#1.data[].create_at | string | 是 | 数据库返回的过滤器创建时间;历史记录未保存时间时为 null。 | |
oneOf#1.data[].update_at | string | 是 | 数据库返回的过滤器最后更新时间;历史记录未保存时间时为 null。 | |
oneOf#1.data[].internal | integer enum | 是 | 是否为系统内置过滤器:1 表示内置,0 表示用户自定义。 | 0 | 1 |
oneOf#1.data[].enable | integer enum | 是 | 过滤器启用状态:1 表示启用,0 表示禁用。 | 0 | 1 |
oneOf#1.data[].task_id | integer(int64) | 是 | 最近一次过滤器同步或删除任务的 ID;没有关联任务时为 null。 | |
oneOf#1.data[].version | integer(int64) | 是 | 过滤器配置版本号,修改过滤器时递增。 | |
oneOf#1.data[].state | string | 是 | 关联任务的当前状态;过滤器没有关联任务时为 null。 | |
oneOf#1.data[].create_at2 | string | 是 | 格式化为 `YYYY-MM-DD HH:mm:ss` 的创建时间;原始创建时间为 null 时也为 null。 | |
oneOf#1.data[].update_at2 | string | 是 | 格式化为 `YYYY-MM-DD HH:mm:ss` 的最后更新时间;原始更新时间为 null 时也为 null。 | |
oneOf#1.data[].username | string | 是 | 过滤器所属用户的名称;不归属于具体用户的系统内置过滤器为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文参数、权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
POST /v1/cc-filters
为当前登录用户创建一个 CC 过滤器,创建前会按照当前账号的网站数量和系统配置检查可创建的站点关联对象配额;同一所属用户下过滤器名称不可重复。普通用户只能创建归属于自己的自定义过滤器,管理员可通过请求体指定所属用户或创建系统内置过滤器。`req_rate` 类型必须配置单 URI 请求上限,`url_auth` 类型必须配置 URL 鉴权参数;其他类型的扩展配置会以空对象保存。新增过滤器固定以启用状态和版本 1 写入。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
internal | query | integer | 否 | 兼容性权限检查参数。传 1 时要求管理员身份,否则返回 `cc_filter-55`;该查询参数本身不会把新过滤器标记为内置,创建内置过滤器应同时在 JSON 请求体中传 `internal: 1`。 | |
请求体必填。
Content-Type:application/json
创建 CC 过滤器的 JSON 对象;未识别字段不会参与创建逻辑。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.type | string enum | 否 | 请求频率限制类型,要求同时提供单 URI 请求上限。 | req_rate |
oneOf#2.type | string enum | 否 | URL 鉴权类型,要求同时提供符合所选模式的扩展配置。 | url_auth |
oneOf#2.extra | oneOf | 是 | 根据 `mode` 选择 TypeA 或 TypeB 的 URL 鉴权配置。 | |
oneOf#2.extra(oneOf#1).mode | string enum | 是 | URL 鉴权模式;TypeA 从独立的时间戳查询参数读取签名时间。 | TypeA |
oneOf#2.extra(oneOf#1).key | string | 是 | 计算 URL 签名使用的密钥,长度必须为 16 至 32 个字符。 | |
oneOf#2.extra(oneOf#1).sign_name | string | 是 | 请求 URL 中承载签名值的查询参数名,不能为空。 | |
oneOf#2.extra(oneOf#1).time_name | string | 是 | TypeA 模式下承载签名时间戳的查询参数名,不能为空。 | |
oneOf#2.extra(oneOf#1).time_diff | oneOf | 是 | 签名时间与服务端时间允许的最大秒数差,必须为不超过 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_times | oneOf | 是 | 同一签名允许使用的次数,必须为非负整数或仅含十进制数字的字符串。 | |
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).mode | string enum | 是 | URL 鉴权模式;TypeB 不要求独立的时间戳参数名。 | TypeB |
oneOf#2.extra(oneOf#2).key | string | 是 | 计算 URL 签名使用的密钥,长度必须为 16 至 32 个字符。 | |
oneOf#2.extra(oneOf#2).sign_name | string | 是 | 请求 URL 中承载签名值的查询参数名,不能为空。 | |
oneOf#2.extra(oneOf#2).time_diff | oneOf | 是 | 签名时间与服务端时间允许的最大秒数差,必须为不超过 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_times | oneOf | 是 | 同一签名允许使用的次数,必须为非负整数或仅含十进制数字的字符串。 | |
oneOf#2.extra(oneOf#2).sign_use_times(oneOf#1) | integer | 否 | | |
oneOf#2.extra(oneOf#2).sign_use_times(oneOf#2) | string | 否 | | |
oneOf#3.type | string enum | 否 | 无需额外条件字段的验证、跳转或轮转过滤器类型。 | easy_click_filter | easy_slide_filter | 302_challenge | browser_verify_auto | slide_filter | captcha_filter | click_filter | delay_jump_filter | rotate_filter |
业务结果通过 HTTP 200 返回。创建成功时返回新过滤器 ID;配额不足、名称或阈值不合法、类型条件字段缺失、URL 鉴权配置错误、管理员专属字段越权、系统维护或认证失效时返回字符串业务错误码,数据库事务会回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,过滤器创建并提交事务后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 过滤器记录创建成功后返回的确认消息。 | 过滤器添加成功 |
oneOf#1.data | integer(int64) | 是 | 数据库为新 CC 过滤器生成的唯一 ID。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文配额、字段校验、URL 鉴权、权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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`。 | |
[].id | oneOf | 是 | 要更新的 CC 过滤器 ID;接受正整数或仅含十进制数字的字符串,记录必须存在且当前身份必须有权更新。 | |
[].id(oneOf#1) | integer | 否 | | |
[].id(oneOf#2) | string | 否 | | |
[].name | string | 否 | 新的过滤器名称;服务端会过滤可执行的 HTML 内容,处理后不得为空,并且在校验所属用户下不可与其他过滤器重名。 | |
[].des | string | 否 | 新的过滤器备注;服务端会过滤可执行的 HTML 内容,可传空字符串清空备注。 | |
[].type | string 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_second | oneOf | 否 | 新的请求统计窗口秒数;接受非负整数或仅含十进制数字的字符串,省略时保持原值。 | |
[].within_second(oneOf#1) | integer | 否 | | |
[].within_second(oneOf#2) | string | 否 | | |
[].max_req | oneOf | 否 | 新的统计窗口总请求上限;接受非负整数或仅含十进制数字的字符串,省略时保持原值。 | |
[].max_req(oneOf#1) | integer | 否 | | |
[].max_req(oneOf#2) | string | 否 | | |
[].max_req_per_uri | oneOf | 否 | 新的单 URI 请求上限。仅目标更新后的类型为 `req_rate` 时校验并写入,必须为非负整数或十进制数字字符串;其他类型会忽略该字段。 | |
[].max_req_per_uri(oneOf#1) | integer | 否 | | |
[].max_req_per_uri(oneOf#2) | string | 否 | | |
[].extra | object | 否 | 新的扩展配置。仅目标更新后的类型为 `url_auth` 时校验并序列化写入,要求 `mode`、`key`、`sign_name`、`time_diff`、`sign_use_times`,TypeA 还要求 `time_name`;其他类型会忽略该字段,附加键会随对象保存。 | |
[].extra.mode | string enum | 否 | URL 鉴权模式;TypeA 还要求 `time_name`,TypeB 不要求独立的时间戳参数名。 | TypeA | TypeB |
[].extra.key | string | 否 | 计算 URL 签名使用的密钥,长度必须为 16 至 32 个字符。 | |
[].extra.sign_name | string | 否 | 请求 URL 中承载签名值的查询参数名,不能为空。 | |
[].extra.time_name | string | 否 | TypeA 模式下承载签名时间戳的查询参数名;TypeA 必填且不能为空。 | |
[].extra.time_diff | oneOf | 否 | 签名时间与服务端时间允许的最大秒数差,必须为不超过 3600 的非负整数。 | |
[].extra.time_diff(oneOf#1) | integer | 否 | | |
[].extra.time_diff(oneOf#2) | string | 否 | | |
[].extra.sign_use_times | oneOf | 否 | 同一签名允许使用的次数,必须为非负整数或仅含十进制数字的字符串。 | |
[].extra.sign_use_times(oneOf#1) | integer | 否 | | |
[].extra.sign_use_times(oneOf#2) | string | 否 | | |
[].enable | integer enum | 否 | 新的启用状态:1 表示启用,0 表示禁用。禁用前会检查所有当前用户及系统 CC 规则,仍被引用时返回 `cc_filter-30`。 | 0 | 1 |
[].uid | integer(int64) | 否 | 兼容性管理员字段,用作本次名称唯一性和 CC 规则引用检查的用户上下文;仅管理员可传。该字段不会修改过滤器数据库中的所属用户,不能用于转移过滤器。 | |
[].internal | integer enum | 否 | 兼容性处理标记,1 要求管理员身份并会按内置过滤器流程决定同步任务。该字段不会改写数据库中已有的内置状态,不能用于把普通过滤器转换为内置过滤器或反向转换。 | 0 | 1 |
业务结果通过 HTTP 200 返回。全部元素更新并提交后返回确认消息;请求体格式、过滤器 ID、访问权限、更新字段、URL 鉴权配置或禁用前引用检查失败,以及系统维护或认证失效时返回字符串业务错误码,整个批次事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,整个批次更新并提交后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 所有过滤器更新成功后返回的确认消息。 | 更新过滤器成功 |
oneOf#1.data | string enum | 是 | 批量更新成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文请求格式、记录、字段校验、引用冲突、权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
DELETE /v1/cc-filters/{filter_id}
删除路径中指定的一个或多个 CC 过滤器,多个 ID 使用英文逗号分隔并在同一个数据库事务中处理。普通用户只能删除归属于自己的自定义过滤器,管理员可以删除系统内置过滤器及其他用户的过滤器。每个目标必须已经禁用;如果仍有关联的同步或删除任务,该任务状态必须为 `done`。任一 ID 格式错误、记录不存在、越权、仍启用或任务未完成时,整个批次回滚,不会保留部分删除结果。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
filter_id | path | string | 是 | 要删除的 CC 过滤器 ID;删除多个过滤器时按 `10021,10022` 形式使用英文逗号连接,每一段都必须是十进制数字。 | |
业务结果通过 HTTP 200 返回。全部目标通过检查、删除并提交后返回确认消息;ID 格式、记录存在性、权限、启用状态或关联任务状态不符合要求,以及系统维护或认证失效时返回字符串业务错误码,整个批次事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,所有目标过滤器删除并提交后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 整个删除批次成功提交后返回的确认消息。 | 过滤器删除成功 |
oneOf#1.data | string enum | 是 | 删除成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文 ID、记录、状态、权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/cc-filters/{filter_id}
按 ID 获取一条 CC 过滤器的原始配置记录。系统内置过滤器仅管理员身份可以读取;用户自定义过滤器仅允许其所属用户读取,管理员身份本身不会绕过自定义过滤器的所有者校验。返回的是 `cc_filter` 记录本身,不包含列表接口联表得到的任务状态、用户名或格式化时间字段;`extra` 为序列化后的扩展配置 JSON 字符串,使用前需要再次解析。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
filter_id | path | integer(int64) | 是 | 要查询的 CC 过滤器 ID;路由只接受十进制整数。 | |
业务结果通过 HTTP 200 返回。过滤器存在且当前身份有读取权限时返回完整原始配置;记录不存在、读取内置过滤器时不是管理员、读取其他用户的自定义过滤器或认证失效时返回字符串业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,过滤器详情读取成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 详情读取成功时没有附加提示,固定为空字符串。 | |
oneOf#1.data | object | 是 | 数据库中的 CC 过滤器原始配置记录。 | |
oneOf#1.data.id | integer(int64) | 是 | CC 过滤器的唯一 ID。 | |
oneOf#1.data.uid | integer(int64) | 是 | 过滤器所属用户的 ID;系统内置过滤器不归属于具体用户时为 null。 | |
oneOf#1.data.name | string | 是 | 过滤器名称,同一所属用户下不可重名。 | |
oneOf#1.data.des | string | 是 | 过滤器备注,可为空字符串。 | |
oneOf#1.data.type | string 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_second | integer(int32) | 是 | 请求统计窗口的秒数。 | |
oneOf#1.data.max_req | integer(int32) | 是 | 统计窗口内允许的最大请求数。 | |
oneOf#1.data.max_req_per_uri | integer(int32) | 是 | `req_rate` 类型下同一 URI 在统计窗口内允许的最大请求数;其他类型通常为 0。 | |
oneOf#1.data.extra | string | 是 | 序列化后的扩展配置 JSON。`url_auth` 类型包含 URL 鉴权模式及签名参数,其他类型通常为 `{}`。 | |
oneOf#1.data.create_at | string | 是 | 数据库返回的过滤器创建时间;历史记录未保存时间时为 null。 | |
oneOf#1.data.update_at | string | 是 | 数据库返回的过滤器最后更新时间;历史记录未保存时间时为 null。 | |
oneOf#1.data.internal | integer enum | 是 | 是否为系统内置过滤器:1 表示内置,0 表示用户自定义。 | 0 | 1 |
oneOf#1.data.enable | integer enum | 是 | 过滤器启用状态:1 表示启用,0 表示禁用。 | 0 | 1 |
oneOf#1.data.task_id | integer(int64) | 是 | 最近一次过滤器同步或删除任务的 ID;没有关联任务时为 null。 | |
oneOf#1.data.version | integer(int64) | 是 | 过滤器配置版本号,每次更新时递增。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文记录不存在、所有权、管理员权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
PUT /v1/cc-filters/{filter_id}
按路径 ID 更新一条 CC 过滤器,只修改 JSON 对象中明确提供且被服务端支持的字段;JSON 对象内的 `id` 即使存在也会被路径参数覆盖。普通用户只能更新归属于自己的自定义过滤器,管理员可更新其他用户或系统内置过滤器。成功更新时配置版本号必定递增并刷新更新时间,即使请求体为空对象。修改正在使用的关键配置或系统内置过滤器时会创建节点同步任务;禁用过滤器时如仍被 CC 规则引用则拒绝,否则创建节点删除任务。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
filter_id | path | integer(int64) | 是 | 要更新的 CC 过滤器 ID;路由只接受十进制整数,记录必须存在且当前身份必须有权更新。 | |
请求体必填。
Content-Type:application/json
单个过滤器的更新对象;可以为空对象,此时只递增版本并刷新更新时间。请求体必须是 JSON 对象,数组、标量或空 JSON 返回 `cc_filter-6`;未识别字段不写入记录,`id` 字段由路径参数覆盖。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 否 | 新的过滤器名称;服务端会过滤可执行的 HTML 内容,处理后不得为空,并且在校验所属用户下不可与其他过滤器重名。 | |
des | string | 否 | 新的过滤器备注;服务端会过滤可执行的 HTML 内容,可传空字符串清空备注。 | |
type | string 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_second | oneOf | 否 | 新的请求统计窗口秒数;接受非负整数或仅含十进制数字的字符串,省略时保持原值。 | |
within_second(oneOf#1) | integer | 否 | | |
within_second(oneOf#2) | string | 否 | | |
max_req | oneOf | 否 | 新的统计窗口总请求上限;接受非负整数或仅含十进制数字的字符串,省略时保持原值。 | |
max_req(oneOf#1) | integer | 否 | | |
max_req(oneOf#2) | string | 否 | | |
max_req_per_uri | oneOf | 否 | 新的单 URI 请求上限。仅目标更新后的类型为 `req_rate` 时校验并写入,必须为非负整数或十进制数字字符串;其他类型会忽略该字段。 | |
max_req_per_uri(oneOf#1) | integer | 否 | | |
max_req_per_uri(oneOf#2) | string | 否 | | |
extra | object | 否 | 新的扩展配置。仅目标更新后的类型为 `url_auth` 时校验并序列化写入,要求 `mode`、`key`、`sign_name`、`time_diff`、`sign_use_times`,TypeA 还要求 `time_name`;其他类型会忽略该字段,附加键会随对象保存。 | |
extra.mode | string enum | 否 | URL 鉴权模式;TypeA 还要求 `time_name`,TypeB 不要求独立的时间戳参数名。 | TypeA | TypeB |
extra.key | string | 否 | 计算 URL 签名使用的密钥,长度必须为 16 至 32 个字符。 | |
extra.sign_name | string | 否 | 请求 URL 中承载签名值的查询参数名,不能为空。 | |
extra.time_name | string | 否 | TypeA 模式下承载签名时间戳的查询参数名;TypeA 必填且不能为空。 | |
extra.time_diff | oneOf | 否 | 签名时间与服务端时间允许的最大秒数差,必须为不超过 3600 的非负整数。 | |
extra.time_diff(oneOf#1) | integer | 否 | | |
extra.time_diff(oneOf#2) | string | 否 | | |
extra.sign_use_times | oneOf | 否 | 同一签名允许使用的次数,必须为非负整数或仅含十进制数字的字符串。 | |
extra.sign_use_times(oneOf#1) | integer | 否 | | |
extra.sign_use_times(oneOf#2) | string | 否 | | |
enable | integer enum | 否 | 新的启用状态:1 表示启用,0 表示禁用。禁用前会检查所有当前用户及系统 CC 规则,仍被引用时返回 `cc_filter-30`。 | 0 | 1 |
uid | integer(int64) | 否 | 兼容性管理员字段,用作本次名称唯一性和 CC 规则引用检查的用户上下文;仅管理员可传。该字段不会修改过滤器数据库中的所属用户,不能用于转移过滤器。 | |
internal | integer enum | 否 | 兼容性处理标记,1 要求管理员身份并会按内置过滤器流程决定同步任务。该字段不会改写数据库中已有的内置状态,不能用于转换过滤器归类。 | 0 | 1 |
业务结果通过 HTTP 200 返回。目标过滤器更新并提交后返回确认消息;请求体不是对象、过滤器不存在、访问权限不足、更新字段或 URL 鉴权配置无效、禁用时仍被引用,以及系统维护或认证失效时返回字符串业务错误码,更新事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,过滤器更新并提交后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 目标过滤器更新成功后返回的确认消息。 | 更新过滤器成功 |
oneOf#1.data | string enum | 是 | 单个过滤器更新成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文请求格式、记录、字段校验、引用冲突、权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/cc-matchs
分页查询当前身份可见的 CC 请求匹配器。普通用户始终只返回归属于自己的匹配器;管理员默认可查看全部用户及系统内置匹配器,并可按所属用户筛选。接口支持按匹配器 ID、名称、启用状态和是否为内置匹配器筛选,结果按匹配器 ID 倒序排列;系统保留的 10020 号记录始终不会出现在列表中。响应中的 `data` 是序列化 JSON 字符串:`{}` 表示匹配全部请求,其他记录通常是由匹配项、操作符和值组成的条件数组。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,从 1 开始;省略时为 1。只能传十进制非负整数字符串,非数字值返回 `cc_match-28`;`limit=0` 时该参数不影响返回范围。 | |
limit | query | integer(int32) | 否 | 每页返回的匹配器数量,省略时为 10;传 0 表示不分页并返回全部匹配记录。非数字值返回 `cc_match-29`。 | |
uid | query | integer(int64) | 否 | 按匹配器所属用户 ID 精确筛选,仅管理员身份生效;普通用户传入该参数时仍只返回自己的匹配器。 | |
internal | query | integer | 否 | 按是否为系统内置匹配器精确筛选:1 表示内置,0 表示用户自定义。使用该筛选条件要求管理员身份,普通用户传入时返回 `cc_match-42`。 | |
enable | query | integer | 否 | 按启用状态精确筛选:1 表示已启用,0 表示已禁用。 | |
id | query | integer(int64) | 否 | 按 CC 匹配器 ID 精确筛选列表;系统保留的 10020 号记录即使匹配也不会返回。 | |
name | query | string | 否 | 按匹配器名称进行包含匹配。 | |
请求通过 HTTP 200 返回。成功时给出符合身份范围及筛选条件的总数和当前页匹配器列表;页码或每页数量格式错误、普通用户筛选内置匹配器或认证失效时,通过字符串 `code` 和 `msg` 返回业务错误。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,列表查询成功时固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 符合身份范围及筛选条件的匹配器总数,不受当前页 `limit` 限制。 | |
oneOf#1.data | array | 是 | 当前页的 CC 匹配器记录,按匹配器 ID 从大到小排列。 | |
oneOf#1.data | array<object> | 否 | 当前页的 CC 匹配器记录,按匹配器 ID 从大到小排列。 | |
oneOf#1.data[].id | integer(int64) | 是 | CC 匹配器的唯一 ID。 | |
oneOf#1.data[].uid | integer(int64) | 是 | 匹配器所属用户的 ID;不归属于具体用户的系统内置匹配器可为 null。 | |
oneOf#1.data[].c.uid | integer(int64) | 是 | 查询结果中因再次选择所属用户列而生成的重复字段,值与 `uid` 相同;系统内置匹配器可为 null。 | |
oneOf#1.data[].name | string | 是 | 匹配器名称,同一用户下不可重名。 | |
oneOf#1.data[].des | string | 是 | 匹配器备注,可为空字符串。 | |
oneOf#1.data[].data | string | 是 | 序列化后的匹配规则 JSON。`{}` 表示匹配全部请求;条件数组中的每项包含 `item`、`op` 和规范化后的 `value`。 | |
oneOf#1.data[].create_at | string | 是 | 数据库返回的匹配器创建时间;历史记录未保存时间时为 null。 | |
oneOf#1.data[].update_at | string | 是 | 数据库返回的匹配器最后更新时间;历史记录未保存时间时为 null。 | |
oneOf#1.data[].internal | integer enum | 是 | 是否为系统内置匹配器:1 表示内置,0 表示用户自定义。 | 0 | 1 |
oneOf#1.data[].enable | integer enum | 是 | 匹配器启用状态:1 表示启用,0 表示禁用。 | 0 | 1 |
oneOf#1.data[].task_id | integer(int64) | 是 | 最近一次匹配器同步或删除任务的 ID;没有关联任务时为 null。 | |
oneOf#1.data[].version | integer(int64) | 是 | 匹配器配置版本号,每次更新时递增。 | |
oneOf#1.data[].state | string | 是 | 关联任务的当前状态;匹配器没有关联任务时为 null。 | |
oneOf#1.data[].create_at2 | string | 是 | 格式化为 `YYYY-MM-DD HH:mm:ss` 的创建时间;原始创建时间为 null 时也为 null。 | |
oneOf#1.data[].update_at2 | string | 是 | 格式化为 `YYYY-MM-DD HH:mm:ss` 的最后更新时间;原始更新时间为 null 时也为 null。 | |
oneOf#1.data[].username | string | 是 | 匹配器所属用户的名称;不归属于具体用户的系统内置匹配器为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文参数、权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
POST /v1/cc-matchs
为当前登录用户创建一个 CC 请求匹配器,创建前会按照当前账号的网站数量和系统配置检查可创建的站点关联对象配额;同一所属用户下匹配器名称不可重复。普通用户只能创建归属于自己的自定义匹配器,管理员可通过 JSON 对象指定所属用户或创建系统内置匹配器。省略 `data` 时保存 `{}`,表示匹配全部请求;提供 `data` 时必须是条件数组,服务端会去除值中的空行和首尾空白并转换为小写。新增匹配器固定以启用状态和版本 1 写入。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
internal | query | integer | 否 | 兼容性权限检查参数,只接受 0 或 1。传 1 时要求管理员身份,否则返回 `cc_match-38`;该查询参数本身不会把新匹配器标记为内置,创建内置匹配器应在 JSON 对象中传 `internal: 1`。 | |
请求体必填。
Content-Type:application/json
创建 CC 匹配器的 JSON 对象;未识别的顶层字段不会参与创建逻辑。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 是 | 匹配器名称;服务端会过滤可执行的 HTML 内容,且要求处理后的名称非空、在所属用户下唯一。 | |
des | string | 否 | 匹配器备注;服务端会过滤可执行的 HTML 内容,省略时保存为空字符串。 | |
data | array | 否 | 请求匹配条件数组。省略整个字段时保存 `{}` 并匹配全部请求;提供时可为空数组,每项按 `item`、`op` 和 `value` 进行校验及规范化。 | |
data | array<object> | 否 | 请求匹配条件数组。省略整个字段时保存 `{}` 并匹配全部请求;提供时可为空数组,每项按 `item`、`op` 和 `value` 进行校验及规范化。 | |
data[].item | string 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[].op | string enum | 是 | 匹配操作符,依次支持大于、等于、不等于、不包含、包含、前缀、后缀、正则匹配、正则不匹配、存在、不存在、位于 IP 网段和不位于 IP 网段。 | > | = | != | !contain | contain | prefix | suffix | regex | !regex | exists | !exists | ip_range | !ip_range |
data[].value | string | 否 | 匹配值,省略时补为空字符串。服务端会去除首尾空白和空行并转为小写;`ip_range` 与 `!ip_range` 可用空白分隔多个 IP/CIDR,且每项都会校验格式;`exists` 与 `!exists` 通常使用空字符串。 | |
data[].value2 | string | 否 | 随条件原样保存的补充参数;管理界面将其用于 `header` 的自定义请求头名称,以及 `count404`、`uniq_ua` 等统计匹配项的统计秒数。 | |
uid | integer(int64) | 否 | 新匹配器所属用户的 ID;省略时为当前登录用户,仅管理员可指定该字段,否则返回 `cc_match-39`。 | |
internal | integer enum | 否 | 是否创建为系统内置匹配器:1 表示内置,0 表示用户自定义;省略时为 0,传 1 要求管理员身份,否则返回 `cc_match-40`。 | 0 | 1 |
enable | integer enum | 否 | 兼容性输入字段,只接受 0 或 1;新增记录最终固定以启用状态 1 保存,即使这里传 0 也不会创建禁用记录。 | 0 | 1 |
业务结果通过 HTTP 200 返回。创建成功时返回新匹配器 ID;配额不足、查询或 JSON 内置标记无效、名称校验失败、条件数组及其匹配项/操作符/值不合法、管理员专属字段越权、系统维护或认证失效时返回字符串业务错误码,数据库事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,匹配器创建并提交事务后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 匹配器记录创建成功后返回的确认消息。 | 匹配器添加成功 |
oneOf#1.data | integer(int64) | 是 | 数据库为新 CC 匹配器生成的唯一 ID。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文配额、名称、匹配条件、状态、权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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`。 | |
[].id | oneOf | 是 | 要更新的 CC 匹配器 ID;接受正整数或仅含十进制数字的字符串,记录必须存在且当前身份必须有权更新。 | |
[].id(oneOf#1) | integer | 否 | | |
[].id(oneOf#2) | string | 否 | | |
[].name | string | 否 | 新的匹配器名称;服务端会过滤可执行的 HTML 内容,处理后不得为空,并且在校验所属用户下不可与其他匹配器重名。 | |
[].des | string | 否 | 新的匹配器备注;服务端会过滤可执行的 HTML 内容,可传空字符串清空备注。 | |
[].data | array | 否 | 新的请求匹配条件数组;可为空数组。服务端会逐项校验,并将每项 `value` 去除首尾空白和空行后转换为小写再保存。 | |
[].data | array<object> | 否 | 新的请求匹配条件数组;可为空数组。服务端会逐项校验,并将每项 `value` 去除首尾空白和空行后转换为小写再保存。 | |
[].data[].item | string 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[].op | string enum | 是 | 匹配操作符,支持大小比较、包含、前后缀、正则、存在性以及 IP 网段包含或排除判断。 | > | = | != | !contain | contain | prefix | suffix | regex | !regex | exists | !exists | ip_range | !ip_range |
[].data[].value | string | 否 | 匹配值,省略时补为空字符串;服务端会移除首尾空白和空行并转为小写。IP 网段操作符可用空白分隔多个 IP/CIDR,且每项都会校验格式。 | |
[].data[].value2 | string | 否 | 随条件原样保存的补充参数;管理界面将其用于自定义请求头名称或统计匹配项的统计秒数。 | |
[].enable | integer enum | 否 | 新的启用状态:1 表示启用,0 表示禁用。禁用前会检查当前用户及系统 CC 规则,仍被引用时返回 `cc_match-25`。 | 0 | 1 |
[].uid | integer(int64) | 否 | 兼容性管理员字段,用作本次名称唯一性和 CC 规则引用检查的用户上下文;仅管理员可传。该字段不会修改匹配器数据库中的所属用户,不能用于转移匹配器。 | |
[].internal | integer enum | 否 | 兼容性处理标记,1 要求管理员身份并会按内置匹配器流程决定同步任务。该字段不会改写数据库中已有的内置状态,不能用于转换匹配器归类。 | 0 | 1 |
业务结果通过 HTTP 200 返回。全部元素更新并提交后返回确认消息;请求体格式、匹配器 ID、访问权限、名称、条件数组、匹配项、操作符、值、启用状态或禁用前引用检查失败,以及系统维护或认证失效时返回字符串业务错误码,整个批次事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,整个批次更新并提交后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 所有匹配器更新成功后返回的确认消息。 | 更新匹配器成功 |
oneOf#1.data | string enum | 是 | 批量更新成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文请求格式、记录、名称、匹配条件、引用冲突、权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
DELETE /v1/cc-matchs/{match_id}
删除路径中指定的一个或多个 CC 请求匹配器,多个 ID 使用英文逗号分隔并在同一个数据库事务中处理。普通用户只能删除归属于自己的自定义匹配器,管理员可以删除系统内置匹配器及其他用户的匹配器。每个目标必须已经禁用;如果仍有关联的同步或删除任务,该任务状态必须为 `done`。任一 ID 格式错误、记录不存在、越权、仍启用或任务未完成时,整个批次回滚,不会保留部分删除结果。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
match_id | path | string | 是 | 要删除的 CC 匹配器 ID;删除多个匹配器时按 `10021,10022` 形式使用英文逗号连接,每一段都必须是十进制数字。 | |
业务结果通过 HTTP 200 返回。全部目标通过检查、删除并提交后返回确认消息;ID 格式、记录存在性、权限、启用状态或关联任务状态不符合要求,以及系统维护或认证失效时返回字符串业务错误码,整个批次事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,所有目标匹配器删除并提交后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 整个删除批次成功提交后返回的确认消息。 | 匹配器删除成功 |
oneOf#1.data | string enum | 是 | 删除成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文 ID、记录、状态、权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/cc-matchs/{match_id}
按 ID 获取一条 CC 请求匹配器的原始配置记录。系统内置匹配器仅管理员身份可以读取;用户自定义匹配器仅允许其所属用户读取,管理员身份本身不会绕过自定义匹配器的所有者校验。返回的是 `cc_match` 记录本身,不包含列表接口联表得到的任务状态、用户名或格式化时间字段;`data` 为序列化后的匹配条件 JSON 字符串,使用前需要再次解析。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
match_id | path | integer(int64) | 是 | 要查询的 CC 匹配器 ID;路由只接受十进制整数。 | |
业务结果通过 HTTP 200 返回。匹配器存在且当前身份有读取权限时返回完整原始配置;记录不存在、读取内置匹配器时不是管理员、读取其他用户的自定义匹配器或认证失效时返回字符串业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,匹配器详情读取成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 详情读取成功时没有附加提示,固定为空字符串。 | |
oneOf#1.data | object | 是 | 数据库中的 CC 匹配器原始配置记录。 | |
oneOf#1.data.id | integer(int64) | 是 | CC 匹配器的唯一 ID。 | |
oneOf#1.data.uid | integer(int64) | 是 | 匹配器所属用户的 ID;系统内置匹配器不归属于具体用户时为 null。 | |
oneOf#1.data.name | string | 是 | 匹配器名称,同一所属用户下不可重名。 | |
oneOf#1.data.des | string | 是 | 匹配器备注,可为空字符串。 | |
oneOf#1.data.data | string | 是 | 序列化后的匹配条件 JSON。`{}` 表示匹配全部请求;条件数组中的每项包含 `item`、`op`、规范化后的 `value`,并可包含补充参数。 | |
oneOf#1.data.create_at | string | 是 | 数据库返回的匹配器创建时间;历史记录未保存时间时为 null。 | |
oneOf#1.data.update_at | string | 是 | 数据库返回的匹配器最后更新时间;历史记录未保存时间时为 null。 | |
oneOf#1.data.internal | integer enum | 是 | 是否为系统内置匹配器:1 表示内置,0 表示用户自定义。 | 0 | 1 |
oneOf#1.data.enable | integer enum | 是 | 匹配器启用状态:1 表示启用,0 表示禁用。 | 0 | 1 |
oneOf#1.data.task_id | integer(int64) | 是 | 最近一次匹配器同步或删除任务的 ID;没有关联任务时为 null。 | |
oneOf#1.data.version | integer(int64) | 是 | 匹配器配置版本号,每次更新时递增。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文记录不存在、所有权、管理员权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
PUT /v1/cc-matchs/{match_id}
按路径 ID 更新一条 CC 请求匹配器,只修改 JSON 对象中明确提供且被服务端支持的字段;JSON 对象内的 `id` 即使存在也会被路径参数覆盖。普通用户只能更新归属于自己的自定义匹配器,管理员可更新其他用户或系统内置匹配器。成功更新时配置版本号必定递增并刷新更新时间,即使请求体为空对象。修改正在被 CC 规则引用的匹配条件或系统内置匹配器时会创建节点同步任务;禁用匹配器时如仍被引用则拒绝,否则创建节点删除任务。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
match_id | path | integer(int64) | 是 | 要更新的 CC 匹配器 ID;路由只接受十进制整数,记录必须存在且当前身份必须有权更新。 | |
请求体必填。
Content-Type:application/json
单个匹配器的更新对象;可以为空对象,此时只递增版本并刷新更新时间。必须提供 JSON 对象,数组、标量或空 JSON 返回 `cc_match-6`;未识别字段不写入记录,`id` 字段由路径参数覆盖。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 否 | 新的匹配器名称;服务端会过滤可执行的 HTML 内容,处理后不得为空,并且在校验所属用户下不可与其他匹配器重名。 | |
des | string | 否 | 新的匹配器备注;服务端会过滤可执行的 HTML 内容,可传空字符串清空备注。 | |
data | array | 否 | 新的请求匹配条件数组;可为空数组。服务端会逐项校验,并将每项 `value` 去除首尾空白和空行后转换为小写再保存。 | |
data | array<object> | 否 | 新的请求匹配条件数组;可为空数组。服务端会逐项校验,并将每项 `value` 去除首尾空白和空行后转换为小写再保存。 | |
data[].item | string 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[].op | string enum | 是 | 匹配操作符,支持大于、相等、包含、前后缀、正则、存在性以及 IP 网段包含或排除判断。 | > | = | != | !contain | contain | prefix | suffix | regex | !regex | exists | !exists | ip_range | !ip_range |
data[].value | string | 否 | 匹配值,省略时补为空字符串;服务端会移除首尾空白和空行并转为小写。IP 网段操作符可用空白分隔多个 IP/CIDR,且每项都会校验格式。 | |
data[].value2 | string | 否 | 随条件原样保存的补充参数;管理界面将其用于自定义请求头名称或统计匹配项的统计秒数。 | |
enable | integer enum | 否 | 新的启用状态:1 表示启用,0 表示禁用。禁用前会检查当前用户及系统 CC 规则,仍被引用时返回 `cc_match-25`。 | 0 | 1 |
uid | integer(int64) | 否 | 兼容性管理员字段,用作本次名称唯一性和 CC 规则引用检查的用户上下文;仅管理员可传。该字段不会修改匹配器数据库中的所属用户,不能用于转移匹配器。 | |
internal | integer enum | 否 | 兼容性处理标记,1 要求管理员身份并会按内置匹配器流程决定同步任务。该字段不会改写数据库中已有的内置状态,不能用于转换匹配器归类。 | 0 | 1 |
业务结果通过 HTTP 200 返回。目标匹配器更新并提交后返回确认消息;请求体不是对象、匹配器不存在、访问权限不足、名称或匹配条件无效、禁用时仍被引用,以及系统维护或认证失效时返回字符串业务错误码,更新事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,匹配器更新并提交后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 目标匹配器更新成功后返回的确认消息。 | 更新匹配器成功 |
oneOf#1.data | string enum | 是 | 单个匹配器更新成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文请求格式、记录、名称、匹配条件、引用冲突、权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,从 1 开始;省略时为 1。只能传十进制非负整数字符串,非数字值返回 `cc_rule-30`;`limit=0` 时该参数不影响返回范围。 | |
limit | query | integer(int32) | 否 | 每页返回的规则组数量,省略时为 10;传 0 表示不分页并返回全部匹配记录。非数字值返回 `cc_rule-31`。 | |
uid | query | integer(int64) | 否 | 目标用户 ID。未使用 `internal_self` 时按所属用户精确筛选;使用 `internal_self=1` 时作为可见性计算的目标用户。该参数仅管理员可用,普通用户传入时返回 `cc_rule-382`。 | |
internal_self | query | integer | 否 | 传 1 时返回全局内置规则、目标用户自己的规则以及 `show_to` 中包含目标用户 ID 的规则;省略 `uid` 时目标用户为当前登录用户。 | |
internal | query | integer | 否 | 按是否为系统内置规则组精确筛选:1 表示内置,0 表示用户自定义。该筛选条件仅管理员可用,普通用户传入时返回 `cc_rule-383`。 | |
enable | query | integer | 否 | 按启用状态精确筛选:1 表示已启用,0 表示已禁用。 | |
is_show | query | integer | 否 | 按前台显示状态精确筛选:1 表示展示给可见用户,0 表示不在前台选择列表中展示。 | |
id | query | integer(int64) | 否 | 按 CC 规则组 ID 精确筛选;系统保留的 10020 号记录即使匹配也不会返回。 | |
name | query | string | 否 | 按规则组名称进行包含匹配。 | |
请求通过 HTTP 200 返回。成功时给出符合可见性及筛选条件的总数和当前页规则组列表;普通用户指定目标用户或筛选内置状态、页码或每页数量格式错误、认证失效时,通过字符串 `code` 和 `msg` 返回业务错误。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,列表查询成功时固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 符合可见性及筛选条件的规则组总数,不受当前页 `limit` 限制。 | |
oneOf#1.data | array | 是 | 当前页的 CC 规则组记录,按排序值升序、相同排序值按创建时间倒序排列。 | |
oneOf#1.data | array<object> | 否 | 当前页的 CC 规则组记录,按排序值升序、相同排序值按创建时间倒序排列。 | |
oneOf#1.data[].id | integer(int64) | 是 | CC 规则组的唯一 ID。 | |
oneOf#1.data[].sort | integer(int32) | 是 | 规则组排序值,数值越小越靠前。 | |
oneOf#1.data[].uid | integer(int64) | 是 | 规则组所属用户的 ID;不归属于具体用户的系统内置规则可为 null。 | |
oneOf#1.data[].c.uid | integer(int64) | 是 | 查询结果中因再次选择所属用户列而生成的重复字段,值与 `uid` 相同;系统内置规则可为 null。 | |
oneOf#1.data[].name | string | 是 | 规则组名称,同一用户下不可重名。 | |
oneOf#1.data[].des | string | 是 | 规则组备注,可为空字符串。 | |
oneOf#1.data[].data | string | 是 | 序列化后的规则步骤 JSON 数组。每步包含执行模式、匹配器 ID、动作、启用状态、第一过滤器 ID,并可包含第二过滤器及用于界面显示的名称。 | |
oneOf#1.data[].show_to | string | 是 | 允许看到该规则组的用户 ID 列表,多个 ID 使用英文逗号分隔;空字符串表示未指定定向用户,内置规则此时对所有用户全局可见。 | |
oneOf#1.data[].create_at | string | 是 | 数据库返回的规则组创建时间;历史记录未保存时间时为 null。 | |
oneOf#1.data[].update_at | string | 是 | 数据库返回的规则组最后更新时间;历史记录未保存时间时为 null。 | |
oneOf#1.data[].internal | integer enum | 是 | 是否为系统内置规则组:1 表示内置,0 表示用户自定义。 | 0 | 1 |
oneOf#1.data[].enable | integer enum | 是 | 规则组启用状态:1 表示启用,0 表示禁用。 | 0 | 1 |
oneOf#1.data[].is_show | integer enum | 是 | 前台显示状态:1 表示展示,0 表示隐藏。 | 0 | 1 |
oneOf#1.data[].task_id | integer(int64) | 是 | 最近一次规则组同步或删除任务的 ID;没有关联任务时为 null。 | |
oneOf#1.data[].version | integer(int64) | 是 | 规则组配置版本号,每次更新时递增。 | |
oneOf#1.data[].state | string | 是 | 关联任务的当前状态;规则组没有关联任务时为 null。 | |
oneOf#1.data[].create_at2 | string | 是 | 格式化为 `YYYY-MM-DD HH:mm:ss` 的创建时间;原始创建时间为 null 时也为 null。 | |
oneOf#1.data[].update_at2 | string | 是 | 格式化为 `YYYY-MM-DD HH:mm:ss` 的最后更新时间;原始更新时间为 null 时也为 null。 | |
oneOf#1.data[].username | string | 是 | 规则组所属用户的名称;不归属于具体用户的系统内置规则为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文参数、权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
POST /v1/cc-rules
为当前登录用户创建一个 CC 规则组,创建前会按当前账号的网站数量和系统配置检查站点关联对象配额;同一所属用户下规则组名称不可重复。普通用户只能创建归属于自己的自定义规则组,管理员可指定所属用户、创建系统内置规则或设置定向可见用户。每个规则步骤必须指定执行模式、动作、已启用的匹配器和第一过滤器,可选第二过滤器;步骤数量不得超过运行时配置 `cc-rule-max-limit`,初始安装值为 5。记录创建成功后会立即创建节点同步任务,规则组可按请求以启用或禁用状态创建。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
internal | query | integer | 否 | 兼容性权限检查参数。传 1 时要求管理员身份,否则返回 `cc_rule-377`;该查询参数本身不会把新规则组标记为内置,创建内置规则应在 JSON 对象中传 `internal: 1`。 | |
请求体必填。
Content-Type:application/json
创建 CC 规则组的 JSON 对象;未识别的顶层字段不会参与创建逻辑。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 是 | 规则组名称;服务端会过滤可执行的 HTML 内容,且要求处理后的名称非空、在所属用户下唯一。 | |
sort | oneOf | 否 | 规则组排序值,数值越小越靠前;接受非负整数或仅含十进制数字的字符串,省略时为 100。 | |
sort(oneOf#1) | integer | 否 | | |
sort(oneOf#2) | string | 否 | | |
des | string | 否 | 规则组备注;服务端会过滤可执行的 HTML 内容,省略时保存为空字符串。 | |
data | array | 是 | 按顺序执行的 CC 规则步骤数组,可为空数组;元素数量不得超过系统配置 `cc-rule-max-limit`,初始安装值为 5。 | |
data | array<object> | 否 | 按顺序执行的 CC 规则步骤数组,可为空数组;元素数量不得超过系统配置 `cc-rule-max-limit`,初始安装值为 5。 | |
data[].mode | string enum | 是 | 步骤命中后的流程模式:`break` 表示执行后结束该规则组,`continue` 表示继续评估后续步骤。 | break | continue |
data[].action | string enum | 是 | 步骤动作:`block` 执行所选过滤器防护,`log` 记录命中行为。 | block | log |
data[].matcher | oneOf | 是 | 用于判断该步骤是否命中的 CC 匹配器 ID;接受整数或数字字符串,目标匹配器必须存在且处于启用状态,服务端最终保存为字符串。 | |
data[].matcher(oneOf#1) | integer | 否 | | |
data[].matcher(oneOf#2) | string | 否 | | |
data[].filter1 | oneOf | 是 | 步骤使用的第一 CC 过滤器 ID;接受整数或数字字符串,目标过滤器必须存在且处于启用状态,服务端最终保存为字符串。 | |
data[].filter1(oneOf#1) | integer | 否 | | |
data[].filter1(oneOf#2) | string | 否 | | |
data[].filter2 | oneOf | 否 | 可选的第二 CC 过滤器 ID;省略或空字符串表示不使用第二过滤器,非空时必须是已启用过滤器的整数或数字字符串。 | |
data[].filter2(oneOf#1) | integer | 否 | | |
data[].filter2(oneOf#2) | string | 否 | | |
data[].state | oneOf | 否 | 该规则步骤是否启用;省略时为 true,也接受 0 或 1。 | |
data[].state(oneOf#1) | boolean | 否 | | |
data[].state(oneOf#2) | integer | 否 | | |
data[].matcher_name | string | 否 | 匹配器名称快照,仅供界面展示;服务端不据此查找匹配器,会与步骤一起原样保存。 | |
data[].filter1_name | string | 否 | 第一过滤器名称快照,仅供界面展示;服务端不据此查找过滤器,会与步骤一起原样保存。 | |
data[].filter2_name | string | 否 | 第二过滤器名称快照,仅供界面展示;没有第二过滤器时通常为空字符串。 | |
show_to | oneOf | 否 | 允许看到该规则组的用户 ID,多个 ID 使用英文逗号分隔;空字符串表示未指定定向用户。仅管理员可设置,每个 ID 都必须对应现有用户。 | |
show_to(oneOf#1) | integer | 否 | | |
show_to(oneOf#2) | string | 否 | | |
uid | integer(int64) | 否 | 新规则组所属用户的 ID;省略时为当前登录用户,仅管理员可指定该字段,否则返回 `cc_rule-378`。 | |
internal | oneOf | 否 | 是否创建为系统内置规则组:true 或 1 表示内置,false 或 0 表示用户自定义;省略时为 0,创建内置规则要求管理员身份。 | |
internal(oneOf#1) | boolean | 否 | | |
internal(oneOf#2) | integer | 否 | | |
enable | oneOf | 否 | 规则组初始启用状态;true 或 1 表示启用,false 或 0 表示禁用,省略时启用。 | |
enable(oneOf#1) | boolean | 否 | | |
enable(oneOf#2) | integer | 否 | | |
is_show | oneOf | 否 | 规则组初始前台显示状态;true 或 1 表示展示,false 或 0 表示隐藏,省略时展示。 | |
is_show(oneOf#1) | boolean | 否 | | |
is_show(oneOf#2) | integer | 否 | |
业务结果通过 HTTP 200 返回。规则组、关联同步任务创建并提交后返回新规则组 ID;配额、名称、排序、步骤数量或结构、模式、动作、匹配器、过滤器、步骤状态、定向用户、启用/显示状态、管理员专属字段、系统维护或认证校验失败时返回字符串业务错误码,事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,规则组及同步任务创建并提交后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | CC 规则组创建成功后返回的确认消息。 | cc规则添加成功 |
oneOf#1.data | integer(int64) | 是 | 数据库为新 CC 规则组生成的唯一 ID。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文配额、字段、规则步骤、引用对象、可见性、权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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`。数组中任一对象失败时整个事务回滚。 | |
[].id | oneOf | 是 | 要更新的 CC 规则组 ID;接受正整数或仅含十进制数字的字符串。记录必须存在,普通用户只能操作归属于自己的非系统规则组。 | |
[].id(oneOf#1) | integer | 否 | | |
[].id(oneOf#2) | string | 否 | | |
[].name | string | 否 | 新的规则组名称;服务端会过滤可执行的 HTML 内容,处理后不得为空,并且在校验所属用户下不可与其他规则组重名。省略时保持原名称。 | |
[].sort | oneOf | 否 | 新的排序值,数值越小越靠前;接受非负整数或仅含十进制数字的字符串,省略时保持原值。 | |
[].sort(oneOf#1) | integer | 否 | | |
[].sort(oneOf#2) | string | 否 | | |
[].des | string | 否 | 新的规则组备注;服务端会过滤可执行的 HTML 内容,可传空字符串清空备注,省略时保持原值。 | |
[].data | array | 否 | 替换当前完整规则步骤的数组,可为空数组;元素数量不得超过运行时配置 `cc-rule-max-limit`,初始安装值为 5。若规则组已启用且正被网站使用,修改步骤会创建节点同步任务。 | |
[].data | array<object> | 否 | 替换当前完整规则步骤的数组,可为空数组;元素数量不得超过运行时配置 `cc-rule-max-limit`,初始安装值为 5。若规则组已启用且正被网站使用,修改步骤会创建节点同步任务。 | |
[].data[].mode | string enum | 是 | 步骤命中后的流程模式:`break` 表示执行后结束该规则组,`continue` 表示继续评估后续步骤。 | break | continue |
[].data[].action | string enum | 是 | 步骤动作:`block` 执行所选过滤器防护,`log` 记录命中行为。 | block | log |
[].data[].matcher | oneOf | 是 | 用于判断该步骤是否命中的 CC 匹配器 ID;接受整数或数字字符串,目标匹配器必须存在且处于启用状态,服务端最终保存为字符串。 | |
[].data[].matcher(oneOf#1) | integer | 否 | | |
[].data[].matcher(oneOf#2) | string | 否 | | |
[].data[].filter1 | oneOf | 是 | 步骤使用的第一 CC 过滤器 ID;接受整数或数字字符串,目标过滤器必须存在且处于启用状态,服务端最终保存为字符串。 | |
[].data[].filter1(oneOf#1) | integer | 否 | | |
[].data[].filter1(oneOf#2) | string | 否 | | |
[].data[].filter2 | oneOf | 否 | 可选的第二 CC 过滤器 ID;省略或空字符串表示不使用第二过滤器,非空时必须是已启用过滤器的整数或数字字符串。 | |
[].data[].filter2(oneOf#1) | integer | 否 | | |
[].data[].filter2(oneOf#2) | string | 否 | | |
[].data[].state | oneOf | 否 | 该规则步骤是否启用;省略时为 true,也接受 0 或 1。 | |
[].data[].state(oneOf#1) | boolean | 否 | | |
[].data[].state(oneOf#2) | integer | 否 | | |
[].data[].matcher_name | string | 否 | 匹配器名称快照,仅供界面展示;服务端不据此查找匹配器,会与步骤一起原样保存。 | |
[].data[].filter1_name | string | 否 | 第一过滤器名称快照,仅供界面展示;服务端不据此查找过滤器,会与步骤一起原样保存。 | |
[].data[].filter2_name | string | 否 | 第二过滤器名称快照,仅供界面展示;没有第二过滤器时通常为空字符串。 | |
[].show_to | oneOf | 否 | 新的定向可见用户 ID,多个 ID 使用英文逗号分隔;空字符串表示不指定定向用户。仅管理员可修改,每个 ID 都必须对应现有用户。 | |
[].show_to(oneOf#1) | integer | 否 | | |
[].show_to(oneOf#2) | string | 否 | | |
[].uid | integer(int64) | 否 | 兼容性管理员字段,用作本次名称唯一性校验的用户上下文;仅管理员可传。该字段不会修改规则组数据库中的所属用户,不能用于转移规则组。 | |
[].internal | oneOf | 否 | 兼容性处理标记;1 或 true 要求管理员身份,并会按系统规则流程决定同步任务。该字段不会改写已有规则组的系统内置状态,不能用于转换规则组类型。 | |
[].internal(oneOf#1) | boolean | 否 | | |
[].internal(oneOf#2) | integer | 否 | | |
[].enable | oneOf | 否 | 新的启用状态:true 或 1 表示启用,false 或 0 表示禁用。禁用前要求规则组未被网站或任何默认配置引用,且 ID 不得小于 10020;满足条件后会为非系统规则创建节点删除任务。 | |
[].enable(oneOf#1) | boolean | 否 | | |
[].enable(oneOf#2) | integer | 否 | | |
[].is_show | oneOf | 否 | 新的前台显示状态:true 或 1 表示展示,false 或 0 表示隐藏;省略时保持原值。 | |
[].is_show(oneOf#1) | boolean | 否 | | |
[].is_show(oneOf#2) | integer | 否 | |
业务结果通过 HTTP 200 返回。全部规则组更新并提交后返回确认消息;请求体格式、规则组 ID、访问权限、名称、排序、规则步骤、引用的匹配器或过滤器、定向用户、启用/显示状态、禁用前引用检查、系统维护或认证校验失败时返回字符串业务错误码,整个批次事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,整个批次更新并提交后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 所有规则组更新成功后返回的确认消息。 | 更新cc规则成功 |
oneOf#1.data | string enum | 是 | 批量更新成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文请求格式、目标记录、字段校验、规则步骤、引用关系、禁用限制、访问权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
DELETE /v1/cc-rules/{rule_id}
删除路径中指定的一个或多个 CC 规则组,多个 ID 使用英文逗号分隔并在同一个数据库事务中处理。普通用户只能删除归属于自己的自定义规则组,管理员可以删除系统内置规则组及其他用户的规则组。每个目标必须已经禁用;如果仍有关联的同步或删除任务,该任务状态必须为 `done`。任一 ID 格式错误、记录不存在、越权、仍启用或任务未完成时,整个批次回滚,不会保留部分删除结果。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
rule_id | path | string | 是 | 要删除的 CC 规则组 ID;删除多个规则组时按 `10021,10022` 形式使用英文逗号连接,每一段都必须是十进制数字。 | |
业务结果通过 HTTP 200 返回。全部目标通过检查、删除并提交后返回确认消息;ID 格式、记录存在性、权限、启用状态或关联任务状态不符合要求,以及系统维护或认证失效时返回字符串业务错误码,整个批次事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,所有目标规则组删除并提交后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 整个删除批次成功提交后返回的确认消息。 | cc规则删除成功 |
oneOf#1.data | string enum | 是 | 删除成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文 ID、记录、状态、权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/cc-rules/{rule_id}
按 ID 获取一条 CC 规则组的原始配置记录。系统内置规则组仅管理员身份可以读取;用户自定义规则组仅允许其所属用户读取,管理员身份本身不会绕过自定义规则组的所有者校验。返回的是 `cc_rule` 记录本身,不包含列表接口联表得到的任务状态、用户名或格式化时间字段;`data` 为序列化后的规则步骤 JSON 字符串,使用前需要再次解析。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
rule_id | path | integer(int64) | 是 | 要查询的 CC 规则组 ID;路由只接受十进制整数。 | |
业务结果通过 HTTP 200 返回。规则组存在且当前身份有读取权限时返回完整原始配置;记录不存在、读取系统内置规则组时不是管理员、读取其他用户的自定义规则组或认证失效时返回字符串业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,规则组详情读取成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 详情读取成功时没有附加提示,固定为空字符串。 | |
oneOf#1.data | object | 是 | 数据库中的 CC 规则组原始配置记录。 | |
oneOf#1.data.id | integer(int64) | 是 | CC 规则组的唯一 ID。 | |
oneOf#1.data.sort | integer(int32) | 是 | 规则组排序值,数值越小越靠前。 | |
oneOf#1.data.uid | integer(int64) | 是 | 规则组所属用户的 ID;历史或系统内置记录不归属于具体用户时可能为 null。 | |
oneOf#1.data.name | string | 是 | 规则组名称,同一所属用户下不可重名。 | |
oneOf#1.data.des | string | 是 | 规则组备注,可为空字符串。 | |
oneOf#1.data.data | string | 是 | 序列化后的规则步骤 JSON 数组。每个步骤包含 `mode`、`action`、`matcher`、`filter1`,并可包含 `filter2`、`state` 及界面展示用名称;客户端需要再次进行 JSON 解析。 | |
oneOf#1.data.show_to | string | 是 | 允许看到该规则组的定向用户 ID,多个 ID 使用英文逗号分隔;空字符串表示未指定定向用户。 | |
oneOf#1.data.create_at | string | 是 | 数据库返回的规则组创建时间;历史记录未保存时间时为 null。 | |
oneOf#1.data.update_at | string | 是 | 数据库返回的规则组最后更新时间;历史记录未保存时间时为 null。 | |
oneOf#1.data.internal | integer enum | 是 | 是否为系统内置规则组:1 表示内置,0 表示用户自定义。 | 0 | 1 |
oneOf#1.data.enable | integer enum | 是 | 规则组启用状态:1 表示启用,0 表示禁用。 | 0 | 1 |
oneOf#1.data.is_show | integer enum | 是 | 规则组前台显示状态:1 表示展示,0 表示隐藏。 | 0 | 1 |
oneOf#1.data.task_id | integer(int64) | 是 | 最近一次规则组同步或删除任务的 ID;没有关联任务时为 null。 | |
oneOf#1.data.version | integer(int64) | 是 | 规则组配置版本号,每次更新时递增。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文记录不存在、所有权、管理员权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
PUT /v1/cc-rules/{rule_id}
按路径 ID 更新一条 CC 规则组。请求体必须是 JSON 对象,路径中的 `rule_id` 是唯一目标标识;即使请求体包含 `id`,服务端也会用路径 ID 覆盖。名称、排序、备注、规则步骤、定向可见用户、启用状态和前台显示状态均为可选字段,只更新明确提供的字段。普通用户只能更新归属于自己的自定义规则组,管理员可更新其他用户或系统内置规则组。传入空对象也会递增版本号并刷新更新时间。修改已启用且被网站使用的规则步骤会创建节点同步任务;禁用前必须确认规则组未被网站、全局默认值、用户默认值、防火墙默认页规则或自动规则切换引用,禁用成功时会创建节点删除任务。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
rule_id | path | integer(int64) | 是 | 要更新的 CC 规则组 ID;路由只接受十进制整数,并会覆盖请求体中可能存在的 `id`。 | |
请求体必填。
Content-Type:application/json
指定规则组的部分更新对象,可为空对象;请求体中的 `id` 和未识别字段不会决定目标或写入规则组记录。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 否 | 新的规则组名称;服务端会过滤可执行的 HTML 内容,处理后不得为空,并且在校验所属用户下不可与其他规则组重名。省略时保持原名称。 | |
sort | oneOf | 否 | 新的排序值,数值越小越靠前;接受非负整数或仅含十进制数字的字符串,省略时保持原值。 | |
sort(oneOf#1) | integer | 否 | | |
sort(oneOf#2) | string | 否 | | |
des | string | 否 | 新的规则组备注;服务端会过滤可执行的 HTML 内容,可传空字符串清空备注,省略时保持原值。 | |
data | array | 否 | 替换当前完整规则步骤的数组,可为空数组;元素数量不得超过运行时配置 `cc-rule-max-limit`,初始安装值为 5。若规则组已启用且正被网站使用,修改步骤会创建节点同步任务。 | |
data | array<object> | 否 | 替换当前完整规则步骤的数组,可为空数组;元素数量不得超过运行时配置 `cc-rule-max-limit`,初始安装值为 5。若规则组已启用且正被网站使用,修改步骤会创建节点同步任务。 | |
data[].mode | string enum | 是 | 步骤命中后的流程模式:`break` 表示执行后结束该规则组,`continue` 表示继续评估后续步骤。 | break | continue |
data[].action | string enum | 是 | 步骤动作:`block` 执行所选过滤器防护,`log` 记录命中行为。 | block | log |
data[].matcher | oneOf | 是 | 用于判断该步骤是否命中的 CC 匹配器 ID;接受整数或数字字符串,目标匹配器必须存在且处于启用状态,服务端最终保存为字符串。 | |
data[].matcher(oneOf#1) | integer | 否 | | |
data[].matcher(oneOf#2) | string | 否 | | |
data[].filter1 | oneOf | 是 | 步骤使用的第一 CC 过滤器 ID;接受整数或数字字符串,目标过滤器必须存在且处于启用状态,服务端最终保存为字符串。 | |
data[].filter1(oneOf#1) | integer | 否 | | |
data[].filter1(oneOf#2) | string | 否 | | |
data[].filter2 | oneOf | 否 | 可选的第二 CC 过滤器 ID;省略或空字符串表示不使用第二过滤器,非空时必须是已启用过滤器的整数或数字字符串。 | |
data[].filter2(oneOf#1) | integer | 否 | | |
data[].filter2(oneOf#2) | string | 否 | | |
data[].state | oneOf | 否 | 该规则步骤是否启用;省略时为 true,也接受 0 或 1。 | |
data[].state(oneOf#1) | boolean | 否 | | |
data[].state(oneOf#2) | integer | 否 | | |
data[].matcher_name | string | 否 | 匹配器名称快照,仅供界面展示;服务端不据此查找匹配器,会与步骤一起原样保存。 | |
data[].filter1_name | string | 否 | 第一过滤器名称快照,仅供界面展示;服务端不据此查找过滤器,会与步骤一起原样保存。 | |
data[].filter2_name | string | 否 | 第二过滤器名称快照,仅供界面展示;没有第二过滤器时通常为空字符串。 | |
show_to | oneOf | 否 | 新的定向可见用户 ID,多个 ID 使用英文逗号分隔;空字符串表示不指定定向用户。仅管理员可修改,每个 ID 都必须对应现有用户。 | |
show_to(oneOf#1) | integer | 否 | | |
show_to(oneOf#2) | string | 否 | | |
uid | integer(int64) | 否 | 兼容性管理员字段,用作本次名称唯一性校验的用户上下文;仅管理员可传。该字段不会修改规则组数据库中的所属用户,不能用于转移规则组。 | |
internal | oneOf | 否 | 兼容性处理标记;1 或 true 要求管理员身份,并会按系统规则流程决定同步任务。该字段不会改写已有规则组的系统内置状态,不能用于转换规则组类型。 | |
internal(oneOf#1) | boolean | 否 | | |
internal(oneOf#2) | integer | 否 | | |
enable | oneOf | 否 | 新的启用状态:true 或 1 表示启用,false 或 0 表示禁用。禁用前要求规则组未被网站或任何默认配置引用,且 ID 不得小于 10020;满足条件后会为非系统规则创建节点删除任务。 | |
enable(oneOf#1) | boolean | 否 | | |
enable(oneOf#2) | integer | 否 | | |
is_show | oneOf | 否 | 新的前台显示状态:true 或 1 表示展示,false 或 0 表示隐藏;省略时保持原值。 | |
is_show(oneOf#1) | boolean | 否 | | |
is_show(oneOf#2) | integer | 否 | |
业务结果通过 HTTP 200 返回。目标规则组更新并提交后返回确认消息;请求体格式、目标记录、访问权限、名称、排序、规则步骤、引用的匹配器或过滤器、定向用户、启用/显示状态、禁用前引用检查、系统维护或认证校验失败时返回字符串业务错误码,事务回滚。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,规则组更新并提交后固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 规则组更新成功后返回的确认消息。 | 更新cc规则成功 |
oneOf#1.data | string enum | 是 | 更新成功时没有额外业务数据,固定为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 与业务错误码对应的中文请求格式、目标记录、字段校验、规则步骤、引用关系、禁用限制、访问权限、维护状态或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
本组包含以下接口,点击卡片进入详情。
可购买套餐、套餐分组和升级包。
GET /v1/package-groups
分页查询套餐组,并按排序值升序返回。普通登录用户仅能看到 `enable` 为 1 的套餐组;管理员可查看全部套餐组。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer | 否 | 页码,必须为非负数字字符串或数字;默认 1。 | 1 |
limit | query | integer | 否 | 每页返回条数,必须为非负数字;默认 10。传 0 时不使用分页限制。 | 10 |
查询成功时不含 `msg` 字段;参数或认证错误仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.count | integer | 是 | 筛选后的套餐组总数,未受分页影响。 | 2 |
oneOf#1.data | array | 是 | 当前页套餐组记录,按 `sort` 升序排列。 | |
oneOf#1.data | array<object> | 否 | 当前页套餐组记录,按 `sort` 升序排列。 | |
oneOf#1.data[].id | integer | 是 | 套餐组 ID。 | |
oneOf#1.data[].name | string | 是 | 套餐组名称。 | |
oneOf#1.data[].des | string | 是 | 套餐组备注。 | |
oneOf#1.data[].sort | integer | 是 | 展示排序值,数值越小越靠前。 | |
oneOf#1.data[].enable | integer enum | 是 | 是否启用:1 为启用,0 为停用。 | 0 | 1 |
oneOf#1.data[].create_at | string | 是 | 创建时间,由数据库日期时间字段序列化返回。 | |
oneOf#1.data[].update_at | string | 是 | 最后更新时间,由数据库日期时间字段序列化返回;新建记录可能为 null。 | |
oneOf#2.code | string enum | 是 | 页码/分页条数格式错误或未登录时的业务错误码。 | package_group-4 | package_group-5 | login_required |
oneOf#2.msg | string | 是 | 错误原因。 | page参数格式不正确 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
POST /v1/package-groups
以管理员身份创建套餐组。套餐组名称在系统内必须唯一;未提供的备注保存为空字符串,排序默认 100,启用状态默认启用。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 是 | 套餐组名称,不能为空且必须唯一。 | 标准套餐 |
des | string | 否 | 套餐组备注;未传时保存为空字符串。 | 适用于普通网站 |
sort | integer | 否 | 展示排序值;未传或传空值时为 100,数值越小越靠前。 | 100 |
enable | integer enum | 否 | 是否启用:1 为启用,0 为停用;未传时为 1。 | 1 |
套餐组创建成功,`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.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 套餐组添加成功 |
oneOf#1.data | integer | 是 | 新创建套餐组的自增 ID。 | 3 |
oneOf#2.code | string | 是 | 业务错误码。 | package_group-11 |
oneOf#2.msg | string | 是 | 错误原因。 | 套餐组名称 标准套餐已存在 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
DELETE /v1/package-groups/{group_id}
以管理员身份删除一个或多个套餐组。路径参数支持英文逗号分隔多个套餐组 ID;每个套餐组必须存在且未关联任何套餐,任一校验失败都会回滚本次删除。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
group_id | path | string | 是 | 一个套餐组 ID,或以英文逗号分隔的多个套餐组 ID。 | 3,4 |
套餐组删除成功。 未登录、维护模式限制、非管理员、套餐组不存在或套餐组仍关联套餐时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package_group-17`、`package_group-1` 或 `package_group-2`。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 套餐组删除成功 |
oneOf#1.data | string | 是 | 该操作未返回已删除的套餐组数据。 | |
oneOf#2.code | string | 是 | 业务错误码。 | package_group-2 |
oneOf#2.msg | string | 是 | 错误原因。 | 当前套餐组已有套餐,请先移除再操作 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
GET /v1/package-groups/{group_id}
按 ID 获取套餐组详情。接口仅要求登录,查询时不按 `enable` 过滤,因此普通用户也可读取已停用套餐组的详情。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
group_id | path | integer | 是 | 套餐组 ID。 | 3 |
成功、未登录和套餐组不存在均返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 成功时为空字符串。 | |
oneOf#1.data | object | 是 | 套餐组记录。 | |
oneOf#1.data.id | integer | 是 | 套餐组 ID。 | |
oneOf#1.data.name | string | 是 | 套餐组名称。 | |
oneOf#1.data.des | string | 是 | 套餐组备注。 | |
oneOf#1.data.sort | integer | 是 | 展示排序值。 | |
oneOf#1.data.enable | integer enum | 是 | 是否启用:1 为启用,0 为停用。 | 0 | 1 |
oneOf#1.data.create_at | string | 是 | 创建时间,由数据库日期时间字段序列化返回。 | |
oneOf#1.data.update_at | string | 是 | 最后更新时间,由数据库日期时间字段序列化返回;可能为 null。 | |
oneOf#2.code | string enum | 是 | 套餐组不存在或未登录时的业务错误码。 | package_group-3 | login_required |
oneOf#2.msg | string | 是 | 错误原因。 | 套餐组不存在 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
PUT /v1/package-groups/{group_id}
以管理员身份更新套餐组。路径中的套餐组 ID 会覆盖请求体中的同名字段;未提供的字段保持原值,至少应提交一个与原值不同的字段。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
group_id | path | integer | 是 | 要更新的套餐组 ID。 | 3 |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 否 | 套餐组名称;传入时不能为空且必须与其他套餐组名称不同。 | 标准套餐(新版) |
des | string | 否 | 套餐组备注;允许传空字符串清空。 | 适用于普通网站 |
sort | integer | 否 | 展示排序值;传空值时更新为 100,数值越小越靠前。 | 80 |
enable | integer enum | 否 | 是否启用:1 为启用,0 为停用。 | 1 |
套餐组更新成功。 鉴权或字段校验失败时仍返回 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.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 更新套餐组成功 |
oneOf#1.data | string | 是 | 该操作未返回更新后的套餐组对象。 | |
oneOf#2.code | string | 是 | 业务错误码。 | package_group-14 |
oneOf#2.msg | string | 是 | 错误原因。 | 数据未更改 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
GET /v1/package-ups
分页查询套餐升级规则,按升级包 ID 倒序返回。普通用户仅能看到已启用的规则:未传 `upid` 时只返回未绑定基础套餐的规则,传入 `upid` 时返回未绑定规则及绑定到该用户套餐所用基础套餐的规则。管理员可查看全部,并可用 `enable` 筛选。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer | 否 | 页码,必须为数字;默认 1。 | 1 |
limit | query | integer | 否 | 每页条数,必须为数字;默认 10。传 0 时不分页。 | 10 |
enable | query | integer | 否 | 仅管理员有效:按是否启用筛选。普通用户始终只查询启用规则。 | 1 |
upid | query | integer | 否 | 仅普通用户使用的用户套餐 ID。传入后依据该用户套餐的基础套餐匹配可用升级规则;未传或为空时仅返回未绑定基础套餐的规则。管理员忽略此参数。 | 101 |
查询成功时不含 `msg` 字段;参数或认证错误仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.count | integer | 是 | 筛选后的升级规则总数,未受分页影响。 | 1 |
oneOf#1.data | array | 是 | 当前页升级规则。 | |
oneOf#1.data | array<object> | 否 | 当前页升级规则。 | |
oneOf#1.data[].id | integer | 是 | 升级规则 ID。 | |
oneOf#1.data[].name | string | 是 | 升级规则名称。 | |
oneOf#1.data[].des | string | 是 | 升级规则备注。 | |
oneOf#1.data[].type | string enum | 是 | 可升级的资源类型。 | traffic | domain | main_domain | http_port | stream_port | custom_cc_rule |
oneOf#1.data[].amount | integer | 是 | 本规则增加的资源数量;自定义 CC 规则类型固定为 1。 | |
oneOf#1.data[].bind_package | string | 是 | 可使用该规则的基础套餐 ID 列表,使用英文逗号分隔;空字符串表示不限制基础套餐。 | |
oneOf#1.data[].price | integer | 是 | 升级价格,以系统最小货币单位保存。 | |
oneOf#1.data[].create_at | string | 是 | 创建时间,由数据库日期时间字段序列化返回。 | |
oneOf#1.data[].update_at | string | 是 | 最后更新时间,由数据库日期时间字段序列化返回。 | |
oneOf#1.data[].enable | integer enum | 是 | 是否启用:1 为启用,0 为停用。 | 0 | 1 |
oneOf#1.data[].create_at2 | string | 是 | 格式化创建时间,格式为 `YYYY-MM-DD HH:mm:ss`。 | |
oneOf#2.code | string enum | 是 | 页码/分页条数格式错误、用户套餐不存在或未登录时的业务错误码。 | package_up-21 | package_up-22 | package_up-26 | login_required |
oneOf#2.msg | string | 是 | 错误原因。 | upid:101不存在 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
POST /v1/package-ups
以管理员身份创建套餐升级规则。名称必须唯一;普通资源类型必须提供增加数量,`custom_cc_rule` 类型的数量由服务端强制设为 1。金额以系统最小货币单位保存。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.name | string | 是 | 升级规则名称,不能为空且必须唯一。 | |
oneOf#1.des | string | 否 | 升级规则备注;服务端会进行 XSS 过滤,未传时保存为空字符串。 | |
oneOf#1.type | string enum | 是 | 要增加的资源类型。 | traffic | domain | main_domain | http_port | stream_port |
oneOf#1.amount | integer | 是 | 增加的资源数量,必须为非负整数。 | |
oneOf#1.bind_package | string | 否 | 可使用该规则的基础套餐 ID 列表,以英文逗号分隔;未传或空字符串表示不限制基础套餐。 | |
oneOf#1.price | integer | 是 | 升级价格,必须为非负整数,单位为系统最小货币单位。 | |
oneOf#1.enable | integer enum | 否 | 是否启用:1 为启用,0 为停用;未传时为 1。 | 0 | 1 |
oneOf#2.name | string | 是 | 升级规则名称,不能为空且必须唯一。 | |
oneOf#2.des | string | 否 | 升级规则备注;服务端会进行 XSS 过滤,未传时保存为空字符串。 | |
oneOf#2.type | string enum | 是 | 增加自定义 CC 规则数量。 | custom_cc_rule |
oneOf#2.amount | integer | 否 | 可省略;服务端会忽略传值并固定保存为 1。 | |
oneOf#2.bind_package | string | 否 | 可使用该规则的基础套餐 ID 列表,以英文逗号分隔;未传或空字符串表示不限制基础套餐。 | |
oneOf#2.price | integer | 是 | 升级价格,必须为非负整数,单位为系统最小货币单位。 | |
oneOf#2.enable | integer enum | 否 | 是否启用:1 为启用,0 为停用;未传时为 1。 | 0 | 1 |
升级规则创建成功,`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.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 升级包添加成功 |
oneOf#1.data | integer | 是 | 新创建升级规则的自增 ID。 | 8 |
oneOf#2.code | string | 是 | 业务错误码。 | package_up-25 |
oneOf#2.msg | string | 是 | 错误原因。 | 指定的套餐id:11不存在 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
DELETE /v1/package-ups/{package_id}
以管理员身份删除一个或多个套餐升级规则。路径参数支持英文逗号分隔多个规则 ID;每条规则必须存在且未被任何用户套餐升级记录引用,任一检查失败都会回滚本次操作。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | string | 是 | 一个升级规则 ID,或以英文逗号分隔的多个升级规则 ID。 | 8,9 |
升级规则删除成功。 未登录、维护模式限制、非管理员、规则不存在或规则仍在使用时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package_up-28`、`package_up-1` 或 `package_up-2`。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 升级包删除成功 |
oneOf#1.data | string | 是 | 该操作未返回已删除规则的数据。 | |
oneOf#2.code | string | 是 | 业务错误码。 | package_up-2 |
oneOf#2.msg | string | 是 | 错误原因;在用时会包含引用记录 ID。 | 此升级包已经在用,user_package_up id301 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
GET /v1/package-ups/{package_id}
按 ID 获取套餐升级规则详情。任何登录用户都可读取启用规则;停用规则仅管理员可读取。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 升级规则 ID。 | 8 |
成功、未登录、停用规则无权访问及规则不存在均返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 成功时为空字符串。 | |
oneOf#1.data | object | 是 | 升级规则记录。 | |
oneOf#1.data.id | integer | 是 | 升级规则 ID。 | |
oneOf#1.data.name | string | 是 | 升级规则名称。 | |
oneOf#1.data.des | string | 是 | 升级规则备注。 | |
oneOf#1.data.type | string enum | 是 | 可升级的资源类型。 | traffic | domain | main_domain | http_port | stream_port | custom_cc_rule |
oneOf#1.data.amount | integer | 是 | 增加的资源数量。 | |
oneOf#1.data.bind_package | string | 是 | 可使用该规则的基础套餐 ID 列表,使用英文逗号分隔;空字符串表示不限制。 | |
oneOf#1.data.price | integer | 是 | 升级价格,单位为系统最小货币单位。 | |
oneOf#1.data.create_at | string | 是 | 创建时间,由数据库日期时间字段序列化返回。 | |
oneOf#1.data.update_at | string | 是 | 最后更新时间,由数据库日期时间字段序列化返回。 | |
oneOf#1.data.enable | integer enum | 是 | 是否启用:1 为启用,0 为停用。 | 0 | 1 |
oneOf#2.code | string enum | 是 | 规则不存在、读取停用规则时非管理员或未登录时的业务错误码。 | package_up-20 | package_up-30 | login_required |
oneOf#2.msg | string | 是 | 错误原因。 | 需要管理员权限 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
PUT /v1/package-ups/{package_id}
以管理员身份更新一条升级规则。请求体必须是 JSON 对象,路径中的规则 ID 会覆盖请求体 ID。服务端每次都会更新 `update_at`,因此空对象也会成功。注意:传入 `type` 会被校验并参与数量处理,但当前服务端不会将新的 `type` 写入数据库。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 要更新的升级规则 ID。 | 8 |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 否 | 升级规则名称;传入时不能为空、经 XSS 过滤且必须与其他规则名称不同。 | 增加流量包(新版) |
des | string | 否 | 升级规则备注;传入时经 XSS 过滤,可传空字符串清空。 | 增加月流量额度 |
type | string enum | 否 | 资源类型。当前服务端会校验该值,但不会把更新后的类型保存到数据库;传 `custom_cc_rule` 时会把本次的 `amount` 强制设为 1。 | traffic |
amount | integer | 否 | 增加的资源数量;传入时必须为非负整数。若同时传 `type: custom_cc_rule`,服务端固定保存为 1。 | 200 |
bind_package | string | 否 | 可使用该规则的基础套餐 ID 列表,以英文逗号分隔;传入的每个 ID 必须存在,空字符串可清空绑定限制。 | 11,12 |
price | integer | 否 | 升级价格;传入时必须为非负整数,单位为系统最小货币单位。 | 1200 |
enable | integer enum | 否 | 是否启用:1 为启用,0 为停用。 | 1 |
升级规则更新成功。 鉴权、请求体类型或字段校验失败时仍返回 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.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 更新升级包成功 |
oneOf#1.data | string | 是 | 该操作未返回更新后的升级规则对象。 | |
oneOf#2.code | string | 是 | 业务错误码。 | package_up-23 |
oneOf#2.msg | string | 是 | 错误原因。 | 需要字典格式 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
GET /v1/packages
分页查询套餐,按排序值升序返回。普通用户仅能查询已启用的非专属套餐;传 `mine` 时仅查询 `owner` 包含当前用户 ID 的专属套餐。管理员可查看全部,并可按启用状态筛选。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer | 否 | 页码,必须为数字;默认 1。 | 1 |
limit | query | integer | 否 | 每页条数,必须为数字;默认 10。传 0 时不分页。 | 10 |
enable | query | integer | 否 | 仅管理员有效:按是否启用筛选。普通用户固定只查询启用套餐。 | 1 |
group | query | integer | 否 | 套餐组 ID;筛选归属该套餐组的套餐。 | 3 |
region_id | query | integer | 否 | 区域 ID;精确筛选套餐所属区域。 | 1 |
mine | query | string | 否 | 传任意非空值时,仅查询 `owner` 逗号列表包含当前登录用户 ID 的专属套餐;未传时普通用户只查询 `owner` 为空的套餐。 | 1 |
查询成功时不含 `msg` 字段;参数或认证错误仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.count | integer | 是 | 筛选后的套餐总数,未受分页影响。 | 1 |
oneOf#1.data | array | 是 | 当前页套餐记录。 | |
oneOf#1.data | array<object> | 否 | 当前页套餐记录。 | |
oneOf#1.data[].id | integer | 否 | 套餐 ID。 | |
oneOf#1.data[].name | string | 否 | 套餐名称。 | |
oneOf#1.data[].des | string | 否 | 套餐备注。 | |
oneOf#1.data[].region_id | integer | 否 | 所属区域 ID。 | |
oneOf#1.data[].region_name | string | 否 | 所属区域名称。 | |
oneOf#1.data[].node_group_id | integer | 否 | 主线路组 ID。 | |
oneOf#1.data[].node_group_name | string | 否 | 主线路组名称。 | |
oneOf#1.data[].backup_node_group | integer | 否 | 备用线路组 ID。 | |
oneOf#1.data[].backup_node_group_name | string | 否 | 备用线路组名称。 | |
oneOf#1.data[].cname_domain | integer | 否 | CNAME 域名配置 ID。 | |
oneOf#1.data[].cname_hostname2 | string | 否 | 备用 CNAME 主机名。 | |
oneOf#1.data[].cname_mode | string | 否 | CNAME 模式。 | |
oneOf#1.data[].traffic | integer | 否 | 套餐流量额度。 | |
oneOf#1.data[].bandwidth | string | 否 | 带宽限制值。 | |
oneOf#1.data[].connection | integer | 否 | 连接数限制。 | |
oneOf#1.data[].domain | integer | 否 | 可添加域名数量限制。 | |
oneOf#1.data[].main_domain | integer | 否 | 主域名数量限制。 | |
oneOf#1.data[].http_port | integer | 否 | HTTP 端口数量限制。 | |
oneOf#1.data[].stream_port | integer | 否 | 四层转发端口数量限制。 | |
oneOf#1.data[].custom_cc_rule | integer enum | 否 | 是否允许自定义 CC 规则:1 为允许,0 为不允许。 | 0 | 1 |
oneOf#1.data[].websocket | integer enum | 否 | 是否支持 WebSocket:1 为支持,0 为不支持。 | 0 | 1 |
oneOf#1.data[].http3 | integer enum | 否 | 是否支持 HTTP/3:1 为支持,0 为不支持。 | 0 | 1 |
oneOf#1.data[].l2_state | integer enum | 否 | 是否启用二层调度能力:1 为启用,0 为停用。 | 0 | 1 |
oneOf#1.data[].cc_protect | string | 否 | CC 防护能力说明。 | |
oneOf#1.data[].ddos_protect | string | 否 | DDoS 防护能力说明。 | |
oneOf#1.data[].expire | string | 否 | 套餐停售或有效期截止时间,由数据库日期时间字段序列化返回。 | |
oneOf#1.data[].expire2 | string | 否 | 格式化截止时间,格式为 `YYYY-MM-DD HH:mm:ss`。 | |
oneOf#1.data[].buy_num_limit | integer | 否 | 可购买数量限制。 | |
oneOf#1.data[].backend_ip_limit | string | 否 | 源站 IP 限制配置文本。 | |
oneOf#1.data[].id_verify | integer enum | 否 | 是否要求实名认证:1 为要求,0 为不要求。 | 0 | 1 |
oneOf#1.data[].before_exp_days_renew | integer | 否 | 到期前允许续费的提前天数。 | |
oneOf#1.data[].month_price | integer | 否 | 月付价格,单位为系统最小货币单位。 | |
oneOf#1.data[].quarter_price | integer | 否 | 季付价格,单位为系统最小货币单位。 | |
oneOf#1.data[].year_price | integer | 否 | 年付价格,单位为系统最小货币单位。 | |
oneOf#1.data[].create_at | string | 否 | 创建时间,由数据库日期时间字段序列化返回。 | |
oneOf#1.data[].create_at2 | string | 否 | 格式化创建时间,格式为 `YYYY-MM-DD HH:mm:ss`。 | |
oneOf#1.data[].update_at | string | 否 | 最后更新时间,由数据库日期时间字段序列化返回。 | |
oneOf#1.data[].sort | integer | 否 | 展示排序值,数值越小越靠前。 | |
oneOf#1.data[].owner | string | 否 | 专属用户 ID 列表,使用英文逗号分隔;空值表示非专属套餐。 | |
oneOf#1.data[].enable | integer enum | 否 | 是否启用:1 为启用,0 为停用。 | 0 | 1 |
oneOf#1.data[].groups | string | 否 | 套餐所属套餐组 ID 的聚合字符串,使用英文逗号分隔;未分组时为 null。 | |
oneOf#2.code | string enum | 是 | 页码/分页条数格式错误或未登录时的业务错误码。 | package-38 | package-39 | login_required |
oneOf#2.msg | string | 是 | 错误原因。 | page参数格式不正确 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
POST /v1/packages
以管理员身份创建套餐。主线路组必须属于所选区域且至少配置一条启用线路;CNAME 域名必须存在;套餐名称必须唯一,并必须选择至少一个套餐组。创建成功后会同步该区域的 OpenResty 配置。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 是 | 套餐名称;不能为空、经 XSS 过滤且必须唯一。 | 标准套餐 |
des | string | 否 | 套餐备注;经 XSS 过滤,未传时保存为空字符串。 | 适用于普通网站 |
cc_protect | string | 否 | CC 防护能力说明;经 XSS 过滤,未传时为空字符串。 | 基础防护 |
ddos_protect | string | 否 | DDoS 防护能力说明;经 XSS 过滤,未传时为空字符串。 | 基础防护 |
region_id | integer | 是 | 套餐所属区域 ID,必须提供数字。 | 1 |
node_group_id | integer | 是 | 主线路组 ID;必须存在、属于 `region_id`,且至少有一条启用的解析线路。 | 2 |
backup_node_group | integer | 否 | 备用线路组 ID;可省略或传空值。传入时必须存在、属于同一区域、已配置启用解析线路,且不得与主线路组相同。 | 4 |
cname_domain | integer | 是 | CNAME 域名配置 ID,必须存在。 | 1 |
cname_hostname2 | string | 否 | 备用 CNAME 主机名;会转换为小写,非空时必须是合法主机名。未传时为空字符串。 | backup.cdn.example.invalid |
cname_mode | string enum | 否 | CNAME 使用模式;未传时为 `site`。 | site |
traffic | integer | 否 | 流量额度;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。 | 100 |
bandwidth | string | 否 | 带宽限制;可为 `-1` 表示不限,或数字加 `Mbps`/`Gbps`,如 `10Mbps`。未传时为 `-1`。 | 10Mbps |
connection | integer | 否 | 连接数限制;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。 | 1000 |
domain | integer | 否 | 可添加域名数量;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。 | 10 |
main_domain | integer | 否 | 可添加主域名数量;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。 | 1 |
http_port | integer | 否 | HTTP 端口数量;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。 | 2 |
stream_port | integer | 否 | 四层转发端口数量;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。 | 0 |
custom_cc_rule | integer enum | 否 | 是否允许自定义 CC 规则:1 为允许,0 为不允许;未传时为 0。 | 1 |
websocket | integer enum | 否 | 是否支持 WebSocket:1 为支持,0 为不支持;未传时为 0。 | 1 |
http3 | integer enum | 否 | 是否支持 HTTP/3:1 为支持,0 为不支持;未传时为 0。 | 1 |
l2_state | integer enum | 否 | 是否启用二层调度能力:1 为启用,0 为停用;未传时为 0。 | 0 |
expire | string | 否 | 套餐截止时间,非空时必须为合法日期时间;传空值或未传时保存为 null。 | 2026-12-31 23:59:59 |
buy_num_limit | integer | 否 | 单用户购买数量限制;非负整数表示限制值,`-1` 表示不限,未传时为 `-1`。 | 1 |
backend_ip_limit | string | 否 | 源站 IP/CIDR 限制列表,每行一个合法 IPv4/IPv6 CIDR;未传时保存为 null。 | 192.0.2.0/24
2001:db8::/32 |
id_verify | integer enum | 否 | 是否要求实名认证:1 为要求,0 为不要求;未传时为 0。 | 0 |
before_exp_days_renew | integer | 否 | 到期前允许续费的提前天数;非负整数表示天数,`-1` 表示不限,未传时为 `-1`。 | 7 |
sort | integer | 否 | 展示排序值;未传或传空值时为 100,数值越小越靠前。 | 100 |
owner | string | 否 | 专属用户 ID 列表,以英文逗号分隔;每个 ID 必须对应现有用户。未传时为 null,表示非专属套餐。 | 12,13 |
month_price | integer | 是 | 月付价格,必须为非负整数,单位为系统最小货币单位。 | 1000 |
quarter_price | integer | 是 | 季付价格,必须为非负整数,单位为系统最小货币单位。 | 2700 |
year_price | integer | 是 | 年付价格,必须为非负整数,单位为系统最小货币单位。 | 10000 |
enable | integer enum | 否 | 是否启用:1 为启用,0 为停用;未传时为 1。 | 1 |
groups | string | 是 | 套餐组 ID 列表,以英文逗号分隔;不能为空,列表中的每一项必须是数字。 | 3,4 |
套餐创建成功,`data` 为新套餐的自增 ID。 未登录、维护模式限制、非管理员或任一关联/字段校验失败时仍返回 HTTP 200。错误码以 `package-` 为前缀,例如:名称或价格必填/格式错误、区域和线路组不匹配、线路未配置解析、CNAME 不存在、套餐组未选择、备用线路组非法、源站 IP/CIDR 格式错误、专属用户不存在等。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 套餐添加成功 |
oneOf#1.data | integer | 是 | 新创建套餐的自增 ID。 | 11 |
oneOf#2.code | string | 是 | 业务错误码,可能为 `login_required`、`maintain`、`package-91` 或具体参数校验的 `package-*` 代码。 | package-72 |
oneOf#2.msg | string | 是 | 错误原因。 | 指定的线路组不属于当前所选区域 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
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> | 否 | 要更新的套餐列表;每个元素独立校验并在同一事务中处理。 | |
[].id | integer | 是 | 要更新的现有套餐 ID。 | 11 |
[].name | string | 否 | 套餐名称;传入时经 XSS 过滤,不能为空且必须唯一。 | |
[].des | string | 否 | 套餐备注;传入时经 XSS 过滤,空字符串可清空。 | |
[].cc_protect | string | 否 | CC 防护能力说明;传入时经 XSS 过滤。 | |
[].ddos_protect | string | 否 | DDoS 防护能力说明;传入时经 XSS 过滤。 | |
[].region_id | integer | 否 | 所属区域 ID;若同时更新主或备用线路组,必须与其所属区域一致。 | |
[].node_group_id | integer | 否 | 主线路组 ID;传入时必须存在并属于所选区域。 | |
[].backup_node_group | integer | 否 | 备用线路组 ID;空值可清除。非空时必须存在、属于同一区域、配置启用解析线路且不同于主线路组。 | |
[].cname_domain | integer | 否 | CNAME 域名配置 ID;传入时必须存在。 | |
[].cname_hostname2 | string | 否 | 备用 CNAME 主机名;会转换为小写,非空时必须为合法主机名。 | |
[].cname_mode | string enum | 否 | CNAME 使用模式。 | site | package |
[].traffic | integer | 否 | 流量额度;非负整数为限制值,`-1` 表示不限。 | |
[].bandwidth | string | 否 | 带宽限制;可为 `-1`,或数字加 `Mbps`/`Gbps`,如 `10Mbps`。 | |
[].connection | integer | 否 | 连接数限制;非负整数为限制值,`-1` 表示不限。 | |
[].domain | integer | 否 | 域名数量限制;非负整数为限制值,`-1` 表示不限。 | |
[].main_domain | integer | 否 | 主域名数量限制;非负整数为限制值,`-1` 表示不限。 | |
[].http_port | integer | 否 | HTTP 端口数量限制;非负整数为限制值,`-1` 表示不限。 | |
[].stream_port | integer | 否 | 四层转发端口数量限制;非负整数为限制值,`-1` 表示不限。 | |
[].custom_cc_rule | integer enum | 否 | 是否允许自定义 CC 规则:1 为允许,0 为不允许。 | 0 | 1 |
[].websocket | integer enum | 否 | 是否支持 WebSocket:1 为支持,0 为不支持。 | 0 | 1 |
[].http3 | integer enum | 否 | 是否支持 HTTP/3:1 为支持,0 为不支持。 | 0 | 1 |
[].l2_state | integer enum | 否 | 是否启用二层调度能力:1 为启用,0 为停用。 | 0 | 1 |
[].expire | string | 否 | 套餐截止时间;非空时必须为合法日期时间,空值可清除。 | |
[].buy_num_limit | integer | 否 | 单用户购买数量限制;非负整数为限制值,`-1` 表示不限。 | |
[].backend_ip_limit | string | 否 | 源站 IP/CIDR 限制列表,每行一个合法 IPv4/IPv6 CIDR;空字符串可清空。 | |
[].id_verify | integer enum | 否 | 是否要求实名认证:1 为要求,0 为不要求。 | 0 | 1 |
[].before_exp_days_renew | integer | 否 | 到期前允许续费的提前天数;非负整数表示天数,`-1` 表示不限。 | |
[].sort | integer | 否 | 展示排序值;传空值时更新为 100。 | |
[].owner | string | 否 | 专属用户 ID 列表,以英文逗号分隔;每项必须对应现有用户,空字符串可清空。 | |
[].month_price | integer | 否 | 月付价格;传入时必须为非负整数,单位为系统最小货币单位。 | |
[].quarter_price | integer | 否 | 季付价格;传入时必须为非负整数,单位为系统最小货币单位。 | |
[].year_price | integer | 否 | 年付价格;传入时必须为非负整数,单位为系统最小货币单位。 | |
[].enable | integer enum | 否 | 是否启用:1 为启用,0 为停用。 | 0 | 1 |
[].groups | string | 否 | 替换套餐所属套餐组的数字 ID 列表,以英文逗号分隔。省略时保留既有套餐组。 | |
[].sync-item | string | 否 | 要同步到使用该套餐的用户套餐的字段列表,以英文逗号分隔。仅支持 `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`。 | |
批量更新成功。 未登录、维护模式限制、非管理员、请求体不是数组或任何套餐的关联/字段校验失败时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package-41`、`package-91` 及具体校验的 `package-*` 代码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 更新套餐成功 |
oneOf#1.data | string | 是 | 该操作未返回更新后的套餐对象。 | |
oneOf#2.code | string | 是 | 业务错误码。 | package-41 |
oneOf#2.msg | string | 是 | 错误原因。 | 需要列表格式 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
DELETE /v1/packages/{package_id}
以管理员身份删除一个或多个套餐。路径参数支持英文逗号分隔多个套餐 ID;每条套餐必须存在且未被任何用户套餐引用。删除时会同时移除套餐与套餐组的关联,任一检查失败都会回滚本次操作。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | string | 是 | 一个套餐 ID,或以英文逗号分隔的多个套餐 ID。 | 11,12 |
套餐删除成功。服务端会将请求的 `package_id` 原样写入 `msg`,而非返回固定成功文案。 未登录、维护模式限制、非管理员、ID 格式错误、套餐不存在或套餐仍被用户套餐使用时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package-90`、`package-1`、`package-2` 或 `package-3`。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 原样回显请求中的套餐 ID 字符串。 | 11,12 |
oneOf#1.data | string | 是 | 该操作未返回已删除套餐的数据。 | |
oneOf#2.code | string | 是 | 业务错误码。 | package-3 |
oneOf#2.msg | string | 是 | 错误原因;套餐被使用时会包含引用的用户套餐 ID。 | 用户套餐101在用此套餐,不允许删除 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
GET /v1/packages/{package_id}
获取一条套餐记录。普通用户只能读取启用套餐,管理员可读取停用套餐。传入 `duration` 时,服务端会按当前登录用户的有效折扣和可用优惠码试算该周期价格,并在返回数据中附加价格字段。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 套餐 ID。 | 11 |
duration | query | string | 否 | 购买周期。传入后触发当前用户的价格试算。 | month |
coupon_code | query | string | 否 | 优惠码;仅在传入 `duration` 时用于价格试算。存在有效用户折扣时不会与优惠码叠加,原因通过响应中的 `err` 返回。 | REDACTED_COUPON |
成功、未登录、套餐不存在、普通用户查询停用套餐及周期参数非法均返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 成功时为空字符串。 | |
oneOf#1.data | object | 是 | 套餐记录;指定 `duration` 时会额外包含 `orgin_price`、`new_price` 和 `err`。 | |
oneOf#1.data.id | integer | 否 | 套餐 ID。 | |
oneOf#1.data.name | string | 否 | 套餐名称。 | |
oneOf#1.data.des | string | 否 | 套餐备注。 | |
oneOf#1.data.region_id | integer | 否 | 所属区域 ID。 | |
oneOf#1.data.node_group_id | integer | 否 | 主线路组 ID。 | |
oneOf#1.data.backup_node_group | integer | 否 | 备用线路组 ID。 | |
oneOf#1.data.cname_domain | integer | 否 | CNAME 域名配置 ID。 | |
oneOf#1.data.cname_hostname2 | string | 否 | 备用 CNAME 主机名。 | |
oneOf#1.data.cname_mode | string | 否 | CNAME 使用模式。 | |
oneOf#1.data.traffic | integer | 否 | 流量额度;`-1` 表示不限。 | |
oneOf#1.data.bandwidth | string | 否 | 带宽限制值;`-1` 表示不限。 | |
oneOf#1.data.connection | integer | 否 | 连接数限制;`-1` 表示不限。 | |
oneOf#1.data.domain | integer | 否 | 域名数量限制;`-1` 表示不限。 | |
oneOf#1.data.main_domain | integer | 否 | 主域名数量限制;`-1` 表示不限。 | |
oneOf#1.data.http_port | integer | 否 | HTTP 端口数量限制;`-1` 表示不限。 | |
oneOf#1.data.stream_port | integer | 否 | 四层转发端口数量限制;`-1` 表示不限。 | |
oneOf#1.data.custom_cc_rule | integer enum | 否 | 是否允许自定义 CC 规则:1 为允许。 | 0 | 1 |
oneOf#1.data.websocket | integer enum | 否 | 是否支持 WebSocket:1 为支持。 | 0 | 1 |
oneOf#1.data.http3 | integer enum | 否 | 是否支持 HTTP/3:1 为支持。 | 0 | 1 |
oneOf#1.data.l2_state | integer enum | 否 | 是否启用二层调度能力:1 为启用。 | 0 | 1 |
oneOf#1.data.cc_protect | string | 否 | CC 防护能力说明。 | |
oneOf#1.data.ddos_protect | string | 否 | DDoS 防护能力说明。 | |
oneOf#1.data.expire | string | 否 | 套餐截止时间,由数据库日期时间字段序列化返回。 | |
oneOf#1.data.buy_num_limit | integer | 否 | 单用户购买数量限制;`-1` 表示不限。 | |
oneOf#1.data.backend_ip_limit | string | 否 | 源站 IP/CIDR 限制配置文本。 | |
oneOf#1.data.id_verify | integer enum | 否 | 是否要求实名认证:1 为要求。 | 0 | 1 |
oneOf#1.data.before_exp_days_renew | integer | 否 | 到期前允许续费的提前天数;`-1` 表示不限。 | |
oneOf#1.data.month_price | integer | 否 | 月付价格,单位为系统最小货币单位。 | |
oneOf#1.data.quarter_price | integer | 否 | 季付价格,单位为系统最小货币单位。 | |
oneOf#1.data.year_price | integer | 否 | 年付价格,单位为系统最小货币单位。 | |
oneOf#1.data.create_at | string | 否 | 创建时间,由数据库日期时间字段序列化返回。 | |
oneOf#1.data.update_at | string | 否 | 最后更新时间,由数据库日期时间字段序列化返回。 | |
oneOf#1.data.sort | integer | 否 | 展示排序值。 | |
oneOf#1.data.owner | string | 否 | 专属用户 ID 列表,使用英文逗号分隔。 | |
oneOf#1.data.enable | integer enum | 否 | 是否启用:1 为启用,0 为停用。 | 0 | 1 |
oneOf#1.data.orgin_price | integer | 否 | 仅传 `duration` 时返回:所选周期的原始价格,单位为系统最小货币单位。 | |
oneOf#1.data.new_price | integer | 否 | 仅传 `duration` 时返回:应用有效折扣或优惠码后的所选周期试算价格,单位为系统最小货币单位。 | |
oneOf#1.data.err | string | 否 | 仅传 `duration` 时返回:优惠码或折扣不能应用时的原因;无错误时为 null。 | |
oneOf#2.code | string enum | 是 | 周期参数非法、套餐不存在、普通用户无权查询停用套餐或未登录时的业务错误码。 | package-83 | package-36 | package-37 | login_required |
oneOf#2.msg | string | 是 | 错误原因。 | 无权限查询 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
PUT /v1/packages/{package_id}
以管理员身份更新一条套餐。请求体必须为 JSON 对象;路径中的套餐 ID 会覆盖请求体中的 ID。未提供的字段保持原值,且服务端每次都会更新 `update_at`,因此空对象也会成功。`sync-item` 可将指定配置同步到使用该套餐的用户套餐、网站和四层转发。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 要更新的套餐 ID。 | 11 |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 否 | 套餐名称;传入时经 XSS 过滤,不能为空且必须唯一。 | |
des | string | 否 | 套餐备注;传入时经 XSS 过滤,空字符串可清空。 | |
cc_protect | string | 否 | CC 防护能力说明;传入时经 XSS 过滤。 | |
ddos_protect | string | 否 | DDoS 防护能力说明;传入时经 XSS 过滤。 | |
region_id | integer | 否 | 所属区域 ID;若更新线路组,必须与其所属区域一致。 | |
node_group_id | integer | 否 | 主线路组 ID;传入时必须存在并属于所选区域。 | |
backup_node_group | integer | 否 | 备用线路组 ID;空值可清除。非空时必须存在、属于同一区域、配置启用解析线路且不同于主线路组。 | |
cname_domain | integer | 否 | CNAME 域名配置 ID;传入时必须存在。 | |
cname_hostname2 | string | 否 | 备用 CNAME 主机名;会转换为小写,非空时必须为合法主机名。 | |
cname_mode | string enum | 否 | CNAME 使用模式。 | site | package |
traffic | integer | 否 | 流量额度;非负整数为限制值,`-1` 表示不限。 | |
bandwidth | string | 否 | 带宽限制;可为 `-1`,或数字加 `Mbps`/`Gbps`,如 `10Mbps`。 | |
connection | integer | 否 | 连接数限制;非负整数为限制值,`-1` 表示不限。 | |
domain | integer | 否 | 域名数量限制;非负整数为限制值,`-1` 表示不限。 | |
main_domain | integer | 否 | 主域名数量限制;非负整数为限制值,`-1` 表示不限。 | |
http_port | integer | 否 | HTTP 端口数量限制;非负整数为限制值,`-1` 表示不限。 | |
stream_port | integer | 否 | 四层转发端口数量限制;非负整数为限制值,`-1` 表示不限。 | |
custom_cc_rule | integer enum | 否 | 是否允许自定义 CC 规则:1 为允许,0 为不允许。 | 0 | 1 |
websocket | integer enum | 否 | 是否支持 WebSocket:1 为支持,0 为不支持。 | 0 | 1 |
http3 | integer enum | 否 | 是否支持 HTTP/3:1 为支持,0 为不支持。 | 0 | 1 |
l2_state | integer enum | 否 | 是否启用二层调度能力:1 为启用,0 为停用。 | 0 | 1 |
expire | string | 否 | 套餐截止时间;非空时必须为合法日期时间,空值可清除。 | |
buy_num_limit | integer | 否 | 单用户购买数量限制;非负整数为限制值,`-1` 表示不限。 | |
backend_ip_limit | string | 否 | 源站 IP/CIDR 限制列表,每行一个合法 IPv4/IPv6 CIDR;空字符串可清空。 | |
id_verify | integer enum | 否 | 是否要求实名认证:1 为要求,0 为不要求。 | 0 | 1 |
before_exp_days_renew | integer | 否 | 到期前允许续费的提前天数;非负整数表示天数,`-1` 表示不限。 | |
sort | integer | 否 | 展示排序值;传空值时更新为 100。 | |
owner | string | 否 | 专属用户 ID 列表,以英文逗号分隔;每项必须对应现有用户,空字符串可清空。 | |
month_price | integer | 否 | 月付价格;传入时必须为非负整数,单位为系统最小货币单位。 | |
quarter_price | integer | 否 | 季付价格;传入时必须为非负整数,单位为系统最小货币单位。 | |
year_price | integer | 否 | 年付价格;传入时必须为非负整数,单位为系统最小货币单位。 | |
enable | integer enum | 否 | 是否启用:1 为启用,0 为停用。 | 0 | 1 |
groups | string | 否 | 替换套餐所属套餐组的数字 ID 列表,以英文逗号分隔;省略时保留既有套餐组。 | |
sync-item | string | 否 | 要同步到使用该套餐的用户套餐的字段列表,以英文逗号分隔。仅支持 `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`。 | |
套餐更新成功。 未登录、维护模式限制、非管理员、请求体不是对象或任何关联/字段校验失败时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`package-40`、`package-91` 及具体校验的 `package-*` 代码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 更新套餐成功 |
oneOf#1.data | string | 是 | 该操作未返回更新后的套餐对象。 | |
oneOf#2.code | string | 是 | 业务错误码。 | package-40 |
oneOf#2.msg | string | 是 | 错误原因。 | 需要字典格式 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
当前用户套餐、用量和升级。
GET /v1/user-package/{package_id}/upgrades
分页查询指定用户套餐已购买的升级包。普通用户只能查询自己的用户套餐;管理员可查询任意用户套餐。结果按升级记录 ID 倒序返回。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 用户套餐 ID;必须存在且当前用户有权限查看。 | 8 |
page | query | integer | 否 | 页码,必须为数字;未传时为 1。 | 1 |
limit | query | integer | 否 | 每页数量,必须为数字;未传时为 10,传 0 表示不分页。 | 10 |
请求已被处理。成功时返回升级包记录列表和总数;套餐无权限、页码或每页数量格式错误时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
count | integer | 是 | 该用户套餐已购买升级包记录总数。 | 1 |
data | array | 是 | 用户套餐升级包记录。 | |
data | array<object> | 否 | 用户套餐升级包记录。 | |
data[].id | integer | 是 | 用户套餐升级记录 ID。 | |
data[].uid | integer | 是 | 归属用户 ID。 | |
data[].user_package | integer | 是 | 用户套餐 ID。 | |
data[].package_up | integer | 是 | 升级包定义 ID。 | |
data[].amount | integer | 是 | 当前购买数量。 | |
data[].package_up_name | string | 是 | 升级包名称。 | |
data[].type | string | 是 | 升级资源类型,例如 traffic、domain、http_port。 | |
data[].package_up_amount | integer | 是 | 每单位升级包提供的资源数量。 | |
POST /v1/user-package/{package_id}/upgrades
为指定用户套餐购买或增加升级包数量。请求体必须是对象。普通用户只能操作自己的套餐:系统会校验升级包是否绑定当前基础套餐、套餐剩余时间不少于一天,并按剩余天数、可用折扣和数量计算价格后从账户余额扣款,同时创建已付款订单。管理员操作时不执行该余额扣款流程。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 要升级的用户套餐 ID,必须存在且当前用户有权限操作。 | 8 |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
package_up | integer | 是 | 必填。升级包定义 ID,必须存在。普通用户购买时,若升级包绑定基础套餐,当前用户套餐必须在绑定范围内。 | 3 |
amount | integer | 否 | 购买数量,必须为数字;未传时为 1。若已有同一升级包,会在当前数量上累加。 | 2 |
请求已被处理。成功时 `code` 为 0、`msg` 为“升级包添加成功”、`data` 为 null;套餐或升级包不存在、权限不足、套餐到期、余额不足或升级包不适用时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 升级包添加成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
PUT /v1/user-package/{package_id}/upgrades
调整指定用户套餐中已购买升级包的数量。请求体必须为对象。普通用户仅能操作自己的套餐,且只能把已存在升级包的数量减少到大于 0 且小于当前数量的值;减少后系统会校验流量、域名、端口及自定义 CC 规则等已用资源是否仍有足够额度。管理员不受普通用户的资源减少限制。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 要调整的用户套餐 ID,必须存在且当前用户有权限操作。 | 8 |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
package_up | integer | 是 | 必填。要调整的升级包定义 ID,必须存在且已关联当前用户套餐。 | 3 |
amount | integer | 是 | 必填。调整后的总数量。普通用户必须小于当前数量且大于 0;管理员可按实现规则调整。 | 1 |
请求已被处理。成功时 `code` 为 0、`msg` 为“升级包修改成功”、`data` 为 null;请求体格式、套餐、升级包、数量、权限或资源余量不符合要求时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 升级包修改成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
DELETE /v1/user-package/{package_id}/upgrades/{package_up_id}
从指定用户套餐移除一个升级包。普通用户只能操作自己的套餐;删除前会检查移除后流量、域名、主域名、HTTP/转发端口和自定义 CC 规则等已用资源是否仍有足够额度。管理员不执行该普通用户资源余量检查。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 用户套餐 ID,必须存在且当前用户有权限操作。 | 8 |
package_up_id | path | integer | 是 | 要移除的升级包定义 ID,必须存在。 | 3 |
请求已被处理。成功时 `code` 为 0、`msg` 为“升级包删除成功”、`data` 为 null;套餐或升级包不存在、无权限、或移除后资源不足时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 升级包删除成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
GET /v1/user-package/{package_id}/upgrades/{package_up_id}
试算指定用户套餐购买升级包的价格。服务端按套餐剩余天数、当前用户组适用折扣和请求数量计算原月价、折后月价、原价及实付价;套餐已过期或剩余不足一天时不能试算。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 用户套餐 ID。 | 8 |
package_up_id | path | integer | 是 | 要试算的升级包定义 ID。 | 3 |
amount | query | integer | 否 | 试算数量;未传时为 1。该值参与价格计算。 | 2 |
请求已被处理。成功时 `data` 为按剩余天数计算的价格试算结果;套餐已过期或套餐剩余时间不足一天时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 成功时为空字符串,失败时为错误说明。 | |
data | object | 是 | 升级包价格试算结果。 | |
data.orgin_month_price | number | 是 | 升级包原月价。 | |
data.new_month_price | number | 是 | 应用当前用户可用折扣后的月价。 | |
data.orgin_price | number | 是 | 按剩余天数和数量计算的原始应付金额。 | |
data.price | number | 是 | 按折后月价、剩余天数和数量计算的实际应付金额。 | |
data.days | integer | 是 | 用于计费的套餐剩余天数;超过半天按一天计。 | |
data.amount | integer | 是 | 参与本次试算的数量。 | |
GET /v1/user-package/{package_id}/usage
查询指定用户套餐当前已使用的域名、主域名、HTTP 非标准端口、四层转发端口和流量。普通用户只能查询自己的套餐;管理员可查询任意用户套餐。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 要查询用量的用户套餐 ID,必须存在且当前用户有权限查看。 | 8 |
请求已被处理。成功时返回套餐资源用量;套餐不存在或无权限时仍返回 HTTP 200。该接口成功响应不包含 `msg` 或 `count` 字段。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
data | object | 是 | 用户套餐当前资源用量。 | |
data.domain_usage | integer | 是 | 已使用域名数量。 | |
data.main_domain_usage | integer | 是 | 已使用主域名数量。 | |
data.http_port_usage | integer | 是 | 已使用 HTTP 非标准端口数量。 | |
data.stream_port_usage | integer | 是 | 已使用四层转发端口数量。 | |
data.traffic_usage | integer | 是 | 已使用流量,单位由服务端用量统计函数确定。 | |
GET /v1/user-packages
分页查询用户已购买的基础套餐。普通用户只能查询自己的套餐;管理员可按用户、套餐、到期时间、CNAME、流量超额和启用状态筛选。默认按 ID 倒序,可按到期时间升序。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer | 否 | 页码,必须为数字;未传时为 1。 | 1 |
limit | query | integer | 否 | 每页数量,必须为数字;未传时为 10,传 0 表示不分页。 | 10 |
uid | query | integer | 否 | 管理员可选。按套餐归属用户 ID 筛选;普通用户不能借此查看其他用户。 | 12 |
expire | query | integer | 否 | 按即将到期筛选:返回结束时间早于当前时间加此天数的套餐。 | 7 |
user_package | query | string | 否 | 按用户套餐 ID 或套餐名称包含文本筛选。 | 8 |
base_package | query | integer | 否 | 按基础套餐定义 ID 筛选。 | 2 |
cname_hostname | query | string | 否 | 按套餐 CNAME 主机名精确筛选。 | demo.example.invalid |
order_by | query | string | 否 | 排序字段:`id` 为 ID 倒序,`end_at` 为到期时间升序。 | end_at |
traffic_exceed | query | integer | 否 | 按流量超额状态筛选。 | 1 |
enable | query | integer | 否 | 按套餐启用状态筛选。 | 1 |
请求已被处理。成功时返回用户套餐列表和总数;页码、每页数量、uid 或排序字段无效时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
count | integer | 是 | 符合筛选条件的用户套餐总数。 | 1 |
data | array | 是 | 用户套餐列表。 | |
data | array<object> | 否 | 用户套餐列表。 | |
data[].id | integer | 是 | 用户套餐 ID。 | |
data[].uid | integer | 是 | 归属用户 ID。 | |
data[].user_name | string | 否 | 归属用户名。 | |
data[].name | string | 否 | 用户套餐名称。 | |
data[].user_package_name | string | 否 | 用户套餐名称的别名。 | |
data[].package | integer | 是 | 基础套餐定义 ID。 | |
data[].package_name | string | 否 | 基础套餐名称。 | |
data[].start_at2 | string | 是 | 套餐生效时间。 | |
data[].end_at2 | string | 是 | 套餐到期时间。 | |
data[].traffic_usage | integer | 否 | 已使用流量。 | |
data[].traffic_upgrade | integer | 否 | 已购买流量升级包带来的总增量。 | |
data[].traffic_exceed | integer | 否 | 是否流量超额。 | |
data[].enable | integer enum | 是 | 套餐启用状态。 | 0 | 1 |
data[].enable_ipv6 | integer enum | 否 | 是否启用 IPv6。 | 0 | 1 |
data[].cname_hostname | string | 否 | 套餐 CNAME 主机名。 | |
data[].cname_domain | integer | 否 | 套餐 CNAME 域名配置 ID。 | |
data[].region_id | integer | 否 | 区域 ID。 | |
data[].node_group_id | integer | 否 | 线路组 ID。 | |
POST /v1/user-packages
购买并创建一个用户套餐。普通用户为自己购买时会校验套餐可购资格、购买次数、实名认证、套餐状态,并按 `duration`、可用折扣和优惠码计算价格后扣除余额、创建订单;管理员可为指定用户分配套餐,并可覆盖套餐资源额度与价格。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
package | integer | 是 | 必填。要购买的基础套餐定义 ID,必须存在。 | 2 |
name | string | 是 | 必填。用户套餐名称;会进行 XSS 过滤。 | 我的标准套餐 |
duration | string enum | 否 | 购买期限;普通用户购买时用于计算价格。 | month |
coupon_code | string | 否 | 可选。购买基础套餐时使用的优惠码。 | WELCOME10 |
enable_ipv6 | integer enum | 否 | 是否启用 IPv6;未传时为 1。 | 0 | 1 |
uid | integer | 否 | 管理员专用。指定套餐归属用户 ID。 | |
cname_hostname | string | 否 | 管理员专用。自定义套餐 CNAME 主机名;必须唯一且合法。 | |
traffic | integer | 否 | 管理员专用。流量额度;-1 表示不限。 | |
bandwidth | string | 否 | 管理员专用。带宽额度;-1 表示不限,其他值为数字加 Mbps 或 Gbps。 | |
connection | integer | 否 | 管理员专用。连接数额度;-1 表示不限。 | |
domain | integer | 否 | 管理员专用。域名数量额度;-1 表示不限。 | |
main_domain | integer | 否 | 管理员专用。主域名数量额度;-1 表示不限。 | |
http_port | integer | 否 | 管理员专用。HTTP 非标准端口额度;-1 表示不限。 | |
stream_port | integer | 否 | 管理员专用。四层转发端口额度;-1 表示不限。 | |
custom_cc_rule | integer enum | 否 | 管理员专用。是否允许自定义 CC 规则。 | 0 | 1 |
websocket | integer enum | 否 | 管理员专用。是否允许 WebSocket。 | 0 | 1 |
http3 | integer enum | 否 | 管理员专用。是否允许 HTTP/3。 | 0 | 1 |
month_price | integer | 否 | 管理员专用。月付价格。 | |
quarter_price | integer | 否 | 管理员专用。季付价格。 | |
year_price | integer | 否 | 管理员专用。年付价格。 | |
end_at | string | 否 | 管理员专用。到期时间,格式 YYYY-MM-DD HH:mm:ss。 | |
enable | integer enum | 否 | 管理员专用。套餐启用状态。 | 0 | 1 |
reason | string enum | 否 | 管理员禁用套餐时必填的禁用原因。 | 到期 | 流量用完 | 锁定 |
请求已被处理。成功时 `code` 为 0、`msg` 为“套餐添加成功”、`data` 为新建用户套餐 ID;套餐不存在、无购买权限、实名不足、余额不足或参数不合法时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 套餐添加成功 |
data | integer | 是 | 成功时的新建用户套餐 ID;失败时为空字符串。 | 8 |
DELETE /v1/user-packages/{package_id}
删除一个用户套餐及其已购买的升级包。普通用户只能删除自己的套餐。默认删除模式要求套餐没有关联网站和四层转发;传入 `force` 会同时删除关联网站、四层转发及其部分关联数据,但仍不允许删除未到期且存在网站或四层转发的套餐。若这是该用户唯一套餐,强制删除还会删除该用户的证书、DNS API、访问控制、CC 规则、分组、任务和消息发送配置。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 要删除的用户套餐 ID。套餐必须存在,普通用户只能删除自己的套餐。 | 8 |
force | query | string | 否 | 可选。传任意非空值启用强制删除:删除套餐关联的网站、四层转发及关联缓存和分组数据。未到期且仍有关联网站或四层转发时,强制删除会被拒绝。 | 1 |
请求已被处理。成功时 `code` 为 0、`msg` 为“用户套餐删除成功”、`data` 为 null;套餐不存在、无权限、有关联资源或不满足强制删除条件时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 用户套餐删除成功 |
data | string | 是 | 本接口成功时为 null;失败时为空字符串。 | null |
GET /v1/user-packages/{package_id}
获取用户套餐详情。可选传入 `duration` 试算续费价格,或传入 `to_package` 试算更换至另一基础套餐的差价;可同时传入优惠码参与续费价格计算。普通用户只能查看自己的套餐,管理员可查看任意套餐。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 要查询的用户套餐 ID,必须存在且当前用户有权限查看。 | 8 |
duration | query | string | 否 | 可选。传入后返回该期限的续费及已购升级包价格试算。 | month |
coupon_code | query | string | 否 | 可选。续费试算时使用的优惠码;不可用时返回业务错误。 | WELCOME10 |
to_package | query | integer | 否 | 可选。目标基础套餐 ID;传入后返回更换套餐的周期、当前价格、新套餐价格与差价试算。 | 3 |
请求已被处理。成功时 `data` 为用户套餐详情,并按请求可选附加续费或换套餐试算字段;套餐不存在、无权限或优惠码不可用时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 成功时为空字符串,失败时为错误说明。 | |
data | object | 是 | 用户套餐详情与可选价格试算结果。 | |
data.id | integer | 是 | 用户套餐 ID。 | |
data.uid | integer | 是 | 归属用户 ID。 | |
data.package | integer | 是 | 基础套餐定义 ID。 | |
data.package_name | string | 否 | 基础套餐名称。 | |
data.name | string | 是 | 用户套餐名称。 | |
data.start_at2 | string | 是 | 生效时间。 | |
data.end_at2 | string | 是 | 到期时间。 | |
data.traffic_reset_time | string | 是 | 下一次流量重置时间。 | |
data.traffic_usage | integer | 否 | 已使用流量。 | |
data.traffic | integer | 否 | 流量额度,-1 表示不限。 | |
data.enable | integer enum | 否 | 启用状态。 | 0 | 1 |
data.reason | string | 否 | 禁用原因。 | |
data.cname_hostname | string | 否 | 套餐 CNAME 主机名。 | |
data.basic_price | number | 否 | 续费试算中的基础套餐价格,仅传 duration 时返回。 | |
data.up_price | number | 否 | 续费试算中的升级包价格,仅传 duration 时返回。 | |
data.total_price | number | 否 | 续费试算总价,仅传 duration 时返回。 | |
data.orgin_price | number | 否 | 续费试算原价,仅传 duration 时返回。 | |
data.period | string | 否 | 换套餐试算的当前计费周期,仅传 to_package 时返回。 | |
data.curr_price | number | 否 | 换套餐试算的当前套餐价格。 | |
data.new_price | number | 否 | 换套餐试算的新套餐价格。 | |
data.diff_price | number | 否 | 换套餐试算的应补或应退差价。 | |
data.remain_days | integer | 否 | 换套餐试算使用的剩余天数。 | |
PUT /v1/user-packages/{package_id}
更新一个已购买套餐的名称、线路、CNAME、资源额度、开关或到期时间,也可通过 `duration` 为套餐续费。普通用户只能更新自己的套餐中无需管理员权限的字段;资源额度、价格、CNAME 主机名、到期时间及启用状态仅管理员可改。传入 `package` 时执行更换基础套餐并立即完成,不能与其他修改字段组合处理。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 要更新的用户套餐 ID。套餐必须存在;普通用户只能操作自己的套餐。 | 8 |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
uid | integer | 否 | 管理员专用。指定续费、优惠和余额处理所使用的用户 ID;必须存在。该字段不会转移用户套餐归属。 | 12 |
package | integer | 否 | 更换目标基础套餐定义 ID。不能与当前套餐相同;传入后立即执行换套餐,其他请求字段不会继续处理。 | 3 |
name | string | 否 | 套餐显示名称;会进行 XSS 过滤。 | 我的标准套餐 |
duration | string enum | 否 | 续费期限。续费会按套餐及已购升级包价格扣除当前用户余额并延长到期时间;管理员续费不扣费。 | month |
coupon_code | string | 否 | 续费时使用的优惠码;仅在同时传入 duration 时参与价格计算。 | WELCOME10 |
region_id | integer | 否 | 区域 ID。更新时线路组必须属于该区域;变更会同步使用套餐 CNAME 的网站和四层转发。 | 1 |
node_group_id | integer | 否 | 主线路组 ID,不能为空,且必须属于当前区域。 | 2 |
backup_node_group | integer | 否 | 备用线路组 ID;传空值可清除。若设置,必须属于当前区域且不能与主线路组相同。 | 3 |
cname_domain | integer | 否 | CNAME 域名配置 ID,必须存在。变更会更新套餐及相关网站、四层转发的 CNAME 记录。 | 4 |
cname_mode | string enum | 否 | CNAME 归属模式:site 为网站或转发各自使用 CNAME,package 为跟随用户套餐。 | package |
cname_hostname | string | 否 | 管理员专用。套餐 CNAME 主机名;每个以点分隔的标签都必须是合法主机名,且在用户套餐中唯一。 | user-12.example.invalid |
traffic | integer | 否 | 管理员专用。流量额度;-1 表示不限。提高额度或改为不限时会解除流量超额状态。 | 100 |
bandwidth | string | 否 | 管理员专用。带宽额度;-1 表示不限,其他值必须为数字加 Mbps 或 Gbps。 | 100Mbps |
connection | integer | 否 | 管理员专用。并发连接数额度;-1 表示不限。 | 1000 |
domain | integer | 否 | 管理员专用。域名数量额度;-1 表示不限。 | 10 |
main_domain | integer | 否 | 管理员专用。主域名数量额度;-1 表示不限。 | 5 |
http_port | integer | 否 | 管理员专用。HTTP 非标准端口数量额度;-1 表示不限。 | 3 |
stream_port | integer | 否 | 管理员专用。四层转发端口数量额度;-1 表示不限。 | 2 |
custom_cc_rule | integer enum | 否 | 管理员专用。是否允许自定义 CC 规则。 | 1 |
websocket | integer enum | 否 | 管理员专用。是否允许 WebSocket。 | 1 |
http3 | integer enum | 否 | 管理员专用。是否允许 HTTP/3。 | 1 |
enable_ipv6 | integer enum | 否 | 是否启用 IPv6;变更会创建 CNAME 更新任务。 | 1 |
month_price | integer | 否 | 管理员专用。用户套餐的月付价格。 | 1000 |
quarter_price | integer | 否 | 管理员专用。用户套餐的季付价格。 | 2700 |
year_price | integer | 否 | 管理员专用。用户套餐的年付价格。 | 10000 |
end_at | string | 否 | 管理员专用。直接设置到期时间,格式 YYYY-MM-DD HH:mm:ss。 | 2026-12-31 23:59:59 |
enable | integer enum | 否 | 管理员专用。套餐启用状态;设为 0 时必须同时提供 reason,设为 1 会恢复相关网站和转发。 | 1 |
reason | string enum | 否 | 当 enable 为 0 时必填,表示禁用原因。 | 锁定 |
sync-item | string | 否 | 可选。将套餐配置同步到关联网站和四层转发的项目。可传 cname_mode,或以英文逗号组合 node_group_id、cname_domain、cname_mode。 | node_group_id,cname_domain |
请求已被处理。成功时 `code` 为 0、`msg` 为“更新用户套餐成功”、`data` 为 null;套餐不存在、无权限、字段格式错误、套餐资源不匹配、未到续费时间或余额不足时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 更新用户套餐成功 |
data | string | 是 | 本接口成功时为 null;失败时为空字符串。 | null |
流量包
GET /v1/traffic-packages
分页查询流量包。普通用户只能看到已启用的流量包;管理员可通过 `enable` 查询指定启用状态。结果按流量包 ID 倒序返回,并带出可绑定套餐名称。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer | 否 | 页码,必须为数字;未传时为 1。 | 1 |
limit | query | integer | 否 | 每页数量,必须为数字;未传时为 10,传 0 表示不分页。 | 10 |
enable | query | integer | 否 | 管理员可选。按启用状态筛选;普通用户始终仅返回启用的流量包。 | 1 |
请求已被处理。成功时返回流量包列表和总数;页码或每页数量格式错误时也返回 HTTP 200,并在业务码中说明原因。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
count | integer | 是 | 符合筛选条件的流量包总数。 | 2 |
data | array | 是 | 流量包列表。 | |
data | array<object> | 否 | 流量包列表。 | |
data[].id | integer | 是 | 流量包 ID。 | |
data[].name | string | 是 | 流量包名称。 | |
data[].des | string | 否 | 备注。 | |
data[].amount | string | 是 | 流量额度,格式为数字加 GB、TB 或 PB。 | |
data[].bind_package | string | 否 | 可绑定套餐 ID 的逗号分隔字符串。 | |
data[].bind_package_name | string | 否 | 可绑定套餐名称的逗号分隔字符串。 | |
data[].valid_days | integer | 是 | 流量包有效天数。 | |
data[].price | integer | 是 | 价格,单位为系统最小货币单位。 | |
data[].enable | integer enum | 是 | 启用状态。 | 0 | 1 |
data[].create_at | string | 否 | 创建时间,格式为 YYYY-MM-DD HH:mm:ss。 | |
POST /v1/traffic-packages
创建流量包。该操作要求管理员权限。流量包名称全局唯一,额度使用 `GB`、`TB` 或 `PB` 单位;可选地限制为只能绑定指定基础套餐。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 是 | 必填。流量包名称;会进行 XSS 过滤,且必须全局唯一。 | 100GB 流量包 |
des | string | 否 | 可选。流量包备注;会进行 XSS 过滤,未传时为空字符串。 | 月度加油包 |
amount | string | 是 | 必填。流量额度,格式为非负数字加 `GB`、`TB` 或 `PB`,例如 `100GB`。 | 100GB |
bind_package | string | 否 | 可选。允许绑定此流量包的基础套餐 ID,多个 ID 用英文逗号分隔;每个 ID 必须存在。未传时不限制基础套餐。 | 1,2 |
valid_days | integer | 是 | 必填。流量包有效天数,必须为大于 0 的数字。 | 30 |
price | number | 是 | 必填。售价,必须为不小于 0 的数值。 | 10.5 |
enable | integer enum | 否 | 是否启用;未传时为 1。 | 1 |
请求已被处理。成功时 `code` 为 0、`msg` 为“流量包添加成功”、`data` 为新建流量包 ID;权限不足和字段校验失败仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 流量包添加成功 |
data | integer | 是 | 成功时的新建流量包 ID;失败时为空字符串。 | 5 |
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}] |
[].id | integer | 是 | 必填。要更新的流量包 ID,必须存在。 | |
[].name | string | 否 | 流量包名称;会进行 XSS 过滤,且必须全局唯一。 | |
[].des | string | 否 | 备注;会进行 XSS 过滤,可传空字符串。 | |
[].amount | string | 否 | 流量额度,格式为数字加 GB、TB 或 PB。 | |
[].bind_package | string | 否 | 可绑定基础套餐 ID,多个 ID 以英文逗号分隔;每个 ID 必须存在。 | |
[].valid_days | integer | 否 | 有效天数,必须大于 0。 | |
[].price | number | 否 | 售价,不得小于 0。 | |
[].enable | integer enum | 否 | 启用状态。 | 0 | 1 |
请求已被处理。成功时 `code` 为 0、`msg` 为“更新流量包成功”、`data` 为 null;请求体不是数组、流量包不存在、权限不足或字段校验失败时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 更新流量包成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
DELETE /v1/traffic-packages/{package_id}
删除一个或多个流量包。该操作要求管理员权限;路径参数支持单个 ID 或英文逗号分隔的多个 ID。每个流量包必须存在,且不能仍被任何用户流量包引用;任一项目不满足条件时整次删除会回滚。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | string | 是 | 要删除的流量包 ID,或以英文逗号分隔的 ID 列表;每一项必须是数字。 | 5,6 |
请求已被处理。成功时 `code` 为 0,`msg` 为已删除的 ID 字符串,`data` 为 null;权限不足、ID 无效、流量包不存在或仍被用户流量包使用时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 成功时为请求中已删除的流量包 ID 字符串。 | 5,6 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
GET /v1/traffic-packages/{package_id}
获取单个流量包详情,并按当前登录用户和可选优惠券计算实际售价 `new_price`。普通用户不能查询已禁用流量包;管理员可查询任意已有流量包。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 要查询的流量包 ID,必须存在。 | 5 |
coupon_code | query | string | 否 | 可选。用于计算当前用户购买该流量包后的实际价格;无效或不可用优惠券会返回业务错误。 | WELCOME10 |
请求已被处理。成功时 `code` 为 0、`data` 为流量包详情及计算后的 `new_price`;流量包不存在、普通用户查询禁用项或优惠券不可用时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 成功时为空字符串,失败时为错误说明。 | |
data | object | 是 | 流量包详情。 | |
data.id | integer | 是 | 流量包 ID。 | |
data.name | string | 是 | 流量包名称。 | |
data.des | string | 否 | 备注。 | |
data.amount | string | 是 | 流量额度,格式为数字加 GB、TB 或 PB。 | |
data.bind_package | string | 否 | 可绑定基础套餐 ID 列表。 | |
data.valid_days | integer | 是 | 有效天数。 | |
data.price | number | 是 | 原始售价。 | |
data.new_price | number | 是 | 针对当前用户及 coupon_code 计算后的实际售价。 | |
data.enable | integer enum | 是 | 启用状态。 | 0 | 1 |
data.create_at | string | 否 | 创建时间。 | |
data.update_at | string | 否 | 更新时间。 | |
PUT /v1/traffic-packages/{package_id}
更新指定流量包。该操作要求管理员权限;路径中的 `package_id` 会写入请求对象,客户端不能通过请求体更换更新目标。请求体必须是单个 JSON 对象,仅传需要修改的字段。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 要更新的流量包 ID,必须存在。 | 5 |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 否 | 流量包名称;会进行 XSS 过滤,且必须全局唯一。未传时保持原值。 | |
des | string | 否 | 备注;会进行 XSS 过滤,可传空字符串。 | |
amount | string | 否 | 流量额度,格式为数字加 GB、TB 或 PB。 | |
bind_package | string | 否 | 可绑定基础套餐 ID,多个 ID 以英文逗号分隔;每个 ID 必须存在。 | |
valid_days | integer | 否 | 有效天数,必须大于 0。 | |
price | number | 否 | 售价,不得小于 0。 | |
enable | integer enum | 否 | 启用状态。 | 0 | 1 |
请求已被处理。成功时 `code` 为 0、`msg` 为“更新流量包成功”、`data` 为 null;权限不足、流量包不存在、请求体格式错误或字段校验失败时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 更新流量包成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
当前用户流量包和用量。
GET /v1/user-traffic-package/usage
按时间统计一个用户流量套餐已消耗的流量。普通用户只能查询自己的流量套餐;管理员可查询任意用户。可选按关联的用户套餐过滤。未同时指定时间范围时,接口根据已有用量记录跨度自动按小时、天或月汇总。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
user_traffic_package | query | integer | 是 | 必填。要统计的用户流量套餐 ID;必须存在,且当前用户拥有该套餐或具有管理员权限。 | 21 |
user_package | query | integer | 否 | 可选。仅统计关联到指定用户套餐 ID 的流量消耗记录。 | 8 |
start | query | string | 否 | 可选。统计开始时间,格式 YYYY-MM-DD HH:mm:ss;如提供必须同时提供 end。 | 2026-01-01 00:00:00 |
end | query | string | 否 | 可选。统计结束时间,格式 YYYY-MM-DD HH:mm:ss;查询范围为 time 大于等于 start 且小于 end,必须不早于 start。 | 2026-01-08 00:00:00 |
请求已被处理。成功时 data 为按时间分组的流量用量数组;流量套餐不存在、无权限、时间范围不完整或时间格式无效时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
data | array | 是 | 按统计粒度汇总的流量用量。时间跨度小于 7 天按时间点汇总,少于 180 天按天汇总,其他情况按月汇总。 | |
data | array<object> | 否 | 按统计粒度汇总的流量用量。时间跨度小于 7 天按时间点汇总,少于 180 天按天汇总,其他情况按月汇总。 | |
data[].date | string | 是 | 统计时间标签,格式随统计跨度为 YYYY-MM-DD HH:mm:ss、YYYY-MM-DD 或 YYYY-MM。 | 2026-01-01 |
data[].value | integer | 是 | 该时间分组内的流量消耗总值。 | 1073741824 |
GET /v1/user-traffic-packages
分页查询已购买的用户流量套餐。普通用户只能查看自己的流量套餐;管理员可按归属用户、流量套餐定义和启用状态筛选。结果按用户流量套餐 ID 倒序返回。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer | 否 | 页码,必须为数字;未传时为 1。 | 1 |
limit | query | integer | 否 | 每页数量,必须为数字;未传时为 10,传 0 表示不分页。 | 10 |
uid | query | integer | 否 | 管理员可选。按归属用户 ID 筛选;普通用户始终只能查询自己的流量套餐。 | 12 |
traffic_package_id | query | integer | 否 | 按流量套餐定义 ID 筛选,必须为数字。 | 3 |
enable | query | integer | 否 | 按用户流量套餐启用状态筛选。 | 1 |
请求已被处理。成功时返回用户流量套餐列表及总数;页码、每页数量、用户 ID 或流量套餐 ID 格式无效时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
count | integer | 是 | 符合筛选条件的用户流量套餐总数。 | 1 |
data | array | 是 | 用户流量套餐列表。 | |
data | array<object> | 否 | 用户流量套餐列表。 | |
data[].id | integer | 是 | 用户流量套餐 ID。 | 21 |
data[].uid | integer | 是 | 归属用户 ID。 | 12 |
data[].user_name | string | 否 | 归属用户名。 | demo |
data[].name | string | 是 | 用户流量套餐名称。 | 100 GB 加油包 |
data[].traffic_package_id | integer | 是 | 流量套餐定义 ID。 | 3 |
data[].bind_package | string | 否 | 适用的基础套餐定义 ID,以英文逗号分隔;为空表示不限制。 | 2,3 |
data[].bind_package_name | string | 否 | 适用基础套餐名称的聚合结果。 | 标准套餐,专业套餐 |
data[].amount | string | 是 | 购买流量总量,单位为 GB、TB 或 PB。 | 100GB |
data[].usage | integer | 是 | 已使用流量。 | 1073741824 |
data[].price | number | 否 | 实际购买价格。 | 10 |
data[].orgin_price | number | 否 | 优惠前购买价格。 | 12 |
data[].expire | string | 是 | 流量套餐到期时间,格式 YYYY-MM-DD HH:mm:ss。 | 2026-12-31 23:59:59 |
data[].create_at | string | 否 | 创建时间,格式 YYYY-MM-DD HH:mm:ss。 | 2026-01-01 00:00:00 |
data[].enable | integer enum | 是 | 启用状态。 | 1 |
data[].reason | string | 否 | 禁用原因;启用时通常为空。 | null |
POST /v1/user-traffic-packages
购买一个流量套餐并创建用户流量套餐记录。普通用户只能为自己购买已启用的流量套餐,系统会校验绑定基础套餐、优惠码和账户余额,并按流量套餐有效天数设置到期时间;管理员可为指定用户分配套餐并覆盖名称、适用套餐、流量总量、到期时间及启用状态。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
traffic_package_id | integer | 是 | 必填。要购买或分配的流量套餐定义 ID,必须存在且已启用。 | 3 |
coupon_code | string | 否 | 可选。购买时使用的优惠码;系统会验证该优惠码是否适用于此流量套餐。 | TRAFFIC10 |
uid | integer | 否 | 管理员专用。指定流量套餐归属的用户 ID,必须存在;未传时归属当前用户。 | 12 |
name | string | 否 | 管理员专用。用户流量套餐显示名称;未传时使用流量套餐定义名称,内容会进行 XSS 过滤。 | 客户专属 100 GB 加油包 |
bind_package | string | 否 | 管理员专用。适用的基础套餐定义 ID,以英文逗号分隔;每个 ID 必须存在。空字符串表示不限制基础套餐。 | 2,3 |
amount | string | 否 | 管理员专用。流量总量,必须为数字加 GB、TB 或 PB,例如 50GB。 | 100GB |
expire | string | 否 | 管理员专用。到期时间,格式 YYYY-MM-DD HH:mm:ss;未传时由流量套餐定义的有效天数计算。 | 2026-12-31 23:59:59 |
enable | integer enum | 否 | 管理员专用。启用状态;未传时为 1。设为 0 时必须同时传入 reason。 | 1 |
reason | string | 否 | 管理员专用。当 enable 为 0 时必填,记录禁用原因。 | 人工锁定 |
请求已被处理。成功时 code 为 0、msg 为“用户流量包添加成功”、data 为新建用户流量套餐 ID;流量套餐不可用、绑定套餐不满足、优惠码无效或余额不足时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 用户流量包添加成功 |
data | integer | 是 | 成功时的新建用户流量套餐 ID;失败时为空字符串。 | 21 |
DELETE /v1/user-traffic-packages/{package_id}
删除一个或多个用户流量套餐及其全部流量用量记录。该操作仅管理员可执行;路径参数支持单个 ID 或英文逗号分隔的多个 ID。每个 ID 必须为数字且对应的用户流量套餐必须存在。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | string | 是 | 要删除的用户流量套餐 ID,或以英文逗号分隔的 ID 列表;每一项必须为数字。 | 21,22 |
请求已被处理。成功时 code 为 0、msg 为请求中删除的 ID 字符串、data 为 null;权限不足、ID 格式无效或流量套餐不存在时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 成功时为请求中删除的用户流量套餐 ID 字符串。 | 21,22 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
GET /v1/user-traffic-packages/{package_id}
获取一个已购买流量套餐的详情。普通用户只能查看自己的流量套餐;管理员可查看任意用户的流量套餐。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 要查询的用户流量套餐 ID,必须存在且当前用户有权限查看。 | 21 |
请求已被处理。成功时 data 为用户流量套餐详情;套餐不存在或无权限时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 成功时为空字符串,失败时为错误说明。 | |
data | object | 是 | 用户流量套餐详情。 | |
data.id | integer | 是 | 用户流量套餐 ID。 | 21 |
data.uid | integer | 是 | 归属用户 ID。 | 12 |
data.name | string | 是 | 用户流量套餐名称。 | 100 GB 加油包 |
data.traffic_package_id | integer | 是 | 流量套餐定义 ID。 | 3 |
data.bind_package | string | 否 | 适用的基础套餐定义 ID,以英文逗号分隔;为空表示不限制。 | 2,3 |
data.amount | string | 是 | 购买流量总量,单位为 GB、TB 或 PB。 | 100GB |
data.usage | integer | 是 | 已使用流量。 | 1073741824 |
data.price | number | 否 | 实际购买价格。 | 10 |
data.orgin_price | number | 否 | 优惠前购买价格。 | 12 |
data.expire | string | 是 | 到期时间。 | 2026-12-31 23:59:59 |
data.create_at | string | 否 | 创建时间。 | 2026-01-01 00:00:00 |
data.enable | integer enum | 是 | 启用状态。 | 1 |
data.reason | string | 否 | 禁用原因;启用时通常为空。 | null |
PUT /v1/user-traffic-packages/{package_id}
更新一个用户流量套餐的名称、适用基础套餐、流量总量、到期时间或启用状态。路径接口请求体必须是对象。所有实际可修改字段均要求管理员权限;启用状态设为禁用时必须提供禁用原因。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
package_id | path | integer | 是 | 要更新的用户流量套餐 ID,必须存在。 | 21 |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
traffic_package_id | integer | 否 | 可选。用于校验流量套餐定义存在且已启用;当前更新逻辑不会据此修改已购流量套餐的定义 ID。 | 3 |
name | string | 否 | 管理员专用。用户流量套餐名称;内容会进行 XSS 过滤。 | 客户专属 100 GB 加油包 |
bind_package | string | 否 | 管理员专用。适用的基础套餐定义 ID,以英文逗号分隔;每个 ID 必须存在。空字符串表示不限制基础套餐。 | 2,3 |
amount | string | 否 | 管理员专用。流量总量,必须为数字加 GB、TB 或 PB。 | 200GB |
expire | string | 否 | 管理员专用。到期时间,格式 YYYY-MM-DD HH:mm:ss。 | 2026-12-31 23:59:59 |
enable | integer enum | 否 | 管理员专用。启用状态;设为 0 时必须同时传入 reason。 | 1 |
reason | string | 否 | 管理员专用。当 enable 为 0 时必填,记录禁用原因。 | 人工锁定 |
请求已被处理。成功时 code 为 0、msg 为“更新用户流量包成功”、data 为 null;套餐不存在、权限不足、字段格式无效、适用基础套餐不存在或禁用时未提供原因仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 更新用户流量包成功 |
data | string | 是 | 成功时为 null;失败时为空字符串。 | null |
优惠码、折扣和使用记录。
GET /v1/coupons
分页查询优惠码管理记录,按 ID 倒序返回。该接口需要登录且仅管理员可调用;不提供额外筛选条件。limit=0 时不执行 SQL 分页限制并返回全部记录。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,默认 1。服务端仅校验其为数字;当 limit 不为 0 时偏移量按 (page - 1) × limit 计算。 | |
limit | query | integer(int32) | 否 | 每页记录数,默认 10。传 0 时取消 SQL limit 并返回全部记录。 | |
业务结果使用 HTTP 200 返回。成功响应含 code、count、data,不含 msg 字段;权限、认证或分页参数失败时返回 code、msg、data 业务错误封装。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 符合查询条件的优惠码总数,未受分页限制影响。 | |
oneOf#1.data | array | 是 | 当前页优惠码记录,按 id 倒序排列。 | |
oneOf#1.data | array<object> | 否 | 当前页优惠码记录,按 id 倒序排列。 | |
oneOf#1.data[].id | integer(int64) | 是 | 优惠码记录 ID。 | |
oneOf#1.data[].name | string | 是 | 优惠码管理名称。 | |
oneOf#1.data[].des | string | 是 | 优惠码备注。 | |
oneOf#1.data[].code | string | 是 | 用户兑换时提交的唯一优惠码字符。 | |
oneOf#1.data[].cate | string | 是 | 适用类别,使用英文逗号组合 package(基础套餐)和 traffic(流量包)。 | |
oneOf#1.data[].coupon_type | string enum | 是 | 优惠方式:discount 按折扣值计价,price 使用固定优惠价格。 | discount | price |
oneOf#1.data[].price_gt | integer(int64) | 是 | 可选的原始价格门槛;订单原价不得低于该值才可使用。 | |
oneOf#1.data[].discount_value | number(double) | 是 | coupon_type 为 discount 时使用的折扣值。 | |
oneOf#1.data[].price_value | integer(int64) | 是 | coupon_type 为 price 时使用的固定优惠价格。 | |
oneOf#1.data[].persist_discount | integer enum | 是 | 是否在后续续费中持续使用优惠:1 是,0 否。 | 0 | 1 |
oneOf#1.data[].max_times | integer(int64) | 是 | 最多可使用次数;null 表示不设置次数上限。 | |
oneOf#1.data[].used_times | integer(int64) | 是 | 当前已使用次数。 | |
oneOf#1.data[].package | string | 是 | 适用的基础套餐 ID,多个 ID 使用英文逗号分隔;空字符串表示不限定。 | |
oneOf#1.data[].traffic_package | string | 是 | 适用的流量包 ID,多个 ID 使用英文逗号分隔;空字符串表示不限定。 | |
oneOf#1.data[].start_at | string | 是 | 可选生效起始时间,格式 YYYY-MM-DD HH:mm:ss。 | |
oneOf#1.data[].end_at | string | 是 | 可选失效时间,格式 YYYY-MM-DD HH:mm:ss。 | |
oneOf#1.data[].enable | integer enum | 是 | 启用状态:1 启用,0 禁用。 | 0 | 1 |
oneOf#1.data[].create_at | string | 是 | 优惠码创建时间,格式 YYYY-MM-DD HH:mm:ss。 | |
oneOf#2.code | string enum | 是 | 分页参数格式错误、管理员权限不足或认证失效的业务错误码。 | coupon-3 | coupon-4 | coupon-35 | login_required |
oneOf#2.msg | string | 是 | 分页参数、权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 是 | 优惠码管理名称,不能为空且必须全局唯一。 | |
des | string | 否 | 可选备注;省略时保存为空字符串。 | |
code | string | 是 | 用户兑换时提交的优惠码字符,不能为空且必须全局唯一。 | |
coupon_type | string enum | 是 | 优惠方式:discount 按折扣值计价,price 使用固定优惠价格。 | discount | price |
cate | string | 是 | 生效类别,使用英文逗号组合 package(基础套餐)和 traffic(流量包);不能为空。 | |
price_gt | oneOf | 否 | 可选订单原价门槛。省略、null 或空值表示不限制;提供时必须为整数。 | |
price_gt(oneOf#1) | integer(int64) | 否 | | |
price_gt(oneOf#2) | string | 否 | | |
discount_value | oneOf | 否 | 折扣值。coupon_type=discount 时必填,服务端接受整数或单个小数点的数字文本;其他类型可省略。 | |
discount_value(oneOf#1) | number(double) | 否 | | |
discount_value(oneOf#2) | string | 否 | | |
price_value | oneOf | 否 | 固定优惠价格。coupon_type=price 时必填,且只能为整数;其他类型可省略。 | |
price_value(oneOf#1) | integer(int64) | 否 | | |
price_value(oneOf#2) | string | 否 | | |
max_times | oneOf | 否 | 可选最大使用次数。省略、null 或空值表示不限制;提供时必须为整数。 | |
max_times(oneOf#1) | integer(int64) | 否 | | |
max_times(oneOf#2) | string | 否 | | |
package | string | 否 | 可选适用基础套餐 ID 列表,多个 ID 用英文逗号分隔;每个 ID 必须存在。省略时为空字符串。 | |
traffic_package | string | 否 | 可选适用流量包 ID 列表,多个 ID 用英文逗号分隔;每个 ID 必须存在。省略时为空字符串。 | |
start_at | string | 否 | 可选生效开始时间,格式 YYYY-MM-DD HH:mm:ss;省略、null 或空值表示立即可用。 | |
end_at | string | 否 | 可选失效时间,格式 YYYY-MM-DD HH:mm:ss;省略、null 或空值表示不设置结束时间。 | |
enable | integer enum | 否 | 可选启用状态:1 启用,0 禁用;省略时默认为 1。 | 0 | 1 |
persist_discount | integer enum | 否 | 可选续费持续优惠标记:1 表示后续续费继续享受此优惠,0 表示仅当前购买;省略时默认为 1。 | 0 | 1 |
业务结果使用 HTTP 200 返回。成功时 data 为新优惠码 ID;字段、套餐引用、时间、权限或优惠方式校验失败时返回字符串业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 创建成功提示。 | 优惠码添加成功 |
oneOf#1.data | integer(int64) | 是 | 新建优惠码记录 ID。 | |
oneOf#2.code | string | 是 | 业务错误码,包括字段校验错误 coupon-7 至 coupon-34、管理员权限错误 coupon-37 及认证错误 login_required。 | |
oneOf#2.msg | string | 是 | 字段、套餐引用、时间、权限或优惠方式校验失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
DELETE /v1/coupons/{coupon_id}
按路径中的优惠码 ID 删除记录。路由使用字符串参数,支持以英文逗号传入多个 ID;服务端逐个确认记录存在,任一记录不存在时返回 coupon-1 并回滚本次删除。该接口需要登录且仅管理员可调用。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
coupon_id | path | string | 是 | 要删除的一个或多个优惠码 ID,多个 ID 使用英文逗号分隔。 | |
业务结果使用 HTTP 200 返回。成功时 data 为 null;任一优惠码不存在、管理员权限不足或认证失效时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 删除成功提示。 | 优惠码删除成功 |
oneOf#1.data | object | 是 | 成功时固定为 null。 | |
oneOf#2.code | string enum | 是 | 优惠码不存在、管理员权限不足或认证失效的业务错误码。 | coupon-1 | coupon-36 | login_required |
oneOf#2.msg | string | 是 | 记录或权限校验失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/coupons/{coupon_id}
按优惠码 ID 读取完整数据库记录。该接口需要登录且仅管理员可调用;不存在的优惠码返回 coupon-2 业务错误。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
coupon_id | path | integer(int64) | 是 | 要读取的优惠码记录 ID。 | |
业务结果使用 HTTP 200 返回。成功时返回 coupon 表完整记录;记录不存在、管理员权限不足或认证失效时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 详情读取成功时固定为空字符串。 | |
oneOf#1.data | object | 是 | coupon 表的完整优惠码记录。 | |
oneOf#1.data.id | integer(int64) | 是 | 优惠码记录 ID。 | |
oneOf#1.data.name | string | 是 | 优惠码管理名称。 | |
oneOf#1.data.des | string | 是 | 优惠码备注。 | |
oneOf#1.data.code | string | 是 | 用户兑换时提交的唯一优惠码字符。 | |
oneOf#1.data.cate | string | 是 | 适用类别,以英文逗号组合 package 和 traffic。 | |
oneOf#1.data.coupon_type | string enum | 是 | 优惠方式:discount 为折扣,price 为固定价格。 | discount | price |
oneOf#1.data.price_gt | integer(int64) | 是 | 可选订单原价门槛。 | |
oneOf#1.data.discount_value | number(double) | 是 | discount 方式使用的折扣值。 | |
oneOf#1.data.price_value | integer(int64) | 是 | price 方式使用的固定优惠价格。 | |
oneOf#1.data.persist_discount | integer enum | 是 | 续费是否持续享受优惠:1 是,0 否。 | 0 | 1 |
oneOf#1.data.max_times | integer(int64) | 是 | 最多可使用次数;null 表示不限制。 | |
oneOf#1.data.used_times | integer(int64) | 是 | 已使用次数。 | |
oneOf#1.data.package | string | 是 | 适用基础套餐 ID 列表,多个 ID 用英文逗号分隔。 | |
oneOf#1.data.traffic_package | string | 是 | 适用流量包 ID 列表,多个 ID 用英文逗号分隔。 | |
oneOf#1.data.start_at | string | 是 | 生效开始时间;数据库 datetime 经 JSON 序列化后返回。 | |
oneOf#1.data.end_at | string | 是 | 失效时间;数据库 datetime 经 JSON 序列化后返回。 | |
oneOf#1.data.enable | integer enum | 是 | 启用状态:1 启用,0 禁用。 | 0 | 1 |
oneOf#1.data.create_at | string | 是 | 创建时间;数据库 datetime 经 JSON 序列化后返回。 | |
oneOf#2.code | string enum | 是 | 优惠码不存在、管理员权限不足或认证失效的业务错误码。 | coupon-2 | coupon-35 | login_required |
oneOf#2.msg | string | 是 | 读取或权限失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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_id | path | integer(int64) | 是 | 要更新的优惠码记录 ID。 | |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 否 | 可选的新管理名称;提供时不能为空且必须全局唯一。 | |
des | string | 否 | 可选的新备注;可传空字符串清空。 | |
code | string | 否 | 可选的新兑换字符;提供时不能为空且必须全局唯一。 | |
coupon_type | string enum | 否 | 可选的新优惠方式。变为 discount 时必须有有效 discount_value,变为 price 时必须有有效 price_value。 | discount | price |
cate | string | 否 | 可选生效类别,以英文逗号组合 package 和 traffic。 | |
price_gt | oneOf | 否 | 可选订单原价门槛;传 null 或空值清除门槛,非空值必须为整数。 | |
price_gt(oneOf#1) | integer(int64) | 否 | | |
price_gt(oneOf#2) | string | 否 | | |
discount_value | oneOf | 否 | 可选折扣值。当前或更新后的 coupon_type=discount 时必须保持有效非空数值。 | |
discount_value(oneOf#1) | number(double) | 否 | | |
discount_value(oneOf#2) | string | 否 | | |
price_value | oneOf | 否 | 可选固定优惠价格。当前或更新后的 coupon_type=price 时必须保持有效非空整数。 | |
price_value(oneOf#1) | integer(int64) | 否 | | |
price_value(oneOf#2) | string | 否 | | |
max_times | oneOf | 否 | 可选最大使用次数;传 null 或空值取消次数上限。 | |
max_times(oneOf#1) | integer(int64) | 否 | | |
max_times(oneOf#2) | string | 否 | | |
package | string | 否 | 可选基础套餐 ID 列表;多个 ID 用英文逗号分隔,非空时每个 ID 都必须存在。 | |
traffic_package | string | 否 | 可选流量包 ID 列表;多个 ID 用英文逗号分隔,非空时每个 ID 都必须存在。 | |
start_at | string | 否 | 可选生效开始时间;传 null 或空值清除,非空时格式为 YYYY-MM-DD HH:mm:ss。 | |
end_at | string | 否 | 可选失效时间;传 null 或空值清除,非空时格式为 YYYY-MM-DD HH:mm:ss。 | |
enable | integer enum | 否 | 可选启用状态:1 启用,0 禁用。 | 0 | 1 |
persist_discount | integer enum | 否 | 可选续费持续优惠标记:1 继续享受优惠,0 仅当前购买。 | 0 | 1 |
业务结果使用 HTTP 200 返回。成功时 data 为 null;优惠码不存在、字段/套餐/时间校验失败、没有实际变更、权限不足或认证失效时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 更新成功提示。 | 更新优惠码成功 |
oneOf#1.data | object | 是 | 成功时固定为 null。 | |
oneOf#2.code | string | 是 | 业务错误码,包括记录/字段校验错误 coupon-5 至 coupon-34、管理员权限错误 coupon-37 及认证错误 login_required。 | |
oneOf#2.msg | string | 是 | 记录、字段、套餐、时间、无变更或权限失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/discounts
分页查询全局折扣规则,按 priority 升序返回。该接口需要登录且仅管理员可调用;不支持额外筛选。limit=0 时取消 SQL 分页限制并返回全部记录。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,默认 1。服务端仅校验其为数字;分页偏移按 (page - 1) × limit 计算。 | |
limit | query | integer(int32) | 否 | 每页记录数,默认 10;传 0 时返回全部记录。 | |
业务结果使用 HTTP 200 返回。成功响应含 code、count、data,不含 msg 字段;分页参数、管理员权限或认证失败时返回业务错误封装。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 折扣规则总数,未受分页限制影响。 | |
oneOf#1.data | array | 是 | 当前页折扣规则,按 priority 从小到大排列。 | |
oneOf#1.data | array<object> | 否 | 当前页折扣规则,按 priority 从小到大排列。 | |
oneOf#1.data[].id | integer(int64) | 是 | 折扣规则 ID。 | |
oneOf#1.data[].name | string | 是 | 折扣规则名称。 | |
oneOf#1.data[].des | string | 是 | 规则备注。 | |
oneOf#1.data[].user_group | string | 是 | 适用用户分组 ID,多个 ID 用英文逗号分隔;空字符串表示不限定。 | |
oneOf#1.data[].cate | string enum | 是 | 规则适用对象:基础套餐、升级包或流量包。 | package | package_up | traffic |
oneOf#1.data[].package | string | 是 | 适用基础套餐 ID 列表,多个 ID 用英文逗号分隔。 | |
oneOf#1.data[].package_up | string | 是 | 适用升级包 ID 列表,多个 ID 用英文逗号分隔。 | |
oneOf#1.data[].traffic_package | string | 是 | 适用流量包 ID 列表,多个 ID 用英文逗号分隔。 | |
oneOf#1.data[].dis_type | string enum | 是 | 折扣类型:discount 使用折扣值,price 使用月/季/年固定价格。 | discount | price |
oneOf#1.data[].discount_value | number(double) | 是 | dis_type=discount 时使用的折扣值。 | |
oneOf#1.data[].month_price | integer(int64) | 是 | dis_type=price 时的月付固定价格。 | |
oneOf#1.data[].quarter_price | integer(int64) | 是 | dis_type=price 时的季付固定价格。 | |
oneOf#1.data[].year_price | integer(int64) | 是 | dis_type=price 时的年付固定价格。 | |
oneOf#1.data[].start_at | string | 是 | 可选开始生效时间。 | |
oneOf#1.data[].end_at | string | 是 | 可选结束生效时间。 | |
oneOf#1.data[].priority | integer(int32) | 是 | 规则优先级,数值越小越先匹配。 | |
oneOf#1.data[].enable | integer enum | 是 | 启用状态:1 启用,0 禁用。 | 0 | 1 |
oneOf#1.data[].create_at | string | 是 | 规则创建时间。 | |
oneOf#2.code | string enum | 是 | 分页参数错误、管理员权限不足或认证失效的业务错误码。 | discount-3 | discount-4 | discount-34 | login_required |
oneOf#2.msg | string | 是 | 分页参数、权限或认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
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
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 是 | 折扣规则名称,不能为空且必须全局唯一。 | |
des | string | 否 | 可选备注;省略时保存为空字符串。 | |
user_group | string | 否 | 可选适用用户分组 ID 列表,多个 ID 用英文逗号分隔;非空时每个 ID 都必须存在。省略时不限定用户分组。 | |
cate | string enum | 否 | 可选适用类别:基础套餐、升级包或流量包。省略时保存为空字符串。 | package | package_up | traffic |
package | string | 否 | 可选基础套餐 ID 列表,多个 ID 用英文逗号分隔;非空时每个 ID 都必须存在。 | |
package_up | string | 否 | 可选升级包 ID 列表,多个 ID 用英文逗号分隔;非空时每个 ID 都必须存在。 | |
traffic_package | string | 否 | 可选流量包 ID 列表,多个 ID 用英文逗号分隔;非空时每个 ID 都必须存在。 | |
dis_type | string enum | 是 | 价格方式:discount 使用 discount_value;price 使用月、季、年固定价格。 | discount | price |
discount_value | oneOf | 否 | 折扣值。dis_type=discount 时必填,接受整数或单个小数点数字文本;其他方式可省略。 | |
discount_value(oneOf#1) | number(double) | 否 | | |
discount_value(oneOf#2) | string | 否 | | |
month_price | oneOf | 否 | 月付固定价格。dis_type=price 时必填且必须为整数;其他方式可省略。 | |
month_price(oneOf#1) | integer(int64) | 否 | | |
month_price(oneOf#2) | string | 否 | | |
quarter_price | oneOf | 否 | 季付固定价格。dis_type=price 时必填且必须为整数;其他方式可省略。 | |
quarter_price(oneOf#1) | integer(int64) | 否 | | |
quarter_price(oneOf#2) | string | 否 | | |
year_price | oneOf | 否 | 年付固定价格。dis_type=price 时必填且必须为整数;其他方式可省略。 | |
year_price(oneOf#1) | integer(int64) | 否 | | |
year_price(oneOf#2) | string | 否 | | |
start_at | string | 否 | 可选开始生效时间,格式 YYYY-MM-DD HH:mm:ss;省略、null 或空值表示立即生效。 | |
end_at | string | 否 | 可选结束生效时间,格式 YYYY-MM-DD HH:mm:ss;省略、null 或空值表示不设置结束时间。 | |
enable | integer enum | 否 | 可选启用状态:1 启用,0 禁用;省略时默认为 1。 | 0 | 1 |
priority | oneOf | 否 | 可选优先级,必须为数字;数值越小越先匹配,省略时默认为 100。 | |
priority(oneOf#1) | integer(int32) | 否 | | |
priority(oneOf#2) | string | 否 | |
业务结果使用 HTTP 200 返回。成功时 data 为新折扣规则 ID;字段、引用套餐/分组、时间、权限或价格方式校验失败时返回字符串业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 创建成功提示。 | 折扣添加成功 |
oneOf#1.data | integer(int64) | 是 | 新建折扣规则 ID。 | |
oneOf#2.code | string | 是 | 业务错误码,包括字段校验错误 discount-7 至 discount-33、管理员权限错误 discount-36 及认证错误 login_required。 | |
oneOf#2.msg | string | 是 | 字段、引用对象、时间、权限或价格方式校验失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
DELETE /v1/discounts/{discount_id}
按路径中的折扣规则 ID 删除记录。路由使用字符串参数,支持以英文逗号传入多个 ID;服务端逐个确认记录存在,任一记录不存在时返回 discount-1 并回滚本次删除。该接口需要登录且仅管理员可调用。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
discount_id | path | string | 是 | 要删除的一个或多个折扣规则 ID,多个 ID 使用英文逗号分隔。 | |
业务结果使用 HTTP 200 返回。成功时 data 为 null;任一折扣规则不存在、管理员权限不足或认证失效时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 删除成功提示。 | 折扣删除成功 |
oneOf#1.data | object | 是 | 成功时固定为 null。 | |
oneOf#2.code | string enum | 是 | 折扣规则不存在、管理员权限不足或认证失效的业务错误码。 | discount-1 | discount-35 | login_required |
oneOf#2.msg | string | 是 | 记录或权限校验失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/discounts/{discount_id}
按折扣规则 ID 读取 discount 表完整记录。该接口需要登录且仅管理员可调用;不存在的记录返回 discount-2 业务错误。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
discount_id | path | integer(int64) | 是 | 要读取的折扣规则 ID。 | |
业务结果使用 HTTP 200 返回。成功时返回 discount 表完整记录;记录不存在、管理员权限不足或认证失效时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 详情读取成功时固定为空字符串。 | |
oneOf#1.data | object | 是 | discount 表的完整折扣规则记录。 | |
oneOf#1.data.id | integer(int64) | 是 | 折扣规则 ID。 | |
oneOf#1.data.name | string | 是 | 折扣规则名称。 | |
oneOf#1.data.des | string | 是 | 规则备注。 | |
oneOf#1.data.user_group | string | 是 | 适用用户分组 ID 列表。 | |
oneOf#1.data.cate | string enum | 是 | 适用对象类别。 | package | package_up | traffic |
oneOf#1.data.package | string | 是 | 适用基础套餐 ID 列表。 | |
oneOf#1.data.package_up | string | 是 | 适用升级包 ID 列表。 | |
oneOf#1.data.traffic_package | string | 是 | 适用流量包 ID 列表。 | |
oneOf#1.data.dis_type | string enum | 是 | 价格方式。 | discount | price |
oneOf#1.data.discount_value | number(double) | 是 | discount 方式使用的折扣值。 | |
oneOf#1.data.month_price | integer(int64) | 是 | price 方式使用的月付固定价格。 | |
oneOf#1.data.quarter_price | integer(int64) | 是 | price 方式使用的季付固定价格。 | |
oneOf#1.data.year_price | integer(int64) | 是 | price 方式使用的年付固定价格。 | |
oneOf#1.data.start_at | string | 是 | 生效开始时间;数据库 datetime 经 JSON 序列化后返回。 | |
oneOf#1.data.end_at | string | 是 | 生效结束时间;数据库 datetime 经 JSON 序列化后返回。 | |
oneOf#1.data.priority | integer(int32) | 是 | 优先级,数值越小越先匹配。 | |
oneOf#1.data.enable | integer enum | 是 | 启用状态:1 启用,0 禁用。 | 0 | 1 |
oneOf#1.data.create_at | string | 是 | 创建时间;数据库 datetime 经 JSON 序列化后返回。 | |
oneOf#2.code | string enum | 是 | 规则不存在、管理员权限不足或认证失效的业务错误码。 | discount-2 | discount-34 | login_required |
oneOf#2.msg | string | 是 | 读取或权限失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
PUT /v1/discounts/{discount_id}
更新指定折扣规则的已提交字段;路径 discount_id 会覆盖请求体中的 id。所有业务字段均可选,未提交字段保持原值,但请求必须实际改变至少一个字段,否则返回 discount-32。更新后的 dis_type 仍决定折扣值或月/季/年价格的必填组合。该接口需要登录且仅管理员可调用。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
discount_id | path | integer(int64) | 是 | 要更新的折扣规则 ID。 | |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
name | string | 否 | 可选的新规则名称;提供时不能为空且必须全局唯一。 | |
des | string | 否 | 可选的新备注;可传空字符串清空。 | |
user_group | string | 否 | 可选适用用户分组 ID 列表;多个 ID 用英文逗号分隔,非空时每个 ID 必须存在。 | |
cate | string enum | 否 | 可选适用类别。 | package | package_up | traffic |
package | string | 否 | 可选基础套餐 ID 列表;非空时每个 ID 必须存在。 | |
package_up | string | 否 | 可选升级包 ID 列表;非空时每个 ID 必须存在。 | |
traffic_package | string | 否 | 可选流量包 ID 列表;非空时每个 ID 必须存在。 | |
dis_type | string enum | 否 | 可选价格方式。更新后为 discount 时必须保留有效 discount_value;为 price 时必须保留有效月、季、年价格。 | discount | price |
discount_value | oneOf | 否 | 可选折扣值。当前或更新后的 dis_type=discount 时必须保持有效非空数值。 | |
discount_value(oneOf#1) | number(double) | 否 | | |
discount_value(oneOf#2) | string | 否 | | |
month_price | oneOf | 否 | 可选月付固定价格。当前或更新后的 dis_type=price 时必须保持有效非空整数。 | |
month_price(oneOf#1) | integer(int64) | 否 | | |
month_price(oneOf#2) | string | 否 | | |
quarter_price | oneOf | 否 | 可选季付固定价格。当前或更新后的 dis_type=price 时必须保持有效非空整数。 | |
quarter_price(oneOf#1) | integer(int64) | 否 | | |
quarter_price(oneOf#2) | string | 否 | | |
year_price | oneOf | 否 | 可选年付固定价格。当前或更新后的 dis_type=price 时必须保持有效非空整数。 | |
year_price(oneOf#1) | integer(int64) | 否 | | |
year_price(oneOf#2) | string | 否 | | |
start_at | string | 否 | 可选开始生效时间;传 null 或空值清除,非空时格式为 YYYY-MM-DD HH:mm:ss。 | |
end_at | string | 否 | 可选结束生效时间;传 null 或空值清除,非空时格式为 YYYY-MM-DD HH:mm:ss。 | |
enable | integer enum | 否 | 可选启用状态:1 启用,0 禁用。 | 0 | 1 |
priority | oneOf | 否 | 可选优先级,必须为数字;数值越小越先匹配。 | |
priority(oneOf#1) | integer(int32) | 否 | | |
priority(oneOf#2) | string | 否 | |
业务结果使用 HTTP 200 返回。成功时 data 为 null;记录不存在、字段/引用对象/时间校验失败、无实际变更、权限不足或认证失效时返回业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 更新成功提示。 | 更新折扣成功 |
oneOf#1.data | object | 是 | 成功时固定为 null。 | |
oneOf#2.code | string | 是 | 业务错误码,包括记录/字段校验错误 discount-5 至 discount-33、管理员权限错误 discount-36 及认证错误 login_required。 | |
oneOf#2.msg | string | 是 | 记录、字段、引用对象、时间、无变更或权限失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
订单
GET /v1/order/count
按订单创建时间的日、月或年分组,统计每组订单金额。接口要求登录。普通用户固定统计自身订单;管理员可传 uid 统计指定用户或不传 uid 统计全量。`count` 是匹配的时间分组数量,不是订单总数量。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
group_by | query | string | 否 | 时间分组粒度,默认 day。 | |
type | query | string | 否 | 订单类型精确筛选,服务端不限制枚举。 | |
state | query | string | 否 | 订单状态精确筛选。 | |
start | query | string | 否 | 创建时间下界;只有同时传 end 才生效,直接由数据库比较。 | 2026-01-01 00:00:00 |
end | query | string | 否 | 创建时间上界(不含);只有同时传 start 才生效。 | 2026-02-01 00:00:00 |
uid | query | integer | 否 | 仅管理员有效:用户 ID 筛选,普通用户传入时被忽略。 | 12 |
page | query | integer | 否 | 分组结果页码,默认 1。服务端未额外校验格式。 | |
limit | query | integer | 否 | 每页分组数,默认 10;传字符串 0 时不分页。服务端未额外校验格式。 | |
成功和业务错误均返回 HTTP 200。金额在数据库中以分存储,接口按 `amount / 100` 求和、截断到两位小数并以字符串返回。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 订单金额分组统计查询成功时固定为 0。 | 0 |
oneOf#1.count | integer | 是 | 未分页的时间分组数量。 | |
oneOf#1.data | array | 是 | 当前页分组金额,未显式指定排序。 | |
oneOf#1.data | array<object> | 否 | 当前页分组金额,未显式指定排序。 | |
oneOf#1.data[].time | string | 是 | 按 group_by 格式化的时间键:YYYY-MM-DD、YYYY-MM 或 YYYY。 | |
oneOf#1.data[].sum | string | 是 | 该时间组金额总和,单位为元,截断两位小数。 | 12.34 |
oneOf#2.code | string enum | 是 | state 非法、group_by 非法或认证失败的业务错误码。 | order-5 | order-6 | login_required |
oneOf#2.msg | string | 是 | 订单状态、统计粒度或认证失败的具体原因。 | |
oneOf#2.data | string enum | 是 | 发生业务错误时固定返回空字符串。 | |
GET /v1/orders
分页查询订单,按订单 ID 倒序返回。接口要求登录。普通用户仅查询自身订单;管理员可传 uid 查询指定用户,或不传 uid 查询全部。`total` 为匹配订单 amount 的总和,保持数据库以分为单位的整数值。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer | 否 | 页码,必须为数字,默认 1。 | |
limit | query | integer | 否 | 每页条数,必须为数字,默认 10;传 0 时不分页。 | |
uid | query | integer | 否 | 仅管理员有效:用户 ID 精确筛选。 | 12 |
type | query | string | 否 | 订单类型精确筛选。 | |
state | query | string | 否 | 订单状态精确筛选。 | |
start | query | string | 否 | 创建时间下界,直接交给数据库比较。 | 2026-01-01 00:00:00 |
end | query | string | 否 | 创建时间上界(不含),直接交给数据库比较。 | 2026-02-01 00:00:00 |
成功及参数/认证错误均返回 HTTP 200。列表成功响应不含 msg。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 订单列表查询成功时固定为 0。 | 0 |
oneOf#1.count | integer | 是 | 未分页的匹配订单数。 | |
oneOf#1.total | integer | 是 | 匹配订单 amount 总和,单位为分;无订单时数据库可能返回 null。 | |
oneOf#1.data | array | 是 | 当前页订单。 | |
oneOf#1.data | array<object> | 否 | 当前页订单。 | |
oneOf#1.data[].id | integer | 是 | 订单 ID。 | |
oneOf#1.data[].uid | integer | 是 | 订单所属用户 ID。 | |
oneOf#1.data[].type | string | 是 | 订单类型。 | |
oneOf#1.data[].des | string | 是 | 订单描述。 | |
oneOf#1.data[].data | string | 是 | 订单业务数据文本。 | |
oneOf#1.data[].amount | integer | 是 | 订单金额,单位为分。 | |
oneOf#1.data[].real_amount | integer | 是 | 实付金额,单位为分。 | |
oneOf#1.data[].pay_type | string | 是 | 付款方式。 | |
oneOf#1.data[].mch_order_no | string | 是 | 商户订单号。 | |
oneOf#1.data[].transaction_id | string | 是 | 支付交易号。 | |
oneOf#1.data[].state | string | 是 | 订单状态。 | |
oneOf#1.data[].create_at | string | 是 | 格式化创建时间,YYYY-MM-DD HH:mm:ss。 | |
oneOf#1.data[].pay_at | string | 是 | 格式化付款时间,YYYY-MM-DD HH:mm:ss。 | |
oneOf#2.code | string enum | 是 | page/limit 格式、state 非法或认证失败的业务错误码。 | order-1 | order-2 | order-4 | login_required |
oneOf#2.msg | string | 是 | 分页参数、订单状态或认证失败的具体原因。 | |
oneOf#2.data | string enum | 是 | 发生业务错误时固定返回空字符串。 | |
POST /v1/orders
以管理员身份为指定用户人工创建一条订单记录。接口会校验用户是否存在;订单金额以系统最小货币单位保存,订单说明会经过 XSS 过滤。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
uid | integer | 是 | 订单所属用户 ID;必须对应现有用户。 | 12 |
type | string | 是 | 订单类型,由调用方按业务场景填写。 | 充值 |
des | string | 否 | 订单说明;服务端会进行 XSS 过滤。未传时保存为空字符串。 | 账户余额充值 |
create_at | string(date-time) | 否 | 订单创建时间,格式为 `YYYY-MM-DD HH:mm:ss`;未传时服务端尝试使用当前时间。 | 2026-07-28 10:30:00 |
pay_at | string(date-time) | 否 | 付款时间,格式为 `YYYY-MM-DD HH:mm:ss`;未传时使用当前时间。 | 2026-07-28 10:30:00 |
amount | integer | 否 | 订单应付金额,可为负数;以系统最小货币单位保存。未传时为 0。 | 10000 |
real_amount | integer | 否 | 订单实付金额,可为负数;以系统最小货币单位保存。未传时为 0。 | 10000 |
pay_type | string | 是 | 付款方式。 | manual |
mch_order_no | string | 否 | 支付渠道的商户订单号;未传时保存为空字符串。 | MANUAL-20260728-0001 |
transaction_id | string | 否 | 支付渠道交易流水号;未传时保存为空字符串。 | TXN-20260728-0001 |
state | string | 否 | 订单状态;未传时默认为“已付款”。 | 已付款 |
订单创建成功,`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.code | integer | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 订单添加成功 |
oneOf#1.data | integer | 是 | 新创建订单的自增 ID。 | 1201 |
oneOf#2.code | string | 是 | 业务错误码。 | order-5 |
oneOf#2.msg | string | 是 | 错误原因。 | 用户ID 12不存在 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
DELETE /v1/orders/{order_id}
以管理员身份删除一个或多个订单。路径参数使用英文逗号分隔多个订单 ID;服务端会逐个确认订单存在,并在同一事务中执行删除。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
order_id | path | string | 是 | 一个订单 ID,或以英文逗号分隔的多个订单 ID。 | 501,502 |
指定订单删除成功后返回的标准业务响应。 未登录、非管理员、维护模式限制或订单不存在时仍返回 HTTP 200。`code` 可能为 `login_required`、`maintain`、`order-15` 或 `order-1`。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 订单删除成功 |
oneOf#1.data | string | 是 | 该操作未返回订单对象。 | |
oneOf#2.code | string | 是 | 业务错误码。 | order-1 |
oneOf#2.msg | string | 是 | 错误原因。 | 订单不存在 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
GET /v1/orders/{order_id}
获取当前登录用户的一条订单。服务端始终以订单 ID 和当前登录用户 ID 联合查询;即使管理员登录,也不能通过此接口查看其他用户的订单。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
order_id | path | integer | 是 | 要查询的订单 ID。 | 501 |
成功、未登录和订单不存在/无权限均返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 获取成功 |
oneOf#1.data | object | 是 | 订单记录。 | |
oneOf#1.data.id | integer | 是 | 订单 ID。 | |
oneOf#1.data.uid | integer | 是 | 订单所属用户 ID。 | |
oneOf#1.data.type | string | 是 | 订单类型。 | |
oneOf#1.data.des | string | 是 | 订单说明。 | |
oneOf#1.data.data | string | 是 | 订单关联的业务数据文本。 | |
oneOf#1.data.create_at | string | 是 | 订单创建时间;由数据库日期时间字段序列化返回。 | |
oneOf#1.data.pay_at | string | 是 | 订单付款时间;由数据库日期时间字段序列化返回。 | |
oneOf#1.data.amount | integer | 是 | 订单应付金额,单位为系统最小货币单位。 | |
oneOf#1.data.real_amount | integer | 是 | 订单实付金额,单位为系统最小货币单位。 | |
oneOf#1.data.pay_type | string | 是 | 付款方式。 | |
oneOf#1.data.mch_order_no | string | 是 | 支付渠道商户订单号。 | |
oneOf#1.data.transaction_id | string | 是 | 支付渠道交易流水号。 | |
oneOf#1.data.state | string | 是 | 订单状态。 | |
oneOf#2.code | string enum | 是 | 订单不存在、无权访问或未登录时的业务错误码。 | order-3 | login_required |
oneOf#2.msg | string | 是 | 错误原因。 | 订单不存在或无权限 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
PUT /v1/orders/{order_id}
以管理员身份更新指定订单。路径中的订单 ID 会覆盖请求体中的同名字段;未传的可更新字段保持原值,至少应提供一个与原值不同的字段。订单说明会经过 XSS 过滤。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
order_id | path | integer | 是 | 要更新的订单 ID。 | 501 |
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
uid | integer | 否 | 订单所属用户 ID;传入时必须对应现有用户。 | 12 |
type | string | 否 | 订单类型;传入时不能为空。 | 充值 |
des | string | 否 | 订单说明;服务端会进行 XSS 过滤。 | 账户余额充值 |
create_at | string(date-time) | 否 | 订单创建时间,格式为 `YYYY-MM-DD HH:mm:ss`。 | 2026-07-28 10:30:00 |
pay_at | string(date-time) | 否 | 订单付款时间,格式为 `YYYY-MM-DD HH:mm:ss`。 | 2026-07-28 10:30:00 |
amount | integer | 否 | 订单应付金额,可为负数;以系统最小货币单位保存。 | 10000 |
real_amount | integer | 否 | 订单实付金额,可为负数;以系统最小货币单位保存。 | 10000 |
pay_type | string | 否 | 付款方式;传入时不能为空。 | manual |
mch_order_no | string | 否 | 支付渠道商户订单号。 | MANUAL-20260728-0001 |
transaction_id | string | 否 | 支付渠道交易流水号。 | TXN-20260728-0001 |
state | string | 否 | 订单状态。 | 已付款 |
订单字段更新成功后返回的标准业务响应。 鉴权或校验失败时仍返回 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.code | integer enum | 是 | 业务状态码;0 表示成功。 | 0 |
oneOf#1.msg | string | 是 | 业务提示。 | 更新订单成功 |
oneOf#1.data | string | 是 | 该操作未返回订单对象。 | |
oneOf#2.code | string | 是 | 业务错误码。 | order-12 |
oneOf#2.msg | string | 是 | 错误原因。 | 数据未更改 |
oneOf#2.data | string | 是 | 错误响应中的固定空字符串。 | |
支付
POST /v1/alipay/preorder
为当前登录用户创建支付宝余额充值预订单。充值金额必须以字符串提交,可使用整数或最多两位小数;服务端会根据系统充值限制检查实名认证或企业认证状态,并按后台配置的支付宝通道生成支付地址或易支付提交参数。接口会同时创建一条金额以分为单位、状态为“未付款”的充值订单;只有后续支付回调验签成功后才会增加账户余额。不同支付通道返回的数据结构不同,调用方应按返回字段选择跳转或表单提交方式。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
amount | string | 是 | 充值金额,单位为元。必须是非负数字字符串,可不带小数或保留一至两位小数;不接受负号、千位分隔符或超过两位小数。 | |
业务结果通过 HTTP 200 返回。创建成功时,官方支付宝和码支付通道返回支付地址、系统订单 ID 及通道实收金额,易支付通道返回需要提交到支付网关的签名表单字段;金额格式、认证限制、通道未开通或支付网关下单失败时返回字符串业务错误码。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,充值预订单创建成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 充值预订单写入并取得支付地址后返回的确认消息。 | 订单创建成功 |
oneOf#1.data | object | 是 | 官方支付宝 PC、面对面付或码支付通道的预下单结果。 | |
oneOf#1.data.qr_code_url | string | 是 | 支付地址。PC 通道返回带签名参数的支付宝跳转 URL,面对面付或码支付通道返回可生成二维码的支付内容。 | |
oneOf#1.data.order_id | integer(int64) | 是 | 本系统创建的未付款充值订单 ID。 | |
oneOf#1.data.money | oneOf | 是 | 支付通道确认的实收金额;码支付通道返回字符串或数字,官方支付宝通道尚未确认实收金额时为 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.code | integer enum | 是 | 成功状态码,易支付预订单创建成功时固定为 0。 | 0 |
oneOf#2.msg | string enum | 是 | 易支付预订单写入并生成签名参数后返回的确认消息。 | 订单创建成功 |
oneOf#2.data | object | 是 | 客户端需要以表单方式提交给易支付网关的完整参数。 | |
oneOf#2.data.url | string | 是 | 客户端应提交支付表单的易支付网关地址,已包含 `/submit.php`。 | |
oneOf#2.data.pid | string | 是 | 后台配置的易支付商户 ID。 | |
oneOf#2.data.type | string enum | 是 | 易支付通道类型,支付宝充值固定为 `alipay`。 | alipay |
oneOf#2.data.out_trade_no | string | 是 | 发送给易支付网关的商户订单号,以 `cy` 开头,并与本系统未付款订单关联。 | |
oneOf#2.data.notify_url | string | 是 | 支付完成后由易支付服务器调用的异步通知地址。 | |
oneOf#2.data.return_url | string | 是 | 支付完成后浏览器跳回的前端地址。 | |
oneOf#2.data.name | string | 是 | 支付网关展示的订单名称,由系统名称和“余额充值”组成。 | |
oneOf#2.data.money | string | 是 | 提交给易支付网关的充值金额字符串,与请求中的 `amount` 一致。 | |
oneOf#2.data.sitename | string | 是 | 支付网关展示的站点名称,取自系统名称配置。 | |
oneOf#2.data.sign | string | 是 | 按字段名排序并拼接商户密钥后计算的 MD5 签名。 | |
oneOf#2.data.sign_type | string enum | 是 | 易支付表单使用的签名算法,固定为 `MD5`。 | MD5 |
oneOf#3.code | string 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.msg | string | 是 | 与业务错误码对应的中文金额、认证状态、通道配置或支付网关错误原因。 | |
oneOf#3.data | string enum | 是 | 业务错误时固定为空字符串。 | |
POST /v1/wxpay/preorder
为当前登录用户创建余额充值订单,并按后台配置调用原生微信支付、CodePay 或 Cccyun 微信支付渠道。系统会根据充值限制要求个人实名认证、二次实名认证或企业认证;成功后订单状态为未付款,支付回调到账后才会增加余额。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
amount | string | 是 | 必填。充值金额,必须是非负数字字符串;可带小数点,且最多两位小数。 | 10.00 |
请求已被处理。成功时返回支付二维码、支付网关表单参数或订单 ID;金额格式无效、未开通微信支付、未满足认证限制或第三方下单失败时仍返回 HTTP 200。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer | 是 | 业务状态码;成功为 0。 | 0 |
msg | string | 是 | 处理结果说明。 | 订单创建成功 |
data | object | 是 | 支付渠道返回的预支付数据。原生微信和 CodePay 返回 code_url、order_id、money;Cccyun 返回提交支付网关所需参数。 | |
data.code_url | string | 否 | 原生微信或 CodePay 的付款二维码链接。 | weixin://wxpay/bizpayurl?pr=demo |
data.order_id | integer | 否 | 本系统创建的充值订单 ID;Cccyun 渠道不返回该字段。 | 101 |
data.money | string | 否 | CodePay 或 Cccyun 返回的支付金额;原生微信支付通常为 null。 | 10.00 |
data.url | string | 否 | Cccyun 支付网关提交地址。 | https://pay.example.invalid/submit.php |
data.pid | string | 否 | Cccyun 商户标识。 | demo-merchant |
data.type | string | 否 | Cccyun 支付方式,固定为 wxpay。 | wxpay |
data.out_trade_no | string | 否 | 商户订单号。 | cy202601010001 |
data.notify_url | string | 否 | 支付回调地址。 | https://master.example.invalid/v1/wxpay/notify |
data.return_url | string | 否 | 付款完成后的返回地址。 | https://master.example.invalid/pay-result |
data.name | string | 否 | 订单商品名称。 | Cdnfly余额充值 |
data.sitename | string | 否 | 站点名称。 | Cdnfly |
data.sign | string | 否 | Cccyun 请求签名。 | sanitized-signature |
data.sign_type | string | 否 | 签名算法,固定为 MD5。 | MD5 |
本组包含以下接口,点击卡片进入详情。
网站访问、安全和实时监控。
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。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
start | query | string | 是 | 查询起始时间(含),格式 `YYYY-MM-DD HH:mm:ss`。 | 2026-01-01 00:00:00 |
end | query | string | 是 | 查询结束时间(不含),格式 `YYYY-MM-DD HH:mm:ss`。 | 2026-01-01 01:00:00 |
host | query | string | 否 | 空格分隔的网站域名。普通用户的每个域名必须属于自己;通配符网站可匹配对应子域名。 | www.example.invalid api.example.invalid |
server_port | query | string | 否 | 源站服务端口,必须为合法端口。 | 443 |
addr | query | string | 否 | 客户端 IP 精确筛选,必须为合法 IP。 | 192.0.2.10 |
uid | query | integer | 否 | 仅管理员有效:用户 ID 精确筛选。普通用户传入时被忽略。管理员未传时不添加 uid 筛选。 | 12 |
req_uri | query | string | 否 | 请求 URI,必须以 `/` 开头。匹配方式由 uri_match_type 决定。 | /assets/app.js |
uri_match_type | query | string | 否 | URI 匹配方式:`exact` 精确匹配(默认);`prefix` 以前缀匹配并将 URI 转小写、去除末尾 `/`。 | |
status | query | string | 否 | 三位 HTTP 状态码精确筛选。 | 200 |
node_id | query | string | 否 | 节点 ID(日志字段 nid),必须为数字。 | 1001 |
cache_status | query | string | 否 | 缓存状态精确筛选。 | |
method | query | string | 否 | HTTP 方法精确筛选,仅允许 1 至 10 个英文字母。 | GET |
tls_fp | query | string | 否 | JA4 TLS 指纹,必须为 36 个字母、数字或下划线。 | t13d4907h2_0d8feac7bc37_7395dae3b2f3 |
country | query | string | 否 | 国家名称精确筛选。 | |
province | query | string | 否 | 省份名称精确筛选。 | |
city | query | string | 否 | 城市名称精确筛选。 | |
isp | query | string | 否 | 运营商名称精确筛选。 | |
referer | query | string | 否 | Referer 精确筛选。 | |
page | query | integer | 否 | 页码,默认 1。服务端最多查询前 1000 条,超过范围时会调整页码。 | |
limit | query | integer | 否 | 每页条数,默认 10;服务端会将超过 100 的值压缩为 100。 | |
get_count | query | string | 否 | 任意非空值均启用仅计数模式;启用时不返回日志数组。 | 1 |
成功、筛选参数错误和认证/网站归属错误均返回 HTTP 200。普通查询的总数由日志库返回,查询体设置 `track_total_hits=1000`。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 仅统计匹配数量时成功状态固定为 0。 | 0 |
oneOf#1.data | integer | 是 | 仅 get_count 非空时返回的匹配日志数量。 | |
oneOf#2.code | integer enum | 是 | 访问日志列表查询成功时固定为 0。 | 0 |
oneOf#2.count | integer | 是 | 当前筛选条件下日志库返回的匹配总数。 | |
oneOf#2.data | array | 是 | 当前页日志,按 time 倒序。 | |
oneOf#2.data | array<object> | 否 | 当前页日志,按 time 倒序。 | |
oneOf#2.data[]._id | string | 是 | 日志文档 ID。 | |
oneOf#2.data[].tls_fp | string | 是 | TLS 指纹,缺失时为空字符串。 | |
oneOf#2.data[].host2 | string | 是 | 附加 Host 字段,缺失时为空字符串。 | |
oneOf#2.data[].country | string | 是 | 国家,缺失时为空字符串。 | |
oneOf#2.data[].province | string | 是 | 省份,缺失时为空字符串。 | |
oneOf#2.data[].city | string | 是 | 城市,缺失时为空字符串。 | |
oneOf#2.data[].nid | string | 是 | 节点 ID。 | |
oneOf#2.data[].status | string | 是 | HTTP 状态码。 | |
oneOf#2.data[].protocol | string | 是 | 请求协议。 | |
oneOf#2.data[].addr | string | 是 | 客户端 IP。 | |
oneOf#2.data[].bytes_sent | integer | 是 | 响应发送字节数。 | |
oneOf#2.data[].cache_status | string | 是 | 缓存状态。 | |
oneOf#2.data[].up_resp_time | object | 是 | 上游响应耗时,保持日志库原始类型。 | |
oneOf#2.data[].host | string | 是 | 请求 Host。 | |
oneOf#2.data[].server_port | object | 是 | 源站端口;日志缺失时为空字符串。 | |
oneOf#2.data[].referer | string | 是 | Referer。 | |
oneOf#2.data[].user_agent | string | 是 | User-Agent。 | |
oneOf#2.data[].content_type | string | 是 | 响应 Content-Type。 | |
oneOf#2.data[].time | string | 是 | 日志时间字段。 | |
oneOf#2.data[].req_uri | string | 是 | 请求 URI。 | |
oneOf#2.data[].up_recv | object | 是 | 上游接收字节数,保持日志库原始类型。 | |
oneOf#2.data[].method | string | 是 | HTTP 方法。 | |
oneOf#2.data[].timestamp | object | 是 | Elasticsearch sort 时间戳,保持原始类型。 | |
oneOf#2.data[].sip | string | 是 | 源站 IP,缺失时为空字符串。 | |
oneOf#2.data[].l1_cache_status | string | 是 | 一级缓存状态,缺失时为空字符串。 | |
oneOf#2.data[].l2_cache_status | string | 是 | 二级缓存状态,缺失时为空字符串。 | |
oneOf#2.data[].l2_ip | string | 是 | 二级节点 IP,缺失时为空字符串。 | |
oneOf#2.data[].lat | object | 是 | 纬度,缺失时为空字符串。 | |
oneOf#2.data[].lng | object | 是 | 经度,缺失时为空字符串。 | |
oneOf#2.data[].isp | string | 是 | 运营商,缺失时为空字符串。 | |
oneOf#3.code | string 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.msg | string | 是 | 访问日志查询参数校验或认证失败的具体原因。 | |
oneOf#3.data | string enum | 是 | 发生业务错误时固定返回空字符串。 | |
GET /v1/monitor/site/access-log/{id}
按 Elasticsearch 文档 ID 获取访问日志的请求头、响应头和请求体。接口要求登录。普通用户仅能读取日志中 uid 与自身相同的记录;管理员可读取任何记录。当前服务端直接取查询结果首项,日志 ID 不存在时没有标准业务错误封装,可能返回服务端异常。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
id | path | string | 是 | 访问日志 Elasticsearch 文档 ID。 | |
成功和普通用户越权均使用 HTTP 200。缺失的 `req_header`、`resp_header` 或 `req_body` 统一返回空字符串。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 0 表示查询成功。 | 0 |
oneOf#1.msg | string enum | 是 | 成功时固定为空字符串。 | |
oneOf#1.data | object | 是 | 指定访问日志记录中保存的原始请求与响应内容。 | |
oneOf#1.data.req_header | oneOf | 是 | 日志原始请求头;字段未记录时为空字符串。对象形式的键为 HTTP 头名称、值为对应头值。 | |
oneOf#1.data.req_header(oneOf#1) | string | 否 | | |
oneOf#1.data.resp_header | oneOf | 是 | 日志原始响应头;字段未记录时为空字符串。对象形式的键为 HTTP 头名称、值为对应头值。 | |
oneOf#1.data.resp_header(oneOf#1) | string | 否 | | |
oneOf#1.data.req_body | string | 是 | 日志原始请求体;字段未记录时为空字符串。 | |
oneOf#2.code | string enum | 是 | 普通用户访问其他用户日志或认证失败时返回。 | access_log_detail-1 | login_required |
oneOf#2.msg | string | 是 | 权限不足或认证失败的具体原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时为空字符串。 | |
GET /v1/monitor/site/blackip
查询日志库中仍有效(`exp >= 当前 Unix 时间戳`)的网站黑名单 IP,按创建时间倒序返回。接口要求登录。普通用户固定按自身 uid 过滤;管理员不加 uid 限制。传 `action=export` 时不返回 JSON,而下载去重后的 IP 文本。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer | 否 | 页码,必须为数字,默认 1。 | |
limit | query | integer | 否 | 每页条数,必须为数字,默认 10;服务端将超过 300 的值压缩为 300。 | |
ip | query | string | 否 | 黑名单 IP 精确筛选,服务端不额外校验格式。 | 192.0.2.10 |
filter_name | query | string | 否 | 黑名单日志字段 `filter` 的精确筛选值;名称历史上保留为 filter_name,通常为 CC 过滤器 ID。 | 8 |
site_id | query | string | 否 | 网站 ID 精确筛选,服务端不额外校验格式。 | 123 |
action | query | string | 否 | 传 `export` 时导出全部匹配的唯一 IP,每行一个;其他值按普通 JSON 查询处理。 | |
普通查询成功时返回 JSON;导出成功时返回 text/plain 附件 `black_ip.txt`。日志查询异常、分页参数错误或认证失败仍可返回 HTTP 200 的业务错误封装。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 黑名单列表查询成功时固定为 0。 | 0 |
oneOf#1.count | integer | 是 | 所有匹配且未过期的记录总数。 | |
oneOf#1.data | array | 是 | 当前页黑名单记录。 | |
oneOf#1.data | array<object> | 否 | 当前页黑名单记录。 | |
oneOf#1.data[].position | string | 是 | 黑名单位置描述;日志未记录时为空字符串。 | |
oneOf#1.data[].site_id | string | 是 | 日志中的网站 ID 原始值。 | |
oneOf#1.data[].ip | string | 是 | 被封禁 IP。 | |
oneOf#1.data[].fname | string | 是 | 日志中的 filter 原始值,通常为 CC 过滤器 ID。 | |
oneOf#1.data[].domain | string | 是 | 网站域名;无法解析网站时回退为 site_id 原始值。 | |
oneOf#1.data[].name | string | 是 | 关联 CC 过滤器名称;无法解析时为 null。 | |
oneOf#1.data[].create_at | object | 是 | 黑名单创建时间,保持日志库原始类型。 | |
oneOf#1.data[].exp | object | 是 | 过期时间,Unix 时间戳,保持日志库原始类型。 | |
oneOf#2.code | string enum | 是 | page/limit 格式、日志库查询错误或认证失败的业务错误码。 | black_ip-1 | black_ip-2 | black_ip-3 | login_required |
oneOf#2.msg | string | 是 | 筛选参数、日志查询或认证失败的具体原因。 | |
oneOf#2.data | string enum | 是 | 发生业务错误时固定返回空字符串。 | |
GET /v1/monitor/site/blackip-count
按 `site_id` 聚合黑名单日志的文档数。接口要求登录且不接受查询参数。普通用户仅聚合自身 uid 的记录,管理员聚合全部记录。注意:该接口不筛选 `exp`,因此计数可能包含已过期黑名单;日志库 terms 聚合最多返回 100 个网站桶。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
成功时返回 HTTP 200 的统计数组。当前服务端未对日志库查询异常做业务错误转换。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer enum | 是 | 0 表示聚合成功。 | 0 |
count | integer | 是 | 返回的网站聚合桶数量,不是黑名单总记录数。 | |
data | array | 是 | 按日志库 terms 聚合返回的网站统计,最多 100 项。 | |
data | array<object> | 否 | 按日志库 terms 聚合返回的网站统计,最多 100 项。 | |
data[].site_id | object | 是 | 日志中的网站 ID 原始值,类型由日志库决定。 | |
data[].count | integer | 是 | 该网站对应的黑名单日志文档数,包含已过期记录。 | |
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_id | path | integer | 是 | 访问日志下载任务(job)ID。 | |
下载成功时返回 gzip 二进制附件;响应的 Content-Disposition 文件名为 `{host}-{job_id}.log.gz` 或 `{job_id}.log.gz`。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
(root) | string(binary) | 否 | gzip 压缩的访问日志文件。 | |
任务存在但不属于当前登录用户。响应为中文纯文本 `无权限`。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
(root) | string | 否 | |
任务不存在、任务尚未完成或已生成文件被清理。响应为中文纯文本。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
(root) | string | 否 | |
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。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer | 否 | 页码,必须为数字,默认 1。 | |
limit | query | integer | 否 | 每页条数,必须为数字,默认 10。action=export 时服务端忽略该值并查询全部。 | |
uid | query | integer | 否 | 仅管理员有效:按黑名单所属用户 ID 精确筛选;普通用户传入时仍仅查询自身。 | 12 |
ip | query | string | 否 | 黑名单 IP 精确筛选。 | 192.0.2.10 |
site_id | query | integer | 否 | 网站 ID 精确筛选。 | 123 |
start | query | string | 否 | 创建时间下界;只有同时传 end 才生效,直接交给数据库比较。 | 2026-01-01 00:00:00 |
end | query | string | 否 | 创建时间上界(不含);只有同时传 start 才生效,直接交给数据库比较。 | 2026-01-02 00:00:00 |
action | query | string | 否 | 传 export 时下载所有匹配 IP 的去重文本;其他值按普通查询处理。 | |
普通查询返回 JSON;导出返回 text/plain 附件。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | integer enum | 是 | 历史黑名单列表查询成功时固定为 0。 | 0 |
count | integer | 是 | 未应用分页前的匹配历史记录总数。 | |
data | array | 是 | 当前页历史黑名单。 | |
data | array<object> | 否 | 当前页历史黑名单。 | |
data[].site_id | integer | 是 | 网站 ID。 | |
data[].ip | string | 是 | 被封禁 IP。 | |
data[].filter | string | 是 | 关联 CC 过滤器 ID 原始值。 | |
data[].uid | integer | 是 | 黑名单所属用户 ID。 | |
data[].exp | object | 是 | 过期时间,保持数据库原始类型。 | |
data[].create_at | string(date-time) | 是 | 创建时间。 | |
data[].position | string | 是 | 黑名单位置描述。 | |
data[].auto_unlock | integer enum | 是 | 自动解锁标记的数据库布尔值。 | 0 | 1 |
data[].domain | string | 是 | 关联网站域名;网站不存在时为空。 | |
data[].fname | string | 是 | 关联 CC 过滤器名称;过滤器不存在时为空。 | |
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。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
type | query | string | 是 | 监控指标类型。 | |
start | query | string | 是 | 开始时间(含),格式 `YYYY-MM-DD HH:mm:ss`,按 +08:00 解释。 | 2026-01-01 00:00:00 |
end | query | string | 是 | 结束时间(不含),格式 `YYYY-MM-DD HH:mm:ss`。 | 2026-01-01 01:00:00 |
domain | query | string | 否 | 空格分隔的网站域名精确筛选。普通用户每个域名都必须属于自己。 | www.example.invalid api.example.invalid |
server_port | query | string | 否 | 源站端口精确筛选,必须为合法端口。 | 443 |
成功及参数、域名权限错误均返回 HTTP 200。日志库未返回聚合时 data 为空数组。时间戳为 Elasticsearch date_histogram 桶键(通常为 Unix 毫秒时间戳)。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 网站实时指标查询成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 实时指标查询成功时固定为空字符串。 | |
oneOf#1.data | array | 是 | 除 status-4xx/status-5xx 外,元素为 [时间戳, 指标值]。bandwidth 和 backend-bandwidth 为每秒字节数;traffic/backend-traffic 为字节总量;req 为请求数;qps 为每秒请求数;backend-resp-time 为平均源站响应时间;两个缓存类型为 0 至 100 的命中百分比。状态码类型时元素改为分组对象。 | |
oneOf#1.data | array<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).name | string | 是 | 4xx 或 5xx HTTP 状态码。 | |
oneOf#1.data[](oneOf#2).value | array | 是 | 该状态码完整时间序列。 | |
oneOf#1.data[](oneOf#2).value | array<array> | 否 | 该状态码完整时间序列。 | |
oneOf#2.code | string enum | 是 | 缺少/不支持指标、缺少时间、域名无权限、日期格式、跨度超过限制、端口错误或认证失败的业务错误码。 | realtime-1 | realtime-2 | realtime-3 | realtime-5 | realtime-6 | realtime-7 | realtime-8 | realtime-9 | realtime-11 | login_required |
oneOf#2.msg | string | 是 | 实时指标参数、权限或时间范围校验失败的具体原因。 | |
oneOf#2.data | string enum | 是 | 发生业务错误时固定返回空字符串。 | |
GET /v1/monitor/site/top
按 IP、国家、省份、运营商、URL、域名端口、TLS 指纹或 Referer 聚合访问日志。需要登录;普通用户仅查询自己的 uid 且传入域名必须属于自己,管理员查询全量。榜单条数由系统 `res_rank_size` 配置决定。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
type | query | string | 是 | 排行维度。 | |
recent_time | query | string | 否 | 最近时间窗口;提供时忽略 start/end,仅支持 10m、30m、60m。 | |
start | query | string | 否 | 自定义开始时间(含);未传 recent_time 时与 end 一同必填,格式 YYYY-MM-DD HH:mm:ss,跨度不超过 1.5 小时。 | 2026-01-01 00:00:00 |
end | query | string | 否 | 自定义结束时间(不含);未传 recent_time 时与 start 一同必填。 | 2026-01-01 01:00:00 |
domain | query | string | 否 | 空格分隔域名筛选;普通用户只能传自身域名。 | www.example.invalid |
server_port | query | string | 否 | 源站端口精确筛选,必须为合法端口。 | 443 |
cc | query | string | 否 | 攻击流量模式:0(默认)全部流量;1 仅统计窗口内出现过 HTTP 444 的 IP。管理员生成攻击 IP 候选集时不应用域名和端口筛选。 | |
成功、参数和域名权限错误均返回 HTTP 200。日志库异常或无聚合时成功返回空数组。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 网站资源排行查询成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 网站资源排行查询成功时固定为空字符串。 | |
oneOf#1.data | array | 是 | 排行数据。 | |
oneOf#1.data | array<object> | 否 | 排行数据。 | |
oneOf#1.data[].traffic | number | 是 | bytes_sent 总和。 | |
oneOf#1.data[].up_recv | number | 是 | up_recv 总和。 | |
oneOf#1.data[].count | integer | 是 | 请求文档数。 | |
oneOf#1.data[].res | string | 是 | 资源值:IP、地理字段、运营商、URL、域名端口、TLS 指纹或 Referer,由 type 决定。 | |
oneOf#2.code | string 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.msg | string | 是 | 排行类型、时间范围、域名权限或认证失败的具体原因。 | |
oneOf#2.data | string enum | 是 | 发生业务错误时固定返回空字符串。 | |
套餐与流量用量统计。
GET /v1/monitor/usage
按小时或按天聚合带宽、流量、请求数或黑名单数量。接口要求登录。普通用户固定查询自身 uid;管理员可选 uid 查询指定用户或全量。未指定 `res` 时从套餐汇总表查询,指定 `res` 时从资源明细表查询。普通用户没有任何 user_package 时直接成功返回空数组。时间范围达到 7 天时按天汇总,否则按小时汇总。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
type | query | string | 是 | 用量指标。 | |
start | query | string(date) | 是 | 开始日期(含),格式 YYYY-MM-DD。 | 2026-01-01 |
end | query | string(date) | 是 | 结束日期(不含),格式 YYYY-MM-DD。 | 2026-01-08 |
uid | query | integer | 否 | 仅管理员有效:用户 ID 筛选;普通用户传入时被忽略。 | 12 |
res | query | string | 否 | 空格分隔的资源标识。提供后改从 res_count 明细表查询并按这些 res 精确过滤;未提供时从 res_count_package 套餐汇总表查询。 | www.example.invalid |
user_package | query | string | 否 | 空格分隔的用户套餐 ID,仅允许数字。 | 101 102 |
cate | query | string | 否 | 服务类别筛选。 | |
成功与参数/认证错误均返回 HTTP 200。普通指标返回 data 数组;带宽返回相同 data 并额外带有 max_value、max_95_value。跨 7 天以上查询带宽时,按天结果是当天各小时汇总带宽的最大值,而非总和。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 按小时或天查询用量序列成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 用量序列查询成功时固定为空字符串。 | |
oneOf#1.data | array | 是 | 时间序列。 | |
oneOf#1.data | array<object> | 否 | 时间序列。 | |
oneOf#1.data[].date | string | 是 | 小时查询格式 YYYY-MM-DD HH:00:00,天查询格式 YYYY-MM-DD。 | |
oneOf#1.data[].value | number | 是 | 聚合指标值。 | |
oneOf#2.code | integer enum | 是 | 带宽统计用量查询成功时固定为 0。 | 0 |
oneOf#2.msg | string enum | 是 | 带宽统计用量查询成功时固定为空字符串。 | |
oneOf#2.data | array | 是 | 带宽统计模式下按小时返回的用量序列。 | |
oneOf#2.data | array<object> | 否 | 带宽统计模式下按小时返回的用量序列。 | |
oneOf#2.data[].date | string | 是 | 带宽统计小时,格式为 YYYY-MM-DD HH:00:00。 | |
oneOf#2.data[].value | number | 是 | 该小时聚合得到的带宽用量数值。 | |
oneOf#2.max_value | number | 是 | 仅 bandwidth:所有小时汇总值中的最大值。 | |
oneOf#2.max_95_value | number | 是 | 仅 bandwidth:服务端按降序索引 `len*5/100+1` 取得的 95 值。 | |
oneOf#3.code | string 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.msg | string | 是 | 用量类型、日期、统计粒度、套餐标识或认证失败的具体原因。 | |
oneOf#3.data | string enum | 是 | 发生业务错误时固定返回空字符串。 | |
GET /v1/monitor/usage-count
从 `res_count_package` 套餐汇总表计算指定日期范围内的峰值带宽、流量、请求数及黑名单数。接口要求登录。普通用户固定查询自身 uid;管理员可用 uid 查询指定用户或不传 uid 查询全部。带宽值为范围内按小时汇总后的最大值,其余三个值为范围内总和。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
start | query | string(date) | 是 | 开始日期(含),格式 YYYY-MM-DD。 | 2026-01-01 |
end | query | string(date) | 是 | 结束日期(不含),格式 YYYY-MM-DD。 | 2026-01-08 |
uid | query | integer | 否 | 仅管理员有效:按用户 ID 统计。普通用户传入时被忽略。 | 12 |
成功、日期参数错误和认证错误均返回 HTTP 200。范围内没有匹配记录时四项数值均为 0。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 网站用量汇总查询成功时固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 网站用量汇总查询成功时固定为空字符串。 | |
oneOf#1.data | object | 是 | 指定时间范围内网站带宽、流量、请求和黑名单汇总值。 | |
oneOf#1.data.bandwidth_value | number | 是 | 范围内小时带宽汇总的最大值。 | |
oneOf#1.data.traffic_value | number | 是 | 范围内流量总和。 | |
oneOf#1.data.req_value | number | 是 | 范围内请求数总和。 | |
oneOf#1.data.blackip_value | number | 是 | 范围内黑名单计数总和。 | |
oneOf#2.code | string enum | 是 | 缺少/格式错误日期或认证失败的业务错误码。 | monitor-usage-count-2 | monitor-usage-count-3 | monitor-usage-count-7 | monitor-usage-count-8 | login_required |
oneOf#2.msg | string | 是 | 日期参数格式错误或认证失败的具体原因。 | |
oneOf#2.data | string enum | 是 | 发生业务错误时固定返回空字符串。 | |
消息
GET /v1/messages
分页查询站内消息摘要和当前查询用户的已读状态,按 sort 降序、消息 ID 降序返回。普通用户只可查询展示中的、按当前服务端 receive 条件归属自己的消息;管理员可查询全部消息,也可用 receive 切换为指定接收用户视角。列表响应不包含消息正文 content,正文需通过 GET /v1/messages/{message_id} 获取。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,默认 1。服务端仅校验为数字,分页偏移为 (page - 1) × limit。 | |
limit | query | integer(int32) | 否 | 每页记录数,默认 10;传 0 时返回全部匹配记录。 | |
type | query | string | 否 | 精确筛选消息类型。当前消息创建接口只允许 announcement;服务端对非 announcement 类型会在普通用户或指定 receive 时额外按接收用户过滤。 | announcement |
receive | query | integer(int64) | 否 | 仅管理员可用。指定消息接收用户 ID,并按该用户视角关联已读状态;普通用户传入会被拒绝。 | |
is_show | query | integer | 否 | 仅管理员有效:精确筛选展示状态,必须为数字。普通用户始终只查询 is_show=1 的消息。 | |
user_package_id | query | integer(int64) | 否 | 精确筛选关联的用户套餐 ID。 | |
site_id | query | integer(int64) | 否 | 精确筛选关联的网站 ID。 | |
业务结果使用 HTTP 200 返回。成功响应包含 code、count、data,不含 msg;页码、每页数量、is_show 格式或 receive 权限错误时返回业务错误封装。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 当前权限和筛选条件下、未应用分页前的消息总数。 | |
oneOf#1.data | array | 是 | 当前页消息摘要,按 sort 降序、id 降序排列。 | |
oneOf#1.data | array<object> | 否 | 当前页消息摘要,按 sort 降序、id 降序排列。 | |
oneOf#1.data[].user_package_id | integer(int64) | 否 | 关联的用户套餐 ID;未关联时为 null。 | |
oneOf#1.data[].site_id | integer(int64) | 否 | 关联的网站 ID;未关联时为 null。 | |
oneOf#1.data[].receive | integer(int64) | 否 | 消息指定接收用户 ID;null 表示未指定单个接收者。 | |
oneOf#1.data[].uid | integer(int64) | 否 | 当前查询用户在 message_read 中的用户 ID;非 null 表示该用户已读此消息,null 表示未读。 | |
oneOf#1.data[].id | integer(int64) | 是 | 消息 ID。 | |
oneOf#1.data[].type | string | 是 | 消息类型。 | |
oneOf#1.data[].title | string | 是 | 消息标题。 | |
oneOf#1.data[].is_show | boolean | 是 | 是否在消息列表中展示。 | |
oneOf#1.data[].is_red | boolean | 是 | 是否使用红色强调样式。 | |
oneOf#1.data[].is_bold | boolean | 是 | 是否使用粗体强调样式。 | |
oneOf#1.data[].url | string | 是 | 外部消息跳转地址;非外部消息通常为空字符串。 | |
oneOf#1.data[].is_external | boolean | 是 | 是否为外部链接消息;为 true 时客户端应使用 url,不使用正文。 | |
oneOf#1.data[].is_popup | boolean | 是 | 是否要求客户端以弹窗方式展示。 | |
oneOf#1.data[].sort | integer(int32) | 是 | 排序值,值越大越靠前。 | |
oneOf#1.data[].create_at2 | string | 是 | 格式化后的创建时间,格式为 YYYY-MM-DD HH:mm:ss。 | |
oneOf#1.data[].update_at2 | string | 是 | 格式化后的更新时间,格式为 YYYY-MM-DD HH:mm:ss。 | |
oneOf#2.code | string enum | 是 | page、limit、is_show 参数错误,receive 需要管理员权限或认证失败的业务错误码。 | message-19 | message-20 | message-21 | message-33 | login_required |
oneOf#2.msg | string | 是 | 具体错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
POST /v1/messages
以当前管理员身份创建一条或多条站内消息。仅管理员可调用;发布者自动取当前登录用户,不能由请求指定。请求可为一个消息对象或非空消息对象数组,服务端依次创建并返回逗号分隔的消息 ID。当前实现仅允许消息类型 announcement。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.type | string enum | 是 | 必填。消息类型,当前仅支持 announcement。 | announcement |
oneOf#1.title | string | 是 | 必填。消息标题,不能为空。 | |
oneOf#1.content | string | 否 | 普通消息必填。站内消息正文;当 is_external=1 时可以省略,服务端保存为空字符串。 | |
oneOf#1.is_external | integer enum | 否 | 是否为外部链接消息:0 为站内正文消息,1 为外部链接消息。为 1 时 url 必填。 | 0 | 1 |
oneOf#1.url | string | 否 | 外部链接消息必填。跳转地址;普通消息可省略,默认空字符串。 | |
oneOf#1.is_show | integer enum | 否 | 是否展示:1 为展示,0 为隐藏。 | 0 | 1 |
oneOf#1.is_red | integer enum | 否 | 是否使用红色强调样式:1 为使用,0 为不使用。 | 0 | 1 |
oneOf#1.is_bold | integer enum | 否 | 是否使用粗体强调样式:1 为使用,0 为不使用。 | 0 | 1 |
oneOf#1.is_popup | integer enum | 否 | 是否要求客户端弹窗展示:1 为是,0 为否。 | 0 | 1 |
oneOf#1.sort | integer(int32) | 否 | 排序值,值越大越靠前;未提供时默认 100。服务端要求仅含数字。 | |
oneOf#2 | array<object> | 否 | 批量创建消息的对象数组。服务端按数组顺序创建,返回的 ID 顺序与此一致。 | |
oneOf#2[].type | string enum | 是 | 消息类型。 | announcement |
oneOf#2[].title | string | 是 | 非空消息标题。 | |
oneOf#2[].content | string | 否 | 非外部消息的正文。 | |
oneOf#2[].is_external | integer enum | 否 | 外部消息标记,1 时必须提供 url。 | 0 | 1 |
oneOf#2[].url | string | 否 | 外部消息跳转地址。 | |
oneOf#2[].is_show | integer enum | 否 | 展示标记。 | 0 | 1 |
oneOf#2[].is_red | integer enum | 否 | 红色样式标记。 | 0 | 1 |
oneOf#2[].is_bold | integer enum | 否 | 粗体样式标记。 | 0 | 1 |
oneOf#2[].is_popup | integer enum | 否 | 弹窗展示标记。 | 0 | 1 |
oneOf#2[].sort | integer | 否 | 排序值。 | |
业务结果使用 HTTP 200 返回。成功时 data 为逗号分隔的新增消息 ID;非管理员、请求格式、字段校验或外部链接/正文条件不满足时返回业务错误封装。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 创建成功提示。 | 消息添加成功 |
oneOf#1.data | string | 是 | 新建消息 ID,批量创建时以英文逗号分隔。 | |
oneOf#2.code | string 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.msg | string | 是 | 具体错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
POST /v1/messages/read
将一条或多条消息标记为当前登录用户已读。接口要求登录。对同一消息重复调用不会新增重复已读记录;服务端只校验消息是否存在,不会额外校验消息是否属于当前用户可见范围。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.id | integer | 是 | 要标记已读的消息 ID。服务端检查该消息记录存在。 | 101 |
oneOf#2 | array<object> | 否 | 批量标记的消息对象数组。服务端允许空数组并直接返回成功;实际调用应至少提供一个对象。 | |
oneOf#2[].id | integer | 是 | 消息 ID。 | 101 |
成功及业务错误均返回 HTTP 200。缺少消息 ID 或消息不存在时,响应会保留现有的 code 与 msg 字段取值顺序,调用方应同时依据两字段处理失败结果。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 0 表示全部消息均已标记。 | 0 |
oneOf#1.msg | string enum | 是 | 成功提示。 | 消息已读 |
oneOf#1.data | object | 是 | 成功时为 null。 | |
oneOf#2.code | string enum | 是 | 缺少 ID、消息不存在或认证失败的实际业务错误标识;前两种值来自服务端的参数顺序。 | 请提供id | 找不到此消息 | login_required |
oneOf#2.msg | string enum | 是 | 实际业务错误消息;前两种为服务端写入的错误标识。 | message_read-2 | message_read-3 | 需要登录 |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/messages/sub
查询当前登录用户的消息订阅记录。接口要求登录,不支持筛选参数;每条记录对应一个消息类型的邮件和短信接收开关。没有订阅记录时返回空数组。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
成功与认证错误均返回 HTTP 200。成功时 `data` 为当前用户的 `message_sub` 表记录数组。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 0 表示查询成功。 | 0 |
oneOf#1.msg | string enum | 是 | 成功提示。 | 获取订阅成功 |
oneOf#1.data | array | 是 | 当前用户的订阅记录;表中没有匹配记录时为空数组。 | |
oneOf#1.data | array<object> | 否 | 当前用户的订阅记录;表中没有匹配记录时为空数组。 | |
oneOf#1.data[].uid | integer | 是 | 订阅所属用户 ID,固定为当前登录用户。 | 12 |
oneOf#1.data[].msg_type | string | 是 | 订阅的消息类型。 | announcement |
oneOf#1.data[].phone | integer enum | 是 | 短信订阅开关的数据库布尔值:1 开启,0 关闭;未设置时为空。 | 0 | 1 |
oneOf#1.data[].email | integer enum | 是 | 邮件订阅开关的数据库布尔值:1 开启,0 关闭;未设置时为空。 | 0 | 1 |
oneOf#2.code | string enum | 是 | 未登录或登录会话无效时的业务错误码。 | login_required |
oneOf#2.msg | string | 是 | 认证失败原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时为空字符串。 | |
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_type | string | 是 | 要更新的消息类型;服务端不限制枚举值,必须与已有订阅记录的类型匹配才会实际更新。 | announcement |
oneOf#1.phone | integer enum | 否 | 可选。短信订阅开关:1 开启,0 关闭。 | 0 | 1 |
oneOf#1.email | integer enum | 否 | 可选。邮件订阅开关:1 开启,0 关闭。 | 0 | 1 |
oneOf#2 | array<object> | 否 | 批量更新对象数组。服务端允许空数组并返回成功;实际调用应至少提交一项。 | |
oneOf#2[].msg_type | string | 是 | 消息类型。 | |
oneOf#2[].phone | integer enum | 否 | 短信订阅开关。 | 0 | 1 |
oneOf#2[].email | integer enum | 否 | 邮件订阅开关。 | 0 | 1 |
成功及业务错误均返回 HTTP 200。注意:当前服务端中三个 `client_error` 调用的参数顺序与通用约定相反,缺少 `msg_type` 或开关值非法时,中文原因出现在 `code`,错误标识出现在 `msg`。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 0 表示处理完成。 | 0 |
oneOf#1.msg | string enum | 是 | 成功提示。 | 订阅已更新 |
oneOf#1.data | object | 是 | 成功时为 null,不返回更新后的订阅记录。 | |
oneOf#2.code | string enum | 是 | 缺少消息类型、phone/email 值非法或认证失败的实际错误标识;前三种来自服务端的参数顺序。 | 请提供msg_type | phone值错误 | email值错误 | login_required |
oneOf#2.msg | string enum | 是 | 实际错误消息;前三种为服务端写入的错误标识。 | message_sub-2 | message_sub-4 | message_sub-6 | 需要登录 |
oneOf#2.data | string enum | 是 | 业务错误时为空字符串。 | |
DELETE /v1/messages/{message_id}
删除指定消息及其全部 `message_read` 已读记录。接口要求管理员身份。路径参数是字符串,可传单个消息 ID 或用英文逗号分隔多个 ID;服务端逐个验证 ID 格式和消息存在性,任一项失败时整个事务回滚。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
message_id | path | string | 是 | 单个消息 ID,或英文逗号分隔的多个消息 ID。每个值必须是数字且对应现有消息。 | |
成功和业务错误均返回 HTTP 200。成功时不返回已删除 ID 列表;参数格式错误、消息不存在或权限不足时返回业务错误。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 0 表示所有指定消息均已删除。 | 0 |
oneOf#1.msg | string enum | 是 | 成功提示。 | 消息删除成功 |
oneOf#1.data | object | 是 | 成功时为 null。 | |
oneOf#2.code | string enum | 是 | 分别表示某个 ID 非数字、消息不存在或需要管理员权限。 | message-4 | message-5 | message-30 |
oneOf#2.msg | string | 是 | 具体错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时为空字符串。 | |
GET /v1/messages/{message_id}
按 ID 返回 `message` 表的完整消息记录(包含正文及发送状态字段)。接口要求登录。若消息指定了 `receive` 且其值不是当前用户 ID,则仅管理员可查看;服务端不额外检查 `is_show`,因此已登录用户可读取未指定接收者的隐藏消息详情。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
message_id | path | integer | 是 | 消息 ID。路由只匹配整数;不存在时返回业务错误。 | |
成功、消息不存在、接收者权限不足及认证错误均返回 HTTP 200。成功响应的 `msg` 固定为空字符串。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 0 表示查询成功。 | 0 |
oneOf#1.msg | string enum | 是 | 详情查询成功时固定为空字符串。 | |
oneOf#1.data | object | 是 | 消息表完整记录。布尔数据库字段按 0/1 数值返回。 | |
oneOf#1.data.id | integer | 是 | 消息 ID。 | |
oneOf#1.data.type | string | 是 | 消息类型,例如 announcement。 | |
oneOf#1.data.pub_user | integer | 是 | 发布者用户 ID。 | |
oneOf#1.data.receive | integer | 是 | 指定接收用户 ID;为空表示未指定单个接收者。 | |
oneOf#1.data.title | string | 是 | 消息标题。 | |
oneOf#1.data.content | string | 是 | 站内消息正文;外部链接消息通常为空字符串。 | |
oneOf#1.data.phone_content | string | 是 | 短信发送正文。 | |
oneOf#1.data.templ_id | string | 是 | 消息发送模板 ID。 | |
oneOf#1.data.templ_para | string | 是 | 模板参数文本。 | |
oneOf#1.data.event_id | string | 是 | 关联事件标识。 | |
oneOf#1.data.user_package_id | integer | 是 | 关联用户套餐 ID。 | |
oneOf#1.data.site_id | integer | 是 | 关联网站 ID。 | |
oneOf#1.data.is_show | integer enum | 是 | 展示标记:1 展示,0 隐藏。 | 0 | 1 |
oneOf#1.data.is_red | integer enum | 是 | 红色标题标记。 | 0 | 1 |
oneOf#1.data.is_bold | integer enum | 是 | 粗体标题标记。 | 0 | 1 |
oneOf#1.data.is_external | integer enum | 是 | 外部链接标记:1 使用 url,0 使用 content。 | 0 | 1 |
oneOf#1.data.is_popup | integer enum | 是 | 弹窗显示标记。 | 0 | 1 |
oneOf#1.data.email_need_send | integer enum | 是 | 是否需要发送邮件通知。 | 0 | 1 |
oneOf#1.data.phone_need_send | integer enum | 是 | 是否需要发送短信通知。 | 0 | 1 |
oneOf#1.data.email_is_sent | integer enum | 是 | 邮件是否已发送。 | 0 | 1 |
oneOf#1.data.phone_is_sent | integer enum | 是 | 短信是否已发送。 | 0 | 1 |
oneOf#1.data.url | string | 是 | 外部消息跳转地址。 | |
oneOf#1.data.sort | integer | 是 | 排序值。 | |
oneOf#1.data.create_at | string(date-time) | 是 | 消息创建时间。 | |
oneOf#1.data.update_at | string(date-time) | 是 | 消息更新时间。 | |
oneOf#2.code | string enum | 是 | 分别表示消息不存在、指定接收者消息需要管理员权限或认证失败。 | message-18 | message-32 | login_required |
oneOf#2.msg | string | 是 | 具体错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时为空字符串。 | |
PUT /v1/messages/{message_id}
更新指定消息的可编辑字段。接口要求管理员身份,路径中的 `message_id` 会覆盖请求体可能携带的 `id`。请求体必须为对象;所有业务字段均可省略,空对象也会成功并只更新 `update_at`。更新后的站内消息必须保有非空 `content`,外部链接消息必须保有非空 `url`。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
message_id | path | integer | 是 | 要更新的消息 ID,必须存在。 | |
请求体必填。
Content-Type:application/json
更新字段。`id` 即使传入也会被路径参数替换,建议不要传。所有下列字段均为可选;未传字段保留原值。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
id | integer | 否 | 会被路径 `message_id` 覆盖,不应依赖该值。 | |
type | string enum | 否 | 可选消息类型;提供时只能为 announcement。 | announcement |
title | string | 否 | 可选的新标题;提供时不能为空。 | 维护时间调整 |
content | string | 否 | 可选站内正文。消息最终为非外部链接时必须非空。 | 维护窗口已调整为 01:00 至 02:00。 |
is_external | integer enum | 否 | 可选外部链接标记:1 时最终 url 必须非空;0 时最终 content 必须非空。 | 0 | 1 |
url | string | 否 | 可选外部链接地址。消息最终为外部链接时必须非空。 | https://www.example.invalid/notice |
is_show | integer enum | 否 | 可选展示标记:1 展示,0 隐藏。 | 0 | 1 |
is_red | integer enum | 否 | 可选红色标题样式标记。 | 0 | 1 |
is_bold | integer enum | 否 | 可选粗体标题样式标记。 | 0 | 1 |
is_popup | integer enum | 否 | 可选弹窗展示标记。 | 0 | 1 |
sort | integer | 否 | 可选排序值;服务端要求数字。 | 200 |
成功和业务错误均返回 HTTP 200。更新成功时 `data` 为 null;路径消息不存在、字段校验失败、最终正文/链接条件不满足或非管理员访问时返回业务错误。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 0 表示更新成功。 | 0 |
oneOf#1.msg | string enum | 是 | 成功提示。 | 更新消息成功 |
oneOf#1.data | object | 是 | 成功时为 null。 | |
oneOf#2.code | string 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.msg | string | 是 | 具体错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时为空字符串。 | |
任务
GET /v1/jobs
分页查询当前登录用户创建的任务申请及其关联执行任务状态,按任务申请 ID 倒序返回。可按任务类型、两个业务索引字段和创建时间筛选,limit=0 时返回全部匹配记录。注意:当 type 精确传 backup 时,服务端使用独立查询条件,不再按当前用户 ID 限制结果;该行为按当前 Python 主控实现保留。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,默认 1。服务端仅校验为数字,分页偏移为 (page - 1) × limit。 | |
limit | query | integer(int32) | 否 | 每页记录数,默认 10。传字符串 0 时不附加 SQL limit,返回全部匹配记录。 | |
type | query | string | 否 | 任务类型筛选。可用逗号分隔多个仅含字母、数字、下划线或连字符的类型,例如 clean_url,unlock_ip;精确值 backup 使用特殊查询逻辑,不按当前用户 ID 过滤。 | clean_url,pre_cache_url |
key1 | query | string | 否 | 精确筛选任务申请的 key1 字段。该字段由创建任务时的具体业务类型写入,例如缓存任务的域名。 | |
key2 | query | string | 否 | 精确筛选任务申请的 key2 字段。该字段由创建任务时的具体业务类型写入,例如缓存任务的 URL。 | |
start | query | string | 否 | 创建时间下限,筛选 create_at 大于或等于该值。服务端直接将值交给数据库比较,不在接口层校验格式。 | 2026-01-01 00:00:00 |
end | query | string | 否 | 创建时间上限(不含),筛选 create_at 小于该值。服务端直接将值交给数据库比较,不在接口层校验格式。 | 2026-01-02 00:00:00 |
业务结果使用 HTTP 200 返回。成功响应包含 code、count、data,不含 msg;分页参数、type 格式不正确或登录失效时返回统一业务错误封装。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 当前筛选条件下、未应用分页前的任务申请总数。 | |
oneOf#1.data | array | 是 | 当前页任务申请记录,按 job.id 倒序排列。 | |
oneOf#1.data | array<object> | 否 | 当前页任务申请记录,按 job.id 倒序排列。 | |
oneOf#1.data[].enable | integer | 否 | 关联 task 的启用标记;没有关联执行任务时为 null。 | |
oneOf#1.data[].id | integer(int64) | 是 | 任务申请(job)ID。 | |
oneOf#1.data[].uid | integer(int64) | 是 | 创建该任务申请的用户 ID。 | |
oneOf#1.data[].type | string | 是 | 任务类型,例如 clean_url、clean_dir、pre_cache_url、cancel_task、unlock_ip、clean_white_ip 或 down_http_access_log。 | |
oneOf#1.data[].key1 | string | 否 | 任务业务索引字段 1,具体含义取决于任务类型。 | |
oneOf#1.data[].key2 | string | 否 | 任务业务索引字段 2,具体含义取决于任务类型。 | |
oneOf#1.data[].data | string | 是 | 创建任务时保存的 JSON 文本;接口不解析该字段,具体键由任务类型决定。 | |
oneOf#1.data[].create_at | string(date-time) | 是 | 数据库返回的任务申请创建时间。 | |
oneOf#1.data[].task_id | integer(int64) | 是 | 关联 task 的 ID。 | |
oneOf#1.data[].create_at2 | string | 是 | 格式化后的任务申请创建时间,格式为 YYYY-MM-DD HH:mm:ss。 | |
oneOf#1.data[].end_at | string(date-time) | 否 | 关联 task 的结束时间;任务未结束或无关联任务时为 null。 | |
oneOf#1.data[].state | string | 否 | 关联 task 的执行状态,例如 pending、running、success 或 failed;无关联任务时为 null。 | |
oneOf#1.data[].ret | string | 否 | 关联 task 的返回内容或错误信息;无返回内容时为 null。 | |
oneOf#1.data[].progress | string | 否 | 关联 task 的进度文本;无进度信息时为 null。 | |
oneOf#2.code | string enum | 是 | page 或 limit 格式错误、type 含非法字符或认证失败的业务错误码。 | job-21 | job-22 | job-41 | login_required |
oneOf#2.msg | string | 是 | 具体错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
POST /v1/jobs
提交缓存刷新或预热、IP 解锁、白名单清理、网站访问日志下载等异步任务。需要登录。请求可为一个任务对象或非空任务对象数组;服务端依次校验并在同一事务中创建全部任务,任一项失败会回滚。任务结果和执行状态可通过 GET /v1/jobs 查询。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
请求体必填。
Content-Type:application/json
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.type | string 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.data | object | 是 | 任务参数对象。字段是否必填由 type 决定:缓存类任务必须提供 url;IP 解锁和白名单清理必须提供 site_id;访问日志下载必须提供 start 和 end。 | |
oneOf#1.data.url | string(uri) | 否 | clean_url、clean_dir、pre_cache_url 或 cancel_task 必填。必须是 HTTP/HTTPS URL,域名必须属于当前用户或调用者为管理员;clean_dir 的 URL 必须以 / 结尾。 | |
oneOf#1.data.site_id | integer(int64) | 否 | unlock_ip 或 clean_white_ip 必填。网站 ID;非管理员只能操作自己的网站。unlock_ip 可传 0 表示不绑定具体网站。 | |
oneOf#1.data.ip | string | 否 | unlock_ip 可选。以空白字符分隔的一个或多个待解锁 IP,每个必须是合法 IP;未提供时服务端使用 __all__ 表示解锁全部。单次数量受系统 ip-unlock-max-per-limit 配置限制。 | |
oneOf#1.data.key1 | string | 否 | unlock_ip 或 clean_white_ip 可选的业务索引字段名。前端通常传 site_id,服务端会取 data[key1] 写入任务 key1。 | |
oneOf#1.data.key2 | string | 否 | unlock_ip 或 clean_white_ip 可选的第二业务索引字段名。服务端会取 data[key2] 写入任务 key2。 | |
oneOf#1.data.start | string | 否 | down_http_access_log 必填。日志开始时间,格式必须为 YYYY-MM-DD HH:mm:ss。 | |
oneOf#1.data.end | string | 否 | down_http_access_log 必填。日志结束时间,格式必须为 YYYY-MM-DD HH:mm:ss;结束与开始的间隔不得超过 25 小时。 | |
oneOf#1.data.host | string | 否 | down_http_access_log 可选。以空白字符分隔的域名筛选;非管理员提供的每个域名都必须属于自己。 | |
oneOf#1.data.addr | string | 否 | down_http_access_log 可选。按客户端 IP 筛选,提供时必须为合法 IP。 | |
oneOf#1.data.req_uri | string | 否 | down_http_access_log 可选。按请求 URI 筛选,提供时必须以 / 开头。 | |
oneOf#1.data.status | string | 否 | down_http_access_log 可选。按三位 HTTP 状态码筛选。 | |
oneOf#1.data.cache_status | string enum | 否 | down_http_access_log 可选。缓存状态筛选,只允许 HIT 或 MISS。 | HIT | MISS |
oneOf#1.data.server_port | string | 否 | down_http_access_log 可选。按源端口筛选,提供时必须为数字。 | |
oneOf#1.data.node_id | string | 否 | down_http_access_log 可选。按节点 ID 筛选,提供时必须为数字。 | |
oneOf#2 | array<object> | 否 | 批量提交的任务对象数组。服务端按数组顺序处理,成功响应 data 中的任务 ID 与此顺序一致。 | |
oneOf#2[].type | string enum | 是 | 任务类型。 | clean_url | clean_dir | pre_cache_url | cancel_task | unlock_ip | clean_white_ip | down_http_access_log |
oneOf#2[].data | object | 是 | 任务参数。缓存类使用 url;IP 类使用 site_id、ip、key1/key2;日志下载使用 start/end 及可选筛选字段。 | |
oneOf#2[].data.url | string | 否 | 缓存类任务必填的 HTTP/HTTPS URL;clean_dir 必须以 / 结尾。 | |
oneOf#2[].data.site_id | integer(int64) | 否 | IP 解锁或白名单清理任务必填的网站 ID。 | |
oneOf#2[].data.ip | string | 否 | IP 解锁任务可选的空白分隔 IP 列表。 | |
oneOf#2[].data.key1 | string | 否 | 可选业务索引字段名,常用值 site_id。 | |
oneOf#2[].data.key2 | string | 否 | 可选第二业务索引字段名。 | |
oneOf#2[].data.start | string | 否 | 日志下载必填开始时间,YYYY-MM-DD HH:mm:ss。 | |
oneOf#2[].data.end | string | 否 | 日志下载必填结束时间,YYYY-MM-DD HH:mm:ss,时间范围最多 25 小时。 | |
oneOf#2[].data.host | string | 否 | 日志下载可选域名筛选。 | |
oneOf#2[].data.addr | string | 否 | 日志下载可选 IP 筛选。 | |
oneOf#2[].data.req_uri | string | 否 | 日志下载可选 URI 筛选,必须以 / 开头。 | |
oneOf#2[].data.status | string | 否 | 日志下载可选三位状态码。 | |
oneOf#2[].data.cache_status | string enum | 否 | 日志下载可选缓存状态。 | HIT | MISS |
oneOf#2[].data.server_port | string | 否 | 日志下载可选数字端口。 | |
oneOf#2[].data.node_id | string | 否 | 日志下载可选数字节点 ID。 | |
业务结果使用 HTTP 200 返回。成功时返回新建任务申请 ID 的字符串数组;请求格式、任务类型、业务对象归属、限额或参数校验失败时返回业务错误封装。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.msg | string enum | 是 | 提交成功提示。 | 添加成功 |
oneOf#1.data | array | 是 | 已创建的 job ID 字符串数组,与请求任务顺序一致。 | |
oneOf#1.data | array<string> | 否 | 已创建的 job ID 字符串数组,与请求任务顺序一致。 | |
oneOf#2.code | string 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.msg | string | 是 | 具体错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
用户登录和操作日志。
GET /v1/log/login
分页查询登录记录,按日志 ID 倒序返回。普通用户只能查看自己的记录;管理员可查看所有记录,或使用 uid 仅查看指定用户。支持按登录 IP、成功状态和创建时间筛选,limit=0 时返回全部匹配记录。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,默认 1。服务端仅校验为数字,分页偏移为 (page - 1) × limit。 | |
limit | query | integer(int32) | 否 | 每页记录数,默认 10;传 0 时不附加 SQL limit,返回全部匹配记录。 | |
uid | query | integer(int64) | 否 | 仅管理员有效:精确筛选用户 ID。普通用户传入该参数仍只会查询自己的登录日志。 | |
ip | query | string | 否 | 按登录 IP 进行包含匹配,不要求完整 IP。 | 198.51.100 |
success | query | string | 否 | 精确筛选登录结果。通常传 1 查询成功记录,传 0 查询失败记录;服务端直接将非空值交给数据库比较,不在接口层校验取值。 | |
start | query | string | 否 | 创建时间下限,筛选 create_at 大于或等于该值。服务端直接交给数据库比较。 | 2026-01-01 00:00:00 |
end | query | string | 否 | 创建时间上限(不含),筛选 create_at 小于该值。服务端直接交给数据库比较。 | 2026-01-02 00:00:00 |
业务结果使用 HTTP 200 返回。成功响应含 code、count、data,不含 msg;页码、每页数量或认证失败时返回业务错误封装。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 当前权限和筛选条件下、未应用分页前的登录日志总数。 | |
oneOf#1.data | array | 是 | 当前页登录日志,按 id 倒序排列。 | |
oneOf#1.data | array<object> | 否 | 当前页登录日志,按 id 倒序排列。 | |
oneOf#1.data[].id | integer(int64) | 是 | 登录日志 ID。 | |
oneOf#1.data[].uid | integer(int64) | 是 | 尝试登录的用户 ID;无法对应用户时为 null。 | |
oneOf#1.data[].ip | string | 是 | 客户端登录 IP 地址。 | |
oneOf#1.data[].ip_location | string | 是 | 服务端根据 IP 记录的地理位置,格式通常为 国家-省份-城市。 | |
oneOf#1.data[].success | integer enum | 是 | 登录结果的数据库布尔值:1 为成功,0 为失败;数据库字段为空时为 null。 | 0 | 1 |
oneOf#1.data[].create_at | string | 是 | 格式化后的登录时间,格式为 YYYY-MM-DD HH:mm:ss。 | |
oneOf#1.data[].create_at2 | string | 是 | 与 create_at 相同的格式化登录时间字段,兼容前端展示。 | |
oneOf#2.code | string enum | 是 | page 格式错误、limit 格式错误或认证失败的业务错误码。 | log_login-1 | log_login-2 | login_required |
oneOf#2.msg | string | 是 | 具体错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
GET /v1/log/op
分页查询资源新增、更新和删除等操作日志,按日志 ID 倒序返回。普通用户只能查看自己的操作;管理员可查询全部日志或用 uid 筛选指定用户。支持按 IP、时间、资源类别、操作动作、操作对象和变更内容筛选,limit=0 时返回全部匹配记录。
除文档标明的公共接口外,请在请求头携带 api-key + api-secret,或 access-token。示例主控:https://master.example.com。
| 名称 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
page | query | integer(int32) | 否 | 页码,默认 1。服务端仅校验为数字,分页偏移为 (page - 1) × limit。 | |
limit | query | integer(int32) | 否 | 每页记录数,默认 10;传 0 时不附加 SQL limit,返回全部匹配记录。 | |
uid | query | integer(int64) | 否 | 仅管理员有效:精确筛选操作用户 ID。普通用户提供此参数仍只查询自己的日志。 | |
ip | query | string | 否 | 按客户端 IP 进行包含匹配,不要求完整 IP。 | 198.51.100 |
start | query | string | 否 | 创建时间下限,筛选 create_at 大于或等于该值。服务端直接交给数据库比较。 | 2026-01-01 00:00:00 |
end | query | string | 否 | 创建时间上限(不含),筛选 create_at 小于该值。服务端直接交给数据库比较。 | 2026-01-02 00:00:00 |
type | query | string | 否 | 精确筛选资源类别,即日志中的 type,例如 网站、任务、证书或 ACL。 | |
action | query | string | 否 | 精确筛选操作动作。通用写入逻辑使用 新增、更新、删除。 | |
content | query | string | 否 | 按操作对象内容进行包含匹配,例如资源 ID 或以逗号分隔的资源 ID。 | |
diff | query | string | 否 | 按字段变更内容进行包含匹配。该字段通常保存更新前后差异的文本或 JSON 文本。 | |
业务结果使用 HTTP 200 返回。成功响应含 code、count、data,不含 msg;页码、每页数量或认证失败时返回统一业务错误封装。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
oneOf#1.code | integer enum | 是 | 成功状态码,固定为 0。 | 0 |
oneOf#1.count | integer(int64) | 是 | 当前权限和筛选条件下、未应用分页前的日志总数。 | |
oneOf#1.data | array | 是 | 当前页操作日志,按 id 倒序排列。 | |
oneOf#1.data | array<object> | 否 | 当前页操作日志,按 id 倒序排列。 | |
oneOf#1.data[].id | integer(int64) | 是 | 操作日志 ID。 | |
oneOf#1.data[].uid | integer(int64) | 是 | 执行操作的用户 ID。 | |
oneOf#1.data[].type | string | 是 | 资源类别,例如 网站、任务、证书、ACL。 | |
oneOf#1.data[].action | string | 是 | 操作动作,通用写入逻辑为 新增、更新 或 删除。 | |
oneOf#1.data[].content | string | 是 | 被操作对象的标识文本,通常为资源 ID 或逗号分隔的资源 ID。 | |
oneOf#1.data[].diff | string | 是 | 字段变更详情文本或 JSON 文本;新增、删除操作通常为空。 | |
oneOf#1.data[].ip | string | 是 | 执行操作的客户端 IP。 | |
oneOf#1.data[].ip_location | string | 是 | 服务端根据 IP 记录的地理位置,格式通常为 国家-省份-城市。 | |
oneOf#1.data[].create_at | string(date-time) | 是 | 数据库返回的操作创建时间。 | |
oneOf#1.data[].process | string | 是 | 操作处理标记;通用新增、更新、删除写入时为空字符串。 | |
oneOf#1.data[].create_at2 | string | 是 | 格式化后的操作时间,格式为 YYYY-MM-DD HH:mm:ss。 | |
oneOf#2.code | string enum | 是 | page 格式错误、limit 格式错误或认证失败的业务错误码。 | log_op-1 | log_op-2 | login_required |
oneOf#2.msg | string | 是 | 具体错误原因。 | |
oneOf#2.data | string enum | 是 | 业务错误时固定为空字符串。 | |
本组包含以下接口,点击卡片进入详情。
用户 API 通用响应封装结构。
| 字段 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
code | oneOf | 是 | 0 表示成功;字符串表示业务错误码。 | 0 |
code(oneOf#1) | integer | 否 | | |
code(oneOf#2) | string | 否 | | |
msg | string | 是 | 结果说明。 | |
data | object | 是 | 业务数据;结构以具体接口示例为准。 | |
count | integer(int64) | 否 | 分页查询的总记录数。 | |