# ddns

**Repository Path**: yun81911_admin/ddns

## Basic Information

- **Project Name**: ddns
- **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-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DDNS（ddns-go）

基于 [`jeessy/ddns-go`](https://hub.docker.com/r/jeessy/ddns-go) 的 Docker Compose 部署；默认镜像已推送至华为云 SWR：

`swr.cn-north-4.myhuaweicloud.com/hzsb/ddns-go:latest`

支持主流 DNS 服务商（镜像内置），本仓库首批文档覆盖：**Cloudflare、DNSPod、阿里云、腾讯云**。

## 前置依赖

- 已安装 [Docker](https://docs.docker.com/get-docker/) 与 Compose V2（`docker compose`）
- Docker 守护进程处于运行状态（Windows 请先启动 Docker Desktop）

若 Docker 未运行，`docker compose up` 会失败，属预期行为。

## 快速开始

```bash
# 1. 进入项目目录
cd /path/to/ddns

# 2.（可选）复制环境变量
cp .env.example .env

# 3. 启动
docker compose up -d

# 4. 打开管理界面（默认端口 9876）
# http://<主机IP>:9876
```

首次访问请按 **ddns-go 自带流程** 设置登录账号与密码，并配置 DNS。本项目**不额外提供**登录组件或账号环境变量。

### 常用命令

| 操作 | 命令 |
|------|------|
| 查看日志 | `docker compose logs -f ddns-go` |
| 停止 | `docker compose stop` |
| 启动 | `docker compose start` |
| 销毁容器（保留配置） | `docker compose down` |

配置与登录信息保存在 `./data`（映射到容器 `/root`，配置文件为隐藏文件 `.ddns_go_config.yaml`）。

## 忘记 Web 密码

使用官方重置方式（将 `新密码` 换成你的密码）：

```bash
docker exec ddns-go ./ddns-go -resetPassword 新密码
docker compose restart
```

然后用新密码登录管理界面。

## DNS 服务商配置要点

在 Web 界面选择服务商并填写凭证。**凭证不要写入 `.env` 或提交到 Git。**

| 服务商 | 典型凭证 | 配置提示 |
|--------|----------|----------|
| Cloudflare | API Token，或 Global API Key + Email | Token 建议仅授予目标 Zone 的 DNS Edit |
| DNSPod | ID + Token | 与腾讯云 DNSPod 控制台凭证一致 |
| 阿里云 | AccessKey ID + Secret | 建议使用仅 DNS 权限的 RAM 子账号 |
| 腾讯云 | SecretId + SecretKey | 按界面「腾讯云」选项填写；与 DNSPod 产品线相关时注意选对类型 |

保存后，ddns-go 会周期性探测公网 IP，并在与 DNS 记录不一致时更新。失败原因可在 Web 界面或容器日志中查看。

镜像还支持其他服务商时，可直接在 UI 中配置；本仓库不对其做专项验收。

## IPv4 / IPv6

- 在 Web 中按域名分别启用 IPv4（A）和/或 IPv6（AAAA）
- 仅有公网 IPv4 时，只启用 IPv4 即可
- 使用 IPv6 时，宿主机需具备可达的公网 IPv6；Windows / macOS 上默认 bridge 网络若探测不准，可在 Linux 主机尝试 host 网络（见下方可选配置）

## 安全建议

- 管理端口默认 `9876`，建议仅本机或内网访问，勿对公网裸奔
- `./data` 与 `.env` 已在 `.gitignore` 中忽略，请勿强制添加密钥文件
- 定期备份 `./data` 目录以便迁移或重建

## 环境变量

复制 `.env.example` 为 `.env` 后可修改：

| 变量 | 默认 | 说明 |
|------|------|------|
| `DDNS_WEB_PORT` | `9876` | 宿主机 Web 端口 |
| `DDNS_IMAGE` | `swr.cn-north-4.myhuaweicloud.com/hzsb/ddns-go` | 镜像名；可改回 `jeessy/ddns-go` |
| `DDNS_IMAGE_TAG` | `latest` | 建议改为固定小版本以便复现 |

## 升级与备份

```bash
# 备份配置
cp -r data data-backup-$(date +%Y%m%d)

# 拉取新镜像并重建容器（保留 ./data）
docker compose pull
docker compose up -d
```

## 可选：Linux host 网络

若需更好的本机 IP / IPv6 探测，可在 **Linux** 上将 `compose.override.example.yml` 复制为 `compose.override.yml` 后重启。

**注意：** Windows Docker Desktop / 多数 macOS 场景不适用 `network_mode: host`。

## 常见问题

| 现象 | 处理 |
|------|------|
| `failed to connect to the docker API` | 先启动 Docker Desktop 或 dockerd |
| 端口被占用 | 修改 `.env` 中 `DDNS_WEB_PORT` |
| 容器重建后配置丢失 | 确认 `./data` 卷挂载存在且未被删除 |
| 无法登录 | 使用上文「忘记 Web 密码」重置；勿删除 `./data`  unless 要彻底清空 |
| 镜像拉取失败 | 先 `docker login swr.cn-north-4.myhuaweicloud.com`，再 `docker compose pull`；或改回官方 `jeessy/ddns-go` |

## 规格文档

结构化需求与设计见 [`.kiro/specs/docker-ddns/`](.kiro/specs/docker-ddns/)。