网络CLI【免费下载链接】DDNS自动更新域名解析到本机IP,支持dnspod,阿里DNS,CloudFlare,华为云,DNSCOM...项目地址https://gitcode.com/gh_mirrors/dd/DDNS点击查看免费下载本文档面向希望扩展或改造 DDNS 配置系统的开发者系统讲解其「CLI 参数 JSON 文件 环境变量 默认值」的分层合并架构、Config类的统一访问接口以及从 JSON Schema 到单元测试的完整参数添加流程。读完本文你将掌握新增配置参数的标准五步法、数组/布尔/数值等特殊类型的底层处理规则并能基于仓库源码理解endpoint等参数在 Provider 层的工作机制。系统架构三源合一的配置管道DDNS 的配置系统采用分层架构所有配置源最终汇入同一个Config类再由 Provider 与应用模块消费。整体优先级链条如下┌─────────────────────────────────────────────┐ │ 配置源优先级 │ ├─────────────────────────────────────────────┤ │ CLI 参数 JSON 文件 环境变量 默认值 │ ├─────────────────────────────────────────────┤ │ Config 类 │ │ 统一配置访问接口 │ ├─────────────────────────────────────────────┤ │ Provider 和应用模块 │ └─────────────────────────────────────────────┘核心模块位于 ddns/config/ 目录cli.py—— 命令行参数解析负责把argparse解析结果转换为配置字典file.py—— JSON 配置文件的加载与保存支持本地文件、远程 HTTP(S) URL、注释与 AST 回退解析开发文档中提到的json.py在仓库中实际实现为file.pyenv.py—— 环境变量解析默认前缀DDNS_config.py——Config类实现负责按优先级合并三路配置并完成类型转换__init__.py—— 对外入口load_configs()串联起完整加载流程。真实加载链路load_configs()从 ddns/config/init.py#L101-L171 可以看到完整的加载顺序先解析 CLI 得到cli_config再读取环境变量得到env_config随后根据-c/--config或DDNS_CONFIG指定的路径支持多个、支持远程 URL逐一加载 JSON 配置最后为每个 JSON 配置创建一个Config(cli_config, json_config, env_config)实例。这意味着多配置文件场景下会得到多个Config对象每个都共享同一份 CLI 与环境变量配置。load_configs还会对每个配置执行「必须指定 DNS 服务商」的校验缺失时打印错误并退出ddns/config/init.py#L90-L98。在 ddns/main.py#L149 中程序入口通过load_configs(__description__, __version__, build_date)拿到配置列表再逐个交给run()执行 IP 获取与 DNS 记录更新。因此理解配置系统就理解了 DDNS 整个运行流程的起点。Config 类统一配置访问接口Config是配置系统的核心。它接收三份原始配置字典并在构造阶段把所有参数投影为实例属性供上层模块直接读取。开发文档给出的骨架如下class Config(object): def __init__(self, cli_configNone, json_configNone, env_configNone): self._cli_config cli_config or {} self._json_config json_config or {} self._env_config env_config or {} # 配置属性初始化 self.dns self._get(dns, debug) self.endpoint self._get(endpoint) # 新增的端点配置 def _get(self, key, defaultNone): 按优先级获取配置值CLI JSON ENV default return ( self._cli_config.get(key) or self._json_config.get(key) or self._env_config.get(key) or default )对照当前仓库 ddns/config/config.py#L90-L183 的真实实现_get的语义与骨架一致但细节更丰富def _get(self, key, defaultNone): value self._cli_config.get(key) if isinstance(value, list) and len(value) 1: # 单个元素的列表取出第一个元素 value value[0] if value is None: value self._json_config.get(key, self._env_config.get(key, default)) if is_false(value): return False # 处理数组参数 if key in SIMPLE_ARRAY_PARAMS: return split_array_string(value, key in (index4, index6)) return value两点值得注意单元素列表解包CLI 解析出的多值参数可能以列表形式存在若列表只有一个元素_get会取出该元素避免上层拿到[value]而非value。is_false特殊判断字符串false、none不区分大小写、忽略首尾空格以及布尔False会被直接解析为False而数字0不被当作 False见 ddns/config/config.py#L39-L47这保证了index4: 0第一个网卡这类合法取值不被误伤。另外当前源码中self.dns self._get(dns, )的默认值是空字符串而非debugddns/config/config.py#L139debug是--new-config生成配置文件模板时的默认值ddns/config/file.py#L163。tests/test_config_config.py中的test_config_initialization_comprehensive也确认了空默认行为Config()构造后dns 。配置指纹md5()Config.md5()ddns/config/config.py#L242-L274会对合并后的关键配置字段dns、id、token、endpoint、index4/index6、ipv4/ipv6、line、ttl、cache、proxy、ssl 及全部日志与 extra 字段序列化后计算 MD5。该指纹用于缓存键隔离__main__.run()中Cache.new(config.cache, config.md5(), ...)保证配置不同时缓存互不串扰测试用例test_config_md5_and_edge_cases验证了相同配置指纹一致、不同配置指纹不同的行为。已知键与 extra 收集Config内部维护_known_keys集合ddns/config/config.py#L106-L136凡是已知键都不会进入extra而extra_前缀的键、嵌套的extra字典以及所有未知键都会被收集进config.extra优先级仍为 CLI JSON ENV见_collect_extra。这些 extra 字段最终通过 ddns/main.py#L99 的dns.set_record(..., **config.extra)透传给各 Provider用于传递服务商私有参数。CLI 侧还支持--extra.xxx value这种未知参数写法会在 ddns/config/cli.py#L563-L585 被转换为extra_xxx注入。配置参数全览必需参数id—— DNS 服务商认证 ID部分服务商可留空如 Cloudflare 使用 Token 时、HE.nettoken—— DNS 服务商 API Token / Secret Key绝大多数服务商必填。从 schema/v4.0.json#L316-L318 看Schema 的required数组仅包含token并设置了additionalProperties: false因此非法键会在编辑期即被 IDE 拦截。主要参数默认值与说明参数类型默认值说明dnsstring空字符串模板为debugDNS 服务商标识endpointstring | nullnull自定义 API 端点覆盖服务商默认端点ipv4/ipv6array[]待更新的 IPv4/IPv6 域名列表index4/index6string | int | bool | array[default]本机 IP 获取方式支持default、public、数字、url:、regex:、cmd:、shell:等规则ttlnumber | nullnullDNS TTL秒不填则使用服务商默认linestring | nullnullDNS 线路/路由如电信、telecom部分服务商支持proxystring | null | array[]HTTP 代理多个代理分号/逗号分隔依次尝试DIRECT表示直连cachestring | booltrue是否启用缓存也可传入自定义缓存文件路径cache_max_ageint259200缓存文件最大有效期秒0表示每次运行清空缓存sslstring | boolautoSSL 验证方式true/false/auto/自定义 CA 证书路径log_levelstringINFO日志级别DEBUG/INFO/WARNING/ERROR/CRITICALlog_filestring | nullnull日志文件路径空则输出到控制台log_formatstring | null按级别自适应Pythonlogging格式字符串log_datefmtstring%Y-%m-%dT%H:%M:%S日期时间格式在 v4.1 版本schema/v4.1.json中配置还增加了intervalWeb 控制台内置同步间隔1–1440 分钟、httpWeb 与 MCP HTTP 共享的 host/port/token/origins 监听配置以及providers多服务商数组每个元素包含provider、id、token、endpoint等独立配置。注意providers与顶层dns不能同时出现file.py的_process_multi_providers会对此报错ddns/config/file.py#L25-L28。支持的 DNS 服务商开发文档列出了 11 个服务商当前仓库实际支持 18 个以 ddns/config/cli.py#L172-L194 的--dnschoices 为准51dns, alidns, aliesa, callback, cloudflare, cloudns, debug, dnscom, dnspod_com, dnspod, edgeone, edgeone_dns, he, huaweidns, namesilo, noip, tencentcloud, west注schema/v4.0.json#L58-L73 的 dns 枚举为 14 项缺少51dns、cloudns、edgeone_dns、westv4.1 的 providers 枚举已补齐为 18 项。此外ddns/provider/init.py#L33-L92 的get_provider_class维护了大量兼容别名例如dnspod_cn → dnspod、dnspod_global → dnspod_com、qcloud/tencent → tencentcloud、no-ip → noip、webhook/http → callback、print → debug、51dns/dns_com → dnscom、35cn → west等历史配置中的旧名称可继续使用。添加新配置参数五步开发流程开发文档给出了「修改 4 个文件」的流程结合英文版文档与实际仓库完整流程可归纳为五步JSON Schema、CLI 参数、环境变量、Config 类、单元测试外加文档同步。1. 更新 JSON Schema在 schema/v4.0.json或 v4.1的properties中定义新参数让 IDE/编辑器获得补全与校验{ properties: { my_param: { type: string, title: My Parameter, description: Description of my parameter, default: default_value } } }Schema 使用的是 JSON Schema draft-07。建议同时补充pattern、minLength、maxLength、enum等约束例如 v4.0 中对ipv4/ipv6域名列表就定义了严格的正则模式schema/v4.0.json#L75-L91。2. 添加 CLI 参数在 ddns/config/cli.py 的_add_ddns_args()中通过add_argument注册新参数arg.add_argument( --my-param, helpDescription of my parameter, defaultNone )若参数支持多值可结合nargs*与项目自实现的ExtendAction兼容 Python 3.8 之前缺失的extendaction见 ddns/config/cli.py#L113-L125从而支持「重复参数名」与「空格分隔」两种传值方式。load_config()最终会把 Namespace 转为字典并过滤None值ddns/config/cli.py#L599-L601保证只有用户显式给出的值才参与合并。3. 环境变量支持自动 命名规则新参数无需额外编码即可自动获得环境变量支持命名规则为DDNS_PARAM_NAME全大写export DDNS_MY_PARAMvalueddns/config/env.py#L38-L79 的load_config()会遍历environ凡是以DDNS_开头的变量均会剥离前缀并转为小写键名同时支持点号转下划线如DDNS_LOG.LEVEL→log_level。它还会对以[开头]结尾的变量值尝试用literal_eval解析为数组失败时输出告警对token、http_token去除首尾空格识别标准环境变量别名PYTHONHTTPSVERIFY → ssl显式DDNS_SSL优先级更高。4. 更新 Config 类在 ddns/config/config.py 的__init__中增加属性投影并在md5()的字典中加入新字段如需参与缓存指纹class Config(object): def __init__(self, cli_configNone, json_configNone, env_configNone): # ...existing code... self.my_param self._get(my_param, default_value) def md5(self): return md5(str({ # ...existing fields... my_param: self.my_param, }).encode(utf-8)).hexdigest()同时把新键加入_known_keysddns/config/config.py#L106-L136避免它被误收进extra而透传给 Provider 的 API 调用。5. 添加单元测试在 tests/test_config_config.py或对应模块的测试文件中至少覆盖三种配置源与优先级def test_my_param_configuration(self): Test my_param configuration from different sources # CLI 配置测试 config Config(cli_config{my_param: cli_value}) self.assertEqual(config.my_param, cli_value) # JSON 配置测试 config Config(json_config{my_param: json_value}) self.assertEqual(config.my_param, json_value) # 优先级测试CLI JSON config Config( cli_config{my_param: cli_value}, json_config{my_param: json_value} ) self.assertEqual(config.my_param, cli_value) # CLI 优先仓库现成的测试模式可以参考TestConfig.test_config_initialization_comprehensive默认值断言与test_config_boolean_and_special_values类型转换断言它们分别验证了默认值与str_bool转换的各种边界情况。6. 同步文档最后在 docs/config/cli.md、docs/config/env.md、docs/config/json.md 中补充参数说明、使用示例、默认值与合法取值范围保持「代码—Schema—文档」三者一致。特殊类型处理数组参数需要在SIMPLE_ARRAY_PARAMS中注册才会被自动拆分。当前注册的键为[ipv4, ipv6, proxy, index4, index6]ddns/config/config.py#L20SIMPLE_ARRAY_PARAMS [ipv4, ipv6, proxy, index4, index6]核心拆分函数是split_array_string()ddns/config/config.py#L50-L87。它的行为比文档示例更精细传入已是list时原样返回空值返回[]非字符串标量如整数123、0包装为单元素列表分隔符判定有优先级在「特殊来源起始位置之前」的范围内优先用逗号,只有该范围无逗号才用分号;定义SPECIAL_ARRAY_PREFIXES (url:, regex:, cmd:, shell:)ddns/config/config.py#L21一旦某段以这些前缀开头后续所有内容即使含逗号/分号都会合并为同一条规则因为 URL 查询串、正则与 shell 命令可能自带分隔符但对proxy参数会以preserve_specialFalse调用因此url:8080;DIRECT会被正确拆成[url:8080, DIRECT]见测试test_split_array_string_comprehensive。例如split_array_string(item1,item2,item3) # [item1, item2, item3] split_array_string(item1;item2;item3) # [item1, item2, item3] split_array_string(public,regex:192\\.168\\..*) # [public, regex:192\\.168\\..*] split_array_string(regex:192\\.168\\..*,public) # [regex:192\\.168\\..*,public] 整条保留布尔值处理开发文档示例中的str_bool支持true/yes/1/on等当前仓库实现位于 ddns/config/cli.py#L26-L42语义略有差异以实际为准def str_bool(v): if isinstance(v, bool): return v if v is None: return False if not isinstance(v, str) and not type(v).__name__ unicode: return bool(v) if v.lower() in (yes, true, t, y, 1): return True elif v.lower() in (no, false, f, n, 0): return False else: return v # 非布尔字符串原样返回如 auto、证书路径这一「原样返回」设计很关键cache、ssl等参数既可以接收布尔值也可以接收auto或自定义证书路径这类字符串str_bool不会把它们误转成布尔。测试test_config_boolean_and_special_values验证了(auto, auto)、(path/to/cert, path/to/cert)等用例。数值与日志级别转换ttlint(ttl) if isinstance(ttl, string_types) else ttl字符串含 bytes会被转成整数数值保持原样ddns/config/config.py#L147-L148cache_max_age通过_get_cache_max_age()ddns/config/config.py#L185-L199强制非负整数布尔值、负数、非法字符串、浮点数都会抛ValueErrorlog_level字符串经getLevelName()映射为logging数值级别DEBUG→10、INFO→20、WARNING→30、ERROR→40、CRITICAL→50测试test_config_array_and_conversion_parameters覆盖了全部映射CLI 侧的--cache-max-age、--ssl、--log_level等还会经过non_negative_int、port_number、interval_minutes等类型校验函数非法输入会在参数解析阶段直接报错ddns/config/cli.py#L45-L96。配置使用示例CLI 基本用法python -m ddns --dnscloudflare --endpointhttps://api.custom.com/v4/多值参数支持重复参数或空格分隔注意 CLI 侧不支持逗号拼接多个域名ddns --dns cloudflare --id userexample.com --token API_TOKEN \ --ipv4 example.com --ipv4 www.example.com \ --index4 public --index6 regex:2001:.* \ --ttl 300 --proxy http://127.0.0.1:1080 --proxy DIRECTJSON 配置{ $schema: https://ddns.newfuture.cc/schema/v4.0.json, dns: cloudflare, endpoint: https://api.custom.com/v4/, ipv4: [example.com], ttl: 600 }配置文件支持//与#注释加载前会经remove_comment清理、嵌套对象展平如log.level自动展平为log_level以及extra/http等保留键ddns/config/file.py#L45-L71。可通过ddns --new-config config.json一键生成带默认值的模板ddns/config/cli.py#L128-L147未指定路径时会写入当前目录config.json若已存在则提示用--new-config路径指定新文件。环境变量export DDNS_DNScloudflare export DDNS_ENDPOINThttps://api.custom.com/v4/ export DDNS_IPV4[example.com] # 数组字面量会被解析为列表多配置文件与远程配置-c/--config可重复指定也支持 HTTP(S) URL远程拉取失败会自动重试 3 次见 ddns/config/file.py#L97-L107ddns -c cloudflare.json -c dnspod.json ddns -c https://config.example.com/ddns.json --proxy http://proxy:8080配置文件默认查找路径为config.json、~/.ddns/config.json、~/.ddns.json、/etc/ddns/config.json、/etc/ddns.jsonddns/config/file.py#L14。配置验证、调试与测试配置完整性验证开发文档给出的验证思路id/token 必填、provider 受支持、ttl 范围在仓库中以更细化的方式落地load_configs会对每个配置执行「DNS 服务商必填」校验ddns/config/init.py#L90-L98Provider 层还会在_validate()中要求id、token、endpoint均非空ddns/provider/_base.py#L162-L174。文档示例可作为一个通用的扩展模板def validate_config(config): 验证配置完整性 errors [] if not config.id or not config.token: errors.append(id and token are required) if config.dns not in SUPPORTED_DNS_PROVIDERS: errors.append(Unsupported DNS provider: {}.format(config.dns)) if config.ttl and (config.ttl 1 or config.ttl 86400): errors.append(TTL must be between 1 and 86400 seconds) return errors配置调试敏感信息脱敏调试输出配置信息时务必隐藏凭据文档中的模式可直接复用def debug_config(config): 输出配置信息隐藏敏感数据 config_dict config.dict() for key, value in config_dict.items(): if key token and value: value value[:2] *** value[-2:] print({}: {}.format(key, value))运行配置相关测试仓库提供了完善的配置测试套件tests/test_config_*.py可按如下方式运行# 运行配置相关测试 python -m unittest discover tests -k test_config -v # 测试特定功能 python -m unittest tests.test_config_config.TestConfig -v其中 tests/test_config_config.py 覆盖了split_array_string的各种分隔符与特殊前缀组合、三源优先级CLI JSON ENV、ttl/log_level/cache/ssl类型转换、cache_max_age校验、md5指纹以及extra收集行为是新增参数测试的最佳参照。测试工具函数开发文档提供的create_test_config工厂函数适合在扩展测试中快速构造配置def create_test_config(**overrides): 创建测试配置 default_config { dns: debug, id: test_id, token: test_token } default_config.update(overrides) return Config(json_configdefault_config) # 使用 config create_test_config(dnscloudflare, endpointhttps://api.test.com)开发最佳实践添加新参数的检查清单✅JSON Schema—— 在 schema/v4.0.json / schema/v4.1.json 中定义类型、默认值与约束✅CLI 参数—— 在 ddns/config/cli.py 中添加--param-name多值参数配ExtendAction✅Config 类—— 在 ddns/config/config.py 中添加属性投影、加入_known_keys按需纳入md5()✅单元测试—— 测试配置优先级和类型转换参考TestConfig系列用例✅向后兼容—— 提供合理的默认值必要时兼容旧参数名如self.new_param self._get(new_param) or self._get(old_param)✅文档同步—— 更新 docs/config/cli.md、docs/config/env.md、docs/config/json.md。代码规范类型安全统一使用str_bool()、int()、split_array_string()等转换函数避免在业务代码里手工判断类型默认值所有新参数必须有默认值保证不配置也能运行命名规范配置键使用下划线my_paramCLI 参数使用连字符--my-param环境变量使用DDNS_MY_PARAM严格 Schemav4.0 顶层additionalProperties: false新键必须先进 Schema 再使用否则会被 IDE 标记为非法。endpoint 参数特性endpoint是 v4.0 引入的覆盖型参数主要用于覆盖 DNS Provider 类的默认 API 端点如自定义或私有化部署地址支持测试环境、镜像节点或网关代理场景在 Provider 初始化时优先于类的 API 属性生效。其底层机制在 ddns/provider/_base.py#L110-L139SimpleProvider.__init__接收endpoint关键字参数若传入则执行self.endpoint endpoint覆盖类属性默认值。而 ddns/main.py#L124-L127 的run()正是用provider_class(config.id, config.token, endpointconfig.endpoint, loggerlogger, proxyconfig.proxy, sslconfig.ssl)将配置注入 Provider。由于_validate()要求endpoint非空实际覆盖发生在实例化阶段各子类通过self.endpoint拼接 API 路径见_http与各 Provider 实现。配置系统架构优势多源融合CLI、JSON、环境变量三路配置无缝合并-c支持多个文件与远程 URL优先级明确CLI JSON ENV 默认值由_get()单点保证行为可预测类型安全自动类型转换数组/布尔/整数/日志级别与多层校验Schema、CLI 类型函数、Config 构造期、Provider_validate易于扩展添加新参数仅需五步且环境变量支持自动生效向后兼容新旧参数名别名映射get_provider_class、_get双键兜底、默认值兜底历史配置无需迁移即可继续使用。通过这套配置系统开发者可以快速为 DDNS 增加新功能参数同时保持代码一致性与可维护性——所有改动路径都有现成的源码、Schema 与测试作为参照。赞分享网络CLI【免费下载链接】DDNS自动更新域名解析到本机IP,支持dnspod,阿里DNS,CloudFlare,华为云,DNSCOM...项目地址https://gitcode.com/gh_mirrors/dd/DDNS点击查看免费下载相关推荐DDNS 配置系统开发指南从分层架构到自定义参数扩展的完整实践DDNS 配置系统开发指南从分层架构到自定义参数扩展的完整实践 导读 本文面向想要理解或扩展 DDNS 配置系统的开发者以 ddns/config 模块网络CLISphinx 扩展机制详解内置扩展全景、配置参数与实战指南Sphinx 扩展机制详解内置扩展全景、配置参数与实战指南 Sphinx 文档生成器允许在构建流程中挂载扩展extension每个扩展都可以修改文档文档开发工具Linux系统DisplayLink多屏扩展配置指南Linux系统DisplayLink多屏扩展配置指南 在日常工作中你是否遇到过这样的困扰使用USB扩展坞连接多个显示器时Linux系统无法正常识别外接显示嵌入式创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考