Metadata-Version: 2.4
Name: shizukudns
Version: 2.2.1
Summary: shizukudns — DNSHE 免费域名 API 全栈管理工具（CLI + Web）。命令 myn，支持自定义美化、PWA、跨账号搜索、子域名整合 DNS、内置语言包（含猫羽雫猫娘定制）。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 个接口。支持自定义美化、PWA、跨账号整合搜索、内置语言包（含猫羽雫猫娘定制）。

[![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)

## ✨ 功能特性

- **全覆盖 API**：DNSHE Free Domain API v2.0 全部 18 个接口，CLI + Web 双重覆盖
- **多账号管理**：本地存储多组 API 凭证，一键切换
- **跨账号整合搜索**：搜索某个域名在哪个账号下，点击直达 DNS 记录管理
- **子域名 + DNS 一体化**：子域名页面直接展开管理该域名的 DNS 记录（无需切换 tab）
- **自定义美化**：全局背景图、自定义 CSS、主题强调色、自定义 favicon、自定义模块
- **内置语言包**：默认中文 + 猫羽雫定制（猫娘风格，称呼用户为"老婆"，自称"小雫"）
- **PWA 支持**：可安装到桌面/主屏幕，离线缓存
- **内置终端**：Web 版命令行，覆盖全部 API
- **完整操作日志**：所有 API 调用自动记录，支持筛选/详情/导出 CSV
- **移动端适配**：竖屏手机友好，汉堡菜单抽屉式侧栏
- **深色模式**：跟随系统或手动切换
- **8 种 DNS 记录**：A / AAAA / CNAME / MX / TXT / NS / SRV / CAA

## 安装

> 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
pip download shizukudns --no-deps -d ./sd
pip install --target ./sd requests Flask
python -c "import sys; sys.path.insert(0,'./sd'); from shizukudns.cli import main; main()" -v
```

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

## 快速开始

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

# 2. 环境自检（版本/依赖/账号/网络连通性）
myn selfcheck

# 3. 查看配额
myn quota

# 4. 列出子域名
myn sub list

# 5. 启动 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 web --no-open` | 不自动打开浏览器 |
| `myn stats` | 查看本地统计 |
| `myn selfcheck` | 环境自检（版本/依赖/账号/网络/安装建议） |

### 账号管理 (account)

```bash
myn account list                                   # 列出账号
myn account add <name> <api_key> <api_secret>       # 添加账号
myn account add <name> <key> <secret> --note 备注   # 带备注
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] [sort_by=created_at] [sort_dir=desc]
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] [line=default]
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>     # 重置 Secret（仅显示一次）
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] [source=cli]
myn logs clear
```

## Web 界面

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

### 页面

| 页面 | 路径 | 功能 |
|------|------|------|
| 仪表盘 | `/` | 配额概览 + 调用统计 + 端点分布 + 最近动态 |
| 子域名 | `/subdomains` | 筛选/排序/分页/注册/续期/删除/**展开管理 DNS 记录**/导出 CSV |
| API 密钥 | `/keys` | 创建/列表/重置 Secret/删除 |
| 配额查询 | `/quota` | 配额概览 + 原始响应 |
| 永久升级 | `/upgrade` | 任务列表/创建/助力/取消 |
| **跨账号搜索** | `/search` | 搜索域名在哪个账号，点击直达 DNS 管理 |
| WHOIS 查询 | `/whois` | 公开 WHOIS 查询 |
| 内置终端 | `/terminal` | Web 版命令行，覆盖全部 API |
| 操作日志 | `/logs` | 6 维筛选 + 详情 + 导出 CSV + 清空 |
| 账号管理 | `/accounts` | 多账号增删改、设默认 |
| **外观定制** | `/customize` | 语言包/背景图/CSS/强调色/favicon/模块/PWA |

### 自定义美化（外观定制页）

访问 `/customize` 可自定义：

- **语言包**（置顶）：默认中文 / 猫羽雫定制（猫娘风格，称呼用户"老婆"，自称"小雫"）
- **全局背景图**：URL 输入 + 蒙层透明度调节，有背景图时卡片/侧栏自动半透明 + 毛玻璃效果
- **主题强调色**：6 色预设（绿/蓝/紫/红/橙/粉）+ 自定义颜色
- **自定义 CSS**：全局注入，影响所有页面
- **自定义 Favicon**：URL 或 data URI
- **自定义模块**：在页面顶部添加自定义 HTML 模块（公告/说明等）
- **PWA 开关**：可安装到桌面/主屏幕，离线缓存

#### 内置语言包

| 语言 | 说明 |
|------|------|
| 默认中文 | 标准技术风格 |
| 猫羽雫定制 | 萌萌猫娘风格，称呼用户为"老婆"，自称"小雫"，文案带表情符号 |

切换后保存，全站文案（导航/按钮/提示/页脚等）即时变为对应语言风格。

### 移动端适配

- 竖屏手机友好，汉堡菜单抽屉式侧栏
- 卡片单列堆叠，表格横向滚动
- 模态框底部铺满，单手操作友好
- 支持 320px~768px 宽度

## 数据存储

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

- `config.json` — 账号列表 + 外观设置
- `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 |

## 环境自检

遇到问题时运行 `myn selfcheck` 一键诊断：

```
shizukudns 自检
  版本:        2.1.0
  Python:      3.12.13 (Linux x86_64)
  数据目录:    /home/user/.shizukudns
  依赖:        requests 2.32.5 · Flask 3.1.3
  账号数:      1
  默认账号:    我的账号（cfsd•••••••xxxx）

网络连通性:
✓ DNSHE API 可达（HTTP 401）

安装建议:
  若 pip install 报 externally-managed-environment:
  pipx install shizukudns    # 推荐
  pip install --break-system-packages shizukudns    # 应急
```

## 技术栈

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

## License

MIT
