在 Windows 上更新 HiNC¶

由 Windows 安裝程式 HiNC-2025-webservice-win-Setup.exe、或由可攜式套件 HiNC-2025-webservice-win-Portable.zip 放置的一份 HiNC，會從選單列自我更新：它檢查更新伺服器提供了什麼，並在你要求時下載、安裝某個版本。本頁說明更新標記、軟體更新對話框、一個版本怎麼安裝上去、更新設定、教室鏡像，以及同一台電腦執行好幾個站時怎麼更新。安裝 HiNC、它的資料目錄與設定檔，見在 Windows 上安裝 HiNC。

已安裝的副本與其他副本¶

由安裝程式或可攜式套件放置的一份 HiNC，是已安裝的副本：它可以檢查新版本、下載某個版本——較舊的版本也可以——並重新啟動為那個版本。它把在對話框裡做的更新選擇保存在資料目錄的 update-state.json：自動檢查的開關、提供的版本的選擇，以及決定這份安裝在分批推出中所處位置的安裝 id。

一份 HiNC-2025.exe（已安裝的 HiNC 的程式）若是以其他任何方式放置——例如從一份安裝裡手動複製出來的資料夾——仍然可以檢查更新伺服器提供了什麼，並列出它們的版本，但無法安裝任何一個：軟體更新對話框會用一條灰色橫幅說明這一點，它的版本表沒有安裝按鈕，HTTP 介面也會以 NotInstalled 拒絕安裝。它的更新選擇在重新啟動之後不會保留。

HiNC-2025-webservice 範例——也就是單獨執行的網頁服務，伺服器部署執行的、以及用 dotnet run 從原始碼啟動的，都是它——完全沒有更新檢查：它的版本標記只標出版本，說明選單到日誌檢視器為止，它也不提供 api/app-update（見從另一個專案裝載網頁服務；英文，未鏡像）。

更新標記¶

選單列左端的版本標記——v 後面接著執行中的版本——同時也是更新標記。它的顏色、圖示與工具提示跟著更新狀態走：

狀態	標記	工具提示
還沒檢查過	灰色外框	尚未檢查更新。按一下即可檢查。
已是最新版本	綠色外框，勾號	已是最新版本（… 檢查）。
連不上伺服器	灰色外框，劃掉的雲朵	連不上更新伺服器（…）。
有較新的版本可用	橘色，向上箭頭，`v<current> → <new>`	有新版本 …。按一下即可更新。
下載中	橘色，百分比	正在下載版本 …：…%
準備中	橘色，準備中…，有量測時再加上該步驟的百分比	下載完成，正在準備版本 …。
下載失敗，等待重試	灰色，時鐘	上次下載失敗，將於 … 重試。
已下載，等待套用	橘色，重新啟動圖示，`v<current> → <new>`	版本 … 已下載。按一下即可重新啟動並套用。
重新啟動中	橘色，旋轉的箭頭	正在重新啟動為版本 …
執行中的版本已被撤回	紅色	這個版本已被撤回：…

在任何狀態下，點一下標記都會打開軟體更新；標記本身從不檢查、下載或套用任何東西。說明 ▸ 檢查更新…打開的是同一個對話框。頁面每分鐘讀一次更新狀態，檢查或下載進行中時則每秒一次；服務以另一個版本回來時，頁面會自行重新載入，讓新的前端跟著載入。

「軟體更新」對話框¶

對話框最上方是目前版本與立即檢查，接著一行寫出上次檢查的時間，以及回應那次檢查的伺服器在設定中的名稱——若那次檢查沒有任何伺服器回應，這一行就照實說明。光是打開對話框並不會檢查；立即檢查會檢查，不管自動檢查的開關怎麼設。沒有設定任何更新伺服器時，它不可用；從同一個頁面要求的每次檢查之後，它也有 30 秒不可用——它的工具提示會寫出何時可以再按。

其下視情況出現：無法安裝的副本的那條灰色橫幅；沒有設定伺服器時的灰色橫幅；發行者撤回了執行中的版本時的紅色橫幅，寫出原因並提供改裝 …；進行中的下載的狀態；有較新的版本可用時的有新版本 …。，在已安裝的副本上附帶更新到 …；或者這台電腦已是開放給它的最新版本。。檢查或下載失敗時，會在一行橘色的上次的問題裡留下原因；不論介面是哪種語言，那段文字都是英文。

接著是兩項設定。自動檢查更新切換自動檢查，提供的版本則在穩定版與所有版本（含測試版）之間選擇。已安裝的副本把這兩項選擇都保存在它的資料目錄裡，它們在那裡優先於設定中的預設值。

版本列出上次檢查找到的每個版本，最新的在前，帶著它的日期、狀態、說明與下載大小，不論提供的版本怎麼設。執行中版本的那一列會反白，並標示執行中；其他每個已安裝的副本可以換上的版本，都帶有安裝。

狀態	意義
穩定版	由發行者升為穩定版；在穩定版下提供，可能先開放給一部分安裝
測試版	為接受每個版本的人發佈；只在所有版本下提供。發行者的版本表沒有列出的版本，一律視為測試版
已撤回	已撤回：從不提供、無法安裝，只有在它是執行中的版本時才會列出

發行者撤回的版本，在已經安裝它的地方會繼續執行。更新標記變成紅色，橫幅上的改裝 …會安裝開放給這份安裝的最新版本——可能是較舊的版本。在按下它之前，什麼都不會改變。

分批推出給一部分安裝的穩定版，只會提供給落在那一部分之內的安裝。每一份安裝的位置由它資料目錄裡的安裝 id 固定，所以每一次都是同一批安裝先收到分批推出的版本——包括修正某個出了問題的版本的那一版。尚未開放給這台電腦的穩定版帶著一個沙漏，分批開放中：尚未開放給這台電腦，但仍然可以從它那一列安裝——老師要全班用同一個版本時，也是這樣做。所有版本不理會分批推出的比例。

安裝某個版本¶

按下更新到 …、改裝 …，或某一列上的安裝。確認訊息寫著HiNC 會下載版本 …，下載完成後重新啟動。這個頁面會自動重新連線。比目前執行的版本舊的版本，還會加上用較新版本儲存的專案，在它上面可能開不起來。
下載會顯示它的百分比，旁邊是取消下載。
下載內容若只帶著相對於已安裝版本的變動，HiNC 接著會準備新版本：把變動套到目前安裝的版本上，重新組成完整的套件，共三個步驟——解開目前安裝的版本、套用變動、組成新版本的套件。這需要 20 秒到 1 分鐘，而且無法取消。
下載好的版本會立刻套用——除非有執行正在進行，或有其他站從同一份安裝執行。這時它會等待，標記顯示 v<current> → <new>，對話框則提供重新啟動並套用。按下它時，會詢問現在重新啟動會中斷這次執行。仍要重新啟動嗎？，或列出套用更新會關閉的那些站；仍要重新啟動則照樣進行。
HiNC 以它當初啟動時的同一條命令列重新啟動為新版本，通常需要 20 到 40 秒，回來之後頁面會重新載入。

下載好的版本絕不會在下次啟動時自行套用。重新啟動之後，較新的版本會再次被提供來套用；較舊的版本不會，要從它那一列再安裝一次。如果切換到新版本沒有完成——HiNC 以外的某個程式佔著安裝資料夾裡的某個檔案，例如在那裡開著的命令提示字元——舊版本會再次啟動，而上次的問題會說明這件事。關掉那個程式，再安裝一次這個版本：對話框有重新啟動並套用就按它，否則按它那一列的安裝。

自行檢查與重試¶

只有已安裝的副本會自行檢查，而且只在自動檢查更新開著時：第一次在它啟動後 1 到 10 分鐘，之後每隔 ScanIntervalHours 一次，每次等待都會隨機偏移最多 10%，讓同時啟動的安裝不會同時檢查。把這項設定打開，會立刻檢查一次。一次檢查會從第一台回應的伺服器讀兩個小小的索引檔，從不下載任何版本：只有使用者要求時才會開始下載。

伺服器依 Priority 由小到大嘗試，優先順序相同的伺服器之間則以隨機順序。下載在每一台伺服器上都失敗時，會排入佇列，在 1、2、4、8 分鐘之後重試，之後每 15 分鐘一次，每次等待都隨機乘上 0.7 到 1.3 之間的倍數；失敗十二次之後就放棄，這個版本要晚一點再安裝一次。等待期間，對話框寫著上次下載失敗。HiNC 會在 … 自動重試（第 … 次重試），而取消下載會把它撤回。這段時間請讓 HiNC 繼續執行。

Update 設定區段¶

Update 區段隨程式資料夾裡的 HiNC-2025.settings.json 出貨，而每次更新都會換掉這個檔案。要改它，請改在資料目錄的 appsettings.local.json 裡，這個檔案在它之後讀取（見變更設定）。逐鍵說明：

鍵	意義	預設值
`ScanEnabled`	已安裝的副本是否自行檢查	`true`
`ScanIntervalHours`	兩次自動檢查之間相隔的小時數	`24`
`Track`	`Stable` 或 `Latest`——也就是提供的版本設定	`Stable`
`Servers`	更新伺服器，以操作者自訂的名稱為鍵	`HiNC-2025.settings.json` 所指名的四台伺服器
`Servers:<name>:Url`	更新來源資料夾（feed folder）：一個 `http`／`https` 位址，或本機、`\\server\share` 資料夾；留空則停用該項	—
`Servers:<name>:Priority`	數值較小者先嘗試	`1`

ScanEnabled 與 Track 只是預設值：一旦在對話框裡改過其中之一，保存在資料目錄裡的選擇就會勝出。Servers 以名稱為鍵，讓 appsettings.local.json 可以加上一台伺服器，或把某個出貨時就有的伺服器的 Url 設為空字串來停用它，而不必把其他伺服器重寫一遍。出貨的每一項都以它的主機命名——也就是在 Windows 上安裝 HiNC 裡安裝程式下載所用的四個網址，依那個順序嘗試——所以 "superhightech.com.tw": { "Url": "" } 會停用其中最後一台。

教室鏡像¶

全班透過同一條網路線更新時，在區域網路上放一份更新，就不必每台電腦都把同一個版本各下載一次。

建一個全班電腦都讀得到的共用資料夾，例如 \\teacher-pc\hinc-update\win。內部網頁伺服器上的資料夾也可以。
從更新伺服器的資料夾 https://superhightech-hinc-1.webredirect.org/hinc-update/win/ 複製進去：
- releases.win.json 與 hinc-versions.json；
- 全班要裝的那個版本的 HiNC-2025-webservice-<版本>-full.nupkg；
- 那個版本、以及它和全班目前版本之間每一個版本的 HiNC-2025-webservice-<版本>-delta.nupkg。電腦只要能用這些變動套件更新就會用它們，只落後一個版本也一樣。
在每一台電腦的 appsettings.local.json 加上這個鏡像，然後重新啟動 HiNC：
```
{
  "Update": {
    "Servers": {
      "Classroom": { "Url": "\\\\teacher-pc\\hinc-update\\win", "Priority": 0 }
    }
  }
}
```
JSON 裡的反斜線都要寫兩次。之後對話框會寫著檢查是「經由 Classroom」。

完整套件留給用不了變動套件的電腦：落後超過十個版本的、要退回較舊版本的，以及變動套件更新失敗的。鏡像上沒有的東西——例如更舊版本的變動套件——會從網際網路上的伺服器取得。
連不上、或裡面沒有任何版本的鏡像會被略過，改用網際網路上的伺服器，服務日誌會記下略過它的那次檢查與原因。
只要鏡像有回應，HiNC 就只從它取得版本清單與每個版本的狀態。發行者每次發佈、撤回或擴大開放某個版本，都要再複製一次那兩個 .json 檔：舊的副本會讓全班都看不到撤回。

同一份安裝上的多個站¶

同一份安裝可以再執行其他站，每一站以 --environment <name> 啟動，並遵守單機多站配置的規則。它們共用資料目錄、更新選擇與安裝 id。一次只有一站能下載或套用更新；在某一站等著的版本，會在另一站下載別的版本時被丟掉；套用更新會關掉這份安裝的每一站，而只有套用它的那一站會重新啟動——規則與對話框見多站時的更新。

HTTP 介面¶

更新標記與對話框都建立在 api/app-update 之上，而只有已安裝的 HiNC 的程式 HiNC-2025.exe 提供它。HiNC-2025-webservice 範例沒有這條路由：在那裡發出的 GET 會轉由應用程式自己的頁面回應，得到的是 HTML。如何呼叫服務，見透過 HTTP 驅動網頁服務（英文，未鏡像）。

方法	路徑	作用
GET	`api/app-update/status`	更新狀態：`currentVersion`、`installed`、`serversConfigured`、`scanEnabled`、`track`、`checking`、`lastCheckedAt`、`lastCheckSucceeded`、`lastError`、`lastServer`、`newestOffered`、`updateAvailable`、`currentRecalled`、`currentNote`、`phase`（`Idle`、`Downloading`、`Queued`、`Downloaded`、`Applying`）、`targetVersion`、`progress`、`stage`（`Transfer`、`Rebuild`）、`rebuildStep`、`rebuildPercent`、`attempt`、`nextRetryAt`
GET	`api/app-update/versions`	上次檢查找到的每個版本，最新的在前：`version`、`status`、`rollout`、`date`、`note`、`fullSize`、`downloadable`、`offered`、`isCurrent`
PUT	`api/app-update/settings`	本體 `{ scanEnabled, track }`，省略其中一項即維持不變；回應狀態
POST	`api/app-update/check`	立即檢查伺服器；回應狀態
POST	`api/app-update/install`	本體 `{ version, restartWhenDone }`（`restartWhenDone` 預設為 `true`）；回應狀態
POST	`api/app-update/apply`	本體 `{ force }`；重新啟動開始進行後回應 `202`
POST	`api/app-update/cancel`	取消執行中或排入佇列的下載；回應狀態

lastServer 是回應上次檢查的伺服器在設定中的名稱；在沒有任何伺服器回應的檢查之後，它是 null。

install、apply 與 cancel 拒絕時回應 409，本體為 { success: false, code, message }：

`code`	拒絕的原因
`NotInstalled`	這份 `HiNC-2025.exe` 不是由安裝程式或可攜式套件放置的
`UnknownVersion`	伺服器沒有提供那個版本（未知、已撤回，或沒有套件）
`AlreadyCurrent`	那個版本就是執行中的版本
`Busy`	已經有下載或重新啟動正在進行
`NothingDownloaded`	沒有下載好、等著套用的版本——或這份安裝的另一站後來下載了別的版本，這時 `lastError` 會說明
`SessionBusy`	有執行正在進行或暫停中；`force` 可以略過
`OtherStationsRunning`	有其他站從這份安裝執行；本體會加上 `stations`，`force` 可以略過
`UpdaterFailed`	更新程式無法啟動；什麼都沒有改變，原因在 `lastError` 裡
`CannotCancelNow`	套件正在重新組成，這一步無法停止

延伸閱讀¶

在 Windows 上安裝 HiNC — 安裝程式、資料目錄、設定檔與它的讀取順序
應用程式視窗 — 更新標記所在的選單列，以及「說明」選單
訊息與日誌 — 資料目錄裡的日誌檔，以及塑造它們的那些設定
單機多站配置 — 每一站都必須保持唯一的那些設定，以及多站時的更新
系統需求 — 這台機器需要什麼