uncloud 集群 Caddy 反代部署实战深入解析uc caddy deploy命令【免费下载链接】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 caddy deploy是 Uncloud 的命令行工具uc中用于在集群全部或指定机器上部署、升级 Caddy 反向代理服务的关键命令。它负责把官方或自定义的 Caddy 镜像以全局服务的形式推送到各台 Docker 主机并在更新已有容器时执行滚动更新以最小化中断部署完成后还会自动同步集群域名解析确保流量能够到达运行 Caddy 的机器。读完本文你将掌握该命令的完整参数语义、四种典型使用场景以及它背后的部署计划、滚动更新与 DNS 同步原理从而安全、可控地在生产集群中维护入口网关。命令定位Uncloud 集群入口网关的一键升级入口在 Uncloud 中Caddy 被设计为集群的入口反向代理当集群通过uc machine init初始化时Caddy 会以全局服务global mode自动部署到每一台机器上负责接收入站的 HTTP/HTTPS 流量并按服务发布的端口路由到后端容器。uc caddy deploy就是针对这个内置caddy服务的管理命令之一与之配套的还有uc caddy config查看当前机器上由 Uncloud 自动生成并实际生效的 Caddyfile详见 cmd/uc/caddy/config.gouc caddy logs查看 Caddy 容器日志uc inspect caddy查看caddy服务状态及运行所在机器见 管理 Caddy 的概念文档。命令层级定义在 cmd/uc/caddy/root.godeploy子命令的实现位于 cmd/uc/caddy/deploy.go。语法与参数速查uc caddy deploy [flags]参数类型说明--caddyfile string文件路径自定义全局 Caddy 配置Caddyfile路径该配置会被前置拼接到自动生成的 Caddy 配置之前-h, --help布尔显示 deploy 帮助信息--image string镜像名要部署的 Caddy Docker 镜像帮助文本中的默认占位符为caddy:LATEST_VERSION-m, --machine strings字符串列表指定部署目标机器的名称或 ID可多次指定也支持逗号分隔列表默认为集群所有机器参数细节来自 uc_caddy_deploy.md 与命令实现 cmd/uc/caddy/deploy.go。关于--image默认值的重要说明CLI 帮助文本中展示的默认占位符是caddy:LATEST_VERSION但实际实现中该参数的默认值是空字符串。当未指定镜像时命令会调用LatestCaddyImage()实时查询 Docker Hub 上官方caddy镜像的最新2.x.x稳定版本标签详见下文版本解析小节因此uc caddy deploy等价于升级到当前最新稳定版。此外deploy还继承了uc caddy及uc的全局参数参数说明--connect string不使用 Uncloud 配置文件直接连接远程集群机器支持[ssh://]userhost[:port]、sshgo://userhost[:port]、tcp://host:port、unix:///path/to/uncloud.sock格式可用环境变量$UNCLOUD_CONNECT替代-c, --context string使用的集群上下文名称默认当前上下文可用环境变量$UNCLOUD_CONTEXT替代--uncloud-config stringUncloud 配置文件路径默认~/.config/uncloud/config.yaml可用环境变量$UNCLOUD_CONFIG替代场景一部署/升级到最新稳定版集群刚初始化、或希望将入口网关升级到官方最新稳定版本时直接执行uc caddy deploy命令执行流程对应 runDeploy连接集群ConnectCluster读取当前上下文/连接配置检查现有caddy服务若尚未运行会打印service: caddy (not running)若已在运行则打印服务名、模式global以及当前容器使用的镜像当检测到多台机器运行着不同版本镜像时会明确提示current images (multiple versions detected): ...由于未指定镜像命令会在创建部署时通过LatestCaddyImage()解析最新稳定版本并在计划生成后打印target image: caddy:X.Y.Z (latest stable)生成部署计划并展示等待用户确认后执行。命令执行成功后还可以用uc inspect caddy核对每台机器上的容器镜像与运行状态输出示例来自管理 Caddy 文档ID: b5b269d5dc5ed4fdae6542894f94de82 Name: caddy Mode: global CONTAINER ID IMAGE CREATED STATUS MACHINE fb8f390e634d caddy:2.10.0 3 weeks ago Up 3 weeks prod-ap1 0182f5d7bd9f caddy:2.10.0 3 months ago Up 3 weeks prod-us1版本解析的源码实现LatestCaddyImage()位于 pkg/client/caddy.go其策略是通过go-containerregistry的remote.List拉取 Docker Hub 上caddy仓库的全部 tag用正则^2\.\d\.\d$过滤出2.x.x形态的稳定版本 tag排除了latest、alpine、builder等变体借助Masterminds/semver比较语义化版本选出数值上最新的 tag若找不到任何符合格式的 tag则回退到latesttag。这也解释了帮助文本中caddy:LATEST_VERSION的含义LATEST_VERSION不是固定值而是每次部署时动态计算出来的最新 2.x 稳定版。场景二部署/升级到指定镜像版本当需要固定版本例如配合 Cloudflare 插件镜像或回滚到旧版本时使用--imageuc caddy deploy --image caddybuilds/caddy-cloudflare:2.10.2指定后命令会直接以该镜像为目标打印target image: ...以绿色高亮并进入同样的计划-确认-执行流程。场景三只部署到部分机器默认情况下 Caddy 会部署到集群所有机器如需定向操作例如灰度升级某个区域的机器、或某台机器暂时下线维护使用-m/--machineuc caddy deploy --machine machine1 uc caddy deploy --machine machine2,machine3,machine4该参数支持重复指定与逗号分隔两种写法内部会经cli.ExpandCommaSeparatedValues展开后作为api.Placement的机器约束传入部署对象见 cmd/uc/caddy/deploy.go。当首次部署且显式指定了机器时确认提示前会打印 This will run a Caddy container on each selected machine.否则打印 on each machine.。场景四携带自定义全局 Caddyfile需要注入全局配置如开启 debug、定义可复用的 snippet或为 Uncloud 不管理的内部服务配置反向代理时uc caddy deploy --caddyfile global.Caddyfile自定义配置会在本地被读取并去除首尾空白strings.TrimSpace然后作为CaddySpec.Config写入服务规格Uncloud 控制器在生成最终 Caddyfile 时会把它前置到自动生成内容之前见 pkg/client/caddy.go。示例配置文件# Global options. { debug } # A snippet that can be reused in custom Caddy configs for services (x-caddy). (my_snippet) { ... } # Expose an internal service that is not managed by Uncloud. internal.example.com { reverse_proxy 192.168.1.100 }部署计划先展示、再确认、后执行uc caddy deploy不会在敲下回车后立即改动集群。它会先构造一个Deployment对象NewCaddyDeployment调用Plan()生成部署计划操作序列然后通过 TUI 展示给用户并请求确认展示内容包含服务级变更 create service caddy (global)或~ update service caddy (global)、镜像新旧对比同仓库仅展示 tag 差异如caddy:2.9.1 → 2.10.0跨仓库则展示完整镜像名、每台机器上的容器操作树以及一行汇总如2 create · 3 replace (start-first) · across 5 machines格式逻辑见 pkg/client/deploy/deploy.go确认提示会带上目标连接或上下文名称如 Proceed with deployment to prod-us1?防止误部署到错误集群若用户选择取消会输出Caddy deploy cancelled. No changes were made.并安全退出若计划中没有任何操作所有机器上的容器均已符合期望规格命令会直接输出caddy service is up to date.并结束不会重复无意义的部署。滚动更新机制最小化中断的全局服务升级文档强调A rolling update is performed when updating existing containers to minimise disruption其实现位于RollingStrategypkg/client/deploy/strategy.go。由于 Caddy 是全局服务每台机器最多一个容器滚动更新主要依赖planGlobalstrategy.go与reconcileGlobalContainerstrategy.go两个函数核心逻辑如下对每台符合调度约束的机器检查其现有容器规格与目标规格是否一致EvalContainerSpecChange已是最新的容器直接跳过避免无谓重启需要更新时生成ReplaceContainerOperation替换操作更新顺序由determineUpdateOrder决定strategy.go若新旧容器存在端口冲突Caddy 占用 80/443 主机端口必须先停旧再启新stop-first否则新容器无法绑定端口无冲突时默认先启新再停旧start-first让新容器接流后再回收旧容器将停机时间压到最低对不符合新放置约束的机器上残留容器生成RemoveContainerOperation清理。这种逐机替换、有端口冲突才先停后启的策略保证了升级过程中集群入口网关始终可用。此外Caddy 服务的规格细节定义在 pkg/client/caddy.go 的NewCaddyDeployment中值得注意运行命令固定为caddy run -c /config/Caddyfile环境变量CADDY_ADMINunix//run/caddy/admin.sock供 Uncloud 守护进程通过共享 admin socket 更新配置发布端口为80:80host、443:443hostTCP以及443:443hostUDP为 HTTP/3/QUIC 所需数据卷挂载/var/lib/uncloud/caddy映射到容器/config与/data持久化配置与证书等/run/uncloud/caddy映射到/run/caddy共享运行目录。部署完成后的 DNS 记录同步部署执行成功后命令并不会立即结束还会调用UpdateDomainRecordscmd/uc/caddy/deploy.go处理集群域名的解析记录如果集群没有保留域名未执行过uc dns reserve会打印 Skipping DNS records update as no cluster domain is reserved (see uc dns). 并正常返回否则打印 Updating cluster domain records in Uncloud DNS to point to machines running caddy service...并调用CreateIngressRecordspkg/client/dns.go——它会对每台运行 Caddy 的机器公网 IP 发送 HTTP 探测只有正确返回本机机器 ID 的机器才会被纳入 DNS 记录最后打印形如*.example.com A → 1.2.3.4, 5.6.7.8的记录明细。需要特别注意的失败场景若没有任何运行 Caddy 的机器可以从公网访问返回client.ErrNoReachableMachines命令会打印明确的解决建议包括确保机器拥有公网 IP添加机器时使用--public-ip标志覆盖自动探测的 IP检查机器上的防火墙设置位于 NAT 之后时配置端口转发解决连通性问题后重新执行uc caddy deploy重试。同时会提示在至少一台机器可达之前服务无法从互联网访问若本就不打算对外暴露任何服务可以执行uc dns release释放域名。验证与排障部署完成后建议按以下顺序验证查看服务状态uc inspect caddy确认每台机器上的容器镜像、创建时间与运行状态符合预期核对生效配置uc caddy config查看该机器上实际生效的完整 Caddyfile自动生成头 用户全局配置 各服务x-caddy配置 由服务端口生成的站点块便于确认自定义配置是否正确拼装无效的用户配置会以注释形式被跳过并附上错误原因详见生成逻辑与 uc caddy config 参考文档查看运行日志uc caddy logs排查 Caddy 启动、TLS 证书签发或反向代理错误确认域名解析部署输出中会打印更新后的 DNS 记录可结合uc dns show复核。小结uc caddy deploy是 Uncloud 集群入口网关的一站式管理命令不指定镜像即升级到最新稳定版指定镜像可固定版本或回滚--machine支持灰度与定向部署--caddyfile支持注入全局配置其内部通过部署计划预览、人工确认、基于RollingStrategy的全局滚动更新以及部署后的公网可达性探测与 DNS 同步把入口网关的升级风险降到最低。相关命令与文档可继续参阅uc caddy父命令uc caddy config管理 Caddy 概念指南含 Compose 方式管理 Caddy 的完整示例命令实现cmd/uc/caddy/deploy.go、pkg/client/caddy.go滚动更新实现pkg/client/deploy/strategy.goDNS 记录同步pkg/client/dns.go【免费下载链接】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），仅供参考