mirror of
https://github.com/NewFuture/DDNS.git
synced 2026-10-20 08:17:43 +00:00
New Futureandopenhands
e9ad33e88b
* feat(rust): add Web dashboard and MCP services Share configuration, status and synchronization between Web and MCP; add authenticated HTTP, stdio lifecycle support, in-process scheduling and offline regression tests. Exercise native tests on the existing Windows/macOS/Linux CI matrix. Co-authored-by: openhands <openhands@all-hands.dev> * ci(rust): allow manual cross-platform validation Enable workflow_dispatch for feature-branch CI without requiring PR creation. Preserve matrices, permissions, publishing boundaries and trusted-branch cache policy. Co-authored-by: openhands <openhands@all-hands.dev> * ci(rust): validate feature branch pushes Run the existing Rust cross-platform matrix for feat/** pushes while retaining trusted-branch-only cache writes and unchanged release triggers. Co-authored-by: openhands <openhands@all-hands.dev> * ci(rust): remove temporary branch trigger The v5 pull request now exists and runs the complete native matrix, so restore the original trusted push branches while retaining Web/MCP paths and tests. Co-authored-by: openhands <openhands@all-hands.dev> --------- Co-authored-by: openhands <openhands@all-hands.dev>
429 lines
12 KiB
Markdown
429 lines
12 KiB
Markdown
# DDNS Docker
|
||
|
||
- 基本特性
|
||
- 基于 Alpine Linux，最终编译后的镜像体积小（< 7MB）
|
||
- 支持多种硬件架构（amd64、arm64、arm/v7、arm/v6、ppc64le、s390x、386、mips64le）
|
||
- 内置定时任务，默认每 5 分钟自动更新一次
|
||
- 无需外部依赖，开箱即用, 性能优化，资源占用低
|
||
- 配置方式:
|
||
- [CLI 命令行参数](config/cli.md)
|
||
- [JSON 配置文件](config/json.md)
|
||
- [Env 环境变量](config/env.md)
|
||
|
||
## 镜像说明
|
||
|
||
### Rust V5 开发镜像
|
||
|
||
稳定默认镜像仍是 `newfuture/ddns` / `ghcr.io/newfuture/ddns`，不会被 Rust
|
||
镜像替换。Rust V5 在 `v5` 分支开发，目前只构建 Linux amd64/arm64
|
||
OCI 工件，不推送公共镜像。它直接运行 `ddns-rs`，不包含 Python 镜像的 cron
|
||
入口；默认单次同步，`web` 模式提供进程内定时同步。可从分支源码本地构建：
|
||
|
||
```bash
|
||
docker build -f docker/rust.Dockerfile -t ddns-rs:v5-dev .
|
||
docker run --rm ddns-rs:v5-dev --help
|
||
```
|
||
|
||
V5 尚未发布，暂不提供公共 `latest` / `next` Rust 镜像入口。
|
||
|
||
Web 示例（先准备含 `config.json` 的本地 `config/` 目录，并在 shell 中设置私密的
|
||
`DDNS_HTTP_TOKEN`）：
|
||
|
||
```bash
|
||
docker run --rm -p 127.0.0.1:8000:8000 \
|
||
-v "$PWD/config:/ddns" ddns-rs:v5-dev \
|
||
web -c /ddns/config.json --host 0.0.0.0 --port 8000 \
|
||
--http-token "$DDNS_HTTP_TOKEN" --http-origin http://127.0.0.1:8000 --interval 5
|
||
```
|
||
|
||
容器内的非回环监听也必须设置 token；仅将发布端口绑定主机回环地址，客户端使用
|
||
Bearer token 鉴权。若需远程访问，应使用可信 TLS 反向代理或隧道，并按需重复
|
||
`--http-origin ORIGIN`。控制台与 `/mcp` 共用监听器和服务；独立 MCP HTTP 可改用
|
||
`mcp -c /ddns/config.json --transport http` 并保留相同监听/鉴权选项。
|
||
stdio MCP 使用 `docker run --rm -i`（不要分配 TTY），挂载配置后运行 `mcp -c /ddns/config.json`。
|
||
|
||
Web/MCP 仅接受单个本地配置。保存及备份/恢复需要容器非 root 用户 `ddns` 对挂载目录
|
||
有写权限；请按部署环境配置权限，不要将其设为全局可写。配置 API 会返回完整配置，
|
||
包括凭据；配置、备份和监听 token 都应保密。镜像只内嵌明确列出的公共 Web 资源与
|
||
字段模型，不复制用户配置。构建必须从仓库根目录提供上下文。
|
||
监听 token 授予敏感配置访问与 DNS 更新权限。Web 同步会以容器用户身份执行
|
||
本地配置中的 `cmd:`/`shell:` 规则，只应向可信管理员授予访问权限。
|
||
|
||
进程内调度间隔为 1..1440 分钟；退出容器即停止。尚未实现 `task` 或系统任务
|
||
检测/接管，启用前必须手动停用旧 Python/主机任务。兼容限制和详细选项见
|
||
[Rust V5 开发文档](dev/rust.md)。以下镜像版本和默认 cron 行为仅适用于稳定 Python 镜像。
|
||
|
||
### 镜像版本
|
||
|
||
DDNS 镜像版本(Docker Tag)：
|
||
|
||
- `latest`: 最新稳定版
|
||
- `next`: 下一个版本
|
||
- `edge` 最新开发版,不稳定
|
||
|
||
```bash
|
||
docker pull newfuture/ddns:latest
|
||
docker pull newfuture/ddns:next
|
||
```
|
||
|
||
您也可以指定特定版本，例如：
|
||
|
||
```bash
|
||
docker pull newfuture/ddns:v4.0.0
|
||
```
|
||
|
||
### 镜像源
|
||
|
||
镜像会同步发布到以下源：
|
||
|
||
- [Docker Hub](https://hub.docker.com/r/newfuture/ddns): `docker.io/newfuture/ddns`
|
||
- [GitHub Packages](https://github.com/newfuture/DDNS/pkgs/container/ddns): `ghcr.io/newfuture/ddns`
|
||
|
||
支持 `docker pull ghcr.io/newfuture/ddns`
|
||
|
||
## 运行方式 docker run
|
||
|
||
DDNS Docker 镜像支持三种配置方式：命令行，环境变量和配置文件。
|
||
|
||
- 当设置了命令行参数时，容器将**直接运行单次执行 DDNS 程序，而不会启用定时任务**。
|
||
- 如果您需要定时任务，请使用环境变量或配置文件方式。
|
||
|
||
**注意**:
|
||
|
||
- 使用了 `-v` 挂载配置文件或目录，确保容器内的 `/ddns/` 目录包含有效的配置文件（如 `config.json`），否则 DDNS 将无法正常工作。
|
||
- 使用了 `--network host`，请确保您的 Docker 守护进程已正确配置以支持此模式。
|
||
- 使用 `-d` 参数可以让容器在后台运行, 使用前请确保您了解 Docker 的基本操作。
|
||
- 使用 `-e DDNS_XXX=YYY` 参数可以设置环境变量，容器内的 DDNS 程序会自动读取这些变量。
|
||
|
||
### 使用命令行参数 CLI
|
||
|
||
可以参考[命令行参数说明](config/cli.md)获取详细的参数列表。
|
||
此时 `docker run -v /local/config/:/ddns/ --name=ddns --network=host newfuture/ddns` 就相当于 `ddns` 命令行，不会执行定时任务。
|
||
|
||
此方式适合需要一次性运行或调试的场景, 参数与 DDNS 命令行参数一致。
|
||
|
||
```bash
|
||
# 查看ddns命令行参数 等价于 ddns -h
|
||
docker run --rm newfuture/ddns -h
|
||
# 加上ddns的 --debug 参数可以启用调试模式（或者 --log.level=debug）
|
||
docker run --rm --network=host newfuture/ddns --debug --dns=dnspod --id=12345 --token=mytokenkey --ipv4=www.example.com --ipv4=ipv4.example.com --index4 public
|
||
# 容器内调试
|
||
docker run -it newfuture/ddns sh
|
||
```
|
||
|
||
### 使用配置文件 JSON
|
||
|
||
Docker 容器内的工作目录是 `/ddns/`，默认配置文件会被映射到容器内的 `/ddns/config.json`。
|
||
|
||
```bash
|
||
docker run -d -v /host/config/:/ddns/ newfuture/ddns
|
||
```
|
||
|
||
其中 `/host/config/` 是您本地包含 `config.json` 的目录。
|
||
详见 `config.json` 的内容可以参考 [JSON 配置文件说明](config/json.md)。
|
||
|
||
### 使用环境变量 ENV
|
||
|
||
环境变量和命令行参数类似, 加上 DDNS 前缀，推荐全大写。数组类型需要使用 JSON 格式或者单引号包裹。
|
||
|
||
当然也可以使用 `--env-file` 参数来加载环境变量文件。
|
||
|
||
```bash
|
||
docker run -d \
|
||
-e DDNS_DNS=dnspod \
|
||
-e DDNS_ID=12345 \
|
||
-e DDNS_TOKEN=mytokenkey \
|
||
-e DDNS_IPV4='["example.com","www.example.com"]' \
|
||
-e DDNS_INDEX4='["public",0]' \
|
||
--network host \
|
||
--name ddns \
|
||
newfuture/ddns
|
||
```
|
||
|
||
想要了解所有支持的环境变量，请参考[环境变量配置说明](config/env.md)。
|
||
|
||
## 网络模式
|
||
|
||
### host 网络模式
|
||
|
||
使用 `--network host` 可让容器直接使用宿主机的网络，这样 DDNS 可以正确获取宿主机的 IP 地址。
|
||
|
||
对于 Public 或者 url 通常不需要设置 host。
|
||
|
||
```bash
|
||
docker run -d \
|
||
-e DDNS_DNS=dnspod \
|
||
-e DDNS_ID=12345 \
|
||
-e DDNS_TOKEN=mytokenkey \
|
||
-e DDNS_IPV4=example.com \
|
||
--network host \
|
||
newfuture/ddns
|
||
```
|
||
|
||
### bridge 网络模式（默认）
|
||
|
||
如果您不想使用 host 网络模式，也可以使用默认的 bridge 模式，但需要注意此时容器具有自己的 IP，您需要使用 `public` 模式获取公网 IP：
|
||
|
||
```bash
|
||
docker run -d \
|
||
-e DDNS_DNS=dnspod \
|
||
-e DDNS_ID=12345 \
|
||
-e DDNS_TOKEN=mytokenkey \
|
||
-e DDNS_IPV4=example.com \
|
||
-e DDNS_INDEX4=public \
|
||
newfuture/ddns
|
||
```
|
||
|
||
## 高级配置
|
||
|
||
### 自定义定时任务周期
|
||
|
||
默认情况下，DDNS 容器会每 5 分钟自动更新一次 DNS 记录。您可以通过 `DDNS_CRON` 环境变量自定义定时任务的执行周期。
|
||
|
||
`DDNS_CRON` 环境变量使用标准的 cron 表达式格式：`分钟 小时 日 月 星期`
|
||
|
||
**示例**：
|
||
|
||
```bash
|
||
# 每 10 分钟执行一次
|
||
docker run -d \
|
||
-e DDNS_CRON="*/10 * * * *" \
|
||
-e DDNS_DNS=dnspod \
|
||
-e DDNS_ID=12345 \
|
||
-e DDNS_TOKEN=mytokenkey \
|
||
-e DDNS_IPV4=example.com \
|
||
--network host \
|
||
newfuture/ddns
|
||
|
||
# 每小时执行一次
|
||
docker run -d \
|
||
-e DDNS_CRON="0 * * * *" \
|
||
-e DDNS_DNS=dnspod \
|
||
-e DDNS_ID=12345 \
|
||
-e DDNS_TOKEN=mytokenkey \
|
||
-e DDNS_IPV4=example.com \
|
||
--network host \
|
||
newfuture/ddns
|
||
|
||
# 每天凌晨 2 点执行一次
|
||
docker run -d \
|
||
-e DDNS_CRON="0 2 * * *" \
|
||
-e DDNS_DNS=dnspod \
|
||
-e DDNS_ID=12345 \
|
||
-e DDNS_TOKEN=mytokenkey \
|
||
-e DDNS_IPV4=example.com \
|
||
--network host \
|
||
newfuture/ddns
|
||
|
||
# 每 30 秒执行一次（使用两个 cron 任务）
|
||
# 注意：cron 最小单位是分钟，如需更频繁的更新，可以使用多个任务
|
||
docker run -d \
|
||
-e DDNS_CRON="* * * * *" \
|
||
-e DDNS_DNS=dnspod \
|
||
-e DDNS_ID=12345 \
|
||
-e DDNS_TOKEN=mytokenkey \
|
||
-e DDNS_IPV4=example.com \
|
||
--network host \
|
||
newfuture/ddns
|
||
```
|
||
|
||
**Cron 表达式说明**：
|
||
|
||
| 字段 | 允许值 | 允许的特殊字符 |
|
||
|------|--------|----------------|
|
||
| 分钟 | 0-59 | * , - / |
|
||
| 小时 | 0-23 | * , - / |
|
||
| 日 | 1-31 | * , - / |
|
||
| 月 | 1-12 | * , - / |
|
||
| 星期 | 0-7 | * , - / |
|
||
|
||
**常用表达式示例**：
|
||
|
||
- `*/5 * * * *` - 每 5 分钟（默认值）
|
||
- `*/10 * * * *` - 每 10 分钟
|
||
- `*/15 * * * *` - 每 15 分钟
|
||
- `0 * * * *` - 每小时
|
||
- `0 */2 * * *` - 每 2 小时
|
||
- `0 0 * * *` - 每天午夜
|
||
- `0 2 * * *` - 每天凌晨 2 点
|
||
- `0 0 * * 0` - 每周日午夜
|
||
|
||
**Docker Compose 示例**：
|
||
|
||
```yaml
|
||
version: "3"
|
||
services:
|
||
ddns:
|
||
image: newfuture/ddns:latest
|
||
restart: always
|
||
network_mode: host
|
||
environment:
|
||
- DDNS_CRON=*/10 * * * * # 每 10 分钟执行一次
|
||
- DDNS_DNS=dnspod
|
||
- DDNS_ID=12345
|
||
- DDNS_TOKEN=mytokenkey
|
||
- DDNS_IPV4=example.com
|
||
```
|
||
|
||
### 多域名配置
|
||
|
||
环境变量方式配置多域名：
|
||
|
||
```bash
|
||
docker run -d \
|
||
-e DDNS_DNS=dnspod \
|
||
-e DDNS_ID=12345 \
|
||
-e DDNS_TOKEN=mytokenkey \
|
||
-e DDNS_IPV4='["example.com", "www.example.com", "sub.example.com"]' \
|
||
--network host \
|
||
newfuture/ddns
|
||
```
|
||
|
||
命令行参数方式配置多域名：
|
||
|
||
```bash
|
||
docker run --rm --network host newfuture/ddns \
|
||
--dns dnspod \
|
||
--id 12345 \
|
||
--token mytokenkey \
|
||
--ipv4 ipv4.example.com \
|
||
--ipv4 www.example.com
|
||
```
|
||
|
||
### 启用 IPv6 支持
|
||
|
||
要在 Docker 容器中使用 IPv6，需要确保 Docker 守护程序配置了 IPv6 支持：
|
||
|
||
1. 编辑 `/etc/docker/daemon.json`：
|
||
|
||
```json
|
||
{
|
||
"ipv6": true,
|
||
"fixed-cidr-v6": "fd00::/80"
|
||
}
|
||
```
|
||
|
||
2. 重启 Docker 服务：
|
||
|
||
```bash
|
||
sudo systemctl restart docker
|
||
```
|
||
|
||
3. 启动容器时启用 IPv6：
|
||
|
||
```bash
|
||
docker run -d \
|
||
--network host \
|
||
-e DDNS_DNS=dnspod \
|
||
-e DDNS_ID=12345 \
|
||
-e DDNS_TOKEN=mytokenkey \
|
||
-e DDNS_IPV6=example.com \
|
||
newfuture/ddns
|
||
```
|
||
|
||
## Docker Compose 示例
|
||
|
||
创建 `docker-compose.yml` 文件：
|
||
|
||
### 基本环境变量配置
|
||
|
||
```yaml
|
||
version: "3"
|
||
services:
|
||
ddns:
|
||
image: newfuture/ddns:latest
|
||
restart: always
|
||
network_mode: host
|
||
environment:
|
||
- DDNS_DNS=dnspod
|
||
- DDNS_ID=12345
|
||
- DDNS_TOKEN=mytokenkey
|
||
- DDNS_IPV4=example.com,www.example.com
|
||
- DDNS_INDEX4=['public','url:http://api.ipify.org']
|
||
- DDNS_LOG_LEVEL=WARNING
|
||
```
|
||
|
||
### 使用配置文件
|
||
|
||
```yaml
|
||
version: "3"
|
||
services:
|
||
ddns:
|
||
image: newfuture/ddns:latest
|
||
restart: always
|
||
network_mode: host
|
||
volumes:
|
||
- ./config:/ddns
|
||
```
|
||
|
||
运行 Docker Compose：
|
||
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
## 使用自定义镜像
|
||
|
||
如果您需要在容器中添加其他工具或自定义环境，可以基于官方镜像创建自己的 Dockerfile：
|
||
|
||
```dockerfile
|
||
FROM newfuture/ddns:latest
|
||
|
||
# 安装额外的工具
|
||
RUN apk add --no-cache curl
|
||
|
||
# 添加自定义脚本
|
||
COPY custom-script.sh /bin/
|
||
RUN chmod +x /bin/custom-script.sh
|
||
|
||
# 覆盖默认入口点（可选）
|
||
# ENTRYPOINT ["/bin/custom-script.sh"]
|
||
```
|
||
|
||
## 排障和常见问题
|
||
|
||
### 容器无法获取正确的 IP 地址
|
||
|
||
**问题**: DDNS 无法正确获取主机 IP
|
||
|
||
**解决方案**:
|
||
|
||
1. 使用 `--network host` 网络模式
|
||
2. 或者设置 `-e DDNS_INDEX4=public` 强制使用公网 API 获取 IP
|
||
|
||
### 未收到定时任务更新
|
||
|
||
**问题**: 容器运行但不自动更新 DNS
|
||
|
||
**解决方案**:
|
||
|
||
1. 检查容器日志 `docker logs ddns`
|
||
2. 确认容器没有被暂停 `docker ps -a`
|
||
3. 尝试手动执行更新 `docker exec ddns /bin/ddns`
|
||
|
||
### 首次运行后立即退出
|
||
|
||
**问题**: 容器启动后立即退出
|
||
|
||
**解决方案**:
|
||
|
||
1. 添加 `-it` 参数以交互方式运行查看问题 `docker run -it --rm newfuture/ddns`
|
||
2. 检查环境变量或配置文件是否正确设置
|
||
|
||
### 网络连接问题
|
||
|
||
**问题**: 容器无法连接到 DNS 服务商 API
|
||
|
||
**解决方案**:
|
||
|
||
1. 检查网络连接 `docker exec ddns ping api.dnspod.cn`
|
||
2. 配置 HTTP 代理 `-e DDNS_PROXY=http://proxy:port`
|
||
|
||
## 更多资源
|
||
|
||
- [DDNS GitHub 主页](https://github.com/NewFuture/DDNS)
|
||
- [Docker Hub - newfuture/ddns](https://hub.docker.com/r/newfuture/ddns)
|
||
- [环境变量配置详情](config/env.md)
|
||
- [JSON 配置文件详情](config/json.md)
|
||
- [命令行参数详情](config/cli.md)
|