## 用户管理 (`users`)

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

鉴权: 仅管理员 · 文档: https://www.gocdn888.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 上限,超了或格式错 422);空串等同不传。与其他条件取交集;看不到的 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`

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

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `currency` | CurrencyBrief |  | 账户货币(ISO 4217)与符号,余额、充值、订单都按它记,面板金额显示用;没开过账户时为新用户默认。 |
| `email` | string |  | 邮箱 |
| `enabled` | boolean |  | 是否启用 |
| `login_ip_allow` | string[] |  | 登录 IP 白名单(IP 或 CIDR);空 = 不限。 |
| `login_verify` | LoginVerify |  | 登录二次验证:none 不要求;email / sms 登录时还要邮件/短信验证码(须平台允许且已绑定对应地址)。 可选值: ["none","email","sms"] |
| `password` | string |  | 创建时必填;修改时给了即重设口令,吊销该用户全部会话并删其全部 API Key(审计 detail 记 api_keys_revoked)。 |
| `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}`

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

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `currency` | CurrencyBrief |  | 账户货币(ISO 4217)与符号,余额、充值、订单都按它记,面板金额显示用;没开过账户时为新用户默认。 |
| `email` | string |  | 邮箱 |
| `enabled` | boolean |  | 是否启用 |
| `login_ip_allow` | string[] |  | 登录 IP 白名单(IP 或 CIDR);空 = 不限。 |
| `login_verify` | LoginVerify |  | 登录二次验证:none 不要求;email / sms 登录时还要邮件/短信验证码(须平台允许且已绑定对应地址)。 可选值: ["none","email","sms"] |
| `password` | string |  | 创建时必填;修改时给了即重设口令,吊销该用户全部会话并删其全部 API Key(审计 detail 记 api_keys_revoked)。 |
| `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 | 有 | 名称 |
| `password` | string |  | 创建时必填;修改时给了即重设口令,吊销该用户全部会话并删其全部 API Key(审计 detail 记 api_keys_revoked)。 |
| `scopes` | string[] | 有 | 授权范围,取值同创建时的 scopes。 |
| `totp_code` | string |  | 操作者本人动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。 |

```sh
curl -X POST "https://panel.example.com/api/v2/users/{user_id}/api-keys" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"default","password":"${CURRENT_PASSWORD}","scopes":["*"]}'
```

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

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

请求体:

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `allow_ips` | ApiKeyAllowIps |  | 调用 IP 白名单(只收单个 IP,最多 200 个);空 = 不限。不在名单里的调用按凭据无效回 401。 |
| `password` | string |  | 创建时必填;修改时给了即重设口令,吊销该用户全部会话并删其全部 API Key(审计 detail 记 api_keys_revoked)。 |
| `reset` | boolean |  | 为 true 时换新 key,旧 key 立即失效。 |
| `totp_code` | string |  | 操作者本人动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。 |

```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 '{"password":"${CURRENT_PASSWORD}","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 | 有 | 金额(分),须为正整数。 |
| `currency` | CurrencyBrief |  | 账户货币(ISO 4217)与符号,余额、充值、订单都按它记,面板金额显示用;没开过账户时为新用户默认。 |
| `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"] |
| `active_packages` | integer |  | 生效中套餐数(end_at 晚于现在,改账户货币的阻碍之一)。只有管理员 GET /users/{user_id}/account 带。 |
| `affected` | integer |  | 处理的用户数。 |
| `allow_ips` | ApiKeyAllowIps |  | 调用 IP 白名单(只收单个 IP,最多 200 个);空 = 不限。不在名单里的调用按凭据无效回 401。 |
| `amount_cents` | integer | 有 | 金额(分),须为正整数。 |
| `archived` | boolean |  | 已被归档任务搬进档案表(只读)。 |
| `avatar_ver` | integer |  | 头像版本,每次上传变大;没有头像为空。 |
| `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 |  | 创建时间 (只读) |
| `currencies` | AccountCurrencyOption[] |  | 可选的启用货币(基准在前,其余按 code);仅 currency_changeable 为 true 时带,只有 GET /account 与管理员 GET /users/{user_id}/account。 |
| `currency` | CurrencyBrief |  | 账户货币(ISO 4217)与符号,余额、充值、订单都按它记,面板金额显示用;没开过账户时为新用户默认。 (只读) |
| `currency_changeable` | boolean |  | 租户自己现在能不能改账户货币(余额 0、无未付款订单、无生效中套餐)。只有 GET /account 与管理员 GET /users/{user_id}/account 带。 |
| `data` | object |  | 附加数据(如套餐购买明细);在线付差额的充值单带 intent(办理意图,state 为 pending/running/done/failed,failed 时 code/reason 写明原因,done 时 user_package_id 为办理的用户套餐)。 |
| `default_currency` | string |  | 新用户默认的账户货币(ISO 4217);租户端判断「账户币没动过」用(现币 = 它才按界面语言预选)。与 currencies 同时带,仅 currency_changeable 为 true 时有,只有 GET /account 与管理员 GET /users/{user_id}/account。 |
| `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 个。 |
| `ip_site_new` | boolean |  | 名下有使用中(未到期)且开放 IP 网站的套餐:能新建 IP 网站、选新 IP、签 ZeroSSL 付费版(zerossl_api)证书、给 ZeroSSL 账号设 API Key。只有 GET /me 带;管理员恒为 true。 (只读) |
| `ip_site_on` | boolean |  | ip_site_new 为 true,或名下已有 IP 网站、IP 证书(SAN 全是 IP)、配了 API Key 的 ZeroSSL 账号任一(免费 ZeroSSL 账号不算):IP 网站相关菜单与页签可见,已有数据可查看、编辑、删除。只有 GET /me 带;管理员恒为 true。 (只读) |
| `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 |  | 名称 |
| `nickname` | string |  | 昵称;没设为空(界面显示登录名)。 |
| `paid_at` | string |  | 付款时间;未付款为空。 |
| `password` | string |  | 创建时必填;修改时给了即重设口令,吊销该用户全部会话并删其全部 API Key(审计 detail 记 api_keys_revoked)。 |
| `pay_type` | string |  | admin/balance/alipay/wxpay 等;空 = 未付款。 |
| `phone` | string |  | 手机号 |
| `prefix` | string |  | 明文的前几位,便于辨认。 |
| `rate_to_base` | string |  | 下单时汇率:1 单位该币 = ? 基准货币(十进制串,8 位小数);之后改汇率不动历史。 |
| `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_code` | string |  | 操作者本人动态口令(TOTP)的 6 位当前码;账号须已启用动态口令。 |
| `totp_enabled` | boolean |  | 是否已启用动态口令。 |
| `totp_recovery_left` | integer |  | 未用完的 TOTP 恢复码个数。只有 GET /me、PUT /me 且已启用动态口令时带。 (只读) |
| `transaction_id` | string |  | 网关侧交易号;未付款为空。 |
| `type` | string |  | recharge(管理员充值)/deduct(管理员扣款)/payment(在线支付)/package(套餐)等。 |
| `unpaid_orders` | integer |  | 未付款订单数(改账户货币的阻碍之一)。只有管理员 GET /users/{user_id}/account 带,其余读写接口不带。 |
| `updated_at` | string |  | 更新时间 (只读) |
| `user_id` | integer |  | 用户 ID |
| `username` | string |  | 用户名 |
