檢測 Agent 原生安裝包 設計定案

狀態：設計定案・待實作（D1–D9 已拍板；Q1–Q4 為實作期查證項）｜建立日期：2026-08-18 前作：FR-063 Nuitka 落地版打包 design（build 管線／私房 wheel／resource_path 慣例）／FR-064 防竄改偵測 design（manifest 簽章泛用層）／FR-065 落地版 Installer design（install.sh 七步結構／維運子命令） 討論稿（唯一內容真相源，D1–D9 拍板脈絡與被排除方案全文）：discussion.html

這節不需要任何技術背景就讀得懂。工程細節從下一節起。

這案在做什麼：檢測 Agent 是我們派駐在客戶機房、替我們去做掃描的小程式。它原本包在 docker 容器裡出貨（容器＝一個跟外界隔開的獨立小房間）。但 Agent 的工作就是量測它所在 的那台機器，隔著這層隔離會讀不到硬體身分、或每次重啟讀到的值都不一樣——這件事已經 真的出過事（系統認不得同一台機器）。本案把它改成直接裝進機器裡，就像同業的掃描 Agent （Nessus、Qualys、Wazuh）一貫的做法。

為什麼值得做（三個實際好處）：

1. 身分不會漂——機器識別碼直讀主機，不再靠外掛腳本從外面抄值硬撐
2. 客戶不必先會 docker——解開一顆包、跑安裝腳本、回答三個問題就好
3. 封閉機房也能裝——掃描工具全部隨包附上，安裝過程不必連外網下載任何東西

順帶做掉的：客戶端少一個資料庫服務、少一個網路轉發服務要維運（都省成 Agent 自己承接）， 以及防偽章——出貨前逐個檔案蓋章，有人動過包裡任何檔案，Agent 就拒絕啟動。

影響哪些畫面／操作：產品畫面完全不變。這是交付形態的改造，客戶端的變化是「裝的 方式不同了」；雲端後台看到的 Agent 清單、派工、報告全部照舊。唯一要注意的是：改了機器 身分的算法，既有已開通的 Agent 指紋會變、需要重新開通一次（決策 D11，當時存量最少、 最便宜）。

拍板了什麼（決策 D1–D19 的白話版，完整理由見 §3）：

現在到哪了：母卡 CM-1284 已於 2026-08-23 收案，compose 版已隨產品出貨。 各子需求「怎麼親手驗它做完了」見下一節的分工概述表。

1.1 背景：容器裡的 Agent 量不到宿主

檢測 Agent（evidence-agent，獨立 repo ~/Projects/Billows/Audit-Manager/evidence-agent，v0.2.27，Flask + dependency-injector）目前唯一交付形式是 docker image（python:3.11-slim）＋三容器 compose（agent 本體＋agent-db postgres:16＋nginx mTLS sidecar），出貨走 docker save / docker load。

但 agent 的本職是量測宿主機——機器指紋要讀 /sys/class/dmi/id/product_uuid、/etc/machine-id、主網卡 MAC，這些在容器裡讀不到或會漂移（已發生 Debian base image /etc/machine-id 空檔退回隨機 MAC 的指紋漂移事故），現行靠 deploy/collect-host-id.sh workaround 從宿主抽值塞進容器硬撐。業界同類產品（Nessus / Qualys / Wazuh / Elastic / Datadog Agent）全部以原生套件（deb/rpm/tarball）＋ systemd 服務交付——貼宿主量測的產品，原生安裝就是行規。

FR-065（產品落地 installer）期間決策者裁定：agent 安裝包另起新 FR、非 docker，即本案。

1.2 本案目標

• Agent 做成 Nuitka standalone 編譯（把 Python 程式編成機器碼、原始碼不可見）的 tarball 安裝包
• install.sh 一鍵安裝為 Linux systemd 服務
• 外部檢測工具全包在同一顆 tarball，離線（封閉網路）完全自足
• Windows 不實作，只出評估文件與前提清單

1.3 前作可複用資產

1.4 端到端安裝時序

客戶側從解 tarball 到心跳上線，mTLS（雙向 TLS 認證）全自動、客戶零 openssl 操作：

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
    participant OP as 客戶操作者
    participant IS as install.sh
    participant SD as systemd
    participant AG as guidant-agent 服務
    participant CL as 雲端產品（FR-065 已含 PKI）
    OP->>IS: 解 tarball、執行 install.sh
    IS->>IS: 七步：前置檢查→驗 manifest 簽章→落檔 versions/<ver>→裝 bundle 工具→建 symlink→裝 systemd unit→啟動
    IS->>OP: 互動問答三題（雲端位址／註冊 token／本機對外位址）
    IS->>IS: 生成 /etc/guidant-agent/agent.env
    IS->>SD: systemctl enable --now guidant-agent
    SD->>AG: 啟動（啟動時驗 manifest 簽章）
    AG->>AG: 直讀宿主指紋（product_uuid / machine-id / MAC）
    AG->>CL: enroll：產 keypair＋CSR（SAN=本機位址）＋token 註冊
    CL-->>AG: CA 簽回 client 憑證＋8443 server 憑證
    AG->>AG: 憑證存 cert_dir，gunicorn/ssl 自起 8443 資料面
    loop 心跳
        AG->>CL: mTLS 心跳（404 → 自動重註冊）
    end

本節寫給決策者與非工程讀者：每個大項在做什麼、產出是什麼、以及你要怎麼親手判定它完成了。工程細節從 §3 起。

整案一句話：把檢測 Agent 從「docker 三容器出貨」改成「Nuitka 編譯＋外部工具全包的一顆 tarball，install.sh 一鍵裝成 Linux systemd 服務」——宿主指紋直讀、SQLite 取代 PG、agent 自起 TLS 取代 nginx sidecar、build 期 manifest 簽章＋啟動驗章。

依賴一句：.1 → .2 → .3 串行（build 產物是打包的輸入、打包產物是安裝的輸入），.4 收口；與 FR-063/064/065 不同，本案各階段產物互為輸入，無平行空間。.6 依賴 .1 編譯產物，與 .4 收口平行；.5 暫緩最後做。

九項全部已由決策者拍板；每項含定案理由與被排除方案（全文脈絡見討論稿 §2）。

D11 實作註（T-6.1 落地，2026-08-21）——兩則都是實測才現形、且都「看起來已經做對了」：

① 撞號守門的豁免條件必須是「憑 agent_uid 認出來的」，不是「resolve 到同一列」。 BE _resolve_agent 在 agent 沒帶 uid 時會退用指紋去重，於是複製出來的機器必然 resolve 到被撞的那一列、uid 自然相等——守門若比對 resolved.uid 就會判定「就是它 自己」而放行。首版即如此，實測（DEV 真打 register）回 HTTP 200 且原機那一列的 base_url 被複製品覆寫，正是本守門要防的情境。指紋 fallback 這條路徑就是複製品會走 的，拿它當「同一台」的證據等於把守門前提交給攻擊面本身。已改為 _resolve_agent 回傳 (entity, matched_by_uid)，只豁免前者。

② 指紋演算法一改，--upgrade 必須一併更新 guidant-agent-ctl。 該檔是安裝當下 複製出去的獨立腳本（讓客戶刪掉 2GB 安裝包後仍能用 status／logs），升級只換 /opt 下的 程式、不會動它。其 fingerprint 子命令是 agent 演算法的 shell 複刻，版本不一致 就印出另一個值——而那正是客戶要抄去雲端開通的那串。123 真機實撞：服務報二源值、舊 ctl 報三源值。原有的「與執行中服務對帳」機制有出聲（正是這樣抓到的），但它在服務沒 跑時（開通前，恰是 fingerprint 的主要使用時機）無從對帳，故不能當解法。

共同教訓：凡是「同一套邏輯存在兩份實作」（Python↔︎shell 複刻、演算法↔︎守門豁免）， 改一邊就要指名另一邊，且要對真端點／真機各跑一次——單元層 fixture 會繞過真實 解析路徑（本例即因 fixture 直餵 resolved=None 而漏掉 ①）。 | D12 | 雙形態支援矩陣 | compose 版＝Linux 有 docker 環境首選（含 SeaweedFS 全套）；原生 tarball＝封閉網路／無 docker／未來 Windows 路線。兩版共用同一顆 Nuitka 產物與同一套簽章，build_all 加 compose 打包出口，不開第二條產線 | —（雙產線＝雙倍 QA/出貨負擔，違背單一產物精神） | | D13 | 產品端「使用 Agent 服務」 | ＝FR-039 既有功能，BE/FE 零新功能。雲端儲存設備設定頁本就有該選項（storage config 指 agent base_url/agent_uid → RemoteAgentAdapter → agent blob API → agent 依自身 STORAGE_TYPE 落地）。本案只做 agent 端：內建 SeaweedFS 預設接上＋自有後端 env 設定＋驗收既有鏈在新編譯 agent 上仍通 | —（在 BE/FE 另做新儲存選項＝重複造輪子，鏈路早已存在） | | D14 | 自有儲存後端的設定介面 | 本地 CLI 先做（T-6.5）：agent 加 configure-storage 維運子命令——secret 不離機、連通驗證當場做、量級小且是 web 下發的必要兜底（下發失敗／無雲端連線時的現場設定路徑）。web 設定下發開獨立評估卡給 PM 排優先度（前置資安題：客戶儲存憑證入雲端 DB 是否可接受） | 直接做 web 下發（三端成本＋secret 治理題未決，不該擋住立即可用的 CLI） | | D15 | compose 版交付形態 | 配互動安裝程式（T-6.6），照主產品 FR-065 installer 同款模式：環境檢查→載 image→問答→生成設定→起服務→維運子命令。受眾是一線工程師/業務，不假設會 docker；SeaweedFS 憑證自動生成不讓客戶發明密碼 | 手填 .env＋docker compose up（T-6.3 首版形態——僅適合熟 docker 者，不符落地版交付受眾） | | D16 | 出貨形態收斂（2026-08-22） | 原生 tarball 版暫不出貨——現階段對客戶出貨一律 compose 版。原生開發成果（.1~.3 全部產物與腳本）保留不廢，何時解凍等商務需求（封閉網路／無 docker 客戶出現時）。連動：T-4.1（原生乾淨機＋斷網驗收）暫緩；T-4.2 手冊改 compose 為主、原生降附錄。同日另一裁示（CM-1335）：compose 交付包廢除 install/upgrade 兩包制、收斂一顆通吃（兩包只差 82MB seaweedfs image，維護兩條路不值；客戶端以「本機已有該 image」為升級放行條件）。⚠️ 遺留：斷網封閉網路驗證至今無人跑過（D3 立案根基）——若 compose 版也出給封閉網路客戶，此驗證應轉移到 compose 版做，不隨原生凍結 | 雙形態同時出貨（D12 原案）：原生版每出一版都要 QA 兩形態，現階段無原生需求客戶，QA 成本無對價 | | D17 | Windows 支援路線（2026-08-22） | docker（Docker Desktop）路線先行，原生 Windows 版暫不討論（T-4.3 評估為據）。承載選 Docker Desktop（決策者定案）：安裝體驗是「裝一個 Windows 軟體」，客戶不碰 Linux 層；其商用授權（>250 人或年營收 >$10M 組織需付費訂閱）為客戶側前置條件，寫入指引與售前須知。指紋風險接受度（決策者裁示）：WSL/Docker Desktop 重置後指紋漂移＝可接受的維運事件，處理＝log 記錄＋「重置後重新開通」SOP，不做 host 值注入 workaround（維持 D9/D11 立場）。安裝程式出 install.ps1（PowerShell 互動版，與 D15「不假設客戶會 docker」同一受眾邏輯——也不假設會 Linux 終端）；交付物＝同一顆 onepack 包（一個位元組不改）＋install.ps1＋薄前置指引。setup.exe 安裝精靈記為 PM 反饋觸發的升級項（不做的理由：SmartScreen 攔無簽章 exe，消警告需買 OV/EV code signing 憑證——docker 路線本已繞開此成本，不為包裝形式請回來）⚠️ 2026-08-23 D18 修訂：Docker Desktop 降 demo/PoC 限定（T-7.1 實測登出全滅），出貨路線改 FR-066.8 原生版；T-7.2/T-7.3 降級為 demo 支援用途。 | ①WSL2＋docker engine（免授權費但客戶要自管 WSL，違背交付受眾設定）②路線甲「客戶在 WSL 終端跑現有 install.sh」（零開發但要求客戶進 Linux 世界，與 D15 受眾邏輯矛盾）③首版就做 setup.exe（SmartScreen＋憑證成本） | | D18 | Windows 出貨路線定案（2026-08-23） | 原生 Windows 服務版（FR-066.8）為 Windows 唯一出貨路線。依據：T-7.1 實測證實 Docker Desktop 登出後 engine 全滅、SYSTEM 排程與 com.docker.service 兩條無登入自起路徑皆失敗（probe §8，P0）——「常駐」與「綁登入 session」本質矛盾，Docker Desktop 降為 demo/PoC 限定（有人值守場景仍可用，T-7.1 已驗全鏈通）。B 案（WSL2＋docker engine＋排程器常駐）否決：常駐機制未驗、四層架構（Windows→排程器→WSL→docker→容器）查修成本高、指紋仍是 VM 值、產出對原生版零複用——demo 用不到（A 夠）、出貨不如 C，兩頭不沾。Code signing 階段策略（行規=B2B agent 類幾乎全簽，但按階段投入）：現階段（Windows 客戶數 0）不買憑證——manifest 簽章（自有鑰）照做、SmartScreen 靠客戶 IT 白名單（GPO/AppLocker）指引承接，與客群（封閉網路、IT 管控）相容；第一個正式 Windows 客戶在望即買 OV（年費數百美金級，含數週申請＋信譽爬升期，不可等簽約後）；大客戶臨時需求買 EV（免爬升）。年費列為 Windows 版固定成本讓售前/PM 知情 | ①Docker Desktop 出貨（登出全滅 P0 無解）②B 案（見上）③現在就買憑證（為未驗證市場預付訂閱）④Azure Trusted Signing（台灣組織不可申請） | | D19 | Windows 線凍結（2026-08-23，PM 拍板） | FR-065/FR-066 不再探討 Windows 安裝，先以 Linux 為主；客戶真有需求再開卡。決策鏈收束：A（Docker Desktop）＝demo/有人值守可用但出貨不可（T-7.1 登出全滅）；B（WSL+engine 常駐）＝T-7.4 實測判死——WSL VM 閒置約 60 秒凍結整個 distro userspace（SYSTEM 帳戶被硬拒、S4U 可跑但照凍、vmIdleTimeout=-1 無效、distro 內 anchor 連坐被凍、外部 watchdog 只能做到「每分鐘重開機」會腰斬檢測任務），死因＝WSL VM 生命週期需要 Windows 側永不退出的進程握持，而該進程的正規形態就是 Windows 服務——推導出唯一活路 C（原生版）；C 需第二個編譯出口（Windows build 機＋MSVC），PM 裁示此投資等客戶訊號。凍結時保留資產：T-4.3 評估、T-7.1/T-7.4 兩份實測紀錄、FR-066.8 卡樹（CM-1340~1345 暫緩）；解凍首步＝build 機佈建。Windows 掃描需求的現行解答＝Linux agent 走 CINC WinRM 遠端掃（既有功能） | ①續投 B 唯一殘存路線（WinSW 握 wsl.exe——工同 C 的 T-8.3、換到六層架構、對 C 零複用）②Hyper-V appliance（等同要求客戶出一台 Linux，非解法）③立即投 C（PM：build 產線投資等客戶訊號） |

D8 附錄：Windows 可行性初判（2026-08-18 口頭討論）

性質：決策者 2026-08-18 口頭討論確認的初判，非定案——定案要等 T-4.3 正式查證。此節作為 T-4.3 評估文件的起點素材。

核心結論：本案技術路線（Nuitka＋SQLite＋paramiko＋環境變數設定）每一項都恰好沒堵死 Windows 的路；原生路線在 Windows 反而比 docker 路線順（免 Docker Desktop 企業授權）。粗估 Windows 版工作量約 Linux 版 40–60%（源碼層幾乎共用）。

分層可行性表：

工具鏈逐項：CINC Auditor 有 Windows msi ✅／sonar-scanner 有 windows-x64 zip（自帶 JRE）✅／git 有 portable 版 ✅／LibreOffice 有 Windows 版（離線佈署形式待查）🟡／xsltproc 無原生、可改用 Python lxml 取代（反而更乾淨）🟡／SSH 掃描走 paramiko 純 Python ✅。工具面無死路，但每項都要重做一次離線化整備。

待 T-4.3 正式查證項：LibreOffice Windows 離線佈署形式、NSSM vs pywin32 原生 service 取捨、code signing 憑證需求與成本、Windows build 機規格。

evidence-agent repo 內每個會被本案觸動的元件，逐項列現況與本案動作：

5.1 FR-066.1　Nuitka build 管線與程式改造

白話：這階段做「讓 agent 能被編成機器碼、且編出來在裸機上跑得起來」的所有程式面工作——它是整案起點，後面的打包（.2）與安裝（.3）都以這裡的 build 產物為輸入。docker 時代靠容器環境撐著的假設（旁邊有一個 PG、版號讀得到 pyproject.toml、__file__ 指得到源碼樹、指紋由 collect-host-id.sh 餵進來）在這一棒全部改掉。

5.1.1 SQLite 化（D2）

• Q2 前置查證先做：掃 jedi-file-upload 的 model 定義與所有查詢，確認無 jsonb / ON CONFLICT 等 PG 方言；有的話評估改寫成本再定落地細節。
• init_db() 的 SQLAlchemy URL 換 sqlite:///<資料目錄>/agent.db；upload_files 表沿用 create(checkfirst=True) 自建，無 migration 體系要搬。
• SQLite 檔落在資料目錄（不在版本目錄，配合 D7 升級模型）。
• agent-db 容器、其在 compose 的編排、對應連線環境變數隨之退場。

5.1.2 程式改造

• version bake：config/config.py 讀 pyproject.toml 取版號的邏輯，改為 build 期把版號 bake 進常數（FR-063 D6 同款手法）——Nuitka 產物內沒有 pyproject.toml。
• resource_path() 三處：inspec.py:145 / nmap.py:101 / config.py:85 的 __file__ 定位改 resource_path() 慣例（FR-063 同款），配合 --include-data-dir 帶入 assets/（nmap.xsl 等）。
• 指紋直讀（D9）：core/fingerprint.py 直讀 /sys/class/dmi/id/product_uuid、/etc/machine-id、主網卡 MAC；廢除 deploy/collect-host-id.sh 與其在部署流程的掛點。
• 工具路徑配置化：connector 內 /usr/bin/* 硬編路徑改為可由環境變數／設定覆寫（預設值指向 install.sh 建立的 bundle 工具 symlink，見 .3）。

5.1.3 agent 版 build_release

• 以 FR-063 scripts/build/build_release.sh 為藍本開 agent 版：dependency-injector 私房 wheel 直接複用 rebuild_wheels.sh；jedi-common / jedi-file-upload 從 Nexus 拉入編進 binary（build 機需可達 Nexus）。
• Q3：EXCLUDE_COMPILE_PKGS 名單依 agent 依賴集合（paramiko / python-gvm / zaproxy / cryptography 等）重評，不照抄 FR-063。
• build 完跑 smoke 驗證：產物在無 Python 環境的裸機（或乾淨容器）啟動、心跳邏輯 dry-run、SQLite 建表成功。

5.2 FR-066.2　tarball 打包與工具 bundle

白話：這階段把「.1 編好的 agent」跟「它工作時要呼叫的所有外部工具」組成一顆客戶拿了就能離線安裝的壓縮包，並在出貨前蓋上防竄改簽章。沒有這一棒，客戶機上要自己裝 CINC、LibreOffice、中文字型……封閉網路根本裝不了；有了它，一顆 tarball 就是完整交付物。

5.2.1 工具 bundle（D3）

• 不 bundle：ZAP / OpenVAS（客戶自備 daemon）、OpenSCAP / Nmap 引擎（裝在目標主機、agent SSH 過去跑，不在 agent 機上）。
• Q4：查證 image 內 openscap-utils / sshpass 是否實際已無用（OpenSCAP connector 已改 paramiko 直連、不用官方 oscap-ssh 腳本）——確認殘留就不搬進 tarball，包更瘦。

5.2.2 manifest 簽章＋啟動驗章（D6）

• 簽章泛用層（FR-064）加 agent_manifest type；gen_integrity_manifest.py 改常數（掃描根目錄／輸出路徑）產逐檔 SHA-256 manifest；sign_manifest.sh 近零改，走 License Center 簽發。
• agent 啟動時以編譯進 binary 的公鑰驗 manifest.sig，逐檔比對；驗章失敗拒絕啟動（瘦身版：不做 runtime 抽查／lockdown）。

5.2.3 build_bundle 打包腳本

• 組 tarball 骨架：agent/（Nuitka 產物）＋tools/（bundle 工具）＋install.sh＋systemd/＋manifest 簽章（雙層，見下）。
• 產出 guidant-agent-<ver>.tar.gz 並附 sha256 檔（交付完整性驗證，FR-065 digest 慣例同款）。
• 實作：evidence-agent scripts/build/build_agent_bundle.sh（打包六步）＋smoke_agent_bundle.sh（六項交付驗證，含 gate 正反例突變測試）。

🔄 落地調整（2026-08-20，T-2.3／CM-1294）：manifest 由單份改雙層。 初版設計是骨架根一份 manifest 涵蓋全部；實作時發現它與啟動 gate 的掃描錨點衝突——gate（T-2.2）讀 binary 所在目錄（agent/）的 manifest.sig 並逐檔比對該樹，而工具樹安裝後散落 /opt/cinc-auditor、/opt/libreoffice25.8、/usr/share/fonts，不在版本目錄、gate 掃不到也不該掃（那些路徑不歸版本目錄管）。單份 manifest 的結果是：gate 在 agent/ 下找不到 sig、路徑也對不上 → 正常包每次啟動必拒。拆成雙層後各管各的：

簽章順序：agent 層先簽（它是交付檔的一部分）→ 骨架全組完 → bundle 層才產 manifest 送簽 → tar。打包腳本有可執行斷言擋順序倒置（bundle manifest 必含 agent/manifest.sig）。兩層同走 LC agent_manifest type、同一把鑰。

連帶兩個配套調整（同 commit a11ccf2）：

• gen_agent_manifest.py 加 --external-symlinks {abort,skip}：工具樹帶指向安裝後路徑的 symlink（CINC binstub、LibreOffice desktop 檔），屬 omnibus／deb 打包形式，tar 原樣保留出貨；bundle 掃描以 skip 略過不收錄（對 build 機上恰好同名的檔算 hash 既無意義也不穩定），dist 掃描維持 abort 原判準。
• startup_gate.py 錨點與 resource_root() 分家（_manifest_root()）：打包模式固定＝binary 所在目錄、不吃 AGENT_RESOURCE_ROOT——驗證錨點可被環境變數改指等於自廢，且 smoke 第 4c 項（拿該變數做 resource_path 反證）會讓簽章產物在 gate 假紅。源碼模式保留覆寫（fake-root 突變測試靠它）。

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart LR
  T["guidant-agent-&lt;ver&gt;.tar.gz<br/>~1GB+（D3 已接受）"]
  T --> A["agent/<br/>Nuitka standalone 產物<br/>自家 code 已編機器碼<br/>＋manifest.json/.sig（agent 層：<br/>啟動 gate 每次啟動全驗）"]
  T --> B["tools/<br/>外部工具 bundle"]
  T --> C["install.sh<br/>七步安裝＋互動問答<br/>upgrade / rollback / 維運子命令"]
  T --> D["manifest.json ＋ manifest.sig<br/>（bundle 層：install.sh 安裝前驗整包，<br/>涵蓋 agent 層 sig 互鎖）<br/>FR-064 泛用層簽章 type=agent_manifest<br/>🔄 雙層拆分見 §5.2.3"]
  T --> E["systemd/<br/>guidant-agent.service<br/>EnvironmentFile=/etc/guidant-agent/agent.env"]
  B --> B1["cinc-auditor（~275MB）<br/>⚖️ 不可換官方 InSpec"]
  B --> B2["sonar-scanner＋JRE（~147MB）"]
  B --> B3["LibreOffice＋fonts-noto-cjk（~400MB+）<br/>形式待 Q1 實測"]
  B --> B4["xsltproc＋nmap.xsl / git"]

出貨側 build 管線（FR-063/064 資產複用點）：

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart LR
  S["evidence-agent 源碼<br/>+ jedi-common / jedi-file-upload<br/>（build 機需可達 Nexus）"] --> W["dependency-injector<br/>私房 wheel<br/>（複用 FR-063 rebuild_wheels.sh）"]
  W --> N["Nuitka standalone 編譯<br/>version bake ＋ resource_path()<br/>--include-data-dir assets/<br/>EXCLUDE 名單重評（Q3）"]
  N --> P["組 tarball 骨架<br/>agent/ + install.sh + systemd/"]
  TB["工具 bundle 下載/整備<br/>CINC / sonar-scanner /<br/>LibreOffice（Q1）/ xsltproc / git"] --> P
  P --> M["gen_integrity_manifest.py<br/>（FR-064 改常數）逐檔 hash"]
  M --> SG["sign_manifest.sh → License Center 簽章<br/>type=agent_manifest（D6）"]
  SG --> OUT["guidant-agent-&lt;ver&gt;.tar.gz<br/>出貨"]

5.3 FR-066.3　install.sh 與 systemd

白話：這階段做客戶手上唯一會碰到的東西——安裝腳本。客戶解開 tarball、跑 install.sh、回答三個問題，agent 就變成一個開機自起、由 systemd 看管的系統服務並自動向雲端註冊上線；日後升級換版、出問題回滾、日常看狀態看 log，也全走同一支腳本的子命令。它吃 .2 的 tarball 當輸入，是 .1/.2 成果對客戶的「出口」。

5.3.1 install.sh 主流程

七步（承 FR-065 七步結構）：前置檢查（root / systemd / 磁碟空間 / amd64；支援 --check-only）→ 驗 manifest 簽章（D6 交付完整性）→ 落檔 /opt/guidant-agent/versions/<ver>/ → 裝 bundle 工具（含 Q1 定案的 LibreOffice 落地形式與 fonts-noto-cjk 字型）→ 建 symlink（current → 版本目錄；工具指令 symlink 供 connector 預設路徑取用）→ 裝 systemd unit（guidant-agent.service，EnvironmentFile=/etc/guidant-agent/agent.env）→ 啟動（systemctl enable --now）。

互動問答三題生成 agent.env（D5）：①雲端位址 ②註冊 token ③本機對外位址（CSR SAN 用）。生成後 agent 首次啟動即走既有 core/enroll.py 自我註冊，並以 gunicorn/ssl 自起 8443 資料面 TLS（D4）——nginx unit／設定完全不存在於交付物。

5.3.2 upgrade / rollback（D7）

• install.sh --upgrade <新tarball>：驗章 → 解進 versions/<新ver>/ → 停服務 → 切 current symlink → 起服務；資料目錄（SQLite 檔、mTLS 憑證、agent.env）不動。
• install.sh --rollback：切回前一版 symlink、重啟。無 DB migration、無備份還原步驟——這是刻意的輕量模型（D7）。

5.3.3 維運子命令

比照 FR-065：status（服務狀態＋版本＋心跳連線）／logs（journalctl 包裝）／uninstall（停服務、移除 unit 與版本目錄；資料目錄詢問後才刪）／fingerprint（印出本機三指紋值，供雲端綁定核對）。

5.4 FR-066.4　驗收與文件

白話：前三棒各自驗過自己，這棒證明「整條路對客戶真的成立」——拿一台從沒裝過任何東西的 Linux 機，只給它一顆 tarball，從安裝到跑完一輪真實檢測任務；再模擬客戶的封閉網路（斷網）環境重來一遍。最後把過程寫成客戶看得懂的安裝手冊，並把 Windows 可不可行的評估寫成文件收口 D8。

• 真機驗收：乾淨 Linux 機（非 build 機、非開發機）→ tarball → install.sh → 心跳上線 → 派一輪實際檢測任務（至少涵蓋一個用到 bundle 工具的 connector，如 CINC）→ 證據回收成功；另驗 upgrade → rollback 一輪。
• 封閉網路驗證：斷外網環境完整重跑安裝與任務（工具 bundle 自足性的最終證明）。
• 客戶安裝手冊：比照 FR-065 T-4.1 手冊體例（安裝／開通／升級／回滾一本通），agent 版另含目標主機前提（OpenSCAP / Nmap 引擎裝在受測機的說明沿用 FR-057/058 setup_guide 內容）。
• Windows 評估文件（D8）：從零寫，覆蓋指紋來源（WMI / registry）、服務形式（Windows Service / NSSM）、工具鏈可用性三題，結論給「可行性＋若做的前提清單」，不承諾時程。

依賴鏈：FR-066.1 → .2 → .3 串行，.4 收口。

FR-066.1　Nuitka build 管線與程式改造 — 依賴：無（起點）

FR-066.2　tarball 打包與工具 bundle — 依賴：FR-066.1（build 產物是輸入）

FR-066.3　install.sh 與 systemd — 依賴：FR-066.2（tarball 是輸入）

FR-066.4　驗收與文件 — 依賴：FR-066.1–.3（收口）

FR-066.5　EL（Rocky/RHEL 9）生態支援（PM 決議暫緩，最後做） — 依賴：FR-066.1–.3（產物與腳本是輸入）；於 .4 收口前完成

FR-066.6　docker compose 形態＋SeaweedFS 內建儲存 — 依賴：FR-066.1（編譯產物是輸入）；與 .4 平行

| T-6.7 | 恢復系統內建 SeaweedFS（出廠快照＋configure-storage 選項） | 安裝生成 SEAWEEDFS 帳密時快照 factory-defaults.env 到資料目錄（600、只含 SEAWEEDFS_* 五項，D7 資料目錄語意跨版本存活）；原生 scripts/install/install.sh 與 compose deploy/install.sh 兩處同步；configure-storage 第一題改四選項（1 系統內建恢復預設／2 自有 SeaweedFS／3 自有 MinIO／4 本機磁碟），選 1 從快照讀回→照舊連通驗證→寫入→重啟、user 零輸入；快照不存在時選項照顯但給明確指引（舊站點已改自有後端補不回，文件註明找原廠）；upgrade 路徑補快照（現行設定仍為內建值時）；「舊檔不搬家」紅字警告在恢復路徑同樣觸發（T-6.5 機制）；deploy README 對齊。主產品對應功能另卡處理 | 原生與 compose 各走一輪「內建→自有→恢復內建」循環，恢復後上傳實落內建 SeaweedFS；快照檔 600；無快照場景指引正確；deb 家族不回歸 | T-6.5, T-6.6 |

FR-066.7　Windows（Docker Desktop）支援 — 依賴：FR-066.6（compose onepack 包是輸入）

⏸ D19（2026-08-23）：本節全卡樹暫緩——PM 拍板 Windows 不再探討；T-7.1/T-7.4 已完成的探路結論保留（見 t71-windows-probe.md／t74-wsl-engine-probe.md）。

FR-066.8　原生 Windows 版 — 依賴：FR-066.1（Nuitka 產物源碼同源）；T-4.3 評估＋T-7.1 實測為規格輸入

⏸ D19（2026-08-23）：本節全卡樹暫緩——PM 拍板 Windows 不再探討；T-7.1/T-7.4 已完成的探路結論保留（見 t71-windows-probe.md／t74-wsl-engine-probe.md）。

開放項歸屬（Q1–Q4）

1. 乾淨 Linux 機（無 Python、無 docker、非 build 機）解 tarball → install.sh 七步全綠 → 互動三題填答 → 服務 active、開機自起。
2. Agent 直讀宿主三指紋（product_uuid / machine-id / MAC）與實機值一致；enroll 全自動拿到 mTLS 憑證；心跳上線、雲端 agent 清單可見。
3. 一輪實際檢測任務跑通：至少含一個吃 bundle 工具的 connector（CINC）＋一個 SSH 遠端型（OpenSCAP）→ 報告回收進證據池；LibreOffice 預覽轉 PDF 中文不缺字。
4. 封閉網路情境：斷外網環境完整重跑 1–3（雲端產品在同內網），無任何步驟需要對外連線。
5. 升級→回滾：--upgrade 新版心跳上報新版號、SQLite 資料與憑證保留；--rollback 後舊版正常服務。
6. 防竄改：竄改任一交付檔後啟動被拒（manifest 驗章生效）。
7. 文件收口：客戶安裝手冊、Windows 評估文件產出。
8. EL 家族：以上 1–3 於 Rocky Linux 9（SELinux enforcing）重跑一輪通過（FR-066.5）。
9. compose 形態：docker 機上 compose 版完成上述 2/3/6 對應項＋「使用 Agent 服務」證據上傳落 SeaweedFS 全鏈通（FR-066.6）。
10. Windows（Docker Desktop）形態：160 真機上 install.ps1 全程問答安裝→enroll 上線→跑一單檢測任務→報告回雲端；重置 Docker Desktop 後照 SOP 重新開通成功（FR-066.7）。
11. 原生 Windows 形態：乾淨 Windows 機 install.ps1 裝成雙服務→登出/重開機服務存活且雲端在線→跑檢測任務→證據落本機 SeaweedFS→升級回滾→防竄改拒起（FR-066.8）。

• 本案標的 repo 是 evidence-agent；主專案（compliance-manager-be）只承載文件與簽章工具鏈的複用來源。
• Q1–Q4 不阻擋開工，但 Q2 是 T-1.1 的前置守門。
• Notion 開卡（母案＋子卡）於派工時依 big-feature-workflow skill Step 4/5 進行，本文件拆分表即開卡依據。