一次自建 Tailscale DERP 节点的证书故障排查:从「Relay Server Unavailable」到自动化续期闭环

背景

我在家里的 Mac Mini 上自建了一个 Tailscale DERP 中继节点,作为整个 tailnet 在 NAT 打洞失败时的兜底链路。部署形态如下:

  • 运行方式:LaunchDaemon 托管,以 root 常驻
  • 证书模式:-certmode=manual,证书由 acme.sh 从 Let's Encrypt 签发
  • 监听端口:自定义非标端口(家宽入站 80/443 普遍被封)
  • DERP Region:900,自定义区域

某天客户端弹出报错:

Relay Server Unavailable
Code: no-derp-connection
DERP Region ID: 900
DERP Region Name: Home Beijing

这篇文章记录完整的排查路径、真正的根因,以及最后做的加固——这次故障的价值不在于修好证书,而在于暴露了一整条自动化链路上的三个静默失效点。


一、排查方法论:分层二分

面对「连不上」这类问题,最忌讳一上来就猜。有效的做法是沿着数据路径分层验证,每一层都用最小成本的命令做二分:

进程存活 → 本机 TLS → 局域网可达 → 公网可达 → 客户端侧

每一步的结果都能砍掉一半的可能性。下面逐层展开。

Step 1:确认进程与端口

ps aux | grep derper
sudo lsof -iTCP -sTCP:LISTEN -P | grep derper
sudo lsof -iUDP -P | grep 3478

结果:进程健在,已连续运行数周;TCP 自定义端口与 80 端口均在监听;STUN 的 3478/UDP 正常。

这一步排除了「服务挂了」和「开机没自启」两种最常见的原因。

Step 2:本机自测 TLS 端点

curl -v https://derp.example.com:<PORT>/derp/probe

关键输出:

* Connected to derp.example.com (x.x.x.x) port <PORT>
* TLS handshake, Certificate (11):
* SSL certificate problem: unable to get local issuer certificate
curl: (60) SSL certificate problem

信息量很大:

  • TCP 连接成功 → DNS 解析正确、端口转发正常、运营商没封 → 网络层可以整体排除
  • 卡在证书验证 → 问题精确锁定在 TLS 层

后续的 Step 3~5(局域网测试、公网测试、客户端 netcheck)全部可以跳过。这就是分层排查的价值:一条 curl 砍掉了 80% 的排查面积。

Step 3:定位证书问题的具体形态

unable to get local issuer certificate 字面含义是「无法构建到受信任根 CA 的证书链」,常见成因有两个:

  1. 证书文件只含叶子证书,缺少中间 CA(acme.sh 用 --cert-file 而非 --fullchain-file 安装时的经典坑)
  2. 证书本身有问题(过期、自签)

用一条命令区分:

openssl x509 -in derp.example.com.crt -noout -subject -issuer -dates

结果:

subject=CN=derp.example.com
issuer=C=US, O=Let's Encrypt, CN=E8
notBefore=Apr 12 17:20:51 2026 GMT
notAfter=Jul 11 17:20:50 2026 GMT

证书已过期 11 天。 issuer 是 Let's Encrypt,排除自签;链完整性问题也不是主因。

补充:unable to get local issuer certificate 这个报错措辞其实有一定误导性——直觉上会以为是链不完整,但证书过期后 OpenSSL 在某些路径下也会返回这个错误码而非更直白的 certificate has expired。所以不要只看报错文本,一定要用 openssl x509 直接看证书本身。


二、根因不止一层

修复过期证书只需要一条命令。但真正要问的是:为什么会过期?

Let's Encrypt 证书 90 天有效期,acme.sh 默认 60 天自动续期,留有 30 天容错窗口。能一路走到过期,说明自动化链路整体失效了。逐层深挖后发现了三个独立问题。

根因 1:定时任务根本不存在

crontab -l
# crontab: no crontab for user

acme.sh 在安装时如果检测不到可写的 crontab,或安装过程被中断,会跳过 cron 注册且不报错。这是最直接的原因——续期机制压根没被调度过。

根因 2:缺少 reloadcmd,证书更新不会生效

即便续期成功,还有第二个坑:derper 在 -certmode=manual 下会缓存证书,磁盘上的文件被替换,进程不会自动重载。

这意味着一个更隐蔽的失败模式:acme.sh 静默续期成功 → 磁盘上是新证书 → derper 内存里还是旧证书 → 客户端照样连不上 → 排查时看文件却发现证书是新的,陷入困惑。

必须通过 --reloadcmd 在证书安装后重启服务。

根因 3:cron 硬编码了带版本号的路径

后续用 acme.sh --install-cronjob 补装定时任务,生成的条目是:

59 17 * * * /opt/homebrew/Cellar/acme.sh/3.1.2/libexec/acme.sh --cron --home "~/.acme.sh" > /dev/null

Homebrew 的 Cellar 路径带版本号。 等 acme.sh 升级到 3.1.3、brew cleanup 清掉旧目录,这条 cron 就指向一个不存在的文件,每天静默失败——和刚修好的故障是完全相同的失效模式,只是延后了几个月引爆。

acme.sh 用「当前脚本路径」生成 cron,它并不知道自己是被包管理器以版本化路径管理的。


三、修复过程

1. 确认服务的 launchd 标识

因为 reloadcmd 需要重启服务,先拿到准确的 service target:

sudo launchctl list | grep -i derp
# 1618    0    com.tailscale.derper

sudo launchctl print system/com.tailscale.derper | head -20

launchctl print 的输出很有价值,能确认域(system vs gui/$UID)、plist 路径、完整启动参数、日志路径。

2. 理解 launchctl kickstart -k

reloadcmd 里要用的命令是:

sudo launchctl kickstart -k system/com.tailscale.derper

逐段拆解:

部分 含义
kickstart 让服务立即运行。服务已在运行时默认什么都不做
-k 先 SIGKILL 掉当前实例再重启
system/ domain target,对应 /Library/LaunchDaemons/(用户级则是 gui/$UID 或 user/$UID)
com.tailscale.derper plist 中 Label 键的值

-k 不能省。 没有它,kickstart 对运行中的服务直接返回成功、证书不会重载——命令看起来执行成功了,故障却没修好。这类「假成功」是自动化里最难排查的一种。

3. 验证非交互环境下的 sudo

reloadcmd 由 cron/launchd 在非交互环境下执行,sudo 拿不到密码输入会失败。必须提前模拟验证:

sudo -k    # 关键:清除 sudo 凭证缓存,否则测试会假阳性
env -i /bin/sh -c "sudo -n /bin/launchctl kickstart -k system/com.tailscale.derper"

两个细节:

  • sudo -k 不能省。sudo 凭证默认缓存 5 分钟,刚输过密码就测试会得到虚假的成功。
  • 必须用绝对路径。我第一次测试写的是 sudo -n launchctl ...,得到 sudo: launchctl: command not found——env -i 清空了 PATH,sudo 在找到命令之前就退出了,连认证阶段都没走到,等于什么都没验证。这个小插曲反而印证了非交互环境的 PATH 有多窄。

如果提示需要密码,配置最小权限的免密规则:

sudo visudo
<username> ALL=(root) NOPASSWD: /bin/launchctl kickstart -k system/com.tailscale.derper

sudoers 按完整命令行匹配,所以路径和参数要与 reloadcmd 里逐字一致。这样授权范围最小,只能重启这一个服务。

4. 注册安装路径与 reloadcmd

acme.sh --install-cert -d derp.example.com \
  --key-file       /path/to/certs/derp.example.com.key \
  --fullchain-file /path/to/certs/derp.example.com.crt \
  --reloadcmd      "sudo -n /bin/launchctl kickstart -k system/com.tailscale.derper"

要点:

  • 必须用 --fullchain-file 而非 --cert-file。前者含中间 CA,后者只有叶子证书,会导致链不完整。
  • derper 在 manual 模式下按 <hostname>.crt / <hostname>.key 严格匹配文件名。
  • reloadcmd 中的 -n 让 sudo 在权限规则失效时立即报错退出,而不是挂起等待一个永远不会到来的密码输入——失败要响亮,不要静默。
  • --install-cert 只做安装配置,不触发签发。它会把 reloadcmd 写进域名的 .conf,之后每次自动续期都会执行。

5. 强制签发

acme.sh --renew -d derp.example.com --force

--force 是必要的:acme.sh 默认只在剩余有效期不足时续期,证书已过期太久时有可能走进异常分支。

6. 验证

grep -c "BEGIN CERTIFICATE" /path/to/certs/derp.example.com.crt   # 应为 2(叶子 + 中间 CA)
curl -v https://derp.example.com:<PORT>/derp/probe                 # 应返回 200,无 TLS 报错
sudo launchctl list | grep derp                                    # PID 应发生变化,证明 reloadcmd 生效
tailscale netcheck                                                 # Region 900 延迟恢复

PID 变化这一项容易被忽略,但它是唯一能证明 reloadcmd 真正跑通的信号。


四、加固:让它不再复发

修好当下的故障只是及格线。真正要解决的是「静默失效」这个模式本身。

1. 修正 cron 路径

crontab -e
15 3 * * * /opt/homebrew/bin/acme.sh --cron --home /path/to/.acme.sh >> /path/to/.acme.sh/cron.log 2>&1

三处改动:

  • 用 /opt/homebrew/bin/acme.sh 软链替代带版本号的 Cellar 路径。Homebrew 会在升级时自动更新软链指向。
  • 把 > /dev/null 换成日志追加 + 2>&1。这次故障拖了 11 天才被发现,输出丢进黑洞是重要推手。acme.sh 的错误走 stderr,2>&1 不能少。
  • 避开整点。0 0 是默认值,全球大量实例同时打 ACME 端点,存在偶发限流风险。

2. 更可靠的方案:改用 LaunchDaemon

macOS 上 cron 有个硬伤:机器睡眠期间错过的任务不会补跑。launchd 的 StartCalendarInterval 则会在唤醒后补执行。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.example.acme-renew</string>

    <key>UserName</key>
    <string><username></string>

    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/acme.sh</string>
        <string>--cron</string>
        <string>--home</string>
        <string>/path/to/.acme.sh</string>
    </array>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
        <key>HOME</key>
        <string>/path/to/home</string>
    </dict>

    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key><integer>3</integer>
        <key>Minute</key><integer>15</integer>
    </dict>

    <key>StandardOutPath</key>
    <string>/path/to/.acme.sh/renew.log</string>
    <key>StandardErrorPath</key>
    <string>/path/to/.acme.sh/renew.err</string>
</dict>
</plist>

三个关键点:

  • UserName 用普通用户而非 root。acme.sh 装在用户目录下,且 sudoers 免密规则是针对该用户配的,以 root 运行反而会让 reloadcmd 匹配不上规则。
  • 显式设置 PATH 和 HOME。launchd 提供的环境极简,acme.sh 内部调用 openssl、curl 都依赖 PATH。这正是前面 env -i 踩到的坑的同类问题。
  • 日志分离 stdout/stderr,便于排查。

加载与验证:

sudo chown root:wheel /Library/LaunchDaemons/com.example.acme-renew.plist
sudo chmod 644 /Library/LaunchDaemons/com.example.acme-renew.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.acme-renew.plist
sudo launchctl kickstart system/com.example.acme-renew

cron 和 launchd 二选一,不要同时装。 重复执行虽然不会出错(acme.sh 有锁机制),但日志会交错混乱,排查时容易误判。

3. 确认 DNS API 凭证已持久化

如果用 DNS-01 验证(家宽场景下的唯一可靠选择,不依赖任何入站端口,也不受非标端口限制),要确认 API 凭证被写进了配置文件,而不是只存在于你手动 source 的 shell 环境里:

grep -i "SAVED_" ~/.acme.sh/account.conf

cron/launchd 不会执行你的 shell profile,手动 export 的环境变量对它们完全不可见。如果没有 SAVED_* 条目,重新签发一次让 acme.sh 持久化凭证:

source /path/to/export_dns_credentials.sh
acme.sh --issue --dns dns_<provider> -d derp.example.com --force

同时确认 reloadcmd 已写入域名配置:

grep -i "Le_ReloadCmd" ~/.acme.sh/derp.example.com_ecc/derp.example.com.conf

4. macOS 的 TCC 权限

macOS 上 /usr/sbin/cron 若无完全磁盘访问权限,访问某些用户目录下的文件会被 TCC 拦截并报 Operation not permitted。保险做法:系统设置 → 隐私与安全性 → 完全磁盘访问权限,添加 /usr/sbin/cron。

5. 加一层解耦的到期监控

前面所有修复都在优化「续期机制」本身,但自动化最危险的失败模式是静默失败。加一个独立于续期机制的探测:

#!/bin/bash
DAYS=$(( ($(date -j -f "%b %e %T %Y" "$(openssl s_client -connect derp.example.com:<PORT> \
  -servername derp.example.com 2>/dev/null </dev/null | openssl x509 -noout -enddate \
  | cut -d= -f2 | sed 's/ GMT//')" +%s) - $(date +%s)) / 86400 ))

if [ "$DAYS" -lt 20 ]; then
    echo "证书剩余 ${DAYS} 天"
    # 接入通知渠道:Bark / 企业微信机器人 / ntfy 等
fi

设计上有两个刻意的选择:

  • 探测线上服务实际端口,而非读磁盘文件。这样同时覆盖了「没续期」和「续期了但服务没重载」两种故障——后者正是本次踩的坑,读文件是发现不了的。
  • 阈值设 20 天。acme.sh 在 30 天时开始尝试,若掉到 20 天仍未成功,说明续期确实出了问题,而你还有 20 天从容处理。

五、复盘

排查层面

  1. 分层二分,不要猜。一条 curl -v 就把问题从「整个网络路径」收敛到「TLS 层」,后续三个 Step 全部可以跳过。
  2. 不要只信报错文本。unable to get local issuer certificate 直觉上指向链不完整,实际是过期。用 openssl x509 直接看证书本身,一秒定位。
  3. 报错信息要看它没说什么。sudo: launchctl: command not found 表面是路径问题,深层含义是「认证阶段根本没走到,这次测试无效」。

设计层面

这次故障真正的教训不是「证书会过期」,而是一条自动化链路上串联了多个静默失效点:

环节 失效方式 暴露时机
cron 未注册 安装时静默跳过 证书过期后,客户端报错
无 reloadcmd 续期成功但服务不重载 同上,且现象更迷惑
Cellar 硬编码路径 brew 升级后文件消失 几个月后,同样的故障
输出重定向到 /dev/null 所有失败信息丢失 永远不会主动暴露

它们的共同特征是:失败不产生任何信号,直到用户侧感知到服务不可用。 而修复其中一个的过程,又引入了下一个(补装 cron 时带进了 Cellar 路径问题)。

所以最有价值的加固不是把每个环节都修对——那只是把引爆时间推后——而是加一层与实现解耦的、面向结果的监控。它不关心你用的是 cron 还是 launchd、路径对不对、凭证在不在,只关心线上服务实际吐出来的证书还剩几天。

一条通用原则

任何「自动化成功后无输出」的机制,都应该配一个「面向最终结果」的独立探针。前者验证过程,后者验证目的——只有后者才是你真正关心的。


附录:命令速查

# —— 排查 ——
ps aux | grep derper                                    # 进程存活
sudo lsof -iTCP -sTCP:LISTEN -P | grep derper           # 端口监听
curl -v https://derp.example.com:<PORT>/derp/probe      # TLS + 服务探测
openssl x509 -in <cert> -noout -subject -issuer -dates  # 证书详情
grep -c "BEGIN CERTIFICATE" <cert>                      # 链完整性(应为 2)
echo | openssl s_client -connect <host>:<port> -showcerts   # 服务端实际证书链
tailscale netcheck                                      # 客户端侧 DERP 延迟
tailscale debug derp 900                                # 指定 region 探测

# —— launchd ——
sudo launchctl list | grep <keyword>                    # 找 Label
sudo launchctl print system/<label>                     # 服务详情
sudo launchctl kickstart -k system/<label>              # 强制重启
sudo launchctl bootstrap system <plist>                 # 加载新服务

# —— acme.sh ——
acme.sh --install-cert -d <domain> --fullchain-file <path> --key-file <path> --reloadcmd "<cmd>"
acme.sh --renew -d <domain> --force                     # 强制签发
acme.sh --cron --home <dir>                             # 模拟定时执行
grep -i "SAVED_" ~/.acme.sh/account.conf                # 检查 API 凭证持久化
grep -i "Le_ReloadCmd" ~/.acme.sh/<domain>_ecc/<domain>.conf   # 检查 reloadcmd

# —— 非交互环境验证 ——
sudo -k && env -i /bin/sh -c "sudo -n /abs/path/cmd"    # 模拟 cron 环境

参考

posted @ 2026-07-22 02:07  That's_it  阅读(79)  评论(0)    收藏  举报