feat: Add Real IP forwarding feature for bare-metal clusters

ベアメタルKubernetesクラスターやLoadBalancer環境において、
PHP側で訪問者の実IPアドレスを取得できる機能を追加。

Changes:
- Add nginx.forwardRealIP configuration in values.yaml
- Implement real_ip_header and set_real_ip_from in Nginx config
- Pass real IP info to PHP-FPM via fastcgi_param
- Add usage example and documentation in README.md
- Create test-real-ip.php for verification
- Update chart version to 8.5.2-a

Features:
- Compatible with existing customConfig.snippet
- Configurable trusted proxy networks
- Supports multi-tier proxy with recursive option
- Default disabled for backward compatibility

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

CHANGELOG-8.5.2-a.md

@@ -0,0 +1,95 @@
+# Changelog - Version 8.5.2-a
+
+## 新機能
+
+### リアルIP転送機能の追加
+
+ベアメタルKubernetesクラスターやLoadBalancer環境において、PHP側で訪問者の実IPアドレスを取得できる機能を追加しました。
+
+#### 主な変更点
+
+1. **values.yaml**
+   - `nginx.forwardRealIP` セクションを追加
+   - `enabled`: リアルIP取得機能の有効/無効
+   - `header`: リアルIPを取得するHTTPヘッダー名（デフォルト: X-Forwarded-For）
+   - `recursive`: 再帰的にリアルIPを検索（多段プロキシ対応）
+   - `trustedProxies`: 信頼するプロキシのネットワーク範囲
+   - `additionalTrustedProxies`: 環境に応じた追加プロキシ設定
+
+2. **templates/configmap.yaml**
+   - Nginx の `http` セクションにリアルIP設定を追加
+   - `real_ip_header`, `real_ip_recursive`, `set_real_ip_from` ディレクティブを実装
+   - PHP-FPM へ渡す fastcgi_param にリアルIP情報を追加
+   - 既存の `customConfig.snippet` と競合しない構造
+
+3. **README.md**
+   - リアルIP転送機能の設定パラメータ表を追加
+   - 例7としてベアメタル環境でのリアルIP取得の使用例を追加
+   - 検証用PHPコード例を追加
+
+4. **examples/test-real-ip.php** (新規作成)
+   - リアルIP転送設定の動作確認用テストスクリプト
+   - WebUIで各種IP関連変数を確認可能
+   - 診断機能付き
+
+## 技術詳細
+
+### Nginx設定
+```nginx
+# HTTP-levelで設定
+real_ip_header X-Forwarded-For;
+real_ip_recursive on;
+set_real_ip_from 10.0.0.0/8;
+set_real_ip_from 172.16.0.0/12;
+set_real_ip_from 192.168.0.0/16;
+
+# PHP-FPMへ渡すパラメータ
+fastcgi_param REMOTE_ADDR $remote_addr;
+fastcgi_param HTTP_X_REAL_IP $remote_addr;
+fastcgi_param HTTP_X_FORWARDED_FOR $proxy_add_x_forwarded_for;
+```
+
+### PHPでの利用
+```php
+// リアルIPアドレスの取得
+$realIP = $_SERVER['REMOTE_ADDR'];
+```
+
+## 互換性
+
+- 既存の `nginx.customConfig.snippet` 機能と完全に互換性あり
+- デフォルトは `enabled: false` のため、既存環境への影響なし
+- 有効化時のみ、リアルIP取得ロジックが動作
+
+## セキュリティ
+
+- `trustedProxies` には信頼できるプロキシのみを指定してください
+- 不正なプロキシを信頼すると、IPスプーフィング攻撃のリスクがあります
+
+## 使用例
+
+```yaml
+# values.yaml
+nginx:
+  forwardRealIP:
+    enabled: true
+    header: "X-Forwarded-For"
+    recursive: true
+    trustedProxies:
+      - "10.0.0.0/8"
+      - "172.16.0.0/12"
+      - "192.168.0.0/16"
+    additionalTrustedProxies:
+      - "203.0.113.0/24"  # 外部LoadBalancerのIPレンジ
+```
+
+## 検証方法
+
+1. `examples/test-real-ip.php` を `/var/www/html/` に配置
+2. ブラウザでアクセス: `http://your-service/test-real-ip.php`
+3. `REMOTE_ADDR` にパブリックIPが表示されることを確認
+
+---
+
+**リリース日**: 2026-02-10
+**担当**: プロサーバーエンジニア（Claude）

Chart.yaml

@@ -2,6 +2,6 @@ apiVersion: v2
 name: phpfpm
 description: Nginx + PHP-FPM Helm Chart with external DB and optional Selenium support
 type: application
-version: 8.5.2
+version: 8.5.2-a
 appVersion: "8.5.2"
 icon: https://upload.wikimedia.org/wikipedia/commons/thumb/2/27/PHP-logo.svg/330px-PHP-logo.svg.png

README.md

@@ -163,6 +163,11 @@ kubectl logs -l app.kubernetes.io/name=phpfpm -c nginx
 |-----------|------|-----------|
 | `nginx.customConfig.enabled` | カスタム設定有効化 | `false` |
 | `nginx.customConfig.snippet` | 設定スニペット | `""` |
+| `nginx.forwardRealIP.enabled` | リアルIP取得有効化 | `false` |
+| `nginx.forwardRealIP.header` | リアルIP取得ヘッダー | `"X-Forwarded-For"` |
+| `nginx.forwardRealIP.recursive` | 再帰的IP検索 | `true` |
+| `nginx.forwardRealIP.trustedProxies` | 信頼するプロキシネットワーク | `["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]` |
+| `nginx.forwardRealIP.additionalTrustedProxies` | 追加の信頼プロキシ | `[]` |
 
 ## 使用例
 
@@ -347,7 +352,62 @@ persistence:
   enabled: true
 ```
 
-### 例7: 画像処理アプリケーション（GD拡張）
+### 例7: ベアメタル環境でのリアルIP取得
+
+ベアメタルKubernetesやLoadBalancer経由でのアクセスで、PHPからクライアントの実IPアドレスを取得する設定です。
+
+```yaml
+# values.yaml
+service:
+  type: LoadBalancer
+
+nginx:
+  forwardRealIP:
+    # リアルIP取得機能を有効化
+    enabled: true
+
+    # リアルIPを取得するヘッダー（環境に応じて変更）
+    # - X-Real-IP: シンプルな1段プロキシ
+    # - X-Forwarded-For: 多段プロキシ対応（推奨）
+    header: "X-Forwarded-For"
+
+    # 再帰的にリアルIPを検索（多段プロキシ環境で推奨）
+    recursive: true
+
+    # 信頼するプロキシのネットワーク範囲
+    # ベアメタルクラスターのPodネットワークとServiceネットワークを指定
+    trustedProxies:
+      - "10.0.0.0/8"      # Kubernetesデフォルトのクラスタネットワーク
+      - "172.16.0.0/12"   # Dockerデフォルトネットワーク
+      - "192.168.0.0/16"  # プライベートネットワーク
+
+    # 追加で信頼するプロキシ（外部LoadBalancerなど）
+    additionalTrustedProxies:
+      - "203.0.113.0/24"  # 外部LoadBalancerのIPレンジ（例）
+
+persistence:
+  enabled: true
+```
+
+この設定により、PHP側で以下の変数から実IPアドレスが取得できます：
+- `$_SERVER['REMOTE_ADDR']` - クライアントの実IPアドレス
+- `$_SERVER['HTTP_X_REAL_IP']` - 同上（互換性用）
+- `$_SERVER['HTTP_X_FORWARDED_FOR']` - プロキシチェーン全体
+
+**検証用PHPコード:**
+```php
+<?php
+echo "Real IP: " . $_SERVER['REMOTE_ADDR'] . "\n";
+echo "X-Real-IP: " . ($_SERVER['HTTP_X_REAL_IP'] ?? 'not set') . "\n";
+echo "X-Forwarded-For: " . ($_SERVER['HTTP_X_FORWARDED_FOR'] ?? 'not set') . "\n";
+```
+
+**注意事項:**
+- `trustedProxies`には、信頼できるプロキシ（LoadBalancer、Ingressコントローラー）のみを指定してください
+- 不正なプロキシを信頼すると、IPスプーフィング攻撃のリスクがあります
+- `customConfig.snippet`との併用も可能です（競合しません）
+
+### 例8: 画像処理アプリケーション（GD拡張）
 
 ```yaml
 # values.yaml
@@ -378,7 +438,7 @@ ingress:
     - host: images.example.com
 ```
 
-### 例8: 本番環境構成（フル機能）
+### 例9: 本番環境構成（フル機能）
 
 ```yaml
 # production-values.yaml

examples/test-real-ip.php

@@ -0,0 +1,226 @@
+<?php
+/**
+ * Real IP Test Script
+ *
+ * このスクリプトは、NginxのリアルIP転送設定が正しく動作しているかを確認します。
+ *
+ * 使用方法:
+ * 1. values.yamlでnginx.forwardRealIP.enabled=trueに設定
+ * 2. このファイルを /var/www/html/ に配置
+ * 3. ブラウザでアクセス: http://your-service/test-real-ip.php
+ */
+
+header('Content-Type: text/html; charset=utf-8');
+?>
+<!DOCTYPE html>
+<html lang="ja">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Real IP Test</title>
+    <style>
+        body {
+            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+            max-width: 800px;
+            margin: 50px auto;
+            padding: 20px;
+            background: #f5f5f5;
+        }
+        .container {
+            background: white;
+            padding: 30px;
+            border-radius: 8px;
+            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+        }
+        h1 {
+            color: #333;
+            border-bottom: 3px solid #4CAF50;
+            padding-bottom: 10px;
+        }
+        table {
+            width: 100%;
+            border-collapse: collapse;
+            margin-top: 20px;
+        }
+        th, td {
+            padding: 12px;
+            text-align: left;
+            border-bottom: 1px solid #ddd;
+        }
+        th {
+            background-color: #4CAF50;
+            color: white;
+            font-weight: bold;
+        }
+        tr:hover {
+            background-color: #f5f5f5;
+        }
+        .success {
+            color: #4CAF50;
+            font-weight: bold;
+        }
+        .warning {
+            color: #ff9800;
+            font-weight: bold;
+        }
+        .info {
+            background: #e3f2fd;
+            padding: 15px;
+            border-left: 4px solid #2196F3;
+            margin: 20px 0;
+        }
+        code {
+            background: #f4f4f4;
+            padding: 2px 6px;
+            border-radius: 3px;
+            font-family: 'Courier New', monospace;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>🔍 Real IP Detection Test</h1>
+
+        <div class="info">
+            <strong>ℹ️ 情報:</strong> このページは、NginxのリアルIP転送設定が正しく動作しているかを確認します。
+        </div>
+
+        <h2>📊 IP Address Information</h2>
+        <table>
+            <tr>
+                <th>変数名</th>
+                <th>値</th>
+                <th>説明</th>
+            </tr>
+            <tr>
+                <td><code>REMOTE_ADDR</code></td>
+                <td class="success"><?php echo htmlspecialchars($_SERVER['REMOTE_ADDR'] ?? 'not set'); ?></td>
+                <td>クライアントの実IPアドレス（Nginx real_ip設定適用後）</td>
+            </tr>
+            <tr>
+                <td><code>HTTP_X_REAL_IP</code></td>
+                <td><?php echo htmlspecialchars($_SERVER['HTTP_X_REAL_IP'] ?? 'not set'); ?></td>
+                <td>Nginxが設定したリアルIP（互換性用）</td>
+            </tr>
+            <tr>
+                <td><code>HTTP_X_FORWARDED_FOR</code></td>
+                <td><?php echo htmlspecialchars($_SERVER['HTTP_X_FORWARDED_FOR'] ?? 'not set'); ?></td>
+                <td>プロキシチェーン全体（カンマ区切り）</td>
+            </tr>
+            <tr>
+                <td><code>HTTP_CLIENT_IP</code></td>
+                <td><?php echo htmlspecialchars($_SERVER['HTTP_CLIENT_IP'] ?? 'not set'); ?></td>
+                <td>一部のプロキシが使用</td>
+            </tr>
+        </table>
+
+        <h2>🔧 All HTTP Headers</h2>
+        <table>
+            <tr>
+                <th>Header Name</th>
+                <th>Value</th>
+            </tr>
+            <?php
+            $headers = [];
+            foreach ($_SERVER as $key => $value) {
+                if (strpos($key, 'HTTP_') === 0) {
+                    $headerName = str_replace('_', '-', substr($key, 5));
+                    $headers[$headerName] = $value;
+                }
+            }
+            ksort($headers);
+
+            foreach ($headers as $name => $value) {
+                echo '<tr>';
+                echo '<td><code>' . htmlspecialchars($name) . '</code></td>';
+                echo '<td>' . htmlspecialchars($value) . '</td>';
+                echo '</tr>';
+            }
+            ?>
+        </table>
+
+        <h2>✅ 診断結果</h2>
+        <div class="info">
+            <?php
+            $remoteAddr = $_SERVER['REMOTE_ADDR'] ?? '';
+            $xForwardedFor = $_SERVER['HTTP_X_FORWARDED_FOR'] ?? '';
+
+            // プライベートIPかどうかをチェック
+            function isPrivateIP($ip) {
+                $privateRanges = [
+                    '10.0.0.0|10.255.255.255',
+                    '172.16.0.0|172.31.255.255',
+                    '192.168.0.0|192.168.255.255',
+                    '127.0.0.0|127.255.255.255'
+                ];
+
+                $longIP = ip2long($ip);
+                foreach ($privateRanges as $range) {
+                    list($start, $end) = explode('|', $range);
+                    if ($longIP >= ip2long($start) && $longIP <= ip2long($end)) {
+                        return true;
+                    }
+                }
+                return false;
+            }
+
+            if (!empty($remoteAddr) && !isPrivateIP($remoteAddr)) {
+                echo '<p class="success">✅ <strong>正常:</strong> REMOTE_ADDR にパブリックIPアドレスが設定されています。</p>';
+                echo '<p>リアルIP転送設定が正しく動作しています。</p>';
+            } elseif (!empty($remoteAddr) && isPrivateIP($remoteAddr)) {
+                echo '<p class="warning">⚠️ <strong>注意:</strong> REMOTE_ADDR がプライベートIPアドレスです: ' . htmlspecialchars($remoteAddr) . '</p>';
+                echo '<p>これは以下のいずれかが原因です:</p>';
+                echo '<ul>';
+                echo '<li>リアルIP転送設定（nginx.forwardRealIP.enabled）が無効</li>';
+                echo '<li>trustedProxiesの設定が不適切</li>';
+                echo '<li>LoadBalancerがX-Forwarded-Forヘッダーを送信していない</li>';
+                echo '</ul>';
+
+                if (!empty($xForwardedFor)) {
+                    echo '<p><strong>ヒント:</strong> X-Forwarded-For ヘッダーには値があります: ' . htmlspecialchars($xForwardedFor) . '</p>';
+                    echo '<p>values.yaml で <code>nginx.forwardRealIP.enabled: true</code> に設定してください。</p>';
+                }
+            } else {
+                echo '<p class="warning">⚠️ REMOTE_ADDR が設定されていません</p>';
+            }
+            ?>
+        </div>
+
+        <h2>📝 PHPでの使用例</h2>
+        <pre style="background: #f4f4f4; padding: 15px; border-radius: 5px; overflow-x: auto;">
+<code>&lt;?php
+/**
+ * 訪問者のリアルIPアドレスを取得する関数
+ */
+function getRealIP() {
+    // nginx.forwardRealIP.enabled が true の場合、
+    // REMOTE_ADDR に実IPが設定されている
+    return $_SERVER['REMOTE_ADDR'] ?? 'unknown';
+}
+
+// 使用例
+$visitorIP = getRealIP();
+echo "訪問者のIPアドレス: " . $visitorIP;
+
+// データベースに記録する例
+// $stmt = $pdo-&gt;prepare("INSERT INTO access_log (ip_address, visited_at) VALUES (?, NOW())");
+// $stmt-&gt;execute([$visitorIP]);
+?&gt;</code></pre>
+
+        <h2>⚙️ Helm設定例</h2>
+        <pre style="background: #f4f4f4; padding: 15px; border-radius: 5px; overflow-x: auto;">
+<code># values.yaml
+nginx:
+  forwardRealIP:
+    enabled: true
+    header: "X-Forwarded-For"
+    recursive: true
+    trustedProxies:
+      - "10.0.0.0/8"
+      - "172.16.0.0/12"
+      - "192.168.0.0/16"
+    additionalTrustedProxies:
+      - "あなたのLoadBalancerのIPレンジ"</code></pre>
+    </div>
+</body>
+</html>

templates/configmap.yaml

@@ -29,6 +29,25 @@ data:
         sendfile        on;
         keepalive_timeout  65;
 
+        {{- if .Values.nginx.forwardRealIP.enabled }}
+        # ========================================
+        # Real IP forwarding configuration
+        # ========================================
+        # クライアントの実IPアドレスを取得する設定
+        real_ip_header {{ .Values.nginx.forwardRealIP.header }};
+        {{- if .Values.nginx.forwardRealIP.recursive }}
+        real_ip_recursive on;
+        {{- end }}
+
+        # 信頼するプロキシのネットワーク範囲
+        {{- range .Values.nginx.forwardRealIP.trustedProxies }}
+        set_real_ip_from {{ . }};
+        {{- end }}
+        {{- range .Values.nginx.forwardRealIP.additionalTrustedProxies }}
+        set_real_ip_from {{ . }};
+        {{- end }}
+        {{- end }}
+
         server {
             listen       80;
             server_name  localhost;
@@ -45,6 +64,12 @@ data:
                 fastcgi_pass   127.0.0.1:9000;
                 fastcgi_index  index.php;
                 fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
+                {{- if .Values.nginx.forwardRealIP.enabled }}
+                # リアルIP情報をPHP-FPMに渡す
+                fastcgi_param  REMOTE_ADDR        $remote_addr;
+                fastcgi_param  HTTP_X_REAL_IP     $remote_addr;
+                fastcgi_param  HTTP_X_FORWARDED_FOR $proxy_add_x_forwarded_for;
+                {{- end }}
             }
 
             error_page   500 502 503 504  /50x.html;

values.yaml

@@ -55,6 +55,31 @@ nginx:
     enabled: false
     snippet: |-
 
+  # リアルIP転送設定（ベアメタル/LoadBalancer環境向け）
+  forwardRealIP:
+    # リアルIP取得機能を有効化
+    enabled: false
+
+    # リアルIPを取得するヘッダー名
+    # LoadBalancer/Ingressによって異なる
+    # - X-Real-IP: シンプルな1段プロキシ
+    # - X-Forwarded-For: 多段プロキシ対応（推奨）
+    header: "X-Forwarded-For"
+
+    # 再帰的にリアルIPを検索（多段プロキシ環境で推奨）
+    recursive: true
+
+    # 信頼するプロキシのネットワーク範囲
+    # ベアメタルクラスターでは、PodネットワークとServiceネットワークを指定
+    trustedProxies:
+      - "10.0.0.0/8"      # プライベートネットワーク
+      - "172.16.0.0/12"   # プライベートネットワーク
+      - "192.168.0.0/16"  # プライベートネットワーク
+
+    # 追加で信頼するプロキシ（環境に応じてカスタマイズ）
+    additionalTrustedProxies: []
+    #  - "203.0.113.0/24"  # 外部LoadBalancerなど
+
 # Composer設定
 composer:
   # Composerを使用するかどうか