Uncloud 服务部署指南uc 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/uncloud导读uc deploy是 Uncloud 中从 Compose 文件部署服务的核心命令它把 Docker Compose 的声明式描述转换成跨集群机器的实际部署动作构建/推送镜像、调度容器、执行滚动更新、管理卷与配置。本文基于官方命令参考文档与仓库源码cmd/uc/deploy.go 及其下游实现展开讲解每一个参数的含义与生效时机、一次完整部署的内部工作流、滚动更新策略的原理以及 Uncloud 专有的 Compose 扩展x-machines、x-ports、x-caddy、x-pre_deploy读完你可以熟练地用uc deploy把任意 Compose 应用发布到 Uncloud 集群并理解它在底层做了什么。命令概述与语法uc deploy用于从 Compose 文件部署服务是 Uncloud 中最常用的发布入口。它的语法为uc deploy [FLAGS] [SERVICE...] [flags]命令位于service命令组下其定义与参数声明见 cmd/uc/deploy.go。其中[SERVICE...]是可选参数当指定了服务名时只部署这些服务且默认包含它们的依赖服务与docker compose的行为一致见 cmd/uc/deploy.go。命令还注册了服务名补全功能ValidArgsFunction调用completion.ComposeServices在支持 Cobra 补全的 shell 中可对 Compose 服务名自动补全。典型用法示例# 使用当前目录下的 compose.yaml 部署全部服务 uc deploy # 只部署某个服务连同其依赖 uc deploy api # 指定 Compose 文件、启用 profile、非交互自动确认 uc deploy -f compose.yaml -f compose.override.yaml -p staging -y参数详解部署专属选项参数类型说明--build-arg VARVALUEstringArray为服务设置构建时变量对应 Dockerfile 中ARG声明的变量可多次指定--build-pullbool构建服务镜像前总是尝试拉取更新的基础镜像版本-f, --filestrings一个或多个 Compose 文件默认compose.yaml可多次传递以叠加--no-buildbool部署前不构建新镜像跳过有 build 配置的服务的镜像构建--no-cachebool构建镜像时不使用缓存-p, --profilestrings启用一个或多个 Compose profiles--recreatebool即使容器配置和镜像未变化也强制重建--skip-healthbool跳过新容器启动后的监控期与健康检查用于快速紧急部署。注意若新容器未能正常启动可能造成停机-y, --yesbool自动确认部署计划。在非交互环境如 CI/CD 管道中必须显式设置可用环境变量UNCLOUD_AUTO_CONFIRM替代这些标志在 cmd/uc/deploy.go 中逐一注册其中--yes通过cli.BindEnvToFlag与UNCLOUD_AUTO_CONFIRM环境变量绑定见 cmd/uc/deploy.go。从父命令继承的全局选项参数说明--connect直接连接远程集群机器而不使用 Uncloud 配置文件格式为[ssh://]userhost[:port]、sshgo://userhost[:port]、tcp://host:port或unix:///path/to/uncloud.sock可用环境变量UNCLOUD_CONNECT替代-c, --context要使用的集群上下文名称默认使用当前上下文可用环境变量UNCLOUD_CONTEXT替代--uncloud-configUncloud 配置文件路径默认~/.config/uncloud/config.yaml可用环境变量UNCLOUD_CONFIG替代一次部署的完整工作流从源码看runDeploycmd/uc/deploy.go把一次uc deploy拆解为如下阶段1. 加载并解析 Compose 项目compose.LoadProjectpkg/client/compose/project.go基于 compose-go 库解析 Compose 文件并注册了若干 Uncloud 专属的默认值与校验规则deploy.update_config未显式指定monitor时填入默认监控时长api.DefaultHealthMonitorPeriod默认为 5 秒见 pkg/api/container.go卷挂载源为相对路径以.或~开头时报错提示改用绝对路径或使用 configs展开x-command形式的 secrets 简写为driver: exec并校验 external secrets 不被支持依次应用os.Environment、.env文件可用COMPOSE_DISABLE_ENV_FILE禁用、COMPOSE_FILE环境变量与默认 Compose 文件查找逻辑注册四个扩展解析器x-caddy、x-machines、x-ports、x-pre_deploy见 pkg/client/compose/project.go。如果指定了[SERVICE...]此处会调用project.WithSelectedServices只保留目标服务及其依赖--profile选项通过composecli.WithDefaultProfiles启用对应 profiles见 cmd/uc/deploy.go。2. 构建镜像如需要cli.ServicesThatNeedBuild会找出所有带build配置的服务若未加--no-build则调用BuildServices先在本机构建镜像构建参数--build-arg、--build-pull、--no-cache在此阶段生效再逐个推送到集群机器见 cmd/uc/deploy.go。推送目标遵循x-machines扩展若服务声明了x-machines只推送到这些机器否则推送到集群中全部机器pushOpts.AllMachines true以确保后续任意机器上都能启动该镜像。推送过程会收集每个镜像的错误并在最后用errors.Join合并返回保证尽量推送完所有镜像。3. 连接集群并解析 Secrets连接集群后若项目包含secret://name引用compose.HasCommandSecretRefs会先输出 Resolving secrets... 提示再通过compose.ResolveSecrets把命令式 secret 解析为实际值见 cmd/uc/deploy.go。4. 生成并展示部署计划compose.NewDeploymentWithStrategy会先scheduler.InspectClusterState检查整个集群的当前状态机器、容器、卷并获取集群域名用于生成内部 DNS 与端口映射随后composeDeploy.Plan生成部署计划见 pkg/client/compose/deploy.go按依赖顺序graph.InDependencyOrder把每个 Compose 服务转换成api.ServiceSpec检查 external volumes 是否在集群中存在缺失即报错对需要创建的项目卷调用卷调度器生成创建操作见 pkg/client/compose/deploy.go为每个服务调用部署策略生成操作序列无变更no-op的服务计划会被跳过。若所有服务都已是最新状态直接输出 Services are up to date. 并退出见 cmd/uc/deploy.go。否则打印格式化后的Deployment plan包含目标 context 或直连地址、逐服务的操作清单并请求确认。确认逻辑是uc deploy防误操作的关键见 cmd/uc/deploy.go未加--yes且终端不可用时直接报错退出cannot ask to confirm deployment plan in non-interactive mode, use --yes flag or set UNCLOUD_AUTO_CONFIRMtrue to auto-confirm——这正是 CI/CD 场景必须设置-y的原因确认提示会带上目标集群名称context 或--connect地址避免误部署到错误的集群。5. 执行计划确认后通过plan.Execute在进度条标题Deploying to ...下依次执行操作序列。若执行失败命令会自动定位失败点若失败发生在 pre-deploy hookoperation.PreDeployHookError打印失败 hook 容器的最近日志若失败是容器健康检查未通过operation.ContainerHealthError打印失败容器日志日志行数默认取最近 10 行可用环境变量UNCLOUD_FAILED_CONTAINER_LOGS_TAIL覆盖见 cmd/uc/deploy.go日志抓取失败时还会提示手动执行uc logs serviceName/containerID查看见 cmd/uc/deploy.go。滚动更新策略RollingStrategy原理uc deploy默认使用deploy.RollingStrategypkg/client/deploy/strategy.go其两个字段直接对应 CLI 参数ForceRecreate←--recreate为 true 时所有容器都被判定为ContainerNeedsRecreate无视规格是否变化SkipHealthMonitor←--skip-health为 true 时新启动的容器跳过监控期与健康检查对应RunContainerOperation/ReplaceContainerOperation上的SkipHealthMonitor字段。策略接口Strategypkg/client/deploy/strategy.go的Type()返回rollingPlan按服务模式分流副本服务replicated对于deploy.replicas: N的副本服务pkg/client/deploy/strategy.go通过调度器筛选出满足约束placement 等的可用机器随机打乱机器顺序避免每次部署都优先落到同一批机器按含最新容器 含旧容器 空机器的优先级排序机器采用 round-robin 方式把副本均匀铺开机器上已存在且规格匹配的容器直接跳过ContainerUpToDate不匹配的生成ReplaceContainerOperation替换多余的生成RemoveContainerOperation清理。全局服务globaldeploy.mode: global的服务在每个可用机器上保证恰好一个容器pkg/client/deploy/strategy.go无容器则创建有同规格容器则保留并清理多余容器规格不匹配则替换且若新旧容器存在主机端口冲突会先停止旧容器再启动新容器见reconcileGlobalContainerpkg/client/deploy/strategy.go。更新顺序的自动判定替换容器时determineUpdateOrderpkg/client/deploy/strategy.go决定先停旧再启新stop-first还是先启新再停旧start-first用户在deploy.update_config.order中显式指定的值优先新旧端口冲突时必须 stop-first端口需先释放单副本且挂载了数据卷的服务默认 stop-first防止数据损坏其余情况默认 start-first以最小化停机时间。这些分支逻辑有完整的单元测试覆盖例如单副本数据卷默认 stop-first多副本数据卷默认 start-first显式 start-first 覆盖卷默认值等场景见 pkg/client/deploy/strategy_test.go。Uncloud 的 Compose 扩展在标准 Compose 字段之外uc deploy支持四个 Uncloud 专属扩展全部在加载阶段解析pkg/client/compose/project.go并在ServiceSpecFromCompose中映射为服务规格pkg/client/compose/service.gox-machines指定部署机器把服务限制到指定的机器集合可以是字符串、逗号分隔字符串或字符串数组解析逻辑见 pkg/client/compose/machines.goservices: db: image: postgres:16 x-machines: [machine-1, machine-2]它同时影响镜像推送目标与容器调度目标spec.Placement.Machines。不指定时服务默认可调度到集群全部机器镜像也推送到全部机器。x-ports发布服务端口声明对外发布的端口映射格式为host:port/proto或containerPorthost见 pkg/client/compose/port.goservices: web: image: nginx:latest x-ports: - web.example.com:80/https # 通过 Caddy 反向代理到域名 - 8000/http # 直接发布端口 - 5000:3000host # 容器 3000 映射到主机 5000x-caddy声明式 Caddy 配置直接为服务提供 Caddyfile 片段由 Uncloud 的 Caddy 控制器统一管理。模板函数{{ upstreams 80 }}会展开为服务副本的地址列表services: api: image: myapp:1.2.3 x-caddy: | api.example.com { reverse_proxy {{ upstreams 80 }} }注意x-ports与x-caddy互斥见 pkg/client/compose/service.go 及测试夹具中的注释。x-pre_deploy部署前钩子在新版本容器启动前先在目标机器上运行一个一次性任务容器典型场景数据库迁移配置项与校验见 pkg/client/compose/predeploy.goservices: app: image: myapp:1.2.3 x-pre_deploy: command: [sh, -c, python manage.py migrate] environment: DB_HOST: localhost privileged: false timeout: 2m30s user: root钩子容器与主容器运行在同一台机器上旧版本的钩子容器会被清理见 pkg/client/deploy/strategy.go。command为必填项。完整部署示例以下是一个同时运用多种特性的 Compose 文件综合自仓库测试夹具 pkg/client/compose/testdata/compose-full-spec.yaml覆盖了uc deploy支持的绝大多数字段services: web: image: nginx:latest build: context: . command: [nginx, -g, daemon off;] environment: VAR: value healthcheck: test: [CMD, curl, -f, http://localhost] interval: 1m30s timeout: 10s retries: 5 start_period: 15s deploy: replicas: 3 update_config: order: start-first stop_grace_period: 30s pull_policy: always volumes: - data1:/data1 - /path/on/host:/path/in/container:ro x-ports: - web.example.com:80/https x-pre_deploy: command: [sh, -c, echo running migrations] worker: image: worker:1.0 build: context: ./worker deploy: replicas: 2 x-machines: [machine-2] volumes: data1:执行发布构建 → 推送 → 展示计划 → 确认 → 滚动更新uc deploy -f compose.yaml -p production -y --build-arg VERSION1.2.3发布期间控制台会依次显示镜像构建/推送进度、Deployment plan 清单、确认提示若未加-y、最终 Deploying to 的进度输出。若某容器健康检查失败命令会自动打印该容器最近 10 行日志辅助排查无需额外执行uc logs。常见问题与注意事项CI/CD 中部署卡住非交互终端下未加-y会直接报错退出。请设置-y或环境变量UNCLOUD_AUTO_CONFIRMtrue。服务没变化却想强制重建使用--recreate它会无视规格比对强制替换所有容器。紧急恢复时希望尽快起新容器使用--skip-health跳过监控期但要注意新容器若启动失败可能造成停机。x-ports与x-caddy不能同时使用二者均涉及流量入口声明加载阶段会校验互斥。external volumes 缺失部署前会校验所有external: true的卷必须已存在于集群否则报错列出缺失卷名可用uc volume create预先创建。相对路径 bind mount 被拒绝挂载源以.或~开头会被校验拦截请改用绝对路径或考虑使用 configs。相关命令uc deploy与uc service系列命令配合可完成部署后的日常运维停止/启动/扩缩容/查看日志见 uc_service_ls 等页面镜像管理见 uc_image_push更完整的 Compose 特性支持矩阵可参考 8-compose-file-reference。【免费下载链接】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），仅供参考