本版已被 design-v1.4.md 取代（A4／A5／A6 合併成一張卡，設計內容不變）。此檔凍結不改。

FR-193 設計 v1.3（已被 v1.4 取代）

整案一句話：Agent 被掃主機上的 Docker 引擎改成普通帳號 guidant 執行，三顆容器全由它開；客戶照常 sudo ./install.sh，多出來的主機設定全由安裝程式做。

依賴：決策者功課只有一件——A0 需要一台乾淨 Ubuntu 24.04 VM（有 TPM 2.0、能連 DEV 主系統）。主系統那套之後開 FR-193.1，照這份的做法抄。

2.1 三層身分

2.2 現況接入點盤點

3.1 主機準備層 lib/rootless_host.sh（A1）

install.sh 第①步環境檢查之後、寫設定之前呼叫 rootless_host_prepare，冪等，重跑無害。

1. 前提：stat -fc %T /sys/fs/cgroup 要 cgroup2fs；systemctl --version 有輸出；uname -r ≥ 5.11。任一不符 check_fail。
2. Docker 四段式（D8）：先辨識來源——dpkg -s docker-ce／rpm -q docker-ce 有＝官方；dpkg -s docker.io、podman-docker 有＝發行版自帶。①沒有 docker → 從包 debs/docker/<目標>/ 裝（deb 用 dpkg -i 加 apt-get -f，el-9 把目錄當本機 repo 給 dnf）。②官方且 Server.Version ≥ MIN_DOCKER_MAJOR → 只補 docker-ce-rootless-extras、uidmap、slirp4netns、dbus-user-session。③官方但太舊 → fail 印「請自行升級或移除後重跑」。④發行版自帶 → docker ps -aq 與 docker volume ls -q 都空 → 印一行「移除發行版自帶 docker.io，改裝官方 Docker Engine」後 apt-get remove -y docker.io docker-compose docker-doc（el：podman-docker），接①；任一非空 → fail 印出容器與 volume 清單，請客戶確認後自行移除再重跑。裝完 systemctl disable --now docker.service docker.socket containerd.service（containerd 是獨立單元，不停會留一支 root 行程）。
3. 帳號（D5）：GUIDANT_RUN_USER 預設 guidant。不存在 → useradd --system --create-home --shell nologin。不論新建或既有都查 subuid：Ubuntu 24.04 的 useradd --system 不配，且 usermod 不檢查重疊。沒有就補，起點＝/etc/subuid 與 /etc/subgid 所有區段 start+count 的最大值（存在 → 同樣檢查、shell 是否 nologin（否則 warn 不改）、是否在 sudo／wheel 群組（是則 fail）。
4. linger：loginctl enable-linger。
5. sysctl：寫 /etc/sysctl.d/90-guidant-rootless.conf 一行 net.ipv4.ping_group_range = 0 2147483647，sysctl --system。
6. cgroup 委派：寫 /etc/systemd/system/user@.service.d/delegate.conf（Delegate=cpu cpuset io memory pids），daemon-reload；user manager 已在跑的話 systemctl restart user@<uid>.service，等 socket 回應（最多約 30 秒）。不能只 terminate-user，linger 不會把它拉回來。
7. 啟用 rootless：machinectl shell guidant@ /bin/bash -c 'XDG_RUNTIME_DIR=/run/user/$(id -u) dockerd-rootless-setuptool.sh install && systemctl --user enable docker'。沒有 machinectl 就裝 systemd-container。
8. 驗：machinectl shell 不回傳內層結束碼，成敗只看這一步。以 docker info --format '{{.SecurityOptions}} {{.CgroupDriver}}' 要含 rootless 與 systemd，否則 fail。

3.2 docker 指到 guidant 的 daemon（A3、D9、D10）

install.sh 開頭（讀到 GUIDANT_RUN_USER 之後）：

RUN_UID="$(id -u "$GUIDANT_RUN_USER")"
export DOCKER_HOST="unix:///run/user/${RUN_UID}/docker.sock"

之後所有 docker、dc() 原樣可用，不必逐行改。維運入口與三支升級單元是另外的行程，各自要拿到同一個值：維運入口在同一段讀安裝紀錄後 export；單元檔加 Environment=DOCKER_HOST=…（安裝時代入 uid）。守衛 scripts/install/check_docker_host.sh：每支會被獨立執行的入口都要有這一行 export。

主機副本（D10）：/usr/local/lib/guidant-agent/install-lib/，root 755。首裝在映像驗完完整性後存一份；升級在 verify_new_image_tree 通過後換上新版。所有 source <(image_read_file … install-lib/…) 改讀這份。既有的 /usr/local/lib/guidant-agent-secrets 與 guidant-agent-upgrade 併進同一個目錄。

3.3 uid 換算 lib/subuid_map.sh（A4）

subuid_base() { awk -F: -v u="$GUIDANT_RUN_USER" '$1==u{print $2; exit}' /etc/subuid; }
host_uid_for() { echo $(( $(subuid_base) + $1 )); }   # host_uid_for 1000 → 101000

rootless 的對映是 0 → guidant 本人、N → 起點 + N − 1（N≥1）。主機側六處走換算：_storage_key_owner、prepare_agent_host_paths 的 product_uuid／content/cache／factory-defaults.env、upgrade/agent-order、AGENT_UID 常數本身。product_uuid 設 guidant:<容器 1000 的主機 uid> 0440，服務與 fingerprint 子命令（容器內 uid 0）才都讀得到；只設群組的話兩邊算出不同指紋，主系統會多一台陌生 Agent 且沒有任何錯誤。容器內以 -u 0 跑的 chown 1000 不改（容器裡看到的仍是 1000）。重跑 install.sh 不得把擁有者蓋回 1000。

3.4 升級單元（A5、D6）

三支單元維持 User=root。Wants=docker.service 與 After=docker.service 都改成 user@<uid>.service（留著 Wants=docker.service 會在升級單觸發時把 root Docker 拉起來）；secrets 單元的 Before=docker.service 同樣改。單元檔帶 Environment=DOCKER_HOST=…。staging 目錄仍 root 700，解包、驗簽在 root 做完才 docker load。升級腳本偵測到容器屬於 root Docker 時停下，印「本版起改 rootless，請 uninstall 後重新安裝」（D7）。

3.5 出貨包（A2）

fetch_docker_debs.sh 照 fetch_tpm2_debs.sh：同一組目標 ubuntu-22.04 ubuntu-24.04 debian-12 el-9，在對應版本最精簡容器加 Docker 官方 repo 後 apt-get install --download-only／dnf download --resolve，輸出 debs/docker/<目標>/。釘版寫在腳本頂部一個變數，bump 走 commit。平台固定 linux/amd64。

• 主系統那套（對外改 8443、四支單元、資料庫目錄 owner）→ FR-193.1，等 Agent 這輪踩完坑再開。
• 容器內任何改動、image 重打（FR-180 的成果沿用）。
• 多 Agent 同主機、非 x86_64。
• pasta 驅動切換（A0 量出吞吐不夠才開卡）。

批＝可同時開 session 的一組；階段＝給 PM 看的分組。A1 到 A6 都在同一台 VM（192）上實測、都改 deploy/install.sh，所以除了 A1／A2、A5／A6 兩組之外一張一批。A0 已完成。由 handoff/cards.py 產生並驗過依賴與撞檔。A8 在 BE repo（資安報告），其餘在 Agent repo。

1. 拿 A2 出的真包，乾淨 Ubuntu 24.04 與 Debian 12 各一台（有 TPM），sudo ./install.sh 到底，中間不手動介入。
2. scripts/build/audit_nonroot_stack.sh --agent 全 ✔；ps -eo user,comm | grep -E 'dockerd|containerd' 無 root。
3. 手冊第 5 節十二項逐項過。
4. 主系統核准 Agent → 派一次掃描 → 收到結果；網路診斷 ping／traceroute／mtu 三項有值。
5. 主系統發 Agent 更新 → 新版起來；中途拔電重開 → boot-check 退回舊版。
6. uninstall 後 grep guidant /etc/passwd /etc/subuid 空、sysctl 回預設、無 dockerd。

v1.3（相對 v1.2）

A0 在乾淨 Ubuntu 24.04 實測後修正五處，證據在 evidence/agent-rootless-probe.md。

• D9 新增：docker 呼叫改成 root CLI 加 DOCKER_HOST。v1.2 的 sudo -u guidant 實測讓 install.sh 三個基本動作失敗。連帶 /run/guidant-agent 不必開放給 guidant。
• D10 新增：維運程式改讀主機副本，不從 guidant 的映像庫取來以 root 執行。
• D11 新增：NET_RAW 保留、加容器 sysctl。v1.2 寫「拿掉 NET_RAW」實測連 ping 都起不來；traceroute -I 不必改。
• §3.3 換算公式：起點 + N − 1，不是 起點 + N；換算點從三處變六處（v1.2 漏了 prepare_agent_host_paths）。
• §3.1、§3.4：containerd 一起停、子 uid 起點自己算、委派後重起 user manager 並等 socket、Wants=docker.service 也要換。

卡仍是十張，批從六變七：A3 與 A4 都改 deploy/install.sh 且共用同一台 VM，拆成前後兩批。A3、A4、A5、A6 的做法改寫；A1 到 A6 的驗收改成「把改過的檔換進 192 上解開的包」，不必每張卡出一次包；A9 的測試包由決策者出。

v1.2（相對 v1.1）

新增 D8 發行版自帶 Docker 的處理。決策者 2026-11-10 問「Ubuntu 內建的會不會移除」，首腦查到 v1.1 的三段式會讓裝了 docker.io 的主機撞牆：版本號過門檻被判「沿用」，但 docker.io 沒有 rootless 附加套件、與官方 extras 互斥。改四段式：發行版自帶且沒有容器沒有 volume 就移除換官方組，有就停下列清單。改到 §1 D8、§3.1 第 2 步、§6 A1 驗收；卡的批次不變。

v1.1（相對 v1.0）

只改 D1。PM 2026-11-10 裁示：主系統對外一律 8443，不走「預設 443 貼能力、客戶可切」的路三。理由是產品還沒出給客戶，改預設沒有相容成本；省下 rootlesskit capability 的升級重貼與主機掃描報告解釋。

這條只影響主系統（FR-193.1），Agent 這輪十張卡的內容與批次完全不變。FR-193.1 開卡時要涵蓋：