Skip to content

Commit bdc9979

Browse files
NewFutureNewFuture
authored
feat(log+doc): 增加log配置，完善文档 (NewFuture#480)
* update log config * add cli 文档 * update cli config * add docker 文档
1 parent c4dc2a9 commit bdc9979

8 files changed

Lines changed: 1011 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,9 @@
1919
- [二进制文件](https://github.com/NewFuture/DDNS/releases/latest) ![cross platform](https://img.shields.io/badge/system-windows_%7C%20linux_%7C%20mac-success.svg?style=social)
2020

2121
- 配置方式:
22-
- [命令行参数](#详细配置)
23-
- [JSON 配置文件](#详细配置)
24-
- [环境变量配置](doc/env.md) 📖
22+
- [命令行参数](doc/cli.md)
23+
- [JSON 配置文件](doc/json.md)
24+
- [环境变量配置](doc/env.md)
2525

2626
- 域名支持:
2727
- 多个域名支持
@@ -114,12 +114,27 @@
114114

115115
## 详细配置
116116

117-
所有字段可通过三种方式进行配置
117+
所有字段可通过三种方式进行配置，优先级为：**命令行参数 > JSON配置文件 > 环境变量**
118118

119-
1. 命令行参数 `ddns --key=value`（`ddns -h` 查看详情），优先级最高
120-
2. JSON 配置文件（值为 null 认为是有效值，会覆盖环境变量的设置，如果没有对应的 key 则会尝试使用环境变量）
119+
1. [命令行参数](doc/cli.md) `ddns --key=value`（`ddns -h` 查看详情），优先级最高
120+
2. [JSON 配置文件](doc/json.md)（值为 null 认为是有效值，会覆盖环境变量的设置，如果没有对应的 key 则会尝试使用环境变量）
121121
3. 环境变量 DDNS_ 前缀加上 key 全大写或者全小写，点转下划线（`${ddns_id}` 或 `${DDNS_ID}`，`${DDNS_LOG_LEVEL}`）
122122

123+
### 配置优先级和字段覆盖关系
124+
125+
如果同一个配置项在多个地方设置，将按照以下优先级规则生效：
126+
127+
- **命令行参数**：优先级最高，会覆盖其他所有设置
128+
- **JSON配置文件**：介于命令行和环境变量之间，会覆盖环境变量中的设置
129+
- **环境变量**：优先级最低，当其他方式未设置时使用
130+
131+
**特殊情况**：
132+
- JSON配置中明确设为`null`的值会覆盖环境变量设置
133+
- `debug`参数只在命令行中有效，JSON配置文件中的同名设置无效
134+
- 多值参数（如`ipv4`、`ipv6`等）在命令行中使用方式为重复使用参数，如`--ipv4 domain1 --ipv4 domain2`
135+
136+
各配置方式的详细说明请查看对应文档：[命令行](doc/cli.md)、[JSON配置](doc/json.md)、[环境变量](doc/env.md)
137+
123138
> 📖 **环境变量详细配置**: 查看 [环境变量配置文档](doc/env.md) 了解所有环境变量的详细用法和示例
124139

125140
<details open>
@@ -128,6 +143,7 @@
128143
- 首次运行会自动生成一个模板配置文件
129144
- 可以使用 `-c` 使用指定的配置文件（默认读取当前目录的 config.json）
130145
- 推荐使用 vscode 等支持 JsonSchema 的编辑器编辑配置文件
146+
- 查看 [JSON配置文件详细文档](doc/json.md) 了解完整的配置选项和示例
131147

132148
```bash
133149
ddns -c path/to/config.json
@@ -148,9 +164,9 @@ python run.py -c /path/to/config.json
148164
| index6 | string\|int\|array | No | `"default"` | ipv6 获取方式 | 可设置 `网卡`、`内网`、`公网`、`正则` 等方式 |
149165
| ttl | number | No | `null` | DNS 解析 TTL 时间 | 不设置采用 DNS 默认策略 |
150166
| proxy | string\|array | No | 无 | http 代理 `;` 分割 | 多代理逐个尝试直到成功，`DIRECT` 为直连 |
151-
| ~~debug~~| bool | No | `false` | 是否开启调试 | v4 中弃用，请改用 log.level=DEBUG |
167+
| debug | bool | No | `false` | 是否开启调试 | 等同于设置 log.level=DEBUG，仅命令行参数`--debug`有效 |
152168
| cache | string\|bool | No | `true` | 是否缓存记录 | 正常情况打开避免频繁更新，默认位置为临时目录下 `ddns.cache`，也可以指定一个具体路径 |
153-
| log | {"level":string,"file":string} | No | `null` | 日志配置（可选） | 日志配置，日志级别和路径（默认命令行），例如：`{ "level": "DEBUG", "file": "dns.log" }` |
169+
| log | object | No | `null` | 日志配置（可选） | 日志配置对象，支持`level`、`file`、`format`、`datefmt`参数 |
154170

155171
#### index4 和 index6 参数说明
156172

@@ -196,7 +212,9 @@ python run.py -c /path/to/config.json
196212
"proxy": "127.0.0.1:1080;DIRECT",
197213
"log": {
198214
"level": "DEBUG",
199-
"file": "dns.log"
215+
"file": "dns.log",
216+
"format": "%(asctime)s %(levelname)s [%(module)s]: %(message)s",
217+
"datefmt": "%Y-%m-%dT%H:%M:%S"
200218
}
201219
}
202220
```

‎doc/cli.md‎

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
# DDNS 命令行参数参考
2+
3+
本文档详细说明DDNS工具的命令行参数用法。命令行参数可用于覆盖配置文件和环境变量中的设置，具有**最高优先级**。
4+
5+
## 基本用法
6+
7+
可通过`-h` 查看参数列表
8+
9+
```bash
10+
# ddns [选项]
11+
ddns -h
12+
```
13+
14+
或者使用Python源码：
15+
16+
```bash
17+
# python run.py [选项]
18+
python run.py -h
19+
```
20+
21+
## 参数列表
22+
23+
| 长参数 | 短参数 | 类型 | 描述 |
24+
| --------------- | ------ | --------------- | -------------------------------------------- |
25+
| `--help` | `-h` | 标志 | 显示帮助信息并退出 |
26+
| `--version` | `-v` | 标志 | 显示版本信息并退出 |
27+
| `--config` | `-c` | 字符串 | 指定配置文件路径 |
28+
| `--dns` | | 选择项 | DNS服务提供商 |
29+
| `--id` | | 字符串 | API 访问 ID 或授权账户 |
30+
| `--token` | | 字符串 | API 授权令牌或密钥 |
31+
| `--ipv4` | | 字符串列表 | IPv4 域名列表，多个域名重复使用参数 |
32+
| `--ipv6` | | 字符串列表 | IPv6 域名列表，多个域名重复使用参数 |
33+
| `--index4` | | 字符串/数字列表 | IPv4 地址获取方式，支持多种获取方式 |
34+
| `--index6` | | 字符串/数字列表 | IPv6 地址获取方式，支持多种获取方式 |
35+
| `--ttl` | | 整数 | DNS 解析记录的 TTL 时间（秒） |
36+
| `--proxy` | | 字符串列表 | HTTP 代理设置，支持多代理重复使用参数 |
37+
| `--cache` | | 布尔/字符串 | 是否启用缓存或自定义缓存路径 |
38+
| `--debug` | | 标志 | 开启调试模式（等同于 --log.level=DEBUG） |
39+
| `--log.file` | | 字符串 | 日志文件路径，不指定则输出到控制台 |
40+
| `--log.level` | | 字符串 | 日志级别 |
41+
| `--log.format` | | 字符串 | 日志格式字符串 |
42+
| `--log.datefmt` | | 字符串 | 日期时间格式字符串 |
43+
44+
其中`--debug`和`--help`,`--version`为命令行独有参数。
45+
46+
### 参数值示例
47+
48+
| 参数 | 可能的值 | 示例 |
49+
|--------------|----------------------------------------------|----------------------------------------|
50+
| `--dns` | dnspod, alidns, cloudflare, 等 | `--dns cloudflare` |
51+
| `--id` | API ID, 邮箱, Access Key | `--id user@example.com` |
52+
| `--token` | API Token, Secret Key | `--token abcdef123456` |
53+
| `--ipv4` | 域名 | `--ipv4 example.com --ipv4 sub.example.com` |
54+
| `--ipv6` | 域名 | `--ipv6 example.com` |
55+
| `--index4` | 数字, default, public, url:, regex:, cmd:, shell: | `--index4 public`, `--index4 "regex:192\\.168\\..*"` |
56+
| `--index6` | 数字, default, public, url:, regex:, cmd:, shell: | `--index6 0`, `--index6 public` |
57+
| `--ttl` | 秒数 | `--ttl 600` |
58+
| `--proxy` | IP:端口, DIRECT | `--proxy 127.0.0.1:1080 --proxy DIRECT` |
59+
| `--cache` | true, 文件路径 | `--cache=true`, `--cache=/path/to/cache.json` |
60+
| `--debug` | (无值) | `--debug` |
61+
| `--log.file` | 文件路径 | `--log.file=/var/log/ddns.log` |
62+
| `--log.level`| DEBUG, INFO, WARNING, ERROR, CRITICAL | `--log.level=DEBUG` |
63+
| `--log.format` | 格式字符串 | `--log.format="%(asctime)s: %(message)s"` |
64+
| `--log.datefmt` | 日期格式字符串 | `--log.datefmt="%Y-%m-%d %H:%M:%S"` |
65+
66+
## DNS服务配置参数
67+
68+
### `--dns {alidns,cloudflare,dnscom,dnspod,dnspod_com,he,huaweidns,callback}`
69+
70+
DNS服务提供商。
71+
72+
- **默认值**: `dnspod`
73+
- **可选值**:
74+
- `alidns`: 阿里云DNS
75+
- `cloudflare`: Cloudflare
76+
- `dnscom`: DNS.COM
77+
- `dnspod`: DNSPOD国内版
78+
- `dnspod_com`: DNSPOD国际版
79+
- `he`: HE.net
80+
- `huaweidns`: 华为云DNS
81+
- `callback`: 自定义回调
82+
83+
### `--id ID`
84+
85+
API访问ID或用户标识。
86+
87+
- **必需**: 是（部分DNS服务商可选）
88+
- **说明**:
89+
- Cloudflare: 填写邮箱地址（使用Token时可留空）
90+
- HE.net: 可留空
91+
- 华为云: 填写Access Key ID (AK)
92+
- 其他服务商: 根据各自要求填写ID
93+
94+
### `--token TOKEN`
95+
96+
API授权令牌或密钥。
97+
98+
- **必需**: 是
99+
- **说明**: 部分平台称为Secret Key，请妥善保管
100+
101+
## 域名配置参数
102+
103+
### `--ipv4 [DOMAIN...]`
104+
105+
需要更新IPv4记录的域名列表。
106+
107+
- **默认值**: `[]`（不更新IPv4地址）
108+
- **示例**:
109+
- `--ipv4 example.com` (单个域名)
110+
- `--ipv4 example.com --ipv4 subdomain.example.com` (多个域名)
111+
112+
### `--ipv6 [DOMAIN...]`
113+
114+
需要更新IPv6记录的域名列表。
115+
116+
- **默认值**: `[]`（不更新IPv6地址）
117+
- **示例**:
118+
- `--ipv6 example.com` (单个域名)
119+
- `--ipv6 example.com --ipv6 ipv6.example.com` (多个域名)
120+
121+
## IP获取方式参数
122+
123+
### `--index4 [METHOD...]`
124+
125+
IPv4地址获取方式。
126+
127+
- **默认值**: `default`
128+
- **可选值**:
129+
- 数字（`0`，`1`，`2`...）: 第N个网卡IP
130+
- `default`: 系统访问外网默认IP
131+
- `public`: 使用公网IP（通过API查询）
132+
- `url:{URL}`: 从指定URL获取IP
133+
- `regex:{PATTERN}`: 使用正则表达式匹配本地网络配置中的IP
134+
- `cmd:{COMMAND}`: 执行指定命令并使用其输出作为IP
135+
- `shell:{COMMAND}`: 使用系统shell运行命令并使用其输出作为IP
136+
- **示例**:
137+
- `--index4 0` (第一个网卡)
138+
- `--index4 public` (公网IP)
139+
- `--index4 "url:http://ip.sb"` (从URL获取)
140+
- `--index4 "regex:192\\.168\\.*"` (匹配192.168开头的IP)
141+
- `--index4 public --index4 0` (先尝试获取公网IP，失败则使用第一个网卡)
142+
143+
### `--index6 [METHOD...]`
144+
145+
IPv6地址获取方式，用法同`--index4`。
146+
147+
## 网络配置参数
148+
149+
### `--ttl TTL`
150+
151+
DNS解析TTL时间（秒）。
152+
153+
- **默认值**: `null`（使用DNS服务商默认设置）
154+
- **示例**:
155+
- `--ttl 600` (10分钟)
156+
- `--ttl 3600` (1小时)
157+
158+
### `--proxy [PROXY...]`
159+
160+
HTTP代理设置，支持多代理轮换。
161+
162+
- **默认值**: 无（DIRECT 直连）
163+
- **示例**:
164+
- `--proxy 127.0.0.1:1080` (单个代理)
165+
- `--proxy 127.0.0.1:1080 --proxy DIRECT` (多个代理，逐个尝试)
166+
167+
## 系统配置参数
168+
169+
### `--cache [BOOL|PATH]`
170+
171+
启用缓存以减少API请求。
172+
173+
- **默认值**: `true`
174+
- **可选值**:
175+
- `true`: 启用缓存，使用默认路径
176+
- `false`: 禁用缓存
177+
- 文件路径: 自定义缓存文件位置
178+
- **示例**:
179+
- `--cache` (启用默认缓存)
180+
- `--cache=false` (禁用缓存)
181+
- `--cache=/path/to/ddns.cache` (自定义缓存路径)
182+
183+
### `--debug`
184+
185+
启用调试模式（等同于设置`--log.level=DEBUG`）。
186+
187+
- **说明**: 此参数仅作为命令行参数有效，配置文件中的同名设置无效
188+
- **示例**: `--debug`
189+
190+
## 日志配置参数
191+
192+
### `--log.level {CRITICAL|FATAL|ERROR|WARN|WARNING|INFO|DEBUG|NOTSET}`
193+
194+
设置日志级别。
195+
196+
- **默认值**: `INFO`
197+
- **示例**:
198+
- `--log.level=DEBUG` (调试模式)
199+
- `--log.level=ERROR` (仅显示错误)
200+
201+
### `--log.file LOGFILE`
202+
203+
设置日志文件路径。
204+
205+
- **默认值**: 无（输出到控制台）
206+
- **示例**:
207+
- `--log.file=/var/log/ddns.log`
208+
- `--log.file=./ddns.log`
209+
210+
### `--log.format FORMAT`
211+
212+
设置日志格式字符串（参考Python logging模块格式）。
213+
214+
- **默认值**: `%(asctime)s %(levelname)s [%(module)s]: %(message)s`
215+
- **示例**:
216+
- `--log.format="%(asctime)s %(levelname)s: %(message)s"`
217+
- `--log.format="%(levelname)s [%(filename)s:%(lineno)d]: %(message)s"`
218+
219+
### `--log.datefmt FORMAT`
220+
221+
设置日期时间格式字符串（参考Python time.strftime()格式）。
222+
223+
- **默认值**: `%Y-%m-%dT%H:%M:%S`
224+
- **示例**:
225+
- `--log.datefmt="%Y-%m-%d %H:%M:%S"`
226+
- `--log.datefmt="%m-%d %H:%M:%S"`
227+
228+
## 常用命令示例
229+
230+
### 使用配置文件
231+
232+
```bash
233+
# 使用默认配置文件
234+
ddns
235+
236+
# 使用指定配置文件
237+
ddns -c /path/to/config.json
238+
```
239+
240+
### 命令行临时修改配置
241+
242+
```bash
243+
# 启用调试模式
244+
ddns --debug
245+
246+
# 使用指定配置文件并启用调试模式
247+
ddns -c /path/to/config.json --debug
248+
249+
# 更新特定域名的IPv4地址（多个域名）
250+
ddns --ipv4 example.com --ipv4 www.example.com
251+
252+
# 设置为阿里云DNS并提供认证信息
253+
ddns --dns alidns --id YOUR_ACCESS_KEY_ID --token YOUR_ACCESS_KEY_SECRET
254+
```
255+
256+
### 高级用法示例
257+
258+
```bash
259+
# 使用公网IP和特定的网络配置
260+
ddns --ipv4 example.com --index4 public --ttl 600 --proxy 127.0.0.1:1080
261+
262+
# 自定义日志配置
263+
ddns --log.level=DEBUG --log.file=./ddns.log --log.format="%(asctime)s - %(levelname)s: %(message)s"
264+
265+
# 完整配置示例
266+
ddns --dns cloudflare --id user@example.com --token API_TOKEN \
267+
--ipv4 example.com --ipv4 www.example.com --ipv6 example.com \
268+
--index4 public --index6 "regex:2001:.*" \
269+
--ttl 300 --proxy 127.0.0.1:1080 --proxy DIRECT \
270+
--cache=/var/cache/ddns.cache \
271+
--log.level=INFO --log.file=/var/log/ddns.log
272+
```
273+
274+
## 注意事项
275+
276+
1. 命令行参数具有最高优先级，会覆盖配置文件和环境变量中的设置。
277+
2. 对于需要空格的参数值，请使用引号包围，例如：`--log.format="%(asctime)s: %(message)s"`。
278+
3. 对于多值参数（如`--ipv4`、`--index4`、`--proxy`等），请重复使用参数标识，例如：`--ipv4 example.com --ipv4 sub.example.com`。
279+
4. `--debug`参数仅在命令行中有效，配置文件中的debug设置将被忽略。

0 commit comments

Comments
 (0)