timestream-influxdb

Amazon Timestream for InfluxDB

概述

Amazon Timestream for InfluxDB 是一种托管式时序数据库，提供多种引擎变体和部署类型，各自的功能有所不同。在比较它们之前，请先检索 Timestream for InfluxDB 文档，并检查适用的 Create API 模型。对于现有资源，请读取其 GetDbInstance 或 GetDbCluster 响应。使用这些来源，核实用户所在区域支持的引擎变体、端点端口、查询语言、数据模型、身份验证流程、部署类型、许可和 Processing Engine 支持情况。不要根据某个引擎变体推断另一变体的功能，也不要根据本技能中的示例进行推断。

对于新工作负载，请核实支持的引擎变体；如果服务文档将 InfluxDB 3 列为可选项，则建议使用 InfluxDB 3。对于现有的 V2 部署，请先核实 V2 支持情况，再建议继续使用 V2 还是迁移。

本技能仅提供建议：它会推荐操作，并提供用于执行这些操作的 AWS CLI 和 API 命令（包括创建实例或集群、添加标签等变更操作）。它不会自主执行操作——仅在用户明确请求时才执行变更，绝不会主动执行。

工具： 建议使用 AWS MCP 服务，以便更便捷地调用 AWS API，但这不是必需的。所有示例都使用标准 AWS CLI 语法，无需 MCP 也可运行。

常见任务

1. 验证依赖项

在提供任何建议之前，确认工具和引擎变体。

约束：

• 在提供针对特定引擎变体的建议之前，MUST 确认用户使用的是哪种引擎变体（V2、V2 Read Replica 或 V3）——API 和默认值各不相同。
• MUST NOT 混用 V2 API（Flux、org、bucket、端口 8086）和 V3 API（SQL/InfluxQL、数据库、表、端口 8181）。
• 在提供配置指导之前，MUST 确认 AWS CLI（或 call_aws）可用。
• MUST 检查 Create API，并提前询问所有必需参数，包括引擎变体、区域、VPC/子网 ID、名称、实例类型以及受支持的加密选项。对于生产环境的 V3 工作负载，在建议使用客户管理的 KMS 密钥以实现策略控制、轮换、撤销和 CloudTrail 可见性之前，先确认该 API 支持此选项。收集符合该 API 接受格式的标识符。

工具调用示例：

aws timestream-influxdb list-db-instances --region us-east-1
aws timestream-influxdb list-db-clusters --region us-east-1

资源标记（创建资源时始终应用）

创建任何集群或实例（create-db-cluster、create-db-instance）时，始终包含以下标签：

--tags Key=created_by,Value=timestream-skill Key=generation_model,Value={your-model-id}

示例：--tags Key=created_by,Value=timestream-skill Key=generation_model,Value=claude-sonnet-4-20250514

即使用户未提及标签，也要包含这些标签，以便他们识别通过本技能创建的资源。如果用户提供了其他标签，请将这些标签追加到用户的标签中，而不是替换它们。

2. 选择合适的引擎变体

决策流程：

1. 新工作负载 → InfluxDB 3 Core（高可用多节点部署使用 Enterprise）。
2. 现有 V2 迁移到 AWS → InfluxDB 2（如果读负载较重，则使用 Read Replica Cluster）。
3. 高基数（>10M 个序列）或 SQL → InfluxDB 3。
4. 需要 Processing Engine → InfluxDB 3。

在为 InfluxDB 3 或 V2 Read Replica Cluster 提供配置指导之前，MUST 加载并遵循 入门指南 中关于该引擎变体的创建、许可、IAM 和网络要求。 对于 V3 加密选项、客户管理的 KMS 密钥策略、迁移或密钥生命周期指导，请加载加密指南。

MUST 遵循的配置和运维要求：

• InfluxDB 3 Core 创建约定： 为新的 V3 Core 工作负载创建资源时，使用 create-db-cluster，并使用确切的默认参数组标识符 InfluxDBV3Core。不要使用 create-db-instance，也不要传入仅适用于 V2 的 allocatedStorage、dbStorageType、deploymentType、username、password、organization 或 bucket 字段。Core 使用端口 8181 进行连接。预置前，请查阅 Timestream for InfluxDB 文档和当前的 CreateDbCluster API 模型，确认 Core 当前的 Marketplace 和许可前提条件；切勿沿用 V2、Read Replica 或 Enterprise 的要求。如果已安装的 CLI 或 SDK 模型未提供 V3 Core 创建约定，请更新该工具；切勿回退到 V2 创建操作或字段。
• 支持将 Core 升级为 Enterprise： 可通过 AWS Console 或 AWS Support 升级。确实存在升级路径——不要说这不可能，或必须创建新集群。
• 加密配置的可变性： 在断言密钥是否可以更改之前，请先核实 Create 和 Update API 模型中的 kmsKeyId；遵循加密指南中的“Choose the Key Before Creation”。
• 加密范围和密钥丢失： 查阅 Data protection 文档，并且只报告用户要求的细节；遵循加密指南中的“Response Scope”和“Existing Clusters and Key Loss”。
• 密钥验证： 只有将返回的 ARN 与请求的密钥 ARN 匹配后，才能确认特定的客户托管 KMS 密钥。只有在当前 GetDbCluster 响应文档明确说明其语义时，才可解释 kmsKeyId 缺失的含义；切勿用字段缺失来识别特定的客户托管 KMS 密钥。遵循加密指南中的“Verify the Key”。
• 创建完成： create-db-cluster 返回后，轮询 get-db-cluster，直到其报告 AVAILABLE 或终止性失败。集群仍处于 CREATING 状态时，不要报告创建完成，也不要让用户接手轮询。对于客户托管密钥请求，只有返回的 kmsKeyId ARN 与请求的密钥 ARN 匹配，才算成功；集群正在转换状态时若该值缺失，则表示尚未验证，必须在集群达到 AVAILABLE 后再次检查。
• 通过 ARN 获取 V3 初始令牌密钥： 检查 GetDbCluster 输出或 API 参考中的令牌密钥 ARN 字段，然后将返回的 ARN 传递给 AWS Secrets Manager。切勿根据命名约定推导密钥标识符。V3 使用 Authorization: Bearer <token>（而非 Token）。V2 使用 Authorization: Token <token>。
• reboot-db-cluster 支持使用 --instance-ids 指定目标节点。使用前，请核实当前允许的 ID 最大数量，以及 RebootDbCluster API 模型和 Timestream for InfluxDB 文档中的所有请求约束。不要声称不存在重启命令，也不要假设节点数量上限是固定的。
• 在断言 S3 日志传输是否可用或其配置路径之前，请核实 Create 和 Update API 请求参数，以及 Timestream for InfluxDB 日志传输文档。 只能使用这些来源记载的操作、服务主体和存储桶策略要求。
• 不要编造 CloudWatch 指标名称。 加载监控操作和指标发现，然后核实所选引擎变体和部署类型是否支持这些指标。如果不确定某项指标是否存在，请明确说明。
• 在断言备份或恢复是否可用之前，请核实 Timestream for InfluxDB CLI 或 SDK API 模型，以及客户托管备份和恢复文档。 按引擎变体和区域确认是否支持按需、定时、持续、时间点恢复以及自助恢复功能。对于 DbBackup 资源，请使用 DbBackup 术语，绝不要称为“快照”；并且要单独核实服务托管快照的可访问性和恢复路径。
• --publicly-accessible 是创建实例或集群时支持的选项。不要声称该服务仅支持 VPC 内访问——公共访问是一项可选择启用的功能。

3. 设计架构（标签与字段）

标签（已编入索引，用于 WHERE/GROUP BY）：必须具有较低的基数，例如 method、region、status_code。高基数字段值（用户 ID、请求 ID、跟踪 ID）必须作为字段，而不是标签——将它们设为标签会导致序列基数激增，并严重降低查询性能。

字段（未编入索引）：数值测量值、高基数字符串、二进制数据。

InfluxDB 3 对高基数的处理优于 V2，但标签设计会影响查询性能。加载架构设计指南，了解包括去重和保留在内的模式。

4. 从 LiveAnalytics 迁移

LiveAnalytics 处于维护模式。迁移到 InfluxDB 3：

• <1B 条记录 / <125GB：使用经过认证的 LiveAnalytics 迁移插件和迁移客户端。先导出到 S3（Parquet），再重新导入 V3。
• >1B 条记录：联系 AWS 客户团队——更大规模的迁移没有自助服务方案。

加载迁移指南了解操作步骤。

5. 使用 Processing Engine 插件（仅限 V3）

在列出插件或描述自定义插件支持之前，请从 Timestream for InfluxDB Processing Engine 文档或有文档记录的目录 API 中检索经过认证的插件目录和支持声明。只陈述检索到的来源所确认的内容：不要声称插件数量固定，不要提及检索到的目录中不存在的插件，也不要根据通用 InfluxDB 插件仓库推断服务的可用性。加载Processing Engine 指南，获取经过验证的触发器和配置指导。

6. 监控和运维

在提供指标、警报、维护、备份或恢复指导之前，加载监控运维和指标发现。在配置警报之前，根据服务文档和资源的 CloudWatch 遥测数据验证指标名称和维度。应通过各自的 API 模型验证维护请求格式、备份和恢复功能以及服务配额，不要依赖内嵌示例或固定的可用性声明。

故障排查

确认引擎变体以及部署/访问类型，然后加载故障排查手册，针对该引擎变体，获取有关连接、写入/查询、存储、复制和 S3 端点问题的经过验证的分类排查指导。切勿混用 V2 和 V3 的补救措施，也不要在完成手册中的验证步骤之前断言问题原因。

安全注意事项

在每种环境中应用以下基线控制措施：

• **IAM 权限过宽：**使用最小权限角色，并在激活后立即移除临时的宽泛权限。
• **密码或令牌暴露：**将 V2 初始密码和 V3 初始令牌存储在 AWS Secrets Manager 中；切勿将它们写入源代码、日志、Shell 历史记录或命令中的字面参数。按照对应引擎变体的工作流文档轮换或替换各凭证，并为每个工作负载签发范围受限的应用令牌。
• **VPC 配置错误：**优先使用私有网络，并将每条安全组规则限制为受信任的 CIDR 或安全组 ID；切勿允许 0.0.0.0/0。
• **加密缺失：**要求静态加密和传输中的 TLS。在选择客户管理的 KMS 密钥之前，请在数据保护文档和 API 模型中核实受支持的密钥选项。
• **审计缺失：**启用 CloudTrail、受支持的服务日志交付和运维警报。使用 SSE-KMS 保护 CloudTrail S3 对象、CloudWatch Logs 和警报主题，并启用 CloudTrail 日志文件校验。

在提供预置或运维指导之前，必须对每次部署（包括开发、试验和生产环境）加载并遵循安全最佳实践。

附加资源

• Timestream for InfluxDB 开发者指南
• Timestream for InfluxDB 中的安全性
• Timestream for InfluxDB 安全最佳实践
• Timestream for InfluxDB 定价
• InfluxDB 3 文档
• 架构设计最佳实践
• 处理引擎文档

从 aws-database-selection 移交

此技能可以直接调用，也可以在 aws-database-selection 父技能完成需求访谈并生成 requirements.json 工件后，从该技能进入。如果你在最近的对话中看到以反引号括起且符合 aws_dbs_requirements/*/requirements.json 格式的路径，请遵循 aws-database-selection/references/handoff-contract.md 中的入口协议：

1. 使用 file_read 读取工件。
2. 根据 aws-database-selection/references/workload-primary-artifact.schema.json 验证工件。如果格式错误或无法读取，请告知用户并在没有该工件的情况下继续。
3. 用一到两句加粗的话说明其中的相关信息，并引用工件中的高层事实（主要形状、硬性约束、迁移背景）——不要原样复述整个工件。
4. 检查范围：此技能适用于 Amazon Timestream for InfluxDB（V2、V2 Read Replica、V3），涵盖引擎变体选择、架构设计、从 LiveAnalytics 迁移以及 Processing Engine 插件。如果工件的 workload_primaries.dominant_shapes 或 migration_context 与此范围不符，请按照移交合同发出弱反压：对于 DynamoDB 上的非 InfluxDB 时序数据，建议使用 dynamodb-skill；如果主要形状不是时序数据，则建议返回 aws-database-selection；然后询问用户是要返回还是继续。不要默默误用该工件。
5. 按照此技能的原生工作流继续；如果建议基于需求得出，请引用工件路径作为依据。

此技能的所有面向用户的输出都遵循移交合同中的仅使用 Markdown 基本语法的格式约定：使用加粗标签，使用反引号标注路径和枚举值，使用项目符号列出备选项，不使用 ASCII 艺术字或框线字符。