帮助文档

NepBox 通过一个 HTTP 接口把当前的公网 IP 写入你的子域名。下面是接口参数、返回码、常见定时任务写法与排错建议。

快速开始

用 Google 账号登录，账号会获得 2 点初始额度；
在控制台创建子域名，并按需添加 A / AAAA 记录；
复制域名详情里的更新地址，交给路由器或定时任务定时访问。

更新接口

GET https://api.nepbox.com/update

参数	必填	说明
`domain`	是	子域名，不含 `.nepbox.com`
`token`	是	该子域名的更新令牌，可在控制台重置
`ip`	否	手动指定 IPv4 地址，写入 A 记录
`ipv6`	否	手动指定 IPv6 地址，写入 AAAA 记录

不传 ip / ipv6 时，接口按请求来源地址自动判断：IPv4 写入 A 记录，IPv6 写入 AAAA 记录。地址没有变化时接口直接返回 ok，不会产生多余的写入。

调用示例

# 自动探测来源 IP
curl -4 "https://api.nepbox.com/update?domain=YOUR_DOMAIN&token=YOUR_TOKEN"
curl -6 "https://api.nepbox.com/update?domain=YOUR_DOMAIN&token=YOUR_TOKEN"

# 手动指定地址
curl "https://api.nepbox.com/update?domain=YOUR_DOMAIN&token=YOUR_TOKEN&ip=1.2.3.4"
curl "https://api.nepbox.com/update?domain=YOUR_DOMAIN&token=YOUR_TOKEN&ipv6=2001:db8::1"

返回码

响应体	HTTP	含义
`ok`	200	成功。地址没有变化时同样返回 `ok`
`badparam`	400	缺少 `domain` / `token`，或地址格式不正确
`noip`	400	未提供地址，且无法从请求中判断来源 IP
`badtoken`	403	令牌格式不正确，或与该域名不匹配
`toomanyrequests`	429	超过频率限制：每个来源 IP 每分钟 20 次，同一 IP 下的所有子域名共用
`toomanychanges`	429	该域名今天触发地址变更的更新次数已用尽（每天 50 次），`Retry-After` 指向次日重置
`error`	500	服务端或 Cloudflare 出错，可稍后重试

* 频率限制看的是请求，每天 50 次的上限看的是真正产生变更的更新：地址没变的轮询两者都不计数（只受每分钟的请求限制）。一次请求里同时更新 IPv4 与 IPv6 记作一次。

定时任务

Linux / NAS（crontab，每 5 分钟一次）：

*/5 * * * * curl -4 -s "https://api.nepbox.com/update?domain=YOUR_DOMAIN&token=YOUR_TOKEN" > /dev/null

Telegram 变更通知

绑定 Telegram 后，子域名的解析地址发生变化时，bot 会给你发一条消息：域名、记录类型、变更前后的地址、来源和时间。

用 Google 账号登录后打开用户信息页；
点「绑定 Telegram」，页面会生成一条 10 分钟内有效的一次性链接；
在 Telegram 里点「开始」，看到「绑定成功」就完成了，通知默认开启。

控制台里手动新增、修改、删除记录也会发送通知，消息里的「来源」会区分 DDNS 自动更新 和 控制台手动修改。

想安静一会儿：

在用户信息页关掉开关（保留绑定），或在 bot 里发送 /stop；
在 bot 里发送 /help 查看可用命令；
在用户信息页点「解除绑定」彻底解绑，之后 bot 不会再发送任何消息。

* 通知只是提醒渠道：即使消息发送失败（例如你屏蔽了 bot），DDNS 更新仍然照常进行。

常见问题

地址没有更新？

先确认接口返回的是 ok；
检查解析是否已经生效：nslookup YOUR_DOMAIN.nepbox.com，并注意 TTL 与本地 DNS 缓存；
如果你曾在 Cloudflare 后台手动改过记录，服务端保存的旧值会让更新接口认为「无需更新」，请在控制台手动改一次记录；
确认设备使用的是当前令牌 —— 重置 Token 后旧地址会立即失效。

为什么每个域名只能有一条 A 和一条 AAAA？

本服务专注 DDNS：每个子域名只有 apex，且每种类型只保留一条记录，更新接口直接覆盖它。需要更多记录类型或更多主机名时，请为每个用途单独创建子域名。

为什么子域名至少要 5 个字符？

更短的名字数量有限、容易被抢注和滥用，因此最短要求 5 个字符。每个域名消耗 1 点额度，删除域名后额度会退还。

令牌泄露了怎么办？

在域名详情里点「重置 Token」，旧令牌会立即失效，然后更新设备上保存的更新地址。

变更记录为什么只有 20 条？

DDNS 客户端轮询很频繁，为了避免写爆数据库，每个域名只保留最近 20 条变更记录，超出后自动删除。

还有别的问题？

邮件联系 support@nepbox.com。