Uncloud `uc service` 命令全解：集群服务生命周期管理的实战指南-港品优选

Uncloud`uc service`命令全解：集群服务生命周期管理的实战指南

【免费下载链接】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 service（别名uc svc）是 Uncloud CLI 中管理集群服务的核心命令组，覆盖服务从创建（run）、查看（ls/inspect）、诊断（logs/exec）、生命周期控制（start/stop/scale）到销毁（rm）的完整流程。本指南以官方 CLI 参考文档为骨架，结合仓库源码（cmd/uc/service/）与 API 定义（pkg/api/service.go），逐条解析每个子命令的语法、参数与底层原理，读完即可在真实集群中熟练完成服务的部署、扩缩容、排障与下线。

命令总览与全局继承选项

uc service根命令自身只有一个帮助选项：

-h, --help help for service

在源码中（cmd/uc/service/root.go），该命令通过NewRootCommand()注册了 9 个子命令：exec、inspect、ls、logs、rm、run、scale、start、stop，并定义了别名svc——这意味着uc svc ls与uc service ls完全等价。

所有子命令都继承以下三个父命令选项（在整篇文档的每个子命令帮助中都会出现）：

--connect string Connect to a remote cluster machine without using the Uncloud configuration file. [$UNCLOUD_CONNECT] Format: [ssh://]user@host[:port], ssh+go://user@host[: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")

三者分别用于：临时直连某台集群机器（支持 SSH、TCP、Unix Socket 等多种传输协议）、切换集群上下文、以及指定非默认位置的 Uncloud 配置文件。它们都支持对应的环境变量（UNCLOUD_CONNECT、UNCLOUD_CONTEXT、UNCLOUD_CONFIG），便于在 CI/CD 等非交互场景中使用。从源码看，每个子命令的执行都经由uncli.ConnectCluster(ctx)建立到集群的连接（如 cmd/uc/service/ls.go），即服务管理操作全部以整个集群为作用域，而非单台机器。

列出服务：`uc service ls`

uc service ls以表格形式列出集群中的全部服务，语法简洁：

uc service ls [flags]

其输出列包括NAME、MODE、REPLICAS、IMAGE、ENDPOINTS。源码（cmd/uc/service/ls.go）揭示了几点实用细节：

服务按名称排序；若集群中存在重名服务，表格会额外追加ID列用于区分——这是从源码可确认的行为（haveDuplicateNames检测逻辑）。
REPLICAS显示的是当前实际运行的容器数量（len(s.Containers)），而非期望副本数，因此在服务部分失败时该数字可能与--replicas不同。
ENDPOINTS来自服务已发布端口的汇总（s.Endpoints()）；若服务未发布端口但使用了自定义 Caddy 配置，则会显示(custom Caddy config)。

运行服务：`uc service run`

uc service run是从单个镜像直接创建服务的最主要命令，语法为：

uc service run IMAGE [COMMAND...] [flags]

IMAGE是必选参数，COMMAND...用于覆盖镜像默认的 CMD。下面按参数类别完整展开其全部选项。

身份与复制模式

参数	说明
`-n, --name string`	为服务指定名称；不指定时由 Uncloud 自动生成随机名（源码 cmd/uc/service/run.go 显示名称基于镜像名生成，用于进度标题展示）。
`--mode string`	复制模式：`replicated`（在若干台机器上运行指定数量的容器，默认值）或`global`（每台机器运行一个容器）。
`--replicas uint`	`replicated`模式下运行的容器数量，默认`1`；对`global`模式无效。

源码在 pkg/api/service.go 定义了模式常量ServiceModeReplicated = "replicated"与ServiceModeGlobal = "global"。ServiceSpec.SetDefaults()（pkg/api/service.go）会保证模式为空时默认取replicated，且replicated模式至少有一个副本。run命令在组装参数时会校验 mode 与 pull 策略的合法性（cmd/uc/service/run.go），非法值会直接报错。

镜像拉取策略

--pull string Pull image from the registry before running service containers ('always', 'missing', 'never'). (default "missing")

三种策略与 pkg/api/service.go 中定义的PullPolicyAlways、PullPolicyMissing、PullPolicyNever一一对应：always总是从仓库拉取；missing仅在目标机器本地没有该镜像时才拉取（默认值）；never从不拉取，要求镜像已存在于目标机器。

端口发布：`-p, --publish`

端口发布是让服务对外可访问的核心参数，格式灵活：

Format: [hostname:]container_port[/protocol] 或 [host_ip|host_prefix:]host_port:container_port[/protocol]@host Supported protocols: tcp, udp, http, https (default is tcp)

官方文档给出的完整示例：

-p 8080/https # 通过反向代理以默认 service-name.cluster-domain 主机名发布 HTTPS 端口 8080 -p app.example.com:8080/https # 通过反向代理以自定义主机名发布 HTTPS 端口 8080 -p 53:5353/udp@host # 将 UDP 端口 5353 绑定到宿主机的 53 端口 -p 192.168.76.0/24:53:5353/udp@host # 将 UDP 端口 5353 绑定到 192.168.76.0/24 前缀内所有宿主 IP 的 53 端口

要点解读：

不带@host的 http/https 端口属于 ingress（入站）模式，由集群内的 Caddy 反向代理转发；若未指定主机名且集群已保留域名，会自动使用service-name.cluster-domain。
带@host的端口属于 host 模式，直接绑定宿主机端口/IP，不经过反向代理。
每条-p可多次指定以发布多个端口；最终经 pkg/api/port.go 的ParsePortSpec解析为PortSpec。
校验规则（pkg/api/service.go）：ingress 模式的端口只支持http/https协议，tcp/udp必须走 host 模式。

资源限制：CPU、内存与共享内存

--cpu decimal 最大可用 CPU 核数，支持小数，如 0.5（半核）或 2.25（两核又四分之一） --memory bytes 最大可用内存，正整数加可选单位后缀 (b, k, m, g)，无后缀时默认字节 示例：1073741824、1024m、1g（三者均等于 1 GiB） --shm-size bytes 容器共享内存（挂载于 /dev/shm）上限，格式与 --memory 相同

这三个参数在源码中被解析为dockeropts.NanoCPUs与dockeropts.MemBytes类型（cmd/uc/service/run.go），最终写入ContainerSpec.Resources（CPU、Memory、SharedMemory），由 Docker 执行实际限制。

存储挂载：`-v, --volume`

Format: volume_name:/container/path[:ro|volume-nocopy] 或 /host/path:/container/path[:ro]

官方示例：

-v postgres-data:/var/lib/postgresql/data # 将命名卷 postgres-data 挂载到容器内 /var/lib/postgresql/data -v /data/uploads:/app/uploads # 将宿主机目录 /data/uploads 绑定挂载到 /app/uploads -v /host/path:/container/path:ro # 以只读方式绑定挂载宿主机目录或文件

源码 cmd/uc/service/run.go 的parseVolumeFlagValue揭示了底层解析细节：

挂载路径必须是绝对路径（以/开头），否则报错；
第三个字段支持ro/readonly（只读）与volume-nocopy（禁止 Docker 复制卷中既有内容）两种选项；
宿主机路径绑定挂载会被包装为内部名为bind-<随机4位后缀>的 Bind 类型卷，并自动创建宿主机路径（CreateHostPath: true）；
命名卷名称需符合 Docker 的受限命名规则，若想挂载宿主机路径却误写了非法名称，会得到明确报错提示；
卷挂载对调度有直接影响：服务容器会被调度到卷所在的那台机器上，这是 Uncloud 实现有状态服务的关键机制。

环境变量：`-e, --env`

-e, --env strings 为服务容器设置环境变量，可多次指定。 格式：VAR=value 或仅 VAR（使用本地环境中的同名变量值）

源码 cmd/uc/service/run.go 的parseEnv使用strings.Cut拆分=：带=时直接使用给定值；不带=时从本地进程环境（os.LookupEnv）读取同名变量值，便于将本机凭据安全地注入远端容器而无需写入 shell 历史。

运行身份与安全

-u, --user string User name or UID and optionally group name or GID used for running the command inside service containers. Format: USER[:GROUP] or UID[:GID]. If not specified, the user is set to the default user of the image. --privileged Give extended privileges to service containers. This is a security risk and should be used with caution. --entrypoint string Overwrite the default ENTRYPOINT of the image. Pass an empty string "" to reset it.

--user支持USER[:GROUP]或UID[:GID]两种形式，缺省时使用镜像默认用户；--privileged是文档明确标注的安全风险项，仅应在确有必要时使用；--entrypoint的“传空字符串重置”行为在源码 cmd/uc/service/run.go 中有明确实现：只有显式传入了空串（entrypointChanged为 true）才会把 Entrypoint 重置为空。

进程级限制与调度约束

--ulimit strings 设置容器资源限制，可多次指定。 Format: type=soft_limit[:hard_limit]，未指定 hard limit 时软硬限均取 soft limit。 示例： --ulimit nofile=1024:2048 打开文件数软限 1024、硬限 2048 --ulimit nproc=65535 进程数软硬限均为 65535 -m, --machine strings 按机器名称限定服务可运行的机器，可多次指定或用逗号分隔。 （默认：任意合适机器）

--ulimit复用 Docker CLI 的units.ParseUlimit解析逻辑（cmd/uc/service/run.go），结果以map[string]api.Ulimit形式写入资源规格；--machine则映射为api.Placement.Machines列表（pkg/api/placement.go），构成部署调度器做放置决策时的硬性约束。

自定义 Caddy 配置

--caddyfile string Path to a custom Caddy config (Caddyfile) for the service. Cannot be used together with non-@host published ports.

--caddyfile允许为服务提供自定义的 Caddy 反向代理配置（Caddyfile 文本，源码中会读取文件并去除首尾空白后存入CaddySpec.Config，见 cmd/uc/service/run.go）。它不能与非 host 模式的发布端口同时使用——这条约束与ServiceSpec.Validate()中的校验一致（pkg/api/service.go：自定义 Caddy 配置与 ingress 端口互斥）。

执行流程

run的执行链路（cmd/uc/service/run.go）为：解析并校验所有参数组装api.ServiceSpec→ 连接集群 → 调用RunService（以进度条展示“Running service (replicated mode)”）→InspectService获取运行结果 → 打印服务所有端点（每个•一行）。参数校验失败会在启动前直接返回明确错误，例如无效的复制模式、无效的拉取策略、格式错误的端口或挂载。

查看服务详情：`uc service inspect`

uc service inspect SERVICE [flags]

inspect输出单个服务的详细状态信息，包括其规格、副本容器分布与端点等。它也是scale等内部流程的前置调用（见下文scale源码中的clusterClient.InspectService），在 pkg/api/service.go 定义的Service类型聚合了服务规格与各机器上的容器状态。

查看服务日志：`uc service logs`

logs是跨集群聚合日志查看器，语法与示例都相当丰富：

uc service logs [SERVICE[/CONTAINER]...] [flags]

官方文档给出的示例全集：

# 查看某个服务的近期日志 uc logs web # 实时流式跟踪日志（follow 模式） uc logs -f web # 查看多个服务的日志 uc logs web api db # 查看 compose.yaml 中定义的全部服务的日志 uc logs # 每个副本只显示最近 20 行（默认 100 行） uc logs -n 20 web # 显示全部日志，不限行数 uc logs -n all web # 按时间范围过滤 uc logs --since 3h --until 1h30m web # 只查看指定副本（容器）的日志，CONTAINER 支持容器名、完整 ID 或唯一 ID 前缀 uc logs web/61d57fd3428f api/2f60 # 只查看运行在指定机器上的副本的日志 uc logs -m machine1,machine2 web api

参数说明：

参数	说明
`--file strings`	当未指定任何服务时，从 Compose 文件中加载服务名（默认`compose.yaml`，可用`--file`指定多个）。
`-f, --follow`	持续流式输出新产生的日志。
`-m, --machine strings`	按机器名称或 ID 过滤日志，可多次指定或用逗号分隔。
`--since string`	只显示该时间点之后生成的日志，支持相对时长、RFC 3339 日期或 Unix 时间戳。
`--until string`	只显示该时间点之前生成的日志，格式同`--since`。
`-n, --tail string`	每个副本最多显示最近的行数，默认`"100"`，传`all`显示全部。
`--utc`	时间戳使用 UTC 而非本地时区打印。

--since/--until的完整取值示例：

--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-01-01 起秒数）

特别地，logs支持SERVICE/CONTAINER形式精确定位到某个副本，其中CONTAINER可以是容器名、完整 ID 或唯一前缀（例如web/61d57fd3428f、api/2f60），这与exec的--container前缀匹配策略一致。

在容器中执行命令：`uc service exec`

exec用于在运行中的服务容器内执行命令，默认进入交互式 Shell：

uc service exec [OPTIONS] SERVICE [COMMAND ARGS...] [flags]

官方示例全集：

# 启动交互式 Shell（默认依次尝试 bash 或 sh） uc exec web-service # 显式指定命令启动交互式 Shell uc exec web-service /bin/zsh # 在指定容器中列出文件；--container 接受完整 ID 或唯一前缀 uc exec --container d792e web-service ls -la # 将本地输入通过管道送入容器内命令 cat backup.sql | uc exec -T db-service psql -U postgres mydb # 后台运行任务（detached 模式） uc exec -d web-service /scripts/cleanup.sh

参数说明：

参数	说明
`--container string`	指定要进入的容器 ID，接受完整 ID 或唯一前缀；不指定时，若服务有多个副本，命令会在随机一个容器中执行。
`-d, --detach`	分离模式：命令在后台运行。
`-T, --no-tty`	禁止分配伪终端（pseudo-TTY）；默认在连接终端时会自动分配 TTY。

-T对于管道场景至关重要——如上例将backup.sql管道输入psql时需配合-T关闭 TTY；--detach则适合在容器内执行清理脚本等一次性后台任务。

启动与停止服务：`uc service start`/`uc service stop`

启动

uc service start SERVICE [SERVICE...] [flags]

启动一个或多个此前已停止的服务：会跨集群所有机器启动指定服务的全部容器；服务可按名称或 ID 指定。

停止

uc service stop SERVICE [SERVICE...] [flags]

优雅地停止一个或多个运行中的服务，跨集群所有机器停止其全部容器，同样支持名称或 ID。停止后的服务可用uc start重新启动。其专属参数：

参数	说明
`-s, --signal string`	发送给每个容器主进程的信号，可为信号名（SIGTERM、SIGINT、SIGHUP 等）或数字，默认`SIGTERM`。
`-t, --timeout int`	等待每个容器优雅停止的秒数，超时后强制 SIGKILL；传`-1`表示无限等待，默认`10`。

源码（cmd/uc/service/stop.go）显示，stop将信号与超时封装进 Docker 的container.StopOptions后调用client.StopService，并对每个服务以进度条展示“Stopping service ”。

扩缩容：`uc service scale`

scale通过调整副本数对replicated 模式的服务进行扩缩容：

uc service scale SERVICE REPLICAS [flags]

-h, --help help for scale -y, --yes Auto-confirm scaling plan. Should be explicitly set when running non-interactively, e.g., in CI/CD pipelines. [$UNCLOUD_AUTO_CONFIRM]

源码 cmd/uc/service/scale.go 揭示了scale的关键行为，是理解其工作原理的最佳入口：

不支持缩容到 0：当REPLICAS为 0 时直接报错——因为 Uncloud 的服务配置是从现有容器派生的，缩到 0 会丢失服务定义且无法再扩回来；官方提示应改用uc rm <service>删除服务。
仅支持 replicated 模式：对global模式服务执行scale会报错（全局模式副本数由机器数决定，不可手动调整）。
幂等：若目标副本数与当前一致，输出“already has N replicas”并直接返回。
计划与确认：命令会基于现有容器的ServiceSpec生成部署计划（deployment.Plan），展示“Scaling plan”与操作摘要；非交互模式下必须使用--yes或设置UNCLOUD_AUTO_CONFIRM=true，否则会因无法弹出确认而报错——这一点对 CI/CD 集成至关重要。确认提示中会带上目标 context/连接信息，避免误操作到错误集群。
执行：确认后以“Scaling service (N → M replicas)”的进度标题运行部署。

删除服务：`uc service rm`

uc service rm SERVICE [SERVICE...] [flags]

rm删除一个或多个服务。官方文档特别强调了两条数据安全语义：

服务使用的命名卷会被保留，需用uc volume rm单独删除（参见 cmd/uc/volume/rm.go）；
匿名 Docker 卷（由镜像 Dockerfile 中的VOLUME指令自动创建的那些）会随容器一起自动删除。

这一设计让rm成为“移除服务但保全数据”的安全操作，避免误删有状态服务的持久化数据。

与 Compose 部署体系的关系

uc service是命令式管理入口，而 Uncloud 的声明式部署（uc deploy，基于 Compose 文件，参见 pkg/client/compose/）在底层复用同一套服务模型：Compose 服务最终也会渲染为 pkg/api/service.go 定义的ServiceSpec（含Caddy、Configs、Container、Mode、Placement、Ports、Replicas、Volumes等字段）。因此，本命令组的参数语义与 Compose 文件中的字段一一对应——例如-p 8080/https对应 compose 中带http/https协议的端口声明，--mode global对应deploy.mode: global。了解uc service run的参数，就等于掌握了 Compose 服务定义的核心字段含义。

关键源码索引

子命令注册与别名svc：cmd/uc/service/root.go
run参数解析与ServiceSpec组装：cmd/uc/service/run.go
环境变量解析（VAR/VAR=value）：cmd/uc/service/run.go
卷挂载解析（命名卷 / bind /ro/volume-nocopy）：cmd/uc/service/run.go
scale计划与确认流程：cmd/uc/service/scale.go
ServiceSpec结构、默认值与校验：pkg/api/service.go
端口规格PortSpec解析与校验：pkg/api/port.go
放置约束Placement：pkg/api/placement.go
停止服务实现（信号与超时）：cmd/uc/service/stop.go

从 CLI 参考文档到实现代码，uc service命令组展示了 Uncloud 的核心设计哲学：以集群为调度单元、以卷位置决定有状态服务放置、以 Caddy 提供内置 ingress、并以“从现有容器派生服务配置”的方式保持服务定义的无损可恢复性。掌握本命令组，即可脱离 Compose 文件，直接通过命令行完成对集群服务从生到死的精细控制。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析