本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
對 S3 檔案進行故障診斷
此頁面可協助您診斷和解決 S3 檔案的常見問題。
掛載命令失敗
mount -t s3files 命令失敗並發生錯誤。
常見原因和動作：
"mount.s3files： command not found" – S3 Files 用戶端 (amazon-efs-utils) 未安裝或低於 3.0.0 版。安裝或升級用戶端。如需詳細資訊，請參閱S3 檔案的先決條件。
「無法解析檔案系統 DNS 名稱」：EC2 執行個體執行所在的可用區域中沒有掛載目標。在該可用區域中建立掛載目標，或在具有掛載目標的可用區域中啟動執行個體。如需詳細資訊，請參閱建立掛載目標。
連線逾時 – 安全群組組態不允許 NFS 流量。確認掛載目標的安全群組允許來自執行個體安全群組的連接埠 2049 上的傳入 TCP，且執行個體的安全群組允許連接埠 2049 上的傳出 TCP 傳送至掛載目標的安全群組。如需詳細資訊，請參閱S3 檔案的先決條件。
掛載期間「拒絕存取」：連接至運算資源的 IAM 角色沒有必要的 S3 檔案許可。確認角色已連接
AmazonS3FilesClientFullAccess或AmazonS3FilesClientReadOnlyAccess受管政策，或至少已連接s3files:ClientMount許可。如需詳細資訊，請參閱S3 檔案的先決條件。botocore 未安裝 – 掛載協助程式需要 botocore 才能與 AWS 服務互動。按照 GitHub 上 amazon-efs-utils README 中的指示安裝 botocore。
檔案操作的許可遭拒
您可以掛載檔案系統，但在讀取、寫入或存取檔案時收到「拒絕許可」或「不允許操作」錯誤。
常見原因和動作：
缺少寫入許可 – 如果您可以讀取但無法寫入，請確認連接至運算資源的 IAM 角色包含
s3files:ClientWrite許可，或連接AmazonS3FilesClientReadWriteAccess或AmazonS3FilesClientFullAccess受管政策。如需詳細資訊，請參閱 AWS Amazon S3 檔案的 受管政策。缺少根存取 – 如果您在存取根 (UID 0) 擁有的檔案時收到許可錯誤，您的 IAM 角色可能沒有
s3files:ClientRootAccess許可。如果沒有此許可，所有操作都會以 NFS 匿名使用者 （通常是 nfsnobody) 身分執行，這可能無法存取檔案。連接AmazonS3FilesClientFullAccess受管政策或s3files:ClientRootAccess新增至您的政策。檔案系統政策拒絕存取 – 如果您已連接檔案系統政策，請確認它不會拒絕用戶端所需的動作。身分型政策或檔案系統政策中的「允許」已足夠存取。如需詳細資訊，請參閱S3 檔案如何與 IAM 搭配使用。
POSIX 許可不相符 – S3 檔案會對檔案和目錄強制執行標準 POSIX 許可 （擁有者、群組、其他）。如果您的應用程式以不符合檔案擁有者或群組的使用者身分執行，即使 IAM 許可正確，存取也可能遭到拒絕。使用存取點強制執行所有請求的特定 UID/GID。如需詳細資訊，請參閱建立 S3 檔案系統的存取點。
智慧讀取路由無法運作
S3 檔案會執行智慧型讀取路由，因為它會自動將讀取請求路由到最適合它們的儲存層，同時維護完整的檔案系統語意，包括一致性、鎖定和 POSIX 許可。從高效能儲存提供少量、隨機讀取的主動使用檔案，以降低延遲。直接從 S3 儲存貯體提供不在檔案系統上的大型循序讀取和資料讀取，以獲得高輸送量，無需檔案系統資料費用。
如果其中一個用戶端連線指標 (NFSConnectionAccessible、 和 S3BucketReachable) 顯示 0，或者如果您沒有看到預期的讀取輸送量S3BucketAccessible，則智慧型讀取路由可能無法運作。
常見原因和動作：
運算角色缺少 S3 內嵌政策 – 連接至運算資源的 IAM 角色必須包含內嵌政策，並在連結的 S3 儲存貯體
s3:GetObjectVersion上授予s3:GetObject和 。如果沒有此政策，掛載協助程式無法直接從 S3 讀取，而且所有讀取都會經過檔案系統。如需詳細資訊，請參閱S3 檔案的先決條件。無法存取 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 開發人員指南》中的檢視金鑰。
如果該金鑰未啟用，請將其啟用。如需詳細資訊，請參閱《AWS Key Management Service 開發人員指南》中的啟用和停用金鑰。
如果金鑰正在等待刪除，請取消刪除並重新啟用金鑰。如需詳細資訊，請參閱 Key Management Service 開發人員指南中的排程和取消金鑰刪除。 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 檔案的先決條件。 |
S3BucketNotFound |
來源 S3 儲存貯體不再存在或已重新命名。驗證它存在於預期的 AWS 區域和帳戶中。 |
InternalError |
發生內部系統錯誤。 |
S3UserMetadataTooLarge |
超過 S3 使用者中繼資料大小限制。如需這些限制的資訊不支援的功能、限制和配額，請參閱 。 |
FileSizeExceedsS3Limit |
檔案大小超過 S3 物件大小限制。如需這些限制的資訊不支援的功能、限制和配額，請參閱 。 |
EncryptionKeyInaccessible |
S3 儲存貯體使用的加密金鑰無法存取 S3 檔案。授予 S3 檔案存取加密金鑰的權限。如需詳細資訊，請參閱加密。 |
RoleAssumptionFailed |
無法擔任該角色。檢查您的信任政策。如需詳細資訊，請參閱S3 檔案的先決條件。 |
KeyTooLongToBreakCycle |
S3 檔案無法解析循環相依性 （例如，因為將兩個檔案重新命名為彼此的名稱），因為檔案路徑超過 S3 金鑰長度限制。縮短目錄路徑以解決此錯誤。 |
PathTooLong |
您的檔案路徑超過 S3 金鑰長度限制。如需這些限制的資訊不支援的功能、限制和配額，請參閱 。 |
DependencyExportFailed |
父項或相依性具有不可重試的匯出失敗。使用 檢查父系或任何相依性的狀態getfattr。 |
S3ObjectArchived |
S3 物件已封存 (S3 Glacier Flexible Retrieval 或 S3 Glacier Deep Archive)，無法讀取。先使用 S3 APIs 還原物件。 |
S3 檔案會自動重試失敗的匯出。 ExportError 只會針對無法重試的錯誤顯示。
顯示在失物招領目錄中的檔案
檔案已出現在檔案系統根.s3files-lost+found-目錄中的 目錄中。在這種情況下，您會看到 file-system-idLostAndFoundFiles 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 s3filesfile-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納入您的支援案例。
