一次自建 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 的证书链」,常见成因有两个:
- 证书文件只含叶子证书,缺少中间 CA(acme.sh 用
--cert-file而非--fullchain-file安装时的经典坑) - 证书本身有问题(过期、自签)
用一条命令区分:
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 天从容处理。
五、复盘
排查层面
- 分层二分,不要猜。一条
curl -v就把问题从「整个网络路径」收敛到「TLS 层」,后续三个 Step 全部可以跳过。 - 不要只信报错文本。
unable to get local issuer certificate直觉上指向链不完整,实际是过期。用openssl x509直接看证书本身,一秒定位。 - 报错信息要看它没说什么。
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 环境
参考
- Tailscale 自定义 DERP 服务器文档:https://tailscale.com/kb/1118/custom-derp-servers
- acme.sh 项目仓库:https://github.com/acmesh-official/acme.sh
- Let's Encrypt 速率限制说明:https://letsencrypt.org/docs/rate-limits/
- 感谢
Claude Opus
浙公网安备 33010602011771号