feat(tailscale): improve derp startup diagnostics

Author: mudssky

config/network/tailscale/derp/.env.example

@@ -1,5 +1,16 @@
 # 构建与镜像版本。启用 --verify-clients 时，建议这里和 tailscaled 使用同一版本线。
 TAILSCALE_VERSION=latest
+GO_BUILD_IMAGE=golang:1.26-alpine
+
+# 可选：Alpine 包管理镜像源。若 `apk add` 很慢，可改成你本地更快的镜像，例如
+# https://mirrors.aliyun.com/alpine 或 https://mirrors.tuna.tsinghua.edu.cn/alpine
+ALPINE_MIRROR=https://dl-cdn.alpinelinux.org/alpine
+
+# 可选：Go 模块下载代理。若构建阶段访问 proxy.golang.org 超时，可改成你本地可达的镜像。
+# GOPROXY=https://proxy.golang.org,direct
+# GOSUMDB=sum.golang.org
+GOPROXY=https://goproxy.cn,direct
+GOSUMDB=sum.golang.google.cn
 
 # 必填：DERP 对外公布的公网 IP。manual cert 模式会以它作为证书主机名与 certdir 文件名。
 DERP_PUBLIC_IP=
@@ -15,7 +26,8 @@ TS_EXTRA_ARGS=--accept-routes=false --accept-dns=false
 
 # DERP / STUN 监听端口。derper 使用 host network，因此这些端口需要直接在宿主机防火墙放行。
 DERP_PORT=443
-DERP_HTTP_PORT=80
+# IP-only + manual cert 路线，不依赖 80/tcp 做 ACME，先直接关掉
+DERP_HTTP_PORT=-1
 DERP_STUN_PORT=3478
 
 # 可选：证书目录。若目录中不存在 <DERP_PUBLIC_IP>.crt/.key，derper 会自动生成自签 IP 证书。

config/network/tailscale/derp/.gitignore

@@ -0,0 +1 @@
+certs/

config/network/tailscale/derp/Dockerfile.derper

@@ -1,8 +1,18 @@
-# 通过构建时版本参数把 derper 固定到明确的 Tailscale 版本，方便和 tailscaled 对齐。
-FROM golang:1.24-alpine AS build
+ARG GO_BUILD_IMAGE=golang:1.26-alpine
+FROM ${GO_BUILD_IMAGE} AS build
 
+# 通过构建时版本参数把 derper 固定到明确的 Tailscale 版本，方便和 tailscaled 对齐。
+ARG ALPINE_MIRROR=https://dl-cdn.alpinelinux.org/alpine
 ARG TAILSCALE_VERSION=latest
+ARG GOPROXY=https://proxy.golang.org,direct
+ARG GOSUMDB=sum.golang.org
+
+# 通过 build args 暴露 Go 模块下载配置，便于在 proxy.golang.org 不可达时切换镜像站。
+ENV GOPROXY=${GOPROXY}
+ENV GOSUMDB=${GOSUMDB}
 
+# 只替换镜像源域名，保留基础镜像自带的 Alpine 版本路径，避免把 3.x 仓库误切到其它发行线。
+RUN sed -i "s#https\?://dl-cdn.alpinelinux.org/alpine#${ALPINE_MIRROR}#g" /etc/apk/repositories
 RUN apk add --no-cache git
 RUN go install tailscale.com/cmd/derper@${TAILSCALE_VERSION}
 

config/network/tailscale/derp/README.md

@@ -39,6 +39,22 @@ cp config/network/tailscale/derp/.env.example config/network/tailscale/derp/.env
 - `DERP_PUBLIC_IP`
 - `TS_AUTHKEY`
 
+如果你在当前网络里构建 `Dockerfile.derper` 时访问 `proxy.golang.org` 超时，还建议一起补上：
+
+- `GO_BUILD_IMAGE`
+- `ALPINE_MIRROR`
+- `GOPROXY`
+- `GOSUMDB`
+
+例如：
+
+```dotenv
+GO_BUILD_IMAGE=golang:1.26-alpine
+ALPINE_MIRROR=https://mirrors.aliyun.com/alpine
+GOPROXY=https://goproxy.cn,direct
+GOSUMDB=sum.golang.google.cn
+```
+
 3. 确认宿主机防火墙已放行：
 
 - `TCP 80`
@@ -71,13 +87,62 @@ docker compose --env-file config/network/tailscale/derp/.env.local -f config/net
 
 ```powershell
 ./config/network/tailscale/derp/start.ps1
+./config/network/tailscale/derp/start.ps1 build --no-cache
 ./config/network/tailscale/derp/start.ps1 logs --tail 100
 ./config/network/tailscale/derp/start.ps1 ps
 ./config/network/tailscale/derp/start.ps1 pull
 ./config/network/tailscale/derp/start.ps1 config
 ./config/network/tailscale/derp/start.ps1 -DryRun
 ```
 
+## 构建阶段网络说明
+
+`Dockerfile.derper` 会在构建阶段执行：
+
+```text
+go install tailscale.com/cmd/derper@<version>
+```
+
+如果你看到类似下面的错误：
+
+```text
+Get "https://proxy.golang.org/...": dial tcp ...:443: i/o timeout
+```
+
+通常不是 `derper` 本身坏了，而是当前容器网络访问 Go 模块代理超时。此时优先调整：
+
+- `GO_BUILD_IMAGE`
+- `ALPINE_MIRROR`
+- `GOPROXY`
+- `GOSUMDB`
+
+模板已经把这些值透传到 build args，无需再改 Dockerfile。
+
+如果你卡在的是：
+
+```text
+RUN apk add --no-cache git
+```
+
+通常说明 Alpine 包镜像访问慢或不稳定。此时优先把 `ALPINE_MIRROR` 改成你本地更快的镜像，例如：
+
+```dotenv
+ALPINE_MIRROR=https://mirrors.aliyun.com/alpine
+```
+
+如果你看到类似下面的错误：
+
+```text
+requires go >= 1.26.1 (running go 1.24.x)
+```
+
+说明 `derper@latest` 的最低 Go 版本已经高于当前 builder。此时优先把 `GO_BUILD_IMAGE` 提升到
+更高版本，例如：
+
+```dotenv
+GO_BUILD_IMAGE=golang:1.26-alpine
+```
+
 ## 证书行为
 
 默认 `DERP_CERTS_DIR=./certs`。第一轮启动时：
@@ -124,10 +189,146 @@ DERP_PUBLIC_IP=203.0.113.10 TS_AUTHKEY=tskey-example docker compose -f config/ne
 
 客户端侧排查：
 
+- `tailscale status`
 - `tailscale netcheck`
 - `tailscale ping <另一台设备>`
 - `tailscale debug derp`
 
+## 排查与常见故障
+
+### 1. 先确认 DERP 容器本身是否正常
+
+```powershell
+./config/network/tailscale/derp/start.ps1 ps
+./config/network/tailscale/derp/start.ps1 logs --tail 200
+```
+
+正常时至少应满足：
+
+- `tailscaled-auth` 与 `derper` 都是 `Up`
+- `derper` 日志里没有 `tailscaled.sock`、`verify-clients`、证书加载相关 fatal 错误
+
+### 2. 再确认客户端是否已经收到新的 DERP 配置
+
+```bash
+tailscale status
+tailscale netcheck
+```
+
+重点看：
+
+- 客户端是否在线、目标设备是否在线
+- `tailscale netcheck` 里是否能看到你的自定义 DERP region
+
+如果这里完全看不到你的自定义 DERP，优先检查：
+
+- tailnet policy 是否真的保存成功
+- `HostName` / `DERPPort` / `STUNPort` 是否和容器配置一致
+- 宿主机 `TCP 80`、`TCP 443`、`UDP 3478` 是否放行
+
+### 3. `tailscale ping` 为什么在加了 DERP 配置后反而超时
+
+像下面这种：
+
+```text
+tailscale ping macmini
+ping "100.x.x.x" timed out
+```
+
+最常见不是“DERP 配上了但没被用”，而是“客户端现在需要走中继，但可用中继不可达”。
+
+优先怀疑这几类问题：
+
+1. `OmitDefaultRegions: true`
+   影响：你把官方 DERP fallback 关掉了，但自建 DERP 还没完全可用
+   建议：在正式验证通过前，先保持 `OmitDefaultRegions: false`
+2. `HostName` / `DERP_PUBLIC_IP` / 证书主机名不一致
+   影响：客户端看到 DERP 节点，但 TLS 校验或节点匹配失败
+3. `InsecureForTests` 缺失或被改掉
+   影响：IP-only + 自签证书路线下，客户端不会信任这个 DERP
+4. `tailscaled-auth` 在 ACL 中看不到要使用 DERP 的客户端
+   影响：`--verify-clients` 会拒绝这些连接
+5. 自建 DERP 端口没放行
+   影响：客户端无法连上 `443/tcp` 或 `3478/udp`
+
+### 4. 怎么快速判断是不是 DERP 故障
+
+按这个顺序最省时间：
+
+```bash
+tailscale status
+tailscale netcheck
+tailscale ping <另一台设备>
+tailscale debug derp
+```
+
+辅助看 server 侧：
+
+```powershell
+./config/network/tailscale/derp/start.ps1 logs --tail 200
+```
+
+经验判断：
+
+- `tailscale ping` 直连成功
+  说明当前不需要 DERP，不能说明 DERP 配错
+- `tailscale ping` 显示 `via DERP`
+  说明当前正在走中继
+- `tailscale ping` 持续 timeout
+  说明这次连接既没直连成功，也没通过可用 DERP 建立中继
+
+### 5. 关于 `No home relay server`
+
+如果客户端日志或诊断里出现：
+
+```text
+No home relay server
+```
+
+它通常意味着客户端当前没有可用 DERP 可选。这个场景最值得先查：
+
+- `OmitDefaultRegions` 是否过早设成 `true`
+- 自建 DERP 是否真的可达
+- policy 是否下发到客户端
+
+### 6. 推荐上线顺序
+
+为了避免“刚加 DERP 就把联通性打断”，推荐顺序是：
+
+1. 先保持 `OmitDefaultRegions: false`
+2. 先确认 `tailscale netcheck` 能看到你的自定义 DERP
+3. 再观察 `tailscale ping` 是否能在需要时 `via DERP`
+4. 最后如果你确实想强制只用自建 DERP，再把 `OmitDefaultRegions` 切到 `true`
+
+### 7. 当前日志里最常见的两类硬故障
+
+如果你看到 `derper` 容器反复重启，并且日志里有：
+
+```text
+listen tcp :80: bind: address already in use
+```
+
+说明不是 DERP 协议本身坏了，而是宿主机 `80/tcp` 已经被别的服务占用。对当前这套
+IP-only + manual cert 模板来说，最简单的处理是：
+
+- 如果你不需要 `80/tcp`，把 `.env.local` 里的 `DERP_HTTP_PORT` 改成 `-1`
+- 或者把占用 `80/tcp` 的现有服务停掉
+
+如果你看到 `tailscaled-auth` 日志里有：
+
+```text
+invalid key: unable to validate API key
+```
+
+说明当前 `TS_AUTHKEY` 无效、过期，或者填错了。这会导致 `tailscaled-auth` 无法成功加入
+tailnet，`--verify-clients` 也就失去作用。处理方式是：
+
+- 在 Tailscale Admin 里重新生成一个可用的 auth key
+- 更新 `.env.local` 里的 `TS_AUTHKEY`
+- 重新执行 `./config/network/tailscale/derp/start.ps1 up`
+
+如果改了 key 之后依旧反复重启，再考虑清理当前 compose 的 state volume 后重启。
+
 ## 注意事项
 
 - `--verify-clients` 只能限制到 tailnet 级，不能进一步细分“同 tailnet 内哪些设备允许走这个 DERP”

config/network/tailscale/derp/compose.yaml

@@ -23,7 +23,11 @@ services:
       context: .
       dockerfile: Dockerfile.derper
       args:
+        GO_BUILD_IMAGE: ${GO_BUILD_IMAGE:-golang:1.26-alpine}
+        ALPINE_MIRROR: ${ALPINE_MIRROR:-https://dl-cdn.alpinelinux.org/alpine}
         TAILSCALE_VERSION: ${TAILSCALE_VERSION:-latest}
+        GOPROXY: ${GOPROXY:-https://proxy.golang.org,direct}
+        GOSUMDB: ${GOSUMDB:-sum.golang.org}
     restart: unless-stopped
     depends_on:
       - tailscaled-auth