From 33269a27da133dc92c3da42eec28c56e15a28843 Mon Sep 17 00:00:00 2001
From: Claude <claude@cafepieters.com>
Date: Sun, 3 May 2026 07:19:09 +0900
Subject: [PATCH] docs: add encryption key management and recovery guide to
 README

- Recommend explicit encryptionKey setting at install time
- Add kubectl recovery procedure for key mismatch (works even when
  pod is in CrashLoopBackOff via a temporary reader pod)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 Chart.yaml |  2 +-
 README.md  | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/Chart.yaml b/Chart.yaml
index 8145fd0..325f85e 100644
--- a/Chart.yaml
+++ b/Chart.yaml
@@ -2,7 +2,7 @@ apiVersion: v2
 name: n8n
 description: A Helm chart for n8n workflow automation on Kubernetes (ARM/Raspberry Pi ready)
 type: application
-version: "2.19.2-b"
+version: "2.19.2-c"
 appVersion: "2.19.2"
 keywords:
   - n8n
diff --git a/README.md b/README.md
index 48399c5..eadf155 100644
--- a/README.md
+++ b/README.md
@@ -186,13 +186,63 @@ n8n:
   protocol: https
 ```
 
+## 暗号化キーの管理
+
+n8n は起動時に `N8N_ENCRYPTION_KEY` を使って認証情報を暗号化し、その値を `/home/node/.n8n/config` に記録します。
+以降の起動でこのキーが変わると起動エラーになります。
+
+### 推奨設定
+
+初回インストール前に明示的にキーを指定することを推奨します:
+
+```bash
+helm install my-n8n cafepieters/n8n \
+  --set n8n.encryptionKey="$(openssl rand -hex 24)"
+```
+
+または `values.yaml` に記載:
+
+```yaml
+n8n:
+  encryptionKey: "your-fixed-encryption-key"
+```
+
+> **注意**: 未指定の場合、初回インストール時にランダム生成されます。`helm upgrade` では `lookup` で既存 Secret の値を維持するため通常は問題ありませんが、明示指定が最も安全です。
+
+### キーのミスマッチが起きた場合の復旧
+
+PVC 上の n8n コンフィグから元のキーを読み出します。Pod がクラッシュ中でも以下で取得できます
+（`my-n8n-n8n` は PVC 名 = `kubectl get pvc` で確認）:
+
+```bash
+kubectl run n8n-key-reader --image=alpine --restart=Never \
+  --overrides='{
+    "spec": {
+      "volumes": [{"name":"data","persistentVolumeClaim":{"claimName":"my-n8n-n8n"}}],
+      "containers": [{"name":"c","image":"alpine",
+        "command":["sh","-c","cat /data/config 2>/dev/null || cat /data/.n8n/config 2>/dev/null || echo NOT_FOUND"],
+        "volumeMounts":[{"name":"data","mountPath":"/data"}]}]
+    }
+  }' --attach --rm
+```
+
+出力の `encryptionKey` の値を確認し、以下でアップグレードして復旧します:
+
+```bash
+helm upgrade my-n8n cafepieters/n8n \
+  --set n8n.encryptionKey="<上で確認したキー>"
+```
+
 ## バージョン履歴
 
 | バージョン | n8n | 変更内容 |
 |---|---|---|
-| 2.19.2 | 2.19.2 | 初回リリース |
+| バージョン | n8n | 変更内容 |
+|---|---|---|
+| 2.19.2-c | 2.19.2 | 暗号化キー復旧手順を README に追加 |
 | 2.19.2-b | 2.19.2 | 暗号化キーを `lookup` で既存 Secret から維持、`helm upgrade` での再生成を防止 |
 | 2.19.2-a | 2.19.2 | `N8N_SECURE_COOKIE` を Ingress/TLS 設定から自動判定（HTTP/LoadBalancer 環境対応） |
+| 2.19.2 | 2.19.2 | 初回リリース |
 
 ## ライセンス