企业官网建设流程全解析

• 教育
• 后端
• 前端

本文以仓库内随 AWS SDK for PHP 一并分发的主版本支持策略文档 S3_EC_SUPPORT_POLICY.md 为主体，结合 public/lib/aws-sdk/src/S3/Crypto 目录下的真实实现源码，系统讲解 Amazon S3 Encryption Client for PHP（简称 S3EC for PHP）的主版本生命周期、各主版本当前支持状态，以及作为 Moodle 内置依赖应当如何判断版本健康度并规划安全迁移。读完本文，你将能依据官方支持矩阵快速判定手中 SDK 版本所处的维护阶段，理解 1.x/2.x/3.x 在算法与安全性上的本质差异，并掌握在 Moodle 项目中定位、核验与升级该组件的方法。

一、策略文档的定位：它规定什么、覆盖哪些更新

该文档位于仓库内的 AWS SDK 源码树中，路径为 public/lib/aws-sdk/src/S3/Crypto/S3_EC_SUPPORT_POLICY.md，紧邻加密客户端的三个实现文件，专门用于描述Amazon S3 Encryption Client for PHP的支持政策。

按文档 "Overview" 一节的规定，AWS 会定期为这个客户端发布更新，更新内容可能包括：

• 对新 API、新功能的支持；
• 功能增强（enhancements）；
• 缺陷修复（bug fixes）；
• 安全补丁（security patches）；
• 文档更新；
• 对依赖项（dependencies）、语言运行时（language runtimes）和操作系统（operating systems）的适配性调整。

文档同时给出明确的使用建议：用户应持续跟踪 S3EC for PHP 的发布节奏，以获取最新功能、安全更新与底层依赖的修复；继续使用不受支持的 SDK 版本不被推荐，由此产生的风险由使用者自行承担（"Continued use of an unsupported SDK version is not recommended and is done at the user's discretion"）。

这一条对 Moodle 部署者尤其重要：Moodle 通过 composer.json 以依赖形式引入aws/aws-sdk-php（当前锁定版本为3.356.22），并按照 readme_moodle.txt 的说明将 SDK 的src目录整体 vendor 进 public/lib/aws-sdk/src。也就是说，SDK 的主版本支持状态，会直接影响所有依赖 S3 加密能力（例如对象存储备份）的 Moodle 站点的安全基线。

二、主版本生命周期：与 AWS SDK 维护策略对齐

文档 "Major Version Lifecycle" 一节指出，S3 Encryption Client 遵循与 AWS SDK 相同的主版本生命周期，读者可参考 AWS 官方 "SDKs and Tools Maintenance Policy" 中的 version-life-cycle 说明。（顺带说明一个细节：原文在该句中将客户端误写为 "for Go"，结合文档标题 "Amazon S3 Encryption Client for PHP" 与下文版本矩阵，可确认其实际指代的是PHP版本客户端。）

在此基础上，结合文档版本矩阵中实际出现三种状态，可以把 S3EC 各主版本的生命周期归纳为三个阶段：

理解这一生命周期的意义在于：主版本一旦进入 Maintenance 或 End of Support，就意味着"功能迭代停止"乃至"安全补丁停止"，继续使用将面临未修复漏洞长期暴露的风险，这与文档 "Overview" 中"保持更新以跟进安全补丁"的建议一脉相承。

三、版本支持矩阵：3.x / 2.x / 1.x 的当前状态

文档 "Version Support Matrix" 一节给出了完整的支持状态表格，此处完整呈现：

对表格的逐项解读：

• 3.x（当前主版本）：处于 General Availability，是当前唯一完整支持、持续迭代的主版本。文档没有为其标注下一个状态与日期，意味着短期内无降级或停止支持的安排。
• 2.x（过渡版本）：当前仍为 General Availability，但按文档记载，其下一个状态为 Maintenance，计划过渡日期为2026-06-15。这释放的信号是：2.x 的功能开发已接近收尾，未来只保留维护性修复，工程团队应当把迁移到 3.x 提上日程。
• 1.x（遗留版本）：已处于End of Support，不再提供任何更新，文档明确不建议继续使用。

四、从源码看三个主版本的"真身"：算法与安全差异

支持矩阵并非空泛声明，仓库中的三个客户端实现可以精确对应到表格的每一行。

1.x —— 遗留实现 S3EncryptionClient

• 实现文件：public/lib/aws-sdk/src/S3/Crypto/S3EncryptionClient.php
• 类注释中明确标注@deprecated，并声明 "Legacy implementation using older encryption workflow"（旧版加密工作流）。
• 内部常量CRYPTO_VERSION = '1n'（见 S3EncryptionClient.php），用于 User-Agent 指标上报。
• 构造函数会直接触发E_USER_DEPRECATED错误，提示 "S3EncryptionClient is deprecated and will be removed in a future release due to security vulnerabilities"（因安全漏洞即将在后续版本中被移除）。
• 在加密参数上，1.x 同时接受cbc与gcm两种 Cipher，其中cbc已被标记为弃用、建议改用gcm（见类注释中对@CipherOptions的说明）。

2.x —— 过渡实现 S3EncryptionClientV2

• 实现文件：public/lib/aws-sdk/src/S3/Crypto/S3EncryptionClientV2.php
• 常量CRYPTO_VERSION = '2.1'（S3EncryptionClientV2.php）。
• 相比 1.x 改为全面使用 AES-GCM，并引入 Key Commitment 相关的@CommitmentPolicy参数（该版本仅支持FORBID_ENCRYPT_ALLOW_DECRYPT一档，见 AbstractCryptoClientV2.php）。
• 构造函数同样触发E_USER_DEPRECATED，且警告文本直接点出安全原因：CVE-2024-56473，并建议尽快迁移到S3EncryptionClientV3（见 S3EncryptionClientV2.php）。
• 一个值得注意的运行时细节：对于 PHP < 7.1 的环境，2.x 使用 AES-GCM 的 polyfill 实现，大输入数据下性能显著低于 PHP 7.1+ 的原生实现，这也是升级 PHP 运行时的理由之一（见类注释）。

3.x —— 当前主版本 S3EncryptionClientV3

• 实现文件：public/lib/aws-sdk/src/S3/Crypto/S3EncryptionClientV3.php
• 常量CRYPTO_VERSION = '3.0'（S3EncryptionClientV3.php）。
• 类注释明确声明：AWS 强烈建议从 V2/V1 升级到 V3，因其提供更新的数据安全最佳实践；V3 包含破坏性变更，迁移需要工程团队提前规划，新工作流应直接基于 V3 起步。
• 构造函数在初始化时强制校验openssl扩展是否加载，未加载则抛出CryptoException（S3EncryptionClientV3.php）；同时会拒绝把另一个加密客户端当作底层 S3Client 传入（S3EncryptionClientV3.php）。
• V3 的@CommitmentPolicy支持完整三档配置，Cipher 仅接受gcm，KeySize仅支持 256。

版本演进小结

五、支持策略在源码中的"落地机制"

支持策略不是靠文档喊口号，而是通过代码层面的几类机制强制或提示用户：

1. 弃用即报错：E_USER_DEPRECATED触发

1.x 与 2.x 的构造函数都会trigger_error(..., E_USER_DEPRECATED)。这意味着任何仍然实例化旧客户端的新代码，在 PHP 的默认错误报告级别下都会收到明确的弃用提示，形成第一道"迁移提醒"。

2. Key Commitment 策略的强制校验

V3 通过 CryptoParamsTraitV3.php 中的getKeyCommitmentPolicy()强制要求@CommitmentPolicy必须显式传入且必须是受支持的值，否则抛出InvalidArgumentException。三档策略的语义为（以 S3EncryptionClientV3.php 注释为准）：

• FORBID_ENCRYPT_ALLOW_DECRYPT：写入时不使用密钥承诺，读取时允许带或不带密钥承诺的对象；
• REQUIRE_ENCRYPT_ALLOW_DECRYPT：写入时使用密钥承诺，读取时允许带或不带密钥承诺的对象；
• REQUIRE_ENCRYPT_REQUIRE_DECRYPT：写入时使用密钥承诺，读取时只接受带密钥承诺的对象。

在 AlgorithmSuite.php 中可以看到策略到算法的映射：FORBID_ENCRYPT_ALLOW_DECRYPT选用不带密钥承诺的ALG_AES_256_GCM_IV12_TAG16_NO_KDF，其余两档选用带 HKDF-SHA512 密钥承诺的ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY，并且 V3 只接受 256 位的密钥长度（"not supported by AES (256)"）。这从算法层解释了为什么 3.x 是支持矩阵中唯一持续获得新安全特性的主版本。

3. 加密客户端的实际用法（V3 写读示例）

V3 类注释提供了完整可运行的写读示例，核心要点是：加密客户端包装一个普通的S3Client，并通过@MaterialsProvider（如KmsMaterialsProviderV3）、@CipherOptions、@CommitmentPolicy等前缀为@的参数控制加密行为。写路径示例如下：

use Aws\Crypto\KmsMaterialsProviderV3; use Aws\S3\Crypto\S3EncryptionClientV3; use Aws\S3\S3Client; $encryptionClient = new S3EncryptionClientV3( new S3Client([ 'region' => 'us-west-2', 'version' => 'latest' ]) ); $materialsProvider = new KmsMaterialsProviderV3( new KmsClient([ 'profile' => 'default', 'region' => 'us-east-1', 'version' => 'latest', ], 'your-kms-key-id' ); $encryptionClient->putObject([ '@MaterialsProvider' => $materialsProvider, '@CipherOptions' => [ 'Cipher' => 'gcm', 'KeySize' => 256, ], '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT', '@KmsEncryptionContext' => ['foo' => 'bar'], 'Bucket' => 'your-bucket', 'Key' => 'your-key', 'Body' => 'your-encrypted-data', ]);

读取路径与此对称，同样传入@MaterialsProvider、@CipherOptions与@CommitmentPolicy后调用getObject([...])。完整的参数说明与读路径示例可参见 S3EncryptionClientV3.php 的类注释。

六、在 Moodle 项目中核验与规划迁移

1. 定位与核验当前版本

• SDK 本体 vendor 在 public/lib/aws-sdk，可通过 readme_moodle.txt 了解其导入/更新流程（下载官方包后将src目录拷贝至lib/aws-sdk/src，并同步 LICENSE、README 等文件）。
• 依赖声明在 composer.json（"aws/aws-sdk-php": "3.356.22"），即当前仓库内置的是 AWS SDK 3.356.22。由于 S3EC 是 SDK 的组成部分，SDK 3.x 对应矩阵中的 3.x 主版本，处于 General Availability 阶段。
• 需要判断某个站点实际运行的是哪个 SDK 版本时，可检查站点composer.lock中的aws/aws-sdk-php条目，或直接查看public/lib/aws-sdk的 vendor 快照。

2. 迁移判断清单（依据支持矩阵）

3. 迁移注意事项

• 3.x 含破坏性变更：类注释明确提示迁移需要工程团队规划（breaking changes），不能简单替换类名了事；需同步调整@MaterialsProvider（改用 V3 系列）、@CommitmentPolicy（必须显式指定）、@CipherOptions（仅gcm/256）等参数。
• 新项目直接从 3.x 起步：这是源码注释给出的明确建议（"New workflows should just start with S3EncryptionClientV3"）。
• 关注运行时前提：V3 初始化要求openssl扩展存在；V2 在 PHP < 7.1 下依赖 AES-GCM polyfill 且性能明显下降，升级 PHP 运行时本身也是安全与性能的一部分。
• 安全优先级：1.x 与 2.x 的弃用警告均指向安全漏洞，这与策略文档"持续更新以获取安全补丁"的核心主张一致，应把升级视为安全合规动作而非可选优化。

七、总结

S3_EC_SUPPORT_POLICY.md 用一张矩阵清晰划定了 S3EC for PHP 各主版本的支持边界：3.x 处于 General Availability 且持续演进，2.x 将于 2026-06-15 转入 Maintenance，1.x 已停止支持。仓库源码从三个维度印证了这一策略——通过E_USER_DEPRECATED弃用警告、通过 V3 对 Key Commitment 策略与算法套件的强制约束、通过各版本CRYPTO_VERSION常量的指标化区分。对 Moodle 运维与开发者而言，正确解读这份策略文档的落点只有一个：尽早把基于旧版加密客户端的代码迁移到 3.x，并保持 SDK 依赖随官方发布节奏更新，这样才能持续获得新特性与安全补丁，避免把站点暴露在不受支持版本的安全风险之下。

• 教育
• 后端
• 前端