# coredns-manager

**Repository Path**: winnerxue/coredns-manager

## Basic Information

- **Project Name**: coredns-manager
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-29
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CoreDNS Manager

CoreDNS 管理后端（Go + SQLite）。

当前仓库以**后端重构 + embed 前端交付**为主线：
- 新架构：`api -> service -> store -> sqlite`
- 单库 `manager.db`（结构化存储 Zone/Record/Route/Health）
- 自动同步：DB 变更 -> 生成 zone 文件/Corefile -> 重载 CoreDNS
- 前端静态资源通过 `go:embed` 内置到二进制并由后端统一服务

## 当前状态

- 后端主链路已切换到新架构目录：
  - `internal/api`
  - `internal/service`
  - `internal/store`
  - `internal/domain`
  - `internal/zonefile`
  - `internal/adguard`
  - `internal/app`
- 前端通过 `internal/webui/dist` 被 embed 到后端，可与 API 一起发布。

## 核心能力

- Zone 管理：创建/更新/删除/导入/导出
- Record 管理：分页查询、增删改、批量删除、批量启停、排序
- 路由规则管理：CRUD、启停、重排、同步到 AdGuard
- 健康检查：服务配置、结果持久化、立即检测、后台轮询
- Corefile 管理：读取、保存、历史、恢复
- 系统能力：日志查询、手动同步、CoreDNS 重载

## 架构说明

### 分层调用

`api -> service -> store -> sqlite`

- `api`：HTTP 路由、参数解析、统一响应
- `service`：业务规则、联动编排（同步、AdGuard、健康检查）
- `store`：SQLite 数据访问
- `domain`：共享领域模型与统一错误类型
- `zonefile`：zone/Corefile 文本解析与生成

### 同步链路

1. API 写入业务数据（Zone/Record/Route 等）
2. service 触发 `SyncService.Notify(...)`
3. 防抖聚合后执行同步
4. 从 DB 读取启用配置
5. 生成并写入 zone 文件与 Corefile
6. 触发 CoreDNS reload

## 数据存储

默认数据目录：`{corednsdir}/data`

主要表（单库）：
- `zones`
- `records`
- `routing_rules`
- `health_services`
- `health_results`
- `settings`
- `operation_log`
- `corefile_history`
- `zone_exports`

## 快速开始

### 1) 环境要求

- Go 1.21+
- Node.js 20+（构建 embed 前端产物时必需）

### 2) 运行方式

```bash
go run . -addr=:8080 -corednsdir=/etc/coredns
```

或先构建：

```bash
go build -o coredns-manager .
./coredns-manager -addr=:8080 -corednsdir=/etc/coredns
```

### 3) 启动参数

| 参数 | 默认值 | 说明 |
|---|---|---|
| `-addr` | `:8080` | HTTP 监听地址 |
| `-corednsdir` | `/etc/coredns` | CoreDNS 根目录（自动创建 `zones/`、`data/`） |
| `-prefix` | 空 | 反向代理子路径前缀（如 `/dns-admin`） |
| `-adguard-url` | 空 | AdGuard Home API URL |
| `-adguard-user` | 空 | AdGuard 用户名 |
| `-adguard-pass` | 空 | AdGuard 密码 |

### 4) 路由访问约定

- 无 prefix（默认）：
  - 前端：`/`
  - API：`/api/*`
  - 健康检查：`/healthz`

- 有 prefix（例如 `-prefix=/dns-admin`）：
  - 前端：`/dns-admin/`
  - API：`/dns-admin/api/*`
  - 健康检查：`/dns-admin/healthz`

- SPA fallback：
  - 非 API 路由（如 `/zones`、`/routing`）会回退到 `index.html`，用于前端路由刷新。

### 5) 目录结构（运行时）

```text
{corednsdir}/
├── Corefile
├── zones/
│   └── db.<zone>
└── data/
    └── manager.db
```

## 构建（go:embed）

推荐使用构建脚本：

- Linux：`./build.sh`
- Windows：`build.bat`

脚本会执行：
1. 构建前端（`web/dist`）；
2. 同步产物到 `internal/webui/dist`（Go embed 目录）；
3. 构建后端二进制。

若缺少 `web/` 或 `dist/index.html`，脚本会直接失败并提示。

## 服务安装与管理（Linux systemd）

### 1) 构建并部署二进制

在开发机上构建：

```bash
# Linux 构建（交叉编译）
./build.sh

# 或在 Linux 服务器上直接构建
go build -ldflags "-s -w" -o coredns-manager .
```

将二进制上传到服务器：

```bash
scp coredns-manager root@server:/usr/local/bin/
ssh root@server chmod +x /usr/local/bin/coredns-manager
```

### 2) 安装 systemd 服务

项目提供了 [deploy/coredns-manager.service](deploy/coredns-manager.service)，可直接使用：

```bash
# 复制 service 文件到 systemd 目录
cp deploy/coredns-manager.service /etc/systemd/system/

# 根据实际环境修改配置（重要！）
vim /etc/systemd/system/coredns-manager.service
```

需要修改的关键字段：

| 字段 | 说明 | 示例 |
|------|------|------|
| `ExecStart` | 启动命令及参数 | `-addr=127.0.0.1:8089 -corednsdir=/etc/coredns` |
| `-adguard-url` | AdGuard Home API 地址 | `-adguard-url=https://adguard.example.com` |
| `-adguard-user` | AdGuard Home 用户名 | `-adguard-user=admin` |
| `-adguard-pass` | AdGuard Home 密码 | `-adguard-pass=your_password` |
| `-prefix` | 反向代理子路径（可选） | `-prefix=/dns-admin` |
| `ReadWritePaths` | 需要写入权限的路径 | `/etc/coredns` |

修改完成后重载 systemd 配置：

```bash
systemctl daemon-reload
```

### 3) 服务管理命令

```bash
# 启动服务
systemctl start coredns-manager

# 停止服务
systemctl stop coredns-manager

# 重启服务（修改配置后）
systemctl restart coredns-manager

# 设置开机自启
systemctl enable coredns-manager

# 取消开机自启
systemctl disable coredns-manager

# 查看服务状态
systemctl status coredns-manager

# 查看实时日志
journalctl -u coredns-manager -f

# 查看最近 100 条日志
journalctl -u coredns-manager -n 100

# 查看今天的服务日志
journalctl -u coredns-manager --since today
```

### 4) 服务更新

构建新版本后，替换二进制即可：

```bash
# 上传新二进制
scp coredns-manager root@server:/usr/local/bin/

# 重启服务
systemctl restart coredns-manager

# 验证启动正常
systemctl status coredns-manager
```

### 5) 服务故障排查

```bash
# 检查服务是否运行
systemctl is-active coredns-manager

# 检查服务是否开机自启
systemctl is-enabled coredns-manager

# 查看启动失败的详细原因
systemctl status coredns-manager --no-pager -l

# 查看完整日志（含错误堆栈）
journalctl -u coredns-manager --since "1 hour ago" --no-pager

# 测试二进制能否正常运行（不通过 systemd）
/usr/local/bin/coredns-manager -addr=:8080 -corednsdir=/etc/coredns
```

## 服务安装与管理（Windows）

### 1) 构建

```cmd
build.bat
```

生成 `coredns-manager.exe`。

### 2) 直接运行

```cmd
coredns-manager.exe -addr=:8080 -corednsdir=C:\coredns
```

### 3) 注册为 Windows 服务（推荐使用 NSSM）

[NSSM](https://nssm.cc/) 是一个轻量的 Windows 服务管理工具：

```cmd
:: 安装服务
nssm install CoreDNSManager "C:\path\to\coredns-manager.exe" -addr=:8080 -corednsdir=C:\coredns

:: 启动服务
nssm start CoreDNSManager

:: 停止服务
nssm stop CoreDNSManager

:: 重启服务
nssm restart CoreDNSManager

:: 编辑服务参数
nssm edit CoreDNSManager

:: 查看服务状态
nssm status CoreDNSManager

:: 卸载服务
nssm remove CoreDNSManager confirm
```

### 4) 注册为 Windows 服务（sc 命令）

如果不方便安装 NSSM，也可以使用 Windows 自带的 `sc` 命令：

```cmd
:: 创建服务
sc create CoreDNSManager binPath= "C:\path\to\coredns-manager.exe -addr=:8080 -corednsdir=C:\coredns" start= auto DisplayName= "CoreDNS Manager"

:: 启动服务
sc start CoreDNSManager

:: 停止服务
sc stop CoreDNSManager

:: 查询状态
sc query CoreDNSManager

:: 删除服务
sc delete CoreDNSManager
```

> **注意**：使用 `sc` 创建的服务无法设置环境变量、日志重定向等高级选项，推荐使用 NSSM。

## API 概览

统一响应结构：

```json
{"ok": true, "data": {}, "error": ""}
```

### 仪表盘
- `GET /api/dashboard/metrics`
- `GET /api/dashboard/recent-logs`

### Zones
- `GET /api/zones`
- `POST /api/zones`
- `GET /api/zones/{id}`
- `PUT /api/zones/{id}`
- `DELETE /api/zones/{id}`
- `POST /api/zones/{id}/export`
- `POST /api/zones/import`

### Records
- `GET /api/zones/{zoneId}/records`
- `POST /api/zones/{zoneId}/records`
- `GET /api/zones/{zoneId}/records/{id}`
- `PUT /api/zones/{zoneId}/records/{id}`
- `DELETE /api/zones/{zoneId}/records/{id}`
- `POST /api/zones/{zoneId}/records/batch-delete`
- `POST /api/zones/{zoneId}/records/batch-enable`
- `POST /api/zones/{zoneId}/records/reorder`

### 路由规则
- `GET /api/routes`
- `POST /api/routes`
- `PUT /api/routes/{id}`
- `DELETE /api/routes/{id}`
- `POST /api/routes/{id}/toggle`
- `POST /api/routes/reorder`
- `POST /api/routes/sync-adguard`

### 健康检查
- `GET /api/health/services`
- `POST /api/health/services`
- `PUT /api/health/services/{id}`
- `DELETE /api/health/services/{id}`
- `GET /api/health/services/{id}/results`
- `POST /api/health/services/{id}/check-now`

### AdGuard
- `GET /api/adguard/status`
- `GET /api/adguard/stats`
- `GET /api/adguard/config`
- `PUT /api/adguard/config`

### Corefile
- `GET /api/corefile`
- `PUT /api/corefile`
- `GET /api/corefile/history`
- `POST /api/corefile/restore`

### 系统
- `GET /api/settings`
- `GET /api/logs`
- `GET /api/sync/status`
- `POST /api/sync/trigger`
- `POST /api/coredns/reload`

## 部署建议

### systemd

可使用 [deploy/coredns-manager.service](deploy/coredns-manager.service) 部署。

### Nginx 反向代理

可参考 [deploy/nginx.conf](deploy/nginx.conf)。
建议至少启用：
- Basic Auth 或上游 SSO
- HTTPS
- 仅内网访问管理面

> 使用子路径部署时（例如 `/dns-admin/`），请保证启动参数 `-prefix` 与 Nginx 路径一致。

## 安全与权限

- 进程需具备 `corednsdir` 读写权限。
- 触发 CoreDNS reload 需具备对应系统权限。
- AdGuard 账号密码属于敏感配置，避免在日志输出明文。

## 开发说明

- 后端开发优先：先保证 API/service/store 主链路完整。
- 新增业务请遵循分层，不要跨层直接访问数据库或拼配置文件。
- 各后端子目录详细说明见：
  - [internal/README.md](internal/README.md)
  - [internal/api/README.md](internal/api/README.md)
  - [internal/app/README.md](internal/app/README.md)
  - [internal/service/README.md](internal/service/README.md)
  - [internal/store/README.md](internal/store/README.md)
  - [internal/domain/README.md](internal/domain/README.md)
  - [internal/zonefile/README.md](internal/zonefile/README.md)
  - [internal/adguard/README.md](internal/adguard/README.md)
  - [internal/testutil/README.md](internal/testutil/README.md)