Uncloud 集群系统服务日志排查指南uc machine logs 详解【免费下载链接】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 machine logs是 Uncloud CLI 提供的跨机器系统服务日志查看命令用于在集群内一次性地、按时间顺序聚合查看多台机器上的系统级服务日志覆盖 Corrosion 分布式状态存储、Docker 守护进程与 Uncloud 守护进程三类服务。读完本文你将掌握该命令的全部参数语义、时间过滤语法、跟随follow模式用法并理解其底层多机日志合并与心跳保序机制的实现原理从而高效完成集群层面的故障排查与运行状态观测。命令概述与定位uc machine logs从集群中所有机器或-m指定的部分机器上读取指定系统服务的日志并按时间戳统一排序输出。它与uc service logs面向应用服务的容器日志互补uc service logs关注的是用户部署的服务容器而uc machine logs关注的是支撑整个集群运转的系统组件。命令别名log用法格式uc machine logs [SERVICE...] [flags]对应命令定义位于 cmd/uc/machine/logs.go。从源码看SERVICE...位置参数为可选项当不指定任何服务时命令内部会将服务列表默认设置为uncloud见 runLogs 中的api.SystemServiceUncloud分支即默认流式读取 Uncloud 守护进程的日志。支持的三种系统服务命令仅接受以下三种系统服务名传入其他名称会直接报错校验逻辑见 runLogs服务常量定义在 pkg/api/logs.go服务名全称与角色日志来源源码依据corrosionCorrosion 分布式状态存储负责集群状态的复制与持久化以守护进程管理的容器形式运行日志取自容器dockerDocker 守护进程systemd 单元docker日志取自 journaluncloudUncloud 守护进程集群 Agentsystemd 单元uncloud日志取自 journal从源码结构看在服务端 internal/machine/machine.go#L1425-L1438 的MachineLogs实现中uncloud与docker走 systemd journal 读取路径而corrosion因为由 daemon 托管为容器容器名常量见corroservice.ContainerName走的是与uc service logs相同的容器日志路径。实战用法示例以下示例均来自命令自带帮助文本见 logs.go可直接复制使用# 查看 uncloud 服务最近的日志默认行为等价于不带参数 uc machine logs uc machine logs uncloud # 实时跟随follow 模式持续输出新增日志 uc machine logs -f uncloud # 同时查看多个服务的日志 uc machine logs uncloud docker corrosion # 每台机器只显示最后 20 行默认 100 行 uc machine logs -n 20 docker # 显示全部日志不限制行数 uc machine logs -n all docker # 按时间范围过滤 uc machine logs --since 3h --until 1h30m docker # 只查看指定机器的日志 uc machine logs -m machine1,machine2 uncloud corrosion注意-n/--tail的行数是按副本每台机器上的实例分别限制的在多机场景下每个机器的日志流各取最后 N 行再合并而非整体只取 N 行。参数选项详解核心选项选项简写类型默认值说明--follow-fboolfalse持续流式输出新日志直到用户中断--machine-mstrings—按机器名称或 ID 过滤可多次指定也支持逗号分隔列表--since—string仅显示该时间点之后生成的日志支持相对时长 / RFC 3339 / Unix 时间戳--tail-nstring100限制每个副本显示的最新日志行数all表示不限制--until—string仅显示该时间点之前生成的日志语法同--since--utc—boolfalse时间戳按 UTC 打印而非本地时区选项的定义位置在 internal/cli/logs/logs.go#L22-L47其中-m支持逗号分隔是通过cli.ExpandCommaSeparatedValues展开的见 runLogs--tail的取值解析函数Tail位于 internal/cli/logs/logs.go#L49-L59。--since / --until 的时间语法--since与--until共用同一套时间语法支持三种格式1. 相对时长Go duration 语法--since 2m30s # 2 分 30 秒前 --since 1h # 1 小时前 --since 3h # 3 小时前2. RFC 3339 日期/时间--since 2025-11-24 # 仅日期按本地时区零点 --since 2024-05-14T22:50:00 # 日期时间按本地时区 --since 2024-01-31T10:30:00Z # 日期时间UTC3. Unix 时间戳自 1970-01-01 起的秒数--since 1763953966时间戳的解析发生在服务端日志读取层对于 journal 路径journalctl会按这些条件过滤条目。组合使用时--since与--until划定了一个时间窗口例如--since 3h --until 1h30m表示1.5 小时前到 3 小时前之间的日志。从父命令继承的全局选项选项说明--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 string指定 Uncloud 配置文件路径默认~/.config/uncloud/config.yaml可用环境变量$UNCLOUD_CONFIG输出格式与多机合并统一输出列命令的输出由 internal/cli/logs/formatter.go 中的Formatter负责渲染每条日志包含四段信息时间戳 机器名 服务名 日志内容时间戳默认按本地时区、Jan _2 15:04:05.000毫秒精度格式显示加--utc则转换为 UTC见 formatTimestamp。机器名粗体显示单服务日志场景下不同机器使用不同颜色区分10 色调色板循环分配见 palette。服务名多服务日志场景下不同服务用颜色区分列宽根据实际涉及的机器名/服务名动态对齐保证多行可读性。stderr 分流stderr 流的日志写到标准错误输出stdout 流写到标准输出见 PrintEntry方便管道重定向时分离错误信息。跨机器的时间序合并在客户端MachineLogs实现于 pkg/client/logs.go#L162-L195会先按过滤条件列出机器为每台机器分别建立一条日志流并附加机器元数据然后通过NewLogMerger将多条流按时间戳升序合并为单一输出流。这里要注意由于物理时钟存在偏差跨机器的日志无法保证绝对严格的全局排序——合并算法使用低水位low watermark机制尽力保证正确顺序服务端发送的心跳条目用于推进水位促使客户端及时吐出已缓冲的日志。当一次指定多个服务时命令会为每个服务各建一条MachineLogs流再用外层LogMerger合并见 runLogs由于内层每条流已自带 stall 检测外层合并刻意跳过了重复的告警逻辑。底层原理从 CLI 到 journal/容器的完整链路请求链路uc machine logs → CLI 组装 api.ServiceLogsOptions → 客户端 c.MachineLogs(ctx, service, opts) → 对每台机器ProxySingleMachineContext 注入机器路由 → gRPC 服务端流式接口 MachineLogs → 服务端 internal/machine/machine.go 的 MachineLogs → uncloud/dockerinternal/journal.Logsjournalctl → corrosiondockerService.ContainerLogs容器日志 → 客户端 LogMerger 按时间戳合并 → Formatter 渲染输出gRPC 接口定义见 api/pb/machine.protoMachineLogs服务端流式 RPC请求参数LogsRequest携带id服务名、follow、tail、since、until。systemd journal 读取对uncloud与docker两个服务服务端调用 internal/journal 包的Logs函数读取 journal。日志条目采用journalctl的 short-unix 时间戳格式SSSSSSSSSS.UUUUUU秒.微秒由 parseUnixTimestamp 解析为time.Time消息正文会补回换行符见 entry。心跳保序机制在 follow 模式下服务端每 200ms常量logsHeartbeatInterval见 internal/machine/machine.go#L1405-L1406发送一条HEARTBEAT类型的空日志条目只有当最近一次发送时间距现在超过一个心跳间隔时才发送且时间戳取一个心跳之前的保守值见 machine.go#L1483-L1501避免客户端误以为已收到全部日志。这条心跳正是客户端低水位合并算法推进水位的信号源是follow 模式下跨机器日志能及时刷出的关键设计。流中断与错误提示如果某个机器的日志流停滞或出错客户端会收到一条ErrLogStreamStalled错误条目Formatter 将其渲染为黄色 WARNING如WARNING: log stream from system service uncloud on machine m1 stopped responding而普通错误则渲染为红色 ERROR见 printError便于在多机日志流中快速定位异常节点。典型排障场景Uncloud 守护进程异常uc machine logs uncloud查看默认服务日志若集群行为异常可先uc machine logs -n 200 uncloud看更多上下文。Docker 引擎问题容器无法调度或状态异常时uc machine logs -m node-a docker仅看目标机器的 Docker 日志避免被其他机器刷屏。集群状态存储故障uc machine logs corrosion观察 Corrosion 的复制与同步日志结合-f实时观察状态变更。多服务交叉排查uc machine logs -f uncloud docker corrosion -m machine1固定一台机器同时观察三类系统组件利用颜色区分快速定位相互影响的日志。相关命令uc machine管理集群中的机器uc machine logs是其子命令之一。uc service logs查看应用服务容器日志系统服务与用户服务日志读取链路共享同一套LogMerger合并与 Formatter 渲染逻辑。全局连接与上下文选项说明见 7-cli-config-reference 中的--connect/--context/--uncloud-config约定。【免费下载链接】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），仅供参考