客户端 / 服务端类软件的 CI/CD 发布
术语详解 · 特别流程 · 开源项目 · 单条命令动手实践

• 为什么先做这一步：它验证「服务器能不能连上这个仓库」——这正是后面 Argo CD 的 repo-server 要做的事。连通性有问题就要先解决，而不是等到部署时才发现。
• 输出里的 HEAD 和分支名是哈希值，不是文件名。能看到一堆哈希就说明通了。

• --depth 1：浅克隆，只拿最新一次提交，不拉全部历史。学习用途足够，能省大量时间和磁盘。
• ls -1：每行一个地列目录。先看它怎么分层——这一步的目的是找出「服务端代码」和「客户端 SDK」分别在哪个目录，这是你理解两端关系的第一步。
• cat package.json：看它的 workspaces 字段。Monorepo 项目会把多个包放在一个仓库里，看清这个结构你就知道发布时哪些包需要各自打版本。

• grep -ril：-r 递归、-i 忽略大小写、-l 只输出文件名（不输出匹配内容，避免刷屏）。
• --include=*.rs：只在 Rust 源码里搜，跳过文档和资源文件。
• 为什么用这种方式读代码：面对一个十几万行的大项目，不要从头读。先锁定关键词再定位文件，是读陌生代码库最有效的方法。你要找的就是「版本检查」和「下载替换」这两段。

• ss -lntp | grep ...：先检查端口有没有被占用。21115/21116/21117 是 RustDesk 服务端的默认端口。先检查再启动是个好习惯，能避免「启动了但连不上」的困惑。
• docker run -d：后台运行。--restart=unless-stopped：除非手动停，否则开机自启。
• --net=host：直接使用宿主机网络（RustDesk 需要大量 UDP 端口，桥接模式很麻烦）。
• docker logs --tail 30：看最近 30 行日志确认启动成功。服务端启动后第一件事永远是看日志。

注意：这条命令会真的启动一个容器。不想留就 docker rm -f hbbs 清掉。

• 官方文档说协议定义在 networkprotocol.h 这个头文件里，所以直接去那里找。
• PROTOCOL_VERSION 类常量是编译期常量——也就是「协议版本」是写死在代码里的，改一次就要重新编译发版。这正是「协议变更 = 不可热更」的物理原因。
• 你要观察的：这个数字是怎么被用在握手里的？搜 TOSERVER_INIT（客户端发给服务端的第一个包）看它怎么校验版本、校验失败后怎么回应。

• Luanti 的规则是：Major 号只有出现破坏性变更时才递增，minor 是新功能，patch 是修 bug。
• 这就是语义化版本（SemVer）的核心思想，也是为什么「协议版本」和「软件版本」要分开——软件的 patch 号涨了不代表协议变了。

• NetServer.java 是它的服务端网络核心。先找到「核心文件」，再在里面搜关键词，比全仓库搜快得多。
• 你要找的是：它怎么拿到连进来的客户端的版本、怎么比较、不一致时是断开还是警告。这就是版本闸门的最小实现。

• ls -1 cmd/：Go 项目的惯例是每个可执行程序在 cmd/ 下有一个目录。看这里就知道它拆了几个服务进程——这就是 1.2 节讲的「服务端分工」的真实样子。
• ls -1 internal/：内部实现包。看目录名能看出它的分层（网关、消息、推送、存储…）。
• 读法建议：不要读实现细节，先画出「哪个进程负责什么、它们之间怎么通信」的图。有了图，再去读你关心的那一块。

• Book/ 里是分章节的中文教程（运行指南、热更、网络、服务器架构等），比读代码快得多。
• 建议阅读顺序：先看「运行指南」理解两端怎么启动，再看「热更」章节——那一章就是本文 1.3 节的实践版。

• 看 harbor 和 gate 两个：前者是「跨机器路由」，后者是「客户端接入」。这两个就是 1.2 节讲的「网关服」和「位置服」的最简实现。

• nproc → CPU 核数。你的机器是 2。
• uptime → 最后的三个数字是 1/5/15 分钟平均负载。判断标准是「负载 ÷ 核数」：2 核机器上负载 0.8 就意味着 40% 已被占用。你的机器空闲时就是 0.79/0.87/0.82，所以要记得给自己留余量。
• free -m → 看 available 那一列（真正能用的），不是 free。同时看 Swap——你的机器 Swap 是 0，意味着内存一紧张就会直接被 OOM Killer 杀进程，没有缓冲。所以起新服务前一定先看 available。
• df -h / → 根分区剩余空间。你的机器剩 42G。

• ps aux --sort=-%cpu：按 CPU 占用降序排列（- 表示降序），head -6 只看前 5 行 + 表头。
• 你会看到 tailscaled 占 28% CPU——它同时在为整个 k8s 集群做中继。这是你环境里最大的常驻开销，知道它在哪，排查「机器为什么慢」时就不会走错方向。
• 第二个命令按内存排序，你会看到 Jenkins 占约 1GB。这是正常的（Jenkins 是 JVM 应用），但它意味着这台机器不是「什么都没跑」。

• ss -lntp：-l 只看监听中的、-n 显示数字端口（不解析成服务名）、-t TCP、-p 显示占用进程。
• || echo ...：|| 表示「前面失败才执行后面」。grep 没找到会返回非零退出码，所以就会打印那句话。

• sudo -u nexus：以 nexus 这个系统用户的身份运行。Nexus 出于安全考虑拒绝以 root 启动，直接 /opt/nexus/bin/nexus start 会报错退出。
• /opt/nexus/bin/nexus：官方的启停脚本。你的机器上没有 systemd 服务单元（systemctl list-unit-files | grep nexus 会是空的），所以只能用这个脚本。
• start：启动。stop / status / restart 同理，脚本支持这些参数。
• 副作用提醒：Nexus 是 Java 应用，启动约占 1GB 内存（它自带 Temurin JDK 21）。启动前先确认 free -m 的 available 够。

• sleep 30：Nexus 是 JVM 应用，启动要 20～40 秒。不是它卡住了，是 JVM 要初始化。
• ss -lntp | grep ':7878'：确认端口真的在监听。看到 LISTEN 那行就说明成功了。
• curl -s -o /dev/null -w 'HTTP %{http_code}'：-s 静默（不打印进度）、-o /dev/null 丢弃响应体、-w 只打印我们关心的格式。这是检查 HTTP 服务是否存活的通用写法，比 curl 出来一整页 HTML 干净得多。期望看到 HTTP 200。

• 登录地址：http://<服务器IP>:7878，用户名 admin。
• 学习建议：改密码时记下来，后面 curl 上传制品要用到。

• -u admin:'密码'：HTTP Basic 认证。注意单引号——密码里有 @ 这类特殊字符时，不加引号会被 shell 解释掉。
• -X POST：这是「创建」操作，不是查询。
• "format": "raw"：关键字段。raw 类型表示「不按 Maven/npm 等格式解析，就当一个普通文件仓库」——正适合放安装包和补丁。
• "type": "hosted"：本地托管（我们上传到它这里），区别于 proxy（代理别人）和 group（聚合） 。
• "writePolicy": "allow_once"：这是本仓库最重要的一条策略——同一个路径只能写一次，不允许覆盖。为什么：产物一旦发布就不许改。如果允许覆盖，「1.2.0 版安装包」在不同时间下载到的内容可能不一样，客户端校验哈希就会失败，而且你永远说不清线上跑的是哪一个包。
• strictContentTypeValidation: false：不校验 MIME 类型（补丁文件是自定义二进制格式，校验会误拦）。
• -w '\nHTTP %{http_code}\n'：最后打印状态码。201 或 204 表示创建成功。

• --upload-file：curl 的上传参数，直接把本地文件 PUT 到目标 URL。URL 里的路径就是仓库里的目录结构（client/1.0.0/test.txt）。
• 下载时不需要认证也能读（raw 仓库默认允许匿名读）。这一点很重要：客户端要能匿名下载安装包。
• 第二条命令期望输出 hello v1.0.0。能看到就说明「客户端产物分发通道」已经通了。
• 再验证一次 allow_once 的效果：把同一条上传命令再跑一遍，应该返回 400 而不是成功——这就是「已发布的东西不许改」。

• export PATH=/root/node/bin:$PATH：把 Node 加进 PATH。你的 Node 装在 /root/node/bin，不是系统默认路径。
• npm config set registry https://registry.npmmirror.com：把 npm 源换成国内镜像。你的 Dockerfile 里也做了这一步，所以构建镜像时不会因为拉不到包而失败。
• npm install：安装依赖（这个项目只依赖一个 ws 包，用来做 WebSocket 服务端）。
• 最后一行：用环境变量启动，这是本 demo 的核心教学点——FEATURES 就是 Feature Flag。改这个值重启，就相当于「服务端下发不同的开关配置」。
• 观察启动日志：它会打印协议窗口 [4, 5]、configVersion、当前开关。这三行就是「服务端能力声明」。

按 Ctrl+C 停止，或者另开一个终端继续下一步。

• ① 正常路径。观察输出里的「握手通过」和「对我开放的功能」。
• ② 这是最重要的一条。协议 4 在兼容窗口 [4,5] 内，所以放行；但因为它是老协议，服务端不下发新功能。这一条完整演示了「老客户端还能玩，只是看不到新功能」——也就是你推断三的实现。
• ③ 协议 3 低于 MIN_PROTOCOL=4，服务端返回 reject 并告知最低要求。这就是「强制更新」的技术本质——不是客户端自己想更新，是服务端不让它进。
• ④ 模拟「配置表只发了一半」的场景（1.8 节的事故模式三）。

• 为什么要做这个测试：如果分桶哈希写得不好，连续 ID 会落到连续的桶里，你看到的可能是「命中 0 个」或「命中 1 个」这种荒谬结果，而不是接近放量比例的数字。
• 服务端默认 ROLLOUT_PERCENT=100（全部命中），所以想看到真实分布，要把服务端用 ROLLOUT_PERCENT=20 重启后再测，此时 100 个用户里应该命中约 20 个。
• 这个坑真实存在：本文 demo 的第一版哈希就没做雪崩混淆，连续 ID 得到的是连续桶号，放量 20% 实际只覆盖了 ID 尾号靠前的一小撮用户。修复后 1000 个连续 ID 的命中率才是 20.1%。

• DRAIN_GRACE_MS=3000：把排空宽限期从默认 20 秒改成 3 秒，这样你不用等太久。
• 第三个 curl /healthz 返回 503 是故意的——readiness 失败 → K8s 会把 Pod 从 Endpoints 摘掉 → 新连接不再进来。这就是「摘流」的实现方式：不是去调负载均衡的 API，而是让自己的就绪探针失败。
• 第四个 curl /livez 仍然是 200——这是为了告诉 K8s「我活着，别重启我」。如果这两个探针用同一个接口，排空会被 K8s 的重启打断（1.6 节的经典错误）。
• 同时去终端 B 看：客户端应该收到 {"type":"reconnect","message":"服务即将重启..."}，而不是异常断开。这就是「用户感受到的是卡顿，而不是掉线」。
• Linux 上还可以用 SIGTERM 触发同一条路径：pkill -TERM -f "node server.js"。它和 /drain 调用的是同一个函数。

• xdelta 在 EPEL 源里（你的机器已启用 epel 仓库，实测可安装 xdelta.x86_64 3.1.0-17.el9）。
• 它是什么：一个生成/应用二进制差量补丁的工具。给两个版本的安装包，它能算出「只有差异部分」的小补丁。
• 为什么用 xdelta 而不是 bsdiff：bsdiff 在 Rocky 的官方源和 EPEL 里都没有，xdelta3 有。功能用途相同。
• 验证：xdelta3 -V 能看到版本号就成功了。

• mkdir -p：-p 表示父目录不存在就一起建，已存在也不报错。
• dd if=/dev/urandom of=... bs=1k count=2000：生成 2000KB（约 2MB）的随机文件，用来模拟安装包。bs=1k count=2000 就是 1000 字节 × 2000 块。真实项目里这一步是「执行构建脚本」，这里只是造个有体积的假包。
• ls -lh：-h 让体积以人类可读形式显示（KB/MB），而不是字节数。

• -e：encode，表示「生成补丁」（对应的 -d 是 decode，即应用补丁）。
• -s 1.0.0/full.tar.gz：源文件（玩家本地已有的那个版本）。-s 是 source 的意思。
• 然后是新文件，最后是输出补丁。顺序不能乱。
• 真实场景下这里会看到补丁只有整包的百分之几。你这次用随机数据，补丁会接近整包大小——这是正常的，因为随机数据没有重复模式可利用。想看到真实效果，可以把 1.2.0 改成「1.0.0 的副本 + 改几个字节」：cp 1.0.0/full.tar.gz 1.2.0/full.tar.gz && echo change >> 1.2.0/full.tar.gz，这样生成的补丁就只有几 KB。

• sha256sum：输出「64 位十六进制哈希 + 文件名」。它的用途是完整性校验——客户端下载完文件后重算一次，和清单里的值比对，不一致就说明文件损坏或被篡改。
• stat -c '%n %s bytes'：-c 表示自定义输出格式。%n 是文件名，%s 是文件字节数。不要用 ls -l 去抄体积，它显示的是 KB/MB 会四舍五入，清单里需要精确字节数。
• 为什么必须手工算而不是估算：这两个值是客户端用来判断「下载是否成功」的唯一依据。填错了客户端会认为所有下载都是坏的。

• cat > 文件 <<'EOF' ... EOF：heredoc 写法，把两个 EOF 之间的内容写进文件。注意 'EOF' 要加单引号——不加的话 shell 会把内容里的 $ 和反引号当变量展开，JSON 就会被破坏。
• 为什么叫 .tmp：下一步会解释。这一步是「先写临时文件」。
• python3 -m json.tool：把 JSON 格式化并校验语法。如果 JSON 写错了（少个逗号、多个括号），这条命令会直接报错并指出行号。你要用这个当「语法检查器」——不要等客户端来发现你的 JSON 是坏的。
• 每个字段的作用（对照 1.7 节）：
  • latest / minSupported / recommended 三个版本号决定客户端是「不更新 / 可选更新 / 强制更新」。
  • protocol 是给服务端做版本闸门用的兼容窗口。
  • configVersion 用来防「配置表只发了一半」。
  • rollout.percent: 20 表示只给 20% 的用户开放更新（分桶决定谁命中）。
  • packages[] 是整包兜底，patches[] 是优先使用的差量补丁。

• 如果客户端正好在你写到一半的时候来拉取，它读到的是半个 JSON → 解析失败 → 卡在更新界面。这是一个真实的线上事故类型。
• mv 在同一个文件系统内是原子操作：客户端要么看到完整的旧文件、要么看到完整的新文件，不存在中间态。
• ls -l manifest.json* 会显示只剩 manifest.json，临时文件已消失。
• 这个技巧通用：配置下发、证书替换、静态站点发布都用同一招。

• cp ... .bak：改任何配置文件前先备份。改坏了 cp ruoyi.conf.bak ruoyi.conf && nginx -s reload 就能回滚。
• alias /opt/patches/client/：把 URL 路径 /patches/ 映射到磁盘目录。注意 alias 会把 location 之后的部分直接拼到目录后面。
• autoindex on：允许列出目录内容。学习阶段方便你确认文件在不在，生产环境建议关掉（会暴露文件结构）。
• nginx -t：只检查配置语法，不生效。这一步至关重要——如果配置写错直接 reload，Nginx 会拒绝加载新配置（老配置继续跑，服务不断），但你会困惑「为什么我的修改没效果」。
• nginx -s reload：平滑重载（不中断现有连接）。
• 验证：curl -s http://127.0.0.1/patches/manifest.json | python3 -m json.tool 应该能打印出格式化的 JSON。

• echo -n "1.0.0" > local/version.txt：模拟「用户设备上装的是 1.0.0 版本」。-n 表示不追加换行符。
• --auto：自动接受可选更新（不传的话，弹窗类的更新会被跳过）。
• --url：指向我们刚刚用 Nginx 发布的清单地址。
• 预期输出顺序：拉取 manifest → 打印三个版本号 → 决策（可选更新/未命中放量/已最新）→ 下载差量补丁 → SHA256 校验 → 应用 → 版本变更 → 连接服务端握手。这一整条就是客户端的 CD。
• 如果分桶没命中（percent: 20），换个 --user 值再试，直到命中。这本身就是在体验「分阶段放量」。

• 预期输出：[校验] SHA256 不匹配！期望 deadbeef… 实际 29c0d44c… 然后 拒绝应用该包，本地版本仍然是 1.0.0。
• python3 - <<'PY' ... PY：把一段 Python 脚本通过标准输入交给 Python 执行，不落盘成文件。这就是「不需要写脚本文件」的做法——一次性操作直接用 heredoc 喂给解释器。
• 为什么必须有这一步：差量补丁应用失败会产生「看起来能用但实际损坏」的包。没有哈希校验，这种坏包会直接进到玩家设备上。

• -f：HTTP 出错时返回非零退出码（否则 curl 会「成功」地保存一个错误页面）。-L：跟随重定向。--retry 3：失败重试 3 次。
• gh-proxy.com/https://raw.githubusercontent.com/...：这是把 GitHub 的原始链接套一层国内代理。实测下载 929730 字节。备用通道：ghfast.top 前缀、cdn.jsdelivr.net/gh/argoproj/argo-rollouts@v1.7.2/manifests/install.yaml。
• wc -c 校验字节数，确认下载完整——这是防止「下载了一半的 YAML」的第二道保险。
• 为什么是 v1.7.2：你的集群是 k8s v1.28，而 Argo Rollouts 官方 stable 分支测试的是 1.32～1.35、master 是 1.34～1.37，都不覆盖 1.28。1.8 起已明确不支持 1.28 以下。

• quay.m.daocloud.io：DaoCloud 提供的 quay.io 国内代理，实测 manifest 可拉取（含 amd64）。备用：quay.nju.edu.cn/argoproj/argo-rollouts。
• 为什么要搬进 Harbor 而不是直接用代理：集群对公网没有依赖、镜像有留存、后续升级路径统一。这是上一轮 Argo CD 方案里同样的做法。
• sed -i "s#旧#新#g"：用 # 当分隔符是因为路径里含 /，用 / 当分隔符要转义很麻烦。
• grep -n 'image:'：确认替换干净——输出里不应该再出现 quay.io。

• 为什么要 nodeSelector 钉在 k8s-node3：你的集群里 node1 内存 76%、node2 内存 93%，只有 node3（7.4G 分配）余量够。不钉的话调度器可能把它丢到 node2 上，直接触发 OOM。
• imagePullSecrets：Harbor 是私有仓库，需要拉取凭据。这个 secret 要先从 ruoyi 命名空间复制过来，或者手工创建。
• kubectl get crd | grep argoproj：确认 CRD 装上了——能看到 rollouts.argoproj.io 和 analysistemplates.argoproj.io 就成功了。

• --watch：持续刷新状态。你会看到 setWeight 从 10% → 30% → 60% → 100%，中间有 pause 等待窗口。
• set image：改镜像 tag，这就是触发一次新发布的动作。在 GitOps 流程里这一步由 Argo CD 改清单完成，这里手工触发是为了让你看到过程。
• abort：这个命令请务必练熟。它会把流量切回 Stable 版本，是新版本出问题时的第一反应。
• 注意流量切分靠的是 ingress-nginx 的 canary 注解，由 Rollouts 自动维护，你不需要手工改 Ingress。

• 「强制更新」是唯一一个一旦发错就可能导致全量用户进不去的操作。它和别的发布不一样——别的发错了用户还能用旧版本，这个发错了用户连旧版本都用不了。
• 所以你必须提前练会「紧急撤回」：把 minSupported 改回旧值 → 原子替换 manifest → 确认老客户端能重新登录。这个动作要练到 3 分钟内能完成。
• 注意每一步都用了 .tmp + mv 的原子替换。这种场景下尤其不能省——你在撤回的时候如果写坏了 manifest，就是雪上加霜。