yuzu/Cloudflare-DDNS-Updater
1
0
Fork 0
mirror of https://github.com/YuzuZensai/Cloudflare-DDNS-Updater.git synced 2026-07-15 14:26:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 docs: rewrite README

Browse Source
This commit is contained in:
Yuzu
2026-07-01 13:27:50 +07:00
parent 389656f763
commit 7531fece83
1 changed files with 31 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+31 -110
View File
@@ -1,6 +1,6 @@
# Cloudflare DDNS Updater
Cloudflare DDNS Updater keeps Cloudflare DNS records pointed at the machine's current public IPv4 and/or IPv6 address.
Keeps Cloudflare DNS records pointed at the machine's current public IPv4 and/or IPv6 address.
The container reads:
@@ -15,14 +15,12 @@ Pull the published image:
docker pull ghcr.io/yuzuzensai/cloudflare-ddns-updater:latest
```
Create `.env` from the example:
Create `.env` from the example and set your Cloudflare API token:
```sh
cp .env.example .env
```
Edit `.env` and set your Cloudflare API token:
```env
NODE_ENV=production
EXAMPLE_SITE_TOKEN=replace-with-cloudflare-api-token
@@ -88,8 +86,6 @@ services:
- ./configs:/home/node/app/configs
```
Start it with:
```sh
docker compose up -d
```
@@ -98,127 +94,52 @@ docker compose up -d
`configs/UpdaterConfig.json` is an array of Cloudflare account/token configurations.
Each top-level object uses these fields:
Each top-level object:
- `token`: Cloudflare API token, or an environment reference like `{ENV_TOKEN:EXAMPLE_SITE_TOKEN}`.
- `updateInterval`: update interval in seconds.
- `zone`: DNS records to manage.
| Field | Description |
| ---------------- | --------------------------------------------------------------------------------------- |
| `token` | Cloudflare API token, or an environment reference like `{ENV_TOKEN:EXAMPLE_SITE_TOKEN}` |
| `updateInterval` | Update interval in seconds |
| `zone` | DNS records to manage |
Each `zone` entry uses these fields:
Each `zone` entry:
- `id`: Cloudflare zone ID.
- `type`: DNS record type, usually `A` or `AAAA`.
- `name`: DNS record name, for example `example.com` or `home.example.com`.
- `content`: `{CURRENT_IPv4}` for an `A` record or `{CURRENT_IPv6}` for an `AAAA` record.
- `ttl`: Cloudflare TTL. Use `1` for automatic TTL.
- `proxied`: Cloudflare proxy status, `true` or `false`.
| Field | Description |
| --------- | ------------------------------------------------------------------------- |
| `id` | Cloudflare zone ID |
| `type` | DNS record type, usually `A` or `AAAA` |
| `name` | DNS record name, e.g. `example.com` or `home.example.com` |
| `content` | `{CURRENT_IPv4}` for an `A` record, `{CURRENT_IPv6}` for an `AAAA` record |
| `ttl` | Cloudflare TTL. Use `1` for automatic |
| `proxied` | Cloudflare proxy status, `true` or `false` |
Important: keep the JSON property order shown in the examples. The current config validator expects exact key order.
## Cloudflare Zone ID and API Token
## Cloudflare Zone ID And Token
**Zone ID** — In the [Cloudflare dashboard](https://dash.cloudflare.com/), select the domain, open its overview page, and copy `Zone ID` from the `API` section of the right sidebar into `zone[].id`.
You need two Cloudflare values before running the updater:
**API token** — In the dashboard, go to your profile icon → `My Profile` → `API Tokens` → `Create Token`. Use the built-in `Edit zone DNS` template (recommended) or a custom token with `Zone > DNS > Edit` and `Zone > Zone > Read` permissions. Either way, scope `Zone Resources` to `Include` → `Specific zone` → your domain, then create and copy the token — Cloudflare only shows it once. Don't use your Global API Key; the updater only needs a scoped token for the zones it manages.
- Zone ID: identifies the Cloudflare zone/domain that contains the DNS records.
- API token: authorizes the updater to read and edit DNS records in that zone.
The Zone ID goes in `configs/UpdaterConfig.json` as `zone[].id`.
The API token should go in `.env`, then `configs/UpdaterConfig.json` references it with `{ENV_TOKEN:VARIABLE_NAME}`. The variable name is up to you. `EXAMPLE_SITE_TOKEN`, `HOME_SITE_TOKEN`, `MY_DOMAIN_TOKEN`, or any other valid environment variable name will work as long as both files use the same name.
### Get Your Zone ID
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/).
2. Select the domain you want to update.
3. Open the domain overview page.
4. Find `Zone ID` in the right sidebar under `API`.
5. Copy that value into each matching `zone[].id` field in `configs/UpdaterConfig.json`.
Example:
```json
{
"id": "023e105f4ecef8ad9ca31a8372d0c353",
"type": "A",
"name": "home.example.com",
"content": "{CURRENT_IPv4}",
"ttl": 1,
"proxied": false
}
```
### Create an API Token
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/).
2. Click your profile icon in the top-right corner.
3. Open `My Profile`.
4. Open `API Tokens`.
5. Select `Create Token`.
The easiest option is the built-in template:
1. Find the `Edit zone DNS` template.
2. Select `Use template`.
3. Under `Zone Resources`, select `Include` > `Specific zone` > your domain.
4. Leave the permissions as DNS edit/read permissions.
5. Select `Continue to summary`.
6. Review the token summary.
7. Select `Create Token`.
8. Copy the token immediately. Cloudflare only shows it once.
If you create a custom token instead, use this setup:
1. Select `Create Custom Token`.
2. Give it a clear name, for example `Cloudflare DDNS Updater`.
3. Add these permissions:
- `Zone` > `DNS` > `Edit`
- `Zone` > `Zone` > `Read`
Set the zone resource scope:
1. Under `Zone Resources`, choose `Include`.
2. Choose `Specific zone`.
3. Select the domain this updater will manage.
4. Select `Continue to summary`.
5. Review the token summary.
6. Select `Create Token`.
7. Copy the token immediately. Cloudflare only shows it once.
Do not use your Global API Key. This app only needs a scoped API token with DNS access for the selected zone.
After creating the token, copy it into `.env`. The name before `=` is the environment variable name. You can change it.
Put the token in `.env` under any variable name you like, then reference that same name from `UpdaterConfig.json`:
```env
EXAMPLE_SITE_TOKEN=your-cloudflare-api-token
```
If you change the variable name in `.env`, update the `token` value in `configs/UpdaterConfig.json` to match it exactly.
Example:
```env
HOME_SITE_TOKEN=your-token
HOME_SITE_TOKEN=your-cloudflare-api-token
```
```json
"token": "{ENV_TOKEN:HOME_SITE_TOKEN}"
```
Another example with a different name:
Avoid writing the literal token directly into `UpdaterConfig.json` — `{ENV_TOKEN:...}` keeps the secret in `.env`, which is gitignored.
```env
MY_DOMAIN_TOKEN=your-token
## Development
```sh
bun install
bun run dev # run with --watch
bun run check # typecheck + format + lint + test
```
```json
"token": "{ENV_TOKEN:MY_DOMAIN_TOKEN}"
```
Do not include the literal token in `UpdaterConfig.json` unless you intentionally want the secret stored there. Using `{ENV_TOKEN:...}` keeps the token in `.env`, which is ignored by git.
## Notes
- The updater fetches IPv4 from `https://api.ipify.org?format=json`.
- The updater fetches IPv6 from `https://api64.ipify.org/?format=json`.
- If `configs/UpdaterConfig.json` is missing, the app creates one from the bundled example, but you must edit it before real use.
- IPv4 is looked up via `https://api.ipify.org?format=json`, IPv6 via `https://api64.ipify.org/?format=json`.
- If `configs/UpdaterConfig.json` is missing, the app creates one from the bundled example — edit it before real use.