Headscale 配置迁移避坑指南8 个废弃参数完整对照3 步完成升级【免费下载链接】headscaleAn open source, self-hosted implementation of the Tailscale control server项目地址: https://gitcode.com/GitHub_Trending/he/headscaleHeadscale 是一个开源的自托管 Tailscale 控制服务器让你不依赖官方云也能搭自己的私有 mesh 网络。如果你正从 0.26 之前的老版本升级上来这次 Headscale 配置迁移会碰到一批被移除的旧参数下面这份清单能帮你少踩三个坑。为什么团队要重构这些配置老版本的配置是一锅扁平的键值dns_config.xxx、acl_policy_path、randomize_client_port全堆在顶层命名互相不挨着也容易写错。团队干脆按功能归组重排成dns.*、policy.*、node.*配置文件和代码结构对齐新增选项也有地方放。另一头是清垃圾像用户名进 Magic DNS 域名、OIDC 剥邮箱域名这类已经没人用的开关直接连根拔起。说白了新结构更清楚死参数直接删不留兼容包袱。Headscale 配置迁移新旧参数对照清单DNS 模块是重灾区7 个参数整体从dns_config.*搬进dns.*分组dns_config.magic_dns→dns.magic_dns开关类参数跟随分组改名dns_config.base_domain→dns.base_domaindns_config.override_local_dns→dns.override_local_dnsdns_config.nameservers→dns.nameservers.global拆出 global/split 两个子组全局解析器和按域名切分的解析器不再混在一个列表里dns_config.restricted_nameservers→dns.nameservers.split同理分割 DNS 从此有明确的家dns_config.domains→dns.search_domains新名字直接说清它是搜索域dns_config.extra_records→dns.extra_records注意它和dns.extra_records_path互斥二选一策略模块只改一个参数一句话带过acl_policy_path→policy.path和policy.modefile/database同组策略现在支持两种存储模式层级放深一层正好表达这点详见 官方策略文档。节点生命周期oidc.expiry彻底移除统一为node.expiry节点过期不再是 OIDC 专属逻辑所有认证方式共用一套过期规则ephemeral_node_inactivity_timeout→node.ephemeral.inactivity_timeout旧键暂时还能用但只会打警告下一版就没了。被删掉、没有配置替代的dns.use_username_in_magic_dns和oidc.strip_email_domain0.26.0 起移除直接从配置里删掉即可randomize_client_port在 0.29.0 起搬进了策略文件——在策略 JSON 顶层加randomizeClientPort: true不写在 config.yaml 里。3 步完成配置迁移并验证先备份cp config.yaml config.yaml.bak多一层保险不亏。对照上面清单把旧键逐个替换并删掉旧行——光加新键不行旧键还挂着轻则警告、重则起不来。用headscale configtest跑一遍校验通过后systemctl restart headscale收尾官方配置参考 里每个新键都有说明可对照。最容易翻车的 3 个地方⚠️ 旧参数不会静默兜底。只设旧键不设新键时服务直接拒启动日志会点名那个键新旧都设才只是警告所以替换完记得删旧行。⚠️dns.override_local_dns设为true时必须同时给非空的dns.nameservers.global否则直接 fatal——这是改完配置起不来的头号原因。⚠️randomize_client_port已经不归配置文件管了只改 config.yaml 等于功能悄悄失效它必须写进策略文件。迁移本质就是改名字 删死参数现有节点连接和预授权密钥都不受影响。改完记得systemctl restart headscale五分钟收工。【免费下载链接】headscaleAn open source, self-hosted implementation of the Tailscale control server项目地址: https://gitcode.com/GitHub_Trending/he/headscale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Headscale 配置迁移避坑指南：8 个废弃参数完整对照，3 步完成升级
Headscale 配置迁移避坑指南8 个废弃参数完整对照3 步完成升级【免费下载链接】headscaleAn open source, self-hosted implementation of the Tailscale control server项目地址: https://gitcode.com/GitHub_Trending/he/headscaleHeadscale 是一个开源的自托管 Tailscale 控制服务器让你不依赖官方云也能搭自己的私有 mesh 网络。如果你正从 0.26 之前的老版本升级上来这次 Headscale 配置迁移会碰到一批被移除的旧参数下面这份清单能帮你少踩三个坑。为什么团队要重构这些配置老版本的配置是一锅扁平的键值dns_config.xxx、acl_policy_path、randomize_client_port全堆在顶层命名互相不挨着也容易写错。团队干脆按功能归组重排成dns.*、policy.*、node.*配置文件和代码结构对齐新增选项也有地方放。另一头是清垃圾像用户名进 Magic DNS 域名、OIDC 剥邮箱域名这类已经没人用的开关直接连根拔起。说白了新结构更清楚死参数直接删不留兼容包袱。Headscale 配置迁移新旧参数对照清单DNS 模块是重灾区7 个参数整体从dns_config.*搬进dns.*分组dns_config.magic_dns→dns.magic_dns开关类参数跟随分组改名dns_config.base_domain→dns.base_domaindns_config.override_local_dns→dns.override_local_dnsdns_config.nameservers→dns.nameservers.global拆出 global/split 两个子组全局解析器和按域名切分的解析器不再混在一个列表里dns_config.restricted_nameservers→dns.nameservers.split同理分割 DNS 从此有明确的家dns_config.domains→dns.search_domains新名字直接说清它是搜索域dns_config.extra_records→dns.extra_records注意它和dns.extra_records_path互斥二选一策略模块只改一个参数一句话带过acl_policy_path→policy.path和policy.modefile/database同组策略现在支持两种存储模式层级放深一层正好表达这点详见 官方策略文档。节点生命周期oidc.expiry彻底移除统一为node.expiry节点过期不再是 OIDC 专属逻辑所有认证方式共用一套过期规则ephemeral_node_inactivity_timeout→node.ephemeral.inactivity_timeout旧键暂时还能用但只会打警告下一版就没了。被删掉、没有配置替代的dns.use_username_in_magic_dns和oidc.strip_email_domain0.26.0 起移除直接从配置里删掉即可randomize_client_port在 0.29.0 起搬进了策略文件——在策略 JSON 顶层加randomizeClientPort: true不写在 config.yaml 里。3 步完成配置迁移并验证先备份cp config.yaml config.yaml.bak多一层保险不亏。对照上面清单把旧键逐个替换并删掉旧行——光加新键不行旧键还挂着轻则警告、重则起不来。用headscale configtest跑一遍校验通过后systemctl restart headscale收尾官方配置参考 里每个新键都有说明可对照。最容易翻车的 3 个地方⚠️ 旧参数不会静默兜底。只设旧键不设新键时服务直接拒启动日志会点名那个键新旧都设才只是警告所以替换完记得删旧行。⚠️dns.override_local_dns设为true时必须同时给非空的dns.nameservers.global否则直接 fatal——这是改完配置起不来的头号原因。⚠️randomize_client_port已经不归配置文件管了只改 config.yaml 等于功能悄悄失效它必须写进策略文件。迁移本质就是改名字 删死参数现有节点连接和预授权密钥都不受影响。改完记得systemctl restart headscale五分钟收工。【免费下载链接】headscaleAn open source, self-hosted implementation of the Tailscale control server项目地址: https://gitcode.com/GitHub_Trending/he/headscale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考