AdGuard Home v0.108.0 命令行接口重构指南：--web-addr、stderr 日志与 SIGHUP 热重载等变更详解

AdGuard Home v0.108.0 命令行接口重构指南--web-addr、stderr 日志与 SIGHUP 热重载等变更详解【免费下载链接】AdGuardHomeNetwork-wide ads trackers blocking DNS server项目地址: https://gitcode.com/gh_mirrors/ad/AdGuardHome本篇指南聚焦 AdGuard Home 面向 v0.108.0 的命令行接口与配置管理演进覆盖新增的--web-addr、--logfilestderr、可配置 pprof 端口、SIGHUP全量热重载以及-h语义调整、旧参数移除与多项历史缺陷修复。读完本文你将掌握新旧参数的一一对应关系、新式host:port地址解析规则、配置热重载的底层实现原理以及升级后配置文件与启动命令的正确写法。文档定位一份仍在演进中的 v0.108.0 变更草案本文依据的原始材料是仓库中的 internal/next/changelog.md。该文档在开头即注明“This changelog should be merged into the main one once the next API matures enough.”待新一代 API 成熟后将合并进主 CHANGELOG说明这是 v0.108.0 发布前的变更草案。“next”在源码层面指代 internal/next 目录下正在推进的架构重写新的入口 internal/next/cmd/cmd.go、新的配置管理器 internal/next/configmgr/configmgr.go、新的 DNS 服务与 Web 服务模块。本草案记录的正是这次重写对启动参数command-line options、日志输出、Web UI 监听地址与配置重载机制带来的可见变化因此对使用者而言具有直接的升级指导价值。值得注意的是其中“New HTTP API新 HTTP API”小节在草案中仍标记为TODO(a.garipov)尚未形成最终描述与之配套的 OpenAPI 定义可参见 openapi/next.yaml。新增四项值得关注的新能力1. pprof 调试 API 端口可配置草案新增的第一项能力是“The ability to change the port of the pprof debug API”即 Gonet/http/pprof性能分析端口的可配置化。在新架构中pprof 不再是布尔开关而是一个独立配置块定义于 internal/next/configmgr/config.go// httpPprofConfig is the on-disk pprof configuration. type httpPprofConfig struct { Port uint16 yaml:port Enabled bool yaml:enabled }对应的 YAML 写法在示例配置 internal/next/AdGuardHome.example.yaml 中给出http: pprof: port: 6060 enabled: true端口字段类型为uint16因此合法取值范围为 0–65535enabled控制是否挂载 profiling HTTP handler。从配置迁移测试 internal/configmigrate/migrations_internal_test.go 可以看到旧版配置中的debug_pprof: true会被迁移为pprof: {enabled: true, port: 6060}结构默认端口 6060这属于配置格式的平滑演进。2.--logfilestderr日志输出到标准错误草案新增“The ability to log to stderr using--logFilestderr”。在新代码中该参数的完整定义为 internal/next/cmd/opt.go 中的logFileIdxlogFileIdx: { defaultValue: stdout, description: Path to log file. Special values include stdout, stderr, and syslog., long: logfile, short: l, valueType: path, },即实际参数名为小写--logfile短参数-l支持三个特殊取值stdout写入标准输出默认值stderr写入标准错误syslog写入系统日志草案对应实现中仍标注 TODO参见 internal/next/cmd/log.go 中的newBaseLogger分支逻辑。这一能力对以服务方式运行、需要将应用日志与标准输出流量分离的场景例如被 systemd 等进程管理器接管日志时非常实用。newBaseLogger依据opts.logFile的值选择输出流并在opts.verbose为真时把日志级别从slog.LevelInfo提升到slog.LevelDebug。3.--web-addr以host:port形式指定 Web UI 监听地址草案新增“The new--web-addrflag to set the Web UI address in ahost:portform”这是本次 CLI 变化的核心。其定义同样位于 internal/next/cmd/opt.gowebAddrIdx: { defaultValue: netip.AddrPort{}, description: Address to serve the web UI on, in the host:port format., long: web-addr, short: , valueType: host:port, },几点值得注意的源码细节参数值类型为netip.AddrPort通过flag.TextVar注册见parseOptions/addOption因此必须是合法的 IP 加端口组合例如--web-addr192.168.1.10:3000internal/home/options_internal_test.go 的TestParseBindAddr覆盖了大量边界情况1.2.3.4:0合法、1.2.3.4:x非数字端口报错、1.2.3.4:0x100十六进制报错、负数端口与超过 65536 的端口均报错在 internal/next/configmgr/configmgr.go 中该值作为Config.WebAddr注释明确“It is not written to the configuration file”即不会回写进配置文件传入websvc.Config.OverrideAddress作为 Web 服务的覆盖监听地址。# 通过命令行覆盖 Web UI 监听地址示例 ./AdGuardHome --web-addr0.0.0.0:80804.SIGHUP全量热重载配置草案新增“SIGHUPnow reloads all configuration from the configuration fileissue #5676”。在新架构中这一行为由服务管理器实现见 internal/next/cmd/service.go 的Refresh方法其流程为记录日志reconfiguring started调用Shutdown依次关闭 Web 服务与 DNS 服务通过configmgr.New依据配置文件重建配置管理器updConfMgr重新Start启动 Web 服务与 DNS 服务记录日志reconfiguring finished。源码注释也如实标注了该实现的粗糙之处“This is a very rough way to do it. Some services can be reconfigured without the full shutdown”部分服务本可免于整体关停当前实现是整体重启式重载。使用方式为# 修改配置文件后向运行中的进程发送 SIGHUP 触发重载 kill -HUP AdGuardHome_PID变更-h语义调整与新一代 HTTP API-h从--host变为--help的别名草案“Other changes”小节指出-h现在是--help的别名取代了原先的--host需要设置 Web UI 地址时请改用--web-addrhost:port。在 internal/next/cmd/opt.go 中helpIdx定义为helpIdx: { defaultValue: false, description: Print this help message and quit., long: help, short: h, valueType: , },对照 internal/home/options.go 中旧版--host的定义description 注明 “Deprecated. Host address to bind HTTP server on. Use --web-addr. The short -h will work as --help in the future.”可以清晰看到这一迁移路径旧参数先被标记废弃最终在 v0.108.0 中移除并把-h让位给帮助输出。# v0.108.0 中查看帮助 ./AdGuardHome -h ./AdGuardHome --help新一代 HTTP API 仍在打磨中草案中的“New HTTP API”小节目前只有一句TODO(a.garipov): Describe the new API and add a link to the new OpenAPI doc.说明新一代 Web API 的对外描述尚未定稿。感兴趣的读者可以提前查看 openapi/next.yaml 了解其形态但应以正式发布时的 CHANGELOG 与 API 文档为准本文不展开虚构细节。修复三个历史问题的解决--check-config不再破坏配置文件issue #4067旧实现中仅做配置校验的--check-config在特定情况下会改写损坏配置文件本身。新架构将其与配置写入解耦校验逻辑独立为configmgr.Validate见 internal/next/configmgr/configmgr.go只负责读取、解码与校验不触碰磁盘写入processOptions在校验失败时向 stdout 输出错误并以失败码退出成功则正常退出。# 只校验配置文件不修改它v0.108.0 起安全可重复执行 ./AdGuardHome --check-config--work-dir/-w应用不一致issue #2598、#2902草案修复了--work-dir/-w应用不一致的问题。新入口中工作目录在读取其他一切配置之前生效见 internal/next/cmd/cmd.go 中Main的调用顺序——解析参数后先os.Chdir(opts.workDir)再读取配置文件保证“所有相对路径均相对于工作目录”。internal/next/cmd/opt.go 中workDirIdx的描述也明确了这一语义workDirIdx: { defaultValue: , description: Path to the working directory. It is applied before all other configuration is read, so all relative paths are relative to it., long: work-dir, short: w, valueType: path, },-v/--verbose与--version的顺序不再影响结果issue #2893旧实现中-v --version与--version -v会产生不同输出属于参数处理顺序缺陷。新实现将两者作为独立布尔标志处理processOptions中先检查--help再检查--version——若opts.version为真则根据opts.verbose决定输出简短版本号AdGuard Home version还是详细版本信息version.Verbose(...)与命令行书写顺序无关。移除被取代的旧参数--no-mem-optimization与--no-etc-hosts草案移除了两个早已废弃的参数--no-mem-optimization关闭内存优化与--no-etc-hosts不读取 hosts 文件。在新架构中它们对应的行为不再通过命令行暴露相关配置走配置文件路径。--host与-p/--port的告别草案移除--host与-p/--port统一由--web-addrhost:port承担 Web UI 监听地址的职责。旧参数在 internal/home/options.go 中仍留有“Deprecated ... Use --web-addr”的过渡说明可作为迁移对照。下表总结了本次 CLI 变动的对应关系旧参数已移除新参数说明--host ip--web-addrhost:port绑定地址与端口合并为一个参数-p/--port port--web-addrhost:port同上-h原--host-h/--help语义改为打印帮助--no-mem-optimization无移入配置/默认行为废弃项清理--no-etc-hosts无移入配置/默认行为废弃项清理完整命令行参数参考来自 cmd/opt.go新架构 internal/next/cmd/opt.go 的commandLineOptions表完整登记了 v0.108.0 支持的参数整理如下长参数短参数取值类型默认值说明--config-cpathinternal/next/AdGuardHome.yaml开发期默认配置文件路径--logfile-lpathstdout日志文件路径特殊值stdout/stderr/syslog--pidfile—path空PID 文件路径--service-saction空服务控制动作status/install/uninstall/start/stop/restart/reload--work-dir-wpath空工作目录先于其他配置生效--web-addr—host:port空Web UI 监听地址--check-config——false校验配置并退出--no-check-update——false禁用自动更新检查--glinet——falseGL-Inet 兼容模式--help-h—false打印帮助并退出--local-frontend——false使用本地前端目录--no-permcheck——false跳过敏感文件权限检查--update——false更新当前二进制并在必要时重启服务--verbose-v—false详细日志Debug 级别--version——false打印版本并退出配合-v输出详细信息新配置文件示例与校验配合新的 pprof 配置块与 HTTP 配置一份典型的 next 架构配置文件节选自 internal/next/AdGuardHome.example.yaml如下dns: upstream_mode: parallel addresses: - 0.0.0.0:53 bootstrap_dns: - 9.9.9.10 - 149.112.112.10 upstream_dns: - 8.8.8.8 upstream_timeout: 1s cache_size: 1048576 ratelimit: 100 http: pprof: port: 6060 enabled: true addresses: - 0.0.0.0:3000 secure_addresses: [] timeout: 5s force_https: true log: verbose: true schema_version: 100配置文件顶层结构在 internal/next/configmgr/config.go 中定义为dns、http、log、schema_version四个区块其中http.pprof即前文所述可配置端口的能力来源。修改配置后可以放心使用--check-config校验或直接向进程发送SIGHUP触发热重载。从源码看参数解析链路理解本次变更的底层机制只需追踪一条调用链internal/next/cmd/cmd.go 的Main调用parseOptions(cmdName, os.Args[1:])internal/next/cmd/opt.go 的parseOptions基于 Go 标准库flag构造FlagSet遍历commandLineOptions表逐一注册长短参数netip.AddrPort等实现了encoding.TextUnmarshaler的类型走flag.TextVar分支从而获得严格的host:port解析与校验processOptions依次处理--help、--version、--check-config等“即查即退”参数返回是否退出及退出码随后基于opts构建基础日志器internal/next/cmd/log.go必要时切换工作目录并把webAddr等传入配置管理器组装服务internal/next/configmgr/configmgr.go。信号处理部分Main末尾通过service.NewSignalHandler注册信号处理器并将服务管理器同时注册为service.Interface与service.Refresherinternal/next/cmd/cmd.go这正是SIGHUP能触发Refresh全量重载的接线方式。升级与验证建议迁移启动命令凡使用--host/-p/-port的脚本统一改写为--web-addrhost:port不要继续依赖-h绑定地址的旧语义现在-h输出帮助。日志采集被 systemd、supervisord 等托管时可设置--logfilestderr让日志汇入进程的标准错误流便于统一收集。pprof 迁移若旧配置使用debug_pprof: true注意迁移后默认端口为 6060可通过http.pprof.port调整。配置校验与热重载升级后可先用--check-config验证配置合法性此操作不再破坏文件日常变更配合SIGHUP完成无停机重载。版本确认--version与-v的组合顺序不再敏感可放心在脚本中组合使用。以上全部内容均以 internal/next/changelog.md 为骨架并结合仓库中 internal/next/cmd/opt.go、internal/next/cmd/service.go、internal/next/configmgr/config.go、internal/next/configmgr/configmgr.go、internal/next/AdGuardHome.example.yaml 等源码与配置相互印证。由于该变更清单仍处于草案阶段正式版本发布前个别细节可能继续调整请以最终发布说明为准。【免费下载链接】AdGuardHomeNetwork-wide ads trackers blocking DNS server项目地址: https://gitcode.com/gh_mirrors/ad/AdGuardHome创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考