Uncloud 集群域名管理完全指南：使用 `uc dns` 保留与释放 `uncld.dev` 域名

Uncloud 集群域名管理完全指南使用uc dns保留与释放uncld.dev域名【免费下载链接】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/unclouduc dns是 Uncloud CLI 中管理集群域名的命令组它让每个 Uncloud 集群可以保留一个唯一的xxxxxx.uncld.dev域名并在 Caddy 反向代理服务部署后自动将 DNS 记录指向集群内的互联网可达机器从而为集群中的服务提供统一的公网访问入口。读完本文你将掌握uc dns reserve、uc dns show、uc dns release三个子命令的完整用法、全部参数以及域名从保留、记录写入到释放的底层工作原理。uc dns命令概述uc dns用于管理 Uncloud DNS 中的集群域名。其长帮助文本明确说明了核心用途见 cmd/uc/dns/root.goDNS 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.也就是说uc dns承担两个职责域名生命周期管理为集群保留或释放一个唯一的xxxxxx.uncld.dev域名DNS 记录自动同步域名保留后Caddy 服务部署会自动更新 DNS 记录把流量路由到集群中的服务上。该命令组由三个子命令组成注册逻辑同样位于 cmd/uc/dns/root.go子命令功能对应源码uc dns reserve在 Uncloud DNS 中保留一个集群域名cmd/uc/dns/reserve.gouc dns show打印集群域名cmd/uc/dns/show.gouc dns release释放已保留的集群域名cmd/uc/dns/release.go语法与帮助uc dns [flags] uc dns [command]Optionsuc dns自身选项选项说明-h, --help显示dns命令的帮助信息继承自父命令的选项uc dns及其所有子命令均继承自uc根命令的全局连接与上下文选项与 cmd/uc/context/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 配置文件的路径所有 DNS 子命令在执行时都会通过uncli.ConnectCluster(ctx)连接当前集群或--connect指定的机器例如 cmd/uc/dns/reserve.goclusterClient, err : uncli.ConnectCluster(ctx) if err ! nil { return fmt.Errorf(connect to cluster: %w, err) } defer clusterClient.Close()子命令一uc dns reserve— 保留集群域名uc dns reserve在 Uncloud DNS 服务中为当前集群保留一个唯一的xxxxxx.uncld.dev域名。语法与选项uc dns reserve [flags]选项说明--endpoint stringUncloud DNS 服务的 API 端点默认值为https://dns.uncloud.run/v1-h, --help显示reserve命令的帮助信息--endpoint的默认值定义在 cmd/uc/dns/reserve.goconst DefaultUncloudDNSAPIEndpoint https://dns.uncloud.run/v1 cmd.Flags().StringVar(opts.endpoint, endpoint, DefaultUncloudDNSAPIEndpoint, API endpoint for the Uncloud DNS service.)执行流程与示例$ uc dns reserve Reserved cluster domain: abc123.uncld.dev执行reserve后CLI 会依次完成以下工作cmd/uc/dns/reserve.go连接集群调用集群端 RPCReserveDomain携带Endpoint参数若集群中已存在保留域名服务端返回codes.AlreadyExistsCLI 报错domain already reserved并终止保留成功后输出Reserved cluster domain: domainCaddy 集成检查调用InspectService检查集群中是否已部署名为 Caddy 的反向代理服务若 Caddy 服务尚未部署输出提示Deploy the Caddy reverse proxy service (uc caddy deploy) to enable internet access to your services via the reserved or your custom domain.随后正常结束——域名只是完成保留公网访问需要先部署 Caddy若 Caddy已部署则继续调用caddy.UpdateDomainRecords更新集群域名在 Uncloud DNS 中的记录使其指向运行 Caddy 服务的互联网可达机器。从源码结构看reserve在部署了 Caddy 的情况下会触发一次实时的 DNS 记录创建这正是保留域名 自动路由这一自动化能力的关键衔接点。子命令二uc dns show— 查看集群域名uc dns show用于打印当前集群已保留的域名名称。语法与选项uc dns show [flags]选项说明-h, --help显示show命令的帮助信息执行流程与示例$ uc dns show abc123.uncld.dev对应实现见 cmd/uc/dns/show.goCLI 连接集群后调用GetDomainRPC若集群尚未保留域名返回api.ErrNotFound则报错no domain reserved否则直接打印域名名称。从客户端角度看pkg/client/dns.go中的GetDomain方法把服务端返回的 gRPCNotFound状态码统一转换为api.ErrNotFound供 CLI 层做友好的错误分支判断pkg/client/dns.go。子命令三uc dns release— 释放集群域名uc dns release释放当前集群已保留的域名释放后该域名不再属于该集群。语法与选项uc dns release [flags]选项说明-h, --help显示release命令的帮助信息执行流程与示例$ uc dns release Released cluster domain: abc123.uncld.dev对应实现见 cmd/uc/dns/release.goCLI 连接集群后调用ReleaseDomainRPC若集群本来就没有保留域名gRPCNotFound则报错no domain reserved否则输出Released cluster domain: domain。深入原理域名保留与 DNS 记录在集群端如何落地1. 域名的持久化存储保留动作真正发生在集群端。internal/machine/cluster/dns.go中的ReserveDomain实现展示了完整链路internal/machine/cluster/dns.go校验集群就绪、校验Endpoint非空否则返回codes.InvalidArgumentAPI endpoint not set检查 store 中是否已存在保留域名若存在返回codes.AlreadyExistsdomain already reserved通过dns.NewClient()调用 Uncloud DNS 服务的POST {endpoint}/domains接口获取域名name与鉴权token将Endpoint、Name、Token序列化为 JSON存入集群 store 的uncloud_dns键internal/machine/cluster/dns.go中uncloudDNSKey常量见 internal/machine/cluster/dns.go其中 token 目前以明文形式存储源码中留有TODO: encrypt the token in the store注释。GetDomain与ReleaseDomain同样围绕 store 中的uncloud_dns键操作读取并反序列化storedDomain或直接store.Delete删除该键。从源码结构看ReleaseDomain目前仅删除本地存储记录释放远端 DNS 域名的端点调用在代码中以TODO: implement and call Uncloud DNS endpoint to release/delete the domain.标注待实现internal/machine/cluster/dns.go。2. DNS 记录如何写入A / AAAA 通配记录当 Caddy 服务已部署时CLI 会调用caddy.UpdateDomainRecords最终触发CreateIngressRecords见 pkg/client/dns.go。其关键步骤为检查运行 Caddy 服务的所有容器收集其所在机器的MachineID只保留具有公网 IPPublicIp非空的机器并发地向每台机器的http://public-ip/.uncloud-verify路径发送 HTTP 请求verifyCaddyReachable配合指数退避重试最大间隔 1s、最长 5sHTTP 客户端超时 3s仅当响应状态为200 OK且响应体内容与该机器的MachineID完全一致时才判定该机器从互联网可达且 Caddy 正确响应pkg/client/dns.go。这一校验用于确保响应来自正确的 Caddy 容器避免 NAT、防火墙或错误实例造成的误判将可达机器的公网 IP 按 IPv4 / IPv6 分类生成两条通配 DNS 记录pkg/client/dns.go*类型A值为所有可达机器的 IPv4 公网地址*类型AAAA值为所有可达机器的 IPv6 公网地址若没有任何机器可达返回ErrNoReachableMachinesno internet-reachable machines running service containers调用集群端CreateDomainRecords由集群使用 store 中保存的域名与 token向 Uncloud DNS 的POST {endpoint}/domains/{domain}/records接口逐个写入记录internal/machine/cluster/dns.go。校验路径/.uncloud-verify是 Caddy 配置中的固定常量VerifyPath定义于 internal/machine/caddyconfig/controller.go同时出现在 Caddyfile 模板handle {{.VerifyPath}}internal/machine/caddyconfig/caddyfile.go与 JSON 配置的路由匹配中internal/machine/caddyconfig/jsonconfig.go。3. 与 Uncloud DNS 服务的 HTTP 交互internal/dns/client.go封装了与 DNS 服务的全部 HTTP 交互internal/dns/client.goReserveDomain(endpoint)POST {endpoint}/domains返回域名与鉴权 tokenCreateRecords(endpoint, domain, token, records)POST {endpoint}/domains/{domain}/records每条记录以Authorization: Bearer token头鉴权请求/响应模型定义于 internal/dns/api.go记录类型支持A与AAAA响应中的FQDN字段回传完整的记录域名错误处理HTTP401且响应体中data.noDomain为true时返回ErrAuthNoDomain提示需要重新保留域名其他非 2xx/3xx 状态码统一报错。需要注意该 DNS 客户端代码源自 acorn-io/runtime 项目的 pkg/dns源码注释明确注明The dns package code is based on https://github.com/acorn-io/runtime/blob/main/pkg/dns这一点仅供理解其设计来源。使用建议与前置条件先部署 Caddy 再考虑公网访问uc dns reserve只负责保留域名要让流量真正进入集群还需要通过uc caddy deploy部署 Caddy 反向代理服务否则 CLI 会明确提示你完成这一步。一个集群一个域名集群 store 中uncloud_dns键是单值存储重复reserve会得到domain already reserved错误需先release再重新保留。域名记录跟随可达性DNS 通配记录只包含通过公网校验能正确响应/.uncloud-verify且返回机器 ID的机器位于 NAT 或防火墙之后的机器不会被写入记录这保证了流量只被路由到真正可达的入口节点。结合自定义域名uc dns管理的uncld.dev域名是开箱即用的默认方案官方文档中关于发布服务与管理 Caddy 的更多细节可参考 2-ingress/2-publishing-services.md 与 2-ingress/3-managing-caddy.md。相关命令速查根命令总览uc子命令详情uc dns reserve、uc dns show、uc dns releaseCaddy 部署uc caddy deploy集群上下文管理uc ctx【免费下载链接】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），仅供参考