本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 對 S3 檔案進行故障診斷 此頁面可協助您診斷和解決 S3 檔案的常見問題。 + [掛載命令失敗](#s3-files-troubleshooting-mount-fails) + [檔案操作的許可遭拒](#s3-files-troubleshooting-permission-denied) + [智慧讀取路由無法運作](#s3-files-troubleshooting-read-routing) + [檔案系統持續傳回 NFS 伺服器錯誤](#s3-files-troubleshooting-encrypted-fs) + [檔案系統寫入後 S3 儲存貯體中缺少物件](#s3-files-troubleshooting-missing-object) + [顯示在失物招領目錄中的檔案](#s3-files-troubleshooting-lost-found) + [同步落後](#s3-files-troubleshooting-sync-behind) + [啟用用戶端偵錯日誌](#s3-files-troubleshooting-debug-logs) ## 掛載命令失敗 `mount -t s3files` 命令失敗並發生錯誤。 **常見原因和動作：** + **"mount.s3files： command not found"** – S3 Files 用戶端 (amazon-efs-utils) 未安裝或低於 3.0.0 版。安裝或升級用戶端。如需詳細資訊，請參閱[S3 檔案的先決條件](s3-files-prereq-policies.md)。 + **「無法解析檔案系統 DNS 名稱」**：EC2 執行個體執行所在的可用區域中沒有掛載目標。在該可用區域中建立掛載目標，或在具有掛載目標的可用區域中啟動執行個體。如需詳細資訊，請參閱[建立掛載目標](s3-files-mount-targets-creating.md)。 + **連線逾時** – 安全群組組態不允許 NFS 流量。確認掛載目標的安全群組允許來自執行個體安全群組的連接埠 2049 上的傳入 TCP，且執行個體的安全群組允許連接埠 2049 上的傳出 TCP 傳送至掛載目標的安全群組。如需詳細資訊，請參閱[S3 檔案的先決條件](s3-files-prereq-policies.md)。 + **掛載期間「拒絕存取」**：連接至運算資源的 IAM 角色沒有必要的 S3 檔案許可。確認角色已連接 `AmazonS3FilesClientFullAccess`或 `AmazonS3FilesClientReadOnlyAccess`受管政策，或至少已連接 `s3files:ClientMount`許可。如需詳細資訊，請參閱[S3 檔案的先決條件](s3-files-prereq-policies.md)。 + **botocore 未安裝** – 掛載協助程式需要 botocore 才能與 AWS 服務互動。按照 GitHub 上 amazon-efs-utils README 中的指示安裝 botocore。 ## 檔案操作的許可遭拒 您可以掛載檔案系統，但在讀取、寫入或存取檔案時收到「拒絕許可」或「不允許操作」錯誤。 **常見原因和動作：** + **缺少寫入許可** – 如果您可以讀取但無法寫入，請確認連接至運算資源的 IAM 角色包含 `s3files:ClientWrite`許可，或連接 `AmazonS3FilesClientReadWriteAccess`或 `AmazonS3FilesClientFullAccess`受管政策。如需詳細資訊，請參閱 [AWS Amazon S3 檔案的 受管政策](s3-files-security-iam-awsmanpol.md)。 + **缺少根存取** – 如果您在存取根 (UID 0) 擁有的檔案時收到許可錯誤，您的 IAM 角色可能沒有 `s3files:ClientRootAccess`許可。如果沒有此許可，所有操作都會以 NFS 匿名使用者 （通常是 nfsnobody) 身分執行，這可能無法存取檔案。連接 `AmazonS3FilesClientFullAccess`受管政策或`s3files:ClientRootAccess`新增至您的政策。 + **檔案系統政策拒絕存取** – 如果您已連接檔案系統政策，請確認它不會拒絕用戶端所需的動作。身分型政策或檔案系統政策中的「允許」已足夠存取。如需詳細資訊，請參閱[S3 檔案如何與 IAM 搭配使用](s3-files-security-iam.md)。 + **POSIX 許可不相符** – S3 檔案會對檔案和目錄強制執行標準 POSIX 許可 （擁有者、群組、其他）。如果您的應用程式以不符合檔案擁有者或群組的使用者身分執行，即使 IAM 許可正確，存取也可能遭到拒絕。使用存取點強制執行所有請求的特定 UID/GID。如需詳細資訊，請參閱[建立 S3 檔案系統的存取點](s3-files-access-points-creating.md)。 ## 智慧讀取路由無法運作 S3 檔案會執行智慧型讀取路由，因為它會自動將讀取請求路由到最適合它們的儲存層，同時維護完整的檔案系統語意，包括一致性、鎖定和 POSIX 許可。從高效能儲存提供少量、隨機讀取的主動使用檔案，以降低延遲。直接從 S3 儲存貯體提供不在檔案系統上的大型循序讀取和資料讀取，以獲得高輸送量，無需檔案系統資料費用。 如果其中一個用戶端連線指標 (`NFSConnectionAccessible`、 和 `S3BucketReachable`) 顯示 0，或者如果您沒有看到預期的讀取輸送量`S3BucketAccessible`，則智慧型讀取路由可能無法運作。 **常見原因和動作：** + **運算角色缺少 S3 內嵌政策** – 連接至運算資源的 IAM 角色必須包含內嵌政策，並在連結的 S3 儲存貯體`s3:GetObjectVersion`上授予 `s3:GetObject`和 。如果沒有此政策，掛載協助程式無法直接從 S3 讀取，而且所有讀取都會經過檔案系統。如需詳細資訊，請參閱[S3 檔案的先決條件](s3-files-prereq-policies.md)。 + **無法存取 S3 儲存貯**體 – 檢查 `S3BucketReachable` 指標。如果顯示 0，請確認您的運算資源具有 S3 的網路存取權 （例如，透過 VPC 端點或 NAT 閘道）。 + **檔案已修改** – 只有在檔案尚未透過檔案系統修改時，才會直接從 S3 提供讀取。如果您已寫入 檔案，且變更尚未同步至 S3，則 讀取會經過檔案系統，直到同步完成為止。 ## 檔案系統持續傳回 NFS 伺服器錯誤 加密檔案系統持續傳回 NFS 伺服器錯誤。當 S3 檔案因為下列其中一個原因無法從 AWS KMS 擷取 KMS 金鑰時，可能會發生這些錯誤： + 該金鑰已停用。 + 該金鑰已刪除。 + S3 檔案使用金鑰的許可已撤銷。 + AWS KMS 暫時無法使用。 **採取動作** 首先，確認 AWS KMS 金鑰已啟用。您可以在 KMS 主控台中 AWS 檢視您的金鑰。如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》**中的[檢視金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html)。 如果該金鑰未啟用，請將其啟用。如需詳細資訊，請參閱《*AWS Key Management Service 開發人員指南*》中的[啟用和停用金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/enabling-keys.html)。 如果金鑰正在等待刪除，請取消刪除並重新啟用金鑰。如需詳細資訊，請參閱 [Key Management Service 開發人員指南中的排程和取消金鑰刪除](https://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys.html)。 *AWS * 如果金鑰已啟用，但您仍然遇到問題，請聯絡 AWS Support。 ## 檔案系統寫入後 S3 儲存貯體中缺少物件 您透過檔案系統撰寫檔案，並預期它在 S3 儲存貯體中顯示為物件，但物件不存在。S3 檔案批次會變更大約 60 秒，然後再將其複製到 S3。如果物件仍未顯示，則匯出可能已失敗。在這種情況下，您會看到 `FailedExports` CloudWatch 指標增加。 **採取動作** 使用延伸屬性檢查檔案的匯出狀態： ``` getfattr -n "user.s3files.status;$(date -u +%s)" missing-file.txt --only-values ``` 屬性名稱中的時間戳記可確保您取得最新狀態。輸出範例： ``` S3Key: s3://bucket/prefix/missing-file.txt ExportError: PathTooLong ``` `ExportError` 如果沒有匯出失敗，則不會顯示 。如果 S3 物件從未連結至 檔案，則 `S3Key` 為空白。 下表列出所有可能`ExportError`的值： | 錯誤 | 原因 | | --- | --- | | S3AccessDenied | S3 檔案擔任的 IAM 角色沒有足夠的許可寫入 S3 儲存貯體。如需詳細資訊，請參閱[S3 檔案的先決條件](s3-files-prereq-policies.md)。 | | S3BucketNotFound | 來源 S3 儲存貯體不再存在或已重新命名。驗證它存在於預期的 AWS 區域和帳戶中。 | | InternalError | 發生內部系統錯誤。 | | S3UserMetadataTooLarge | 超過 S3 使用者中繼資料大小限制。如需這些限制的資訊[不支援的功能、限制和配額](s3-files-quotas.md)，請參閱 。 | | FileSizeExceedsS3Limit | 檔案大小超過 S3 物件大小限制。如需這些限制的資訊[不支援的功能、限制和配額](s3-files-quotas.md)，請參閱 。 | | EncryptionKeyInaccessible | S3 儲存貯體使用的加密金鑰無法存取 S3 檔案。授予 S3 檔案存取加密金鑰的權限。如需詳細資訊，請參閱[加密](s3-files-encryption.md)。 | | RoleAssumptionFailed | 無法擔任該角色。檢查您的信任政策。如需詳細資訊，請參閱[S3 檔案的先決條件](s3-files-prereq-policies.md)。 | | KeyTooLongToBreakCycle | S3 檔案無法解析循環相依性 （例如，因為將兩個檔案重新命名為彼此的名稱），因為檔案路徑超過 S3 金鑰長度限制。縮短目錄路徑以解決此錯誤。 | | PathTooLong | 您的檔案路徑超過 S3 金鑰長度限制。如需這些限制的資訊[不支援的功能、限制和配額](s3-files-quotas.md)，請參閱 。 | | DependencyExportFailed | 父項或相依性具有不可重試的匯出失敗。使用 檢查父系或任何相依性的狀態getfattr。 | | S3ObjectArchived | S3 物件已封存 (S3 Glacier Flexible Retrieval 或 S3 Glacier Deep Archive)，無法讀取。先使用 S3 APIs 還原物件。 | S3 檔案會自動重試失敗的匯出。 `ExportError` 只會針對無法重試的錯誤顯示。 ## 顯示在失物招領目錄中的檔案 檔案已出現在檔案系統根`.s3files-lost+found-file-system-id`目錄中的 目錄中。在這種情況下，您會看到 `LostAndFoundFiles` CloudWatch 指標增加。當同步衝突發生時，就會發生這種情況。當透過檔案系統修改相同的檔案，且對應的 S3 物件在 S3 檔案將檔案系統變更同步回 S3 之前變更時，就會發生衝突。S3 檔案會將 S3 儲存貯體視為事實來源，將衝突的檔案移至遺失和找到的目錄，並將最新版本從 S3 儲存貯體匯入檔案系統。 **識別失物招領目錄中的檔案** 當 S3 檔案將檔案移至遺失並找到的目錄時，它會在檔案名稱前面加上十六進位識別符，以區分可能隨時間移動的相同檔案的多個版本。超過 100 個字元的檔案名稱會被截斷，以為此識別符騰出空間。檔案的原始目錄路徑不會保留在遺失和找到的目錄中。 **採取動作** 取得檔案的原始路徑和對應的 S3 物件金鑰： ``` getfattr -n "user.s3files.status;$(date -u +%s)" .s3files-lost+found-fs-12345678/abcdef1234_report.csv --only-values ``` 輸出範例： ``` S3Key: s3://bucket/prefix/report.csv FilePath: /data/report.csv ``` | 欄位 | Description | | --- | --- | | S3Key | 造成衝突之物件的完整 S3 路徑，如果在 S3 儲存貯體中刪除物件，則為空白。 | | FilePath | 檔案在衝突之前的相對路徑。 | 然後，您可以從 S3 儲存貯體保留最新版本，並從遺失和找到的目錄刪除檔案，或將檔案從遺失和找到的目錄複製回其原始路徑，以覆寫 S3 版本。 **注意** 失物招領目錄中的檔案會無限期保留，並計入您的檔案系統儲存成本。不再需要檔案時，從遺失和找到的目錄中刪除檔案。 ## 同步落後 `PendingExports` CloudWatch 指標正在成長，表示您的工作負載產生變更的速度比 S3 檔案可以同步到 S3 的速度快。 這表示您的工作負載可能超過同步速率。S3 檔案每秒每個檔案系統匯出最多 800 個檔案。考慮降低檔案修改速率，或在多個檔案系統中分配工作。隨著時間的推移監控`PendingExports`指標。如果穩定或減少，S3 檔案就會趕上。如果持續成長，請聯絡 AWS Support。 ## 啟用用戶端偵錯日誌 如果您要對掛載、連線或讀取略過問題進行故障診斷，您可以在 S3 檔案用戶端上啟用偵錯層級記錄，以擷取更多詳細資訊。 **掛載協助程式和監視程式日誌** 編輯記錄層級，`/etc/amazon/efs/s3files-utils.conf`並將記錄層級從 INFO 變更為 DEBUG： ``` [DEFAULT] logging_level = DEBUG ``` 卸載和重新掛載檔案系統，以使變更生效： ``` sudo umount /mnt/s3files sudo mount -t s3files file-system-id:/ /mnt/s3files ``` 日誌會寫入 `/var/log/amazon/efs/`。掛載協助程式日誌為 `mount.log`。 **Proxy (efs-proxy) 日誌** 代理處理 NFS 流量和 S3 讀取繞過。若要啟用代理的偵錯記錄，請編輯 `/etc/amazon/efs/s3files-utils.conf`： ``` [proxy] proxy_logging_level = DEBUG ``` 卸載並重新掛載，以使變更生效。Proxy 日誌會寫入 `/var/log/amazon/efs/`。 **TLS 通道 (stunnel) 日誌** 預設會停用 TLS 通道日誌。若要啟用它們，請編輯`/etc/amazon/efs/s3files-utils.conf`並設定下列項目： ``` [mount] stunnel_debug_enabled = true ``` 若要將檔案系統的所有 stunnel 日誌儲存至單一檔案，也請取消註解`stunnel_logs_file`行： ``` stunnel_logs_file = /var/log/amazon/efs/{fs_id}.stunnel.log ``` **日誌大小限制** 日誌檔案會自動輪換。您可以在 中設定輪換檔案的大小上限和數量`s3files-utils.conf`： ``` [DEFAULT] logging_max_bytes = 1048576 logging_file_count = 10 ``` 預設值為每個日誌檔案 1 MB，具有 10 個輪換檔案，每個日誌類型最多 10 MB。 **與 AWS Support 共用日誌** 聯絡 AWS Support 時，請將用戶端日誌和組態收集到單一封存中： ``` sudo tar -czf /tmp/s3files-support-logs.tar.gz \ /var/log/amazon/efs/ \ /etc/amazon/efs/s3files-utils.conf ``` 將 `/tmp/s3files-support-logs.tar.gz`納入您的支援案例。