# NowDNS 快速上手教程

这份教程带您从零开始完成以下事情：

1. 启动 NowDNS。
2. 创建管理员密码并登录。
3. 用快速配置向导创建动态域名，或为 Tailscale 设备创建域名。
4. 查看并应用 DNS 变更。
5. 日后更新、暂停、恢复或删除记录。

不需要先了解 DNS、接口或服务器等专业词。跟着页面上的提示填写即可。

> **本教程中的截图位置**
>
> 每个 `<!-- SCREENSHOT: ... -->` 都是预留的截图标签。可将该标签替换为对应图片，例如：`![登录页面](images/01-login.png)`。

---

## 1. 先了解 NowDNS 能做什么

NowDNS 会把一个地址对应到您自己的域名上。

常见的两种用法如下：

| 您的情况 | 应选择的方式 | 示例 |
| --- | --- | --- |
| 家里的公网 IP 会变化 | **动态域名** | 让 `home.yourdomain.cn` 始终指向家里的网络 |
| 想给 Tailscale 里的设备取一个好记的名字 | **Tailscale 设备域名** | 让 `nas.yourdomain.cn` 指向 NAS |

NowDNS 会把密钥保存在您自己的电脑或服务器里。它不会要求您把密钥发给其他人。

---

## 2. 开始前准备

开始前，请准备好以下内容。

### 2.1 所有用户都需要

- 一台可以一直开机的 Windows、Linux 或 macOS 电脑/服务器。
- 一个您要使用的域名，例如 `yourdomain.cn`。
- 该域名解析服务的登录信息或解析接口密钥。

如果您的域名在时代互联，请按页面提示准备域名、域名 ID 和解析密钥。使用其他服务商时，请准备该服务商提供的解析接口信息。

### 2.2 只做动态域名时需要

- 一个可以查询公网 IPv4、IPv6 地址的网址。

如果您不知道该填什么，先使用向导中的默认内容即可。

### 2.3 只做 Tailscale 设备域名时需要

- 可以读取设备列表的 Tailscale API Key。
- 您的 Tailscale 网络名称。大多数用户可以保持向导中的默认值。

> **安全提醒**
>
> API Key、Secret、密码都是私密信息。不要把它们发送到聊天记录、工单、截图或公开文章中。

---

## 3. 下载与放置文件

下载与您的系统和 CPU 类型相符的发布包，解压到一个固定目录。

建议使用一个专门目录，例如：

```text
D:\NowDNS\
```

或：

```text
/opt/nowdns/
```

解压后，不要只移动 `nowdns.exe` 或 `nowdns` 文件。请保留整个目录中的文件。

Windows 发布目录通常包含：

```text
nowdns.exe
service.bat
service.ps1
安装服务.bat
启动服务.bat
停止服务.bat
打开控制台.bat
config.example.yaml
user-guide.md
```

Linux 发布目录通常包含：

```text
nowdns
service.sh
config.example.yaml
user-guide.md
```

第一次运行后，NowDNS 会在当前目录创建：

```text
config.yaml
data/
```

其中 `data/` 保存程序数据，后续不要随意删除。

<!-- SCREENSHOT: 01-release-folder | 发布目录文件列表，突出 nowdns.exe、service.bat 和 user-guide.md -->

---

## 4. 第一次启动

请选择与您使用方式相符的一种方法。

### 方法 A：先在前台试用

这种方法最适合第一次使用。关闭命令窗口后，程序会停止。

#### Windows

1. 在发布目录空白处按住 `Shift` 并点击鼠标右键。
2. 选择“在此处打开 PowerShell”。
3. 输入：

```powershell
.\nowdns.exe
```

#### Linux 或 macOS

进入发布目录后输入：

```sh
chmod +x ./nowdns
./nowdns
```

正常情况下，程序会显示访问地址，并自动打开浏览器。

默认地址是：

```text
http://127.0.0.1:8080
```

如果浏览器没有自动打开，请把上面的地址复制到浏览器地址栏。

<!-- SCREENSHOT: 02-first-start-terminal | 首次启动后的终端窗口，突出访问地址和首次设置提示 -->

### 方法 B：安装为系统服务

这种方法适合准备长期使用的用户。安装后，电脑重启时 NowDNS 会自动启动。

#### Windows 推荐方法

1. 双击 `service.bat`。
2. Windows 询问是否允许管理员权限时，选择“是”。
3. 在菜单中输入 `1`。
4. 等待“安装、启动并设置开机自启”完成。
5. 服务端口准备好后，默认浏览器会自动打开管理页面。

也可以直接双击 `安装服务.bat` 完成一次性安装。

<!-- SCREENSHOT: 03-windows-service-menu | Windows 服务菜单，突出选项 1 -->

#### Linux 推荐方法

在发布目录中输入：

```sh
chmod +x ./service.sh
sudo ./service.sh
```

然后在菜单中选择 `1`。

Linux 服务安装完成后，请在浏览器打开配置的管理地址。默认是：

```text
http://127.0.0.1:8080
```

> **注意**
>
> Windows 安装脚本会自动打开浏览器。Linux 通常没有桌面浏览器，因此需要您自行打开地址。

---

## 5. 创建管理员密码

第一次打开管理页面时，会看到管理员设置页面。

1. 输入一个只有您知道的管理员密码。
2. 再输入一次确认密码。
3. 点击“完成设置”。
4. 使用刚才的密码登录。

建议密码至少 8 个字符，并且不要与其他网站重复。

<!-- SCREENSHOT: 04-admin-setup | 管理员密码设置页面 -->

登录后会进入首页。

---

## 6. 首页怎么用

首页可以快速看到：

- 下一次 DNS 同步时间。
- 上一次同步是否成功。
- 已添加的数据源、设备、记录、接入商和域名数量。
- 常用入口。

第一次使用、且还没有添加接入商和域名时，首页会显示“快速开始”提示。

1. 点击“打开快速配置向导”开始设置。
2. 如果您已经熟悉操作，可以点击“不再提示”。

“不再提示”只记录在当前浏览器中。换一台电脑或清除浏览器的网站数据后，提示可能再次出现。

<!-- SCREENSHOT: 05-dashboard-first-use-hint | 首页快速开始提示框，突出“打开快速配置向导”和“不再提示” -->

---

## 7. 最简单的方法：使用快速配置向导

点击首页的“快速配置向导”，会看到两种方式：

1. **动态域名**：适合公网 IP 会变化的家庭宽带、办公室网络或小型服务器。
2. **Tailscale 设备域名**：适合给 Tailscale 内的设备设置容易记住的域名。

请只选择一种开始。以后随时可以回来添加另一种。

<!-- SCREENSHOT: 06-wizard-choice | 快速配置向导首页，展示两个入口 -->

---

## 8. 教程一：设置动态域名

下面以 `home.yourdomain.cn` 为例。

### 第一步：选择或新建公网 IP 数据源

页面会让您选择已有数据源，或点击“新建数据源”。

第一次使用时：

1. 点击“新建数据源”。
2. 填写一个容易识别的名称，例如“家庭宽带”。
3. 选择要使用 IPv4、IPv6，还是两者都使用。
4. 保留默认查询地址，或填写您自己的地址查询网址。
5. 点击“下一步”。

### IPv4、IPv6 与 A、AAAA 的关系

不需要记住复杂规则，只要记住下表即可：

| 在第一步启用的地址 | 向导会自动创建的记录 |
| --- | --- |
| 只启用 IPv4 | 一条 A 记录 |
| 只启用 IPv6 | 一条 AAAA 记录 |
| IPv4 和 IPv6 都启用 | 一条 A 记录和一条 AAAA 记录 |

例如您填写 `home`，并且同时启用了 IPv4 和 IPv6，向导会创建：

```text
home.yourdomain.cn  A
home.yourdomain.cn  AAAA
```

<!-- SCREENSHOT: 07-ddns-source-step | 动态域名向导第一步，突出 IPv4/IPv6 开关和查询地址 -->

### 第二步：选择或新建 DNS 接入商与域名

这一页用于告诉 NowDNS：您的域名在哪里管理，以及要使用哪个域名。

#### 使用已有接入商和域名

1. 在“DNS 接入商”下拉框中选择已有接入商。
2. 在“域名”下拉框中选择已有域名。
3. 点击“下一步”。

#### 新建接入商

1. 点击“新建接入商”。
2. 选择与您实际服务相符的类型。
3. 填写名称。这个名称只用于您自己识别，例如“我的域名解析”。
4. 按页面字段填写密钥。
5. 如果页面要求填写绑定域名，请填写完整域名，例如 `yourdomain.cn`。
6. 点击“下一步”。

使用时代互联服务时，请选择与您购买域名的网站相符的选项，并按页面提示填写域名和解析信息。

#### 新建域名

如果没有可选域名：

1. 点击“新建域名”。
2. 填写根域名，例如 `yourdomain.cn`。
3. 默认 TTL 保持 `600` 即可。
4. 点击“下一步”。

> **不要这样填写**
>
> 这里应填写 `yourdomain.cn`，不要填写 `home.yourdomain.cn`。`home` 这类前缀会在下一步填写。

<!-- SCREENSHOT: 08-provider-and-zone-step | 动态域名向导第二步，展示接入商和域名选择 -->

### 第三步：填写记录名称

1. 在“记录名称”中填写前缀，例如 `home`。
2. 右侧会显示完整名称，例如 `.yourdomain.cn`。
3. 页面会显示将要自动创建的记录类型。
4. TTL 保持 `0` 即可，表示使用域名的默认值。
5. 保持“启用记录”已勾选。
6. 点击“保存配置”。

向导不会再让您手动选择 A 或 AAAA。它会根据第一步的 IPv4/IPv6 选择自动创建正确的记录。

<!-- SCREENSHOT: 09-ddns-record-step | 动态域名向导第三步，突出记录名称后缀和自动创建的 A/AAAA 提示 -->

### 第四步：查看并应用变更

保存后，向导会生成 DNS 变更预览。

1. 检查记录名称、类型和地址是否正确。
2. 没有问题时，点击“立即应用”。
3. 看到成功状态后，动态域名就完成了。

<!-- SCREENSHOT: 10-wizard-ddns-preview | 向导完成页的待应用变更和立即应用按钮 -->

---

## 9. 教程二：给 Tailscale 设备设置域名

下面以 NAS 为例。

### 第一步：选择或新建 Tailscale 数据源

1. 选择已有数据源，或点击“新建数据源”。
2. 填写一个名称，例如“我的 Tailscale 网络”。
3. 填写 Tailscale API Key。
4. 大多数用户可以保留默认网络名称。
5. 点击“下一步”。

NowDNS 会在保存时自动验证并读取设备列表：API Key 不正确时会立即提示错误且不会保存，验证通过则直接显示可用设备，无需再手动同步。

<!-- SCREENSHOT: 11-tailscale-source-step | Tailscale 数据源创建页 -->

### 第二步：选择接入商和域名

这一步与动态域名相同：选择或新建 DNS 接入商，再选择或新建域名。

请再次确认：这里填写的是根域名，例如 `yourdomain.cn`。

### 第三步：选择设备

1. 勾选想要发布的设备。
2. 点击“保存配置”。
3. 查看向导生成的 DNS 变更。
4. 确认无误后点击“立即应用”。

NowDNS 会为您选择的设备创建对应记录。以后设备地址变化时，NowDNS 会按计划检查并更新。

<!-- SCREENSHOT: 12-tailscale-node-step | 设备选择页面，展示可勾选设备列表 -->

---

## 10. 不使用向导时，如何手动设置

熟悉后，您可以在左侧菜单中逐项操作。

推荐顺序如下：

1. **数据源**：添加公网 IP 数据源或 Tailscale 数据源。
2. **DNS 接入商**：添加域名解析服务信息。
3. **域名**：添加要管理的根域名。
4. **DDNS 记录** 或 **节点**：创建具体记录。
5. **DNS 同步**：预览并应用变更。

这个顺序很重要：没有数据源、接入商或域名时，后面的页面会提示您先完成前面的内容。

---

## 11. DDNS 记录页面详细说明

打开“DDNS 记录”页面后，每一行代表一条动态域名记录。

页面会显示：

| 内容 | 含义 |
| --- | --- |
| 记录 | 您设置的完整域名和类型 |
| 数据源 | 这条记录使用哪个公网 IP 数据源 |
| 当前地址 | 最近一次读取到的公网地址 |
| 上次读取 | 最近一次读取公网地址的时间和结果 |
| 状态 | 是否正在使用、是否停止解析、是否有冲突 |
| 操作 | 对这一条记录可执行的操作 |

<!-- SCREENSHOT: 13-ddns-records-list | DDNS 记录列表，标注每一列和“立即更新”按钮 -->

### 11.1 立即更新一条 DDNS 记录

对已启用的记录，点击“立即更新”。

NowDNS 会按以下顺序处理：

1. 读取这条记录对应数据源的最新公网地址。
2. 只检查这条记录需要的 DNS 变更。
3. 直接创建或更新这条记录。

它**不会**顺手应用其他 DDNS 记录、设备记录或 DNS 同步页面中等待处理的变更。

如果页面显示冲突，请先检查是否有其他工具或其他记录占用了相同的名称和类型。

> **什么时候用“立即更新”**
>
> - 刚完成设置，想立刻生效。
> - 知道公网地址已经变化，不想等待下一次自动检查。
> - 只想更新其中一条记录。

### 11.2 编辑

点击“编辑”可以修改记录名称、记录类型、TTL 和启用状态。

数据源和所属域名不能在编辑时直接修改。需要换数据源或域名时，请新建一条记录，再停止旧记录的解析。

### 11.3 启用和禁用

- **禁用**：保留配置和当前 DNS 记录，不再自动更新。
- **启用**：恢复自动更新。

### 11.4 停止解析、恢复解析与立即删除

| 操作 | 会发生什么 |
| --- | --- |
| 停止解析 | 不再更新该名称；现有记录进入保护等待期 |
| 恢复解析 | 取消停止状态，重新允许更新 |
| 立即删除 | 跳过等待期，直接删除服务商上的对应记录 |
| 删除配置 | 删除 NowDNS 中的设置；需要先停止解析并清理对应记录 |

如果只是暂时不用，建议选择“停止解析”，不要直接删除配置。

---

## 12. DNS 同步页面详细说明

大多数设置变更会先出现在“DNS 同步”页面。

这能让您先看清楚将要发生什么，再决定是否应用。

### 12.1 生成预览

1. 打开“DNS 同步”。
2. 点击页面顶部的“生成预览”。
3. 等待列表加载完成。

预览中常见的状态：

| 状态 | 含义 |
| --- | --- |
| 创建 | 将新增一条记录 |
| 更新 | 将把已有记录改成新地址或新设置 |
| 删除 | 将删除不再需要的记录 |
| 无变化 | 记录已经正确，不需要处理 |
| 冲突 | 同名记录被其他设置占用，需要先处理 |

<!-- SCREENSHOT: 14-dns-preview | DNS 同步预览，展示汇总、域名卡片和记录列表 -->

### 12.2 应用预览

预览生成后：

1. 从上到下检查每个域名卡片。
2. 特别确认记录名称、类型和目标地址。
3. 滚动到页面底部。
4. 点击底部的“应用更新”。
5. 如页面要求再次确认删除操作，请认真确认后继续。

顶部保留“生成预览”按钮，方便您随时重新生成最新预览；真正的“应用更新”按钮在预览列表底部，便于先完整阅读再操作。

<!-- SCREENSHOT: 15-dns-apply-bottom | DNS 同步页面底部的应用更新按钮 -->

### 12.3 遇到冲突怎么办

如果看到“冲突”：

1. 不要反复点击“应用更新”。
2. 查看冲突记录的名称和类型。
3. 检查该记录是否被其他设置、其他程序或手工解析占用。
4. 处理冲突后，重新点击“生成预览”。

---

## 13. DNS 自动更新什么时候发生

NowDNS 默认每 5 分钟检查一次已启用的数据源。

检查成功后：

- 公网地址变化时，DDNS 记录会按设置更新。
- Tailscale 设备信息变化时，相关记录会按设置更新。
- 暂停的接入商、域名或记录不会进行 DNS 操作。

如果不想等待：

- DDNS 记录：在该条记录上点击“立即更新”。
- 数据源：在“数据源”页面手动同步。
- 其他 DNS 变更：在“DNS 同步”页面生成预览并应用。

---

## 14. 安全删除保护是什么

为了避免网络临时问题导致记录被误删，NowDNS 不会马上删除不再需要的记录。

默认流程是：

1. 记录先被标记为“等待清除”。
2. 等待保护期，默认是 168 小时，也就是 7 天。
3. 后续检查仍然确认不需要时，才会删除。

数据源读取失败不会推进删除流程。

如果您确认要立刻删除，可以在已停止解析的记录上使用“立即删除”。这项操作无法撤销，请谨慎使用。

---

## 15. 日常查看和维护

### 首页

查看服务是否正常、下一次检查时间和已配置项目数量。

### 数据源

查看公网地址或设备是否读取成功。读取失败时，先检查数据源设置和网络连接。

### DNS 接入商

查看接入商是否启用。暂停接入商后，NowDNS 不会对其域名进行 DNS 操作。

### 域名

查看域名是否启用、默认 TTL，以及由 NowDNS 管理的记录状态。

### DDNS 记录

需要立刻更新单条动态域名时，点击“立即更新”。

### 审计记录

查看设置和 DNS 操作的大致时间与结果。出现问题时，先查看这里和相关页面的错误提示。

---

## 16. 备份：请一定保留这三项

如果您已经正式使用 NowDNS，请定期备份：

```text
data/nowdns.db
data/credential.key
config.yaml
```

它们的作用如下：

| 文件 | 用途 |
| --- | --- |
| `data/nowdns.db` | 保存设置、记录和操作历史 |
| `data/credential.key` | 用于读取已保存的密钥 |
| `config.yaml` | 保存监听地址、日志和检查间隔等设置 |

如果缺少 `credential.key`，已经保存的 Tailscale 密钥和 DNS 解析密钥无法恢复。

> **备份建议**
>
> 先停止 NowDNS，再复制这三个文件。不要把包含密钥的备份公开上传。

---

## 17. 常用设置

大多数用户不需要修改 `config.yaml`。

如果确实需要调整，请先停止程序或服务，再编辑文件，保存后重新启动。

常见内容如下：

```yaml
server:
  listen: 127.0.0.1:8080
  open_browser: true

scheduler:
  interval: 5m

safe_delete:
  grace_period: 168h

updates:
  enabled: false
  channel: stable
  feed_url: https://www.now.cn/download/nowdns/manifest.json
  interval: 24h
  startup_delay: 2m
```

简单说明：

| 设置 | 含义 | 建议 |
| --- | --- | --- |
| `listen` | 管理页面访问地址 | 首次使用保持默认 |
| `open_browser` | 启动时是否自动打开浏览器 | 保持 `true` |
| `scheduler.interval` | DNS 数据源自动检查间隔 | 保持 `5m` |
| `grace_period` | 删除前的保护等待时间 | 保持 `168h` |
| `updates.enabled` | 是否自动检查 NowDNS 新版本 | 部署可用 HTTPS 更新源后设为 `true`；开发构建不会联网 |
| `updates.channel` | 软件更新通道 | 正式使用保持 `stable` |
| `updates.interval` | 软件版本检查间隔 | 保持 `24h` |

管理页面的“系统设置”会显示当前版本、最近检查时间和新版本提示，也可手动点击“立即检查”。发现新版本后，可通过下载页面完成手动更新。

维护私有更新服务器、发布版本或集成更新 API 时，请参阅开发文档 [软件更新检查协议](update-checking.md)。

> **不要直接暴露管理页面**
>
> 默认地址只允许本机访问。若需要从其他设备访问，请先完成管理员设置，并使用 HTTPS 和访问限制保护页面。不了解这些设置时，建议先保持默认。

---

## 18. Windows 服务管理

在 Windows 发布目录中，推荐使用 `service.bat`。

| 您要做什么 | 操作 |
| --- | --- |
| 安装并开机自启 | 双击 `service.bat`，选 `1`；或双击 `安装服务.bat` |
| 启动 | 双击 `启动服务.bat` |
| 停止 | 双击 `停止服务.bat` |
| 卸载 | 双击 `卸载服务.bat` |
| 打开管理页面 | 双击 `打开控制台.bat` |
| 查看日志或配置 | 双击 `service.bat`，在菜单中选择对应项目 |

安装服务后，NowDNS 会等待服务端口就绪并自动打开管理页面。

<!-- SCREENSHOT: 16-windows-service-success | Windows 安装完成提示和自动打开的管理页面 -->

---

## 19. Linux 服务管理

在 Linux 发布目录中：

```sh
chmod +x ./service.sh
sudo ./service.sh
```

在菜单中选择对应操作：

| 选项 | 含义 |
| --- | --- |
| 1 | 安装并设置开机自启 |
| 2 | 启动服务 |
| 3 | 停止服务 |
| 4 | 重启服务 |
| 5 | 查看状态 |
| 6 | 查看最近日志 |
| 10 | 卸载服务 |

如果服务器没有图形界面，请从您自己的电脑浏览器访问服务器的管理地址。首次设置时，建议先通过安全的内部网络访问。

---

## 20. 常见问题

### 浏览器没有自动打开

请手动打开：

```text
http://127.0.0.1:8080
```

如果您修改过 `config.yaml` 中的 `listen`，请使用修改后的地址。

Windows 服务安装后，也可以双击 `打开控制台.bat`。

### 登录后又回到登录页

请确认您使用的访问方式与安全设置一致。

- 本机直接打开 `http://127.0.0.1:8080` 时，通常不需要额外设置。
- 通过 HTTPS 网页转发服务访问时，需要正确开启 Secure Cookie。

不确定时，先改回本机默认访问方式确认能否正常登录。

### DDNS 记录没有更新

按顺序检查：

1. 该记录是否处于“已启用”状态。
2. 该记录的数据源是否启用。
3. 在 DDNS 记录页面点击“立即更新”。
4. 查看“当前地址”和“上次读取”是否显示成功。
5. 如果仍失败，查看页面错误详情或“审计记录”。

### 域名没有解析到新地址

如果您刚完成向导，请先到“DNS 同步”页面：

1. 点击“生成预览”。
2. 确认列表中有您的记录。
3. 滚动到页面底部，点击“应用更新”。

使用“立即更新”时，NowDNS 会直接处理该条已启用的 DDNS 记录；其他类型的变更仍需要通过 DNS 同步页面应用。

### 页面显示冲突

这通常表示同一个名称和类型已被其他记录或其他工具使用。

请检查服务商侧是否已有同名记录，也检查 NowDNS 中是否存在重复设置。处理后重新生成预览或再次点击“立即更新”。

### 忘记管理员密码

不要直接删除数据库。请先备份 `data/nowdns.db`、`data/credential.key` 和 `config.yaml`，再联系维护人员处理。

---

## 21. 操作前快速检查表

第一次真正应用 DNS 变更前，请确认：

- [ ] 管理页面能正常登录。
- [ ] 数据源读取成功。
- [ ] DNS 接入商和域名均已启用。
- [ ] 记录名称正确，例如 `home.yourdomain.cn`。
- [ ] DNS 预览中的地址正确。
- [ ] 没有不认识的删除操作。
- [ ] 已备份 `data/nowdns.db`、`data/credential.key` 和 `config.yaml`。

完成以上检查后，就可以放心点击“应用更新”或对单条 DDNS 记录点击“立即更新”。
