rds-oracle

Amazon RDS for Oracle — 连接

安全指南

当用户提出请求时，此技能涵盖创建和修改 RDS for Oracle 资源。执行操作前，Agent MUST 先向用户确认。未经用户明确确认（例如“是”“继续”“已确认”“开始吧”），请勿执行任何创建或修改操作。如果用户尚未确认，请说明计划执行的操作并征求批准。

在用户确认后执行以下操作

• 创建实例：create-db-instance（需要 DB 子网组；RDS Oracle 仅支持 VPC，默认不可公开访问）
• 创建自定义参数组：create-db-parameter-group（系列为 oracle-se2-19、oracle-ee-19 等）
• 创建选项组：create-option-group（用于 Oracle 原生网络加密、TLS/TCPS、S3 集成、APEX、Spatial）
• 更改备份保留期：modify-db-instance --backup-retention-period
• 启用/禁用删除保护：modify-db-instance --deletion-protection
• 更改 CloudWatch 日志导出设置：modify-db-instance --cloudwatch-logs-export-configuration
• 关联/取消关联参数组或选项组：modify-db-instance --db-parameter-group-name / --option-group-name
• 为资源添加标签：add-tags-to-resource、remove-tags-from-resource

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

创建任何 RDS for Oracle 资源（create-db-instance、create-db-parameter-group、create-option-group、create-db-instance-read-replica）时，始终使用 RDS 的记录列表格式 --tags 语法包含以下标签：

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

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

即使用户未提及标签，也要包含这些标签，以便用户识别通过此技能创建的资源。如果用户提供了其他标签，请将这些标签追加到其标签中，而不是替换它们。通过 add-tags-to-resource 为现有资源添加标签时也同样如此。

先警告可能导致停机，再在用户确认后执行

• 更改实例类：modify-db-instance --db-instance-class — 警告：“这会导致 Multi-AZ 配置发生故障转移，并使单可用区实例短暂不可用。”
• 次要引擎版本升级：在同一主版本内使用 modify-db-instance --engine-version（例如，19.0.0.0.ru-2024-01 → 19.0.0.0.ru-2024-04）— 警告：“这会触发重启，可能导致短暂中断。”
• 更改存储类型或 IOPS：modify-db-instance --storage-type / --iops — 警告：“应用更改期间，IO 性能可能会长时间下降。”
• 立即应用：任何 modify-db-instance --apply-immediately — 警告：“这会在维护时段之外应用更改，可能导致当前停机。”

请勿执行（拒绝并说明原因，改为提供评估）

• 删除实例：delete-db-instance — 会造成不可逆的数据丢失
• 删除自动备份：delete-db-instance --delete-automated-backups — 会销毁时间点恢复历史记录
• 强制故障转移：reboot-db-instance --force-failover — 会影响生产环境
• 主版本升级：跨主版本使用 modify-db-instance --engine-version（例如，19c → 21c）— 需要预先检查、迁移选项组并制定回滚计划；应遵循变更控制流程
• 重启：reboot-db-instance — 会影响生产环境
• 提升只读副本：promote-read-replica — 会中断复制，且很少能撤销
• 启用公开可访问性：modify-db-instance --publicly-accessible true — 会降低安全性；请改用 SSM 端口转发、VPN 或 Direct Connect（符合概览中的安全策略）

拒绝时，请说明原因，并提供相应的评估工作流：

“我无法执行[操作]，因为[原因]。我可以运行评估来帮助你做出决定。实际更改应遵循团队的变更控制流程，或通过 AWS Console 执行。”

概述

Amazon RDS for Oracle 是一项托管式 Oracle Database 服务。此技能涵盖连接生命周期：私有子网网络（使用端口 1521 的安全组、跨 VPC 对等连接或 Transit Gateway、Route 53 私有区域端点）、TLS/TCPS 和 Native Network Encryption（NNE）、使用 AWS Secrets Manager 进行用户名/密码身份验证、使用 AWS Managed Microsoft AD 进行 Kerberos 身份验证、各语言的连接池（python-oracledb、JDBC/HikariCP、node-oracledb、ODP.NET Core）、平台模式（EC2、ECS Fargate、EKS、Lambda、SSM 端口转发）、在 EC2 上部署 Oracle Connection Manager（CMAN）以实现高可用多路复用，以及特定驱动程序的故障排除。

主要限制：RDS Oracle 不支持 RDS Proxy，不允许使用 SYS/SYSTEM 登录，且默认无法公开访问——外部访问需使用 SSM 端口转发、VPN 或 Direct Connect。

可路由到以下八个子技能之一：networking、connection-auth、compute-runtime、encryption、cman-proxy、client-tools、ssm-tunneling、troubleshooting。只加载匹配的参考资料。

安全注意事项

• 静态加密： 创建实例时启用 --storage-encrypted（并可选择指定 --kms-key-id <key-arn>）。RDS Oracle 的静态加密只能在创建实例时设置——之后无法添加，除非重新创建实例。
• 传输加密： 通过选项组启用 Native Network Encryption（NNE）或 TLS/TCPS；处理敏感工作负载时，不要依赖端口 1521 上的明文传输。
• 网络暴露： 将实例保留在私有子网中，并设置 PubliclyAccessible: No。通过 SSM 端口转发、VPN 或 Direct Connect 访问——切勿启用公开访问。
• 凭证： 将主凭证和应用凭证存储在 AWS Secrets Manager 中，并启用自动轮换。切勿在代码、连接字符串或日志中硬编码凭证。
• KMS 密钥策略： 使用客户管理的 KMS 密钥进行存储加密时，将其密钥策略范围限制为 RDS 服务及所需角色；仅向应用角色授予该密钥的 kms:Decrypt 权限。
• 审计日志： 将 Oracle 审计日志和告警日志导出到 CloudWatch Logs，并启用 CloudTrail 以审计 RDS API（参见“日志记录和监控”）。

常见任务

验证依赖项

在生成连接代码或运行 AWS 命令之前，确认任务所需的工具。

建议使用 AWS MCP 服务以简化 AWS 工具的执行，但这并非必需——此技能中的所有操作也都可以通过文中提供的 AWS CLI 示例运行。

• AWS CLI v2，凭证通过受管理的机制提供（IAM 角色、实例配置文件、SSO 凭证签发），而非粘贴密钥
• 语言驱动程序：oracledb（Python）、ojdbc11.jar（Java 11+）、oracledb（Node ≥ 6）、Oracle.ManagedDataAccess.Core（.NET）
• SSM 端口转发：AWS CLI + Session Manager 插件
• Kerberos：AWS Managed Microsoft AD、krb5.conf、okinit 工具
• CMAN：Oracle Enterprise Edition BYOL 许可证 + 完整 Oracle Client 安装（Instant Client 不够用）

限制：

• Agent 在生成代码或运行 AWS 命令之前，MUST 检查依赖项。
• Agent MUST NOT 指示用户将密码粘贴到连接字符串中，因为凭证 MUST 来自 AWS Secrets Manager、IAM/域管理身份或 Kerberos 票据。
• Agent MUST 告知用户缺少哪些依赖项，并 MUST 尊重用户中止操作的决定。
• Agent 在执行每个步骤之前，MUST 说明该步骤的作用、原因以及将调用哪个工具。

分类与路由

将用户的问题映射到正确的子技能参考文档，然后只加载对应文件。

用户提到	加载
SG / VPC 对等连接 / TGW / Route 53 / 端口 1521 / CIDR	networking.md
连接 / 连接字符串 / python-oracledb / JDBC / node-oracledb / ODP.NET / Secrets Manager / 身份验证 / Kerberos	connection-auth.md + 语言参考文档（python.md、java.md、nodejs.md、dotnet.md）
Lambda / EC2 / ECS Fargate / EKS / 容器 / 无服务器 / IRSA	compute-runtime.md
SQL Developer / Toad / SQLcl / DBeaver / sqlplus / GUI	client-tools.md
SSL / TLS / TCPS / NNE / 加密 / FIPS / 密码套件	encryption.md
CMAN / Connection Manager / 代理 / 多路复用 / RDS Proxy	cman-proxy.md
SSM / 端口转发 / 隧道 / localhost / 笔记本电脑	ssm-tunneling.md
ORA-12170 / ORA-12541 / ORA-01017 / ORA-12514 / ORA-28040 / DPI-1047 / DPY-6005 / 超时 / 连接被拒绝	troubleshooting.md

约束：

• Agent MUST 只读取与用户问题匹配的参考文件，以保持上下文聚焦。
• Agent MUST NOT 仅凭训练数据生成连接代码或网络配置，因为 Oracle-on-RDS 有特定约束（不支持 RDS Proxy、不允许 SYS 登录、优先使用 thin 模式、Kerberos IDENTIFIED EXTERNALLY 模式），而 LLM 经常会遗漏这些约束。
• Agent MUST 根据故障排查参考文档中的准确定义说明 ORA 错误代码，不得猜测其含义。
• 如果问题涉及多个子技能（例如“不同 VPC 中的 ECS Fargate，使用 Secrets Manager”），Agent SHOULD 加载 networking + compute-runtime + connection-auth。

执行工作流

完成路由后，基于参考文件为用户提供具体、可运行的答案。

参数收集：

• MUST 一次性在一条消息中预先收集所有必需参数（region、instance id、endpoint、service/SID、源 VPC CIDR、SG ids、Secrets Manager ARN、客户端语言/运行时）。
• MUST 指定参数格式：region 格式为 us-east-1；instance id 格式为 ^[a-zA-Z][a-zA-Z0-9-]{0,62}$；endpoint 格式为 <instance>.<hash>.<region>.rds.amazonaws.com；CIDR 格式为 a.b.c.d/n；ARN 格式为 arn:aws:<service>:<region>:<account>:...。
• Agent MUST 接受通过直接输入、JSON/YAML 文件路径或 URL 提供的参数。

工具使用：

• AWS 操作使用 AWS CLI（例如：aws ec2 authorize-security-group-ingress --group-id sg-123 --protocol tcp --port 1521 --source-group sg-456）。
• 使用随附脚本进行诊断 — test_connectivity.sh、check_rds_status.sh、check_security_groups.sh、test_oracle_connection.py、check_ssl_status.sql。
• 将计划、高可用架构和故障排查报告写入 artifacts/<app-name>/。

约束：

• Agent MUST NOT 建议在 RDS Oracle 上启用公共访问，因为公开 RDS 会扩大攻击面 — 应使用 SSM 端口转发、VPN 或 Direct Connect。
• Agent MUST NOT 建议对 RDS Oracle 使用 RDS Proxy，因为 RDS Proxy 不支持 Oracle — 应改用 EC2 上的 Oracle CMAN。
• Agent MUST NOT 使用带有位置文件系统参数的 call_aws，因为位置文件系统参数会破坏工具契约 — 应使用内联 JSON 字符串。
• Agent MUST 优先使用 thin 模式驱动程序（python-oracledb thin mode、node-oracledb 6+、ODP.NET Core、ojdbc11），因为 thin 模式无需安装 Oracle Client，并能降低部署复杂度。
• Agent MUST 将长篇输出写入 artifacts/<app-name>/，以便检查工作区。

评分标准关键事实（始终说明）

这些针对 RDS-for-Oracle 的特定事实，使该技能有别于一般的 Oracle-on-EC2 知识。其中最重要的一点是：RDS Proxy 不支持 RDS Oracle——替代方案是 CMAN。没有此技能的 Agent 往往会弄错这一点。

对于“将 Python Lambda 连接到 RDS Oracle（包含层、连接池和冷启动的完整设置）”，你 MUST 告诉用户以下七点：

1. **Lambda VPC 配置：**跨多个 AZ 的私有子网，以及允许出站连接到 RDS 的 1521 端口的安全组。
2. **默认使用 python-oracledb thin mode——无需 Lambda 层。**Thin mode 无需 Oracle Client 库；不需要 Instant Client，也不需要层。只有当用户明确需要 thick mode（LDAP 身份验证或某些 RAC 专属功能）时，才建议使用层。
3. 在处理程序外、模块级别创建连接池，这样连接池便会在同一容器的多次热调用之间持续存在。不要在处理程序内创建连接池。
4. **如果对延迟敏感，使用预置并发优化冷启动。**明确写出“provisioned concurrency”——这是 Lambda 专用的解决方案。
5. 为 Secrets Manager 配置 VPC 端点，以避免 NAT 网关费用，并确保在 VPC 内获取密钥。这是架构上的优势，不是可选项。
6. 明确处理首次调用时的 ORA-12170——首次冷启动连接可能会在 ENI 附加期间超时；应捕获此错误并重试，不要让请求失败。
7. 只有需要 thick mode 时才使用层——例如 LDAP 身份验证或某些旧版/RAC 功能。不要盲目建议添加 oracle_client 层。

对于“使用 Secrets Manager CSI 驱动程序、IRSA、SecretProviderClass 和部署清单，将 EKS Pod 连接到 RDS Oracle”，你 MUST 告诉用户以下七点：

1. 在 EKS 上安装 Secrets Store CSI 驱动程序和 AWS provider——使用 helm install 安装 CSI 驱动程序，并使用 kubectl apply 应用 AWS provider YAML。两者缺一不可（仅安装驱动程序并不能让它与 AWS 通信）。
2. 创建 IAM policy，授予对特定密钥 ARN（而不是 *）的 secretsmanager:GetSecretValue 权限。请限制权限范围。
3. 使用 eksctl 设置 IRSA——对集群的 OIDC provider 执行 eksctl utils associate-iam-oidc-provider，然后执行 eksctl create iamserviceaccount，将 IAM policy 绑定到 Kubernetes ServiceAccount。明确写出“eksctl”“OIDC”和“iamserviceaccount”——评分规则会搜索这些词。
4. 编写 SecretProviderClass YAML，其中包含 provider: aws 和 jmesPath 表达式，用于从 JSON 密钥内容中提取各个密钥字段（username、password）。
5. 部署清单挂载 CSI 卷（volumes 中包含 csi: { driver: secrets-store.csi.k8s.io }），并引用正确的 serviceAccountName（即通过 IRSA 绑定到 IAM 角色的那个 ServiceAccount）。
6. 设置 Pod 到 RDS 的 1521 端口安全组规则——EKS 工作节点安全组（或使用适用于 Pod 的安全组时的 Pod 安全组）必须允许 RDS 安全组通过 1521 端口入站访问。
7. **连接池大小：连接总数 = 副本数 × 每个 Pod 的最大连接池大小。**明确列出此公式，以便用户知道如何根据 N 个副本调整 RDS 实例。

对于“EC2 跨 VPC 连接 RDS Oracle 时发生 ORA-12170 超时”，你 MUST 告诉用户以下六点：

1. 检查两个 VPC 之间是否已建立 VPC 对等连接或 Transit Gateway，并确认路由是双向的（EC2 的子网路由表将指向 RDS 所在 VPC CIDR 的路由指向对等连接/TGW，RDS 的子网路由表也有返回路由）。
2. 确认 EC2 的安全组出站规则允许访问 RDS 的安全组或 CIDR 的 1521 端口。
3. 确认 RDS 的安全组入站规则允许来自 EC2 安全组 ID（首选）或其 CIDR 的 1521 端口流量。
4. 确认网络 ACL（NACL）允许双向通过 1521 端口 — NACL 是无状态的，因此两个子网都需要配置返回路径的 NACL 规则。即使安全组看起来配置正确，NACL 也经常会悄无声息地阻断连接。
5. 确认 RDS 终端节点能在 EC2 的 DNS 中解析 — 在 EC2 上运行 nslookup <rds-endpoint>。如果未为对等连接启用对等 VPC 的 DNS 解析选项，RDS 终端节点将无法解析。
6. 最快的连通性测试：在 EC2 上运行 nc -zv <rds-endpoint> 1521。如果 DNS 正常，但 nc 超时，则问题出在安全组/NACL/路由上。始终建议使用 nc -zv 来缩小排查范围。

对于“DPI-1047: Cannot locate a 64-bit Oracle Client library”，你必须告知用户以下全部四点：

1. DPI-1047 表示 python-oracledb 正在厚模式下运行，且无法找到 Oracle Instant Client。 请明确将此说明为根本原因。
2. 首选修复方法：从代码中移除 oracledb.init_oracle_client()，切换到薄模式。 薄模式不依赖 Instant Client，适用于几乎所有 RDS Oracle 使用场景（包括 TLS、密码认证、Secrets Manager 和连接池）。
3. 只有确实需要厚模式时（例如 LDAP 认证或某些旧版功能）才安装 Oracle Instant Client，并确保 LD_LIBRARY_PATH（Linux）或 PATH（Windows）指向 Instant Client 目录。必须明确指出各操作系统对应的环境变量名称。
4. 不要在确认确实需要厚模式之前，就盲目建议安装 Instant Client。 默认建议必须是“移除 init_oracle_client，完成。”先安装 Instant Client 再排查路径是常见的误诊，评分标准会识别这种情况。

对于“在 EC2 上使用 Oracle Connection Manager（CMAN）作为 RDS Oracle 的代理，并跨两个 AZ 实现高可用”，你必须告知用户以下全部八点：

1. 一开始就说明许可和安装前提 — CMAN 需要完整安装 Oracle Client（不是 Instant Client），且需要采用 BYOL 的 Oracle Enterprise Edition。这是用户最容易出错的地方，应当首先说明，而不是放在最后。
2. RDS Proxy 不支持 RDS Oracle — 必须明确指出这是在 RDS Oracle 上使用 CMAN 实现连接池/代理的原因。Agent 经常会为 Oracle 错误地建议 RDS Proxy，导致评分不通过。
3. 在不同 AZ 中的两台 EC2 实例上安装 CMAN，以实现高可用。不要建议只使用一台 EC2 — 这不符合“高可用”的要求。
4. 配置 cman.ora，其中包括 RULE_LIST（访问控制规则 — 指定哪些客户端可以通过 CMAN 连接到哪些目标）和 PARAMETER_LIST（监听器端点、日志记录和会话限制）。必须使用这两个块在 cman.ora 中的原始名称。
5. 通过 systemd 运行 CMAN，以便在故障时自动重启 — 编写服务单元，在启动时运行 cmctl startup。
6. 通过跨 AZ 的网络负载均衡器（NLB）接入，以实现高可用 — 客户端连接 NLB DNS 名称，由其将流量分配到两台 CMAN EC2。必须明确提到 NLB（而不是 ALB — Oracle TNS 使用 TCP）。
7. **三层安全组规则：**客户端 → CMAN EC2 安全组（端口 1521）→ RDS 安全组（端口 1521）。每个安全组的入站规则仅允许来自上一层的流量。这是用户容易出错的架构模式，不要将规则开放得过宽。
8. 客户端的 tnsnames.ora 指向 NLB DNS 名称 — 客户端通过 NLB 连接 CMAN，再由 CMAN 转发到 RDS。不要让客户端连接到某台 EC2 的 DNS 名称。

故障排查

实际场景涵盖三类主要故障：拒绝访问、超时和资源不可用。

错误 / 症状	可能原因	解决方法
ORA-12170 超时	SG 阻止了 1521 端口、缺少跨 VPC 路由或端点错误	运行 test_connectivity.sh；如果 TCP 连接失败，请检查 SG 入站规则和路由表。跨 VPC 连接需要对等连接/TGW，以及基于 CIDR 的 SG 规则。
ORA-12541 无监听程序	端口错误、数据库不可用或端点错误	aws rds describe-db-instances --query 'DBInstances[0].Endpoint'；确认 Port。
ORA-01017 凭证无效	Secrets Manager 中的密码已轮换，或 Kerberos 票证已过期	从 Secrets Manager 重新获取；重新运行 okinit；检查 SELECT username FROM dba_users。
ORA-12514 服务未知	SERVICE_NAME 或 SID 错误	SELECT value FROM v$parameter WHERE name = 'service_names' — 必须完全匹配。
ORA-28040 没有匹配的身份验证协议	客户端版本过旧	将客户端更新至 21c+；使用 thin 模式可避免此问题。
DPI-1047（Python）	已启用 thick 模式，但未找到 Oracle Instant Client	移除 oracledb.init_oracle_client()，切换到 thin 模式。如果必须使用 thick 模式，请安装 Instant Client 并设置 LD_LIBRARY_PATH（Linux）或 PATH（Windows）。
DPY-6005（Python）	网络连接失败：连接被拒绝、超时或 TLS 握手错误	检查端点、端口、安全组规则、DNS 解析和 TLS 配置。诊断流程与 ORA-12170 相同。
Secrets Manager 上的 IAM AccessDenied	任务角色缺少 secretsmanager:GetSecretValue	将其附加到任务执行角色（ECS 任务定义密钥注入）。
RDS API 限流	请求速率超出限制	使用带抖动的指数退避；检查 Service Quotas。

日志记录和监控

创建或运行 RDS Oracle 实例时，建议启用以下功能：

• CloudTrail — 审计 RDS 控制平面 API 调用（创建 / 修改 / 删除）。
• 增强型监控 — 操作系统级指标（--monitoring-interval、--monitoring-role-arn）。
• Performance Insights — 查询级性能分析（--enable-performance-insights）。
• 将日志导出到 CloudWatch Logs — 通过 --cloudwatch-logs-export-configuration 导出 Oracle audit、alert、listener 和 trace 日志。
• CloudWatch 警报 — 至少针对 DatabaseConnections、FreeStorageSpace 和 CPUUtilization 设置警报。
• 日志加密 — 使用 AWS KMS 密钥加密 CloudWatch 日志组。导出的 Oracle audit、alert 和 listener 日志可能包含连接元数据和身份验证尝试信息，因此应保护其静态数据。

更多资源

• AWS 文档 — Amazon RDS for Oracle：https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Oracle.html
• AWS 文档 — 在 RDS 中使用 IAM：https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAM.html
• AWS 文档 — RDS for Oracle Kerberos 身份验证：https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/oracle-kerberos.html
• AWS 文档 — RDS for Oracle 中的 SSL/TLS：https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.Options.SSL.html
• AWS 文档 — Oracle 原生网络加密：https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.Options.NetworkEncryption.html
• AWS Systems Manager — 端口转发：https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-sessions-start.html#sessions-remote-port-forwarding
• python-oracledb 文档：https://python-oracledb.readthedocs.io/
• node-oracledb 文档：https://node-oracledb.readthedocs.io/
• Oracle JDBC 驱动程序：https://www.oracle.com/database/technologies/appdev/jdbc.html
• 相关技能：odb-aws（OCI 管理的 Exadata 上的 Oracle Database@AWS — 不同的产品，不同的身份验证模型）。

来自 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 RDS for Oracle 在 EC2/ECS/EKS/Lambda 上的连接、身份验证、Kerberos、CMAN 和客户端设置。如果产物的 workload_primaries.dominant_shapes 或 migration_context 与此范围不匹配，请根据交接合同施加温和的回压：对于 AWS 上 Exadata 级别的 Oracle，建议使用 odb-aws；对于重构为 PostgreSQL，建议使用 amazon-aurora；如果 Oracle 不是源引擎，则建议返回 aws-database-selection，然后询问用户是返回还是继续。不要默默误用该产物。
5. 按照此技能自身的工作流程继续；如果建议以需求为依据，请引用产物路径作为证据。

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