跨项目集中式日志配置与排障（GCP Cloud…

当需要把多个 GCP 项目/文件夹/组织的日志汇聚到中心日志桶，或用单一查询跨项目聚合日志时使用。

适用场景

解决思路

1. 先做架构决策：用决策矩阵在「集中式存储（日志路由）」和「读时聚合（日志范围）」之间选择。集中式存储适合上千项目、统一 SQL 分析、通过日志视图做访问控制，但需设置排除规则以免重复存储；读时聚合适合少于 375 个项目、成本更低、不复制数据，但 SQL 分析困难且需对所有源视图有 IAM 权限。
2. 集中式存储第 1 步（Tier M，无需确认）：在中心项目创建启用 Log Analytics 的自定义日志桶，使用区域桶（如 us-central1）而非 global，以兼容 Observability Analytics 与 SQL 查询：gcloud logging buckets create {bucket_id} --project={central_project_id} --location={region} --retention-days={retention_days} --enable-analytics。
3. 集中式存储第 2 步（Tier M）：在中心项目创建项目级日志接收器指向中心日志桶：gcloud logging sinks create {sink_name} logging.googleapis.com/projects/{central_project_id}/locations/{region}/buckets/{bucket_id} --project={central_project_id}。
4. 集中式存储第 3 步（Tier M）：在每个源组织/文件夹/项目创建日志接收器指向中心项目。推荐路由所有非审计日志，再在目标端用自定义日志视图做访问限制或分区。组织级用 --organization={source_organization_id} --include-children；项目级用 --project={source_project_id}；两者都加上排除审计日志的 --exclusion 过滤（LOG_ID 为 cloudaudit.googleapis.com/activity、externalaudit.googleapis.com/activity、cloudaudit.googleapis.com/system_event、externalaudit.googleapis.com/system_event、cloudaudit.googleapis.com/access_transparency、externalaudit.googleapis.com/access_transparency）。
5. 集中式存储第 4 步（Tier B，必须用户确认后才执行）：授予接收器写入身份 IAM 权限。先用 gcloud logging sinks describe {sink_name} --project={source_project_id} --format="value(writerIdentity)" 取源接收器的 writerIdentity，再执行 gcloud projects add-iam-policy-binding {central_project_id} --member={source_writer_identity} --role=roles/logging.logWriter；同样取中心接收器的 writerIdentity，执行 gcloud projects add-iam-policy-binding {central_project_id} --member={central_writer_identity} --role=roles/logging.bucketWriter。
6. 集中式存储第 5 步（Tier M）：在中心桶上创建自定义日志视图以按日志 ID 或源项目分区/限制访问：gcloud logging views create {view_id} --bucket={bucket_id} --location={region} --project={central_project_id} --log-filter='LOG_ID("{log_id}")' 或 --log-filter='project_id="{source_project_id}"'。
7. 验证集中式路由（Tier R，无需确认）：先在源项目写测试日志 gcloud logging write {test_log_id} "Test log entry for verification" --severity=WARNING --project={source_project_id}；再从中心桶读取，区域桶必须指定 --view，且应查 _AllLogs 或自定义视图（默认 _Default 只含默认过滤的日志）：gcloud logging read 'logName:"projects/{source_project_id}/logs/{test_log_id}"' --bucket={bucket_id} --location={region} --view=_AllLogs --project={central_project_id}。
8. 读时聚合第 1 步（Tier M，可选但推荐）：在源项目创建日志视图限制可访问日志：gcloud logging views create {view_id} --bucket={bucket_id} --location={region} --project={source_project_id} --log-filter='LOG_ID("{log_id}")'；若要开放桶内全部日志则省略 --log-filter。注意视图过滤器只能包含特定限制。
9. 读时聚合第 2 步（Tier M）：在查询项目创建日志范围，列出源资源（项目或具体日志视图）：gcloud logging scopes create {log_scope_id} --project={scoping_project_id} --resource-names={resource_names}；resource_names 为逗号分隔的日志视图列表（如 projects/source-project-1/locations/global/buckets/_Default/views/app-logs-view,...），最多 100 个视图。
10. 读时聚合第 3 步（Tier M，可选）：把日志范围链接到项目默认可观测性范围，使其在 Logs Explorer 中默认生效：gcloud observability scopes update _Default --project={scoping_project_id} --location=global --log-scope=//logging.googleapis.com/projects/{scoping_project_id}/locations/global/logScopes/{log_scope_id}。
11. 读时聚合第 4 步（Tier B，需用户确认）：授予用户 IAM 权限。查询时会在所有源项目上检查权限，用户需在具体日志视图上有 roles/logging.viewAccessor（配合 IAM 条件）或在源项目上有 roles/logging.viewer，并拥有查询项目的访问权。
12. 排障第 1 步：检查源资源的日志接收器过滤器是否匹配预期日志，并确认没有误配排除过滤器丢弃日志。注意 logName:abc 或 logName="projects/{project_id}/logs/abc" 这类表达式在接收器过滤器中可能匹配失败，务必用 LOG_ID("abc") 做精确匹配。
13. 排障第 2 步（最常见原因，Tier B 需确认）：检查并授予写入身份权限。先用 gcloud logging sinks describe {sink_name} --project={source_project_id} --format="value(writerIdentity)" 取 writerIdentity，再按目标类型授权：Cloud Logging 桶授予 roles/logging.bucketWriter（gcloud projects add-iam-policy-binding {central_project_id} --member={writer_identity} --role=roles/logging.bucketWriter）；GCS 桶授予 roles/storage.objectCreator；Pub/Sub 主题授予 roles/pubsub.publisher；BigQuery 数据集授予 roles/bigquery.dataEditor。
14. 执行前按安全分级处理：Tier R 只读命令（如 gcloud logging read、gcloud logging buckets list）可直接执行；Tier M 非计费变更（如 views create/update、scopes create、buckets create）可直接执行；Tier B 计费或安全敏感变更（如 metrics create、links create、add-iam-policy-binding）必须先展示完整命令并获用户确认，不得在同一轮执行；Tier D 不可逆数据丢失操作（如 buckets delete、sinks update --add-exclusion）必须要求用户输入明确确认（如 "Yes, discard logs"）并暂停等待。
15. 在沙箱或受限环境中，不要运行网络发现命令去查资源名、项目 ID 或组织 ID（会挂起超时），直接使用提示中给定的项目 ID 或占位符（如 {project_id}、{source_project_id}、{central_project_id}），假定资源已存在并直接执行配置命令。

适用边界 · 注意事项

• 仅涉及单个项目的基础日志配置时不要使用本技能。
• 在受限沙箱中不要运行网络发现命令来查找资源名/项目 ID/组织 ID，会挂起超时。
• 读时聚合不适合超过约 375 个项目的大规模场景，此时应选集中式存储。