.NET Reactor 程式碼保護指南

本文件說明 GST 專案的 .NET Reactor 三級保護策略、排除清單與打包流程整合。目前應用於 ProcessVision，未來可能擴展至 Jope-SMB。

1. 三級保護策略

1.1 策略總覽

等級	目標	保護強度	適用 Assembly
Max	授權核心	最高	`GST.Core.Licensing`
Standard	商業邏輯	平衡	`GST.Core.`, `GST.Protocols.`, `GST.Plugin.*`
Light	介面/UI	最低	`GST.Core.Abstractions`, `GST.Core.Aspects`, `GST.UI.*`

1.2 保護參數比較

設定	Light	Standard	Max
NecroBit（IL → Native）	-	✅	✅
NecroBit Reflection Mode	-	✅	-
Anti-Debug	✅	✅	✅
Anti-ILDASM	✅	✅	✅
Exclude Enums	✅	✅	-
Exclude Methods	✅	-	-
Exclude Properties	✅	✅	-
Remove Enum Fields	-	-	✅
Licensing / Hardware Lock	-	-	✅

2. 各等級詳細說明

2.1 Max — 最高保護

對應 Profile：GSTProtection-Max.nrproj 適用 Assembly：GST.Core.Licensing

NecroBit = true（IL 完全轉換為 Native Code，移除所有 IL Metadata）
NecroBit Reflection Mode = false（停用 Reflection 相容性，最大化混淆）
Anti-Debug = true
Anti-ILDASM = true
Obfuscate_All_Method_Parameters = true
Remove_Enum_Fields = true
License_Hardware_Lock_Enabled = true（支援機台綁定）

設計理由：License 驗證是最核心的智財，必須最大程度防止反編譯。

2.2 Standard — 平衡保護

對應 Profile：GSTProtection-Standard.nrproj 適用 Assembly：

GST.Core.*（Core 模組，排除 Abstractions、Aspects、Licensing、Localization）
GST.Protocols.*（通訊協定）
GST.Plugin.*（Plugin 框架，排除 DataLogging、RecipeManagement）

NecroBit = true（IL → Native）
NecroBit Reflection Mode = true（保留 Reflection 相容性，支援 DI/IoC）
Anti-Debug = true
Anti-ILDASM = true
Licensing = false

設計理由：商業邏輯需要保護，但必須保留 Reflection 以支援 DI Container 和 Plugin 動態載入。

2.3 Light — 最低保護

對應 Profile：GSTProtection-Light.nrproj 適用 Assembly：

GST.Core.Abstractions（介面定義）
GST.Core.Aspects（Metalama AOP）
GST.UI.*（WPF UI 元件）
GST.ServiceInfrastructure.*
GST.Reporting.Core

NecroBit = false（停用，保留完整 IL）
Control Flow Obfuscation = false
Name Obfuscation = false
Anti-Debug = true
Anti-ILDASM = true
所有 Types/Methods/Properties/Parameters = Excluded

設計理由：這些模組主要是介面、UI Binding、AOP 切面，積極混淆會破壞 WPF Binding 和 Reflection。僅提供 Anti-Tampering 層級的保護。

3. 排除清單

3.1 完全不保護的 Assembly

Assembly	原因
`GST.App.ProcessVision`	Velopack entry point，必須保持原始狀態
`GST.Core.Localization`	動態資源解析與 .NET Reactor 不相容
`GST.Plugin.DataLogging`	Runtime 型別載入衝突
`GST.Plugin.RecipeManagement`	序列化/Reflection 密集操作不相容

3.2 ReadyToRun 排除（.csproj）

<PublishReadyToRunExclude Include="GST.Core.Localization.dll" />
<PublishReadyToRunExclude Include="GST.Plugin.DataLogging.dll" />
<PublishReadyToRunExclude Include="GST.Plugin.RecipeManagement.dll" />

ReadyToRun 會預先 JIT 編譯 IL 為 Native Code，干擾 .NET Reactor 後續的 IL 分析與轉換。

4. 保護腳本

4.1 檔案位置

GST.App.ProcessVision/
├── protection/
│   ├── Protect-GstAssemblies.ps1      ← 保護執行腳本
│   ├── GSTProtection-Max.nrproj       ← Max Profile
│   ├── GSTProtection-Standard.nrproj  ← Standard Profile
│   └── GSTProtection-Light.nrproj     ← Light Profile
└── build/
    └── publish-velopack.ps1            ← 整合打包腳本

4.2 保護邏輯（Protect-GstAssemblies.ps1）

1. 掃描 publish 目錄中所有 GST.*.dll
2. 依名稱判斷 Tier：
   ├─ GST.Core.Licensing           → Max Profile
   ├─ GST.Core.Abstractions        → Light Profile
   ├─ GST.Core.Aspects             → Light Profile
   ├─ GST.UI.*                     → Light Profile
   ├─ GST.ServiceInfrastructure.*  → Light Profile
   ├─ GST.Reporting.Core           → Light Profile
   ├─ GST.Core.*（其餘）            → Standard Profile
   ├─ GST.Protocols.*              → Standard Profile
   └─ GST.Plugin.*（其餘）          → Standard Profile
3. 跳過排除清單中的 Assembly
4. 呼叫 dotnet_reactor_console.exe 逐一保護
5. 移除 .nrmap 對應檔
6. 輸出保護摘要報告

4.3 執行方式

# 獨立執行保護（需先 dotnet publish）
cd protection
.\Protect-GstAssemblies.ps1 -PublishDir "..\bin\Release\net8.0-windows\win-x64\publish"

# 透過 publish-velopack.ps1 自動執行（推薦）
cd build
.\publish-velopack.ps1 -Version "1.0.6"

5. 打包流程整合

5.1 完整 Pipeline

Stage 1: PUBLISH
  dotnet publish -c Release -r win-x64 --self-contained
  └→ 輸出到 publish/

Stage 2: PROTECT
  Protect-GstAssemblies.ps1
  └→ 原地保護 publish/ 中的 GST.*.dll

Stage 3: VELOPACK PACK
  vpk pack --packId ProcessVision --mainExe Jope.App.ProcessVision.exe
  └→ 產出 .nupkg + Setup.exe + RELEASES

Stage 4: GITHUB RELEASE（可選）
  gh release create v{version} ...
  └→ 上傳到 GitHub Releases

5.2 Pipeline 控制參數

# 只到 Publish（不保護、不打包）
.\publish-velopack.ps1 -Step Publish

# 到 Protect（Publish + 保護）
.\publish-velopack.ps1 -Step Protect

# 到 Pack（完整流程，預設）
.\publish-velopack.ps1 -Step Pack

# 到 Release（完整流程 + 上傳 GitHub）
.\publish-velopack.ps1 -Step Release -UploadToGitHub

# 跳過保護
.\publish-velopack.ps1 -SkipProtection

6. Hardware Lock（機台綁定）

6.1 用途

部署到特定機台時，透過 .NET Reactor 的 Licensing 功能綁定 Hardware ID，防止複製到其他機器執行。

6.2 使用方式

.\publish-velopack.ps1 -Step Protect -HardwareId "ABCD-1234-EFGH-5678-IJKL"

6.3 運作原理

腳本暫時修改 .nrproj 中的 License_Hardware_ID
啟用 Max Profile 的 License_Hardware_Lock_Enabled
執行保護
保護完成後自動還原 .nrproj 為原始狀態
支援多組 Hardware ID（分號分隔）

注意：Hardware Lock 與 GST.Core.Licensing 的 Machine Fingerprint 是不同機制。 Hardware Lock 是 .NET Reactor 層級的執行限制，Machine Fingerprint 是應用層級的授權驗證。

7. 常見問題

7.1 保護後功能異常

檢查該 Assembly 是否應加入排除清單。常見原因：

Reflection 密集（DI、序列化）→ 使用 Standard（開啟 Reflection Mode）或 Light
WPF Binding（XAML 綁定到 Property）→ 使用 Light
Metalama Aspect（編譯時程式碼產生）→ 使用 Light
動態資源載入（Localization JSON）→ 加入排除清單

7.2 Velopack 安裝後啟動失敗

確認 GST.App.ProcessVision.dll（entry point）未被保護。Velopack 需要讀取 entry point 的 metadata。

7.3 ReadyToRun 與 .NET Reactor 衝突

不相容的 Assembly 必須同時加入：

.csproj 的 PublishReadyToRunExclude
Protect-GstAssemblies.ps1 的排除清單

8. 新增 Assembly 時的處理流程

判斷 Assembly 性質（介面 / 商業邏輯 / 核心授權）
選擇對應 Tier（Light / Standard / Max）
測試保護後功能是否正常
如不相容，加入排除清單並更新 .csproj ReadyToRun 排除
更新本文件的 Assembly 對照表

文件版本：v1.0 建立日期：2026-03-16 最後更新：2026-03-16 對應 Linear Issue：GST-169

1. 三級保護策略​

1.1 策略總覽​

1.2 保護參數比較​

2. 各等級詳細說明​

2.1 Max — 最高保護​

2.2 Standard — 平衡保護​

2.3 Light — 最低保護​

3. 排除清單​

3.1 完全不保護的 Assembly​

3.2 ReadyToRun 排除（.csproj）​

4. 保護腳本​

4.1 檔案位置​

4.2 保護邏輯（Protect-GstAssemblies.ps1）​

4.3 執行方式​

5. 打包流程整合​

5.1 完整 Pipeline​

5.2 Pipeline 控制參數​

6. Hardware Lock（機台綁定）​

6.1 用途​

6.2 使用方式​

6.3 運作原理​

7. 常見問題​

7.1 保護後功能異常​

7.2 Velopack 安裝後啟動失敗​

7.3 ReadyToRun 與 .NET Reactor 衝突​

8. 新增 Assembly 時的處理流程​