docs: add encryption key management and recovery guide to README
Helm Chart Release / release-chart (push) Successful in 4s
Update Docker Image Tags and Release Helm Chart / update-and-release (push) Successful in 10s

- 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>
This commit is contained in:
2026-05-03 07:19:09 +09:00
parent 134d3e8bfc
commit 33269a27da
2 changed files with 52 additions and 2 deletions
+51 -1
View File
@@ -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 | 初回リリース |
## ライセンス