版本 2.1.1792967583 · 最新下载 OpenAPI Markdown 版

用户管理

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

users用户账号鉴权: 仅管理员13 个接口

列出用户

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	—	用户名

创建用户

POST/api/v2/users

鉴权: 仅管理员

请求体 application/json

字段	类型	必填	说明
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	必填	用户名

批量启停或删除用户

POST/api/v2/users/batch

鉴权: 仅管理员

请求体 application/json

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

获取用户

GET/api/v2/users/{id}

鉴权: 仅管理员

修改用户

PUT/api/v2/users/{id}

鉴权: 仅管理员

请求体 application/json

字段	类型	必填	说明
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	必填	用户名

删除用户

DELETE/api/v2/users/{id}

鉴权: 仅管理员

查看用户账户

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

鉴权: 仅管理员

冻结或解冻用户账户

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

鉴权: 仅管理员

请求体 application/json

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

列出指定用户的 API Key

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

鉴权: 仅管理员

查询参数

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

为指定用户开通 API Key

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

鉴权: 仅管理员

请求体 application/json

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

改指定用户 API Key 的 IP 白名单或重置

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

鉴权: 仅管理员

请求体 application/json

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

删除指定用户的 API Key

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

鉴权: 仅管理员

给用户充值或扣款

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

鉴权: 仅管理员

请求体 application/json

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

用户管理对象

字段	类型	必填	说明
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	—	用户名

curl

# 列出用户
curl "https://panel.example.com/api/v2/users" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 创建用户
curl -X POST "https://panel.example.com/api/v2/users" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 批量启停或删除用户
curl -X POST "https://panel.example.com/api/v2/users/batch" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 获取用户
curl "https://panel.example.com/api/v2/users/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 修改用户
curl -X PUT "https://panel.example.com/api/v2/users/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 删除用户
curl -X DELETE "https://panel.example.com/api/v2/users/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 查看用户账户
curl "https://panel.example.com/api/v2/users/{user_id}/account" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 冻结或解冻用户账户
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}'

# 列出指定用户的 API Key
curl "https://panel.example.com/api/v2/users/{user_id}/api-keys" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 为指定用户开通 API Key
curl -X POST "https://panel.example.com/api/v2/users/{user_id}/api-keys" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 改指定用户 API Key 的 IP 白名单或重置
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}'

# 删除指定用户的 API Key
curl -X DELETE "https://panel.example.com/api/v2/users/{user_id}/api-keys/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# 给用户充值或扣款
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":"线下转账"}'