将 Amazon Quick 日志投递至 Amazon S3：审计与长期留存指南

摘要：本文介绍如何通过 CloudWatch Logs V2 delivery，将 Amazon Quick 支持的日志直接持续投递到指定的 Amazon S3 Bucket。CloudWatch Logs 在此架构中仅作为日志投递的控制面。日志会直接写入 S3，无需创建 CloudWatch Log Group，也无需配置 Log Group Export。

一、概述

Quick 投入使用后，团队通常需要持续了解用户行为、对话质量、知识库运行状态以及 Agent、Research、Flow 和 Automation 的使用情况。仅在 Quick 控制台逐项查看，适合临时排障，却不利于长期留存、跨团队分析和接入既有数据治理流程。

将日志持续投递到自有 S3 Bucket，可将分散的运行信号沉淀在组织可控的数据边界内。后续可按需使用 Athena、Amazon QuickSight、Amazon Data Firehose、SIEM 平台或内部数据管道进行查询、告警、审计和报表构建；本文聚焦于原始日志的可靠落地。

CHAT_LOGS 和 FEEDBACK_LOGS 可能包含用户输入或业务上下文。启用日志投递前，应完成数据分类、隐私评估、访问控制和保留期限设计。

二、支持的日志类型与环境信息

本文既可用于首次搭建日志归档，也可作为生产环境标准化配置的参考。开始部署前，请先确认目标 Region、AWS 账号、S3 Bucket、日志所有者、访问角色和保留期限。

2.1 环境信息

<YOUR-AWS-ACCOUNT-ID> 表示你的 AWS 账号 ID，不能直接用于 AWS API。本文后续 Shell 命令会通过 STS 自动获取实际账号 ID。

2.2 Quick 支持的日志类型

Amazon Quick 当前支持以下五类日志。每类日志都必须使用独立的 Delivery Source，但可以共用同一个 S3 Delivery Destination。

CHAT_LOGS

该日志适用于分析聊天内容、常见问题、无答案场景、被拦截请求和回答质量。常见字段包括 status_code、conversation_id、user_message_id、user_message、system_message_id、system_text_message、agent_id、flow_id、message_scope、user_selected_resources、action_connectors、cited_resource 和 file_attachment。

官方文档中标记为 * 的字段默认不会写入日志，例如 namespace、latency、time_to_first_token、surface_type 和 web_search。如需这些字段，必须在 CreateDelivery 时通过 record-fields 显式指定，并同时包含该日志类型的必填字段。

FEEDBACK_LOGS

该日志用于分析用户满意度及反馈原因，常见字段包括 conversation_id、system_message_id、user_message_id、feedback_type、feedback_reason 和 feedback_details。

FEEDBACK_LOGS 与 CHAT_LOGS 相互独立。仅配置 CHAT_LOGS 不会自动记录点赞、点踩或文字反馈。

AGENT_HOURS_LOGS

该日志用于分析 Agent、Research、Flow 或 Automation 的小时用量。常见字段包括：

• subscription_type：ENTERPRISE 或 PROFESSIONAL；
• reporting_service：例如 RESEARCH、FLOWS 或 AUTOMATIONS；
• usage_group：例如 Included 或 Extra；
• usage_hours；
• service_resource_arn。

此类日志侧重用量和费用分析，不包含聊天内容。

INDEX_USAGE_LOGS

该日志用于跟踪 Knowledge Base 和 Space 的索引存储使用情况。常见字段包括 consumed_index_size（整个索引的权威总大小）、source_type（SPACE 或 KB）、source_name、source_arn、consumed_source_size 和 consumed_source_doc_count。

仅当来源被创建、更新、同步或删除等变化发生时，才会发布事件；不保证每天都有记录。若需重建当前状态，应按 source_arn 选择最新的一条事件。

KB_FILE_SYNC_LOGS

该日志用于跟踪 Knowledge Base 同步期间各文档的处理结果。每次同步中，每个文档都会产生一条记录。常见字段包括 document_id、document_title、document_status、sync_result、sync_id、data_source_id、source_uri、error_message、error_mitigation、error_type 和 knowledge_base_id。

2.3 工作原理与验收边界

AWS 将日志投递链路拆分为三个对象：

• Delivery Source：代表 Amazon Quick 产生的一种日志类型；
• Delivery Destination：代表投递目标，例如 S3 Bucket；
• Delivery：将一个 Source 连接到一个 Destination。

[图1]

推荐采用“5 个 Source、1 个 Destination、5 条 Delivery”的结构。这样既能统一归档，又可按日志类型独立观察、排障或停止投递；新增日志类型时通常只需增加一个 Source 和一条 Delivery。

验收应分为两个阶段：

• 配置验证：确认 5 个 Source、1 个 Destination、5 条 Delivery 以及所需的 Bucket Policy 均已正确建立。
• 数据验证：分别触发五类日志对应的业务事件，并在 S3 中确认实际生成日志对象。

各类日志的触发频率不同。聊天和反馈日志通常可快速验证；用量、索引与文件同步日志依赖实际功能调用或内容变更。建议记录配置时间、触发操作、首个对象出现时间及对象位置，以区分“尚无业务事件”和“投递异常”。

生产环境应分离配置和消费职责：配置者负责管理投递对象，日志消费者仅获得读取 S3 数据的最小权限。资源名称可加入环境或业务域标识，但不应包含个人信息、密钥或其他敏感数据。

变更前先使用 describe-* 命令确认当前对象和关联关系，再进行新增或修改并重新验证。删除时必须先删除 Delivery，才能删除其关联的 Source 或 Destination；承载审计或合规数据的 Bucket 应保留既有对象，直至满足组织的保留与处置要求。

完成部署后，建议建立持续运营闭环：定期查看同步失败、负面反馈、异常用量和索引变化，并将发现的问题反馈至知识库、Agent 配置或权限治理流程。

三、部署方式一：使用 CloudFormation（推荐）

3.1 适用场景与部署结果

CloudFormation 适合首次部署、重复部署专用 Bucket，以及需要固定安全基线的场景。示例模板仓库：aws-samples/sample-enable-quick-logs-to-s3。在 CloudFormation 中部署 quick-logs-cloudformation.yaml 模板，即可创建专用、使用 SSE-S3 加密的 S3 Bucket，并建立全部五类 Quick 日志的投递关系。

3.2 部署步骤

1. 确认模板 URL、Region 和模板内容无误后，选择 Next。
2. 指定 Stack 名称，例如 quick-log-delivery。BucketNamePrefix 仅可使用小写字母、数字和连字符，默认值为 quick-logs；NamePrefix 默认为 quick-cfn，用于 Delivery 资源名称。
3. 确认最终 Bucket 名为 ${BucketNamePrefix}-${AccountId}-${Region}。该名称必须在 S3 全局命名空间中唯一；如已被占用，请修改 BucketNamePrefix。模板不会使用或修改现有 Bucket。
4. 使用具备本文所列权限的 CloudFormation 执行角色或当前身份创建 Stack，并等待状态变为 CREATE_COMPLETE。
5. 在 Stack 的 Outputs 中复制 BucketUri，然后在 Quick 中与 Agent 进行交互，验证数据面是否已到达 S3。

部署会新建 Bucket 和日志投递配置。模板为 Bucket 设置了 DeletionPolicy: Retain：删除 Stack 时会停止投递并删除 CloudWatch Logs Delivery 资源，但不会删除 Bucket 或其中的日志对象，从而避免意外删除审计数据。

3.3 模板创建的资源

模板创建的资源如下：

3.4 部署注意事项与后续验证

模板不会创建 IAM User、Role 或 KMS Key，也不会授予业务人员读取聊天日志的权限；这些权限应由组织按照最小权限原则单独管理。它同样不会回填部署前的历史事件。

不要直接以默认参数部署 Stack，以免发生 Bucket 命名冲突；请先为 NamePrefix 指定新的、未使用的值。部署完成后，应在 Stack 的 Outputs 中确认 BucketUri，再触发测试事件并在 S3 中检查日志对象。

如需复用既有 Bucket、调整资源名称或仅启用部分日志类型，请使用下一节的手动部署方式。两种方式的目标相同：建立所选日志类型的 Source、Destination 和 Delivery 关联。

四、部署方式二：使用 AWS CLI 手动部署

手动部署适合复用既有 S3 Bucket、按组织规范调整资源名称，或仅启用部分日志类型。整体流程如下：

准备 Bucket → 配置 IAM 权限 → 设置变量 → 创建 Destination → 创建 Source 和 Delivery → 验证配置 → 触发测试事件 → 检查 S3 对象

4.1 前提条件

• Amazon Quick 使用 Enterprise 或 Professional 订阅；
• 执行命令的 IAM User 或 Role 位于目标账号，或具备该账号所需权限；也可在具备相应权限的 CloudShell 中执行；
• 已安装较新版本的 AWS CLI v2；
• 使用手动部署时，目标 S3 Bucket 必须已存在；CloudFormation 路径会自动创建专用 Bucket；
• 建议首次配置使用 SSE-S3；如需 SSE-KMS，请参见后文的 KMS 配置说明。

确认当前 AWS 身份：

aws sts get-caller-identity

检查目标 Bucket 是否存在，且当前身份能够访问：

export AWS_REGION="us-east-1"
export ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)"
export BUCKET_NAME="quick-${ACCOUNT_ID}-${AWS_REGION}-an"

aws s3api head-bucket --bucket "${BUCKET_NAME}"

head-bucket 成功时通常没有输出；退出码为 0 表示检查通过。

4.2 配置执行者的 IAM 权限

为用于配置的 IAM User 或 Role 授予以下权限。示例中的账号和 Bucket ARN 已脱敏，实际部署时必须替换为真实 ARN。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowQuickLogDelivery",
      "Effect": "Allow",
      "Action": ["quicksight:AllowVendedLogDeliveryForResource"],
      "Resource": "arn:aws:quicksight:us-east-1:<YOUR-AWS-ACCOUNT-ID>:account/<YOUR-AWS-ACCOUNT-ID>"
    },
    {
      "Sid": "ManageCloudWatchLogDelivery",
      "Effect": "Allow",
      "Action": [
        "logs:PutDeliverySource", "logs:GetDeliverySource", "logs:DeleteDeliverySource",
        "logs:PutDeliveryDestination", "logs:GetDeliveryDestination", "logs:DeleteDeliveryDestination",
        "logs:CreateDelivery", "logs:GetDelivery", "logs:DeleteDelivery",
        "logs:DescribeDeliveries", "logs:DescribeDeliverySources", "logs:DescribeDeliveryDestinations",
        "logs:UpdateDeliveryConfiguration"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AllowS3BucketPolicyConfiguration",
      "Effect": "Allow",
      "Action": ["s3:ListBucket", "s3:GetBucketPolicy", "s3:PutBucketPolicy"],
      "Resource": "arn:aws:s3:::quick-<YOUR-AWS-ACCOUNT-ID>-us-east-1-an"
    }
  ]
}

s3:ListBucket 用于执行 head-bucket 前置检查；s3:GetBucketPolicy 和 s3:PutBucketPolicy 用于在创建 Delivery 时，让 AWS 自动将 delivery.logs.amazonaws.com 所需权限合并到 Bucket Policy 中。若账号使用了 Service Control Policy、Permission Boundary，或 Bucket Policy 中存在显式 Deny，还需确认这些策略不会阻止上述操作。

4.3 设置命令变量

以下命令会通过 STS 自动读取真实账号 ID，而不会使用文中的脱敏值：

export AWS_REGION="us-east-1"
export ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)"
export BUCKET_NAME="quick-${ACCOUNT_ID}-${AWS_REGION}-an"
export QUICK_ACCOUNT_ARN="arn:aws:quicksight:${AWS_REGION}:${ACCOUNT_ID}:account/${ACCOUNT_ID}"
export DESTINATION_NAME="quick-all-logs-s3"

export CHAT_SOURCE_NAME="quick-chat-logs-source"
export FEEDBACK_SOURCE_NAME="quick-feedback-logs-source"
export AGENT_HOURS_SOURCE_NAME="quick-agent-hours-logs-source"
export INDEX_USAGE_SOURCE_NAME="quick-index-usage-logs-source"
export KB_FILE_SYNC_SOURCE_NAME="quick-kb-file-sync-logs-source"

检查关键参数：

echo "Account: ${ACCOUNT_ID}"
echo "Quick ARN: ${QUICK_ACCOUNT_ARN}"
echo "Bucket ARN: arn:aws:s3:::${BUCKET_NAME}"

4.4 创建 S3 Delivery Destination

所有日志类型都可共用一个 S3 Destination，因此只需创建一次：

export DESTINATION_ARN="$(
  aws logs put-delivery-destination \
    --region "${AWS_REGION}" \
    --name "${DESTINATION_NAME}" \
    --delivery-destination-type S3 \
    --delivery-destination-configuration \
      "destinationResourceArn=arn:aws:s3:::${BUCKET_NAME}" \
    --output-format json \
    --query 'deliveryDestination.arn' \
    --output text
)"

确认返回值：

echo "${DESTINATION_ARN}"

其格式应类似：

arn:aws:logs:us-east-1:<YOUR-AWS-ACCOUNT-ID>:delivery-destination:quick-all-logs-s3

若返回空值或 None，请先检查 Destination，而不要继续创建 Delivery：

aws logs get-delivery-destination \
  --region "${AWS_REGION}" \
  --name "${DESTINATION_NAME}"

4.5 创建 Delivery Source 和 Delivery

每种日志类型都需要一个独立的 Delivery Source 和一条 Delivery。执行前，请确认已完成上一节的 Destination 创建，且当前 Shell 中的 DESTINATION_ARN 不为空。

下表列出了各日志类型对应的 Source 名称和 log-type。对每一行依次执行两条命令：先创建 Source，再连接 Destination。

# 以 CHAT_LOGS 为例；替换 SOURCE_NAME 和 LOG_TYPE 后可创建其他四类日志。
SOURCE_NAME="${CHAT_SOURCE_NAME}"
LOG_TYPE="CHAT_LOGS"

aws logs put-delivery-source \
  --region "${AWS_REGION}" \
  --name "${SOURCE_NAME}" \
  --resource-arn "${QUICK_ACCOUNT_ARN}" \
  --log-type "${LOG_TYPE}"

aws logs create-delivery \
  --region "${AWS_REGION}" \
  --delivery-source-name "${SOURCE_NAME}" \
  --delivery-destination-arn "${DESTINATION_ARN}"

如 AWS CLI 对 KB_FILE_SYNC_LOGS 返回本地参数校验错误，请升级 AWS CLI v2；部分旧版本 CLI 的内置服务模型尚未包含该日志类型。若某类日志的 Source 和 Delivery 已存在，请跳过该类配置，避免重复执行 create-delivery。

4.6 验证 Delivery 配置

aws logs describe-deliveries --region "${AWS_REGION}" --output table
aws logs describe-delivery-sources --region "${AWS_REGION}" --output table
aws logs describe-delivery-destinations --region "${AWS_REGION}" --output table

Source 输出中应包含以下五种类型：

CHAT_LOGS
FEEDBACK_LOGS
AGENT_HOURS_LOGS
INDEX_USAGE_LOGS
KB_FILE_SYNC_LOGS

完整配置应包含 5 个 Delivery Source、1 个 S3 Delivery Destination 和 5 条 Delivery。

4.7 检查 S3 Bucket Policy

正常情况下，AWS 会自动向 Bucket Policy 添加日志投递服务所需权限：

aws s3api get-bucket-policy \
  --bucket "${BUCKET_NAME}" \
  --query Policy \
  --output text

策略中应包含 Service Principal delivery.logs.amazonaws.com，以及通常包含 s3:GetBucketAcl、s3:ListBucket 和 s3:PutObject 的相关授权。

若返回 NoSuchBucketPolicy，或策略中没有该 Service Principal，请检查配置身份是否拥有 s3:GetBucketPolicy 和 s3:PutBucketPolicy。Bucket 已有自定义策略时，不要直接覆盖整个 Policy，应将日志投递所需 Statement 合并进去。

4.8 触发并检查测试日志

等待投递后，检查 Bucket：

aws s3 ls "s3://${BUCKET_NAME}/" --recursive

请注意：历史事件不会因新建 Delivery 自动回填；不同日志类型的发布频率不同，不能以聊天日志的到达速度判断用量或索引日志是否异常；INDEX_USAGE_LOGS 仅在来源发生变化时发布；KB_FILE_SYNC_LOGS 会在每次同步中按文档产生记录。

4.9 加密配置：SSE-KMS

目标 Bucket 使用 SSE-S3 时，无需额外 KMS 权限。使用 SSE-KMS 时，必须使用 Customer Managed Key，不应使用 AWS 托管的 aws/s3 Key，并需在 KMS Key Policy 中允许 delivery.logs.amazonaws.com 使用该密钥：

{
  "Sid": "AllowCloudWatchLogsDelivery",
  "Effect": "Allow",
  "Principal": { "Service": "delivery.logs.amazonaws.com" },
  "Action": [
    "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*",
    "kms:GenerateDataKey*", "kms:DescribeKey"
  ],
  "Resource": "*",
  "Condition": {
    "StringEquals": { "aws:SourceAccount": "<YOUR-AWS-ACCOUNT-ID>" },
    "ArnLike": {
      "aws:SourceArn": "arn:aws:logs:us-east-1:<YOUR-AWS-ACCOUNT-ID>:delivery-source:*"
    }
  }
}

建议先通过 SSE-S3 完成投递验证，再切换至 SSE-KMS，以缩小首次配置时的排障范围。

4.10 排障

五、安全与合规建议

Quick 日志可能包含用户输入、系统回答、反馈、引用资源、附件、资源名称和用量信息，因此可能涉及个人信息或企业敏感数据。建议：

• 对 Bucket 及日志读取权限实施最小权限原则；
• 按不同日志类型的保留要求配置 S3 Lifecycle；
• 在生产环境中根据合规要求使用 Customer Managed KMS Key；
• 按业务要求实施敏感数据识别、脱敏和审计；
• 确认日志的存储与处理符合数据驻留和隐私要求。

六、清理配置

删除 Quick 资源不会自动删除日志投递对象。如不再需要某类日志，请按以下顺序清理：

1. 使用 delete-delivery 删除对应的 Delivery；
2. 使用 delete-delivery-source 删除对应的 Source；
3. 仅在 S3 Destination 不再被任何 Delivery 使用时，使用 delete-delivery-destination 删除 Destination。

删除前可先查看 Delivery ID：

aws logs describe-deliveries \
  --region "${AWS_REGION}" \
  --output table

清理会停止后续日志投递，属于高影响操作；请在确认不再需要日志后再执行。

七、AWS 官方参考资料

• Monitoring Amazon Quick usage using CloudWatch Logs
• CloudWatch Logs V2 delivery permissions
• CloudWatch Logs delivery to Amazon S3
• AWS CLI: put-delivery-source
• AWS CLI: put-delivery-destination
• AWS CLI: create-delivery

➡️ 下一步行动：

相关产品：

• Amazon S3 — 适用于 AI、分析和存档的几乎无限的安全对象存储
• Amazon Quick — 人工智能助手，用于研究、业务洞察、自动化和无代码应用程序构建
• Amazon CloudWatch — 可观测性工具
• Amazon KMS — 托管式密钥管理
• Amazon CloudFormation — 基础设施即代码服务

相关文章：

• 基于 Amazon CloudFront 和 Lambda@Edge 实现失败请求的完整记录与异步重放
• 构建 Amazon ElastiCache OSS Caches 慢查询监控方案
• 用 Kiro CLI 自动搭建 FluentBit 日志采集方案：两种 EKS 埋点数据落地 S3 Parquet 的实战对比
• 使用 Amazon EventBridge 与 AWS Lambda 实现 ALB 流量镜像会话自动化配置
• Amazon Bedrock AgentCore 数据持久化文件系统：Session Storage 和 Amazon EFS / S3 Files

*前述特定亚马逊云科技生成式人工智能相关的服务目前在亚马逊云科技海外区域可用。亚马逊云科技中国区域相关云服务由西云数据和光环新网运营，具体信息以中国区域官网为准。

本篇作者

AWS 架构师中心：云端创新的引领者 探索 AWS 架构师中心，获取经实战验证的最佳实践与架构指南，助您高效构建安全、可靠的云上应用