在 Cloud 环境读取、筛选或流式查看…

适用场景：需要用 mcloud logs 获取 Cloud 环境 backend 或 storefront 运行日志，并按时间范围、错误、部署或元数据筛选。

适用场景

解决思路

1. 执行 `mcloud logs` 获取 Cloud 环境运行日志，可用于读取 backend 或 storefront 日志、按时间范围过滤、搜索错误、按特定部署限定范围。
2. 技能允许的工具为 `Bash(mcloud logs*)` 和 `Bash(jq*)`，因此日志查询用 `mcloud logs`，结构化处理用 `jq`。
3. `--follow` 和 `--json` 不兼容；进行程序化日志分析时，使用带边界的时间窗口配合 `--from`/`--to` 和 `--json`。
4. `--follow` 会持续流式输出直到按 `Ctrl+C` 中断，不要在脚本或管道中使用。
5. 默认检索过去 15 分钟的最后 500 行日志。
6. 命令基本形式：`mcloud logs --organization <org-id> --project <project-id-or-handle> --environment <environment-handle> [options]`。
7. 使用 `-o/--organization <id>` 指定组织 ID；默认使用当前活动上下文。
8. 使用 `-p/--project <id-or-handle>` 指定项目 ID 或 handle；默认使用当前活动上下文。
9. 使用 `-e/--environment <handle>` 指定环境 handle；默认使用当前活动上下文。
10. 使用 `-f/--follow` 持续流式输出日志；与 `--json` 不兼容；默认 `false`。
11. 使用 `--limit <1-5000>` 限制最大日志行数；仅非 follow 模式可用；默认 `500`。
12. 使用 `--from <ISO8601>` 指定时间范围开始，例如 `2026-04-22T10:00:00Z`；默认 15 分钟前。
13. 使用 `--to <ISO8601>` 指定时间范围结束；如果 `--to` 早于 15 分钟前，还必须传 `--from`；默认 now。
14. 使用 `--search <string>` 按子串过滤，与 dashboard 搜索栏相同。
15. 使用 `--deployment <id>` 按 deployment 或 build ID 过滤。
16. 使用 `--source <string>` 按 source 过滤；可重复传递。
17. 使用 `--metadata <key=value>` 按 metadata 字段过滤；可重复传递；相同 key 会合并值。
18. 使用 `--type <backend|storefront>` 指定要查询的日志流；默认 `backend`。
19. 使用 `--json` 输出 JSON；与 `--follow` 不兼容；默认 `false`。
20. 基本日志获取：`mcloud logs --json`（最后 500 行，过去 15 分钟）。
21. 搜索错误：`mcloud logs --search error --limit 1000 --json`。
22. 通过 metadata 过滤 HTTP 500 错误：`mcloud logs --metadata status=500 --limit 1000 --json`。
23. 查看特定部署日志（build 或 deployment ID）：`mcloud logs --deployment bld_01ABC123 --json`。
24. 生成供 agent 分析的结构化输出：`mcloud logs --search error --json | jq '.[] | {timestamp, source, message}'`。
25. 查看 storefront 日志：`mcloud logs --type storefront --json`。
26. 流式查看实时日志（人类可读，不用于脚本）：`mcloud logs --follow`。
27. 查看特定时间范围内的日志：`mcloud logs --from 2026-04-22T10:00:00Z --to 2026-04-22T11:00:00Z --limit 1000 --json`。
28. 查看从某时间到现在的日志：`mcloud logs --from 2026-04-22T10:00:00Z --json`。
29. 多个 source 过滤：`mcloud logs --source api --source worker --json`。
30. 多个 metadata 过滤（HTTP 4xx 和 5xx）：`mcloud logs --metadata status=400 --metadata status=500 --limit 500 --json`。
31. 时间范围说明：默认窗口为过去 15 分钟。
32. 只传 `--from` 不传 `--to`，获取从该时间到现在的日志。
33. 只传 `--to` 不传 `--from`，仅当 `--to` 在最近 15 分钟内；否则还必须传 `--from`。
34. `--from` 和 `--to` 都接受 ISO 8601 时间戳。

适用边界 · 注意事项

• 不适用于没有安装 mcloud CLI 或不是 Cloud/mcloud 环境的日志查询。
• 不要在脚本、CI 或管道中使用 `--follow`，因为它会持续流式输出直到 `Ctrl+C` 中断。
• 不要同时使用 `--follow` 和 `--json`，两者不兼容；程序化分析应改用 `--from`/`--to` 与 `--json`。