uncloud CLI 实战uc dns release释放集群保留域名的完整指南【免费下载链接】uncloudA lightweight tool for deploying and managing containerised applications across a network of Docker hosts. Bridging the gap between Docker and Kubernetes ✨项目地址: https://gitcode.com/GitHub_Trending/unc/uncloud本文围绕 uncloud CLI 的uc dns release命令展开讲解如何释放集群中已保留的xxxxxx.uncld.dev域名并深入源码揭示其从命令行到集群存储的完整调用链帮助你理解 uncloud 内置 DNS 服务的生命周期管理。uc dns release是 uncloud 内置 DNSUncloud DNS子命令族中的一员用于释放集群此前通过uc dns reserve保留的唯一子域名。读完本文你将掌握该命令的完整语法、参数与退出行为理解释放操作在集群端的实际执行逻辑本地存储删除、域名记录与 Caddy 网关的关系并能结合uc dns show、uc dns reserve完成域名生命周期管理。命令概览uc dns release的功能一句话概括释放已保留的集群域名Release the reserved cluster domain。命令定义位于 cmd/uc/dns/release.go其帮助信息为Release the reserved cluster domain. uc dns release [flags]该命令不接受任何位置参数直接执行即可。当集群中存在已保留的域名时命令会删除该记录并打印释放结果若尚未保留任何域名则会报错退出。选项详解命令自身选项-h, --help help for releaserelease子命令自身仅提供-h/--help用于打印帮助信息无其他业务参数。继承自父命令的选项所有uc dns子命令都共享以下来自全局配置的选项见 cmd/uc/dns/root.go选项环境变量默认值说明--connect string$UNCLOUD_CONNECT无不使用 uncloud 配置文件直接连接远端集群机器。格式[ssh://]userhost[:port]、sshgo://userhost[:port]、tcp://host:port、unix:///path/to/uncloud.sock-c, --context string$UNCLOUD_CONTEXT当前上下文指定要使用的集群上下文名称--uncloud-config string$UNCLOUD_CONFIG~/.config/uncloud/config.yamluncloud 配置文件路径这些选项保证了uc dns release可以灵活适配不同的连接方式与多集群环境。例如在未初始化配置文件的环境中可以通过--connect直连指定机器执行释放操作。完整工作流程从命令行到集群存储uc dns release的执行并非简单地调用远端 API而是经历「CLI 客户端 → gRPC 集群服务 → 集群分布式存储」的完整链路。下面结合源码逐步拆解。第一步CLI 发起请求命令入口位于 cmd/uc/dns/release.gofunc release(ctx context.Context, uncli *cli.CLI) error { client, err : uncli.ConnectCluster(ctx) if err ! nil { return fmt.Errorf(connect to cluster: %w, err) } defer client.Close() domain, err : client.ReleaseDomain(ctx, emptypb.Empty{}) if err ! nil { if status.Convert(err).Code() codes.NotFound { return errors.New(no domain reserved) } } fmt.Printf(Released cluster domain: %s\n, domain.Name) return nil }关键行为通过uncli.ConnectCluster(ctx)依据当前上下文或--connect参数建立与集群的连接调用client.ReleaseDomain(ctx, emptypb.Empty{})发起 gRPC 请求错误处理若远端返回NotFound状态码即集群从未保留过域名CLI 会将其翻译为人类可读的错误信息no domain reserved并返回其他错误原样透传成功时打印Released cluster domain: 域名。这里体现了 uncloud CLI 一贯的错误语义gRPC 状态码与用户可读消息通过 pkg/api 与 internal/cli/errors.go 进行统一映射。第二步集群端 gRPC 服务处理ReleaseDomainRPC 定义在 api/pb/cluster.protorpc ReserveDomain(ReserveDomainRequest) returns (Domain); rpc GetDomain(google.protobuf.Empty) returns (Domain); rpc ReleaseDomain(google.protobuf.Empty) returns (Domain);集群端的实际实现位于 internal/machine/cluster/dns.gofunc (c *Cluster) ReleaseDomain(ctx context.Context, _ *emptypb.Empty) (*pb.Domain, error) { if err : c.checkReady(); err ! nil { return nil, err } domain, err : c.storedDomain(ctx) if err ! nil { return nil, err } if err c.store.Delete(ctx, uncloudDNSKey); err ! nil { return nil, status.Errorf(codes.Internal, delete domain from store: %v, err) } // TODO: implement and call Uncloud DNS endpoint to release/delete the domain. return pb.Domain{Name: domain.Name}, nil }实现要点就绪检查c.checkReady()确保集群服务可用否则直接返回错误读取已保留域名storedDomain(ctx)从分布式存储中读取以uncloud_dns为键uncloudDNSKey的 JSON 记录若不存在则返回NotFound状态码这正是 CLI 端显示no domain reserved的来源删除记录通过c.store.Delete(ctx, uncloudDNSKey)从集群存储中删除域名记录返回值向调用方返回被释放的域名名称pb.Domain{Name: domain.Name}。第三步已保留域名在存储中的形态ReserveDomain见 internal/machine/cluster/dns.go写入存储的结构体为type uncloudDNSDomain struct { // Endpoint is the API endpoint of the Uncloud DNS service where the domain is reserved. Endpoint string Name string // TODO: encrypt the token in the store. Token string }即每个已保留域名在集群存储中保存三要素DNS 服务端点Endpoint、域名Name与鉴权令牌Token。uc dns release的作用就是删除这条记录使集群回到「未保留域名」状态。注意源码注释提示 Token 目前以明文形式存储TODO: encrypt the token in the store.并提示释放操作尚未真正调用 Uncloud DNS 服务端删除域名TODO: implement and call Uncloud DNS endpoint to release/delete the domain.——这是一个值得留意的实现现状当前版本的释放是「本地注销」而非「远端删除」。实战域名生命周期完整演练将uc dns release放入完整生命周期中更能理解其定位。以 uncloud 官方推荐的 Uncloud DNS 服务默认端点https://dns.uncloud.run/v1定义于 cmd/uc/dns/reserve.go为例1. 查看当前域名uc dns show已保留时打印域名如xxxxxx.uncld.dev未保留时报错no domain reserved。对应实现见 cmd/uc/dns/show.go调用client.GetDomain(ctx)将api.ErrNotFound映射为no domain reserved。2. 保留域名uc dns reserve成功打印Reserved cluster domain: xxxxxx.uncld.dev已存在报错domain already reserved对应codes.AlreadyExists。保留成功后CLI 会检查集群中是否已部署 Caddy 反向代理服务client.InspectService(ctx, client.CaddyServiceName)见 cmd/uc/dns/reserve.go若 Caddy 已部署自动调用caddy.UpdateDomainRecords更新 DNS 记录把域名指向运行 Caddy 的机器若尚未部署提示Deploy the Caddy reverse proxy service (uc caddy deploy) to enable internet access to your services via the reserved or your custom domain.3. 释放域名uc dns release成功打印Released cluster domain: xxxxxx.uncld.dev未保留报错no domain reserved。完整输出示例$ uc dns show abc123.uncld.dev $ uc dns release Released cluster domain: abc123.uncld.dev $ uc dns release Error: no domain reserved释放域名后会发生什么理解释放的副作用需要回到uc dns父命令的定位。根命令帮助文本cmd/uc/dns/root.go明确指出Manage cluster domain in Uncloud DNS. DNS commands allow you to reserve or release a uniquexxxxxx.uncld.devdomain for your cluster. When reserved, Caddy service deployments will automatically update DNS records to route traffic to the services in the cluster.也就是说域名记录与 Caddy 网关部署是联动的保留状态下uc dns reserve及后续 Caddy 服务部署会自动把*.xxxxxx.uncld.dev的 A/AAAA 记录指向集群中可公网访问的、运行 Caddy 的机器详见 pkg/client/dns.go通配符记录Name: *释放之后集群存储中的域名与 Token 被删除后续任何依赖该域名创建 DNS 记录的操作如CreateDomainRecords见 internal/machine/cluster/dns.go都会因storedDomain返回NotFound而失败。此时若想让服务再次通过集群域名对外暴露需要重新uc dns reserve。另外DNS 记录的创建并非无条件写入而是带有可达性校验CreateIngressRecords会对运行 Caddy 的每台机器发起 HTTP 探测pkg/client/dns.go只有响应体与机器 ID 一致、确认是目标 Caddy 容器的机器才会被纳入 DNS 记录探测失败如处于 NAT/防火墙后的机器会被排除全部不可达时返回ErrNoReachableMachines。释放域名后重新保留这套校验会再次执行。常见错误与排查现象原因处理建议no domain reserved集群从未保留域名或域名已被释放先执行uc dns reserve保留域名connect to cluster: ...无法连接集群上下文错误、机器不可达、SSH 配置缺失用uc ctx ls/uc ctx use检查当前上下文或用--connect显式指定机器domain already reservedreserve 时集群已存在保留域名重复调用先uc dns release释放后再重新保留需要特别说明的边界情况由于当前实现中ReleaseDomain仅删除集群本地存储记录Uncloud DNS 服务端仍可能保留该域名的解析记录源码中TODO注释明确标注了这一点。因此在生产环境中释放域名后建议等待 DNS 缓存自然过期或结合业务需要重新保留新域名。关联命令与扩展阅读uc dnsDNS 子命令族入口管理集群域名uc dns reserve保留集群域名uc dns release的逆操作uc dns show打印当前集群域名uc caddy deploy部署 Caddy 反向代理启用基于域名/自定义域名的公网访问。若想深入实现细节建议按以下路径阅读仓库源码cmd/uc/dns/release.goCLI 命令入口与错误映射internal/machine/cluster/dns.go集群端ReserveDomain/GetDomain/ReleaseDomain/CreateDomainRecords完整实现api/pb/cluster.protogRPC 服务定义internal/dns/client.go 与 internal/dns/api.goUncloud DNS HTTP 客户端基于 acorn-io/runtime 的 dns 包思路实现负责与dns.uncloud.run交互pkg/client/dns.goDNS 记录创建与公网可达性校验逻辑。小结uc dns release虽是一个参数极简的子命令但其背后串联了 CLI 错误映射、gRPC 集群服务、分布式存储键值管理以及 Uncloud DNS 服务端交互等完整链路。掌握它你就能熟练管理 uncloud 集群的域名生命周期reserve保留、show查看、release释放并理解释放行为对 Caddy 网关与 DNS 记录的真实影响从而在「对外暴露服务」与「回收域名」之间自由切换。【免费下载链接】uncloudA lightweight tool for deploying and managing containerised applications across a network of Docker hosts. Bridging the gap between Docker and Kubernetes ✨项目地址: https://gitcode.com/GitHub_Trending/unc/uncloud创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考