tuneplane-node daemon。节点主动向控制网关建立
双向 gRPC 连接，通过 TLS 验证网关，并使用每个节点独立、可撤销和自动轮换的凭据。
不开放入站 HTTP 控制端口，也不在节点之间共享凭据。
前置条件
- Docker 或 Podman；GPU 作业还需要 NVIDIA Container Toolkit。
- 一个 Node Fleet，以及在控制台和所有作业机器上挂载到同一绝对路径的共享存储。
- 节点信任的网关服务端 TLS 证书。默认使用系统信任库，也可配置企业私有 CA。 无需给每个节点签发客户端证书，也无需另建 PKI 服务。
- 每个节点明确声明 CPU、内存和 GPU 索引额度。GPU 作业也需要 CPU 和内存限额， 运行时镜像必须解析为不可变摘要。
注册并启动
在 Fleet 页面创建 Join Token，然后执行：TUNEPLANE_NODE_STATE_DIR。注册和启动前应设置相同的状态目录，将其放在持久化本地
磁盘上，与共享作业存储分开；管理同一容器运行时的进程必须共享该状态目录。
/etc/tuneplane-node.env 中的资源额度。网关地址和 CA 可在加入时自动保存，见下文。
升级和重启时保留状态目录。
加入时自动配置网关信任
在控制平面配置节点能访问的网关地址：TUNEPLANE_SECRET_ENC_KEY 加密存入 PostgreSQL，并缓存到
<repo_root>/.tuneplane-data/gateway-tls/current/。网关读取同一套身份，重启复用。
节点加入时通过已验证的 Console HTTPS 接收地址与公共证书，此后直接运行
tuneplane-node serve，无需逐台配置网关证书。
可通过 TUNEPLANE_GATEWAY_TLS_DIR 指定作业存储之外的私有本地缓存目录，私钥权限为 0600。
API、worker 和网关副本可使用各自目录，从数据库恢复同一套身份。首次生成通过 PostgreSQL 串行化。
数据库和加密密钥必须一起备份；本地目录丢失后可恢复，节点信任保持不变。
首次写入数据库时会导入已有本地证书。已有本地身份与数据库不一致、文件不完整、过期或地址不匹配时，启动报错，不会静默替换信任。
控制平面多实例
所有实例共用 PostgreSQL、TUNEPLANE_SECRET_ENC_KEY、Web JWT 密钥及相同的公共网关地址。
网关副本前使用稳定域名和 TCP/TLS 透传负载均衡。网关退出后节点重连，命令归属仍保存在
PostgreSQL 和节点本地日志中。控制平面扩容还需遵循原有 Redis、worker 和 leader 配置。
每台机器各用本地 Docker 卷即可缓存 TLS，无需为证书准备网络文件系统。
Compose 保留现有本地卷。Helm 的 gateway.tlsSecret 留空时使用每个 Pod 的本地缓存；填写时使用外部 Secret。
作业存储仍需独立配置。
使用外部签发证书时设置 TUNEPLANE_GATEWAY_TLS_AUTO_GENERATE=false，给网关传入
--certificate 和 --private-key，并把 API 的 TUNEPLANE_NODE_GATEWAY_TRUST_BUNDLE
指向可读取的公共 CA 文件；系统已信任的公有 CA 可留空该文件路径。
显式配置信任文件也会停用自动生成。不要向节点分发私钥。
Console HTTPS 与 gateway TLS 可以使用不同 CA。如果 Console 自身使用私有 CA，
首次加入仍须通过 join --trust-bundle 或 TUNEPLANE_NODE_ENROLLMENT_TRUST_BUNDLE 建立信任，下载安装器使用 curl --cacert。
TUNEPLANE_NODE_GATEWAY、TUNEPLANE_NODE_TRUST_BUNDLE 可显式覆盖保存的网关配置；
Console 与网关 CA 不同时，不要将仅用于加入的 Console CA 留作服务的网关覆盖配置。
保存的 CA 不会自动刷新：同一 CA 签发的新服务端证书无需修改节点，替换 CA 则需先更新节点信任。
生成 10 年自签证书
在仓库根目录运行，填写节点实际连接网关时使用的域名或 IP：--host 添加域名、IPv4 或 IPv6，参数不带协议前缀和端口。
输出目录必须尚不存在，脚本不会覆盖已有证书或私钥。
tls.crt和tls.key：挂载给 gateway。私钥权限为0600，需要由 gateway 进程所属用户读取。ca.crt：该自签证书的公共副本。放到 API 可读取的位置，并将TUNEPLANE_NODE_GATEWAY_TRUST_BUNDLE指向该路径。不要向 Node 分发tls.key。
--certificate <output>/tls.crt --private-key <output>/tls.key，并把 API 的公共 CA 路径设为
<output>/ca.crt。TUNEPLANE_NODE_GATEWAY_TARGET 中的地址必须匹配证书中的域名或 IP。
部署网关
网关副本共享已迁移的 PostgreSQL 和控制台 SecretBox 密钥，不挂载容器运行时或作业存储。 Helm 中开启gateway.enabled 并配置公共网关地址；也可将 gateway.tlsSecret 指向包含
tls.crt、tls.key 的外部服务端证书 Secret。普通 Kubernetes 可使用
deploy/k8s/gateway.yaml。Compose 提供 gateway profile，从持久卷共享自动生成的证书。
配置 gateway.tlsSecret 后默认关闭自动生成。同一个网关进程还在 8444 端口接收采集器遥测。
通过 TCP 入口暴露 8443 端口，保留到网关的 TLS 连接。节点验证网关主机名，
并仅提交自己的凭据。删除节点会使凭据和已建立的控制会话失效。
凭据有效期为 30 天，在线节点每天自动轮换；一小时交接窗口和原子状态写入支持
轮换响应丢失后的恢复。离线超过凭据有效期的节点需要重新注册。
Node 程序升级
安装器将各版本放到/opt/tuneplane-node/releases/ 独立环境中，current 指向当前守护进程，
updater 指向最后一次健康的升级程序。节点身份、凭据和命令日志保留在持久化状态目录。
重复运行安装器也会走同一套空闲升级流程。
已有非托管 pip/uv 安装需先排空作业并停止服务，在 /etc/tuneplane-node.env 保留原来的
TUNEPLANE_NODE_STATE_DIR，再运行新安装器。安装器会拒绝覆盖正在运行的非托管服务。
/api/node-release，跟随其指定的准确版本，
不会直接追随包索引的最新版。负载均衡命中旧控制平面副本时不会自动降级。
Console 使用私有 CA 时，在 /etc/tuneplane-node.env 等运行环境中配置
TUNEPLANE_NODE_ENROLLMENT_TRUST_BUNDLE。包镜像需支持 HTTPS 并提供兼容的 wheel。
通信协议不兼容时必须安排计划升级，自动升级会拒绝切换。
自动升级默认关闭。先验证一个试点节点，再在选定节点开启：
TUNEPLANE_NODE_AUTO_UPDATE=true。定时器每小时检查，附加最多十分钟随机延迟。
通过选定主机开启定时器控制批次；目前没有 Fleet 全局并发升级限制。
训练、Playground、模型部署、已预留资源及状态不确定的任务都会推迟升级。
新版先安装到独立环境，再停止守护进程。通过本地接单锁和停止后的日志复查，处理升级与新任务接入的竞争。
升级程序备份空闲日志，原子切换程序，并等待最多六十秒，确认新的健康库存和已认证网关连接。
启动失败会恢复旧程序与日志；保留节点身份，不重新注册，不杀作业容器。
切换中断后由最后健康的升级程序先恢复，再联系控制平面。
长期运行的模型部署可能无限期推迟升级，应在维护窗口先迁移或停止相关服务。
通过 /opt/tuneplane-node/update.json 和 journalctl -u tuneplane-node-update.service 查看结果。
健康检查失败的版本不会反复尝试，需要执行 tuneplane-node update --retry 或选择更新的版本。
旧环境保留用于恢复。容器化 Node 由部署系统更新，不使用这套主机/systemd 升级流程。
方案参考 K3s 升级计划 与
Kubernetes 工作节点升级：
锁定目标版本，先小批验证，并在切换前保护作业归属。
执行语义
提交先持久化不可变成员计划和待启动 attempt，独立启动消费者再准备全部成员并提交启动。 重试沿用同一个操作身份，响应丢失不会授权创建第二份作业。 节点失联不代表作业终止。确认终止前持续保留资源占用；重连后必须重新报告库存才能接新作业。 排空和人工隔离状态不会被重连解除。停止和有大小上限的日志读取拥有独立于慢启动的处理额度。 Node Fleet 支持一个同构资源池，单个作业最多跨 8 台机器；更大的作业在提交时即被拒绝， 应提交到 Kubernetes 或 Slurm Fleet。多机 GPU 作业使用 process group 或 Ray； Ray 运行时制品必须声明精确ray_version。多个资源池使用 Kubernetes 或 Slurm。
节点互通端口和共享存储需要单独配置，出站控制连接不能替代它们。启用网关并不代表已支持
对象存储交付，也不代表已完成真实分布式运行时认证。
已完成的对象输入
Node 作业可以引用平台 S3 产物注册表中已完成的检查点。在每台 Node 上设置TUNEPLANE_NODE_STAGING_CAPACITY_GB，为校验后的输入副本预留本地磁盘；容量为零时会拒绝此类输入。
Capsule 和其他已有的共享挂载仍然需要共享存储根目录。
控制网关需要与控制台相同的对象存储配置，下载 URL 仅由网关签发。Node 通过已认证的
双向 gRPC 控制连接获取有效期为 15 分钟的只读授权，然后通过 HTTPS 直接下载。
对象存储证书必须被 Node 的 Python 运行时信任；使用私有 CA 时，请配置系统信任，
或在守护进程环境中设置 SSL_CERT_FILE。此输入通道拒绝重定向和仅支持 HTTP 的对象端点。
下载前会预留磁盘，支持中断文件续传，并在校验完成清单后发布只读挂载。
工作负载通过 TUNEPLANE_INIT_FROM_PATH 获取路径，不会收到下载凭据。
重试受 Node 准备阶段期限限制。重启守护进程时应保留 Node 状态目录及其中的输入副本。
停止启动、禁用所有者或撤回源产物后，将不能再申请新的读取授权。
已签发 URL 在过期前仍然有效，这不代表对象存储能够立即撤销授权。
禁止导出的 Volume 不允许使用这条产物交付通道。
对象存储交付 Capsule
在控制平面设置TUNEPLANE_NODE_CAPSULE_OBJECT_PULL=true，即可通过同一套限定权限的对象读取通道交付 Capsule。Node 的暂存空间需要容纳不可变缓存和可写执行副本，可信 runner 仍以只读方式挂载。输出和缓存仍需要共享挂载；分布式训练必须共用一个输出目录。
Slurm 和 Kubernetes 也可通过工作存储层中的校验副本使用已完成的产物输入；Kubernetes 需要配置工作存储 PVC。Kubernetes 的 Capsule 启动流程还需要 Pod 能访问的 HTTPS 公网或内网控制端点。Pod 启动时才领取短期对象下载链接，因此普通排队等待不会导致提交时的链接过期。限定本次执行的读取凭据有效期为三十天；执行失效或用户被停用后，无法再领取链接。
可在 spec.resources.network 中明确声明 transport: tcp、isolation: fleet，以及 bond0 等具体 interface。网卡必须存在于工作负载的网络命名空间。后端尚无可执行且通过认证的配置时，RDMA 和逐作业隔离要求会被拒绝。训练节点间的网络和对象存储访问需要分别验证，不能用控制通道连通代替。