Metadata-Version: 2.4
Name: shizukudns
Version: 2.0.2
Summary: shizukudns — DNSHE 免费域名 API 全栈管理工具（CLI + Web）。命令为 myn。pipx install shizukudns 推荐。
Author: shizukudns
License: MIT
Project-URL: Homepage, https://pypi.org/project/shizukudns/
Project-URL: Documentation, https://my.dnshe.com/knowledgebase/13/DNSHE-Free-Domain-API-User-Guide-V2.0.html
Project-URL: Source, https://pypi.org/project/shizukudns/
Keywords: dnshe,dns,subdomain,cloudflare,cli,domain,free-domain,whois
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: Name Service (DNS)
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: Flask>=3.0
Dynamic: license-file

# shizukudns

> DNSHE 免费域名 API 全栈管理工具（CLI + Web）。命令为 `myn`，覆盖 DNSHE Free Domain API v2.0 全部 18 个接口。

[![PyPI](https://img.shields.io/pypi/v/shizukudns.svg)](https://pypi.org/project/shizukudns/)
[![Python](https://img.shields.io/pypi/pyversions/shizukudns.svg)](https://pypi.org/project/shizukudns/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 安装

> shizukudns 是一个 **CLI 应用程序**，推荐用以下任一方式安装。

### 方式一：pipx（推荐，自动隔离环境）

`pipx` 会为每个 CLI 工具创建独立虚拟环境，命令全局可用，不会污染系统 Python。

```bash
# 安装 pipx（Debian/Ubuntu/macOS 均可）
sudo apt install pipx          # Debian/Ubuntu
# brew install pipx            # macOS
# pip install --user pipx      # 其他系统

pipx ensurepath               # 把 ~/.local/bin 加入 PATH（仅首次）
pipx install shizukudns
```

安装后 `myn` 命令全局可用。升级用 `pipx upgrade shizukudns`。

### 方式二：venv + pip

```bash
python3 -m venv ~/.venvs/shizukudns
source ~/.venvs/shizukudns/bin/activate
pip install shizukudns
myn -v
# 之后每次使用前先 activate，或直接用 ~/.venvs/shizukudns/bin/myn
```

### 方式三：pip --break-system-packages（不推荐，仅应急）

```bash
pip install --break-system-packages shizukudns
```

> ⚠️ 仅当上述方式不可用时使用，可能影响系统 Python。

### 方式四：直接下载运行（无需安装）

```bash
# 下载 wheel 后用 python 直接运行，无需安装
pip download shizukudns --no-deps -d ./sd
pip install --target ./sd -r <(pip show shizukudns 2>/dev/null || echo "requests Flask")
python -c "import sys; sys.path.insert(0,'./sd'); from shizukudns.cli import main; main()" -v
```

安装后即可使用 `myn` 命令。

## 快速开始

```bash
# 添加一个 DNSHE 账号（API Key + Secret）
myn account add 我的账号 cfsd_xxxxxxxxxx yyyyyyyyyyyy

# 查看配额
myn quota

# 列出子域名
myn sub list

# 启动 Web 管理界面
myn web
# 指定端口（--host 用于定义端口）
myn web --host 8080
```

## 命令总览

### 全局

| 命令 | 说明 |
|------|------|
| `myn -v`, `myn --version` | 查看版本 |
| `myn -h`, `myn --help` | 查看帮助 |
| `myn web` | 启动 Web 管理界面（默认 `http://127.0.0.1:7777`） |
| `myn web --host 8080` | 指定端口（`--host` 用于定义端口） |
| `myn web --bind 0.0.0.0` | 指定绑定地址 |
| `myn stats` | 查看本地统计 |

### 账号管理 (account)

```bash
myn account list                                   # 列出账号
myn account add <name> <api_key> <api_secret>       # 添加账号
myn account use <id>                                # 设为默认
myn account remove <id>                             # 删除账号
myn account show [id]                               # 查看详情
```

### 子域名 (sub)

```bash
myn sub list [page=1] [per_page=20] [search=xxx] [status=active]
myn sub get <subdomain_id>
myn sub register <subdomain> <rootdomain>
myn sub renew <subdomain_id>
myn sub delete <subdomain_id>
```

### DNS 记录 (dns)

```bash
myn dns list <subdomain_id>
myn dns create <subdomain_id> <type> <content> [name=@] [ttl=600] [priority=10]
myn dns update <id> [type=A] [content=...] [ttl=600]
myn dns delete <id|record_id>
```

### API 密钥 (keys)

```bash
myn keys list
myn keys create <key_name> [ip_whitelist=...]
myn keys regenerate <key_id>
myn keys delete <key_id>
```

### 配额 / WHOIS / 永久升级

```bash
myn quota
myn whois <domain>
myn upgrade list
myn upgrade create <subdomain_id>
myn upgrade assist <assist_code>
myn upgrade cancel <request_id>
```

### 操作日志

```bash
myn logs [page=1] [per_page=20] [endpoint=...] [success=true]
myn logs clear
```

## Web 界面

`myn web` 启动一个本地 Flask 服务，提供与 CLI 等价的全功能图形界面：

- **仪表盘**：配额概览 + 调用统计 + 端点分布 + 最近动态
- **子域名**：筛选 / 排序 / 分页 / 注册 / 续期 / 删除 / 导出 CSV
- **DNS 记录**：8 种记录类型（A/AAAA/CNAME/MX/TXT/NS/SRV/CAA）
- **API 密钥**：创建 / 列表 / 重置 Secret / 删除
- **配额 / WHOIS / 永久升级**
- **账号切换**：侧边栏一键切换
- **内置终端**：Web 版命令行
- **操作日志**：6 维筛选 + 详情 + 导出 CSV
- **深色模式**：跟随系统或手动切换

## 数据存储

配置与日志存储在 `~/.shizukudns/`：

- `config.json` — 账号列表（API Key + Secret）
- `logs.db` — SQLite 操作日志

可通过环境变量 `SHIZUKUDNS_HOME` 自定义数据目录。

## 覆盖的 API

覆盖 DNSHE Free Domain API v2.0 全部 **18** 个接口：

| 模块 | 接口 |
|------|------|
| 子域名 (5) | list / get / register / delete / renew |
| DNS 记录 (4) | list / create / update / delete |
| API 密钥 (4) | list / create / regenerate / delete |
| 配额 (1) | quota |
| WHOIS (1) | whois |
| 永久升级 (4) | list / create / assist / cancel |

## 技术栈

- Python ≥ 3.9
- [requests](https://pypi.org/project/requests/) — HTTP 客户端
- [Flask](https://pypi.org/project/Flask/) — Web 界面
- SQLite — 操作日志存储（Python 内置）

## License

MIT
