二级域名分发系统 · 开放 API v1

面向开发者与自动化场景的 RESTful 接口。

一、基础信息

项目	值
Base URL	`https://你的域名/api/v1.php`
协议	HTTPS（生产环境必须）
编码	UTF-8
请求方法	`GET` / `POST`
参数风格	Query String（GET）或 `application/x-www-form-urlencoded`（POST）
响应类型	`application/json; charset=utf-8`
响应版本头	`X-API-Version: 1`

二、响应结构

所有响应均为统一 JSON：

BLOCK0

字段	类型	说明
`code`	int	`0` = 成功；非 0 = 失败
`msg`	string	人类可读的说明
`data`	object / array / null	业务数据，失败时通常为 `null`

常见错误码

code	含义
0	成功
1	参数或业务错误（详情见 `msg`）
401	未认证 / Token 无效
403	账号被封禁或该账号被禁止使用 API
405	请求方法不允许
500	服务器内部错误

三、获取 Token

3.1 管理员 Token

安装时生成，展示一次。若遗失：

登录后台 → 站点设置 → 「API 与开放」→ 当前管理员 API Token → 重新生成

3.2 用户 Token

用户 Token 需要用户自己在「用户中心 → API Token」中申请。管理员可以配置三种模式：

模式	行为
未开放	用户中心不显示「API Token」菜单，管理员只负责分配 Token
直接开放	用户点击「申请 API Token」后立即生成
需要审核	用户提交申请后进入后台「用户 → API 申请」，管理员批准后才生成

查看状态：用户打开「用户中心 → API Token」页面。

四种状态：

状态	含义	用户可执行的操作
未申请	尚未申请	点击「申请 API Token」
待审核	已提交，等待管理员	无（等待审核）
已拒绝	管理员拒绝了申请	查看拒绝原因，可「重新申请」
已通过	Token 已生成	复制 Token、重新生成 Token

重新生成：用户可在「用户中心 → API Token」页面点击「重新生成」，旧 Token 立即失效。

四、使用 Token

任选一种方式：

方式 A：请求头（推荐）

BLOCK1

方式 B：Query 参数（不推荐，仅用于快速测试）

BLOCK2

> 提示：方式 B 会把 Token 泄露到日志与浏览器历史中，仅供本地调试。

五、端点列表

公开端点（无需认证）

1. `GET /api/v1.php?action=health`

健康检查。

BLOCK3

2. `GET /api/v1.php?action=stats`

站点统计。

BLOCK4

3. `GET /api/v1.php?action=check&sub=<子域名头>`

检查某个子域名头在所有根域名下的可用性。

参数	类型	必填	说明
`sub`	string	是	例如 `myapp`（仅字母数字短横线）

BLOCK5

认证端点

以下所有端点均需携带 Token。

4. `GET /api/v1.php?action=me`

获取当前账号信息。

BLOCK6

5. `POST /api/v1.php?action=token.regenerate`

重新生成 Token。旧 Token 立即失效。

> 注意：该端点重置的是「当前登录后台的管理员」的 Token，用于管理员自助重置。用户 Token 请在用户中心自助重新生成。

BLOCK7

6. `GET /api/v1.php?action=domain.list`

获取当前用户组可用的根域名列表。

BLOCK8

7. `GET /api/v1.php?action=subdomains`

获取当前用户的所有解析记录。

BLOCK9

8. `POST /api/v1.php?action=subdomain.create`

申请一个新的二级域名解析。

参数	类型	必填	说明
`root_domain`	string	是	根域名，例如 `example.com`
`sub_name`	string	是	子域名头，例如 `myapp`
`record_type`	string	否	`A` / `AAAA` / `CNAME` / `MX` / `TXT`，默认 `A`
`record_value`	string	是	记录值
`remark`	string	否	备注，支持 HTML

BLOCK10

9. `POST /api/v1.php?action=subdomain.update`

修改已有解析。

参数	类型	必填	说明
`id`	int	是	解析记录 ID
`record_value`	string	是	新的记录值
`record_type`	string	否	不传则保持原类型
`remark`	string	否	不传则保持原备注

BLOCK11

10. `POST /api/v1.php?action=subdomain.delete`

删除一条解析。

参数	类型	必填	说明
`id`	int	是	解析记录 ID

BLOCK12

11. `GET /api/v1.php?action=point_logs`

获取当前用户的积分流水。

参数	类型	必填	说明
`limit`	int	否	每页条数，默认 50，最大 200
`offset`	int	否	偏移量，默认 0
`type`	string	否	`register` / `redeem` / `add` / `edit` / `delete` / `refund` / `admin` / `invite` / `checkin`

BLOCK13

六、错误处理

401：未认证

BLOCK14

可能原因：

请求头没带 Authorization
Token 格式错误
Token 已被重置
用户的 Token 还没被管理员批准（状态仍是待审核或已拒绝）

403：账号被封禁

BLOCK15

可能原因：

账号被管理员封禁
封禁到期时间已到，用户重新登录后自动解封（封禁期间 API 不可用）

405：请求方法不允许

BLOCK16

api/v1.php 只接受 GET 和 POST（OPTIONS 返回 204）。

七、代码示例

cURL

BLOCK17

JavaScript (fetch)

BLOCK18

Python (requests)

BLOCK19

PHP

BLOCK20

八、用户 Token 申请流程（管理员视角）

登录后台 → 站点设置 → 「API 与开放」
勾选「允许用户自助申请 API Token」
可选勾选「用户申请 API 需要管理员审核」
用户打开「用户中心 → API Token」：

若不需审核：用户点击「申请 API Token」后立即生成 Token
若需审核：用户点击「申请」→ 进入后台待审核列表

管理员打开「用户 → API 申请」：

可筛选「待审核 / 已批准 / 已拒绝 / 全部」
支持单个批准/拒绝
支持勾选多条批量批准/拒绝
拒绝时可填写原因（用户可在用户中心看到）

批准后系统自动生成 Token，用户刷新页面即可看到

九、安全建议

绝不将 Token 提交到 Git、贴到聊天群、写进前端代码。
仅在 HTTPS 下使用，HTTP 明文传输会让 Token 完全暴露。
定期轮换：建议 30~90 天重新生成一次 Token。
泄露立即重置：一旦怀疑 Token 被第三方看到，立刻重新生成。
服务端调用：从自己的后端服务器发起请求，不要把 Token 下发到浏览器。
最小权限：API 只能操作 Token 所属账号的资源，无法触达其他用户。
用户 Token 需审核模式建议：面向外部用户开放 API 时，建议开启「需要管理员审核」，避免滥用。
封禁时间机制：被管理员封禁的账号，在封禁期间无法使用 API；封禁到期后重新登录会自动解封。

十、限额

单次请求体不超过 64 KB。
point_logs 单页最多返回 200 条。
建议客户端 每秒不超过 5 次请求。
后续版本可能加入基于 Token 的配额，届时会在本文档顶部注明。

十一、错误排查

现象	原因	处理
`code: 401`	Token 缺失或错误	检查 `Authorization` 头是否携带正确的 Bearer Token
`code: 403`	账号被封禁	联系站点管理员解封，或等待封禁到期
`code: 405`	使用了错误的方法	检查端点文档中要求的 `GET` / `POST`
`code: 500`	服务器异常	稍后重试；若持续出现请联系管理员
返回 HTML 而非 JSON	反代/网关拦截	检查 WAF、Nginx 配置是否放过 `/api/v1.php`
用户中心看不到「API Token」	后台未开启	到「站点设置 → API 与开放」开启
申请后一直待审核	开启了审核模式	等待管理员在「用户 → API 申请」中批准

十二、变更日志

版本	日期	变更
1.0.0	—	首个公开版本
1.0.1	—	新增用户自助申请 Token（含审核模式）；新增封禁到期自动解封

开放 API 文档