xndns

v1.0.7

Published

a month ago

小雫DNS CLI - 零依赖的 DNSHE 子域名管理命令行工具（同步/异步 SDK + CLI）

0High
0Medium
0Low

myndlp1234

dnshe subdomain dns cli sdk xiaoniao 小雫DNS free-domain cloudflare whois domain-management

小雫DNS CLI (`xndns`)

零依赖的 DNSHE 子域名管理命令行工具，支持 REST / JSON-RPC / GraphQL 三种传输层

安装

npm（推荐）

npm install -g xndns

手动安装

# 克隆或下载后
cd xndns-cli
./install.sh  # Linux/macOS
# 或
node index.js help  # 直接运行

特性

零依赖：仅依赖 Node.js 18+ 内置模块（fetch / fs / path），无需 npm install
三传输层：支持 rest / rpc / graphql，可通过 --transport 或配置文件切换
完整功能：子域名 CRUD / DNS 记录 CRUD / API 密钥管理 / 配额查询 / WHOIS / 安装检测
多种配置方式：环境变量 / 配置文件（~/.xndnsrc）/ 命令行参数
JSON 输出：所有命令支持 --json 切换为机器可读格式，方便管道和脚本
跨平台：Linux / macOS / Windows（WSL 或 Git Bash）

安装

方式 1：脚本安装（推荐 Linux / macOS）

# 进入解压后的目录
cd xndns-cli

# 运行安装脚本
./install.sh

安装脚本会把 xndns 复制到 /usr/local/bin/xndns，全局可用。

方式 2：npm 全局安装（如果发布到 npm）

npm install -g xndns

方式 3：直接运行（不安装）

# 直接用 node 运行
node index.js quota

# 或建个软链
ln -s "$(pwd)/index.js" /usr/local/bin/xndns

方式 4：Windows

# 用 PowerShell 建个 wrapper
@echo off
node "C:\path\to\xndns-cli\index.js" %*
> xndns.cmd

# 把 xndns.cmd 所在目录加到 PATH

卸载

./uninstall.sh

会移除 /usr/local/bin/xndns 和 ~/.xndnsrc。

配置凭证

方式 1：使用 `login` 命令（推荐）

xndns login cfsd_xxxxxxxxxxxxxxxx yyyyyyyyyyyyyyyyyyyy --host=https://your-host

凭证保存在 ~/.xndnsrc（权限 600）。

方式 2：环境变量

export XNDNS_API_KEY=cfsd_xxxxxxxxxxxxxxxx
export XNDNS_API_SECRET=yyyyyyyyyyyyyyyyyyyy
export XNDNS_HOST=https://your-host
# 可选：传输层（默认 rest）
export XNDNS_TRANSPORT=rpc

适合 CI/CD 或临时使用，不会写入磁盘。

方式 3：配置文件

直接编辑 ~/.xndnsrc：

{
  "apiKey": "cfsd_xxx",
  "apiSecret": "yyyy",
  "host": "https://your-host",
  "transport": "rest"
}

或用 config 命令：

xndns config show
xndns config set transport rpc
xndns config set host https://other-host

命令一览

基础

| 命令 | 说明 | |---|---| | xndns login <key> <secret> [--host=URL] | 保存凭证 | | xndns logout | 清除凭证 | | xndns whoami | 显示当前凭证 | | xndns config [show\|set <key> <value>] | 查看/修改配置 | | xndns help | 显示帮助 | | xndns version | 显示版本 |

子域名

| 命令 | 说明 | |---|---| | xndns subdomains list [opts] | 列出子域名 | | xndns subdomains get <id> | 查看详情（含 DNS 记录） | | xndns subdomains create <prefix> <root> | 注册 | | xndns subdomains delete <id> | 删除（含 DNS 记录） | | xndns subdomains renew <id> | 续费 |

list 选项：--page=N --per-page=N --search=KEY --status=STATUS --rootdomain=ROOT

DNS 记录

| 命令 | 说明 | |---|---| | xndns dns list <subdomain_id> | 列出记录 | | xndns dns create <subdomain_id> <type> <content> [--ttl=N] [--priority=N] [--name=NAME] | 创建 | | xndns dns update <id> [--type=T] [--content=V] [--ttl=N] | 更新 | | xndns dns delete <id> | 删除 |

类型支持：A / AAAA / CNAME / MX / TXT / NS / SRV / CAA

密钥 / 配额 / WHOIS

| 命令 | 说明 | |---|---| | xndns quota | 查询配额 | | xndns whois <domain> | WHOIS 查询 | | xndns keys list | 列出 API 密钥 | | xndns keys create <name> [--ip-whitelist=IPS] | 创建密钥 | | xndns keys delete <key_id> | 删除密钥 | | xndns keys regenerate <key_id> | 重置 Secret |

检测

| 命令 | 说明 | |---|---| | xndns detect <domain> | 检测目标域名是否安装小雫DNS | | xndns selftest | 检测当前配置的主机 |

全局选项

| 选项 | 说明 | |---|---| | --json | 输出原始 JSON | | --host=URL | 临时覆盖主机 | | --transport=rest\|rpc\|graphql | 临时覆盖传输层 |

使用示例

# 登录
xndns login cfsd_0adc0ce77bc62a2903caf044ddb877a5 b190ba15... --host=https://your-host

# 查看配额
xndns quota
# 配额: 1/3 已用
#   基础: 3
#   邀请奖励: 0
#   可用: 2

# 列出子域名
xndns subdomains list --per-page=5
# 共 1 条，本页 1 条
#
#   #7477265796  mynmail.bbroot.com  [Registered]  2036-07-07 01:08:40

# 注册新子域名
xndns subdomains create myapp us.kg
# ✓ 已注册 myapp.us.kg (#7477265797)

# 创建 DNS 记录
xndns dns create 7477265797 A 192.0.2.1 --ttl=600
# ✓ 已创建 [A] 记录 (id=100)

# WHOIS 查询
xndns whois mynmail.bbroot.com
# 域名:   mynmail.bbroot.com
# 状态:   active
# 注册:   2026-07-07 01:08
# 到期:   2036-07-07 01:08
# 邮箱:   [email protected]
# NS:     ns1.dnshe.com, ns2.dnshe.com

# 切换到 RPC 传输层
xndns config set transport rpc
xndns quota
# (相同输出，但底层走 JSON-RPC)

# JSON 输出（适合脚本）
xndns quota --json | jq '.quota.available'
# 2

# 检测某域名是否安装小雫DNS
xndns detect example.com
# ✗ example.com 未安装小雫DNS

xndns selftest
# ✓ https://your-host 是小雫DNS v1.0.0
#   功能: rest, rpc, graphql, cli, sdk, docs

管道与脚本示例

# 找出所有即将到期的子域名（30 天内）
xndns subdomains list --json | jq '.subdomains[] | select(.expires_at != null) | select((.expires_at | strptime("%Y-%m-%d %H:%M:%S") | mktime) < (now + 30*86400)) | .full_domain'

# 批量备份所有子域名的 DNS 记录
for id in $(xndns subdomains list --json | jq '.subdomains[].id'); do
  xndns dns list $id --json > "dns-backup-${id}.json"
done

# 检测多个域名
for d in site1.com site2.com site3.com; do
  echo -n "$d: "
  xndns detect $d --json | jq -r '.detected'
done

传输层对比

| 传输层 | 优势 | 何时使用 | |---|---|---| | rest (默认) | 资源化 URL，缓存友好 | 日常使用 | | rpc | 单端点，支持批量调用 | 需要批量操作时 | | graphql | 按需取字段，减少传输量 | 只需要部分字段时 |

三种传输层在功能上完全等价，可以随时通过 xndns config set transport <value> 切换。

错误处理

CLI 在出错时会返回非零退出码，错误信息格式：

[error_code] error_message

常见错误码：

| error_code | HTTP | 说明 | |---|---|---| | auth_invalid_credentials | 401 | 凭证无效 | | quota_exceeded | 429 | 配额超限 | | rate_limit_exceeded | 429 | 频率超限 | | subdomain_not_found | 404 | 子域名不存在 | | provider_operation_failed | 502 | 上游失败 |

完整错误码列表见 API 文档。

配置文件

~/.xndnsrc 是 JSON 格式，权限 600：

{
  "apiKey": "cfsd_xxx",
  "apiSecret": "yyyy",
  "host": "https://your-host",
  "transport": "rest"
}

优先级：命令行参数 > 环境变量 > 配置文件。

系统要求

Node.js 18+（内置 fetch）
Linux / macOS / Windows (WSL 或 Git Bash)
网络可访问小雫DNS 主机

开发

源码全部在 index.js 一个文件中，无构建步骤：

# 直接运行
node index.js help

# 调试
node --inspect index.js quota

License

MIT