## 站点缓存分组与本站改动 (`cache-sites`)

查看或设置单个站点使用的缓存分组与本站改动(新增 / 修改 / 删除规则、忽略参数清单)。

鉴权: 用户（部分参数仅管理员） · 文档: https://www.gocdn888.com/zh/docs/api/cache-sites

### GET `/api/v2/cache-sites/{id}`

站点的缓存分组与本站改动 · 鉴权: 用户（部分参数仅管理员）

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

### PUT `/api/v2/cache-sites/{id}`

站点换缓存分组 · 鉴权: 用户（部分参数仅管理员）

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `expected_updated_at` | string |  | 乐观锁(修改时用):调用方读到的站点 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。 |
| `group_id` | integer | 有 | 显式引用的分组;null = 按默认分组。 |
| `keep` | boolean |  | 换分组时是否保留本站改动;缺省 true = 保留并按分组变动规则转换,false = 不保留(清空),全部跟新分组。 |

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

### PUT `/api/v2/cache-sites/{id}/overlay`

保存站点的本站改动 · 鉴权: 用户（部分参数仅管理员）

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `expected_updated_at` | string |  | 乐观锁(修改时用):调用方读到的站点 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。 |
| `overlay` | object | 有 | 本站改动;null = 没有。 |

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

### DELETE `/api/v2/cache-sites/{id}/overlay`

站点全部还原为分组原样 · 鉴权: 用户（部分参数仅管理员）

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

### GET `/api/v2/cache-sites/{id}/switch-preview`

预览站点换缓存分组后的规则 · 鉴权: 用户（部分参数仅管理员）

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `group_id` | integer |  | 目标缓存分组 id(平台分组或站点属主的);不带 = 按默认分组。 |
| `keep` | boolean |  | 是否保留本站改动,缺省 true;false = 不保留,全部跟新分组。 默认: true |

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

站点缓存分组与本站改动对象:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `counts` | object |  | 换后的汇总条数。 |
| `effective` | CacheConfig |  | 缓存规则,同节点契约 schema/site.json 的 cache({rules, ignore_params}),服务端按契约校验。 |
| `effective_group_id` | integer |  | 实际生效的分组;null = 没有可用分组(按出厂标配,不下发分组规则)。 |
| `expected_updated_at` | string |  | 乐观锁(修改时用):调用方读到的站点 updated_at。与库里当前值不等则回 409 stale_version、不保存;不带则不检查;创建时忽略。 |
| `group_id` | integer |  | 显式引用的分组;null = 按默认分组。 |
| `group_ignore_params` | string[] |  | 换后分组自己的忽略参数清单。 |
| `group_name` | string |  | 换后生效分组的名称;没有可用分组时省略。 |
| `ignore_params` | string[] |  | 换后生效的忽略参数清单。 |
| `ignore_params_changed` | boolean |  | 忽略参数清单是否是本站值(与分组不同)。 |
| `keep` | boolean |  | 换分组时是否保留本站改动;缺省 true = 保留并按分组变动规则转换,false = 不保留(清空),全部跟新分组。 |
| `overlay` | object |  | 本站改动;null = 没有。 |
| `overlay_count` | integer |  | 改了几条:规则改动数 + 忽略参数改了算 1。 |
| `rows` | CacheSwitchRow[] |  | 逐条规则,按显示顺序;删除行排在分组里的原位置。 |
| `site_id` | integer |  | 网站 ID |
| `updated_at` | string |  | 站点的 updated_at(站点行的版本,换分组或改本站改动也会更新);写入时作 expected_updated_at 带回。 (只读) |
