EasyTier Supervisor 部署

生产变更复盘 - 这篇文章属于一个选集。

8: 本文

这是一套 EasyTier 私有组网的部署 runbook：公网共享节点负责发现和中转，HK/US 两台客户端通过固定虚拟 IP 加入同一网络，进程交给 Supervisor 托管，并启用 KCP / QUIC Proxy 改善跨区域 TCP 连接体验。

文中使用 203.0.113.10、10.144.66.0/24、et-private-net、CHANGE_ME_NETWORK_SECRET 作为示例值。落地前替换成自己的公网地址、虚拟网段、网络名和密钥；已经出现在聊天、工单或 Git 里的 network-secret 需要重新生成。

0. 结论和使用边界
#

这份记录适合已经拿到 EasyTier Linux 二进制、希望用一台公网机器做私有共享节点的场景。可复用的是部署顺序、Supervisor 配置、验证矩阵、继续/停止条件和回滚路径；不能直接照抄的是公网地址、虚拟网段、主机名和密钥。

项	示例配置
组件	EasyTier CLI / `easytier-core`
进程管理	Supervisor
共享节点	`public-share`，公网地址 `203.0.113.10`
共享节点端口	`23451/tcp`、`23451/udp`
共享节点模式	`--private-mode true`，只允许同网络名和同密钥节点接入
HK 客户端	`hk-client`，虚拟 IP `10.144.66.3`
US 客户端	`us-client`，虚拟 IP `10.144.66.6`
客户端模式	固定虚拟 IP，主动连接共享节点，`--no-listener` 不监听本地端口
传输优化	`--enable-kcp-proxy`、`--enable-quic-proxy`、`--use-smoltcp`

风险边界也要明确：

network-secret 一旦暴露，就按已失效处理，生成新密钥并全网同步替换。
共享节点不配置 -i/--ipv4，主要承担发现、握手和转发；客户端才配置固定虚拟 IP。
本文的 Supervisor 配置使用 user=root，目标是稳定创建 TUN 设备和虚拟 IP，不是 no-root 部署。
KCP / QUIC Proxy 需要有虚拟网内 TCP 连接才会出现活跃记录，不能只看进程状态判断是否生效。

1. 拓扑和流量路径
#

先把角色关系说清楚，后面的命令才有落点。共享节点只负责接入和中转，HK/US 客户端通过同一个 network-name 和 network-secret 进入同一个虚拟网络。

flowchart LR
    hk["hk-client
10.144.66.3"] -->|TCP/UDP 23451| share["public-share
203.0.113.10"]
    us["us-client
10.144.66.6"] -->|TCP/UDP 23451| share
    hk <-->|Virtual Network
10.144.66.0/24| us

客户端启动后主动连接共享节点：

-p tcp://203.0.113.10:23451 用作初始 peer。
-e tcp://203.0.113.10:23451 用作外部发现节点。
--no-listener 让客户端不在本机开放 EasyTier 监听端口。
--hostname 用于在 EasyTier 节点列表和日志里区分客户端。

2. Review Gate
#

上线前先过一遍 Review Gate。这里的目标不是证明链路一定稳定，而是避免把明显不可用或不可回滚的配置推到线上。

检查项	方法	通过标准
二进制存在	`test -x /root/easytier-linux-x86_64/easytier-core`	命令退出码为 0
CLI 存在	`test -x /root/easytier-linux-x86_64/easytier-cli`	命令退出码为 0
版本可见	`/root/easytier-linux-x86_64/easytier-core --version`	输出版本号
端口规划	检查安全组、防火墙、现有监听	`23451/tcp` 和 `23451/udp` 未被占用并允许访问
虚拟 IP 规划	检查现有 EasyTier 节点和路由	`10.144.66.3`、`10.144.66.6` 未冲突
密钥状态	检查聊天记录、工单、Git diff	没有继续使用已暴露密钥
回滚点	备份 `/etc/supervisor/conf.d/easytier-*.conf`	能恢复原 Supervisor 配置

准备命令：

test -x /root/easytier-linux-x86_64/easytier-core
test -x /root/easytier-linux-x86_64/easytier-cli
/root/easytier-linux-x86_64/easytier-core --version
/root/easytier-linux-x86_64/easytier-cli --version

如果希望目录更规范，可以把二进制放到 /opt/easytier/。路径迁移要单独做，不要一边移动文件一边上线；先确认新路径能执行，再同步替换 Supervisor 的 command。

3. 生成和替换网络密钥
#

不要复用已经暴露过的 network-secret。生成新密钥：

openssl rand -base64 32 | tr -d '=+/' | cut -c1-32

后续示例统一使用：

network-name: et-private-net
network-secret: CHANGE_ME_NETWORK_SECRET
public-server: 203.0.113.10
listen-port: 23451

network-name 和 network-secret 必须在共享节点和所有客户端上保持一致。密钥只放在 root 可读的部署文件里，不写入公开文章、工单、聊天记录或仓库。

4. 分阶段部署策略
#

这类组网变更适合按节点推进。共享节点先启动，确认 TCP/UDP 监听正常，再接入第一个客户端，随后接入第二个客户端并验证互通。

阶段	可以继续的条件	应该停止的信号
启动共享节点	`supervisorctl status easytier-share` 为 `RUNNING`，`23451/tcp` 和 `23451/udp` 都在监听	进程反复退出、端口未监听、日志出现密钥或监听地址错误
接入 HK 客户端	`easytier-hk-client` 为 `RUNNING`，客户端日志出现连接共享节点的记录	客户端无法连到 `203.0.113.10:23451`，或虚拟 IP 未创建
接入 US 客户端	`easytier-us-client` 为 `RUNNING`，HK/US 虚拟 IP 互通	IP 冲突、ping 不通、日志提示 network-name/secret 不一致
验证 KCP/QUIC	产生 SSH/HTTP 等虚拟网内 TCP 流量后，`easytier-cli proxy` 能看到代理记录	只有进程状态正常但无代理记录，或业务 TCP 连接失败
固化配置	Supervisor 配置权限为 `600`，备份已生成	配置里仍有真实密钥、真实公网地址或错误主机名

5. 公网共享节点
#

共享节点需要公网可达，并开放 TCP/UDP 23451。如果服务器同时有 IPv4 和 IPv6，可以监听两类地址：

/root/easytier-linux-x86_64/easytier-core \
  --private-mode true \
  --network-name et-private-net \
  --network-secret CHANGE_ME_NETWORK_SECRET \
  -l 'tcp://[::]:23451' \
  -l 'udp://[::]:23451' \
  -l 'tcp://0.0.0.0:23451' \
  -l 'udp://0.0.0.0:23451' \
  --multi-thread \
  --use-smoltcp \
  --file-log-level off \
  --enable-kcp-proxy \
  --enable-quic-proxy

如果机器没有 IPv6，去掉 [::] 两行即可。

检查监听：

ss -lntup | grep ':23451'
ss -lnuap | grep ':23451'

UFW 环境放行端口：

ufw allow 23451/tcp
ufw allow 23451/udp

不用 UFW 的环境按自己的防火墙或云安全组放行同样的 TCP/UDP 端口。

6. 客户端连接共享节点
#

客户端主动连接公网共享节点，不监听本地端口。HK 客户端：

/root/easytier-linux-x86_64/easytier-core \
  --network-name et-private-net \
  --network-secret CHANGE_ME_NETWORK_SECRET \
  -i 10.144.66.3 \
  -p tcp://203.0.113.10:23451 \
  -e tcp://203.0.113.10:23451 \
  --no-listener \
  --hostname "$(hostname -s)" \
  --multi-thread \
  --use-smoltcp \
  --file-log-level off \
  --bind-device false \
  --enable-kcp-proxy \
  --enable-quic-proxy

US 客户端只换虚拟 IP：

/root/easytier-linux-x86_64/easytier-core \
  --network-name et-private-net \
  --network-secret CHANGE_ME_NETWORK_SECRET \
  -i 10.144.66.6 \
  -p tcp://203.0.113.10:23451 \
  -e tcp://203.0.113.10:23451 \
  --no-listener \
  --hostname "$(hostname -s)" \
  --multi-thread \
  --use-smoltcp \
  --file-log-level off \
  --bind-device false \
  --enable-kcp-proxy \
  --enable-quic-proxy

参数含义：

参数	作用
`--network-name`	虚拟网络名称，同一网络必须一致
`--network-secret`	网络密钥，同一网络必须一致
`-i`	当前节点虚拟 IP
`-p` / `--peers`	初始连接的 peer
`-e` / `--external-node`	用作发现的共享节点
`--no-listener`	客户端不监听端口，只主动连接
`--bind-device false`	不把连接 socket 固定到物理网卡
`--use-smoltcp`	为 KCP Proxy / 子网代理启用用户态网络栈
`--enable-kcp-proxy`	将虚拟网内 TCP 流量代理为 KCP，改善丢包链路
`--enable-quic-proxy`	启用 QUIC Proxy；KCP 和 QUIC 同开时通常优先看到 KCP

7. Supervisor 托管
#

示例按 Debian / Ubuntu 的 /etc/supervisor/conf.d/ 编写。RHEL / CentOS 常见目录是 /etc/supervisord.d/，路径不同但配置思路相同。

安装 Supervisor：

apt update
apt install -y supervisor
systemctl enable --now supervisor

7.1 共享节点配置
#

cat > /etc/supervisor/conf.d/easytier-share.conf <<'EOF'
[program:easytier-share]
command=/root/easytier-linux-x86_64/easytier-core --private-mode true --network-name et-private-net --network-secret CHANGE_ME_NETWORK_SECRET -l tcp://[::]:23451 -l udp://[::]:23451 -l tcp://0.0.0.0:23451 -l udp://0.0.0.0:23451 --multi-thread --use-smoltcp --file-log-level off --enable-kcp-proxy --enable-quic-proxy
directory=/root
autostart=true
autorestart=true
startsecs=5
startretries=3
stopsignal=TERM
stopasgroup=true
killasgroup=true
user=root
redirect_stderr=true
stdout_logfile=/var/log/supervisor/easytier-share.log
stdout_logfile_maxbytes=5MB
stdout_logfile_backups=1
EOF
chmod 600 /etc/supervisor/conf.d/easytier-share.conf

加载配置：

supervisorctl reread
supervisorctl update
supervisorctl status easytier-share

7.2 HK 客户端配置
#

Supervisor 的 command 默认不是 shell，$(hostname) 不会自动展开。客户端如果要动态使用当前主机名，需要显式通过 /bin/sh -lc 包一层。

cat > /etc/supervisor/conf.d/easytier-hk-client.conf <<'EOF'
[program:easytier-hk-client]
command=/bin/sh -lc 'exec /root/easytier-linux-x86_64/easytier-core --network-name et-private-net --network-secret CHANGE_ME_NETWORK_SECRET -i 10.144.66.3 -p tcp://203.0.113.10:23451 -e tcp://203.0.113.10:23451 --no-listener --hostname "$(hostname -s)" --multi-thread --use-smoltcp --file-log-level off --bind-device false --enable-kcp-proxy --enable-quic-proxy'
directory=/root
autostart=true
autorestart=true
startsecs=5
startretries=3
stopsignal=TERM
stopasgroup=true
killasgroup=true
user=root
redirect_stderr=true
stdout_logfile=/var/log/supervisor/easytier-hk-client.log
stdout_logfile_maxbytes=5MB
stdout_logfile_backups=1
EOF
chmod 600 /etc/supervisor/conf.d/easytier-hk-client.conf

加载配置：

supervisorctl reread
supervisorctl update
supervisorctl status easytier-hk-client

7.3 US 客户端配置
#

cat > /etc/supervisor/conf.d/easytier-us-client.conf <<'EOF'
[program:easytier-us-client]
command=/bin/sh -lc 'exec /root/easytier-linux-x86_64/easytier-core --network-name et-private-net --network-secret CHANGE_ME_NETWORK_SECRET -i 10.144.66.6 -p tcp://203.0.113.10:23451 -e tcp://203.0.113.10:23451 --no-listener --hostname "$(hostname -s)" --multi-thread --use-smoltcp --file-log-level off --bind-device false --enable-kcp-proxy --enable-quic-proxy'
directory=/root
autostart=true
autorestart=true
startsecs=5
startretries=3
stopsignal=TERM
stopasgroup=true
killasgroup=true
user=root
redirect_stderr=true
stdout_logfile=/var/log/supervisor/easytier-us-client.log
stdout_logfile_maxbytes=5MB
stdout_logfile_backups=1
EOF
chmod 600 /etc/supervisor/conf.d/easytier-us-client.conf

加载配置：

supervisorctl reread
supervisorctl update
supervisorctl status easytier-us-client

8. 验证矩阵
#

部署后按共享节点、客户端、虚拟网互通、代理通道四层验证。不要只看 Supervisor RUNNING，进程存活不等于组网成功。

验证项	方法	通过标准
共享节点进程	`supervisorctl status easytier-share`	状态为 `RUNNING`
TCP 监听	`ss -lntup` 后过滤 `:23451`	能看到 `23451/tcp` 监听
UDP 监听	`ss -lnuap` 后过滤 `:23451`	能看到 `23451/udp` 监听
共享节点日志	`tail -n 100 /var/log/supervisor/easytier-share.log`	无反复退出、密钥错误、监听失败
HK 客户端进程	`supervisorctl status easytier-hk-client`	状态为 `RUNNING`
US 客户端进程	`supervisorctl status easytier-us-client`	状态为 `RUNNING`
虚拟 IP	`ip addr` 后过滤 `10.144.66`	客户端看到自己的虚拟 IP
客户端互通	`ping -c 3 10.144.66.6`	HK 到 US 有响应
TCP 业务路径	`ssh 10.144.66.6` 或访问虚拟网内 HTTP 服务	TCP 连接能建立
KCP/QUIC Proxy	`/root/easytier-linux-x86_64/easytier-cli proxy`	产生 TCP 流量后出现 `Kcp` 或 `Quic`

常用检查命令：

supervisorctl status easytier-share
ss -lntup | grep ':23451'
ss -lnuap | grep ':23451'
tail -n 100 /var/log/supervisor/easytier-share.log

supervisorctl status easytier-hk-client
supervisorctl status easytier-us-client
tail -n 100 /var/log/supervisor/easytier-hk-client.log
tail -n 100 /var/log/supervisor/easytier-us-client.log

ip addr | grep '10.144.66'
ping -c 3 10.144.66.6
ssh 10.144.66.6

查看代理连接：

/root/easytier-linux-x86_64/easytier-cli proxy

transport_type 出现 Kcp 或 Quic，说明对应代理通道已经建立。KCP 和 QUIC 同时启用时，实际输出可能优先看到 KCP。

9. no-root 模式边界
#

EasyTier 的 no-root 模式需要加：

--no-tun

它适合没有 root 权限、不能创建 TUN 设备的环境。这个模式下节点仍可通过虚拟 IP 被访问，也支持 TCP、UDP、ICMP 和子网代理，但节点不能像普通 TUN 模式那样主动访问其他节点。需要主动访问时，要配合 SOCKS5。

当前 Supervisor 配置使用 user=root 运行，目标是稳定创建虚拟网卡和虚拟 IP。后续如果要改成 no-root，要单独验证三件事：

访问方向是否满足业务要求。
是否需要 SOCKS5 作为主动访问入口。
--no-tun 下 KCP / QUIC Proxy 和业务连接路径是否仍符合预期。

10. 回滚方案
#

回滚不是只停进程。至少要能恢复 Supervisor 配置、停止错误实例，并在密钥变更场景下保证所有节点一致。

备份 Supervisor 配置：

tar czf /root/easytier-supervisor-backup-$(date +%F-%H%M%S).tar.gz \
  /etc/supervisor/conf.d/easytier-*.conf

停止实例：

supervisorctl stop easytier-share
supervisorctl stop easytier-hk-client
supervisorctl stop easytier-us-client

恢复配置后重新加载：

supervisorctl reread
supervisorctl update
supervisorctl restart easytier-share
supervisorctl restart easytier-hk-client
supervisorctl restart easytier-us-client

如果只是更换 network-secret，必须共享节点和所有客户端同步替换。只改一端会导致节点无法握手。

回滚场景	处理方式	验证
共享节点无法启动	恢复旧 `easytier-share.conf`，重新 `supervisorctl update`	`supervisorctl status easytier-share` 为 `RUNNING`
单个客户端接入失败	停止该客户端，恢复旧客户端配置	其他客户端仍可通过共享节点运行
密钥写错	同步替换共享节点和所有客户端密钥	客户端重新握手并恢复互通
KCP/QUIC 异常	临时移除 `--enable-kcp-proxy` / `--enable-quic-proxy` 后重启	普通虚拟网连接可用
no-root 改造失败	回到 `user=root` 和 TUN 模式配置	虚拟 IP 存在，客户端互通

11. 常见问题
#

11.1 Supervisor 里 `$(hostname)` 没展开
#

现象：EasyTier 节点名显示为字面量，或日志里看不到预期主机名。

可能原因：Supervisor 不会自动通过 shell 执行 command。

处理方式：

command=/bin/sh -lc 'exec ... --hostname "$(hostname -s)" ...'

也可以直接写死：

--hostname hk-client

11.2 客户端无法连接共享节点
#

现象：客户端进程反复重启，或日志里持续连接 203.0.113.10:23451 失败。

可能原因：

公网安全组没有同时放行 TCP/UDP 23451。
本机防火墙只放行了 TCP，没有放行 UDP。
共享节点没有真正监听 23451。

处理方式：

nc -vz 203.0.113.10 23451
nc -vzu 203.0.113.10 23451
supervisorctl status
tail -n 100 /var/log/supervisor/easytier-hk-client.log

11.3 节点启动后互相 ping 不通
#

现象：Supervisor 状态正常，但 ping -c 3 10.144.66.6 失败。

可能原因：

network-name 或 network-secret 不一致。
客户端虚拟 IP 冲突。
客户端误用了 --no-tun，访问方向和普通 TUN 模式不同。

处理方式：

ip addr | grep '10.144.66'
tail -n 100 /var/log/supervisor/easytier-hk-client.log
tail -n 100 /var/log/supervisor/easytier-us-client.log

必要时先停掉其中一个客户端，排除虚拟 IP 冲突：

supervisorctl stop easytier-us-client
ping -c 3 10.144.66.3

11.4 `easytier-cli proxy` 没有 KCP/QUIC
#

现象：进程正常，虚拟 IP 也能 ping，但 easytier-cli proxy 看不到代理连接。

可能原因：KCP/QUIC Proxy 只会在有对应 TCP 连接时出现活跃记录。

处理方式：先产生一条虚拟网内 TCP 连接，例如 SSH 或 HTTP，再查看：

ssh 10.144.66.6
/root/easytier-linux-x86_64/easytier-cli proxy

如果同时启用 KCP 和 QUIC，优先看到 KCP 属于预期现象。

11.5 修改密钥后全部节点离线
#

现象：共享节点正常监听，但所有客户端都无法加入网络。

可能原因：只改了共享节点或只改了客户端，导致握手密钥不一致。

处理方式：在维护窗口内同步修改共享节点和所有客户端配置，重新加载 Supervisor：

supervisorctl reread
supervisorctl update
supervisorctl restart easytier-share
supervisorctl restart easytier-hk-client
supervisorctl restart easytier-us-client

12. 发布前脱敏检查
#

发布前只保留方法和示例值，不保留能定位真实环境的信息。需要检查：

真实 network-secret
真实公网 IP
真实内网 IP 或虚拟网络规划
真实主机名
私有仓库地址、Token、私钥、API Key

扫描文章：

ARTICLE_FILE="content/posts/easytier-supervisor-deployment.md"
PRIVATE_IP_PATTERN="(^|[^0-9.])(10\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}|172\\.(1[6-9]|2[0-9]|3[0-1])\\.[0-9]{1,3}\\.[0-9]{1,3}|192\\.168\\.[0-9]{1,3}\\.[0-9]{1,3})([^0-9.]|$)"
SECRET_PATTERN="glpat-|oauth2:|BEGIN (RSA|OPENSSH|PRIVATE)|Authorization:[[:space:]]*Bearer|AKIA[0-9A-Z]{16}|api[_-]?key\\s*=|password\\s*=|passwd\\s*=|secret\\s*=|token\\s*=|client_secret\\s*=|private_key"

grep -nEi "${PRIVATE_IP_PATTERN}|${SECRET_PATTERN}" "${ARTICLE_FILE}" || true

本文允许命中 10.144.66.x，它是刻意保留的示例虚拟网段。其他真实公网地址、真实内网地址、真实密钥或 Token 命中后，先脱敏再发布。

检查新增 diff：

git diff -- content/posts/easytier-supervisor-deployment.md \
  | grep -E '^\\+[^+]' \
  | grep -nEi "${PRIVATE_IP_PATTERN}|${SECRET_PATTERN}" || true