踐指南：狀態(tài)漂移、v5 破壞性變更與常見錯(cuò)誤速查)
Cloudflare Terraform Provider 排障與最佳實(shí)踐指南狀態(tài)漂移、v5 破壞性變更與常見錯(cuò)誤速查【免費(fèi)下載鏈接】skillsSkills Catalog for Codex項(xiàng)目地址: https://gitcode.com/GitHub_Trending/skills4/skills本指南以 skills/.curated/cloudflare-deploy/references/terraform/gotchas.md 為核心系統(tǒng)梳理 Cloudflare Terraform Provider 使用中最容易踩坑的問題資源狀態(tài)漂移State Drift、v4→v5 升級(jí)帶來的資源重命名與屬性變更、各資源類型特有的陷阱R2 區(qū)域大小寫、KV 特殊字符、D1 遷移、Worker 體積上限、Pages 漂移以及高頻報(bào)錯(cuò)與配額限制。讀完本文你將掌握如何用lifecycle.ignore_changes、terraform state mv、terraform import等標(biāo)準(zhǔn)手段消除漂移、完成 v5 遷移并快速定位部署失敗根因。背景先確認(rèn)你的 Provider 版本與認(rèn)證方式在進(jìn)入具體排障之前先確認(rèn)當(dāng)前 Provider 版本。本倉(cāng)庫的 Terraform 參考文檔README明確標(biāo)注版本狀態(tài)說明5.x當(dāng)前Current由 OpenAPI 自動(dòng)生成相對(duì) v4 存在破壞性變更4.x遺留Legacy手工維護(hù)已廢棄推薦的 provider 聲明方式版本用~固定小版本避免不可控升級(jí)terraform { required_version 1.0 required_providers { cloudflare { source cloudflare/cloudflare version ~ 5.15.0 } } } provider cloudflare { api_token var.cloudflare_api_token # 或通過 CLOUDFLARE_API_TOKEN 環(huán)境變量 }認(rèn)證優(yōu)先級(jí)見 READMEAPI Token推薦api_token或CLOUDFLARE_API_TOKEN可在 Dashboard → My Profile → API Tokens 創(chuàng)建建議按賬戶/區(qū)域最小授權(quán)Global API Key遺留api_keyapi_email或CLOUDFLARE_API_KEYCLOUDFLARE_EMAIL安全性較低User Service Key用于 Origin CA 證書的user_service_key。注意文中出現(xiàn) Invalid provider configuration 報(bào)錯(cuò)時(shí)請(qǐng)先回到這一步檢查令牌權(quán)限見后文常見錯(cuò)誤。狀態(tài)漂移State Drift與生命周期管理Terraform 的核心工作方式是期望狀態(tài) vs 實(shí)際狀態(tài)的比對(duì)。當(dāng) Cloudflare API 返回的屬性與 Terraform state 中的記錄不一致例如 API 自動(dòng)補(bǔ)充了默認(rèn)值、Secret 類屬性永遠(yuǎn)以 REDACTED 返回就會(huì)出現(xiàn)永無休止的 perpetual diff——每次terraform plan/apply都提示有變更但無論怎么 apply 都消不掉。已知漂移資源速查表資源漂移屬性解決方法cloudflare_pages_projectdeployment_configs.*ignore_changes [deployment_configs]cloudflare_workers_scriptsecrets 以 REDACTED 返回ignore_changes [secret_text_binding]cloudflare_load_balanceradaptive_routing、random_steeringignore_changes [adaptive_routing, random_steering]cloudflare_workers_kv鍵中的特殊字符 5.16.0升級(jí)到 5.16.0忽略 Secret 漂移的完整示例# 示例忽略 secret 漂移 resource cloudflare_workers_script api { account_id var.account_id name api-worker content file(worker.js) secret_text_binding { name API_KEY text var.api_key } lifecycle { ignore_changes [secret_text_binding] } }為什么 secrets 必然漂移因?yàn)?Cloudflare API 出于安全考慮讀取階段不會(huì)回傳 Secret 明文而是返回REDACTED。Terraform state 里保存的是你配置的明文兩者每次比對(duì)都不一致。因此對(duì)secret_text_binding這類屬性標(biāo)準(zhǔn)的工程做法就是用lifecycle.ignore_changes明確告訴 Terraform不要追蹤它的變更。這也是 configuration.md 中 Worker 綁定模型下 Secret 綁定的標(biāo)準(zhǔn)形態(tài)。Pages 項(xiàng)目的漂移處理Pages 項(xiàng)目漂移的根因是Cloudflare API 會(huì)自動(dòng)補(bǔ)上 Terraform state 中不存在的默認(rèn)值例如deployment_configs里各環(huán)境默認(rèn)的兼容性日期、環(huán)境變量等從而形成永續(xù)差異。解決辦法是給cloudflare_pages_project加上生命周期忽略塊resource cloudflare_pages_project site { account_id var.account_id name site production_branch main # deployment_configs 等由 API 回填默認(rèn)值的字段 lifecycle { ignore_changes [deployment_configs] } }完整 Pages 項(xiàng)目配置含 build_config、source、自定義域名可參考 configuration.md。工程提示ignore_changes是必要的妥協(xié)濫用會(huì)掩蓋真實(shí)變更。最佳實(shí)踐是把已知且無害的 API 回填字段列入忽略清單其余字段保持嚴(yán)格追蹤。v5 破壞性變更與狀態(tài)遷移Provider v5 由 OpenAPI 自動(dòng)生成資源命名體系整體重構(gòu)v4→v5 是一次不可自動(dòng)平滑的升級(jí)。升級(jí)后直接terraform plan會(huì)報(bào)資源不存在需要先做狀態(tài)遷移。資源重命名對(duì)照表v4 資源v5 資源備注cloudflare_recordcloudflare_dns_recordcloudflare_worker_scriptcloudflare_workers_script注意變?yōu)閺?fù)數(shù)cloudflare_worker_*cloudflare_workers_*所有 Worker 資源cloudflare_access_*cloudflare_zero_trust_*Access → Zero Trust數(shù)據(jù)源data source的命名同樣發(fā)生變更見 api.mdcloudflare_record→cloudflare_dns_record、cloudflare_worker_script→cloudflare_workers_script、cloudflare_access_*→cloudflare_zero_trust_*。屬性變更對(duì)照表v4 屬性v5 屬性適用資源zonenamezoneaccount_idaccount.idzone對(duì)象語法keykey_nameKVlocation_hintlocationR2v5 中 zone 資源的寫法變?yōu)閷?duì)象語法例如 configuration.mdresource cloudflare_zone example { account { id var.account_id } name example.com type full }狀態(tài)遷移命令升級(jí) v5 后把舊資源名在 state 中改名為新資源名# 在 v5 升級(jí)后重命名 state 中的資源 terraform state mv cloudflare_record.example cloudflare_dns_record.example terraform state mv cloudflare_worker_script.api cloudflare_workers_script.api遷移完成后再執(zhí)行terraform plan確認(rèn)無破壞性差異。從倉(cāng)庫的 configuration.md 可看到 v5 的資源形態(tài)Worker 已演進(jìn)出cloudflare_workercloudflare_worker_versioncloudflare_workers_deployment的漸進(jìn)式發(fā)布gradual rollout模型生產(chǎn)環(huán)境推薦使用該模型而非單一cloudflare_workers_script。資源級(jí)陷阱逐個(gè)拆解R2 區(qū)域大小寫敏感問題Terraform 創(chuàng)建 R2 bucket 成功但后續(xù)apply失敗。根因R2 的location屬性必須大寫小寫會(huì)觸發(fā)反復(fù)不一致。解決使用WNAM、ENAM、WEUR、EEUR、APAC不要寫成wnam、enam等。resource cloudflare_r2_bucket assets { account_id var.account_id name assets location WNAM # 必須大寫 }在 patterns.md 與 configuration.md 中R2 bucket 均以location WNAM大寫形式出現(xiàn)屬于倉(cāng)庫內(nèi)反復(fù)驗(yàn)證的寫法。R2 運(yùn)行時(shí)的其他邊界如 S3 SDK 必須設(shè)置region: auto、流式上傳必須顯式提供長(zhǎng)度可進(jìn)一步參考 r2/gotchas.md。KV 鍵的特殊字符問題Provider 5.16.0問題鍵中包含、#、%時(shí)出現(xiàn)編碼問題。根因Provider 5.16.0 之前存在 URL 編碼缺陷。解決升級(jí)到 5.16.0或避免在鍵中使用特殊字符。v5 中 KV 資源的鍵屬性已由 v4 的key改名為key_name見屬性變更表正確的 KV 資源寫法參考 configuration.mdresource cloudflare_workers_kv_namespace cache { account_id var.account_id title cache } resource cloudflare_workers_kv config { account_id var.account_id namespace_id cloudflare_workers_kv_namespace.cache.id key_name config value jsonencode({ version 1.0 }) }D1 遷移Terraform 只建庫不建表問題Terraform 創(chuàng)建了 D1 數(shù)據(jù)庫但 schema 是空的。根因Terraform 只負(fù)責(zé)創(chuàng)建 D1 資源本身不會(huì)執(zhí)行 SQL 遷移。解決在terraform apply之后用 wrangler 執(zhí)行遷移# 在 terraform apply 之后 wrangler d1 migrations apply db-name這個(gè)雙工具分工是倉(cāng)庫推薦的模式patterns.md 明確 Terraform 負(fù)責(zé) Zones、DNS、安全規(guī)則、Access、負(fù)載均衡、Worker 部署、KV/R2/D1 資源創(chuàng)建而 wrangler 負(fù)責(zé)本地開發(fā)、手動(dòng)部署、D1 遷移、KV 批量操作、wrangler tail日志流。生產(chǎn)環(huán)境遷移必須加--remote標(biāo)志wrangler d1 migrations apply db-name --remote否則遷移只落在本地——這一條在 d1/gotchas.md 中有專門警示。Worker 腳本體積上限10 MB問題Worker 部署失敗報(bào) script too large。根因Worker 腳本 依賴超過 10 MB 上限。解決使用代碼拆分code splitting、外部依賴或壓縮minification。10 MB 上限在限額一節(jié)會(huì)再次出現(xiàn)屬于 Worker 平臺(tái)的硬性約束。倉(cāng)庫 configuration.md 展示的兩種 Worker 部署形態(tài)都通過content file(worker.js)打包腳本腳本體積直接決定是否觸及該限制。常見錯(cuò)誤速查Error: couldnt find resource原因資源在 Terraform 之外被刪除Dashboard 手動(dòng)刪、他人誤刪等。解決用terraform import重新導(dǎo)入 state或從 state 中移除terraform import cloudflare_zone.example zone-id terraform state rm cloudflare_zone.example各類資源的 import ID 格式可查 api.md資源Import ID 格式cloudflare_zonezone-idcloudflare_dns_recordzone-id/record-idcloudflare_workers_scriptaccount-id/script-namecloudflare_workers_kv_namespaceaccount-id/namespace-idcloudflare_r2_bucketaccount-id/bucket-namecloudflare_d1_databaseaccount-id/database-idcloudflare_pages_projectaccount-id/project-name409 Conflict on worker deployment原因同一個(gè) Worker 同時(shí)被 Terraform 和 wrangler 部署。解決二選一。如果使用 Terraform就移除 wrangler 的部署操作。這是倉(cāng)庫反復(fù)強(qiáng)調(diào)的Provider-first / 單一工具原則Terraform 與 wrangler不得管理同一批資源見 README 與 patterns.md 的 CRITICAL 提示。分工建議Terraform 管基礎(chǔ)設(shè)施與 CI/CD 部署wrangler 只管本地開發(fā)與遷移類操作。DNS record already exists原因已有 DNS 記錄未導(dǎo)入 Terraform state。解決在 Cloudflare Dashboard 找到記錄 ID導(dǎo)入terraform import cloudflare_dns_record.example zone-id/record-id也可以借助 cf-terraforming 從現(xiàn)有資源批量生成 HCL 并導(dǎo)入詳見 README# 生成 HCL cf-terraforming generate --resource-type cloudflare_dns_record --zone zone-id # 導(dǎo)入 state cf-terraforming import --resource-type cloudflare_dns_record --zone zone-idInvalid provider configuration原因API Token 缺失、無效或缺少所需權(quán)限。解決設(shè)置CLOUDFLARE_API_TOKEN環(huán)境變量或在 Dashboard 檢查 Token 權(quán)限。State locking errors原因多個(gè) Terraform 進(jìn)程并發(fā)運(yùn)行或崩潰進(jìn)程遺留了過期的鎖。解決用terraform force-unlock lock-id移除過期鎖慎用僅在確認(rèn)沒有其他進(jìn)程在跑時(shí)執(zhí)行。更穩(wěn)妥的團(tuán)隊(duì)協(xié)作方式見 README團(tuán)隊(duì)環(huán)境一律使用遠(yuǎn)程 stateS3、Terraform Cloud 等。倉(cāng)庫 patterns.md 還給出了用 Cloudflare R2 充當(dāng) S3 兼容后端存 tfstate 的完整backend s3配置region 設(shè)為auto、endpoint 指向https://account_id.r2.cloudflarestorage.com并關(guān)閉憑據(jù)/區(qū)域/元數(shù)據(jù)校驗(yàn)。平臺(tái)限額速查資源限額備注API Token 限流依套餐而定開啟api_client_logging true輔助排查Worker 腳本體積10 MB含全部依賴KV 鍵數(shù)量無上限按操作計(jì)費(fèi)R2 存儲(chǔ)無上限按 GB 計(jì)費(fèi)D1 數(shù)據(jù)庫數(shù)每賬戶 50,000免費(fèi)版 10Pages 項(xiàng)目數(shù)每賬戶 500免費(fèi)賬戶 100DNS 記錄數(shù)每區(qū)域 3,500免費(fèi)套餐補(bǔ)充與限額直接相關(guān)的運(yùn)行時(shí)約束來自各產(chǎn)品參考文檔均為倉(cāng)庫內(nèi)可查證內(nèi)容KV鍵最長(zhǎng) 512 字節(jié)、單值最大 25 MiB、單鍵寫入速率 1 次/秒超出返回 429、全局傳播 ≤60 秒見 kv/gotchas.mdR2單對(duì)象 5 TB、分片上傳最多 10,000 片、非末片最小 5 MB、批量刪除 1,000 鍵見 r2/gotchas.mdD1免費(fèi)版單庫 500 MB、付費(fèi) 10 GB查詢超時(shí) 30 秒批量語句免費(fèi)版 1,000 條、付費(fèi) 10,000 條見 d1/gotchas.md。結(jié)語一條可復(fù)用的排障流程當(dāng)terraform plan/apply出現(xiàn)異常時(shí)按以下順序排查可覆蓋本指南 90% 以上的場(chǎng)景確認(rèn)版本Provider 是否為 5.x舊配置是否仍在使用 v4 資源名與屬性名是 → 先做terraform state mv遷移確認(rèn)認(rèn)證CLOUDFLARE_API_TOKEN是否有效且權(quán)限充足報(bào) Invalid provider configuration → 檢查 Token看是否漂移diff 集中在 secrets、deployment_configs、load balancer 路由字段→ 加lifecycle.ignore_changes看是否并發(fā)/重復(fù)管理報(bào) 409→ 檢查 wrangler 與 Terraform 是否在管同一 Worker報(bào) state lock→terraform force-unlock謹(jǐn)慎看資源是否被外部改動(dòng)報(bào) couldnt find resource 或 already exists→terraform import或terraform state rm看是否觸及平臺(tái)硬性限額腳本超 10 MB、D1 無表缺遷移、R2 大小寫錯(cuò) → 分別按上文處理。更多配套資料Provider 配置與認(rèn)證、資源配置大全、數(shù)據(jù)源與導(dǎo)入格式、多環(huán)境與 CI/CD 模式。本文檔屬于 cloudflare-deploy skill 的 Terraform 排障部分該 skill 將 Terraform 作為 Cloudflare 基礎(chǔ)設(shè)施即代碼IaC的核心選項(xiàng)之一與 Pulumi、REST API 并列?！久赓M(fèi)下載鏈接】skillsSkills Catalog for Codex項(xiàng)目地址: https://gitcode.com/GitHub_Trending/skills4/skills創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Cloudflare Terraform Provider 排障與最佳實(shí)踐指南：狀態(tài)漂移、v5 破壞性變更與常見錯(cuò)誤速查
Cloudflare Terraform Provider 排障與最佳實(shí)踐指南狀態(tài)漂移、v5 破壞性變更與常見錯(cuò)誤速查【免費(fèi)下載鏈接】skillsSkills Catalog for Codex項(xiàng)目地址: https://gitcode.com/GitHub_Trending/skills4/skills本指南以 skills/.curated/cloudflare-deploy/references/terraform/gotchas.md 為核心系統(tǒng)梳理 Cloudflare Terraform Provider 使用中最容易踩坑的問題資源狀態(tài)漂移State Drift、v4→v5 升級(jí)帶來的資源重命名與屬性變更、各資源類型特有的陷阱R2 區(qū)域大小寫、KV 特殊字符、D1 遷移、Worker 體積上限、Pages 漂移以及高頻報(bào)錯(cuò)與配額限制。讀完本文你將掌握如何用lifecycle.ignore_changes、terraform state mv、terraform import等標(biāo)準(zhǔn)手段消除漂移、完成 v5 遷移并快速定位部署失敗根因。背景先確認(rèn)你的 Provider 版本與認(rèn)證方式在進(jìn)入具體排障之前先確認(rèn)當(dāng)前 Provider 版本。本倉(cāng)庫的 Terraform 參考文檔README明確標(biāo)注版本狀態(tài)說明5.x當(dāng)前Current由 OpenAPI 自動(dòng)生成相對(duì) v4 存在破壞性變更4.x遺留Legacy手工維護(hù)已廢棄推薦的 provider 聲明方式版本用~固定小版本避免不可控升級(jí)terraform { required_version 1.0 required_providers { cloudflare { source cloudflare/cloudflare version ~ 5.15.0 } } } provider cloudflare { api_token var.cloudflare_api_token # 或通過 CLOUDFLARE_API_TOKEN 環(huán)境變量 }認(rèn)證優(yōu)先級(jí)見 READMEAPI Token推薦api_token或CLOUDFLARE_API_TOKEN可在 Dashboard → My Profile → API Tokens 創(chuàng)建建議按賬戶/區(qū)域最小授權(quán)Global API Key遺留api_keyapi_email或CLOUDFLARE_API_KEYCLOUDFLARE_EMAIL安全性較低User Service Key用于 Origin CA 證書的user_service_key。注意文中出現(xiàn) Invalid provider configuration 報(bào)錯(cuò)時(shí)請(qǐng)先回到這一步檢查令牌權(quán)限見后文常見錯(cuò)誤。狀態(tài)漂移State Drift與生命周期管理Terraform 的核心工作方式是期望狀態(tài) vs 實(shí)際狀態(tài)的比對(duì)。當(dāng) Cloudflare API 返回的屬性與 Terraform state 中的記錄不一致例如 API 自動(dòng)補(bǔ)充了默認(rèn)值、Secret 類屬性永遠(yuǎn)以 REDACTED 返回就會(huì)出現(xiàn)永無休止的 perpetual diff——每次terraform plan/apply都提示有變更但無論怎么 apply 都消不掉。已知漂移資源速查表資源漂移屬性解決方法cloudflare_pages_projectdeployment_configs.*ignore_changes [deployment_configs]cloudflare_workers_scriptsecrets 以 REDACTED 返回ignore_changes [secret_text_binding]cloudflare_load_balanceradaptive_routing、random_steeringignore_changes [adaptive_routing, random_steering]cloudflare_workers_kv鍵中的特殊字符 5.16.0升級(jí)到 5.16.0忽略 Secret 漂移的完整示例# 示例忽略 secret 漂移 resource cloudflare_workers_script api { account_id var.account_id name api-worker content file(worker.js) secret_text_binding { name API_KEY text var.api_key } lifecycle { ignore_changes [secret_text_binding] } }為什么 secrets 必然漂移因?yàn)?Cloudflare API 出于安全考慮讀取階段不會(huì)回傳 Secret 明文而是返回REDACTED。Terraform state 里保存的是你配置的明文兩者每次比對(duì)都不一致。因此對(duì)secret_text_binding這類屬性標(biāo)準(zhǔn)的工程做法就是用lifecycle.ignore_changes明確告訴 Terraform不要追蹤它的變更。這也是 configuration.md 中 Worker 綁定模型下 Secret 綁定的標(biāo)準(zhǔn)形態(tài)。Pages 項(xiàng)目的漂移處理Pages 項(xiàng)目漂移的根因是Cloudflare API 會(huì)自動(dòng)補(bǔ)上 Terraform state 中不存在的默認(rèn)值例如deployment_configs里各環(huán)境默認(rèn)的兼容性日期、環(huán)境變量等從而形成永續(xù)差異。解決辦法是給cloudflare_pages_project加上生命周期忽略塊resource cloudflare_pages_project site { account_id var.account_id name site production_branch main # deployment_configs 等由 API 回填默認(rèn)值的字段 lifecycle { ignore_changes [deployment_configs] } }完整 Pages 項(xiàng)目配置含 build_config、source、自定義域名可參考 configuration.md。工程提示ignore_changes是必要的妥協(xié)濫用會(huì)掩蓋真實(shí)變更。最佳實(shí)踐是把已知且無害的 API 回填字段列入忽略清單其余字段保持嚴(yán)格追蹤。v5 破壞性變更與狀態(tài)遷移Provider v5 由 OpenAPI 自動(dòng)生成資源命名體系整體重構(gòu)v4→v5 是一次不可自動(dòng)平滑的升級(jí)。升級(jí)后直接terraform plan會(huì)報(bào)資源不存在需要先做狀態(tài)遷移。資源重命名對(duì)照表v4 資源v5 資源備注cloudflare_recordcloudflare_dns_recordcloudflare_worker_scriptcloudflare_workers_script注意變?yōu)閺?fù)數(shù)cloudflare_worker_*cloudflare_workers_*所有 Worker 資源cloudflare_access_*cloudflare_zero_trust_*Access → Zero Trust數(shù)據(jù)源data source的命名同樣發(fā)生變更見 api.mdcloudflare_record→cloudflare_dns_record、cloudflare_worker_script→cloudflare_workers_script、cloudflare_access_*→cloudflare_zero_trust_*。屬性變更對(duì)照表v4 屬性v5 屬性適用資源zonenamezoneaccount_idaccount.idzone對(duì)象語法keykey_nameKVlocation_hintlocationR2v5 中 zone 資源的寫法變?yōu)閷?duì)象語法例如 configuration.mdresource cloudflare_zone example { account { id var.account_id } name example.com type full }狀態(tài)遷移命令升級(jí) v5 后把舊資源名在 state 中改名為新資源名# 在 v5 升級(jí)后重命名 state 中的資源 terraform state mv cloudflare_record.example cloudflare_dns_record.example terraform state mv cloudflare_worker_script.api cloudflare_workers_script.api遷移完成后再執(zhí)行terraform plan確認(rèn)無破壞性差異。從倉(cāng)庫的 configuration.md 可看到 v5 的資源形態(tài)Worker 已演進(jìn)出cloudflare_workercloudflare_worker_versioncloudflare_workers_deployment的漸進(jìn)式發(fā)布gradual rollout模型生產(chǎn)環(huán)境推薦使用該模型而非單一cloudflare_workers_script。資源級(jí)陷阱逐個(gè)拆解R2 區(qū)域大小寫敏感問題Terraform 創(chuàng)建 R2 bucket 成功但后續(xù)apply失敗。根因R2 的location屬性必須大寫小寫會(huì)觸發(fā)反復(fù)不一致。解決使用WNAM、ENAM、WEUR、EEUR、APAC不要寫成wnam、enam等。resource cloudflare_r2_bucket assets { account_id var.account_id name assets location WNAM # 必須大寫 }在 patterns.md 與 configuration.md 中R2 bucket 均以location WNAM大寫形式出現(xiàn)屬于倉(cāng)庫內(nèi)反復(fù)驗(yàn)證的寫法。R2 運(yùn)行時(shí)的其他邊界如 S3 SDK 必須設(shè)置region: auto、流式上傳必須顯式提供長(zhǎng)度可進(jìn)一步參考 r2/gotchas.md。KV 鍵的特殊字符問題Provider 5.16.0問題鍵中包含、#、%時(shí)出現(xiàn)編碼問題。根因Provider 5.16.0 之前存在 URL 編碼缺陷。解決升級(jí)到 5.16.0或避免在鍵中使用特殊字符。v5 中 KV 資源的鍵屬性已由 v4 的key改名為key_name見屬性變更表正確的 KV 資源寫法參考 configuration.mdresource cloudflare_workers_kv_namespace cache { account_id var.account_id title cache } resource cloudflare_workers_kv config { account_id var.account_id namespace_id cloudflare_workers_kv_namespace.cache.id key_name config value jsonencode({ version 1.0 }) }D1 遷移Terraform 只建庫不建表問題Terraform 創(chuàng)建了 D1 數(shù)據(jù)庫但 schema 是空的。根因Terraform 只負(fù)責(zé)創(chuàng)建 D1 資源本身不會(huì)執(zhí)行 SQL 遷移。解決在terraform apply之后用 wrangler 執(zhí)行遷移# 在 terraform apply 之后 wrangler d1 migrations apply db-name這個(gè)雙工具分工是倉(cāng)庫推薦的模式patterns.md 明確 Terraform 負(fù)責(zé) Zones、DNS、安全規(guī)則、Access、負(fù)載均衡、Worker 部署、KV/R2/D1 資源創(chuàng)建而 wrangler 負(fù)責(zé)本地開發(fā)、手動(dòng)部署、D1 遷移、KV 批量操作、wrangler tail日志流。生產(chǎn)環(huán)境遷移必須加--remote標(biāo)志wrangler d1 migrations apply db-name --remote否則遷移只落在本地——這一條在 d1/gotchas.md 中有專門警示。Worker 腳本體積上限10 MB問題Worker 部署失敗報(bào) script too large。根因Worker 腳本 依賴超過 10 MB 上限。解決使用代碼拆分code splitting、外部依賴或壓縮minification。10 MB 上限在限額一節(jié)會(huì)再次出現(xiàn)屬于 Worker 平臺(tái)的硬性約束。倉(cāng)庫 configuration.md 展示的兩種 Worker 部署形態(tài)都通過content file(worker.js)打包腳本腳本體積直接決定是否觸及該限制。常見錯(cuò)誤速查Error: couldnt find resource原因資源在 Terraform 之外被刪除Dashboard 手動(dòng)刪、他人誤刪等。解決用terraform import重新導(dǎo)入 state或從 state 中移除terraform import cloudflare_zone.example zone-id terraform state rm cloudflare_zone.example各類資源的 import ID 格式可查 api.md資源Import ID 格式cloudflare_zonezone-idcloudflare_dns_recordzone-id/record-idcloudflare_workers_scriptaccount-id/script-namecloudflare_workers_kv_namespaceaccount-id/namespace-idcloudflare_r2_bucketaccount-id/bucket-namecloudflare_d1_databaseaccount-id/database-idcloudflare_pages_projectaccount-id/project-name409 Conflict on worker deployment原因同一個(gè) Worker 同時(shí)被 Terraform 和 wrangler 部署。解決二選一。如果使用 Terraform就移除 wrangler 的部署操作。這是倉(cāng)庫反復(fù)強(qiáng)調(diào)的Provider-first / 單一工具原則Terraform 與 wrangler不得管理同一批資源見 README 與 patterns.md 的 CRITICAL 提示。分工建議Terraform 管基礎(chǔ)設(shè)施與 CI/CD 部署wrangler 只管本地開發(fā)與遷移類操作。DNS record already exists原因已有 DNS 記錄未導(dǎo)入 Terraform state。解決在 Cloudflare Dashboard 找到記錄 ID導(dǎo)入terraform import cloudflare_dns_record.example zone-id/record-id也可以借助 cf-terraforming 從現(xiàn)有資源批量生成 HCL 并導(dǎo)入詳見 README# 生成 HCL cf-terraforming generate --resource-type cloudflare_dns_record --zone zone-id # 導(dǎo)入 state cf-terraforming import --resource-type cloudflare_dns_record --zone zone-idInvalid provider configuration原因API Token 缺失、無效或缺少所需權(quán)限。解決設(shè)置CLOUDFLARE_API_TOKEN環(huán)境變量或在 Dashboard 檢查 Token 權(quán)限。State locking errors原因多個(gè) Terraform 進(jìn)程并發(fā)運(yùn)行或崩潰進(jìn)程遺留了過期的鎖。解決用terraform force-unlock lock-id移除過期鎖慎用僅在確認(rèn)沒有其他進(jìn)程在跑時(shí)執(zhí)行。更穩(wěn)妥的團(tuán)隊(duì)協(xié)作方式見 README團(tuán)隊(duì)環(huán)境一律使用遠(yuǎn)程 stateS3、Terraform Cloud 等。倉(cāng)庫 patterns.md 還給出了用 Cloudflare R2 充當(dāng) S3 兼容后端存 tfstate 的完整backend s3配置region 設(shè)為auto、endpoint 指向https://account_id.r2.cloudflarestorage.com并關(guān)閉憑據(jù)/區(qū)域/元數(shù)據(jù)校驗(yàn)。平臺(tái)限額速查資源限額備注API Token 限流依套餐而定開啟api_client_logging true輔助排查Worker 腳本體積10 MB含全部依賴KV 鍵數(shù)量無上限按操作計(jì)費(fèi)R2 存儲(chǔ)無上限按 GB 計(jì)費(fèi)D1 數(shù)據(jù)庫數(shù)每賬戶 50,000免費(fèi)版 10Pages 項(xiàng)目數(shù)每賬戶 500免費(fèi)賬戶 100DNS 記錄數(shù)每區(qū)域 3,500免費(fèi)套餐補(bǔ)充與限額直接相關(guān)的運(yùn)行時(shí)約束來自各產(chǎn)品參考文檔均為倉(cāng)庫內(nèi)可查證內(nèi)容KV鍵最長(zhǎng) 512 字節(jié)、單值最大 25 MiB、單鍵寫入速率 1 次/秒超出返回 429、全局傳播 ≤60 秒見 kv/gotchas.mdR2單對(duì)象 5 TB、分片上傳最多 10,000 片、非末片最小 5 MB、批量刪除 1,000 鍵見 r2/gotchas.mdD1免費(fèi)版單庫 500 MB、付費(fèi) 10 GB查詢超時(shí) 30 秒批量語句免費(fèi)版 1,000 條、付費(fèi) 10,000 條見 d1/gotchas.md。結(jié)語一條可復(fù)用的排障流程當(dāng)terraform plan/apply出現(xiàn)異常時(shí)按以下順序排查可覆蓋本指南 90% 以上的場(chǎng)景確認(rèn)版本Provider 是否為 5.x舊配置是否仍在使用 v4 資源名與屬性名是 → 先做terraform state mv遷移確認(rèn)認(rèn)證CLOUDFLARE_API_TOKEN是否有效且權(quán)限充足報(bào) Invalid provider configuration → 檢查 Token看是否漂移diff 集中在 secrets、deployment_configs、load balancer 路由字段→ 加lifecycle.ignore_changes看是否并發(fā)/重復(fù)管理報(bào) 409→ 檢查 wrangler 與 Terraform 是否在管同一 Worker報(bào) state lock→terraform force-unlock謹(jǐn)慎看資源是否被外部改動(dòng)報(bào) couldnt find resource 或 already exists→terraform import或terraform state rm看是否觸及平臺(tái)硬性限額腳本超 10 MB、D1 無表缺遷移、R2 大小寫錯(cuò) → 分別按上文處理。更多配套資料Provider 配置與認(rèn)證、資源配置大全、數(shù)據(jù)源與導(dǎo)入格式、多環(huán)境與 CI/CD 模式。本文檔屬于 cloudflare-deploy skill 的 Terraform 排障部分該 skill 將 Terraform 作為 Cloudflare 基礎(chǔ)設(shè)施即代碼IaC的核心選項(xiàng)之一與 Pulumi、REST API 并列?！久赓M(fèi)下載鏈接】skillsSkills Catalog for Codex項(xiàng)目地址: https://gitcode.com/GitHub_Trending/skills4/skills創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考