@elf-express/admin-net-mcp 1.0.0 → 1.1.0

package/knowledge/Furion_Teaching_Manual/19-3-HTTP/351/201/240/347/253/257/350/253/213/346/261/202/345/270/270/350/246/213/345/225/217/351/241/214.md

@@ -0,0 +1,362 @@
+# 19.Ⅲ HTTP 遠端請求 — 常見問題
+
+> **版本說明**：僅適用於 Furion 4.9.6+（HttpAgent），不支援 .NET8 以下版本。
+
+---
+
+## 19.28 常見問題
+
+### 19.28.1 忽略 SSL 憑證驗證
+
+```csharp
+// HttpClientHandler
+services.AddHttpClient(string.Empty)
+    .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
+    {
+        ServerCertificateCustomValidationCallback = HttpRemoteUtility.IgnoreSslErrors,
+        SslProtocols = HttpRemoteUtility.AllSslProtocols
+    });
+
+// SocketsHttpHandler
+services.AddHttpClient(string.Empty)
+    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
+    {
+        SslOptions = new SslClientAuthenticationOptions
+        {
+            RemoteCertificateValidationCallback = HttpRemoteUtility.IgnoreSocketSslErrors,
+            EnabledSslProtocols = HttpRemoteUtility.AllSslProtocols
+        }
+    });
+
+// 單次請求
+HttpRequestBuilder.Get("https://furion.net/")
+    .SetHttpClientProvider(() => (new HttpClient(new HttpClientHandler
+    {
+        ServerCertificateCustomValidationCallback = HttpRemoteUtility.IgnoreSslErrors,
+        SslProtocols = HttpRemoteUtility.AllSslProtocols
+    }), client => client.Dispose()));
+```
+
+---
+
+### 19.28.2 強制 IPv4 或 IPv6 請求
+
+```csharp
+// 強制 IPv4
+services.AddHttpClient(string.Empty)
+    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
+    {
+        ConnectCallback = HttpRemoteUtility.IPv4ConnectCallback
+    });
+
+// 強制 IPv6
+services.AddHttpClient(string.Empty)
+    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
+    {
+        ConnectCallback = HttpRemoteUtility.IPv6ConnectCallback
+    });
+
+// 自動選擇
+services.AddHttpClient(string.Empty)
+    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
+    {
+        ConnectCallback = HttpRemoteUtility.UnspecifiedConnectCallback
+    });
+
+// 多網卡：指定本地出口 IPv4
+ConnectCallback = (context, token) =>
+    HttpRemoteUtility.ConnectWithLocalIPv4(IPAddress.Parse("192.168.0.103"), context, token)
+
+// 多網卡：指定本地出口 IPv6
+ConnectCallback = (context, token) =>
+    HttpRemoteUtility.ConnectWithLocalIPv6(IPAddress.Parse("::1"), context, token)
+```
+
+---
+
+### 19.28.3 重新導向回應處理
+
+**全域啟用/停用（HttpRemoteOptions）：**
+
+```csharp
+services.AddHttpRemote(builder => {})
+    .ConfigureOptions(options =>
+    {
+        options.AllowAutoRedirect = false;          // 預設 true
+        options.MaximumAutomaticRedirections = 50;  // 預設 50
+    });
+```
+
+**全域啟用/停用（HttpClient）：**
+
+```csharp
+services.AddHttpClient(string.Empty)
+    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
+    {
+        AllowAutoRedirect = true,
+        MaxAutomaticRedirections = 20
+    });
+```
+
+> ⚠️ 完全停用自動重新導向需**同時**設定 `HttpRemoteOptions` 和 `HttpClient`。
+
+**手動處理重新導向：**
+
+```csharp
+var response = await httpRemoteService.GetAsync("https://furion.net/redirect");
+var statusCode = response.StatusCode;
+
+if (statusCode is HttpStatusCode.Ambiguous or HttpStatusCode.Moved or HttpStatusCode.Redirect
+    or HttpStatusCode.RedirectMethod or HttpStatusCode.RedirectKeepVerb || (int)statusCode == 308)
+{
+    var redirectUrl = response.Headers.Location;
+    if (redirectUrl != null)
+        response = await httpRemoteService.GetAsync(redirectUrl);
+}
+```
+
+---
+
+### 19.28.4 效能最佳化
+
+```csharp
+// 全域
+services.AddHttpClient(string.Empty, client => client.PerformanceOptimization());
+
+// 單次
+HttpRequestBuilder.Get("https://furion.net/").PerformanceOptimization();
+```
+
+啟用後自動添加：`Accept: */*`、`Accept-Encoding: gzip, deflate, br`、`Connection: keep-alive`。
+
+> ⚠️ 需要回傳 `Stream` 或進行 `HttpContext` 網頁轉發時，**請勿啟用**此設定。
+
+---
+
+### 19.28.5 設定預設 User-Agent
+
+框架預設使用 Edge 135 的 User-Agent。自訂方式：
+
+```csharp
+// 全域
+services.AddHttpClient(string.Empty, client =>
+    client.DefaultRequestHeaders.Add("User-Agent", "你的 User-Agent"));
+
+// 單次
+HttpRequestBuilder.Post("https://furion.net/")
+    .WithHeader("User-Agent", "你的 User-Agent", replace: true);
+```
+
+---
+
+### 19.28.6 發送相對位址（內部）請求
+
+**ASP.NET 應用：**
+
+```csharp
+services.AddHttpRemote()
+    .ConfigureOptions((options, sp) =>
+    {
+        var addresses = sp.GetRequiredService<IServer>().Features.Get<IServerAddressesFeature>()!;
+        options.FallbackBaseAddress = new Uri(addresses.Addresses.FirstOrDefault());
+    });
+```
+
+**Blazor WebAssembly：**
+
+```csharp
+services.AddHttpRemote()
+    .ConfigureOptions((options, sp) =>
+    {
+        options.FallbackBaseAddress = new Uri(sp.GetRequiredService<NavigationManager>().BaseUri);
+    });
+```
+
+使用時直接發送相對路徑：
+
+```csharp
+var content = await httpRemoteService.GetAsStringAsync("/user/1");
+```
+
+> 若在 `BackgroundService` 中 `Addresses` 為空，可透過 `IConfiguration` 讀取 `Urls` 節點設定。
+
+---
+
+### 19.28.7 取得回應 Cookie
+
+```csharp
+// 方式一：HttpRemoteResult<T>
+var result = await httpRemoteService.GetAsync<string>("https://furion.net/");
+var setCookies = result.SetCookies;       // IList<SetCookieHeaderValue>
+var rawSetCookies = result.RawSetCookies; // List<string>
+
+// 方式二：HttpResponseMessage 擴充方法
+var response = await httpRemoteService.GetAsync("https://furion.net/");
+response.TryGetSetCookies(out var setCookies, out var rawSetCookies);
+```
+
+---
+
+### 19.28.8 設定 Windows 身分驗證
+
+```csharp
+// 使用目前 Windows 登入使用者（推薦）
+.ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler { UseDefaultCredentials = true });
+
+// 手動輸入帳密
+.ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
+{
+    Credentials = new NetworkCredential("使用者名稱", "密碼"),
+    PreAuthenticate = true
+});
+```
+
+---
+
+### 19.28.9 設定 Kerberos / Active Directory 身分驗證
+
+**同網域：** 同 19.28.8，設定 `UseDefaultCredentials = true`。
+
+**跨網域（使用 `Microsoft.Identity.Client`）：**
+
+```bash
+dotnet add package Microsoft.Identity.Client
+```
+
+```csharp
+var app = PublicClientApplicationBuilder.Create(clientId)
+    .WithAuthority($"https://login.microsoftonline.com/{tenantId}")
+    .Build();
+
+var result = await app.AcquireTokenInteractive(new[] { "api://目標服務的作用域" }).ExecuteAsync();
+
+httpRemoteService.SendAsync(HttpRequestBuilder.Post("https://furion.net/")
+    .AddJwtBearerAuthentication(result.AccessToken));
+```
+
+---
+
+### 19.28.10 回應內容解壓與亂碼處理
+
+框架預設**自動解壓** gzip、deflate、brotli。
+
+**自訂自動解壓：**
+
+```csharp
+services.AddHttpClient(string.Empty)
+    .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
+    {
+        AutomaticDecompression = DecompressionMethods.All
+        // 或 DecompressionMethods.GZip | DecompressionMethods.Deflate
+    });
+```
+
+**手動解壓：**
+
+```csharp
+// 先停用自動解壓
+AutomaticDecompression = DecompressionMethods.None
+
+// 手動處理
+var response = await httpRemoteService.GetAsync("https://furion.com");
+if (response.Content.Headers.ContentEncoding.Contains("gzip"))
+{
+    using var stream = await response.Content.ReadAsStreamAsync();
+    using var gzip = new GZipStream(stream, CompressionMode.Decompress);
+    using var reader = new StreamReader(gzip);
+    var content = await reader.ReadToEndAsync();
+}
+```
+
+---
+
+### 19.28.11 JSON 序列化設定
+
+```csharp
+// 全域預設
+services.AddHttpRemote(builder => {})
+    .ConfigureOptions(options =>
+        options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull);
+
+// 客戶端級（優先級更高）
+services.AddHttpClient("furion")
+    .ConfigureOptions(options =>
+        options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull);
+
+// 使用特定客戶端
+var model = await httpRemoteService.SendAsAsync<YourModel>(
+    HttpRequestBuilder.Get("https://furion.net/test-json").SetHttpClientName("furion"));
+
+// 手動處理
+var json = await httpRemoteService.GetAsStringAsync("https://furion.net/test-json");
+var model = JsonSerializer.Deserialize<YourModel>(json, new JsonSerializerOptions());
+```
+
+> 若需替換為 `Newtonsoft.Json`，請自訂 `IHttpContentProcessor` 實作（參見 19.6.3）。
+
+---
+
+### 19.28.12 停用分散式追蹤上下文（traceparent 標頭）
+
+```csharp
+services.AddHttpClient(string.Empty)
+    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
+    {
+        ActivityHeadersPropagator = null
+    });
+```
+
+---
+
+### 19.28.13 設定 Content-Type（MIME）
+
+推薦使用 `MediaTypeNames` 靜態類避免拼字錯誤：
+
+```csharp
+HttpRequestBuilder.Get("...").SetContentType(MediaTypeNames.Text.Plain);
+HttpRequestBuilder.Post("...").SetContentType(MediaTypeNames.Application.Json);
+HttpRequestBuilder.Post("...").SetContentType(MediaTypeNames.Application.FormUrlEncoded);
+```
+
+---
+
+### 19.28.14 在非相依性注入環境中使用（Console / WinForms / WPF）
+
+```csharp
+// 直接使用
+var result = await HttpRemoteClient.Service.GetAsStringAsync("https://furion.net/");
+
+// 自訂設定
+HttpRemoteClient.Configure(services =>
+{
+    services.AddHttpClient(string.Empty).AddProfilerDelegatingHandler();
+});
+
+// 釋放資源（呼叫後無法再次實例化）
+HttpRemoteClient.Dispose();
+```
+
+或手動建立服務容器：
+
+```csharp
+var services = new ServiceCollection();
+services.AddHttpRemote();
+using var provider = services.BuildServiceProvider();
+var httpRemoteService = provider.GetRequiredService<IHttpRemoteService>();
+```
+
+---
+
+### 19.28.15 與舊版 Java API 對接
+
+```csharp
+HttpRequestBuilder.Get("https://furion.net").AutoSetHostHeader();
+```
+
+---
+
+### 19.28.16 AddHttpRemote 二義性錯誤
+
+```csharp
+services.AddHttpRemote(builder => {});
+```

package/knowledge/Furion_Teaching_Manual/20-/350/263/207/346/226/231/345/212/240/350/247/243/345/257/206.md

@@ -0,0 +1,286 @@
+# 20. 資料加解密
+
+---
+
+## 20.1 概述
+
+資料加解密是系統開發必要的環節，用於保護使用者密碼、Cookie 等敏感資訊。
+
+---
+
+## 20.2 內建加密演算法
+
+| 演算法 | 說明 |
+|--------|------|
+| MD5 | 加密 / 比較 |
+| DES | 加解密 |
+| AES | 加解密（支援 IV 向量、Mode、Padding、檔案加解密） |
+| JWT | 加解密（需安裝 `Furion.Extras.Authentication.JwtBearer`） |
+| PBKDF2 | 加密 / 比較（**推薦用於密碼加密**）（4.9.3.7+） |
+| RSA | 加解密（支援超長字元分段加解密） |
+| SHA1 | 加密 / 比較（4.9.2.41+） |
+| KSort | API 資料簽名（4.9.5.10+） |
+| Gzip | 壓縮 / 解壓（4.9.7.26+） |
+
+---
+
+## 20.3 加解密使用
+
+### 20.3.1 MD5 加密
+
+```csharp
+var md5Hash = MD5Encryption.Encrypt("百小僧");           // 加密
+var isEqual = MD5Encryption.Compare("百小僧", md5Hash);  // 比較
+
+var md5Upper = MD5Encryption.Encrypt("百小僧", true);    // 大寫
+var md5_16 = MD5Encryption.Encrypt("百小僧", is16: true); // 16 位（4.2.6+）
+
+// byte[] 支援（4.8.6.3+）
+var bytes = File.ReadAllBytes("image.png");
+var hash = MD5Encryption.Encrypt(bytes);
+var eq = MD5Encryption.Compare(bytes, hash);
+```
+
+### 20.3.2 DES 加解密
+
+```csharp
+var desHash = DESEncryption.Encrypt("百小僧", "Furion"); // 加密
+var str = DESEncryption.Decrypt(desHash, "Furion");      // 解密
+```
+
+> ⚠️ 4.9.2.41+ 命名調整：`DESCEncryption` → `DESEncryption`，`ToDESCEncrypt` → `ToDESEncrypt`，`ToDESCDecrypt` → `ToDESDecrypt`。
+
+### 20.3.3 AES 加解密
+
+```csharp
+var key = Guid.NewGuid().ToString("N"); // 密鑰，長度必須為 16 / 24 / 32 位
+
+var aesHash = AESEncryption.Encrypt("百小僧", key); // 加密
+var str = AESEncryption.Decrypt(aesHash, key);       // 解密
+```
+
+**自訂 IV 向量、Mode、Padding（4.9.2.18+）：**
+
+```csharp
+var key = "bda66540c463dfdbe70666019f89e554"; // 32 位元密鑰
+byte[] customIV = { 0x1a, 0x2b, 0x3c, 0x4d, 0x5e, 0x6f, 0x70, 0x81,
+                    0x92, 0xa3, 0xb4, 0xc5, 0xd6, 0xe7, 0xf8, 0x09 };
+
+var encrypted = AESEncryption.Encrypt(plainText, key, customIV, CipherMode.CBC, PaddingMode.PKCS7);
+var decrypted = AESEncryption.Decrypt(encrypted, key, customIV, CipherMode.CBC, PaddingMode.PKCS7);
+```
+
+> IV 向量必須為長度 16 的 `byte[]`。Base64 編碼的 IV 請用 `Convert.FromBase64String()` 轉換。  
+> 若密鑰為 Base64 字串，需設定 `isBase64: true`（4.9.7.41+）。
+
+**檔案加解密（4.8.8.11+）：**
+
+```csharp
+// 加密
+var originBytes = File.ReadAllBytes("xxx.rar");
+var encryptBytes = AESEncryption.Encrypt(originBytes, "1234567890abcdef");
+
+// 解密
+var encryptBytes = File.ReadAllBytes("xxx.加密.rar");
+var originBytes = AESEncryption.Decrypt(encryptBytes, "1234567890abcdef");
+```
+
+### 20.3.4 JWT 加解密
+
+> ⚠️ 需安裝 `Furion.Extras.Authentication.JwtBearer` 套件。
+
+```csharp
+var token = JWTEncryption.Encrypt(new Dictionary<string, object>
+{
+    { "UserId", user.Id },
+    { "Account", user.Account }
+});
+
+var tokenData = JWTEncryption.ReadJwtToken("你的 token");
+var (isValid, tokenData, validationResult) = JWTEncryption.Validate("你的 token");
+```
+
+### 20.3.5 PBKDF2 加密（4.9.3.7+）
+
+```csharp
+var hash = PBKDF2Encryption.Encrypt("百小僧");
+var isEqual = PBKDF2Encryption.Compare("百小僧", hash);
+```
+
+### 20.3.6 RSA 加解密
+
+```csharp
+var (publicKey, privateKey) = RSAEncryption.GenerateSecretKey(2048);
+// 密鑰大小：2048 ~ 16384，須為 8 的倍數
+
+var encrypted = RSAEncryption.Encrypt("百小僧", publicKey);
+var decrypted = RSAEncryption.Decrypt(encrypted, privateKey);
+```
+
+> RSA 簽名和校驗功能未內建，可查閱開發者提交的程式碼。4.8.8.2+ 支援超長字元（>245 位）分段加解密。
+
+### 20.3.7 SHA1 加密（4.9.2.41+）
+
+```csharp
+var hash = SHA1Encryption.Encrypt("百小僧");
+var isEqual = SHA1Encryption.Compare("百小僧", hash);
+
+var hashUpper = SHA1Encryption.Encrypt("百小僧", true); // 大寫
+
+// byte[]
+var bytes = File.ReadAllBytes("image.png");
+var hash2 = SHA1Encryption.Encrypt(bytes);
+var eq = SHA1Encryption.Compare(bytes, hash2);
+```
+
+### 20.3.8 KSort 資料簽名（API 簽名）（4.9.5.10+）
+
+**C# 簽名：**
+
+```csharp
+var appId = "ca36cb2858ce3517df772ec34ce92f21";
+var appKey = "95e4a4f651c2d62679c4c150f2e39f4a";
+var command = "add.user";
+var data = JsonSerializer.Serialize(new { id = 1, name = "Furion" });
+
+KSortSignature sData = KSortEncryption.Encrypt(appId, appKey, command, data);
+```
+
+產出格式：
+
+```json
+{
+  "app_id": "ca36cb2858ce3517df772ec34ce92f21",
+  "app_key": "95e4a4f651c2d62679c4c150f2e39f4a",
+  "command": "add.user",
+  "data": "{\"id\":1,\"name\":\"Furion\"}",
+  "timestamp": 1726695114461,
+  "signature": "f6ead3f509c952249f3046ebc4e6e149"
+}
+```
+
+**C# 驗證：**
+
+```csharp
+bool result = KSortEncryption.Compare(dataString); // JSON 字串或 KSortSignature 物件
+```
+
+**TypeScript/JavaScript 簽名：**
+
+```bash
+npm install crypto-js
+```
+
+```typescript
+var sData = signatureByKSort(appId, appKey, "add.user", { id: 1, name: "furion" });
+fetch("http://furion.net", sData).then(res => res.json()).then(data => {});
+```
+
+> 客戶端的 `data-signature.ts` 可從 Furion 官方 Gitee 倉庫取得。
+
+**最佳實踐：**
+
+```csharp
+[HttpPost]
+public async Task AddUser([Required] KSortSignature sData)
+{
+    if (!KSortEncryption.Compare(sData))
+        throw new Exception("非法資料");
+
+    var data = JsonSerializer.Deserialize<原始資料型別>(sData.data);
+}
+```
+
+> `appId` 和 `appKey` 應從伺服器取得，切勿明文寫在客戶端程式碼中。可實作中介軟體統一驗證。
+
+### 20.3.9 Gzip 壓縮解壓（4.9.7.26+）
+
+```csharp
+var bytes = GzipEncryption.Compress("Furion");
+var text = GzipEncryption.Decompress(bytes);
+
+// Base64
+var base64 = GzipEncryption.CompressToBase64("Furion");
+var text2 = GzipEncryption.DecompressFromBase64(base64);
+```
+
+---
+
+## 20.4 字串擴充方式
+
+```csharp
+using Furion.DataEncryption.Extensions;
+
+// MD5
+var s = "Furion".ToMD5Encrypt();
+var b = "Furion".ToMD5Compare(s);
+
+// AES
+var s = "Furion".ToAESEncrypt(key);
+var str = s.ToAESDecrypt(key);
+
+// DES
+var s = "Furion".ToDESEncrypt(key);
+var str = s.ToDESDecrypt(key);
+
+// PBKDF2
+var s = "Furion".ToPBKDF2Encrypt();
+var b = "Furion".ToPBKDF2Compare(s);
+
+// RSA
+var (pub, pri) = RSAEncryption.GenerateSecretKey(2048);
+var s = "Furion".ToRSAEncrpyt(pub);
+var str = s.ToRSADecrypt(pri);
+
+// SHA1
+var s = "Furion".ToSHA1Encrypt();
+var b = "Furion".ToSHA1Compare(s);
+
+// Gzip
+var s = "Furion".ToGzipCompress();
+var b = s.ToGzipDecompress();
+var s1 = "Furion".ToGzipCompressToBase64();
+var b1 = s1.ToGzipDecompressFromBase64();
+```
+
+---
+
+## 20.5 SM2、SM3、SM4 國密
+
+框架未內建國密演算法，可使用開源社群貢獻的實作：
+
+```csharp
+// SM2
+var b = SM2Utils.加密("123");
+var b1 = SM2Utils.解密(b);
+
+// SM3（常用於數位簽名）
+var sm3 = new SM3Utils();
+sm3.secretKey = "ASAFSDFDSGSDFSDFSDFSFSF";
+var token = sm3.加密("123");
+
+// SM4
+var sm4 = new SM4Utils();
+sm4.secretKey = "BDBDBDBDBDBDBDBDBDBDBDBDBDBDBD";
+var a = sm4.加密(data);
+var a1 = sm4.解密(a);
+```
+
+---
+
+## 更新日誌摘要
+
+| 版本 | 日期 | 內容 |
+|------|------|------|
+| 4.9.7.71 | 2025.05.23 | 修復 AES ECB + PKCS7 加密結果不一致 |
+| 4.9.7.42 | 2025.04.15 | 修復 AES 密鑰安全漏洞（強制 AES 規範長度） |
+| 4.9.7.41 | 2025.04.14 | AES 解密支援 Base64 字串密鑰 |
+| 4.9.7.27 | 2025.03.21 | 修復 AES iv 位元組不足 16 位問題 |
+| 4.9.7.26 | 2025.03.20 | 新增 Gzip 壓縮解壓 |
+| 4.9.7.7 | 2025.02.14 | 修復 ECB 模式下 AES IV 被截斷問題 |
+| 4.9.5.10 | 2024.09.19 | 新增 KSort API 資料簽名 |
+| 4.9.3.7 | 2024.05.21 | 新增 PBKDF2 加密 |
+| 4.9.2.41 | 2024.05.08 | 新增 SHA1、DES 命名調整 |
+| 4.9.2.18 | 2024.04.15 | AES 支援 IV / Mode / Padding |
+| 4.8.8.11 | 2023.05.05 | AES 檔案加解密 |
+| 4.8.8.2 | 2023.04.19 | RSA 超長字元分段加解密 |