## 用户管理 (`users`)

管理员管理平台账号:增删改查、启停、重设口令、关闭动态口令。删除前须先停用。

鉴权: 仅管理员 · 文档: https://www-demo.kuxitong.com/zh/docs/api/users

### GET `/api/v2/users`

列出用户 · 鉴权: 仅管理员

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | integer |  | 页码,从 1 开始。 默认: 1 |
| `page_size` | integer |  | 每页条数。 默认: 20 |
| `sort` | string |  | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |
| `ids` | string |  | 只列这些 id:逗号分隔的正整数,去重后至多 200 个(同 page_size 上限,超了 400);空串等同不传。与其他条件取交集;看不到的 id 不返回也不报错。分页照旧,一次取回要把 page_size 设成不少于 id 个数。 |
| `email` | string |  | 邮箱 |
| `phone` | string |  | 手机号 |
| `username` | string |  | 用户名 |

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

### POST `/api/v2/users`

创建用户 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `email` | string |  | 邮箱 |
| `enabled` | boolean |  | 是否启用 |
| `login_ip_allow` | string[] |  | 登录 IP 白名单(IP 或 CIDR);空 = 不限。 |
| `login_verify` | LoginVerify |  | 登录二次验证:none 不要求;email / sms 登录时还要邮件/短信验证码(须平台允许且已绑定对应地址)。 可选值: ["none","email","sms"] |
| `password` | string |  | 创建时必填;修改时给了即重设口令并吊销该用户全部会话。 |
| `phone` | string |  | 手机号 |
| `role` | string |  | 账号角色:admin 管理员,tenant 租户。 可选值: ["admin","tenant"] |
| `totp_enabled` | boolean |  | 是否已启用动态口令。 |
| `username` | string | 有 | 用户名 |

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

### POST `/api/v2/users/batch`

批量启停或删除用户 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `action` | string | 有 | enable 启用、disable 停用、delete 删除。 可选值: ["enable","disable","delete"] |
| `ids` | integer[] | 有 | 要操作的用户 id,一次 1~100 个。 |

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

### GET `/api/v2/users/{id}`

获取用户 · 鉴权: 仅管理员

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

### PUT `/api/v2/users/{id}`

修改用户 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `email` | string |  | 邮箱 |
| `enabled` | boolean |  | 是否启用 |
| `login_ip_allow` | string[] |  | 登录 IP 白名单(IP 或 CIDR);空 = 不限。 |
| `login_verify` | LoginVerify |  | 登录二次验证:none 不要求;email / sms 登录时还要邮件/短信验证码(须平台允许且已绑定对应地址)。 可选值: ["none","email","sms"] |
| `password` | string |  | 创建时必填;修改时给了即重设口令并吊销该用户全部会话。 |
| `phone` | string |  | 手机号 |
| `role` | string |  | 账号角色:admin 管理员,tenant 租户。 可选值: ["admin","tenant"] |
| `totp_enabled` | boolean |  | 是否已启用动态口令。 |
| `username` | string | 有 | 用户名 |

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

### DELETE `/api/v2/users/{id}`

删除用户 · 鉴权: 仅管理员

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

### GET `/api/v2/users/{user_id}/account`

查看用户账户 · 鉴权: 仅管理员

```sh
curl "https://panel.example.com/api/v2/users/{user_id}/account" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/users/{user_id}/account`

冻结或解冻用户账户 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `freeze_reason` | string |  | 冻结原因;未冻结为空。 |
| `frozen` | boolean | 有 | 是否已冻结;冻结后扣款一律被拒。 |

```sh
curl -X PUT "https://panel.example.com/api/v2/users/{user_id}/account" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"freeze_reason":"风控核查","frozen":true}'
```

### GET `/api/v2/users/{user_id}/api-keys`

列出指定用户的 API Key · 鉴权: 仅管理员

查询参数:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | integer |  | 页码,从 1 开始。 默认: 1 |
| `page_size` | integer |  | 每页条数。 默认: 20 |
| `sort` | string |  | 排序字段,逗号分隔,前缀 `-` 表示降序,如 `-created_at,id`。 |

```sh
curl "https://panel.example.com/api/v2/users/{user_id}/api-keys" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/users/{user_id}/api-keys`

为指定用户开通 API Key · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `allow_ips` | ApiKeyAllowIps |  | 调用 IP 白名单(只收单个 IP,最多 200 个);空 = 不限。不在名单里的调用按凭据无效回 401。 |
| `expires_at` | string |  | 过期时间 |
| `name` | string | 有 | 名称 |
| `scopes` | string[] | 有 | 授权范围,取值同创建时的 scopes。 |

```sh
curl -X POST "https://panel.example.com/api/v2/users/{user_id}/api-keys" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/users/{user_id}/api-keys/{id}`

改指定用户 API Key 的 IP 白名单或重置 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `allow_ips` | ApiKeyAllowIps |  | 调用 IP 白名单(只收单个 IP,最多 200 个);空 = 不限。不在名单里的调用按凭据无效回 401。 |
| `reset` | boolean |  | 为 true 时换新 key,旧 key 立即失效。 |

```sh
curl -X PUT "https://panel.example.com/api/v2/users/{user_id}/api-keys/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reset":true}'
```

### DELETE `/api/v2/users/{user_id}/api-keys/{id}`

删除指定用户的 API Key · 鉴权: 仅管理员

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

### POST `/api/v2/users/{user_id}/recharges`

给用户充值或扣款 · 鉴权: 仅管理员

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `amount_cents` | integer | 有 | 金额(分),须为正整数。 |
| `direction` | string |  | credit 充值(缺省)、debit 扣款。 可选值: ["credit","debit"] 默认: "credit" |
| `remark` | string |  | 备注 |

```sh
curl -X POST "https://panel.example.com/api/v2/users/{user_id}/recharges" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":10000,"direction":"credit","remark":"线下转账"}'
```

用户管理对象:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `action` | string | 有 | enable 启用、disable 停用、delete 删除。 可选值: ["enable","disable","delete"] |
| `affected` | integer |  | 处理的用户数。 |
| `allow_ips` | ApiKeyAllowIps |  | 调用 IP 白名单(只收单个 IP,最多 200 个);空 = 不限。不在名单里的调用按凭据无效回 401。 |
| `amount_cents` | integer | 有 | 金额(分),须为正整数。 |
| `archived` | boolean |  | 已被归档任务搬进档案表(只读)。 |
| `balance_cents` | integer |  | 账户余额(分),同 GET /users/{user_id}/account 的 balance_cents(无账户记 0)。只有 GET /users 列表带,单个用户的读写接口不带。 (只读) |
| `certified` | boolean |  | 是否已通过实名认证。 |
| `client_ip` | string |  | 本次请求的来源 IP,与登录 IP 白名单校验用的是同一个取法(白名单比什么就显示什么)。只有 GET /me、PUT /me 带。 (只读) |
| `created_at` | string |  | 创建时间 (只读) |
| `data` | object |  | 附加数据(如套餐购买明细)。 |
| `delegated_session` | boolean |  | 当前会话是否由超管代登录或切换为用户签发(是则口令、邮箱、手机号、登录白名单、二次验证与实名只读)。只有 GET /me、PUT /me 带。 (只读) |
| `des` | string |  | 备注说明 |
| `direction` | string |  | credit 充值(缺省)、debit 扣款。 可选值: ["credit","debit"] 默认: "credit" |
| `email` | string |  | 邮箱 |
| `enabled` | boolean |  | 是否启用 |
| `expires_at` | string |  | 过期时间 |
| `freeze_reason` | string |  | 冻结原因;未冻结为空。 |
| `frozen` | boolean |  | 是否已冻结;冻结后扣款一律被拒。 |
| `id` | integer |  | 记录 ID (只读) |
| `ids` | integer[] | 有 | 要操作的用户 id,一次 1~100 个。 |
| `last_used_at` | string |  | 最近一次使用时间;从未使用为空。 |
| `ledger_id` | integer |  | 关联的账户流水 ID;没有则为空。 |
| `login_ip_allow` | string[] |  | 登录 IP 白名单(IP 或 CIDR);空 = 不限。 |
| `login_verify` | LoginVerify |  | 登录二次验证:none 不要求;email / sms 登录时还要邮件/短信验证码(须平台允许且已绑定对应地址)。 可选值: ["none","email","sms"] |
| `mch_order_no` | string |  | 商户订单号(网关侧订单号);非在线支付为空。 |
| `name` | string |  | 名称 |
| `paid_at` | string |  | 付款时间;未付款为空。 |
| `password` | string |  | 创建时必填;修改时给了即重设口令并吊销该用户全部会话。 |
| `pay_type` | string |  | admin/balance/alipay/wxpay 等;空 = 未付款。 |
| `phone` | string |  | 手机号 |
| `prefix` | string |  | 明文的前几位,便于辨认。 |
| `remark` | string |  | 备注 |
| `reset` | boolean |  | 为 true 时换新 key,旧 key 立即失效。 |
| `role` | string |  | 账号角色:admin 管理员,tenant 租户。 可选值: ["admin","tenant"] |
| `scopes` | string[] |  | 授权范围,取值同创建时的 scopes。 |
| `secret` | string |  | 明文 key(X-API-Key 的值),只在创建时返回一次;库里只存哈希。 |
| `status` | string |  | 订单状态:unpaid 待付款、paid 已付款。 可选值: ["unpaid","paid"] |
| `tenant_id` | integer |  | 所属租户(用户)ID (只读) |
| `totp_enabled` | boolean |  | 是否已启用动态口令。 |
| `totp_recovery_left` | integer |  | 未用完的 TOTP 恢复码个数。只有 GET /me、PUT /me 且已启用动态口令时带。 (只读) |
| `transaction_id` | string |  | 网关侧交易号;未付款为空。 |
| `type` | string |  | recharge(管理员充值)/deduct(管理员扣款)/payment(在线支付)/package(套餐)等。 |
| `updated_at` | string |  | 更新时间 (只读) |
| `user_id` | integer |  | 用户 ID |
| `username` | string |  | 用户名 |