Uncloud 集群反向代理管理指南uc caddy命令详解与实战【免费下载链接】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是 Uncloud CLI 中用于管理集群级 Caddy 反向代理服务的命令组。在 Uncloud 中Caddy 作为全局服务自动部署在集群的每一台机器上负责接收外部 HTTP/HTTPS 流量并将其路由到各个业务服务。阅读本文后你将掌握uc caddy三个子命令deploy、config、logs的完整用法、参数语义以及部署升级、配置校验、日志排查的实战方案并理解 Caddyfile 自动生成机制背后的源码实现。命令总览一个入口管理三种操作uc caddy是管理 Caddy 反向代理服务的根命令其下挂载三个子命令分别对应生命周期管理、配置查看与日志跟踪子命令作用uc caddy deploy在集群所有机器上部署或升级 Caddy 反向代理支持滚动更新uc caddy config显示当前 Caddy 配置Caddyfileuc caddy logs查看 Caddy 日志根命令本身只有-h, --help一个选项。从源码看子命令的注册发生在 cmd/uc/caddy/root.go 的NewRootCommand()函数中依次挂载NewConfigCommand()、NewDeployCommand()、NewLogsCommand()三个构造器。如果你只记得log这个别名也没有关系——uc caddy logs在 cmd/uc/caddy/logs.go 中定义了Aliases: []string{log}两种写法等价。继承自父命令的全局选项与所有uc子命令一样uc caddy继承了来自uc根命令的全局选项用于控制连接目标与配置文件也可通过环境变量注入--connect string Connect to a remote cluster machine without using the Uncloud configuration file. [$UNCLOUD_CONNECT] Format: [ssh://]userhost[:port], sshgo://userhost[:port], tcp://host:port, or unix:///path/to/uncloud.sock -c, --context string Name of the cluster context to use (default is the current context). [$UNCLOUD_CONTEXT] --uncloud-config string Path to the Uncloud configuration file. [$UNCLOUD_CONFIG] (default ~/.config/uncloud/config.yaml)--connect绕过 Uncloud 配置文件直接连接远程集群机器。支持ssh://缺省 scheme 时也按 SSH 处理、sshgo://、tcp://和unix://四种格式。例如uc caddy config --connect ssh://user10.0.0.5。-c, --context指定要使用的集群上下文名称默认使用当前上下文对应uc ctx管理的能力。--uncloud-config指定 Uncloud 配置文件路径默认~/.config/uncloud/config.yaml。部署或升级 Caddyuc caddy deployCaddy 会在uc machine init初始化集群时自动作为全局服务caddy部署默认运行在每一台机器上详见「Managing Caddy」。uc caddy deploy负责把这一全局服务部署或升级到集群的指定机器集合上。完整参数--caddyfile string Path to a custom global Caddy config (Caddyfile) that will be prepended to the auto-generated Caddy config. --image string Caddy Docker image to deploy. (default caddy:LATEST_VERSION) -m, --machine strings Machine names or IDs to deploy to. Can be specified multiple times or as a comma-separated list. (default is all machines) -h, --help help for deploy参数默认值说明--caddyfile空自定义全局 Caddy 配置Caddyfile文件路径其内容会被前置拼接到 Uncloud 自动生成的 Caddy 配置之前--imagecaddy:LATEST_VERSION要部署的 Caddy Docker 镜像不指定时使用最新稳定版-m, --machine全部机器目标机器名称或 ID可多次指定或用逗号分隔列表典型用法更新到 Docker Hub 上的最新稳定版 Caddy 镜像uc caddy deploy部署指定版本或自定义镜像例如带 Cloudflare DNS 插件、可做通配符证书的构建版本uc caddy deploy --image caddybuilds/caddy-cloudflare:2.10.2只部署到某一台机器或一个机器子集逗号分隔列表StringSlice类型同时支持多次-m累加uc caddy deploy --machine machine1 uc caddy deploy --machine machine2,machine3,machine4携带自定义全局配置部署uc caddy deploy --caddyfile global.Caddyfile一个可复用的全局 Caddyfile 示例官方文档「Managing Caddy」中原样提供# 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 }注意--caddyfile的内容只是被前置拼接prepend到自动生成的配置之前用于注入全局选项{ debug }、可复用片段snippet以及 Caddy 未纳管的站点定义而站点路由如https://app.example.com → :8000仍由 Uncloud 根据服务的发布端口自动生成。部署流程从计划到执行的完整链路结合 cmd/uc/caddy/deploy.go 的runDeploy()实现一次部署会经历以下阶段读取自定义 Caddyfile若指定了--caddyfile先读取文件内容并TrimSpace去除首尾空白deploy.go。检查现有服务状态通过clusterClient.InspectService(ctx, client.CaddyServiceName)查询caddy服务当前状态deploy.go。若服务未运行会打印service: caddy (not running)若正在运行则显示其Mode通常是global、当前镜像如果检测到多个容器镜像版本不一致还会专门提示current images (multiple versions detected)。生成部署计划调用clusterClient.NewCaddyDeployment(opts.image, caddyfile, placement)创建部署对象再d.Plan(ctx)计算出操作序列deploy.go。若计划为空直接输出service is up to date.——这意味着集群当前配置与目标一致不会做任何多余操作。展示计划并确认终端会先打印部署计划Deployment plan与摘要随后弹出确认提示Proceed with deployment?。当通过--connect直连或使用非默认上下文时确认标题中会明确带上目标集群标识例如Proceed with deployment to my-cluster?避免误部署到错误的集群deploy.go。取消部署会返回Caddy deploy cancelled. No changes were made.。执行部署确认后以进度条形式执行d.Run(ctx)标题形如Deploying service caddy (global mode)。若更新的是已存在的容器会执行滚动更新rolling update以最小化对线上流量的影响——这一点在NewDeployCommand的 Long 描述中明确承诺deploy.go。更新集群域名 DNS 记录UpdateDomainRecordsdeploy.go部署完成后若集群保留有域名通过uc dns管理会自动把域名的 A/AAAA 记录指向所有公网可达且运行着 Caddy 容器的机器随后打印更新后的记录清单app.example.com A 203.0.113.5等。第 6 步是整个部署链路的点睛之笔Uncloud 会先「验证到 caddy 服务的互联网可达性」Verifying internet access to caddy service。如果没有任何公网可达的机器运行 Caddy会打印ErrNoReachableMachines对应的错误与排障建议见下文「排障」小节提示服务在至少一台机器可达之前无法从互联网访问。用 Compose 文件管理 Caddy除 CLI 外也可以使用 Compose 文件获得更精细的控制例如用 Cloudflare DNS 挑战为*.example.com申请通配符 TLS 证书。完整示例见「Managing Caddy」的 Compose 章节核心片段如下services: caddy: image: caddybuilds/caddy-cloudflare:2.10.2 command: caddy run -c /config/Caddyfile environment: CADDY_ADMIN: unix//run/caddy/admin.sock env_file: # Contains CLOUDFLARE_API_TOKENxxxxx - .env.secrets volumes: - /var/lib/uncloud/caddy:/data - /var/lib/uncloud/caddy:/config - /run/uncloud/caddy:/run/caddy x-ports: - 80:80host - 443:443host - 443:443/udphost x-caddy: Caddyfile deploy: mode: global:::warning 注意 官方文档明确警告command、environment、volumes与x-ports这四个属性对 Caddy 在 Uncloud 集群中正常工作至关重要不要改动卷挂载的源路径——Uncloud daemon 依赖这些路径与 Caddy 通信并更新其配置详见 3-managing-caddy.md 的 info 提示。 :::随后执行uc deploy即可按 Compose 文件部署或更新caddy服务。若只需要部署到特定机器可取消x-machines的注释并按需填写。查看当前 Caddy 配置uc caddy configuc caddy config用于显示当前生效的 Caddyfile是调试与校验自定义配置x-caddy、--caddyfile的首选工具。完整参数-m, --machine string Name or ID of the machine to get the configuration from. (default is connected machine) --no-color Disable syntax highlighting for the output. -h, --help help for config参数说明-m, --machine从指定机器名称或 ID获取配置缺省时从当前连接的机器获取--no-color关闭输出语法高亮输出纯文本实现细节源码 cmd/uc/caddy/config.go 揭示了两个值得注意的实现点指定机器时走代理上下文当-m非空时代码先执行ctx clusterClient.ProxySingleMachineContext(ctx, opts.machine)即通过集群客户端把请求代理到目标机器再调用clusterClient.Caddy.GetConfig(ctx, nil)取回该机器上的 Caddyfileconfig.go。这意味着即使你当前连接的机器与目标机器不同也能准确拿到目标机器上的实际配置。语法高亮与降级默认使用 chroma 的quick.Highlight以caddy词法器、monokai配色输出终端高亮若高亮失败则自动降级为纯文本打印config.go。脚本化使用或管道重定向时建议加--no-color以获得干净输出。读懂自动生成的 Caddyfile官方文档「Publishing services」中的示例展示了uc caddy config的完整输出结构。生成的配置自上而下由四个部分拼接而成同样见 2-publishing-services.md文件头注释# Caddyfile autogenerated by Uncloud (DO NOT EDIT)标注生成时间戳并提示配置会在服务或健康状态变化时自动更新。用户定义的全局配置来自caddy服务自身的x-caddy或部署时指定的--caddyfile对应注释# User-defined global config from service caddy。健康检查端点Uncloud 自动为每台机器注入http://站点的/.uncloud-verify路径返回一串随机 token 用于验证 Caddy 可达性——这正是deploy流程第 6 步「验证互联网可达性」的判定依据。站点配置分为三块——由服务发布端口x-ports自动生成的站点例如https://app.example.com { reverse_proxy 10.210.1.3:8000 10.210.2.5:8000 { import common_proxy } }服务自定义的x-caddy站点例如www.example.com的 301 重定向被跳过的非法配置注释# Skipped invalid user-defined configs:每条都附上caddy adapt的校验错误原因。所有反向代理块都统一import common_proxy该片段由 Uncloud 注入负责被动健康检查lb_retries 3最多重试 3 次与fail_duration 30s请求失败后将该上游标记为不健康 30 秒。配置冲突与校验机制Uncloud 会用caddy adapt命令校验每个服务的自定义配置冲突或非法的配置会被跳过并以注释形式留在生成文件中方便排查但官方文档同时警告某些错误仍可能破坏整个配置导致 Caddy 加载失败此时应检查caddy服务日志来定位问题。核心约束是不同服务的自定义 Caddy 配置不得使用重复的 hostname多服务共享同一域名时只能由其中一个服务定义该域名用handle_path按路径分流详见 2-publishing-services.md 的「Multiple services on one domain」示例。查看 Caddy 日志uc caddy logs完整参数-f, --follow Continually stream new logs. -m, --machine strings Filter logs by machine name or ID. Can be specified multiple times or as a comma-separated list. --since string Show logs generated on or after the given timestamp. Accepts relative duration, RFC 3339 date, or Unix timestamp. -n, --tail string Show the most recent logs and limit the number of lines shown per replica. Use all to show all logs. (default 100) --until string Show logs generated before the given timestamp. Accepts relative duration, RFC 3339 date, or Unix timestamp. --utc Print timestamps in UTC instead of local timezone.参数默认值说明-f, --follow关持续流式输出新日志-m, --machine全部机器按机器名称或 ID 过滤日志可多次指定或逗号分隔--since无只看该时间点之后生成的日志接受相对时长、RFC 3339 日期或 Unix 时间戳-n, --tail100每个副本最近 N 行传all显示全部日志--until无只看该时间点之前生成的日志格式同--since--utc本地时区时间戳改用 UTC 输出--since支持三种时间格式官方文档给出的示例--since 2m30s 相对时长2 分 30 秒前 --since 1h 相对时长1 小时前 --since 2025-11-24 RFC 3339 纯日期本地时区午夜 --since 2024-05-14T22:50:00 RFC 3339 日期时间本地时区 --since 2024-01-31T10:30:00Z RFC 3339 日期时间UTC --since 1763953966 Unix 时间戳1970 年 1 月 1 日以来的秒数实现说明uc caddy logs本质上是uc service logs caddy的语法糖源码 cmd/uc/caddy/logs.go 的RunE会把参数改写为[caddy, ...]后直接调用service.RunLogs其帮助文本也明确写着This calls uc logs caddy。因此它继承了uc service logs的全部过滤能力——按机器过滤、时间窗口过滤、每副本行数截断这对定位「配置被跳过」或「整份配置加载失败」类问题非常实用当uc caddy config显示配置异常时执行uc caddy logs --since 1h即可查看 Caddy 进程是否报错、加载了哪份配置。排障DNS 记录更新失败怎么办当uc caddy deploy的最后阶段无法更新集群域名 DNS 记录没有任何公网可达的机器运行 Caddy 容器时CLI 会给出以下排查建议来自 deploy.go 的ErrNoReachableMachines分支确认机器具有公网 IP添加机器时用--public-ip标志覆盖自动探测到的 IP检查机器上的防火墙设置位于 NAT 之后时配置端口转发解决连通性问题后重新执行uc caddy deploy重试。如果本就不打算对外暴露任何服务也可以执行uc dns release释放集群域名从而跳过 DNS 记录更新。总结uc caddy是 Uncloud 集群入口流量的管理中枢deploy完成 Caddy 全局服务的部署、滚动升级与域名记录同步config提供对自动生成 Caddyfile 的透明可见性是校验x-ports、x-caddy与全局配置正确性的调试利器logs则复用uc service logs的完整过滤能力支撑配置与路由问题的快速定位。三者配合即可在一个命令行入口内完成 Uncloud 反向代理的「部署—校验—排查」闭环。如需深入了解 Caddy 的部署原理、服务端口发布格式[hostname:]container_port[/protocol]与 host 模式以及x-caddy模板函数{{upstreams}}、{{.Name}}、{{.Upstreams}}可继续阅读Managing Caddy部署与校验Publishing services端口发布与自定义 Caddy 配置uc caddy deploy 命令参考uc caddy config 命令参考uc caddy logs 命令参考uc 根命令参考【免费下载链接】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），仅供参考 Uncloud 集群反向代理管理指南：`uc caddy` 命令详解与实战
Uncloud 集群反向代理管理指南uc caddy命令详解与实战【免费下载链接】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是 Uncloud CLI 中用于管理集群级 Caddy 反向代理服务的命令组。在 Uncloud 中Caddy 作为全局服务自动部署在集群的每一台机器上负责接收外部 HTTP/HTTPS 流量并将其路由到各个业务服务。阅读本文后你将掌握uc caddy三个子命令deploy、config、logs的完整用法、参数语义以及部署升级、配置校验、日志排查的实战方案并理解 Caddyfile 自动生成机制背后的源码实现。命令总览一个入口管理三种操作uc caddy是管理 Caddy 反向代理服务的根命令其下挂载三个子命令分别对应生命周期管理、配置查看与日志跟踪子命令作用uc caddy deploy在集群所有机器上部署或升级 Caddy 反向代理支持滚动更新uc caddy config显示当前 Caddy 配置Caddyfileuc caddy logs查看 Caddy 日志根命令本身只有-h, --help一个选项。从源码看子命令的注册发生在 cmd/uc/caddy/root.go 的NewRootCommand()函数中依次挂载NewConfigCommand()、NewDeployCommand()、NewLogsCommand()三个构造器。如果你只记得log这个别名也没有关系——uc caddy logs在 cmd/uc/caddy/logs.go 中定义了Aliases: []string{log}两种写法等价。继承自父命令的全局选项与所有uc子命令一样uc caddy继承了来自uc根命令的全局选项用于控制连接目标与配置文件也可通过环境变量注入--connect string Connect to a remote cluster machine without using the Uncloud configuration file. [$UNCLOUD_CONNECT] Format: [ssh://]userhost[:port], sshgo://userhost[:port], tcp://host:port, or unix:///path/to/uncloud.sock -c, --context string Name of the cluster context to use (default is the current context). [$UNCLOUD_CONTEXT] --uncloud-config string Path to the Uncloud configuration file. [$UNCLOUD_CONFIG] (default ~/.config/uncloud/config.yaml)--connect绕过 Uncloud 配置文件直接连接远程集群机器。支持ssh://缺省 scheme 时也按 SSH 处理、sshgo://、tcp://和unix://四种格式。例如uc caddy config --connect ssh://user10.0.0.5。-c, --context指定要使用的集群上下文名称默认使用当前上下文对应uc ctx管理的能力。--uncloud-config指定 Uncloud 配置文件路径默认~/.config/uncloud/config.yaml。部署或升级 Caddyuc caddy deployCaddy 会在uc machine init初始化集群时自动作为全局服务caddy部署默认运行在每一台机器上详见「Managing Caddy」。uc caddy deploy负责把这一全局服务部署或升级到集群的指定机器集合上。完整参数--caddyfile string Path to a custom global Caddy config (Caddyfile) that will be prepended to the auto-generated Caddy config. --image string Caddy Docker image to deploy. (default caddy:LATEST_VERSION) -m, --machine strings Machine names or IDs to deploy to. Can be specified multiple times or as a comma-separated list. (default is all machines) -h, --help help for deploy参数默认值说明--caddyfile空自定义全局 Caddy 配置Caddyfile文件路径其内容会被前置拼接到 Uncloud 自动生成的 Caddy 配置之前--imagecaddy:LATEST_VERSION要部署的 Caddy Docker 镜像不指定时使用最新稳定版-m, --machine全部机器目标机器名称或 ID可多次指定或用逗号分隔列表典型用法更新到 Docker Hub 上的最新稳定版 Caddy 镜像uc caddy deploy部署指定版本或自定义镜像例如带 Cloudflare DNS 插件、可做通配符证书的构建版本uc caddy deploy --image caddybuilds/caddy-cloudflare:2.10.2只部署到某一台机器或一个机器子集逗号分隔列表StringSlice类型同时支持多次-m累加uc caddy deploy --machine machine1 uc caddy deploy --machine machine2,machine3,machine4携带自定义全局配置部署uc caddy deploy --caddyfile global.Caddyfile一个可复用的全局 Caddyfile 示例官方文档「Managing Caddy」中原样提供# 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 }注意--caddyfile的内容只是被前置拼接prepend到自动生成的配置之前用于注入全局选项{ debug }、可复用片段snippet以及 Caddy 未纳管的站点定义而站点路由如https://app.example.com → :8000仍由 Uncloud 根据服务的发布端口自动生成。部署流程从计划到执行的完整链路结合 cmd/uc/caddy/deploy.go 的runDeploy()实现一次部署会经历以下阶段读取自定义 Caddyfile若指定了--caddyfile先读取文件内容并TrimSpace去除首尾空白deploy.go。检查现有服务状态通过clusterClient.InspectService(ctx, client.CaddyServiceName)查询caddy服务当前状态deploy.go。若服务未运行会打印service: caddy (not running)若正在运行则显示其Mode通常是global、当前镜像如果检测到多个容器镜像版本不一致还会专门提示current images (multiple versions detected)。生成部署计划调用clusterClient.NewCaddyDeployment(opts.image, caddyfile, placement)创建部署对象再d.Plan(ctx)计算出操作序列deploy.go。若计划为空直接输出service is up to date.——这意味着集群当前配置与目标一致不会做任何多余操作。展示计划并确认终端会先打印部署计划Deployment plan与摘要随后弹出确认提示Proceed with deployment?。当通过--connect直连或使用非默认上下文时确认标题中会明确带上目标集群标识例如Proceed with deployment to my-cluster?避免误部署到错误的集群deploy.go。取消部署会返回Caddy deploy cancelled. No changes were made.。执行部署确认后以进度条形式执行d.Run(ctx)标题形如Deploying service caddy (global mode)。若更新的是已存在的容器会执行滚动更新rolling update以最小化对线上流量的影响——这一点在NewDeployCommand的 Long 描述中明确承诺deploy.go。更新集群域名 DNS 记录UpdateDomainRecordsdeploy.go部署完成后若集群保留有域名通过uc dns管理会自动把域名的 A/AAAA 记录指向所有公网可达且运行着 Caddy 容器的机器随后打印更新后的记录清单app.example.com A 203.0.113.5等。第 6 步是整个部署链路的点睛之笔Uncloud 会先「验证到 caddy 服务的互联网可达性」Verifying internet access to caddy service。如果没有任何公网可达的机器运行 Caddy会打印ErrNoReachableMachines对应的错误与排障建议见下文「排障」小节提示服务在至少一台机器可达之前无法从互联网访问。用 Compose 文件管理 Caddy除 CLI 外也可以使用 Compose 文件获得更精细的控制例如用 Cloudflare DNS 挑战为*.example.com申请通配符 TLS 证书。完整示例见「Managing Caddy」的 Compose 章节核心片段如下services: caddy: image: caddybuilds/caddy-cloudflare:2.10.2 command: caddy run -c /config/Caddyfile environment: CADDY_ADMIN: unix//run/caddy/admin.sock env_file: # Contains CLOUDFLARE_API_TOKENxxxxx - .env.secrets volumes: - /var/lib/uncloud/caddy:/data - /var/lib/uncloud/caddy:/config - /run/uncloud/caddy:/run/caddy x-ports: - 80:80host - 443:443host - 443:443/udphost x-caddy: Caddyfile deploy: mode: global:::warning 注意 官方文档明确警告command、environment、volumes与x-ports这四个属性对 Caddy 在 Uncloud 集群中正常工作至关重要不要改动卷挂载的源路径——Uncloud daemon 依赖这些路径与 Caddy 通信并更新其配置详见 3-managing-caddy.md 的 info 提示。 :::随后执行uc deploy即可按 Compose 文件部署或更新caddy服务。若只需要部署到特定机器可取消x-machines的注释并按需填写。查看当前 Caddy 配置uc caddy configuc caddy config用于显示当前生效的 Caddyfile是调试与校验自定义配置x-caddy、--caddyfile的首选工具。完整参数-m, --machine string Name or ID of the machine to get the configuration from. (default is connected machine) --no-color Disable syntax highlighting for the output. -h, --help help for config参数说明-m, --machine从指定机器名称或 ID获取配置缺省时从当前连接的机器获取--no-color关闭输出语法高亮输出纯文本实现细节源码 cmd/uc/caddy/config.go 揭示了两个值得注意的实现点指定机器时走代理上下文当-m非空时代码先执行ctx clusterClient.ProxySingleMachineContext(ctx, opts.machine)即通过集群客户端把请求代理到目标机器再调用clusterClient.Caddy.GetConfig(ctx, nil)取回该机器上的 Caddyfileconfig.go。这意味着即使你当前连接的机器与目标机器不同也能准确拿到目标机器上的实际配置。语法高亮与降级默认使用 chroma 的quick.Highlight以caddy词法器、monokai配色输出终端高亮若高亮失败则自动降级为纯文本打印config.go。脚本化使用或管道重定向时建议加--no-color以获得干净输出。读懂自动生成的 Caddyfile官方文档「Publishing services」中的示例展示了uc caddy config的完整输出结构。生成的配置自上而下由四个部分拼接而成同样见 2-publishing-services.md文件头注释# Caddyfile autogenerated by Uncloud (DO NOT EDIT)标注生成时间戳并提示配置会在服务或健康状态变化时自动更新。用户定义的全局配置来自caddy服务自身的x-caddy或部署时指定的--caddyfile对应注释# User-defined global config from service caddy。健康检查端点Uncloud 自动为每台机器注入http://站点的/.uncloud-verify路径返回一串随机 token 用于验证 Caddy 可达性——这正是deploy流程第 6 步「验证互联网可达性」的判定依据。站点配置分为三块——由服务发布端口x-ports自动生成的站点例如https://app.example.com { reverse_proxy 10.210.1.3:8000 10.210.2.5:8000 { import common_proxy } }服务自定义的x-caddy站点例如www.example.com的 301 重定向被跳过的非法配置注释# Skipped invalid user-defined configs:每条都附上caddy adapt的校验错误原因。所有反向代理块都统一import common_proxy该片段由 Uncloud 注入负责被动健康检查lb_retries 3最多重试 3 次与fail_duration 30s请求失败后将该上游标记为不健康 30 秒。配置冲突与校验机制Uncloud 会用caddy adapt命令校验每个服务的自定义配置冲突或非法的配置会被跳过并以注释形式留在生成文件中方便排查但官方文档同时警告某些错误仍可能破坏整个配置导致 Caddy 加载失败此时应检查caddy服务日志来定位问题。核心约束是不同服务的自定义 Caddy 配置不得使用重复的 hostname多服务共享同一域名时只能由其中一个服务定义该域名用handle_path按路径分流详见 2-publishing-services.md 的「Multiple services on one domain」示例。查看 Caddy 日志uc caddy logs完整参数-f, --follow Continually stream new logs. -m, --machine strings Filter logs by machine name or ID. Can be specified multiple times or as a comma-separated list. --since string Show logs generated on or after the given timestamp. Accepts relative duration, RFC 3339 date, or Unix timestamp. -n, --tail string Show the most recent logs and limit the number of lines shown per replica. Use all to show all logs. (default 100) --until string Show logs generated before the given timestamp. Accepts relative duration, RFC 3339 date, or Unix timestamp. --utc Print timestamps in UTC instead of local timezone.参数默认值说明-f, --follow关持续流式输出新日志-m, --machine全部机器按机器名称或 ID 过滤日志可多次指定或逗号分隔--since无只看该时间点之后生成的日志接受相对时长、RFC 3339 日期或 Unix 时间戳-n, --tail100每个副本最近 N 行传all显示全部日志--until无只看该时间点之前生成的日志格式同--since--utc本地时区时间戳改用 UTC 输出--since支持三种时间格式官方文档给出的示例--since 2m30s 相对时长2 分 30 秒前 --since 1h 相对时长1 小时前 --since 2025-11-24 RFC 3339 纯日期本地时区午夜 --since 2024-05-14T22:50:00 RFC 3339 日期时间本地时区 --since 2024-01-31T10:30:00Z RFC 3339 日期时间UTC --since 1763953966 Unix 时间戳1970 年 1 月 1 日以来的秒数实现说明uc caddy logs本质上是uc service logs caddy的语法糖源码 cmd/uc/caddy/logs.go 的RunE会把参数改写为[caddy, ...]后直接调用service.RunLogs其帮助文本也明确写着This calls uc logs caddy。因此它继承了uc service logs的全部过滤能力——按机器过滤、时间窗口过滤、每副本行数截断这对定位「配置被跳过」或「整份配置加载失败」类问题非常实用当uc caddy config显示配置异常时执行uc caddy logs --since 1h即可查看 Caddy 进程是否报错、加载了哪份配置。排障DNS 记录更新失败怎么办当uc caddy deploy的最后阶段无法更新集群域名 DNS 记录没有任何公网可达的机器运行 Caddy 容器时CLI 会给出以下排查建议来自 deploy.go 的ErrNoReachableMachines分支确认机器具有公网 IP添加机器时用--public-ip标志覆盖自动探测到的 IP检查机器上的防火墙设置位于 NAT 之后时配置端口转发解决连通性问题后重新执行uc caddy deploy重试。如果本就不打算对外暴露任何服务也可以执行uc dns release释放集群域名从而跳过 DNS 记录更新。总结uc caddy是 Uncloud 集群入口流量的管理中枢deploy完成 Caddy 全局服务的部署、滚动升级与域名记录同步config提供对自动生成 Caddyfile 的透明可见性是校验x-ports、x-caddy与全局配置正确性的调试利器logs则复用uc service logs的完整过滤能力支撑配置与路由问题的快速定位。三者配合即可在一个命令行入口内完成 Uncloud 反向代理的「部署—校验—排查」闭环。如需深入了解 Caddy 的部署原理、服务端口发布格式[hostname:]container_port[/protocol]与 host 模式以及x-caddy模板函数{{upstreams}}、{{.Name}}、{{.Upstreams}}可继续阅读Managing Caddy部署与校验Publishing services端口发布与自定义 Caddy 配置uc caddy deploy 命令参考uc caddy config 命令参考uc caddy logs 命令参考uc 根命令参考【免费下载链接】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），仅供参考