Headscale 配置迁移指南：Tailscale 控制服务器 8 个弃用参数一次改对-育师

Headscale 配置迁移指南：Tailscale 控制服务器 8 个弃用参数一次改对

【免费下载链接】headscaleAn open source, self-hosted implementation of the Tailscale control server项目地址: https://gitcode.com/GitHub_Trending/he/headscale

你升级了自托管的 Headscale（开源自托管的 Tailscale 控制服务器），启动日志里冒出一串 deprecation 警告？这篇 Headscale 配置迁移指南列出 8 组旧参数与新参数的完整对照表，外加一份 4 步迁移清单，照着改完，警告就能一次清零。

升级后启动日志里的 deprecation 警告说明什么

把 Headscale 的版本升上去，重启服务，日志里开始刷 "The xxx configuration key is deprecated"。先说结论：这不是报错，是项目方在催你换掉一批老参数名。Headscale 把config.yaml重新整理成了层级结构，原来平铺的 key 被归到了dns、policy这类命名空间下。

从当前版本的代码看，迁移规则其实很硬：

旧 key 和新 key 你都写了：打印警告，以新 key 为准；
只写了旧 key：直接 fatal，服务起不来，日志会告诉你该用哪个新名字；
少数参数已经被彻底删掉，写在配置里同样启动失败。

所以这些警告不是可以无视的"黄牌"，它更像搬家的门牌通知：房子没变，地址换了，按新地址走就行。下面按模块把 8 组改名一次讲完。

路径类参数迁移：acl_policy_path 改写成 policy.path

这组只有一个参数。策略文件的指向原来叫acl_policy_path，现在统一挂到policy命名空间下，和policy.mode（策略来源是文件还是数据库）归到一起管理。

旧参数	新参数	一句话说明
`acl_policy_path`	`policy.path`	ACL 策略文件的路径，位置没变，只是 key 换了名

改的时候注意：只把 key 改名，文件路径本身原样保留。

DNS 参数怎么批量替换：7 项 dns_config 改名对照

原来一整块dns_config被拆成dns命名空间，层级更清楚：全局解析器、分域（split）解析器、搜索域各自独立成项，不会互相串味。批量替换的思路很简单：把dns_config.前缀换成dns.，再按下表核对。

旧参数	新参数	一句话说明
`dns_config.magic_dns`	`dns.magic_dns`	是否启用 MagicDNS，按主机名访问节点
`dns_config.base_domain`	`dns.base_domain`	MagicDNS 的基础域名，节点名就挂在它下面
`dns_config.override_local_dns`	`dns.override_local_dns`	是否用 tailscale 的解析器接管系统 DNS
`dns_config.nameservers`	`dns.nameservers.global`	全局 DNS 解析器列表
`dns_config.restricted_nameservers`	`dns.nameservers.split`	按域名分流的解析器，结构是"域名 → 解析器列表"
`dns_config.domains`	`dns.search_domains`	搜索域列表
`dns_config.extra_records`	`dns.extra_records`	额外 DNS 记录（A、AAAA、TXT 等）

有两个点值得多看一眼。第一，dns.nameservers.split的值是一个"域名 → 解析器"的映射，不是简单的一维列表，迁移时保持原来的映射结构别拍扁。第二，dns.extra_records和dns.extra_records_path（从文件加载额外记录）互斥，同时写会直接报配置错误，二选一即可。