siujamo
97ad09ad8a
- store records in SQLite via built-in node:sqlite, no native deps - wrap DB reads in await io() so they stay out of the static shell - add CRUD pages backed by Server Actions with per-request data - generate managed config and restart container via Docker socket - add /resolve page to query dnsmasq for A and CNAME records - add Dockerfile and compose setup with shared config volume
83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
# dnsmasq-admin
|
||
|
||
一个极简的 Web UI，用来管理运行在 Docker 里的 dnsmasq 的 DNS 记录：域名记录的增删改查 + 一个解析测试页。
|
||
|
||
- **记录列表**（`/records`）：新增、编辑、启用/禁用、删除
|
||
- **解析测试**（`/resolve`）：向 dnsmasq 发起 DNS 查询，验证记录是否已生效
|
||
- 支持 **A** 与 **CNAME** 两种记录类型
|
||
|
||
## 工作原理
|
||
|
||
```
|
||
┌──────────┐ 写 /etc/dnsmasq.d/dnsmasq-admin.conf ┌──────────┐
|
||
│ 浏览器 │ ──────────> dnsmasq-admin (Next.js) ─────>│ dnsmasq │
|
||
└──────────┘ Docker socket: restart 容器 └──────────┘
|
||
│
|
||
└─> SQLite（唯一数据源）
|
||
```
|
||
|
||
1. 所有记录存在 **SQLite** 里（用 Node 内置的 `node:sqlite`，**没有任何原生依赖**，`node_modules` 里不会多出编译产物）。
|
||
2. 增删改都只改数据库，**不会立刻影响 dnsmasq**。
|
||
3. 点「应用并重启」后：按启用的记录重新生成托管配置文件 → 通过 Docker socket 重启 dnsmasq 容器使其生效。
|
||
|
||
之所以做成手动触发，是为了让你能先攒一批改动，再一次性重启 —— 每次改一条就重启一次容器没有必要，而且会让 DNS 短暂中断。
|
||
|
||
`address=/example.com/192.168.1.10` 这种写法会同时命中 `example.com` 及其**所有子域名**，所以不需要额外的通配符语法。
|
||
|
||
## 本地开发
|
||
|
||
需要 **Node >= 22.5**（`node:sqlite` 的最低要求）。
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm dev
|
||
```
|
||
|
||
打开 <http://localhost:3000>，会被重定向到 `/records`。
|
||
|
||
本地运行不需要配任何环境变量 —— 数据库默认落在 `./data/dnsmasq-admin.db`，生成的配置默认落在 `./data/dnsmasq-admin.conf`。需要调整时复制 `.env.example` 为 `.env.local`。
|
||
|
||
在 **Windows / macOS 桌面上开发**时没有 `/var/run/docker.sock`，点「应用并重启」会提示「重启已跳过」，但配置文件**照常生成**，可以用来自查内容是否正确。完整的重启链路需要在装了 Docker 的 Linux 上验证。
|
||
|
||
## Docker 部署
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
`docker-compose.yml` 里同时给了 dnsmasq 和 web 两个服务用于开箱联调。如果你已经有自己的 dnsmasq 容器，删掉 `dnsmasq` 服务，把 `dnsmasq-conf` 这个 volume 挂到你容器里的 `/etc/dnsmasq.d` 即可：
|
||
|
||
```yaml
|
||
# 在你现有的 dnsmasq 容器上加：
|
||
volumes:
|
||
- dnsmasq-conf:/etc/dnsmasq.d
|
||
```
|
||
|
||
注意两个 volume 都要保留：`app-data` 存着 SQLite 数据库，删了等于记录全丢。
|
||
|
||
## 环境变量
|
||
|
||
见 [`.env.example`](.env.example)。
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `DNSMASQ_ADMIN_DB_PATH` | `./data/dnsmasq-admin.db` | SQLite 数据库位置 |
|
||
| `DNSMASQ_ADMIN_CONF_PATH` | `./data/dnsmasq-admin.conf` | 生成的托管配置文件 |
|
||
| `DNSMASQ_CONTAINER_NAME` | `dnsmasq` | 应用后要重启的容器名 |
|
||
| `DNSMASQ_ADMIN_DOCKER_SOCKET` | `/var/run/docker.sock` | Docker socket 路径；不存在则跳过重启 |
|
||
| `DNSMASQ_SERVER_IP` | `127.0.0.1` | `/resolve` 页查询用的 DNS 服务器 |
|
||
|
||
## ⚠️ 安全提示
|
||
|
||
**这个应用当前没有任何鉴权** —— 任何能访问到它的人都能增删 DNS 记录并重启你的 dnsmasq 容器。请务必只监听内网或本机，**不要暴露到公网**。
|
||
|
||
在 compose 里 `web` 挂载了 `/var/run/docker.sock`，这意味着该容器具备控制宿主机 Docker 的能力。这是设计使然（需要在应用后重启 dnsmasq），但应当把它当作高权限服务看待：不要用它跑不可信代码，端口只映射到内网网卡（如 `127.0.0.1:3000:3000`）而非 `0.0.0.0`。
|
||
|
||
## 技术备注（Next.js 16）
|
||
|
||
本项目启用了 `cacheComponents: true`，即 Next 16 的 Cache Components / PPR 模式。
|
||
|
||
这里踩到一个关键点：`node:sqlite` 是**同步**驱动，如果不显式处理，它的查询结果会在**构建期**被烤进预渲染的静态 shell，上线后页面永远显示构建时的旧数据。官方 issue 文档明确提到了这一点（`node_modules/next/dist/docs/01-app/03-api-reference/04-functions/io.md`），解法是在读库前 `await io()`，并把数据组件包在 `<Suspense>` 里 —— 参见 `lib/records.ts`。
|
||
|
||
同理，时间戳一律用 SQL 的 `datetime('now')` 而非 JS 的 `new Date()`，后者在预渲染阶段会直接导致构建失败。
|