Csharp on Wayne's blog | 偉恩的部落格 | 技術博客

關於 ASP.NET Core 7.0 的啟動設定檔 (Launch Settings)

Fri, 24 Mar 2023 00:00:00 +0000

由於 ASP.NET Core 7.0 與 ASP.NET Core 6.0 的專案範本中的啟動設定檔(Launch Settings)有些許不同，所以來整理一下相關知識，更好的認識這個 Properties\launchSettings.json 檔案。

先看看 Properties\launchSettings.json 的差異

先用 dotnet new mvc 在 ASP.NET Core 6.0 與 ASP.NET Core 7.0 產生一樣的專案：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# 6.0
mkdir projectV6
cd projectV6

dotnet new globaljson --sdk-version 6.0.100 --roll-forward latestFeature
dotnet --version
dotnet new mvc

# 7.0
mkdir projectV7
cd projectV7

dotnet new globaljson --sdk-version 7.0.100 --roll-forward latestFeature
dotnet --version
dotnet new mvc

由於專案範本不同，專案內的 Properties\launchSettings.json 檔案內容其實不太一樣：

ASP.NET Core 6.0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


{
 "iisSettings": {
 "windowsAuthentication": false,
 "anonymousAuthentication": true,
 "iisExpress": {
 "applicationUrl": "http://localhost:22303",
 "sslPort": 44378
 }
 },
 "profiles": {
 "m1": {
 "commandName": "Project",
 "dotnetRunMessages": true,
 "launchBrowser": true,
 "applicationUrl": "https://localhost:7007;http://localhost:5183",
 "environmentVariables": {
 "ASPNETCORE_ENVIRONMENT": "Development"
 }
 },
 "IIS Express": {
 "commandName": "IISExpress",
 "launchBrowser": true,
 "environmentVariables": {
 "ASPNETCORE_ENVIRONMENT": "Development"
 }
 }
 }
}

ASP.NET Core 7.0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


{
 "iisSettings": {
 "windowsAuthentication": false,
 "anonymousAuthentication": true,
 "iisExpress": {
 "applicationUrl": "http://localhost:9601",
 "sslPort": 44330
 }
 },
 "profiles": {
 "http": {
 "commandName": "Project",
 "dotnetRunMessages": true,
 "launchBrowser": true,
 "applicationUrl": "http://localhost:5041",
 "environmentVariables": {
 "ASPNETCORE_ENVIRONMENT": "Development"
 }
 },
 "https": {
 "commandName": "Project",
 "dotnetRunMessages": true,
 "launchBrowser": true,
 "applicationUrl": "https://localhost:7068;http://localhost:5041",
 "environmentVariables": {
 "ASPNETCORE_ENVIRONMENT": "Development"
 }
 },
 "IIS Express": {
 "commandName": "IISExpress",
 "launchBrowser": true,
 "environmentVariables": {
 "ASPNETCORE_ENVIRONMENT": "Development"
 }
 }
 }
}

從上述內容你可以很清楚的發現 ASP.NET Core 6.0 與 ASP.NET Core 7.0 有以下 2 點差異：

ASP.NET Core 6.0 的 profiles 只有兩個，但是 ASP.NET Core 7.0 的 profiles 卻有三個！
ASP.NET Core 6.0 的第一個 Profile 預設名稱為「專案名稱」(projectV6)，而 ASP.NET Core 7.0 的第一個 Profile 名稱卻是 http，而且還多出一個 https 設定檔。

其實在 ASP.NET Core 6.0 以前，所有的專案範本中第一個 Profile 預設名稱都為「專案名稱」，所以其實大家對這個名字沒有什麼感覺，直到 ASP.NET Core 7.0 做出了改變，這才有人發現原來這東西的用途。

不載入啟動設定檔

從 ASP.NET Core 6.0 開始，透過 dotnet new 專案範本所建立的 ASP.NET Core 專案，預設都不會繼續使用早期的 Port 5000 (http) 與 Port 5001 (https)，可能是因為多專案的架構下太容易衝突，而且太多人不清楚啟動設定檔的存在，所以就改成用亂數的 Port 埠號。

但是亂數的 Port 埠號其實很難寫文件，所以我為了讓學員檢測自己是否有成功裝好 .NET SDK 工具，我會這樣寫：

1
2
3
4
5
6
7
8


# 建立並進入資料夾
mkdir projectV7 && cd projectV7

# 建立 ASP.NET Core MVC 專案範本
dotnet new mvc

# 啟動網站並忽略啟動設定檔
dotnet run --no-launch-profile

這裡的 --no-launch-profile 就是避免 dotnet new 去讀取專案中的 Properties\launchSettings.json 啟動設定檔，而 .NET Runtime 的 dotnet run 命令，在沒有載入啟動設定檔的情況下，在 ASP.NET Core 6.0 與 ASP.NET Core 7.0 有細微的差異：

預設 ASP.NET Core 6.0 網站會監聽 Port 5000 (http) 與 Port 5001 (https)。
預設 ASP.NET Core 7.0 網站會監聽 Port 5000 (http)。

由於 ASP.NET Core 的 TLS 自簽憑證預設只有一年效期，每年都要更新，雖然更新很簡單，命令如下：

1
2


dotnet dev-certs https --clean
dotnet dev-certs https --trust

應該是有很多人搞不定 https 問題，才讓微軟決定降低開發門檻，直接把預設 https 的 binding 移除！

啟動設定檔的用法

我們在執行 dotnet run 的時候，只要沒特別指定啟動設定檔，預設就會自動載入 Properties\launchSettings.json 設定檔中的第一個 profiles 中的設定，由於 ASP.NET Core 7.0 的「第一個」是 http 這個名字：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
 // ...
 "profiles": {
 "http": {
 "commandName": "Project",
 "dotnetRunMessages": true,
 "launchBrowser": true,
 "applicationUrl": "http://localhost:5041",
 "environmentVariables": {
 "ASPNETCORE_ENVIRONMENT": "Development"
 }
 },
 // ...
 }
 // ...
}

所以當網站啟動時，我們的 applicationUrl 預設就只有 http 的網址而已，因此網站啟動時並不會有 https 可以測試！

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


dotnet run

> Building...
> info: Microsoft.Hosting.Lifetime[14]
> Now listening on: http://localhost:5041
> info: Microsoft.Hosting.Lifetime[0]
> Application started. Press Ctrl+C to shut down.
> info: Microsoft.Hosting.Lifetime[0]
> Hosting environment: Development
> info: Microsoft.Hosting.Lifetime[0]
> Content root path: G:\Projects\projectV7

那如果我們也想測試 https 網址怎麼辦，這時你就可以選擇 Properties\launchSettings.json 設定檔中的第二個 profiles 中的設定：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
 // ...
 "profiles": {
 // ...
 "https": {
 "commandName": "Project",
 "dotnetRunMessages": true,
 "launchBrowser": true,
 "applicationUrl": "https://localhost:7068;http://localhost:5041",
 "environmentVariables": {
 "ASPNETCORE_ENVIRONMENT": "Development"
 }
 }
 }
 // ...
}

其啟動的方式如下：

1
2
3
4


dotnet run --launch-profile "https"

# 或者可以簡寫成這樣:
# dotnet run -lp "https"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


dotnet run --launch-profile "https"

> Building...
> info: Microsoft.Hosting.Lifetime[14]
> Now listening on: https://localhost:7068
> info: Microsoft.Hosting.Lifetime[14]
> Now listening on: http://localhost:5041
> info: Microsoft.Hosting.Lifetime[0]
> Application started. Press Ctrl+C to shut down.
> info: Microsoft.Hosting.Lifetime[0]
> Hosting environment: Development
> info: Microsoft.Hosting.Lifetime[0]
> Content root path: G:\Projects\projectV7

深入瞭解啟動設定檔

在啟動設定檔中有個 launchBrowser 屬性，預設為 true，從字面上來看，就是「啟動瀏覽器」的意思。但其實我們用 dotnet run 並不會因為 launchBrowser 為 true 就開啟網頁，而是要透過 dotnet watch 命令啟動網站才會真的啟動瀏覽器並開啟網頁！

另一方面，你可能會發現我們在 Visual Studio 2022 裡面每次啟動網站都會開啟網頁，這時我其實也會覺得這個設計很煩，每次都一直不斷的開啟新頁籤，其實蠻惱人的。而關掉的方法，就是調整啟動設定檔中的 launchBrowser 屬性，調整為 false 即可！

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
 // ...
 "profiles": {
 // ...
 "https": {
 "commandName": "Project",
 "dotnetRunMessages": true,
 "launchBrowser": false,
 "applicationUrl": "https://localhost:7068;http://localhost:5041",
 "environmentVariables": {
 "ASPNETCORE_ENVIRONMENT": "Development"
 }
 }
 }
 // ...
}

另外還有一個 dotnetRunMessages 也是個謎一般的存在，完全沒有文件說明，而這個設定也確實沒太多存在感！各位可以看下圖差異之處，只有在 dotnet run 啟動的時候有非常細微的差異而已。我們在透過 dotnet run 啟動網站時，由於要先 dotnet build 過才能真正 Run 起來，而這段時間大概會跑個 2 ~ 3 秒左右，如果在 dotnetRunMessages 為 true 時，在 Console 會優先出現一個 Building… 字樣，讓你知道 dotnet run 沒掛掉，他只是還在跑而已，否則你會有 2 ~ 3 秒的空白，有人會覺得好像程式沒啟動，感覺怪怪的！😅

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# dotnetRunMessage = true 時
dotnet run

> Building...
> info: Microsoft.Hosting.Lifetime[14]
> Now listening on: http://localhost:5041
> info: Microsoft.Hosting.Lifetime[0]
> Application started. Press Ctrl+C to shut down.
> info: Microsoft.Hosting.Lifetime[0]
> Hosting environment: Development
> info: Microsoft.Hosting.Lifetime[0]
> Content root path: G:\Projects\projectV7

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# dotnetRunMessage = false 時
dotnet run

> info: Microsoft.Hosting.Lifetime[14]
> Now listening on: http://localhost:5041
> info: Microsoft.Hosting.Lifetime[0]
> Application started. Press Ctrl+C to shut down.
> info: Microsoft.Hosting.Lifetime[0]
> Hosting environment: Development
> info: Microsoft.Hosting.Lifetime[0]
> Content root path: G:\Projects\projectV7

詳見 Purpose of dotnetRunMessages in launchSettings.json - Stack Overflow 說明。

最後，還有個 commandName 也是謎一般的存在，依然完全沒有文件說明，但在 Stack Overflow 有篇文章有做詳細說明，其設定值有可能是以下四種：

Project

將當前的這個應用程式作為控制台應用程式運行，這裡的設定跟你用 dotnet run 執行是相同的。

IIS Express

預設使用 IIS Express 開發伺服器來執行 ASP.NET Core 應用程式。

這個選項只能用在 Visual Studio 而已，.NET CLI 是不支援的！

IIS

當你在本機安裝 IIS 後，您可以讓您的應用程式直接在 IIS 執行。

這個選項只能用在 Visual Studio 而已，.NET CLI 是不支援的！

Executable

這讓你可以執行任意執行檔、傳入任意參數，非常靈活的設定！

這個選項只能用在 Visual Studio 而已，.NET CLI 是不支援的！

例如你不想用 Visual Studio 2022 內建難用的 Hot Reload 的話，可以這樣設定：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
 // ...
 "Watch": {
 "commandName": "Executable",
 "dotnetRunMessages": true,
 "executablePath": "dotnet",
 "commandLineArgs": "watch run",
 "workingDirectory": "$(ProjectDir)",
 "launchBrowser": true,
 "applicationUrl": "https://localhost:5001;http://localhost:5000",
 "environmentVariables": {
 "ASPNETCORE_ENVIRONMENT": "Development"
 }
 }
 // ...
}

【WebAPI】分層設計模式 - 三層式架構

Fri, 24 Feb 2023 00:00:00 +0000

參考網站
 參考網站
 參考網站
 參考網站
 參考網站

軟體分層設計模式是我這幾年專案必會使用的架構，它的效益在多人團隊分工上有極大的效益，且能有效專注修改區域，提高共用性。

三層式架構 (Three-Tier) 是很常見的架構，可以應用在實體機器架構上，也可以應用在邏輯架構上，可以按照實體與邏輯上去進行區分。

為甚麼要分層？

如果程式全部一條龍寫到底，後續會產生很多問題，難以維護、難以閱讀、更甚至是萬一人家要接手你的程式碼，這時候改Ａ壞Ｂ，耦合度過高的情況下，你只能祈禱接手的人不知道你住哪…

這種情況下只有自己寫可能還好，那如果需要跟人合作呢？

大家可能容易出現重複的 Code，也難以說明誰該負責寫哪部分。

這時候有一個好的架構，就很重要了，分層設計時，遵循了面向介面設計的思想，那麼這種向下的依賴也應該是一種弱依賴關係。因而在不改變介面定義的前提下，理想的分層式架構，應該是一個支持可抽取、可替換的「抽屜」式架構。

WebAPI 的三層式架構

WebAPI 的三層式架構顧名思義，主要分為了三層：

Controller：控制層，作為接口。
Service：商業邏輯層，只要有關商業邏輯部分的處理全部放在這一層。
Repository：倉儲層，作為資料存儲的一層。
Common：共用層，作為存放各層會用到的相同東西。

他們之間的關係如下圖：

優缺點

優點
1、較好形成一個規範，可做為標準化流程。
2、提高重用性，透過分層將相同類型的程式碼放在一塊。
3、團體合作的時候，能夠分層進行；開發人員只需專注於自己開發的那一層即可。
4、具有好的開放性、可擴充性優點。
5、降低程式碼之間的依賴，每層溝通是透過介面。
6、提高系統安全性，因為使用者需要透過 Service 層才有機會與下一層 Repository 撈取資料。

缺點
1、增加了開發成本，傳統一個人負責寫到底；分層下需要多人進行合作。
2、調整程式可能會出現連動性；有的時候修改一個地方，會導致其他層也需要跟著調整。
3、相較於一條龍開發系統性能下降，原本程式可以直接透過 DB 撈取資料，現在需要透過中間層的轉介才能夠拿到。

Controller

在我們 WebAPI 中，Controller 就屬於『接口』，負責處理 Router，如常見的：Get、Post、Patch…等，都會是在這層負責接應相對應的路由。

Controller 接收的是 Parameter，輸出的是 ViewModel。

Service

在我們程式中最重要的就屬於『商業邏輯』了，這一層是會特別關注的一層；這邊大家可能會問，那商業邏輯是指哪些呢？

我自己認為最簡單分辨的方式，舉凡任何需要對資料特別處理的地方都會是放在這一層，如常見的：登入驗證、加減法運算、確認是否驗證成功…等。

Service 接收的是 InfoModel，輸出的是 Dto。

Repository

資料倉儲層，這層主要處理『有關資料串接』的部分，如：資料庫連接、下 SQL 取 Table 資料…等，都會是在 Repository 處理。

這邊有個特別的地方，如果我們程式需要透過別人的 API 取的資料回來做處理呢？

那與對方 API 串接的地方就會是 Repository，所以 Repository 是處理『有關資料串接』的地方，而這資料當然並不只限於從 DB 撈取的資料。

Repository 接收的是 Condition，輸出的是 DataModel。

Common

共用層相對單純，存放各層間會用到的『共同』東西，最常見的例如：Enum…等，就會放在這一層。

常見問題

三層式架構與傳統 MVC 有甚麼不同呢？

傳統 MVC 分成，View(展示層)、Model(資料層)、Controller(控制層)，這邊與三層式架構最大的區別在於傳統 MVC 並沒有特別把『商業邏輯』抽出來；常會看到傳統 MVC 可能會把商業邏輯附加在 Controller，所以 MVC 與三層式架構是不同的。

各層間溝通一定要透過 Model 嗎？

這個答案就我個人使用的理解是，『不一定要透過 Model』，如果只是要回傳簡單的 bool 、或是一兩個參數，直接傳就可以了；那做成 Model 的用意呢？當然也是為了提高重用性，例如 ResultModel。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public class ResultModel
{
 /// <summary>
 /// 結果
 /// </summary>
 public bool Result { get; set; }

 /// <summary>
 /// 提示訊息
 /// </summary>
 public string Message { get; set; }
}

雖然只有兩個變數，但還是把它包成了 Model ，因為有很多個地方會需要用到，當然就可以包起來給大家共同使用。

Service 層可以呼叫其他 Service 層的程式嗎？

可以，三層式架構的優點就是要提供重用性，當然如果相同的事情在其他地方已經有做過了，直接拿來使用，就不用做重複的事情。

Model 的名稱分了這麼多？不能直接一個通到底嗎？

這問題也是我一開始不太能夠理解的部分，如果是一個人寫程式的時候都會為了方便，就一個 Model 通到底吧；這時候肯定會有人問就算多人合作也可以啊？

真的可以嗎？

各層間的職責都不同，從 Reoisitory 取出來的資料丟給 Service 做處理，有可能不需要全部完整的資料回傳給 Controller，為了避免這種情況當然是分開會比較妥當，自己使用自己的 Model；多人合作的時候只需要定義說好相互要傳遞的參數就可以分層開發了，也不會因為一個 Model 而影響對方。

小結

當我是一個人開發的時候，分層設計真的感受不深，更多的是為何要弄得這麼複雜，但隨著工作團隊的擴展，多人合作開發的時候，分層設計就發揮出了它的價值，各個成員專注各自的層發開，不會被其他成員影響，當需要修改或擴充時，若是要改 UI，只需要異動展示層，若是新增商業邏輯則只需專注業務層，而是為要換第三方配合廠商或者更換資料庫，則只需專注在資料層去修改，而各層的物件又可以依不同情境做重用，不需重複開發，可謂好處多多。

效益：

適合多人團隊分工時不互相影響 (一條龍開發時感受不深)
分層專注，可以專注修改，不會牽一髮動全身

但真的能達到這樣的效益，其實還有一些必要前提：

物件設計須符合 SOLID 原則
各層依賴介面 (Interface)，不依賴實作
專案需導入 DI Framework，做到依賴注入，達成控制反轉 (IoC)
撰寫單元測試 (Unit Test) 保護每次修改
合理的設計各層職責物件，業務層更為重要

【C#】實作 Debounced Job

Mon, 13 Feb 2023 00:00:00 +0000

參考網站
 參考網站
 參考網站

前言

Debounce (去抖動)是前端開發時很常用的技巧，經典應用是整合 AJAX 的欄位輸入自動完成。原始設計是每敲一個字元查一次，當使用者連續輸入 w a y n e b 便會發出 “w”、“wa”、“way”、“wayn”、“wayne”、“wayne-b” 等六次 AJAX 查詢，而使用者期望的是用 wayne-b 帶出 wayne-blog 提示，因此前面五次純屬無效查詢，平白浪費頻寬跟主機資源。有效的改善方法是改成每次敲完一個字元先稍待 0.5 秒或 1 秒，確認沒有要輸入其他字元，最後一次送出 “wayneb”。這在網頁上用 JavaScript setTimeout/clearTimeout 即可輕易實現，這個做法有個術語叫 - Debounce。

伺服器端有類似的應用情境嗎？有。

提到系統自動通知，經常是一筆記錄發一次通知(運作最簡單，系統內建提供不需客製)，而某些事件一旦發生會噴出數十上百筆通知，短短幾秒收件匣或 LINE/Slack 就被暴力洗版。更理想的做法是把短時間內的連續訊息彙整成一封，而這類似前面說的「彙整多個輸入字元再一次發出 AJAX 請求」，可以靠 Debounce 機制改善。而我們要做的就是用 C# 實現類似邏輯，收到第一則通知時先不要馬上轉發，若一段時間內接連還有其他訊息進來都先存起來，等到 30 秒內沒有新訊息，再將累積的訊息彙整成一筆送出。

實作

寫個 ASP.NET Core Minimal API 做概念性驗證(Proof of Concept；POC)：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68


using System.Collections.Concurrent;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// 用途：訊息存於記憶體，不考慮程序異常資料遺失問題
var msgQueue = new ConcurrentQueue<string>();

// 延遲 5 秒執行，期間累積的訊息一次處理
var debouncePrint = new DebouncedJob(TimeSpan.FromSeconds(5));

app.MapPost("/alert", (HttpRequest request) =>
{
 string msg = request.Form["msg"].ToString();
 if (!string.IsNullOrEmpty(msg))
 {
 msgQueue.Enqueue(msg);

 // 若怕新訊息源源不絕一直 Delay 下去，可加入訊息數上限
 // 當 msgQueue 累積數量達上限時，不透過 DebouncedJob 直接執行

 debouncePrint.Run(() =>
 {
 Console.ForegroundColor = ConsoleColor.Yellow;
 Console.WriteLine($"Debounce Print: {DateTime.Now:mm:ss}");
 Console.ResetColor();
 while (msgQueue.TryDequeue(out string m))
 {
 Console.WriteLine(" " + m);
 }
 });
 }
 return Results.Content("OK");
});

app.MapGet("/", () => Results.Content(@"<!DOCTYPE html>
<html>
 <head>
 <meta charset=""utf-8"">
 <title>DebouncedJob</title>
 </head>
 <body>
 <form action=https://blog.wayne-project.com/alert method=post target=result id=frm >
 <input type=hidden name=msg id=msg />
 </form>
 <iframe name=result style=display:none></iframe>
 <button onclick='test()' >Run Test</button>
 <ul id=log></ul>

 <script>
 let delays = [1, 1, 2, 3, 1, 4, 6, 1, 1, 7, 1];
 function test() {
 send();
 }
 function send() {
 let m = `Sent on ${new Date().toISOString().split('T')[1].substr(3, 5)}`;
 document.getElementById('log').innerHTML += `<li>${m}</li>`;
 document.getElementById('msg').value = m;
 document.getElementById('frm').submit();
 if (delays.length) {
 setTimeout(send, delays.shift() * 1000);
 }
 }
 </script>
 </body>
</html>", "text/html"));

app.Run();

目的是由 /alert 收訊息用 Console.WriteLine 顯示出來，但中間加上 5 秒的 Debounce 機制。做法是收到 /alert 時先將 msg 存進 ConcurrentQueue (不考慮程序異常資料遺失)，並排定一個將 ConcurrentQueue 內容全部印出來的動作，若 5 秒內沒有其他 /alert 被呼叫，排定的 Console.Print 才會真的執行。首頁的部分我寫了簡單的 JavaScript，模擬間隔 1、1、2、3、1、4、6、1、1、7、1 秒各呼叫一次 /alert。由於超過 5 秒才會 Print，預期會在等 6 秒、等 7 秒及最後分三次印出。

測試成功，結果符合預期。

運作的關鍵在 Debounced Job，那 Debounced Job 要怎麼寫？

其實還蠻簡單的，.NET 沒有 setTimeout、clearTimeout，但我們可以用 Task.Delay().ContinueWith() 配上 CancellationToken 實現取消要延遲執行作業的相似邏輯，Task.Delay() 像 Thread.Sleep() 可以不佔用 CPU 等待指定時間，但多了接收 CancellationToken 隨時中斷等待的功能，配合 ContinueWith() 時檢查 CancellationToken.IsCancellationRequested 偵測被中斷的話放棄執行，便能實現 clearTimeout 放棄執行的效果。(延伸閱讀：NET 非同步工作的延續 by Huanlin 學習筆記)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


public class DebouncedJob
{
 private CancellationTokenSource _cts = new CancellationTokenSource();
 private readonly object _lock = new object();
 private readonly TimeSpan _delay;

 public DebouncedJob(TimeSpan delay)
 {
 _delay = delay;
 }

 public void Run(Action action)
 {
 lock (_lock)
 {
 // 取消上一次的執行
 // 概念上類似 JavaScript debounce 的 clearTimeout() 技巧
 _cts.Cancel();
 _cts.Dispose();
 }

 _cts = new CancellationTokenSource();
 var token = _cts.Token;

 Task.Delay(_delay, token).ContinueWith(task =>
 {
 // 執行到這裡有兩種情況：
 // 1. 延遲時間到
 // 2. 延遲時間未到，CancellationToken 被取消
 // 後者不執行 action
 if (!token.IsCancellationRequested)
 {
 action();
 }
 });
 }
}

學會這個技巧，未來遇到需要將動作化零為整，提高處理效率及資訊可讀性的場合，我們就可以靠它寫出更貼心有效率的程式囉。

你可能會想，在極端狀態下若訊息源源不絕進來，發送動作將被無限延遲影響通知時效。

這還可透過設定等待上限解決，試寫一個可指定等待上限的版本(預設上限時為等待時間的兩倍)：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


public class DebouncedJob
{
 private CancellationTokenSource _cts = new CancellationTokenSource();
 private readonly object _lock = new object();
 private readonly TimeSpan _delay;
 private readonly TimeSpan? _maxDelay;

 public DebouncedJob(TimeSpan delay, TimeSpan? maxDelay = null)
 {
 _delay = delay;
 // 未指定 maxDelay 時，預設為兩倍 delay 長度
 _maxDelay = maxDelay ?? delay * 2;
 }

 private DateTime? firstRunTime = null;

 public void Run(Action action)
 {
 lock (_lock)
 {
 // 取消上一次的執行
 // 概念上類似 JavaScript debounce 的 clearTimeout() 技巧
 _cts.Cancel();
 _cts.Dispose();
 }

 _cts = new CancellationTokenSource();
 var token = _cts.Token;

 if (firstRunTime == null)
 {
 firstRunTime = DateTime.Now;
 }
 // 超過 maxDelay 直接執行 action
 else if (DateTime.Now - firstRunTime > _maxDelay)
 {
 firstRunTime = null;
 action();
 return;
 }

 Task.Delay(_delay, token).ContinueWith(task =>
 {
 // 執行到這裡有兩種情況：
 // 1. 延遲時間到
 // 2. 延遲時間未到，CancellationToken 被取消
 // 後者不執行 action
 if (!token.IsCancellationRequested)
 {
 firstRunTime =null;
 action();
 }
 });
 }
}

修改 Program.cs，var debouncePrint = new DebouncedJob(TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(8)); 設定八秒上限，可觀察到第一波拆成兩批顯示，最久只會延遲到 8 秒：

ASP.NET Core 網站如何整合 Google 的 reCAPTCHA Enterprise 功能

Tue, 07 Feb 2023 00:00:00 +0000

參考網站
 參考網站
 參考網站
 參考網站
 參考網站
 參考網站
 參考網站

網站上幾乎每頁都有聯絡表單，並透過 AJAX 傳送到後端 API 負責記錄並送出郵件到公司的服務信箱，但網站上線後，垃圾訊息太常收到。因此，我打算將表單加入 Google Cloud Platform (GCP) 的 reCAPTCHA Enterprise 服務，減少收到垃圾訊息的機會，這篇文章我來分享一下完整的開發流程！

先整理幾個重要概念

reCAPTCHA 原本是由卡內基梅隆大學所發展的系統，主要目的是利用 CAPTCHA 技術來幫助典籍數位化的進行，這個計畫將由書本掃瞄下來無法準確的被光學文字辨識技術識別的文字顯示在 CAPTCHA 問題中，讓人類在回答 CAPTCHA 問題時用人腦加以識別。2009 年 9 月 17 日 Google 宣佈收購 reCAPTCHA 技術，持續發展之下也提供標準的 API 供用戶免費使用，時至今日已經發展出好幾個版本。

目前可以在 Google 網站找到 3 個不同的版本，其功能與特性各有不同：

reCAPTCHA v2

除了原來的文字掃瞄圖片外，也採用 Google 街景拍攝的門牌號碼相片。

reCAPTCHA v3

採用分數制驗證系統，對使用者在網站上的動作進行評分，若分數過低則會被判定為機器人。

reCAPTCHA Enterprise

與 reCAPTCHA v3 相同，採用分數制驗證系統，但能夠提供更精細的分數以及高風險分數原因代碼，以供進一步分析之用。

本篇文章主要是以 reCAPTCHA Enterprise 為主，版本比較可參考 Comparison of features between reCAPTCHA versions 文件。

reCAPTCHA Enterprise 有個重要的概念，就是 reCAPTCHA keys 或 site keys，我將其翻譯為「網站通關金鑰」或是「驗證金鑰」也許比較恰當，他是一個使用在你網站的一組公開金鑰，透過這個 site keys 會依據使用者端提供的各種資訊，自動產生一個唯一的「回應值」(Response)，你要把這個「回應值」傳到後端的 reCAPTCHA Server 進行驗證，由 reCAPTCHA Server 判斷出這個「回應值」是否是「真人」(Human)或「假人」(Bots)。

reCAPTCHA Enterprise 的 site keys 有 3 種使用方式：

Score-based (no challenge) site keys

以「分數」為基礎的驗證方法，這種驗證方法完全不需要由使用輸入資訊，系統會自動判斷使用者透過瀏覽器、鍵盤或是觸控等使用方式，自動收集使用者跟手機或網頁之間的互動情況，判斷該「使用者」是否為「真人」或「假人」，送到 reCAPTCHA Server 驗證時，會提供你一個「分數」(Score)，從 0.0 ～ 10.0 分，其中 0.0 就是絕對的「假人」，而 10.0 就是絕對的「真人」。這種類型的 site keys 適用於「手機 APP」或「網頁」環境。

這樣對使用者來說非常方便，不用讓客戶還在那邊選「哪幾張圖是公車」之類的，表單輸入門檻會低很多。

Checkbox (checkbox challenge) site keys

所謂 Checkbox 就真的是「核取方塊」的意思（如下圖示），他需要使用者真的去對這個 Checkbox 做個點擊的動作，藉此判斷跟網頁互動的對像是否為「真人」在操作。想當然的，這種驗證方式一定要跟使用者發生互動，所以只能用在「網頁」的介面上，尤其特別適合用在「表單填寫」、「網站登入」、「註冊會員」等網頁功能，但不適用於透過「手機 APP」或其他互動方式。

這種驗證方式可能不適用於所有情境，例如要提供「無障礙」網站的話，對「視覺」有問題的用戶就會很不方便，因此使用時要注意。詳見 Understanding the caveats with CAPTCHA challenges

reCAPTCHA WAF site keys

這個 reCAPTCHA WAF site keys 可以讓你把 sitekey 安裝在 WAF (應用程式防火牆) 這一層，但這種作法必須要合格的 WAF service provider 才能使用，例如 GCP 自家的 Google Cloud Armor 服務。詳情請見 reCAPTCHA Enterprise for WAF and Google Cloud Armor integration overview 說明。

整合 reCAPTCHA Enterprise 的大致流程

想要整合 reCAPTCHA Enterprise 到你的網站，建議多少理解一下 reCAPTCHA Enterprise 的運作流程，你可以從 How reCAPTCHA Enterprise works 看到以下循序圖(sequence diagram)：

即便你大概知道這個流程，我還是覺得整合 reCAPTCHA Enterprise 有一點小門檻，所以我打算簡化成以下 3 個步驟來說明：

申請 reCAPTCHA keys 階段

你要到 Google Cloud console 建立 reCAPTCHA keys

也可以從 Google Cloud console 左上角的漢堡選單選取 Security > reCAPTCHA Enterprise 進入此頁面。

收集前端使用者回應值階段

安裝 reCAPTCHA keys 到網頁上 (主要用來收集 reCAPTCHA 回應值)

後端評估與驗證回應值階段

這個步驟會先從後端應用程式取得前端傳來的回應值，並將回應值送到 reCAPTCHA Server 進行評估(assessment)，並取得一個評估後的 Score (分數)，從該分數判斷這個 HTTP 要求是否要允許通過。

此步驟最為麻煩，主因是缺少 ASP.NET Core 範例，所以上手確實有點門檻！

以下我就依據這三個階段，分別說明作法！

申請 reCAPTCHA keys 階段

可以參考 Creating reCAPTCHA keys 這份文件進行操作。

你要先有一個 Google 帳戶
在 Google Cloud Console 建立一個新專案

啟用 reCAPTCHA Enterprise API 服務

進入 reCAPTCHA Enterprise 頁面，如果尚未啟用 reCAPTCHA Enterprise API 服務的話，會先出現以下畫面，你必須選對 GCP 上面的專案(Project)，然後按下 ENABLE 啟用服務：

建立 reCAPTCHA keys

進入 reCAPTCHA Enterprise 頁面

輸入一個顯示名稱(Display name)與使用 reCAPTCHA keys 的平台(Platform type)，由於我們是一個網站服務，所以記得選擇 Website 選項

如果是網站使用，就要設定網站的域名在此，你可以新增多個域名：

最後按下 CREATE KEY 建立即可。

收集前端使用者回應值階段

我們從上一個步驟可以看到一個 Web integration 區段，這裡有一段 JavaScript 程式碼片段，你直接複製起來，貼上到網頁的 <head> 區段內，即可開始收集前端使用者回應值。

範例程式碼如下：

1
2
3
4
5
6
7
8


<script src="https://www.google.com/recaptcha/enterprise.js?render=6LdSxPgjAAAAAGTKX703ydrWNF8WbQv2pZbRXGyX"></script>
<script>
grecaptcha.enterprise.ready(function() {
 grecaptcha.enterprise.execute('6LdSxPgjAAAAAGTKX703ydrWNF8WbQv2pZbRXGyX', {action: 'login'}).then(function(token) {
 ...
 });
});
</script>

這裡特別需要知道的地方有以下幾點：

程式碼片段的 6LdSxPgjAAAAAGTKX703ydrWNF8WbQv2pZbRXGyX 就是你的 reCAPTCHA key
這裡的 grecaptcha.enterprise.ready() 函式會在載入完 reCAPTCHA Enterprise 函式庫後執行，只會執行一次
這裡的 grecaptcha.enterprise.execute() 函式則會執行 reCAPTCHA 驗證（這個函式會回傳一個 Promise 物件）
這裡的 { action: 'login'} 也很重要，這裡是設定一個「驗證動作」的類型，這個值要跟後端進行驗證時使用相同的 action 才行
Google reCAPTCHA 的 action 參數可以是任何字串，它可以用來標記驗證的目的或類型。一些常用的 action 值包括：login (用於登入驗證)、register (用於註冊驗證)、password_reset (用於密碼重置驗證)、contact (用於聯繫表單驗證)，但其實沒有一定要用哪一種，不知道要挑哪一種的話，你隨便選個 login 其實都可以。
程式碼片段中的 ... 不是真的程式碼，而是一個要你客製化修改的地方！
由於 grecaptcha.enterprise.execute() 函式是一個 Promise 物件，你可以透過 .then() 帶入的 function callback 得到一個 token 字串，這個就是由 reCAPTCHA Enterprise 幫你收集好的「回應值」，你要設法將這個值帶到後端去驗證。

這裡有個地雷是，這個透過 grecaptcha.enterprise.execute() 函式取回的 token 有效期只有 2 分鐘！

各位~只有 2 分鐘就會過時/過期！只要 2 分鐘就會 Timeout！只要 2 分鐘就不能用了！

很重要，所以說三遍，為了 SEO 要求，我用三份關鍵字描述！🔥

超過 2 分鐘之後這個 token 就失效了，所以千萬不能在「網頁載入」的時候就取得 token 回應值，否則表單填寫超過 2 分鐘之後不就自動失效了嗎？這個注意事項是有出現在 Create an assessment 官方文件中，我有點懷疑會有多少人看到？😅

後端評估與驗證回應值階段

這裡的步驟就有點多了，我會以 ASP.NET Core 6 為例進行解說完整步驟。

到 Google Cloud Console 的 IAM & Admin > Service accounts 建立一個服務帳戶(Service Accounts)

要從網站的後端呼叫 GCP 上面的 API 服務，都需要有一個身分(Principal)來呼叫 API 服務。你可以從 APIs & Services > Enabled APIs & Services 找到 reCAPTCHA Enterprise API 服務，點擊進去：

我們要建立一個 reCAPTCHA Enterprise API 所需的 CREDENTIALS (身分認證)

這裡有兩個選項，我們透過網站整合 reCAPTCHA Enterprise API 一定是使用 Service Accounts (服務帳戶) 這項！

設定一個服務帳戶名稱，好記就好

🔥 這個步驟超級重要，你要是不在這裡選對 Role (角色)，也就是 reCAPTCHA Enterprise Agent，就算你取得 Service Account 也沒有權限呼叫 reCAPTCHA Enterprise API！

如果沒設定的話，你的 ASP.NET Core 執行時就會得到以下錯誤訊息：

1

Status(StatusCode="PermissionDenied", Detail="Permission denied for: recaptchaenterprise.assessments.create. Please ensure you have sufficient permissions: https://cloud.google.com/iam/docs/granting-changing-revoking-access")

這個步驟可以不用設定，直接按下 DONE 完成設定。

點擊進入剛剛建立的服務帳戶

🔥 切換到 KEYS 頁籤，建立一把新的私密金鑰(key)，主要用來給後端程式呼叫 API 時通過驗證用！

建立金鑰可以選擇兩種格式，我們選擇 JSON 格式

🔥 按下 CREATE 之後，瀏覽器就會直接下載一個 *.json 檔案，這個檔案就是我們的金鑰檔，之後在 ASP.NET Core 網站中用的到！

這個 JSON 檔案的內容大致如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "type": "service_account",
 "project_id": "recaptchademo-374714",
 "private_key_id": "9462e07151d......181083e38c718503",
 "private_key": "-----BEGIN PRIVATE KEY-----\nM...g=\n-----END PRIVATE KEY-----\n",
 "client_email": "myrecaptcha@recaptchademo-374714.iam.gserviceaccount.com",
 "client_id": "11581452......4955852",
 "auth_uri": "https://accounts.google.com/o/oauth2/auth",
 "token_uri": "https://oauth2.googleapis.com/token",
 "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
 "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/myrecaptcha%40recaptchademo-374714.iam.gserviceaccount.com"
}

這個步驟我做了好幾次，漏掉一兩步就別想玩下去了，所以 GCP 就是主要的門檻所在！😅

在 ASP.NET Core 網站安裝 Google.Cloud.RecaptchaEnterprise.V1 NuGet 套件

1

dotnet add package Google.Cloud.RecaptchaEnterprise.V1

設定 ASP.NET Core 網站的 DI 容器 (ServiceCollection)

以下程式碼會將 RecaptchaEnterpriseServiceClient 註冊成 Singleton，並設定 JsonCredentials 為我們剛剛下載的私密金鑰 JSON 檔！

1
2
3
4


builder.Services.AddRecaptchaEnterpriseServiceClient(options =>
{
 options.JsonCredentials = File.ReadAllText("recaptchademo-374714-9462e07151d4.json");
});

如果沒有指定 Credentials 的話，執行時就會得到以下錯誤訊息：

1

The Application Default Credentials are not available. They are available if running in Google Compute Engine. Otherwise, the environment variable GOOGLE_APPLICATION_CREDENTIALS must be defined pointing to a file defining the credentials. See https://developers.google.com/accounts/docs/application-default-credentials for more information.

在 Controller 的建構式注入 RecaptchaEnterpriseServiceClient 物件

1
2
3
4
5
6


private readonly RecaptchaEnterpriseServiceClient _recaptchaClient;

public ContactController(RecaptchaEnterpriseServiceClient re)
{
 this._recaptchaClient = re;
}

建立一個 createAssessmentAsync 方法 (Method)

我參考 Create an assessment using the REST API or Client Libraries 的 C# 範例程式進行改寫如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80


// Create an assessment to analyze the risk of an UI action.
// projectID: GCloud Project ID.
// recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha.
// token: The token obtained from the client on passing the recaptchaSiteKey.
// recaptchaAction: Action name corresponding to the token.
private async Task<bool> createAssessmentAsync(string token,
 string projectID = "recaptchademo-374714",
 string recaptchaSiteKey = "6LdSxPgjAAAAAGTKX703ydrWNF8WbQv2pZbRXGyX",
 string recaptchaAction = "login")
{
 if (String.IsNullOrWhiteSpace(token))
 {
 throw new ArgumentException("The `token` argument must not empty.");
 }

 ProjectName projectName = new ProjectName(projectID);

 // Build the assessment request.
 CreateAssessmentRequest createAssessmentRequest = new CreateAssessmentRequest()
 {
 Assessment = new Assessment()
 {
 // Set the properties of the event to be tracked.
 Event = new Event()
 {
 SiteKey = recaptchaSiteKey,
 Token = token,
 ExpectedAction = recaptchaAction
 },
 },
 ParentAsProjectName = projectName
 };

 Assessment response = await _recaptchaClient.CreateAssessmentAsync(createAssessmentRequest);

 // Check if the token is valid.
 if (response.TokenProperties.Valid == false)
 {
 _logger.LogInformation("The CreateAssessment call failed because the token was: " +
 response.TokenProperties.InvalidReason.ToString());

 return false;
 }

 // Check if the expected action was executed.
 if (response.TokenProperties.Action != recaptchaAction)
 {
 _logger.LogInformation("The action attribute in reCAPTCHA tag is: " +
 response.TokenProperties.Action.ToString());
 _logger.LogInformation("The action attribute in the reCAPTCHA tag does not " +
 "match the action you are expecting to score");
 return false;
 }

 // Get the risk score and the reason(s).
 // For more information on interpreting the assessment,
 // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment

 var score = response.RiskAnalysis.Score;

 _logger.LogInformation("The reCAPTCHA score is: " + score);

 foreach (RiskAnalysis.Types.ClassificationReason reason in response.RiskAnalysis.Reasons)
 {
 _logger.LogInformation(reason.ToString());
 }

 // https://developers.google.com/recaptcha/docs/analytics
 // This chart shows the average score on your site, which is designed to help you spot trends.
 // Scores range from 0.0 to 1.0, with 0.0 indicating abusive traffic and 1.0 indicating good traffic.
 // Sign up for reCAPTCHA v3 to gain more insights about your traffic.
 if (score > 0.5)
 {
 return true;
 }
 else
 {
 return false;
 }
}

這裡 method 總共有 4 個參數，都很重要，除了 token 之外，其他都可以寫進 appsettings.json 組態之中！

因為 GCP 上的每個「專案」都有個唯一的 projectID，你要特別查才知道是什麼，這裡的 projectID 要記得到 https://console.cloud.google.com/welcome 查閱！

這裡的 recaptchaSiteKey 就是你先前建立 site key 時拿到的那組！

這裡的 recaptchaAction 必須跟你在「收集前端使用者回應值階段」設定的 {action: 'login'} 完全一樣，這裡是設定一個「驗證動作」的類型，可以是任意字串！

程式碼邏輯的部分我就不贅述了，大家可以自己看，應該很容易理解。最後的 if (score > 0.5) {} 就是在判斷怎樣的分數允許通過驗證，基本上分數只會介於 0.0 ~ 1.0 之間，共 11 個等級。但在尚未通過 Google Security Review 的前提下，預設只會有 0.1、0.3、0.7 與 0.9 這四個等級，所以建議 Score 結果的判斷式不要用 == 來寫，用 <、<= 或 >、>= 才是比較正確的寫法！

最後要使用就很簡單了，以下是一個簡單的 Action 使用範例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Index([FromForm] ContactViewModel model)
{
 if (await createAssessmentAsync(model.RecaptchaToken))
 {
 return NoContent();
 }
 else
 {
 return BadRequest();
 }
}

總結

整合 Google 的 reCAPTCHA Enterprise 實在太多雷了，這對 Google Cloud Platform 不太熟悉的人來說，整合起來著實有不小的門檻，本文這麼多步驟，要是我不記錄下來，過一段時間我肯定又忘記了！😅

我來重新總結一下整個開發過程：

先到 Google Cloud console 建立 reCAPTCHA keys
你可能需要建立一個新專案，並啟用 reCAPTCHA Enterprise API 服務，然後才能建立 reCAPTCHA keys。

每個 GCP 上面的新專案，都需要個別手動啟用 API 服務。如果你選用先前建立過的專案，且 reCAPTCHA Enterprise API 服務已經啟用過，那就不需要再次啟用。

安裝 reCAPTCHA keys 到網頁上 (前端 JavaScript 為主)
這邊需要寫一點點 JavaScript 才能將 token 回寫到表單上，幫助前端將 token 送回後端評估。
從後端評估前端送來的 token (回應值) 是否有效
你必須建立一個 GCP 上的 Service Account (服務帳戶)，並賦予 reCAPTCHA Enterprise Agent 角色。然後為這個 Service Account 建立一把 key (私密金鑰) 才能組成一個 Credential (身分認證資訊) 讓應用程式使用，然後用這份 Credential 跟 reCAPTCHA Enterprise API 通訊，取得 Assessment (評估) 結果，然後依據 Score (分數) 判斷是否為真人的流量，通常這個 Score (分數) 只要大於等於 0.7 通常就意味著可信度夠高。

另外，我想補充說明的是，reCAPTCHA Enterprise 有每月 100 萬次免費使用額度，這些次數主要是「後端」對 reCAPTCHA Enterprise API 發送驗證 Assessment (評估) 的次數，對許多網站來說，這個數量應該是綽綽有餘了，所以我才考慮直接使用這個服務。

ASP.NET Core Docker 筆記 4 - ASP.NET Core 網站容器化經驗分享

Fri, 09 Dec 2022 00:00:00 +0000

參考網站
 參考網站
 參考網站
 參考網站

前言

發表 Docker 筆記以來，一直有網友提醒應改用 Kubernetes (K8S)，關於這點在前篇文章已經提過，用 Docker / Docker-Compose 玩玩小網站還 OK，一旦涉及高可用性如備援、負載平衡，若不依賴現成管理架構，維運操作將複雜到會咬人。而 Kubernetes 正是目前容器管理框架的主流業界標準，尤其如打算將容器直接部署到雲端廠商(Azure、AWS、Google GCP)，不會 Kubernetes 更是寸步難行。故在次聲明以正視聽，在企業環境如需考量高可用性、負載平衡或想直接部署到廠商雲端，一般不會用 Docker-Compose 而會採用 Kubernetes，請大家注意。

這篇筆記是我將部落格網站移入 Docker 容器的經驗分享，將記錄 Miniblog.Core ASP.NET Core 網站搬進 Docker 過程遇到的一些眉角。

Reverse Proxy 問題

由於我打算在同一機器上共享對外 IP 跑多個網站，因此採行前一篇筆記所說的「以 Compose 組合網站與 DB，網站對映 Host IP/Port，Nginx 另跑容器導向各網站 Port」策略。

目錄對應

部落格網站有一些執行期間更新的內容，包含 NLog Log 檔、文章圖檔、SQLitｅ資料庫等，這些內容不適合放在容器裡，故都需設 Volume 對映到 Host OS 的實際檔案，如此容器可任意刪除重建及升級，管理運用較方便。

時區問題

踩了雷才知道：Docker 容器內的時區跟 Host OS 是脫鉤的。即便本機已設好定為台北時區，Docker 容器預設為 UTC+0 時區，有兩種做法：

在 docker-compose.yml 中加註環境參數 TZ
新增 Volume 對映 /etc/localtime:/etc/localtime:ro，要求容器以 Host OS 的時區為準

第一種做法遇到以 Alpine Linux 版 Image 建的容器需要額外裝套件，故對映 /etc/localtime 較單純。

參考：設定 Docker Container 與 Host 相同時區的方法

取得真實來源 IP 問題

Reverse Proxy 來源 IP 在 ASP.NET Core + Nginx on CentOS 安裝筆記提過，當 ASP.NET Core 架設在 Reverse Proxy 後方，直接看到的是 Reverse Proxy 的 IP，要得到真實來源 IP，在 Nginx config 需加註 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for，透過 HTTP Header 傳遞內容。而 ASP.NET Core 程式也需修改：

1
2
3
4
5
6
7


public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
 app.UseForwardedHeaders(new ForwardedHeadersOptions
 {
 ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
 });
}

不過若 ASP.NET Core 運行於容器，綁定的 IP 不是 127.0.0.1 而是隔離網段 172.1x.0.x IP，此行為打破 UseForwardedHeaders 假設 Request 來自 localhost 的前題，就算設了 ForwardedHeaders， IHttpContextAccessor.HttpContext.Connection.RemoteIpAddress 讀到的仍是 172.1x.0.1 (隔離網段的 Gateway IP)。

由 ASP.NET Core 的原始碼，檢查規則為若 ForwardedHeadersOptions.KnownNetworks 或 ForwardedHeadersOptions.KnownProxies 有設定，來源 IP 必須要是 KnownNetworks 或 KnownProxies 才會認定請求為 Proxy 轉傳。而 KnownNetworks 及 KnownProxies 預設只有本機 IP。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


 // ...

 /// <summary>
 /// Addresses of known proxies to accept forwarded headers from.
 /// </summary>
 public IList<IPAddress> KnownProxies { get; } = new List<IPAddress>() { IPAddress.IPv6Loopback };

 /// <summary>
 /// Address ranges of known proxies to accept forwarded headers from.
 /// </summary>
 public IList<IPNetwork> KnownNetworks { get; } = new List<IPNetwork>() { new IPNetwork(IPAddress.Loopback, 8) };

 // ...

解決方法有兩種，一種是將 172.x.0.0 加入 ForwardedHeadersOptions.KnownNetworks，但網段為 Docker 自由調配，最好寫成自動偵測不宜寫死。

另一個解法是將 KnownNetworks 與 KnownProxies 都清空，一般有來源 IP 被偽造的風險，但我們 ASP.NET Core 網站架構 Nginx Reverse Proxy 是唯一的入口，故我將其視為可接受做法：

1
2
3
4
5
6
7


var forwardingOptions = new ForwardedHeadersOptions()
{
 ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
};
forwardingOptions.KnownNetworks.Clear(); //its loopback by default
forwardingOptions.KnownProxies.Clear();
app.UseForwardedHeaders(forwardingOptions);

參考：

Nginx 內容壓縮問題

跑了一陣子才發現，我用的 Nginx + Certbot 容器的 Nginx 設定檔 /etc/nginx/nginx.conf 預設未開啟 GZIP 壓縮。

我的解法是新增 Volume 對映將 /etc/nginx/nginx.conf 對應到 Host /etc/nginx/nginx.conf，並修改增加 gzip 那段內容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


user nginx;
worker_processes 1;

error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
 worker_connections 1024;
}


http {
 include /etc/nginx/mime.types;
 default_type application/octet-stream;

 log_format main '$remote_addr - $remote_user [$time_local] "$request" '
 '$status $body_bytes_sent "$http_referer" '
 '"$http_user_agent" "$http_x_forwarded_for"';

 access_log /var/log/nginx/access.log main;

 sendfile on;
 #tcp_nopush on;

 keepalive_timeout 65;

 gzip on;
 gzip_min_length 1000;
 gzip_buffers 4 16k;
 gzip_comp_level 5;
 gzip_types text/plain application/x-javascript text/css application/xml text/javascript;

 include /etc/nginx/conf.d/*.conf;
}

Nginx 壓縮設定的意義可參考官方文件

ASP.NET Core Docker 筆記 3 - 共用 Nginx 容器與 Certbot 整合

Thu, 08 Dec 2022 00:00:00 +0000

參考網站

前言

前篇文章介紹過使用 Docker Compose 設定關聯容器(Web、DB、Reverse Proxy)組成系統，容器被隔離在專用網段(Compose 自動建立的 Bridge)，並可透過容器名稱彼此溝通，Compose 也確保相關服務一起啟動一起關閉，是用多個容器建構系統最簡便的做法。

註：關於容器管理 Kubernetes，K8S 提供更強大的功能，支援 Cluster 高可用架構 (單一容器、主機掛掉系統不會死)，為當今在雲端掛載容器以及中大型企業實做容器架構的主流，K8S 無疑可取代 Docker Compose，但其複雜性較高。目前我在單一 Linux 機跑 Docker 還用不到牛刀(雖然有單機版 Minikube 可用)，未來若要將 Docker 應用於工作，K8S 已成必要技能。

用 Docker Compose 組合容器建立服務看似完美，但應用在 Reverse Proxy (Nginx) 時需要額外考量。

我打算在同一台 Linux 上跑多個網站，對外用同一個 IP，再依 HTTP Request 的 Host 標頭導向不同網站。

舉例

舉個例子：假設 Linux 的對外 IP 是 123.123.123.123，我申請兩個 DNS 名稱 web1.xxx.com.tw、web2.xxx.com.tw 都指向 123.123.123.123。

使用者用 http://web1.xxx.com.tw 連上 123.123.123.123 的 80 Port 時，Reverse Proxy 導向 Web1 網站；用 http://web2.xxx.com.tw 時連線時則導向 Web2 網站。由於對外靜態 IP 為珍貴資源，多網站透過 Host 共用 IP 是節省成本的常見做法。

上述以 HTTP Host 名稱導向的做法，若用 Docker Compose 將網站連同 Reverse Proxy 包在一起，就可能出問題。

例如：某 Host OS 跑兩個網站，若各自用 Docker Compose 連同 Nginx 一起包進去，網站 A 由 Web-A + MySQL-A + Nginx-A 組成，網站 B 由 Web-B + MySQL-B + Nginx-B 組成，二者跑在自己的專屬網段，僅 Nginx-A 跟 Nginx-B 對映到 Host OS IP 的 80 Port… 哦哦，衝突出現了，Nginx-A 與 Nginx-B 都需對映 Host IP 的 80 Port，但 Host OS 的 80 Port 只允許被一個程序使用。

解決方式

有幾個解決方向：

Nginx-A 與 Nginx-B 各自對應到主機不同 Port，更前端再掛一台 Nginx 聽 80 Port，依 Host Name 導向到 Nginx-A 與 Nginx- B，如此 Nginx-A 與 Nginx-B 的角色顯得多餘，多了一次轉接但未看到明顯效益，徒增複雜性又耗損效能。
將兩個系統包成一個大 Docker Compose，Web-A + MySQL-A + Web-B + MySQL-B + Nginx，共用 Nginx 可避免 Port 80 繫結衝突，但將不相關系統綁架成一團，被迫一起啟動一起停止挺鳥的，更不用提一旦加跑新服務就要改 Docker Compose，我覺得不行。
將 Nginx 從 Docker Compose 抽離，讓 Web-A 與 Web-B 對映到 Host IP 的不同 Port，整個 Host OS 只跑一份 Nginx 聽 80 Port，依 Host Name 分派給網站 A 或網站 B。也就是用 Docker Compose 執行三個容器：

Web-A + MySQL-A
Web-B + MySQL-B
Ngnix

3 是我認為較可行且有效率的做法。

Nginx 包容器的做法在第一篇筆記已提過，這次我們將重點放在整合 Certbot 及 docker-compose.yml 定義。

原本想抓 Nginx 的 Docker Image 自行加裝 certbot 實現自動安裝與更新 Let’s Encrypt SSL 憑證。

用 Docker 的好處是資源豐富，很快在網路上找到現成解決方案，超級好用的全自動化 Nginx + Certbot -> staticfloat/nginx-certbot。

staticfloat/nginx-certbot

使用方法很簡單，在 /etc/nginx/conf.d 放一個 certbot.conf 接受 80 Port 流量，只用於接收 Let’s Encrypt 的 /.well-known/acme-challenge 要求導向 Certbot 完成自動驗證，其餘則一律導向 HTTPS：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


server {
 # Listen on plain old HTTP
 listen 80 default_server;

 # Pass this particular URL off to certbot, to authenticate HTTPS certificates
 location '/.well-known/acme-challenge' {
 default_type "text/plain";
 proxy_pass http://localhost:1337;
 }

 # Everything else gets shunted over to HTTPS
 location / {
 return 301 https://$http_host$request_uri;
 }
}

接著在 /etc/nginx/conf.d 為每個網站新增一個 someweb.conf 承接 HTTPS 請求。server_name 註明該網站綁定的 Host 名稱(DNS 名稱)，ssl_certificate、ssl_certficate_key 則指向 /etc/letsencrypt/live/DNS名稱 的 fullchain.pem 及 private.pem，這兩個檔案不需事先準備，Certbot 會自動產生，至於 proxy_* 相關設定比照先前介紹過的做法。完整範例如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


server {
 listen 443 ssl;
 server_name blog.darkthread.net;
 ssl_certificate /etc/letsencrypt/live/blog.darkthread.net/fullchain.pem;
 ssl_certificate_key /etc/letsencrypt/live/blog.darkthread.net/privkey.pem;

 location / {
 proxy_pass http://localhost:5000;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection keep-alive;
 proxy_set_header Host $host;
 proxy_cache_bypass $http_upgrade;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 }
}

這個 Docker Image 有一段精巧設計，它在啟動時會主動掃瞄 /etc/nginx/conf.d 下的 config，一旦偵測缺少 /etc/letsencrypt/live/*/fullchain.pem 就連上 Let’s Encrypt 網站進行驗證下載 SSL 憑證，另外還設了每週一次的排程，憑證到期前會自動更新，一氣喝成，全不沾手，貼心到我想起立鼓掌。

若對它的運作原理有興趣，Github 有原始碼可以參考。

為了瞭解原理，我是依著 Github 原始碼自己跑 Dockerfile 製作 Nginx + Certbot 的 Image，如果嫌麻煩，直接從 Docker Hub 下載也成。

以下是我的 Nginx docker-compose.yml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


version: "3"
services:
 nginx:
 image: nginx-certbot
 container_name: nginx
 ports:
 - 80:80
 - 443:443
 volumes:
 - /var/log/nginx:/var/log/nginx
 - /etc/nginx/conf.d:/etc/nginx/conf.d
 - /etc/letsencrypt:/etc/letsencrypt
 restart: always
 environment:
 - CERTBOT_EMAIL=your-email@mail.com
 network_mode: "host"

我設了三個 Volume 對映：

/var/log/nginx：Log 檔
/etc/nginx/conf.d：設定檔
/etc/letsencrypt：用來存放 SSL 憑證

若為 SELinux 記得要 chcon -Rt 參考，另外 network_mode 指定 host 表示 Nginx 容器將直接使用 Host OS 網段，不另設 Bridge。

參考：Docker Compose 鏈接外部容器的幾種方式

就醬，Nginx Reverse Proxy 準備好了，下一篇來再來分享我將 ASP.NET Core 搬進 Docker 的經驗。

ASP.NET Core Docker 筆記 2 - 組合容器建構系統

Wed, 07 Dec 2022 00:00:00 +0000

參考網站
 參考網站

上篇文章體驗過在 CentOS 用 Docker Container 分別跑 Nginx 跟 ASP.NET Core 網站，並建立 Reverse Proxy 關係，接著探討在實務上當需要多個 Container 協同運作時應如何規劃整合。

一個系統常可再拆解成多個服務。以線上購物網站為例，就可能是由 ASP.NET Core 網站(Kestrel)、MySQL 資料庫、Reverse Proxy、金流 Gateway… 等多個服務組成，若要以 Docker Container 實現，有幾種策略：

策略

1. 全部裝在單一 Container

撰寫一個 Dockerfile，以 MySQL 資料資料庫為基底，在上面安裝 ASP.NET Core Runtime、Nginx 組裝合成獸。

好處是一個 Container 搞定，高內聚低耦合，不會因相依服務沒配置好或未啟動而故障。但缺點挺明顯：

某些 Container Image 為求輕巧作業系統層次的工具、程式庫很精簡(例如：Nginx Container 連 ping 都沒有)，只求目標程式能執行就好，要加裝其他軟體時要點技巧，得多花些心思。
全部綁在一起便失去動態調配的彈性，例如：當前端 Web 負載過高時，擴充不易。
當需要個別升級資料庫、ASP.NET Core 版本，或是想抽換服務組合時手續複雜，有違模組化精神。

2. 以個別 Container 執行，獨立控制

如同前篇文章的做法，ASP.NET Core 網站跑 Cotainer 繫結到 Host OS 的 5000 Port，用 Container 跑 MySQL，再用 Container 跑 Ngnix 繫結到 Host OS 80 Port，再設定 Reverse Proxy 規則。

Container 間串接配置全靠人工，系統管理員需協助哪個 Container 聽哪個 Port，確保彼此不衝突。如此做有兩個缺點：

相依服務的啟動狀態未連動，需靠人為控制確保先啟動資料庫 Container 再啟動網站 Container 的順序。
若 Host OS 跑多個系統都用到 MySQL，系統管理員需協調 TCP Port 不衝突，Docker 的 Bridge (橋接器)隔離網段機制全無用武之地。

3. 以個別 Container 執行，但使用 Docker Compose 關聯

為滿足多 Container 協同作業需求，Docker Compose 應運而生。

Docker Compose 定義了一套宣告語法(採用 YAML 格式)，在其中定義各服務 Container 的啟動參數、與 Host OS Port 對映、隸屬 Bridge 網段、Volume 資料夾/檔案對應等等。

Docker Compose 會自動為 Container 建立隔離網段並設好名稱解析，讓 Container 使用容器名稱解析成 IP 找到其他 Container，因此設定連線字串或 URL 時便可寫成 httq://myweb:5000、mongodb://mydb，清楚又方便。

最重要是透過 docker-compose up/down 指令可以一次啟動或停用相關服務，Docker Compose 還會依據相依 depends_on 指定關聯先啟動 DB 再啟動 Web，先關閉 Web 再關閉 DB，便利性讓人工操作望塵莫及。

參考：Docker Compose 初步閱讀與學習記錄

實例

針對上述三種做法，以 ASP.NET Core + Ngninx 為題，對映到以下實例：

1. 安裝成單一 Container

以 ASP.NET Core Image 為基底，安裝 Nginx，設定 nginx.conf，複製 ASP.NET Core 網站檔案並設定 service nginx start 及 dotnet /app/web.dll 分別啟動 Nginx 及 Kestrel。

細節做法可參考這篇文章：Nginx Reverse Proxy to ASP.NET Core – Same Docker Container

不過，該文用的 ASP.NET Core 版本偏舊，若為 ASP.NET Core 2.1 包成 Docker Container 的做法請參考前文

2. ASP.NET Core、Nginx 各自跑 Container

就是我們在前篇文章採行的方式，但有一點要補充，除了直接對映到 Host OS IP 的 TCP Port，也可考慮自訂 Bridge，讓 Container 在隔離網段內溝通，例如：ASP.NET Core 的 5000 Port 只有 Nginx 看得到，從 Host OS 無法存取，如此可避免網路介面(網站、資料庫…)外露到 Host OS，減少被攻擊的風險，這部分後面再找時間介紹。

3. 使用 Docker Compose 串連

ASP.NET Core 與 Nginx 各有自己的容器，使用 Docker Compose 組合串連，一次啟動兩個服務。

細節做法可參考這篇文章：Nginx Reverse Proxy to ASP.NET Core – Separate Docker Containers

綜合以上分析，Docker Compose 無疑是整合關聯 Container 較佳的方式。

練習

光說不練是假把式，寫技術文沒實作感覺怪怪的，來個 Docker Compose 練習好了。手邊沒有 ASP.NET Core + DB Server 的範例，就用 Docker 可以找到的 Image 當題材(也方便大家實地驗證)，試試用 Container 跑 Wekan 看板系統。Wekan 在 Node.js 執行，另外需要 MongoDB，這個練習會用 Docker Compose 組合兩個 Container 架設看板網站。

開始前，記得先安裝 Docker Compose，如果發生 sudo docker-compose 找不到指令，要再加上 sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose 參考。

要使用 Docker Compose 很簡單，說穿了就是將 Container 設定寫成 docker-compose.yml，寫好寫對再呼叫 docker-compose up -d 即大功告成。以 Wekan 為例，docker-compose.yml 如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


version: '3'
services:
 wekan:
 image: wekanteam/wekan:latest
 depends_on:
 - wekandb
 environment:
 - MONGO_URL=mongodb://wekandb/wekan
 - ROOT_URL=http://localhost:80
 ports:
 - 80:8080
 wekandb:
 image: mongo:3.2.14
 volumes:
 - /var/www/wekan/db:/data/db

在這個 YAML 裡，我定義了兩個 Service Container，分別叫 wekan 及 wekandb。

Wekan Container Image 來自 wekanteam/wekan 最新版，depends_on 宣告 wekan 依賴 wekandb，故 Docker Compose 會先啟動 wekandb 再啟動 wekan。

MONGO_URL、ROOTL_URL 為環境變數，其中 MONGO_URL 寫成 mongodb://wekandb/wekan，docker-compose.yml 所定義的各 Container 預設隸屬同一個 Bridge 網段，彼此可用機器名稱解析。

Wekan 網站在 Container 掛在 8080 Port，透過 ports 80:8080 會將其對映到 Host IP 80 Port。

wekandb Container 則以 Mongo DB Container Image 為基底，資料庫檔案以 Volume 方式對映到 Host OS /var/www/wekan/db 資料夾。

這裡補充一個眉角，由於 SELinux 資安管控較嚴，在 CentOS/REHL/Fedora 版 Linux 上 Docker Container 讀取 Volume 對映資料夾可能會出現 permission denied 錯誤，需對該資料夾執行 chcon -Rt svirt\_sandbox\_file\_t /var/www/wekan/db 調整權限，或在目錄名稱後方加上 :Z 由 Docker 自動執行。

參考：Using Volumes with Docker can Cause Problems with SELinux

寫好 docker-compose.yml，執行 sudo docker-compose up -d，Docker Compose 依序帶起 weknadb、wekan 兩個容器，Wekan 看板已在 Host OS 80 Port 運行成功。

最後補充一點，前面提到 Docker Compose 會為整組 Container 建立專屬 Bridge，上圖一開始的 Create network “wekan_default” with the default driver 訊息就是證明。

執行 docker network ls，可看到 wekan_default 是個 bridge，執行 docker inspect wekan_default 則可進一步看到這個網段為 172.18..，而兩個 Container 的 IP 分別為 172.28.0.3 及 172.28.0.2。

Docker Compose 非常適合用來組裝 Web、DB 等多個 Container 構建系統，但我發現針對 Nginx 時有些額外考量，這部分留待下集分解。

ASP.NET Core Docker 筆記 1 - 初探

Tue, 06 Dec 2022 00:00:00 +0000

參考網站
 參考網站

前面研究過在 CentOS 安裝及設定 ASP.NET Core + Nginx，習得徒手在 CentOS 安裝部署伺服器的技能，依循 Roadmap 來到下一階段 - 學習使用 Docker 簡化部署。

容器化及 Docker 這幾年熱到發燙，有些人甚至認為它已在軟體產業掀起一波革命。(我親身體驗的感想也是：Wow! 難怪會爆紅) 此刻才起步已算遲了，但也不是沒有好處，晚起鳥兒有更多蟲可以吃，Docker 相關的文章資源多如牛毛，這裡便不多花篇幅贅述觀念與基本操作，只簡單整理我對 Docker 的理解。

Docker 相關介紹

Container

Container (容器)可以想成極度輕量化的虛擬機器(Virtual Machine)，用法及優點與 VM 相同，能在一台 Host OS 同時運行多個彼此隔離的應用程式環境，但差別在 Container 會共用底層 Host OS，相較 VM 需各跑一份 Guest OS 能省下可觀的記憶體、磁碟，因此 Container 多了啟動速度快，耗用資源少(與直接跑應用程式相去不遠)的優勢。

一台 4GB RAM 的機器頂多跑 2 - 3 台 VM 就緊繃了，但執行數十上百個 Container 不是問題。

2 Container 跟 VM 一樣具有很好的隔離效果，每個 Container 有自己的獨立作業環境(記憶體、磁碟空間、網路)，不會彼此干擾，不必擔心 Container A 改系統設定害 Container B 跑不起來，或是兩個 Container 互相搶奪 80 Port，拿到 Image 就一定能在自己的機器跑起來。

Container 在這方面的特性與 VM 完全相同，但因為不用包入作業系統，體積縮小許多，耗用記憶體也少，但便利性完全不減，取得 Container Image，靠一行指令幾秒內就能在機器把程式跑起來。

Docker Hub

Docker Hub 上有超過 10 萬個 Container Image，從 PHP、Node,js、Apache、MySQL、Mongo DB、Nginx、Redis、ASP.NET Core… 幾乎想得到的都有，下指令自動下載 Image，幾秒鐘就裝好一台 DB、Web 伺服器，再下個指令又裝好第二台，不用擔心跟作業系統不相容、與其他軟體相衝、系統環境有誤導致安裝失敗，這就是 Docker 最迷人的所在。

而我們也可將自己的專案網站做成 Image，交給測試人員測試，交付 OP 幾秒部署上線，也能將做好的 Image 上傳到 Docker Hub 與全世界分享。

Docker Container

Docker Container 起初是基於 Linux Container 技術，故在 Container 只能跑 Linux 平台應用程式，雖然在 Windows 也有 Docker for Windows，但背後是用 Hyper-V 跑 Linux 虛擬機執行 Docker Engine 再跑 Docker Container。

後來微軟也依循相同概念發展出 Windows Container，並融入 Docker 體系，自此 Docker Container 開始有 Linux Container、Windows Container 之分，Windows Container 裡跑的就是不折不扣的 Windows 程式。

參考：安裝 Docker 容器環境 - Windows Server 2016

從此，在 Container 裡跑 ASP.NET WebForm不再是夢。

Windows Container

Windows Container 問市後，ASP.NET Core 程式容器化有 Linux Container 與 Windows Container 兩種選擇。

基於 Linux Container 資源數量上的優勢，加上耗用資源較少，軟硬體成本低，我選擇 Linux Container。

雖然 Container 間共用底層作業系統，Docker Engine 為容器中的應用程式提供隔離不受干擾的空間（記憶體、檔案系統、網路 Port）。

例如：容器 A 寫入 /etc/aaa/default.conf 不影響容器 B /etc/aaa/default.conf 的內容、容器 A 與容器 B 都繫結到 80 Port 也不會衝突。

先前文章提過將 Kestrel 轉為 Linux 服務、設定 www-data 執行權限… 等步驟，改用 Docker 後簡單很多，生命週期由 Docker 控制，在容器內部權限一律為 root 不需額外規劃權限，直接跑 dotnet WebApp.dll 聽 5000 Port 就好。

參考資料：

練習

Docker 安裝與基本操作的參考資料很多，這裡不多介紹，直接來幾個練習暖身：在 CentOS 上用 Docker 下載現成 Conatiner Image 執行 Nginx 伺服器，再用預設專案範本建立 ASP.NET Core 網站並包進 Container 執行。最後將二者串接在一起，使用 Nginx 做為 ASP.NET Core 網站的 Reverse Proxy。

執行 Nginx Container

1

sudo docker run --name mynginx -d -p 80:80 --rm nginx

不誇張，真的只要這行 Nginx 就好了。

-d：把 Container 丟到背景執行不要佔用命令列視窗
-p 80:80：表示將 Container 的 80 Port 對應到 Host OS 的 80 Port
--rm：表示 Container 停止時自動刪除。

開個 Chrome 連上 Host OS 的 80 Port，Nginx 已經準備就緒！

註：docker 指令需繫結 Unix Socket，必須以 SuperUser 權限執行，將使用者加入 Docker 群組可省去每次加 sudo 的麻煩。參考：Manage Docker as a non-root user

1
2


sudo groupadd docker
sudo usermod -aG docker $USER

但這招在 CentOS/Fedora/RHEL 不管用!，但有替代方案：在 /etc/sudoers 加入 yourUserAccount ALL=(ALL) NOPASSWD: /usr/bin/docker 開放 sudo docker 時不用敲密碼，再用 alias docker="sudo /usr/bin/docker" 建立同義詞，也可做到不必 sudo 敲密碼跑 docker 指令。

將 ASP.NET Core 專案包進 Container

將 ASP.NET Core 專案包進 Container 使用 .NET Core CLI 建立 MVC 專案，修改 Startup.cs 取消 app.UseHttpsRedirection()，以 Kestrel 執行 ASP.NET Core 網站。

1
2
3
4


dotnet new mvc
sed -i -e 's/app.UseHttps/\/\/app.UseHttps/' Startup.cs
dotnet publish
dotnet bin/Debug/netcoreapp2.1/web.dll

由於 5000 Port 預設不對外開放，懶得開防火牆，在本機用 curl httq://localhost:5000 驗證網站運行中。

驗證程式可執行後，寫個 Dockerfile 腳本將程式封裝成 Docker Image，這部分細節可參考保哥的文章：如何將 ASP.NET Core 2.1 網站部署到 Docker 容器中。

在實務環境可以設計成全自動化測試流程，到版控抓原始碼放進內含 .NET Core SDK 的 Container 編譯，將結果包成只有 .NET Core Runtime 的 Container Image，用它建立 Container 進行 E2E 測試，一切自動化。這裡為求簡便，我選擇用只有 Runtime 的 Container Image 當成基底，將在 Host OS 編譯好的檔案複製到 Container /app 目錄，Dockerfile 內容如下：

1
2
3
4


FROM microsoft/dotnet:2.1-aspnetcore-runtime
WORKDIR /app
COPY ./bin/Debug/netcoreapp2.1 ./
ENTRYPOINT ["dotnet", "web.dll"]

做好 Dockerfile 後執行 docker build，Docker 會從 Docker Hub 下載 microsoft/dotnet:2.1-aspnetcore-runtime (microsoft/dotnet 是 Image 名稱，同一 Image 常有多種版本可選擇，:2.1-aspnetcore-runtime 是標籤可用來指定版本)，-t 參數指定 Image 名稱為 testapp。

Container Image 做好後接著用 docker run -d --rm --name myapp -p 5000:80 testapp 用剛做好的 Image 建立 Container，ASP.NET Core 專案在 Container 執行時，預設聽 80 Port，故我們用 -p 5000:80 將 Container 的 80 Port 導向 Host OS 的 5000 Port。用 curl 驗證網站運行中。

使用 docker images 及 docker ps 我們可以看到剛才建立的 Image testapp 及 Container myapp：

將 Nginx 設成 ASP.NET Core 網站的 Reverse Proxy

至此，我們做了兩個 Container，myginx 聽 Host OS 80 Port，myapp 聽 Host OS 的 5000 Port，下一步要將 Nginx 設成 ASP.NET Core 網站的 Reverse Proxy。

做法跟先前文章介紹過的概念差不多，為求簡便我們直接修改 conf.d/default.conf 將進入 80 Port 的請求導向 5000 Port。(正規做法建議一個網站開一個 conf 檔) Container 的檔案系統是隔離的，將設定檔保存在 Container 裡不是好主意 - 除非每次修改設定存檔就重新產生 Image 並要求未來一律改用新版 Image 建立 Container，否則一旦 Conatiner 被刪除，設定就會消失。同樣問題也會發生在資料庫檔、Log 檔等執行期間要動態更新的內容，這類檔案保存在 Host OS 檔案系統上比較合理，程式換版換了 Container Image 資料才不受影響。Docker 靠 Volume 解決資料保存及共用需求，docker run 有個 -v host-path:container-path 可將 Host OS 特定目錄或檔案對映到 Container，讓 Container 能讀寫 Host OS 的檔案。

對 Nginx Container 來說，Reverse Proxy 設定放在 /etc/nginx/conf.d，我選擇在 Host OS 也建立相同路徑並將 Container 的 default.conf 複製出來(指令如下)，修改後在 docker run 加上 -v /etc/nginx/conf.d:/etc/nginx/conf.d 對映回去：

1

sudo docker cp mynginx:/etc/nginx/conf.d /etc/nginx/conf.d

修改 /etc/nginx/conf.d/default.conf，目前是將進入 Nginx 80 Port 的請求導向 Host OS 5000 Port，但從 Docker Container 存取 Host OS IP 有些眉角，Mac 或 Windows Docker 18.3+ 可用 DNS 名稱 host.docker.internal 指向 Host OS IP，但 Docker for Linux 18.4+ 這招己失效。參考

省事做法是 docker run 時用 --network host 讓 Container 直接繫結本機 IP 而非 Docker 所屬的隔離網段，如此 default.conf 的 proxy_pass 指向 localhost:5000 即可。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


server {
 listen 80;
 server_name localhost;

 #charset koi8-r;
 #access_log /var/log/nginx/host.access.log main;

 location / {
 proxy_pass http://localhost:5000;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection keep-alive;
 proxy_set_header Host $host;
 proxy_cache_bypass $http_upgrade;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 }
}

完整啟動指令如下：

1

sudo docker run --name mynginx -d -v /etc/nginx/conf.d:/etc/nginx/conf.d --network host nginx

從遠端開啟 Chrome 連上 Host OS 的 80 Port，我們已被順利導向 ASP.NET Core 網站，顯示設定成功。

經過以上練習，我們體驗了從 Docker Hub 下載 Image 建立 Docker Containter 跑 Nginx、用 Dockerfile 將 ASP.NET Core 網站包成 Container、用 Port 映對 Host OS TCP Port 到 Container、使用 -v(–volume) 映對資料夾讓 Container 讀寫 Host OS 檔案。

而在實務應用上，相關的 Conatiner 需要組合在一起執行，例如一個 Container 跑網站，一個 Container 跑資料庫，此時可用 docker-compose 簡化管理；另外 Docker 也提供 Bridge 為相關 Container 建立專屬的隔離網段，防止外界接觸到不想對外公開的網路服務，也避免不相干的 Container 彼此干擾… 這些議題就留待下一篇文章討論。

在 CentOS 上安裝 ASP.NET Core + Nginx 的筆記

Tue, 06 Dec 2022 00:00:00 +0000

參考網站

ASP.NET Core 內建的 Kestrel 伺服器輕巧但功能陽春，實務上需搭配 Reverse Proxy 對外提供服務，Linux 有兩大 Reverse Proxy 選擇：Apache 及 Nginx，這邊筆記一下使用這幾年如日中天的 Nginx。

相較於 Apache、lighttpd，Nginx 標榜單一執行緒、記憶耗用少、穩定性高，強調效能取向，在熱門網站間獨霸一方(參考：維基百科)，與強調效能的 ASP.NET Core 搭配，相得益彰。

以下是我的 CentOS Nginx 安裝設定筆記：

安裝 Nginx。參考：How To Install Nginx on CentOS 7

1
2


sudo yum install epel-release
sudo yum install nginx

發現 CentOS 預設沒裝 telnet 客戶端，檢測查修不便，安裝一下 telnet：

1

sudo yum install telnet

啟動 Nginx

1

sudo systemctl start nginx

啟動後 telnet localhost 80 如有連上就是成功了。如從外部連不上多是防火牆緣故，需額外設定：

1
2
3


sudo firewall-cmd --permanent --zone=public --add-service=http
sudo firewall-cmd --permanent --zone=public --add-service=https
sudo firewall-cmd --reload

設好防火牆，從 Windows 開 Chrome 連上 CentOS 主機 80 Port，如果看到 Nginx 歡迎網頁即代表大功告成。

ASP.NET Core 文件有詳細的Nginx 設定教學，做法是直接修改 /etc/nginx/nginx.conf，在 http 區塊加入 server 設定。

但較模組化的做法是為每個站台寫獨立 conf 檔放在 /etc/nginx/conf.d 下。例如：/etc/nginx/conf.d/default.conf

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


server {
 listen 80;
 server_name linux.darkblog.net; #測試用的自訂網域名稱
 location / {
 proxy_pass http://localhost:5000;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection keep-alive;
 proxy_set_header Host $host;
 proxy_cache_bypass $http_upgrade;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 }
}

設定完畢先用 sudo nginx -t 測試設定檔有沒有被改壞，若 OK 就執行 sudo nginx -s reload 重新載入。

試連時我遇到 502 Bad Gateway 錯誤：

1
2


2018/09/24 15:37:53 [crit] 60137#0: *7 connect() to 127.0.0.1:5000 failed (13: Permission denied) while connecting to upstream, client: 192.168.50.159, server: linux.darkblog.net, request: "GET / HTTP/1.1", upstream: "http://127.0.0.1:5000/", host: "linux.darkblog.net"
2018/09/24 15:37:53 [error] 60137#0: *7 no live upstreams while connecting to upstream, client: 192.168.50.159, server: linux.darkblog.net, request: "GET /favicon.ico HTTP/1.1", upstream: "http://localhost/favicon.ico", host: "linux.darkblog.net", referrer: "http://linux.darkblog.net/"

爬文是 Security-Enhanced Linux (SELinux) 作祟，它是 RHEL 6.6+/CentOS 6.6+ 新加的安全鎖，需下指令解除封印：

1

sudo setsebool -P httpd_can_network_connect on

接著要設定 SSL：

有個很威的工具叫 Certbot，可以自動申請、驗證、下載、安裝並定期更新 Let’s Enrypt 憑證。但這部分要將網站正式掛上 Internet 才好測試，真實憑證留待未來再玩，我先做一張自發憑證驗證 SSL 功能。

1
2
3
4


sudo mkdir /etc/ssl/private
sudo chmod 700 /etc/ssl/private
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/nginx-selfsigned.key -out /etc/ssl/certs/nginx-selfsigned.crt
sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

建立一個 /var/nginx/conf.d/ssl.conf

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


server {
 listen 443 http2 ssl;
 listen [::]:443 http2 ssl;

 server_name linux.darkblog.net;

 ssl_certificate /etc/ssl/certs/nginx-selfsigned.crt;
 ssl_certificate_key /etc/ssl/private/nginx-selfsigned.key;
 ssl_dhparam /etc/ssl/certs/dhparam.pem;

 location / {
 proxy_pass http://localhost:5000;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection keep-alive;
 proxy_set_header Host $host;
 proxy_cache_bypass $http_upgrade;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 }
}

參考：

NLog.config 路徑配合作業系統要改 "/var/log/Darkblog/$/$.log"
在 Reverse Proxy 模式下 HttpContext.Connection.RemoteIpAddress 會抓到 ::1，而 HttpContext.Connection.RemotePort 則是 5000，並非真實客戶端 IP 及對外 Port。在 Startup.cs 加入 app.UseForwardedHeaders() 可解決問題，但啟用 UseForwardedHeaders() 若未搭配 Reverse Proxy 會有來源 IP 偽造風險，不想冒險也不想針對 IIS / Nginx 調整設定，我想到一招讓程式自動依 OS 決定要不要啟用，一勞永逸：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
 //運行於 Linux 時啟用 Reverse Proxy 模式 
 if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
 {
 app.UseForwardedHeaders(new ForwardedHeadersOptions
 {
 ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
 });
 }
}

線上主機當然不好每次靠手動輸入 dotnet Blah.dll 啟動網站，ASP.NET Core 文件展示了將程式包成服務的方法。先建立 /etc/systemd/system/kestrel-darkblog.service，內容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


[Unit]
Description=Darkblog.Core Server

[Service]
WorkingDirectory=/var/www/Darkblog
ExecStart=/usr/bin/dotnet /var/www/Darkblog/Darkblog.Core.dll
Restart=always
# Restart service after 10 seconds if the dotnet service crashes:
RestartSec=10
SyslogIdentifier=darkblog-core
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false

[Install]
WantedBy=multi-user.target

設好 kestrel-darkblog.service 後註冊並啟動服務

1
2
3


sudo systemctl enable kestrel-darkblog.service
sudo systemctl start kestrel-darkblog.service
sudo systemctl status kestrel-darkblog.service

馬上遇到錯誤：

1

(code=exited, status=217/USER) Process: 66571 ExecStart=/usr/bin/dotnet /var/www/Darkblog/Darkblog.Core.dll (code=exited, status=1/FAILURE)

原因是服務模式使用 www-data 身分執行，沒有權限存取 ASP.NET Core 網站所在目錄與檔案。這部分我不是很確定做法，找到的解法是用 chown 將 /var/www/Darkblog 目錄的擁有者及群組都設成 www-data，建立 www-data 帳號及群組，並將我的管理帳號也加入 www-data 群組，如此服務可以存取該目錄，而我也有權限部署檔案。(註：) 以下指令建立 www-data 使用者及群組，將 jeffrey 加入群組，並授與 www-data 群組可以寫入：

1
2
3
4


sudo groupadd www-data
sudo useradd -g www-data www-data
sudo usermod -a -G www-data jeffrey
sudo chmod g+w -R /var/www/Darkblog

有一則小訣竅，以服務方式執行 ASP.NET Core 看不到主控台顯示的錯誤訊息，可改用這個指令來查看：

1

sudo journalctl -fu kestrel-darkblog.service

以上，ASP.NET Core + Nginx on CentOS 執行成功。

附上 CPU / Memory 使用狀況，這是在開瀏覽器狂按 F5 下的數字，總記憶體 1GB，dotnet CPU 在 5% 以下，RAM 耗用不到 10%，有個 kworker CPU 偏高，爬文與硬碟有關，推測與 Win10 Hyper-V VM 不怎麼的虛擬磁碟效能有點關係。但整體數字讓我很滿意，遷都 CentOS 計劃繼續挺進。

.NET SqlClient 安全漏洞 CVE-2022-41064 解讀

Fri, 11 Nov 2022 00:00:00 +0000

參考網站

微軟在 2022-11-08 公佈了 System.Data.SqlClient、Microsoft.Data.SqlClient 的安全漏洞，由於涵蓋大量 .NET 版本 (.NET Framework 到 .NET 6 都可能使用到)，範圍不小，身為 .NET 開發人員，應該關注其影響及修補方式。

參考了以下文件，試著整理資訊如後。

漏洞來源及攻擊方式

漏洞發生原因是現有 SQL Client 程式庫有個 Bug，在高負載狀況下「非同步查詢(Asynchronously Executed Query)」有可能發生錯接查詢結果的狀況，亦即查詢 A 拿到查詢 B 的結果。

註：資訊有限，但 Asynchronously Executed Query 應指 ExecuteReaderAsync、ExecuteScalarAsync、ExecuteXmlReaderAsync 等非同步方法參考，同步式查詢(ExecuteReader()…)在一些狀態下也有可能受影響。(在 Github 找到相關單元測試，透過 ExecuteReader() 但不讀取內容就拋棄 Transaction Scope 方式重現)

攻擊成功條件：參考

Exploiting this vulnerability requires an attacker to be within the SQL Connection Pool.
攻擊者須位於同一 SQL Connection Pool 內 (換言之，在同一 Process 內執行)
Successful exploitation of this vulnerability requires an attacker to exhaust all the threads in the thread pool.
攻擊者需耗盡所有 Thread Pool 所有 Thread
In this case, a successful attack could cause the attacker access queries from other users in the SQL Connection Pool.
在此狀況下，攻擊者有機會存取到同 SQL Connetion Pool 其他使用者的查詢結果(撿到什麼內容屬隨機性質)

漏洞範圍

漏洞存在 Microsoft.Data.SqlClient 及 System.Data.SqlClient 眾多版本：

Microsoft.Data.SqlClient 1.1.3 (含)之前及 2.0.0 ~ 2.1.1
System.Data.SqlClient 4.8.4 (含)之前版本

而微軟也已釋出 1.1.4、2.1.2、4.8.5 修補漏洞

修補方式

.NET Core / .NET 5/6 使用以下方式更新版本：

1
2
3
4
5
6
7


dotnet add package Microsoft.Data.SqlClient --version 2.1.2

# 或
dotnet add package Microsoft.Data.SqlClient --version 1.1.4

# 或
dotnet add package System.Data.SqlClient --version 4.8.5

或者直接修改 .csproj：(若專案先參照其他程式庫再間接參照 SqlClient，也需要加入 PackageReference 強制使用新版)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<Project Sdk="Microsoft.NET.Sdk.Web">

 <PropertyGroup>
 <TargetFramework>net6.0</TargetFramework>
 <Nullable>enable</Nullable>
 <ImplicitUsings>enable</ImplicitUsings>
 </PropertyGroup>

 <ItemGroup>
 <PackageReference Include="Microsoft.Data.SqlClient" Version="2.1.2" />
 </ItemGroup>

</Project>

.NET Framework 請安裝 November 2022 Security and Quality Rollup Updates for .NET Framework。

Entity Framework Core 6.0 字串屬性對應欄位 NOT NULL 問題

Thu, 10 Nov 2022 00:00:00 +0000

參考網站

升級 .NET 6 踩到的小問題筆記。

前情提要

依之前學到的 EF Core Model 設計，string 屬性預設對應的欄位預設為 Nullable，標註 [Required] 才會宣告為 NOT NULL。不過，這條規則到 .NET 6 已有所改變。某段 EF Core 寫入資料庫時冒出欄位不允許 NULL，但 Model 中該屬性並未宣告為 [Required]。

研究發現這與 .NET 6 啟用 Nullable Context 有關，csproj 多了 <Nullable>enable</Nullable> 設定以支援 C# 8 推出的 Nullable Reference Type 概念。設為 enable 時，Compiler 啟用 Null Reference Analysis 及相關語言特性，以字串為例，若 string 沒宣告成 string? 卻可能為 null 時會得到警告；若要明確標示此處就是要設成 null，可在後方加上 Null-Forgiving Operator，例如 string x = null!;。

若不想啟用此特性，設成 disable，Compiler 即會恢復 C# 7.3 以前的行為。

EF Core 產生資料庫對應 SQL Schema 時，也會受 Nullable Context 影響，當 <Nullable>enable</Nullable>，即使未加 [Required]，Model 的字串屬性仍會被視為不可為 null，在 CREATE TABLE 時會加上 NOT NULL。

問題重現

用以下程式重現問題。簡單宣告了 Entity 型別、DbContext，其中 RequiredText 有加註 [Required]，另一個 OptionalText 則沒有，呼叫 DbContext.DataBase.GenerateCreateScript() 檢視其對應的 SQL Schema：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


using System.ComponentModel.DataAnnotations;
using Microsoft.EntityFrameworkCore;

var options =
 new DbContextOptionsBuilder<MyContext>()
 .UseSqlServer("data source=(localdb)\\mssqllocaldb")
 .Options;

var dbCtx = new MyContext(options);
Console.WriteLine(dbCtx.Database.GenerateCreateScript());

class MyContext : DbContext
{
 public DbSet<Item> Items { get; set; } = null!;
 public MyContext(DbContextOptions<MyContext> options) : base(options) { }
}

public class Item //Entity 型別
{
 //慣例，屬性名稱為 Id 或 <type name>Id 會自動成為 Entity 的 Key
 public int ItemId { get; set; }

 [Required]
 public string RequiredText { get; set; } = null!;
 public string OptionalText { get; set; } = null!;
}

如下圖所示，當 <Nullable>enable</Nullable> 時，OptionalText 也會被加上 NOT NULL，換成 disable 才會恢復之前的規則。

所以，.NET 6 啟用 Nullable Context 時，Model 字串屬性要允許 null，型別也需改成 string?，這樣才會對應成 Nullable 資料庫欄位。(註：RequiredText 故意拿掉 = null! 觸發 CS8618 警告，證明有設 <Nullable>enable</Nullable>)