Uncloud 集群管理
这是 uc CLI 的参考技能，用于管理 Uncloud——一个使用 Docker 容器、WireGuard 网状网络与 Caddy 反向代理的去中心化自托管平台。
适用场景：引导或加入机器（uc machine）、从 Compose 文件部署服务（uc deploy）、发布 HTTP/HTTPS/TCP/UDP 端口、通过 x-caddy、x-ports 或 --caddyfile 配置 Caddy 入口、将外部局域网设备经由集群代理路由、查看日志、服务状态、卷、DNS 或机器分布。
工作原理：Uncloud 在由 WireGuard 网状网络连接的对等机器上运行 Docker 服务。每台机器都是平等的集群成员，服务通过覆盖网络通信，Caddy 全局运行以终止公网 HTTP/HTTPS 流量。Compose 文件可使用 Uncloud 扩展配置入口、放置策略与生成的 Caddy 配置，uc CLI 负责镜像分发、调度、扩缩容、日志与集群状态。
主要能力与命令： 机器：uc machine init user@host（初始化首台机器/新集群）、uc machine add（加入现有集群）、uc machine ls、uc machine update NAME --public-ip IP、uc machine rm。init 标志含 --name、--network、--no-caddy、--no-dns、--public-ip。 服务：uc service ls、uc service run IMAGE、uc deploy、uc deploy --no-build、uc deploy --recreate、uc scale SERVICE N、uc service logs、uc service exec、uc service inspect、uc service rm（保留命名卷）、uc ps。 镜像：uc image push myapp:latest、uc image push myapp:latest -m machine1,machine2、uc images。 卷：uc volume ls、uc volume ls -m machine1、uc volume create NAME -m MACHINE、uc volume rm NAME。 Caddy：uc caddy config（只读显示当前生成的 Caddyfile）、uc caddy deploy。 DNS 与上下文：uc dns show、uc dns reserve、uc ctx ls、uc ctx use prod。
端口发布：HTTP/HTTPS 经 Caddy 反向代理，格式 -p [hostname:]container_port[/protocol]，如 -p 8080/https（自动生成 hostname）、-p app.example.com:8080/https、-p 8080/http。TCP/UDP 绑定主机并绕过 Caddy，格式 -p [host_ip:]host_port:container_port[/protocol]@host，如 -p 5432:5432@host、-p 127.0.0.1:5432:5432@host、-p 53:5353/udp@host。
Compose 扩展：x-ports 发布带域名的端口；x-caddy 为服务定制 Caddy 配置（支持 {{upstreams}}、{{.Name}}、{{.Upstreams}} 模板函数）；x-machines 设置放置约束。
路由到外部非集群设备：创建 Caddyfile 片段（如 ~/device.caddyfile），用 uc service run --name device-bmc --caddyfile ~/device.caddyfile registry.k8s.io/pause:3.9 注册为无操作容器的命名服务，再用 uc caddy config 验证。--caddyfile 不能与非 @host 发布端口组合使用。
内部服务 DNS：service-name、service-name.internal、rr.service-name.internal（轮询）、nearest.service-name.internal（优先本机）。
扩缩容与全局服务：uc scale web 5，Compose 中 deploy.mode: global 表示每台机器一个容器。镜像标签模板支持 {{gitsha N}}、{{gitdate "format"}}、{{date "format"}}。
常用工作流：uc deploy（构建+推送+部署）、uc build --push && uc deploy --no-build；检查服务用 uc inspect web、uc logs -f web、uc exec web。零停机部署自动进行，等待健康检查后再终止旧容器。
注意事项：不要直接编辑自动生成的 Caddyfile，应使用 x-caddy 或 --caddyfile；代理自签名 HTTPS 上游需加 transport http { tls_insecure_skip_verify }；uc caddy config 无用户自定义块时检查 Caddy admin socket；命名卷在 uc service rm 后仍保留。