API 文档

查看账户

接口说明

用途。查看当前令牌所属账号的资料、余额、流量和是否已实名。

不含。没有 frpc 的 user / auth.token，没有推荐码，没有成长字段，也没有整份网页偏好。连接凭证只在节点配置和客户端配置正文里。

实名。identity_verified 为 true 表示已实名，false 表示未实名。这里没有姓名、证件号和人脸材料。

结果。balance 是余额，单位元。traffic.total 是未过期且仍有剩余的套餐流量合计，不是累计用量。total_remaining 是套餐剩余加签到剩余，单位字节。status 为 0 正常、1 停用、3 封禁。regtime 是 Unix 秒字符串。group 是用户组标识。proxies.use 是已用隧道数，proxies.max 为 -1 表示不按账号设总上限。bandwidth 是峰值，单位 KB/s。

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

是否已实名

接口说明

用途。只回答已实名或未实名。

结果。data 里只有 identity_verified。true 为已实名，false 为未实名。创建隧道或下单被拒绝时，先看这个字段。

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

通知列表

接口说明

用途。站内通知。默认每页 20 条，最多 100。

分页。用 page 和 page_size，也接受 pageSize。默认每页 20 条，最多 100。响应含 page、page_size、total 和 unread_count。category 只能是 all、system、business，其他值返回 400。这里不能把通知标成已读。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

未读通知数

接口说明

用途。未读通知数量。不会修改已读状态。

分类。category 与通知列表相同，只能是 all、system、business。不传按全部统计。其他值返回 400。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

标为已读

接口说明

用途。把一条通知标为已读。路径 id 来自通知列表。没有请求体。成功时 data 为 null。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

全部标为已读

接口说明

用途。把当前分类的通知全部标为已读。category 与列表相同，非法值返回 400。成功时 data 为 null。

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

账户活动

接口说明

用途。账号操作记录。默认第 1 页、每页 20 条，total 是总条数。响应含 page 和 page_size。

翻页。用 page 和 page_size，也接受 pageSize。每页最多 100。

结果。list 每项有 created_at（Unix 秒）、time（相对时间）、code（类型）、tag（中文名）和 content。关联了隧道时还有 proxy_name。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

隧道活动

接口说明

用途。隧道相关动态。默认每页 20 条，最多 100。用 page 和 page_size，也接受 pageSize。响应含 page、page_size 和 total。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

流量统计

接口说明

用途。当前账号的流量汇总，一次返回，不分页。

结果。数字都是字节。today_traffic、yesterday_traffic、month_traffic、last_month_traffic 是对应时段用量。同名的 inbound、outbound 是上行和下行。remaining_traffic 是剩余，used_traffic 是已用，total_traffic 是总量。

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

流量趋势

接口说明

用途。按天看流量趋势。days 默认 7。传 1 时改为最近 24 小时、按小时返回。

结果。data.lastDays 是数组。每项有 date 或 dateLabel、inbound、outbound、total，单位字节。days 为 1 时 dateLabel 形如 15:00。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

流量分布

接口说明

用途。流量在各节点上的分布。data 是数组，不分页。

结果。每项有 node_id、node_name、bytes 和 percent。bytes 是字节，percent 是占比。

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

节点小时流量

接口说明

用途。按小时看流量。days 默认 1。node_id 不传时统计全部节点，不会因此失败。

结果。data.xAxisData 是时间标签。data.series 按节点给出用量，series 里的 data 是字节。days 为 1 时还有 inboundData 和 outboundData，这两项单位是 GB。days 达到 365 时按月返回，那时没有 inboundData。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

套餐列表

接口说明

用途。这个账号自己的套餐，分页。默认第 1 页、每页 10 条，最多 100。看 data.total 决定要不要翻页。参数用 page 和 page_size，也接受 pageSize。响应里有 data.page 和 data.page_size。

两个编号。data.list[].id 是套餐行编号，自动续费和换绑的路径用它。data.list[].order_id 才是套餐组编号，续费和追加时填到 custom_plan_group_order_id。两者不是同一个数。order_id 为空不能续费。

和方案的关系。续费、追加、再买一档时，请求里的 custom_plan_id 必须等于该行的 custom_plan_id。

怎么判断套餐类型。一次购买会拆成多行，用 order_id 分组，速率、隧道和流量通常不在同一行。traffic 大于 0 是按量，-1 是不限流量。inbound 和 outbound 单位是 KB/s。scope 为 explicit 时节点在 node_ids；all_official 和 global 可选官方节点。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

设置自动续费

接口说明

用途。打开或关闭这一行套餐的自动续费。路径 id 是套餐行 id。

必填。请求体必须有 auto_renew。不写这个字段会被当成 false，从而把已经打开的自动续费关掉。社区方案传 true 会被拒绝。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

检查换绑

接口说明

用途。换绑前检查目标节点能不能接这行套餐。路径 id 是套餐行 id。

参数。target_node_id 必填。proxy_ids 可选，多个隧道 id 用逗号分隔，用来预览哪些隧道会一起迁。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

换绑节点

接口说明

用途。把这行套餐换到另一个节点。路径 id 是套餐行 id，不是 order_id。

必填。node_id 是目标节点。不传会失败，文案是请选择目标节点。社区方案，以及方案不允许换绑的套餐，按这个接口提交也会被拒绝。

迁移隧道。要一起迁时，migrate_proxies 设为 true，并且 migrate_proxy_ids 必须是数字数组，例如 [12,13]。写成单个数字会导致整次失败，文案仍是请选择目标节点。只传 migrate_proxies 而不给非空数组，换绑会成功，但隧道不迁。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

清理过期套餐

接口说明

用途。删除已经过期或流量用尽、且不是充值码来源的套餐行，并停用因此失去覆盖的隧道。这是真实删除，调用前先用套餐列表确认。

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

可购方案

接口说明

用途。一次返回当前可购方案。data 是数组，没有 list，也不分页。下单时 custom_plan_id 用这里的 id。

能不能余额买。owner_type 为 user 是社区方案，余额下单会被拒绝。官方方案才可以用 balance。

节点怎么选。scope 为 explicit 时，节点必须在 node_ids 里。scope 为 all_official 时 node_ids 可能是空的，可选任意官方节点。owner_type 为 user 时节点固定为 node_id。

上下限。只传开关为 true 的维度：speed_enabled、proxy_enabled、metered_enabled、unlimited_enabled。开关关掉时，旁边的 min/max 仍可能有数字，不能当成可买。max_duration_days 为 0 表示方案不设上限，单次仍不能超过 36500 天。

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

余额下单

接口说明

用途。用余额完成首购、续费、追加流量、追加隧道或再买一档。需要支付权限。金额由服务端按方案重算，传入的金额会被忽略。

调用前。先看方案列表确认开关和上下限，再看节点列表确认节点在方案范围内。首购可以省略 custom_plan_action，省略或空字符串视为 purchase。续费、追加和再买一档必须写明动作，否则会被当成首购。首购的速率、隧道数、流量方式至少选一项，没选的传 0 或省略。纯按量首购也要填天数。纯按量组不能用 renew，改用 repurchase 或 topup。续费和追加先看套餐列表，取出同一行的 order_id 与 custom_plan_id。未实名时和网页一样拒绝，错误码仍是 validation_error。

成功后看什么。data 只有 order_no、amount、status。余额支付成功时 status 为 paid。这里没有数字订单 id，也没有套餐组编号。组编号要等套餐列表刷新后读 order_id。取消订单用订单列表里的数字 id，不能把 order_no 填进路径。付完后重新拉节点列表，目标节点 available 为 true 才能创建隧道。

幂等和余额。Idempotency-Key 长度 1–128。相同键且请求体相同，会原样重放第一次的响应，包括当时的余额不足。充值后必须换新键才会再扣。键相同但请求体不同是 409 idempotency_conflict。上一笔还在处理时是 409 conflict，文案是请求正在处理，请稍后用相同 Idempotency-Key 重试。余额不足时 data 为空，当前余额和应付金额写在 error.message。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

网关下单

接口说明

用途。用支付宝或微信购买套餐。支付通道参数本次不展开。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

我的充值码

接口说明

用途。当前账号的兑换历史，按使用时间倒序，不是未使用库存。需要 billing:redeem。

结果。code 已打码，不能拿去兑换。type 是 balance 或 custom_plan。amount 是面额，单位元。status 常见 used，循环码仍可能是 unused。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

兑换充值码

接口说明

用途。兑换完整明文充值码。每分钟最多 5 次。需要 billing:redeem。

必填。code 必须是完整明文，网页会转成大写。非余额码必须带 node_id，且要落在该码允许的节点里。

结果。type 为 balance 时 amount 是到账余额，单位元。其它类型看 package_name。traffic 为 -1 表示不限。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

订单列表

接口说明

用途。这个账号的订单，分页。默认每页 10 条，最多 100。用 page 和 page_size，也接受 pageSize。响应里有 data.page 和 data.page_size。

和取消的关系。data.list[].id 是数字订单 id，取消和查详情用它。data.list[].order_no 才是下单成功时返回的订单号。两者不要互换。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

订单详情

接口说明

用途。按数字 id 读一笔订单，只读库，不会去支付宝或微信查单。

路径。id 来自订单列表。把下单响应里的 order_no 填在这里会失败。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

取消余额订单

接口说明

用途。取消自己的余额待支付订单。需要支付权限。已支付、支付宝或微信订单不能从这里取消。

路径。id 是订单数字 id，不是 order_no。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

节点列表

接口说明

用途。一次返回这个账号能看到的节点，不分页，最多约 10000 条。

两个用途不要混。首购选节点看 id，并确认 accepts_new_binding_by_type 里要买的 traffic、proxy、speed 为 true。available 只表示现有套餐已经覆盖该节点，用来建隧道，不是首购条件。

建隧道。node_id 用 available 为 true 的 id。一个都没有时先余额购买，不要直接 POST /tunnels。max_proxies 为 -1 表示该节点不限额，否则和 proxy_count 比较是否还能新建。

常见拒绝。节点不可用时创建会 400 validation_error。社区节点没买套餐的文案是需要先购买该社区节点的套餐。套餐覆盖不上是当前套餐不适用于该节点。条数满了是已达到数量上限。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

节点分组

接口说明

用途。返回全部分组。节点上的 node_group_ids 对得上这里的 id。

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

节点负载

接口说明

用途。近 3 天官方节点负载，不按账号过滤。选节点时作参考，不代表这个账号已经买到该节点。

结果。data 是对象。键是节点 id 的字符串，值是负载百分比，范围 0 到 100。例如 {"79": 12.5}。社区节点不在这里。

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

探测节点延迟

接口说明

用途。探测已登记节点的 TCP 延迟。

地址。host 或 address 必须是节点列表里的 ip 或 hostname。任意公网地址会失败。

结果。成功看 data.delay，单位毫秒。同时有 data.address 和 data.port。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

测速地址

接口说明

用途。取该节点的测速页地址。路径 id 来自节点列表。

结果。data.speedtest_url 是测速页。data.speedtest_token 是短期测速令牌，data.expires_in 是有效秒数，data.port 是测速端口。这不是 frpc 连接凭证。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

隧道列表

接口说明

用途。隧道列表。默认每页 100 条，最多 100，超过必须翻页。参数是 page 和 page_size，也接受 pageSize。可用 node 或 nodeId 按节点筛选。

结果。调客户端隧道时，proxy_ids 用 data.list[].id，和创建响应的 data.id 是同一个数。响应含 page、page_size 和 total。列表才同时有 node、node_id、node_name，enabled 按 status 为 0 计算。列表不返回 sk 和 HTTP 密码。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

检查隧道名称

接口说明

用途。创建前检查名称是否可用。名称需要 3–15 个字符。

结果。名称不合法或已被占用也是 HTTP 200。看 data.available，不要只看状态码。data.valid 表示格式是否合法，data.normalized_name 是规范化后的名称。不可用时 data.message 说明原因，data.suggestions 是建议名，data.random_suggestion 是第一条建议。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

检查端口

接口说明

用途。检查某个节点上的远程端口能否用于 tcp 或 udp。

结果。冲突也是 HTTP 200。看 data.valid，false 表示端口不可用或冲突。同时有 data.conflict、data.reason 和 data.message。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

已占用端口

接口说明

用途。列出该节点上已被占用的 tcp 或 udp 远程端口，给推荐端口用。proxy_type 必填，只能是 tcp 或 udp。

结果。data.ports 是字符串数组。exclude_proxy_id 可排除某条隧道已经占用的端口。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

创建隧道

接口说明

用途。创建一条隧道。未完成实名时和网页一样拒绝，HTTP 403，error.code 仍是 validation_error。

成功后读什么。data 就是隧道对象。下一步用的隧道 id 是 data.id，节点是 data.node_id。没有 data.proxy，也没有 node_name。remote_port 是字符串。是否启用看 data.status 是否为 0。请求里的 enabled 会被忽略，响应里的 enabled 可能是 false。没有幂等键，同样的正文再提交一次会再建一条。

按类型必填。名称 3–15 个字符。tcp 和 udp 要 remote_port，缺了的文案是 TCP/UDP 类型必须指定远程端口。http、https、tcpmux 要 domain 或 subdomain。domain 必须是字符串，多个用逗号分隔，或写成 JSON 数组字符串；传 JSON 数组会被丢掉。缺域名的文案写 domain。subdomain 只填前缀，不能含点或星号；节点没有子域名后缀时文案是该节点未配置子域名后缀，请改用绑定域名。stcp、xtcp、sudp 要 sk，写成 secretKey 会失败，失败文案写 sk，也不要写 remote_port。

节点。node_id 用节点列表里 available 为 true 的 id。也接受字段名 node。社区节点没买套餐时文案是需要先购买该社区节点的套餐。套餐不覆盖时是当前套餐不适用于该节点。条数满了是已达到数量上限。

和网页相同的可选字段。use_encryption、use_compression 接受 true、false 或字符串。http、tcpmux 还可带 httpUser、httpPassword、routeByHTTPUser；http 还可带 locations、host_header_rewrite、header_X_From_Where。tcp、udp 可带 bandwidthLimit、bandwidthLimitMode。支持健康检查的类型可带 healthCheckType、healthCheckPath、healthCheckTimeout、healthCheckMaxFailed、healthCheckInterval。负载均衡用 loadBalancerGroup、loadBalancerGroupKey。访客用户用 allowUsers。xtcp、sudp 可带 natTraversalStunServer。tcpmux 可带 multiplexer，以及 proxyProtocolVersion。这些名字也接受下划线写法，例如 http_user。enabled 会被忽略，新建后 status 为 0，停用再调 toggle。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

导入隧道

接口说明

用途。一次导入多条隧道，字段和创建相同，包括那些可选高级字段。单次 1–50 条，全部成功才写入。未完成实名时整批拒绝。

导入才有的字段。natTraversalEnable、metadatas、annotations 创建表单不提交，导入可以带，并会写入。enabled 仍然无效，导入后为启用。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

隧道详情

接口说明

用途。单条隧道详情。路径 id 来自创建响应的 data.id 或隧道列表。

结果。和创建接口不一样：隧道对象在 data.proxy，id 是 data.proxy.id，不是 data.id。JSON 里的 sk、http_password 会去掉。配置正文里的 secretKey 和 httpPassword 也会去掉。连接用的 user 和 auth.token 不在这里。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

编辑隧道

接口说明

用途。只更新请求里出现的字段。可改 local_ip、local_port、remote_port、domain、subdomain、sk，以及创建时列出的那些可选字段。空的 httpPassword 会清空密码。

改不了的。proxy_name、proxy_type、status 会被丢掉，传了也不改名、不改类型、不改状态，并且不会因此返回 400。开关用 toggle。空的 sk 会保留原来的密钥。annotations 若包含 hzfrp_frpc_client 会直接拒绝。非法 JSON 会返回参数错误。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

启用或停用隧道

接口说明

用途。启用或停用这条隧道。未完成实名时和网页一样拒绝。

怎么调。请求体可以是空对象。每调用一次就在启用和停用之间翻转，不能在正文里指定目标状态。当前是流量用尽时，仍有剩余流量的话这一次会尝试重新启用。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

删除隧道

接口说明

用途。删除这条隧道。路径 id 来自隧道列表。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

隧道配置

接口说明

用途。和隧道详情同一份 JSON。密钥不会出现在这份正文里。

下载文件。只要这一条的完整 YAML，用「下载单条隧道配置」。要节点、多条隧道或 toml，用「下载隧道配置文件」。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

节点配置

接口说明

用途。读取这个节点上全部已启用隧道的完整 frpc TOML。这是 JSON，不是文件下载。

连接凭证。user 和 auth.token 在 data.config 正文里。客户端管理隧道不会出现在这份正文里。账户接口和隧道详情都没有这两项。

下载文件。要按节点、可选隧道和 toml/yaml 下载，用「下载隧道配置文件」。只下一条 YAML 不能单独交给 frpc 运行。

结果。data.config 是完整 TOML。data.login_fail_exit_hint 来自配置里的 loginFailExit，没有则为空字符串。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

下载隧道配置文件

接口说明

用途。下载这个节点上可交给 frpc 运行的配置。由节点、可选隧道、配置文件格式三部分组成，对应请求参数里的路径 id、proxy_ids 和 format。

拼法。GET /api/v1/nodes/{节点}/config/file?proxy_ids={可选隧道}&format={toml 或 yaml}。节点用创建隧道时的 node_id。proxy_ids 用创建响应的 data.id。只有节点必填。不传隧道就是该节点全部已启用隧道，不传格式就是 toml。toml 含 user 和 auth.token。yaml 只含隧道段落。

不能指定的隧道。停用的、不属于该节点的、客户端管理隧道都不会出现。写进 proxy_ids 会 400，文案是这些隧道不在该节点或未启用。编辑或开关之后要重新下载，旧文件不会自动更新。

怎么取。默认 JSON：data.content、data.filename、data.format。download=1 时响应变成 text/plain，并带 Content-Disposition，不再是 JSON。

另外两个下载。只要一条 YAML，用下载单条隧道配置，那份不能单独运行。要某个客户端当前的 TOML，用下载客户端配置文件。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

下载单条隧道配置

接口说明

用途。只下载这一条隧道的 YAML，包含 sk 和 httpPassword。没有 serverAddr、user、auth.token，不能单独交给 frpc 运行。

要能运行的文件。用下载隧道配置文件：路径是节点，proxy_ids 填这条隧道的 id，format=toml。

怎么取。默认 JSON 里的 data.content。download=1 时响应是 text/plain，文件名 tunnel-{id}.yaml。路径 id 来自创建响应的 data.id 或隧道列表。同路径不带 /file 的详情仍会去掉密钥。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

下载客户端配置文件

接口说明

用途。下载这个客户端当前的完整 TOML。在线时取客户端上的配置，否则用缓存或重新生成。

不做脱敏。正文包含 webServer 密码和隧道密钥。

怎么取。默认 JSON 里的 data.content。download=1 时响应是 text/plain，文件名 frpc-client-{id}.toml。按节点拼隧道文件不要用这个接口。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

客户端列表

接口说明

用途。这个账号的 frpc 客户端列表，一次返回全部。data.page 为 1，data.page_size 与 data.total 都是条数。之后路径里的 id 用列表中的 id。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

创建客户端

接口说明

用途。在指定节点上创建一个带本机 webServer 的客户端。未完成实名时和网页一样拒绝。节点 toml 已经可以运行 frpc，这一步不是创建隧道的前置条件。

和网页相同的字段。空字符串与省略相同。remote_port 省略则自动分配。web_server_port 省略或 0 为 7400。web_server_user 省略为 admin。web_server_password 省略则随机生成，只能从返回的 data.config 里读取。

结果。data.client.id 是之后路径里的编号。连接用的 user、auth.token 和 webServer 密码都在 data.config 正文里。创建成功就要保存，之后的状态接口不再返回密码。接着用调整隧道写入业务隧道 id。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

客户端状态

接口说明

用途。查看客户端是否在线、管理端口是否可达，以及最近一次错误。

结果。看 data.is_online 和 data.admin_reachable。还有 name、node_id、node_name、web_server_port、web_server_user、selected_proxy_ids、last_error、last_config_at。这里没有管理密码。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

读取客户端配置

接口说明

用途。读取该客户端当前的完整配置正文。更新配置前先调用这一次，改完再整份提交。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

更新客户端配置

接口说明

用途。用一份完整配置覆盖该客户端。

不要交残缺正文。只提交 serverAddr 和 serverPort 会把正在运行的配置换成残缺文件。应先 GET 同一地址，在返回的 config 上修改后再提交。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

调整客户端隧道

接口说明

用途。指定这个客户端要加载哪些业务隧道。

编号。proxy_ids 这个键必须出现。值是同一 node_id 上的业务隧道 id，来自隧道列表。填客户端自己的管理隧道，或其他节点的隧道，会失败。空数组会从运行中的客户端去掉隧道，库里的业务隧道记录仍保留。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

重载客户端

接口说明

用途。让在线客户端重新加载当前配置。客户端不在线时会失败。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

删除客户端

接口说明

用途。删除这个客户端管理记录。已经创建的业务隧道不会跟着删除。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

推荐码

接口说明

用途。推荐码和注册链接。推荐码不能在开放 API 里重置。

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

推荐统计

接口说明

用途。推荐人数和返利汇总，一次返回。

结果。total_referrals 和 referral_count 都是推荐人数。active_referrals 是活跃人数，this_month_referrals 是本月人数。total_rebate、pending_rebate、paid_rebate、total_rebate_amount 是返利金额，单位元。total_reward_balance 是累计余额奖励，单位元。

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

推荐规则

接口说明

用途。当前站点的推荐奖励规则，只读。

结果。四个 reward_value 单位是分，展示时除以 100。rebate_min_order 单位是元。rebate_rate 是 0 到 1 的小数，0.1 表示 10%。max_referrals 为 0 表示不限人数。

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

推荐记录

接口说明

用途。推荐注册记录。默认每页 10 条，最多 100。用 page 和 page_size，也接受 pageSize。响应含 page 和 page_size。data.records 与 data.list 相同。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

推荐返利

接口说明

用途。推荐返利记录。分页规则与推荐记录相同。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

平台工单列表

接口说明

用途。平台工单列表。需要 support:read。默认每页 10 条。

结果。status 是 pending_reply、replied、completed、closed。旧值 open 和 pending 等同待回复，processing 等同已回复。id 与社区工单不是同一套编号。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

创建平台工单

接口说明

用途。创建平台工单。需要 support:write。

分类。category 用 technical、account、billing 或 other。priority 省略时为 normal。图片把已有地址写进 content，这里不提供上传。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

平台工单详情

接口说明

用途。平台工单详情。data.ticket 是工单，data.replies 是回复。路径 id 不要填社区工单的编号。

回复。replies[].user_type 是 user 或 admin。回复 id 不是工单 id。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

回复平台工单

接口说明

用途。回复自己的平台工单。content 是正文。成功时 data 是这一条回复。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

关闭平台工单

接口说明

用途。关闭自己的平台工单。没有请求体。成功时 data 为 null。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

社区节点工单列表

接口说明

用途。自己发起的社区节点工单。默认每页 20 条。需要 support:read。

结果。id 属于社区工单表。node_name 是节点名。状态取值与平台工单相同。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

创建社区节点工单

接口说明

用途。向社区节点主发工单。node_id 必须是已购买套餐的社区节点，不能填官方节点。需要 support:write。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

社区节点工单详情

接口说明

用途。社区工单详情。字段和 replies 在同一层，没有 ticket 包装。不要把平台工单 id 填到这里。

回复。replies[].user_type 是 buyer、provider 或 admin。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

回复社区节点工单

接口说明

用途。回复自己的社区节点工单。成功时 data 是这一条回复。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

关闭社区节点工单

接口说明

用途。关闭自己的社区节点工单。成功时 data 为 null。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

查看通知偏好

接口说明

用途。返回全部用户通知开关，值是布尔。没保存过的开关为 true，表示允许接收。

不含。网页引导 shop_tour_done、公告状态和云服务器通知键都不会出现。

键名。pref_notify_traffic_warning_enabled 流量预警，pref_notify_traffic_exhausted_enabled 流量耗尽，pref_notify_payment_success_enabled 订单支付通知，pref_notify_recharge_success_enabled 充值码到账，pref_notify_package_expiring_enabled 套餐到期提醒，pref_notify_auto_renew_balance_insufficient_enabled 自动续费余额不足，pref_notify_account_status_change_enabled 账号状态变更，pref_notify_password_changed_enabled 密码修改提醒，pref_notify_register_success_enabled 注册成功通知。

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

修改通知开关

接口说明

用途。合并更新通知开关。未出现的键保持原值，不会被当成 false。

必填。9 个键里至少要出现一个。空对象返回 400，文案是无有效的偏好项。网页引导和云服务器键会被丢掉。

键名。流量预警、流量耗尽、订单支付通知、充值码到账、套餐到期提醒、自动续费余额不足、账号状态变更、密码修改提醒、注册成功通知。键名与查看接口相同。

请求参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。

调用记录

接口说明

用途。查看这个账号的开放 API 调用记录。沿用 account:read。不能在这里签发或轮换令牌。

不含。没有令牌明文，也没有令牌 id。

结果。data.list 每项有 created_at（Unix 秒）、method、route、status_code、error_code、latency_ms、ip、token_prefix。默认每页 20 条，最多 100。

请求参数

返回参数

错误码

401、429、405 和 5xx 见 公共错误码。失败文案里带「不存在」时，HTTP 会收成 404 not_found。