From 70ad99161bc58f1025ebf607293d5b07205d2ac3 Mon Sep 17 00:00:00 2001
From: Timmy <loyangchun@gmail.com>
Date: Wed, 8 Apr 2026 18:23:49 +0800
Subject: [PATCH] docs: add WireGuard VPN section to README

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)

diff --git a/README.md b/README.md
index ca92350..5b5cd7b 100644
--- a/README.md
+++ b/README.md
@@ -212,3 +212,109 @@ ssh root@192.168.42.10 "fw4 restart"
 # 確認規則已移除
 ssh root@192.168.42.10 "nft list chain inet fw4 dstnat_wan | grep <port>"
 ```
+
+---
+
+## WireGuard VPN
+
+**架構**：路由器作為 server，外部裝置以 client 身份連入，取得對 LAN（`192.168.42.0/24`）的存取權。
+
+```
+外部裝置
+   │  UDP 51820
+   ▼
+192.168.42.10  wg0: 10.0.0.1/24   ← server
+   ├── 10.0.0.2  Workstation
+   └── 10.0.0.3  iPhone 15 Pro Max
+```
+
+### 狀態查看
+
+```sh
+# 查看所有 peer 連線狀況（last handshake、傳輸量）
+wg show
+
+# 只看介面摘要
+wg show wg0
+```
+
+### 新增 Peer
+
+```sh
+# 1. 在路由器上產生新的 keypair
+wg genkey | tee /tmp/peer_private.key | wg pubkey > /tmp/peer_public.key
+cat /tmp/peer_private.key
+cat /tmp/peer_public.key
+
+# 2. 加入 peer 設定（以 10.0.0.4 為例）
+uci add network wireguard_wg0
+uci set network.@wireguard_wg0[-1].public_key='<peer_public_key>'
+uci set network.@wireguard_wg0[-1].private_key='<peer_private_key>'
+uci set network.@wireguard_wg0[-1].persistent_keepalive='25'
+uci add_list network.@wireguard_wg0[-1].allowed_ips='10.0.0.4/32'
+uci add_list network.@wireguard_wg0[-1].allowed_ips='192.168.42.0/24'
+uci set network.@wireguard_wg0[-1].dns='1.1.1.1'
+uci set network.@wireguard_wg0[-1].description='<裝置名稱>'
+uci commit network
+service network restart
+```
+
+### 移除 Peer
+
+```sh
+# 找出目標 peer 的索引
+uci show network | grep -n '<peer_public_key>'
+
+# 刪除（假設是 @wireguard_wg0[2]）
+uci delete network.@wireguard_wg0[2]
+uci commit network
+service network restart
+```
+
+### Client 設定檔範本
+
+將以下內容存為 `.conf` 檔匯入裝置（WireGuard app 或 `wg-quick`）：
+
+```ini
+[Interface]
+PrivateKey = <peer_private_key>
+Address = 10.0.0.x/24
+DNS = 1.1.1.1
+
+[Peer]
+PublicKey = s7fZj/dlgcjc1q4Pd1EaeoCOgq8EStyS30h30hOL1RI=
+Endpoint = 125.229.110.50:51820
+AllowedIPs = 192.168.42.0/24, 10.0.0.0/24
+PersistentKeepalive = 25
+```
+
+> `AllowedIPs` 只填 `192.168.42.0/24, 10.0.0.0/24` 表示 split tunnel（只有內網流量走 VPN）。  
+> 若要讓所有流量都走 VPN，改為 `0.0.0.0/0, ::/0`。
+
+### 現有 Peer 一覽
+
+| 描述 | VPN IP | Public Key（前 8 碼） |
+|---|---|---|
+| Workstation | `10.0.0.2` | `daM1BFUS` |
+| iPhone 15 Pro Max | `10.0.0.3` | `PZVrUwd1` |
+
+### 防火牆規則說明
+
+| 規則 | 說明 |
+|---|---|
+| WAN UDP 51820 → ACCEPT | 允許外部 client 建立 VPN tunnel |
+| vpn → lan ACCEPT + masq | VPN client 可存取內網，並做 NAT |
+
+若防火牆規則遺失，手動補回：
+
+```sh
+# 允許 WireGuard 進入
+uci add firewall rule
+uci set firewall.@rule[-1].name='Allow-WireGuard'
+uci set firewall.@rule[-1].src='wan'
+uci set firewall.@rule[-1].dest_port='51820'
+uci set firewall.@rule[-1].proto='udp'
+uci set firewall.@rule[-1].target='ACCEPT'
+uci commit firewall
+fw4 restart
+```