uc logs跨机器聚合查看与实时流式跟踪 Uncloud 服务日志【免费下载链接】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 logs是 Uncloud CLI 提供的统一日志查看命令它把集群中分布在多台 Docker 主机上的服务副本replica/容器日志聚合到终端按时间戳排序输出并支持实时 follow、时间范围过滤、按机器/容器精确筛选等能力。读完本文你将掌握uc logs的完整参数用法、SERVICE/CONTAINER精确定位技巧以及其背后基于低水位low watermark算法的跨机器日志合并原理。命令概览uc logs用于查看指定服务在所有机器上的全部副本的日志。与docker logs只能查看单机单容器不同uc logs面向“集群中的服务”这一抽象一次调用即可拉取该服务分布在多台机器上的所有容器的日志并按时间戳统一排序输出。uc logs [SERVICE[/CONTAINER]...] [flags]位置参数为服务名列表可叠加容器限定SERVICE/CONTAINER形式其中CONTAINER可以是容器名、完整 ID 或唯一 ID 前缀。不带任何服务参数时uc logs会从 Compose 文件默认compose.yaml或--file指定的文件中读取服务列表流式输出全部服务含未激活 profile 的服务的日志。若 Compose 中定义的服务尚未在集群中部署会跳过并打印警告其余服务照常输出见 service/logs.go 与 service/logs.go。常用示例以下示例覆盖了从基础查看到精细化筛选的典型场景# 查看某个服务最近的日志。 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 # 只查看服务的某些副本容器。 uc logs web/61d57fd3428f api/2f60 # 只查看运行在指定机器上的副本的日志。 uc logs -m machine1,machine2 web api参数详解--file strings指定 Compose 文件仅当不带服务参数调用uc logs时生效用于从 Compose 文件加载服务名列表默认值为compose.yaml可多次指定或传逗号分隔的多个文件。当服务来自 Compose 文件时命令还会自动使用 Compose 中声明的集群上下文SetClusterContextIfUnset(compose.ClusterContext(project))见 service/logs.go确保日志连到正确的集群。-f, --follow实时流式输出持续输出新产生的日志等价于docker logs -f/tail -f的集群版。在 follow 模式下服务端会以心跳维持流存活详见下文“底层原理”。-n, --tail string限制每个副本的行数默认值100即每个副本容器只显示最近 100 行。传all表示显示全部日志。参数解析时all会被转换为-1服务端收到-1后返回该容器的全部日志见 internal/cli/logs/logs.go。若传非法数值非整数会报错invalid --tail value。--since/--until时间范围过滤两个参数都接受三种格式的时间戳格式示例说明相对时长--since 2m30s、--since 1h表示从“多久之前”开始RFC 3339 日期/时间--since 2025-11-24本地时区零点、--since 2024-05-14T22:50:00本地时区、--since 2024-01-31T10:30:00ZUTC精确到秒的起止时间Unix 时间戳--since 1763953966自 1970-01-01 起的秒数--since表示输出该时间点及之后生成的日志--until表示输出该时间点之前生成的日志两者可组合使用形成闭合区间例如uc logs --since 3h --until 1h30m web查看最近 1.5~3 小时之间的日志。--utc时间戳时区默认按本机本地时区打印时间戳加上--utc后统一按 UTC 打印便于跨时区对比多机器日志。-m, --machine strings按机器过滤按机器名称或 ID 过滤日志可多次指定或用逗号分隔多个值如-m machine1,machine2。底层会先解析机器过滤条件仅保留运行在这些机器上的副本的日志流见 pkg/client/logs.go。SERVICE/CONTAINER精确定位副本uc logs web/61d57fd3428f api/2f60中CONTAINER支持容器名、完整 ID 或唯一 ID 前缀如2f60。若同一服务的多个参数混用既有web又有web/abc只要出现不带/的纯服务名参数该服务所有副本都会输出见 internal/cli/logs/logs.go 的ParseServiceArgs合并逻辑。输出格式每条日志输出形如Jan 2 15:04:05.000 machine1 web/61d57 GET /api 200依次为时间戳time.StampMilli格式可--utc切换→ 机器名 →服务名/容器ID前5位→ 消息内容。机器名和服务名会按列动态对齐单服务场景下机器名着色、多服务场景下服务名着色调色板见 internal/cli/logs/formatter.go。其中来自stderr的日志会输出到终端的 stderr便于在 shell 中分别重定向。部署钩子容器如 pre-deploy的日志会额外标注[pre-deploy]字样Metadata.Hook字段见 pkg/api/logs.go。流异常如某机器日志流 10 秒无响应会以黄色WARNING提示不影响其余日志输出。底层原理一条日志的跨机器之旅uc logs的高层调用链如下见 cmd/uc/service/logs.go解析位置参数ParseServiceArgs或从 Compose 文件加载服务列表对每个服务调用c.ServiceLogs(ctx, service, opts)见 pkg/client/logs.go先InspectService拿到服务全部容器含钩子容器再按容器逐一建立日志流每个容器流通过 gRPC 代理ContainerLogs请求转发到对应机器上的 unclouddProxySingleMachineContext见 pkg/client/logs.go服务端再对接本机 Docker daemon见 internal/machine/docker/server.go客户端为每个容器流附带服务元数据服务名、机器名、容器 ID、钩子类型再交给LogMerger合并。低水位算法与心跳由于多台机器的物理时钟存在偏差跨机器日志无法保证严格全局有序。LogMerger见 pkg/client/logmerger.go采用低水位low watermark算法为每个输入流记录其最新时间戳lastSeenwatermark 取所有活跃流lastSeen的最小值只有时间戳早于 watermark 的日志才会从最小堆中弹出输出从而在“尽快输出”与“尽可能有序”之间取得平衡见 logmerger.go。为让缓冲的日志能及时输出服务端在无日志产生时每 200ms 发送一次心跳条目logsHeartbeatInterval见 internal/machine/docker/server.go心跳推进 watermark 触发旧日志落盘输出合并器自身会对多流心跳去抖200ms 间隔并统一将心跳时间戳调整为当前 watermark 以维持排序见 logmerger.go。流控与停滞检测合并器为每个输入流设置最多 100 条在途消息的信号量logMergerMaxInFlightPerStream避免单个高速流无限缓冲拖垮整体同时默认每 1 秒检查一次若某流超过 10 秒无任何数据则判定为停滞stalled将其从 watermark 计算中剔除并输出黄色WARNING: log stream ... stopped responding防止一条故障流阻塞整条日志管线见 logmerger.go 与 logmerger.go。继承自父命令的全局选项uc logs同样继承uc的集群连接相关选项在未使用配置文件时可用选项环境变量说明--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_CONFIGUncloud 配置文件路径默认~/.config/uncloud/config.yaml相关命令ucUncloud 根命令管理机器、服务、卷等资源。uc service logs服务子命令下的日志查看与uc logs等价logs是service logs的顶层快捷方式命令定义于 cmd/uc/service/logs.go。uc machine logs查看机器上的系统服务如 uncloudd、Docker、corrosion日志客户端侧由MachineLogs实现见 pkg/client/logs.go。小结uc logs将“查看服务日志”从单机docker logs提升到集群维度一条命令即可聚合多机器、多副本、多服务甚至含部署钩子容器的日志配合-f、-n、--since/--until、-m、SERVICE/CONTAINER等参数可灵活完成实时跟踪与问题排查其底层的低水位合并、心跳推进与停滞检测机制保证了跨机器日志输出的及时性与尽可能有序是 Uncloud 集群日常运维中最高频的调试入口之一。【免费下载链接】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），仅供参考