自更新

Windows x64/arm64、Linux x64/arm64（glibc 與靜態 musl 建置）、macOS Apple Silicon 以及 FreeBSD/NetBSD x64/arm64 上的 CLI 與獨立 Agent 可以從發布網站更新自身的執行檔：

remote-cli update self --check
remote-cli update self
remote-agent update self --check
remote-agent update self

更新器會保持目前執行檔的 C 執行階段：musl 建置只安裝 musl 套件，glibc 建置只安裝 glibc 套件。OpenWrt 即使是 x64/arm64 也繼續使用 opkg/apk：其套件不含封存更新器，在存在 /etc/openwrt_release 的主機上執行的 musl 套件也會拒絕自我更新。只有 manifest 列出對應發布套件的平台才會更新；在支援該平台之前建置的安裝需手動替換一次。

無需登入帳號或設定裝置。

首次安裝 Agent 本體（二進位檔案、私有設定和系統自動啟動）時，優先使用 remote-agent install / remote-agent uninstall ，適用於 Linux、macOS 和 Windows，參見 platforms.md。 該命令不需要網路訪問；配對仍需單獨完成。包含 install 的二進位檔案在機器上安裝一次後，後續升級可以使用 update self ，或在支援的平臺上使用自動更新。

--check 優先讀取清單中的執行檔 SHA-256，無需下載完整封存檔；清單缺少執行檔中繼資料時才下載驗證。雜湊比較能區分版本號相同的開發建置，檢查不會修改安裝。安裝前拒絕降級，並核對執行檔版本、大小和雜湊。

預設來源是 https://r2.ivjn.us （託管 downloads/的 R2 公共域名）。 --source https://your-mirror.example/releases 用於選擇可信映象，映象需提供相同的 downloads/manifest.json 和歸檔佈局。GitHub Releases (mbcc2006/remote-control releases) 作為額外的下載渠道釋出同類桌面歸檔包；它們不會替代網站佈局，自更新仍使用 r2.ivjn.us ，除非將 --source 指向提供 downloads/manifest.json 的映象。僅接受 HTTPS，拒絕重新導向，不傳送帳號令牌。系統根據當前作業系統和架構選擇歸檔名稱，按照 HTTPS 清單校驗其大小和 SHA-256，並僅提取準確匹配的可執行檔案條目。桌面用戶端先用內建 Ed25519 公鑰驗證 downloads/manifest.json.sig，再信任清單。缺少簽名、內容遭竄改或未知金鑰都會拒絕更新。鏡像必須提供原樣的已簽名清單與簽名檔；啟用強制驗證的用戶端前先發佈簽名檔。

安裝前，新可執行檔案必須透過有時間限制的 --version 檢查。更新透過同目錄中的 .update.lock 檔案序列執行，並重新檢查當前可執行檔案以檢測併發替換。更新只修改可執行檔案及其更新/備份檔案；裝置 ID、憑證和設定檔案均會保留。

在 macOS 上，下載的可執行檔案還必須先透過 codesign --verify --strict ，再檢查版本。替換時保留髮布時的簽名和位元組，使後續雜湊比較保持穩定。

舊可執行檔案保留為 <executable>.previous。 必要時，停止 Agent 並將該檔案恢復到原可執行檔案路徑。在 Windows 上，安裝替換檔案前會將正在載入的可執行檔案重新命名為備份；安裝失敗時會恢復原名稱。

成功執行 remote-agent update self（非 --check）後，更新器會嘗試重新啟動正在執行的 Agent 以載入新程式：Linux（glibc 與 musl）上依序執行 systemctl restart remote-agent、systemctl --user restart remote-agent，存在 /etc/init.d/remote-agent 時再執行 rc-service remote-agent restart（OpenRC），都無法使用時以原參數 SIGTERM 重新啟動其他 remote-agent 常駐程式；Windows（x64 與 arm64）上重新啟動排程工作 RemoteAgent，並有處理程序層級的備援；FreeBSD/NetBSD 上執行 remote-agent install --system 安裝的 rc.d 指令碼 remote_agent restart，沒有時提示需手動重新啟動。若執行更新的處理程序本身就是常駐程式（參數不是 update self），Unix 上會 exec 新程式（保留 PID 供服務管理員使用），Windows 上會啟動一個分離的替代處理程序。remote-cli update self 不會重新啟動 Agent。狀態列會說明重新啟動使用了 systemd、OpenRC、rc.d、排程工作、新啟動的處理程序，或未能重新啟動（更新本身仍然成功）。請以安裝擁有者的權限執行；更新器不會提升權限。重新啟動時記錄的命令列會隱藏 --token 的值。如果舊的 Windows Agent 仍在從備份檔執行，請先重新啟動它再更新。

自動更新（桌面 Agent 守護程序）

當 Agent 守護程序執行時（非單次 update self），它會定期檢查相同的網站清單，並在釋出的 remote-agent 二進位檔案不同時應用更新（透過雜湊比較）。預設行為：

• 在支援的桌面建置上預設啟用（Windows x64/arm64 / Linux x64/arm64 glibc 與 musl / macOS arm64 / FreeBSD 與 NetBSD x64/arm64）。
• 可透過環境變數 REMOTE_AUTO_UPDATE=0 （也接受 false / no / off）、JSON 設定 "auto_update": false，或 CLI 引數 --auto-update false 禁用。
• 啟動約 90 秒後首次檢查；之後約每 12 小時檢查一次（並非每次心跳都檢查）。
• 清楚記錄進度；絕不向更新 CDN 傳送裝置令牌。
• OpenWrt（包括在 OpenWrt 主機上執行的 musl 套件）會跳過桌面自動更新；Android 使用自己的 OTA 路徑。Intel Mac、32 位元 ARM 等未對應的架構會返回無發布套件錯誤，不能自動升級。

遠端下發更新（操作員 → 裝置）

擁有普通裝置會話的操作員（ACL 與 OpenExec相同）可以要求線上裝置檢查或應用更新：

協議（WebSocket JSON）：

• OperatorUp::update_device { session_id, device_id, check_only, source? }
• Exchange → DeviceDown::update_req
• 裝置 → 持續返回 DeviceUp::update_status / OperatorDown::update_status ，包含 phase： checking | downloading | applying | up_to_date | available | applied | error

控制台：在裝置詳情中選擇 檢查更新 / 下發更新。

CLI（與其他裝置會話操作方式相同）：

remote-cli device update <device_id> --check
remote-cli device update <device_id>
remote-cli device update <device_id> --source https://r2.ivjn.us

啟用 LAN 時，區域網控制對 update_device 的對映方式與其他 OperatorUp open-* 訊息相同。

OpenWrt 和其他不支援的 Agent 會返回明確的 error 階段，而不會安裝錯誤的產物。Windows arm64、Linux musl、macOS Apple Silicon 與 FreeBSD/NetBSD 使用與 Windows x64、Linux glibc 相同的桌面封存路徑。

Android Agent OTA

Android Agent APK（remote-agent-android.apk 位於網站上）可以透過同一 HTTPS 清單更新自身：

在 Agent 中開啟 Settings / 設定 → 檢查更新 手動檢查。檢查會下載並驗證 APK；發現更新後，還需單獨確認才會開啟 Android 安裝器。

• 下載 APK，驗證位元組大小與 sha256，將 versionCode 和包名與已安裝應用比較（版本相同但雜湊不同的重新建置仍可能安裝）。
• 透過 PackageInstaller 安裝。應用宣告瞭 REQUEST_INSTALL_PACKAGES；首次 OTA 時，使用者可能需要在系統設定中允許 Remote Agent“安裝未知應用”，並在系統安裝器介面出現時確認。
• 開始安裝會返回 available 和等待安裝的訊息，而非 applied。 私有安裝器回撥會開啟系統確認介面。對同一個待安裝 APK 的重複請求會複用會話；失敗和過期的自更新會話會被放棄。Agent 重新連線後，請確認已安裝的版本和雜湊。
• 當 AgentService 執行時，自動檢查會以類似間隔執行。
• 遠端 update_req 由原生 Agent 處理，並呼叫 APK 控制橋 （action: ota_update）。
• 替換安裝包時會保留應用私有儲存（裝置 ID / 令牌）； MY_PACKAGE_REPLACED 在啟用時仍會重啟連線。

所有元件統一使用發布版本 0.1.27：Rust Agent/CLI/Exchange、瀏覽器擴充功能、Android 應用程式和 Web 控制台。後續一起遞增版本，Android versionCode 為 30。打包前執行 python scripts/check-release-versions.py。

Android 控制台更新

原生控制台有獨立的設定 → 檢查更新按鈕，登入前後均可使用。它不攜帶帳號憑證讀取公開網站清單，並將已安裝建置與釋出的 versionCode 比較。如果清單不包含建置後設資料且對外展示的版本一致，它會提供下載，而不會聲稱已安裝應用是最新版本。

下載安裝包會在瀏覽器中開啟網站 APK；請透過 Android 的確認介面完成安裝。該操作更新當前手機上的控制台。裝置詳情頁的更新控制元件仍針對相應的遠端裝置。

控制台“檢查更新”（合併流程）

裝置詳情只保留一個“檢查更新”操作：先發 update_device { check_only: true }；

• up_to_date → 顯示“已是最新版本 x.y.z”；
• available → 顯示“當前 → 最新（大小）”，使用者選擇“下發更新 / 稍後”，確認後發 check_only: false 並顯示進度與結果；
• Android 下發後返回 “Installation pending …” 時提示在裝置上確認系統安裝；
• 裝置離線、瀏覽器裝置直接給出原因；平臺不支援時顯示“此裝置不支援遠端更新”。 結果訊息附帶 current <版本> 和 size <字节> bytes。

另請參閱倉庫中的 docs/watchdog.md ，瞭解可選的存活監視程式 （--watchdog、REMOTE_WATCHDOG=1）。

Android 診斷頁獨立顯示最近一次自動更新結果與時間，不依賴 READ_LOGS 權限。固定原因區分 HTTP 狀態、DNS、逾時、TLS、清單、APK 大小/雜湊及安裝權限失敗。同一安全訊息以 RemoteAgentOTA 標籤寫入 logcat；完整裝置日誌仍要求 READ_LOGS。狀態不會複製例外中的 URL、路徑或憑證。