## CC 过滤器 (`cc-filters`)

对命中的请求限频或发起挑战(JS、滑块、验证码等)的处理方式。

鉴权: 用户（部分参数仅管理员） · 文档: https://www-demo.kuxitong.com/zh/docs/api/cc-filters

### GET `/api/v2/cc-filters`

列出CC 过滤器 · 鉴权: 用户（部分参数仅管理员）

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | integer |  | 页码,从 1 开始。 默认: 1 |
| `page_size` | integer |  | 每页条数。 默认: 20 |
| `sort` | string |  | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
| `tenant_id` | integer |  | 仅管理员可用:按租户过滤。租户凭据调用时忽略,只返回本租户数据。 |
| `name` | string |  | 按名称包含过滤。 |
| `owner` | string |  | platform = 只看平台对象;tenant = 只看租户对象。 可选值: ["platform","tenant"] |

```sh
curl "https://panel.example.com/api/v2/cc-filters" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/cc-filters`

创建CC 过滤器 · 鉴权: 用户（部分参数仅管理员）

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `count_key` | string |  | 按谁计数(rate/challenge):ip = 按客户端 IP(缺省,现有行为);ja4 = 只按 TLS 指纹计数(不分 IP),同指纹的真实访客会一起计入,所以只许配 log 动作,规则条目配 ban/deny 保存时 422;要处置用 ip_ja4 = 同一 IP 且同一指纹合计。非 HTTPS 请求没有指纹,ja4/ip_ja4 退回按 IP。url_auth 不用,只能是 ip。 可选值: ["ip","ja4","ip_ja4"] |
| `des` | string |  | 备注;不给则为空(修改时不给也清空,整体替换)。 |
| `kind` | string |  | 挑战类型(challenge 必填):js/redirect/slide/captcha/click/delay_jump/rotate/cookie;rate 不带。 |
| `max` | integer | 有 | 窗口内允许的请求数。 |
| `mode` | string |  | url_auth 必填:鉴权方式。a = ?<sign_arg>=md5(密钥+路径+时间戳)&<time_arg>=时间戳;b = ?<sign_arg>=时间戳-随机串-uid-md5(路径-时间戳-随机串-uid-密钥)。 可选值: ["a","b"] |
| `name` | string | 有 | 名称 |
| `per_uri_max` | integer |  | rate:单 URI 上限;0 = 不限。 |
| `sign_arg` | string |  | url_auth 必填:签名参数名(字母、数字、下划线、连字符)。 |
| `sign_use_max` | integer |  | url_auth:同一签名最多用几次;0 = 不限。 |
| `time_arg` | string |  | url_auth 且 mode=a 必填:时间戳参数名;mode=b 不带。 |
| `ttl_s` | integer |  | url_auth 必填(1~2592000):签名时间戳与当前时间最多相差几秒。 |
| `type` | string | 有 | rate = 请求频率;challenge = 挑战(kind 指定类型);url_auth = URL 鉴权(签名密钥取站点 config.url_auth_salt)。 可选值: ["rate","challenge","url_auth"] |
| `window_s` | integer | 有 | 统计窗口秒数。 |

```sh
curl -X POST "https://panel.example.com/api/v2/cc-filters" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max":20,"name":"rate-5-20","per_uri_max":10,"type":"rate","window_s":5}'
```

### GET `/api/v2/cc-filters/{id}`

获取CC 过滤器 · 鉴权: 用户（部分参数仅管理员）

```sh
curl "https://panel.example.com/api/v2/cc-filters/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/cc-filters/{id}`

修改CC 过滤器 · 鉴权: 用户（部分参数仅管理员）

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `count_key` | string |  | 按谁计数(rate/challenge):ip = 按客户端 IP(缺省,现有行为);ja4 = 只按 TLS 指纹计数(不分 IP),同指纹的真实访客会一起计入,所以只许配 log 动作,规则条目配 ban/deny 保存时 422;要处置用 ip_ja4 = 同一 IP 且同一指纹合计。非 HTTPS 请求没有指纹,ja4/ip_ja4 退回按 IP。url_auth 不用,只能是 ip。 可选值: ["ip","ja4","ip_ja4"] |
| `des` | string |  | 备注;不给则为空(修改时不给也清空,整体替换)。 |
| `kind` | string |  | 挑战类型(challenge 必填):js/redirect/slide/captcha/click/delay_jump/rotate/cookie;rate 不带。 |
| `max` | integer | 有 | 窗口内允许的请求数。 |
| `mode` | string |  | url_auth 必填:鉴权方式。a = ?<sign_arg>=md5(密钥+路径+时间戳)&<time_arg>=时间戳;b = ?<sign_arg>=时间戳-随机串-uid-md5(路径-时间戳-随机串-uid-密钥)。 可选值: ["a","b"] |
| `name` | string | 有 | 名称 |
| `per_uri_max` | integer |  | rate:单 URI 上限;0 = 不限。 |
| `sign_arg` | string |  | url_auth 必填:签名参数名(字母、数字、下划线、连字符)。 |
| `sign_use_max` | integer |  | url_auth:同一签名最多用几次;0 = 不限。 |
| `time_arg` | string |  | url_auth 且 mode=a 必填:时间戳参数名;mode=b 不带。 |
| `ttl_s` | integer |  | url_auth 必填(1~2592000):签名时间戳与当前时间最多相差几秒。 |
| `type` | string | 有 | rate = 请求频率;challenge = 挑战(kind 指定类型);url_auth = URL 鉴权(签名密钥取站点 config.url_auth_salt)。 可选值: ["rate","challenge","url_auth"] |
| `window_s` | integer | 有 | 统计窗口秒数。 |

```sh
curl -X PUT "https://panel.example.com/api/v2/cc-filters/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max":20,"name":"rate-5-20","per_uri_max":10,"type":"rate","window_s":5}'
```

### DELETE `/api/v2/cc-filters/{id}`

删除CC 过滤器 · 鉴权: 用户（部分参数仅管理员）

```sh
curl -X DELETE "https://panel.example.com/api/v2/cc-filters/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

CC 过滤器对象:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `builtin` | boolean |  | 内置对象,不可删。 (只读) |
| `count_key` | string |  | 按谁计数(rate/challenge):ip = 按客户端 IP(缺省,现有行为);ja4 = 只按 TLS 指纹计数(不分 IP),同指纹的真实访客会一起计入,所以只许配 log 动作,规则条目配 ban/deny 保存时 422;要处置用 ip_ja4 = 同一 IP 且同一指纹合计。非 HTTPS 请求没有指纹,ja4/ip_ja4 退回按 IP。url_auth 不用,只能是 ip。 可选值: ["ip","ja4","ip_ja4"] |
| `created_at` | string |  | 创建时间 (只读) |
| `des` | string |  | 备注;不给则为空(修改时不给也清空,整体替换)。 |
| `id` | integer |  | 记录 ID (只读) |
| `kind` | string |  | 挑战类型(challenge 必填):js/redirect/slide/captcha/click/delay_jump/rotate/cookie;rate 不带。 |
| `max` | integer |  | 窗口内允许的请求数。 |
| `mode` | string |  | url_auth 必填:鉴权方式。a = ?<sign_arg>=md5(密钥+路径+时间戳)&<time_arg>=时间戳;b = ?<sign_arg>=时间戳-随机串-uid-md5(路径-时间戳-随机串-uid-密钥)。 可选值: ["a","b"] |
| `name` | string |  | 名称 |
| `per_uri_max` | integer |  | rate:单 URI 上限;0 = 不限。 |
| `sign_arg` | string |  | url_auth 必填:签名参数名(字母、数字、下划线、连字符)。 |
| `sign_use_max` | integer |  | url_auth:同一签名最多用几次;0 = 不限。 |
| `tenant_id` | integer |  | 所属租户;null = 平台对象(内置或管理员建,租户只读)。 (只读) |
| `time_arg` | string |  | url_auth 且 mode=a 必填:时间戳参数名;mode=b 不带。 |
| `ttl_s` | integer |  | url_auth 必填(1~2592000):签名时间戳与当前时间最多相差几秒。 |
| `type` | string |  | rate = 请求频率;challenge = 挑战(kind 指定类型);url_auth = URL 鉴权(签名密钥取站点 config.url_auth_salt)。 可选值: ["rate","challenge","url_auth"] |
| `updated_at` | string |  | 更新时间 (只读) |
| `window_s` | integer |  | 统计窗口秒数。 |