feat(guanghu-os): add cross-root supervisor slice

2026-08-15 23:49:28 +08:00 · 2026-08-15 23:49:28 +08:00 · 9db3ecd2e7
commit 9db3ecd2e7
parent fed0c73b04
10 changed files with 317 additions and 5 deletions
--- a/product-source/hololake-platform/architecture/HOLOLAKE-JD-CROSS-ROOT-GUANGHU-SUPERVISOR-20260815.md
+++ b/product-source/hololake-platform/architecture/HOLOLAKE-JD-CROSS-ROOT-GUANGHU-SUPERVISOR-20260815.md
@ -0,0 +1,13 @@
+# 京东跨根光湖监督实体
+
+> 开发编号：`DEV-20260815-001`
+>
+> 承接：`DEV-20260810-012`
+>
+> 状态：现实工程执行中
+
+目标不是删除 Linux，而是让光湖控制在完整 Linux 根系统之前出现，并跨根切换持续存在；Linux
+内核保留为硬件兼容底座，仓库服务保留为受控数据面，独立 Linux 救援入口继续存在。
+
+当前工程门按顺序关闭：挂根前绑定与失败封门、`/run` 启动周期交接、根内监督进程持续运行、
+仓库桥按需唤醒与收回、真实节点启动回执。每一门只能凭当前目标的执行证据升为 100。
--- a/product-source/hololake-platform/docs/adr/0177-guanghu-cross-root-supervisor-takeover.md
+++ b/product-source/hololake-platform/docs/adr/0177-guanghu-cross-root-supervisor-takeover.md
@ -0,0 +1,27 @@
+---
+type: ADR
+id: "0177"
+title: "Guanghu cross-root supervisor takeover"
+status: accepted
+date: 2026-08-15
+refines: "0176"
+development_id: "DEV-20260815-001"
+---
+
+# 光湖跨根监督接管
+
+## 决定
+
+initramfs 的 `/run` 会被移动到新根系统，因此挂根前监督器留下的启动周期交接可以由根系统中的
+光湖监督实体重新核验。根监督实体必须重新读取实时 DMI、启动 ID、内核标记与根 UUID，确认它们
+和交接完全一致，写入 `ROOT_SUPERVISOR_ACTIVE` 状态并保持运行；失败必须阻断正常系统目标。
+
+生产投影使用早于 `sysinit.target` 的 systemd 单元。隔离验证使用只读最小 ext4 根镜像和静态
+BusyBox，只证明跨 `switch_root` 的连续接管与常驻进程，不把它等同于真实机器部署、完整 Linux
+按需唤醒或最终光湖 OS 主控。
+
+## 否决
+
+- 只把 JSON 文件从 initramfs 带进新根：文件是证据，不是持续运行的监督主体。
+- 让普通 Linux 服务晚于完整用户态再读取交接：不能证明控制连续性。
+- 在隔离根切换验证前修改京东真实启动：风险边界不成立。
--- a/product-source/hololake-platform/guanghu-os/README.md
+++ b/product-source/hololake-platform/guanghu-os/README.md
@ -114,6 +114,16 @@ the node. A Guanghu supervisor still has not been shown to remain alive across
 on-demand Linux subcontrol therefore remain `0`. See ADR-0176 and
 `deployments/JD-FD-PRIMARY/PRE-ROOT-SUPERVISOR-QEMU-RECEIPT-20260815.hldp`.

+## Cross-root Guanghu supervisor source slice
+
+`scripts/guanghu-root-supervisor.sh` revalidates the live machine and the
+boot-scoped pre-root handoff after `/run` moves into the mounted root. It then
+stays resident with `ROOT_SUPERVISOR_ACTIVE`; the systemd projection starts it
+before `sysinit.target`. `scripts/build-guanghu-cross-root-fixture.sh` creates a
+read-only minimal root image for QEMU proof without mounting or modifying a
+host disk. Source availability alone does not raise the JD cross-root or final
+master predicates. See ADR-0177.
+
 ## Language-primary boot target

 `guanghu-language-primary.target` makes the accepted cognitive-control model
--- a/product-source/hololake-platform/guanghu-os/packaging/systemd/guanghu-root-supervisor.service
+++ b/product-source/hololake-platform/guanghu-os/packaging/systemd/guanghu-root-supervisor.service
@ -0,0 +1,20 @@
+[Unit]
+Description=Guanghu cross-root persistent supervisor
+DefaultDependencies=no
+After=systemd-remount-fs.service
+Before=sysinit.target basic.target
+ConditionKernelCommandLine=guanghu.first_boot=1
+
+[Service]
+Type=simple
+ExecStart=/usr/lib/guanghu/guanghu-root-supervisor run
+Restart=on-failure
+RestartSec=2
+UMask=0077
+NoNewPrivileges=true
+ProtectHome=true
+ProtectSystem=strict
+ReadWritePaths=/run/guanghu
+
+[Install]
+WantedBy=sysinit.target
--- a/product-source/hololake-platform/guanghu-os/scripts/build-guanghu-cross-root-fixture.sh
+++ b/product-source/hololake-platform/guanghu-os/scripts/build-guanghu-cross-root-fixture.sh
@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+[[ $# == 3 ]] || {
+  echo 'usage: build-guanghu-cross-root-fixture.sh <output-image> <config> <root-supervisor>' >&2
+  exit 64
+}
+
+output=$(readlink -m "$1")
+config=$(readlink -f "$2")
+supervisor=$(readlink -f "$3")
+root_uuid=$(sed -n 's/^root_uuid=//p' "${config}")
+[[ ${root_uuid} =~ ^[0-9a-f-]{36}$ ]]
+[[ -x /bin/busybox && -x ${supervisor} ]]
+command -v mkfs.ext4 >/dev/null
+
+staging=$(mktemp -d)
+trap 'rm -rf "${staging}"' EXIT
+mkdir -p "${staging}/bin" "${staging}/sbin" "${staging}/usr/lib/guanghu" \
+  "${staging}/etc/guanghu" "${staging}/run" "${staging}/dev" \
+  "${staging}/proc" "${staging}/sys" "${staging}/lib/modules" \
+  "$(dirname "${output}")"
+install -m 0755 /bin/busybox "${staging}/bin/busybox"
+for applet in sh sleep cat grep tr stat mkdir mv chmod readlink kill sync poweroff; do
+  ln -s busybox "${staging}/bin/${applet}"
+done
+install -m 0755 "${supervisor}" "${staging}/usr/lib/guanghu/guanghu-root-supervisor"
+install -m 0600 "${config}" "${staging}/etc/guanghu/first-boot-supervisor.conf"
+printf '%s\n' 'guanghu.cross-root-fixture/v1' >"${staging}/etc/guanghu/rootfs.marker"
+
+cat >"${staging}/sbin/init" <<'EOF'
+#!/bin/sh
+set -eu
+export PATH=/bin:/sbin
+echo 'GUANGHU_SWITCH_ROOT_INIT_ACTIVE marker=guanghu.cross-root-fixture/v1'
+/usr/lib/guanghu/guanghu-root-supervisor run &
+supervisor_pid=$!
+attempt=0
+while [ ! -s /run/guanghu/root-supervisor/state.json ] && [ "${attempt}" -lt 100 ]; do
+  sleep 0.05
+  attempt=$((attempt + 1))
+done
+kill -0 "${supervisor_pid}"
+grep -Fq '"stage":"ROOT_SUPERVISOR_ACTIVE"' /run/guanghu/root-supervisor/state.json
+echo "GUANGHU_CROSS_ROOT_PERSISTENCE_VERIFIED pid=${supervisor_pid}"
+kill "${supervisor_pid}"
+wait "${supervisor_pid}"
+sync
+poweroff -f
+while :; do sleep 30; done
+EOF
+chmod 0755 "${staging}/sbin/init"
+
+truncate -s 128M "${output}"
+mkfs.ext4 -q -F -U "${root_uuid}" -L GUANGHU_XROOT -d "${staging}" "${output}"
+chmod 0600 "${output}"
+sha256sum "${output}" >"${output}.sha256"
+printf 'GUANGHU_CROSS_ROOT_FIXTURE_BUILT output=%s root_uuid=%s\n' "${output}" "${root_uuid}"
--- a/product-source/hololake-platform/guanghu-os/scripts/guanghu-root-supervisor.sh
+++ b/product-source/hololake-platform/guanghu-os/scripts/guanghu-root-supervisor.sh
@ -0,0 +1,109 @@
+#!/bin/sh
+set -eu
+
+die() {
+  printf 'GUANGHU_ROOT_SUPERVISOR_FAIL_0: %s\n' "$1" >&2
+  exit 1
+}
+
+test_root=${GUANGHU_ROOT_SUPERVISOR_TEST_ROOT:-}
+if [ -n "${test_root}" ]; then
+  test_root=$(readlink -f "${test_root}")
+  config_path=${GUANGHU_ROOT_SUPERVISOR_CONFIG:-}
+  handoff_path=${GUANGHU_ROOT_SUPERVISOR_HANDOFF:-}
+  state_root=${GUANGHU_ROOT_SUPERVISOR_STATE_ROOT:-}
+  dmi_path=${GUANGHU_ROOT_SUPERVISOR_DMI_PATH:-}
+  cmdline_path=${GUANGHU_ROOT_SUPERVISOR_CMDLINE_PATH:-}
+  boot_id_path=${GUANGHU_ROOT_SUPERVISOR_BOOT_ID_PATH:-}
+  for override_path in "${config_path}" "${handoff_path}" "${state_root}" \
+    "${dmi_path}" "${cmdline_path}" "${boot_id_path}"; do
+    resolved_path=$(readlink -f "${override_path}")
+    case "${resolved_path}" in "${test_root}"|"${test_root}"/*) ;; *) die "test path escapes isolated root" ;; esac
+  done
+else
+  [ -z "${GUANGHU_ROOT_SUPERVISOR_CONFIG:-}${GUANGHU_ROOT_SUPERVISOR_HANDOFF:-}${GUANGHU_ROOT_SUPERVISOR_STATE_ROOT:-}${GUANGHU_ROOT_SUPERVISOR_DMI_PATH:-}${GUANGHU_ROOT_SUPERVISOR_CMDLINE_PATH:-}${GUANGHU_ROOT_SUPERVISOR_BOOT_ID_PATH:-}" ] ||
+    die "production path overrides are forbidden"
+  config_path=/etc/guanghu/first-boot-supervisor.conf
+  handoff_path=/run/guanghu/first-boot/handoff.json
+  state_root=/run/guanghu/root-supervisor
+  dmi_path=/sys/class/dmi/id/product_uuid
+  cmdline_path=/proc/cmdline
+  boot_id_path=/proc/sys/kernel/random/boot_id
+fi
+
+[ -f "${config_path}" ] && [ ! -L "${config_path}" ] || die "configuration is missing or unsafe"
+config_mode=$(stat -c '%a' "${config_path}" 2>/dev/null || stat -f '%Lp' "${config_path}")
+[ "${config_mode}" = 600 ] || die "configuration mode must be 0600"
+if [ -z "${test_root}" ]; then
+  config_owner=$(stat -c '%u' "${config_path}" 2>/dev/null || stat -f '%u' "${config_path}")
+  [ "${config_owner}" = 0 ] || die "configuration must be root-owned"
+fi
+
+schema=
+node_id=
+instance_id=
+root_uuid=
+linux_rescue_entry=
+linux_code_bridge=
+while IFS='=' read -r key value; do
+  case "${key}" in
+    schema) schema=${value} ;;
+    node_id) node_id=${value} ;;
+    instance_id) instance_id=${value} ;;
+    root_uuid) root_uuid=${value} ;;
+    linux_rescue_entry) linux_rescue_entry=${value} ;;
+    linux_code_bridge) linux_code_bridge=${value} ;;
+    ''|'#'*) ;;
+    *) die "unknown configuration field ${key}" ;;
+  esac
+done <"${config_path}"
+
+[ "${schema}" = guanghu.first-boot-supervisor/v1 ] || die "configuration schema mismatch"
+[ "${node_id}" = JD-FD-PRIMARY ] || die "node identity mismatch"
+observed_instance=$(tr 'A-F' 'a-f' <"${dmi_path}" | tr -d '\r\n')
+[ "${observed_instance}" = "${instance_id}" ] || die "DMI identity mismatch"
+cmdline=$(cat "${cmdline_path}")
+case " ${cmdline} " in *' guanghu.first_boot=1 '*) ;; *) die "explicit first-boot marker is missing" ;; esac
+case " ${cmdline} " in *" root=UUID=${root_uuid} "*) ;; *) die "root UUID binding is missing" ;; esac
+boot_id=$(tr -d '\r\n' <"${boot_id_path}")
+
+verify_handoff() {
+  [ -f "${handoff_path}" ] && [ ! -L "${handoff_path}" ] || die "pre-root handoff is missing or unsafe"
+  handoff_mode=$(stat -c '%a' "${handoff_path}" 2>/dev/null || stat -f '%Lp' "${handoff_path}")
+  [ "${handoff_mode}" = 600 ] || die "pre-root handoff mode must be 0600"
+  handoff=$(cat "${handoff_path}")
+  for binding in \
+    '"schema":"guanghu.first-boot-handoff/v1"' \
+    "\"node_id\":\"${node_id}\"" \
+    "\"instance_id\":\"${instance_id}\"" \
+    "\"boot_id\":\"${boot_id}\"" \
+    '"control":"GUANGHU_OS"' \
+    '"stage":"PRE_ROOT_SUPERVISOR_ACTIVE"' \
+    '"full_linux_userspace":"DORMANT"' \
+    "\"linux_rescue\":\"${linux_rescue_entry}\""; do
+    printf '%s' "${handoff}" | grep -Fq "${binding}" || die "pre-root handoff binding mismatch"
+  done
+}
+
+write_state() {
+  mkdir -p "${state_root}"
+  temporary_path=${state_root}/state.json.tmp.$$
+  printf '%s\n' "{\"schema\":\"guanghu.root-supervisor-state/v1\",\"node_id\":\"${node_id}\",\"instance_id\":\"${instance_id}\",\"boot_id\":\"${boot_id}\",\"pid\":$$,\"control\":\"GUANGHU_OS\",\"stage\":\"ROOT_SUPERVISOR_ACTIVE\",\"linux_kernel_role\":\"HARDWARE_COMPATIBILITY_SUBSTRATE\",\"linux_code_bridge\":\"${linux_code_bridge}\",\"linux_rescue\":\"${linux_rescue_entry}\"}" >"${temporary_path}"
+  chmod 0600 "${temporary_path}"
+  mv "${temporary_path}" "${state_root}/state.json"
+}
+
+case "${1:-}" in
+  verify)
+    verify_handoff
+    printf 'GUANGHU_ROOT_HANDOFF_VERIFIED node=%s boot_id=%s\n' "${node_id}" "${boot_id}"
+    ;;
+  run)
+    verify_handoff
+    write_state
+    printf 'GUANGHU_ROOT_SUPERVISOR_ACTIVE node=%s boot_id=%s pid=%s\n' "${node_id}" "${boot_id}" "$$"
+    trap 'exit 0' TERM INT HUP
+    while :; do sleep 30 & wait $! || true; done
+    ;;
+  *) die "usage: guanghu-root-supervisor <verify|run>" ;;
+esac
--- a/product-source/hololake-platform/guanghu-os/scripts/test-guanghu-root-supervisor.sh
+++ b/product-source/hololake-platform/guanghu-os/scripts/test-guanghu-root-supervisor.sh
@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+source_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+supervisor=${source_root}/scripts/guanghu-root-supervisor.sh
+unit=${source_root}/packaging/systemd/guanghu-root-supervisor.service
+fixture=$(mktemp -d)
+supervisor_pid=
+trap '[[ -z ${supervisor_pid} ]] || kill "${supervisor_pid}" 2>/dev/null || true; rm -rf "${fixture}"' EXIT
+
+mkdir -p "${fixture}/etc" "${fixture}/run/first-boot" "${fixture}/run/root-supervisor" \
+  "${fixture}/proc/sys/kernel/random" "${fixture}/sys"
+cat >"${fixture}/etc/supervisor.conf" <<'EOF'
+schema=guanghu.first-boot-supervisor/v1
+node_id=JD-FD-PRIMARY
+instance_id=f3d4b730-7f02-452f-975b-7091a4800431
+root_uuid=9e4550a0-452b-4f28-b5a5-d5364aa450f6
+linux_rescue_entry=gnulinux-simple-9e4550a0-452b-4f28-b5a5-d5364aa450f6
+linux_code_bridge=hlcc-jd-candidate.service
+EOF
+chmod 0600 "${fixture}/etc/supervisor.conf"
+printf '%s\n' f3d4b730-7f02-452f-975b-7091a4800431 >"${fixture}/sys/product_uuid"
+printf '%s\n' 11111111-2222-4333-8444-555555555555 >"${fixture}/proc/sys/kernel/random/boot_id"
+printf '%s\n' 'guanghu.first_boot=1 root=UUID=9e4550a0-452b-4f28-b5a5-d5364aa450f6 ro' >"${fixture}/proc/cmdline"
+printf '%s\n' '{"schema":"guanghu.first-boot-handoff/v1","node_id":"JD-FD-PRIMARY","instance_id":"f3d4b730-7f02-452f-975b-7091a4800431","boot_id":"11111111-2222-4333-8444-555555555555","control":"GUANGHU_OS","stage":"PRE_ROOT_SUPERVISOR_ACTIVE","full_linux_userspace":"DORMANT","linux_code_bridge":"PENDING_BOUNDED_HANDOFF","linux_rescue":"gnulinux-simple-9e4550a0-452b-4f28-b5a5-d5364aa450f6"}' >"${fixture}/run/first-boot/handoff.json"
+chmod 0600 "${fixture}/run/first-boot/handoff.json"
+
+env GUANGHU_ROOT_SUPERVISOR_TEST_ROOT="${fixture}" \
+  GUANGHU_ROOT_SUPERVISOR_CONFIG="${fixture}/etc/supervisor.conf" \
+  GUANGHU_ROOT_SUPERVISOR_HANDOFF="${fixture}/run/first-boot/handoff.json" \
+  GUANGHU_ROOT_SUPERVISOR_STATE_ROOT="${fixture}/run/root-supervisor" \
+  GUANGHU_ROOT_SUPERVISOR_DMI_PATH="${fixture}/sys/product_uuid" \
+  GUANGHU_ROOT_SUPERVISOR_CMDLINE_PATH="${fixture}/proc/cmdline" \
+  GUANGHU_ROOT_SUPERVISOR_BOOT_ID_PATH="${fixture}/proc/sys/kernel/random/boot_id" \
+  "${supervisor}" run >"${fixture}/stdout" 2>"${fixture}/stderr" &
+supervisor_pid=$!
+for _ in {1..50}; do [[ -s ${fixture}/run/root-supervisor/state.json ]] && break; sleep 0.02; done
+if ! kill -0 "${supervisor_pid}" 2>/dev/null; then
+  cat "${fixture}/stderr" >&2
+  exit 1
+fi
+grep -Fq 'GUANGHU_ROOT_SUPERVISOR_ACTIVE node=JD-FD-PRIMARY' "${fixture}/stdout"
+grep -Fq '"stage":"ROOT_SUPERVISOR_ACTIVE"' "${fixture}/run/root-supervisor/state.json"
+kill "${supervisor_pid}"
+wait "${supervisor_pid}"
+supervisor_pid=
+
+printf '%s\n' aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee >"${fixture}/proc/sys/kernel/random/boot_id"
+if env GUANGHU_ROOT_SUPERVISOR_TEST_ROOT="${fixture}" \
+  GUANGHU_ROOT_SUPERVISOR_CONFIG="${fixture}/etc/supervisor.conf" \
+  GUANGHU_ROOT_SUPERVISOR_HANDOFF="${fixture}/run/first-boot/handoff.json" \
+  GUANGHU_ROOT_SUPERVISOR_STATE_ROOT="${fixture}/run/root-supervisor" \
+  GUANGHU_ROOT_SUPERVISOR_DMI_PATH="${fixture}/sys/product_uuid" \
+  GUANGHU_ROOT_SUPERVISOR_CMDLINE_PATH="${fixture}/proc/cmdline" \
+  GUANGHU_ROOT_SUPERVISOR_BOOT_ID_PATH="${fixture}/proc/sys/kernel/random/boot_id" \
+  "${supervisor}" verify >/dev/null 2>&1; then
+  echo 'root supervisor accepted a handoff from another boot' >&2
+  exit 1
+fi
+
+grep -Fq 'DefaultDependencies=no' "${unit}"
+grep -Fq 'Before=sysinit.target basic.target' "${unit}"
+grep -Fq 'ExecStart=/usr/lib/guanghu/guanghu-root-supervisor run' "${unit}"
+echo GUANGHU_ROOT_SUPERVISOR_CONTRACT_OK
--- a/product-source/hololake-platform/guanghu-os/world-seed/scripts/run-guanghu-native-quality-gate.sh
+++ b/product-source/hololake-platform/guanghu-os/world-seed/scripts/run-guanghu-native-quality-gate.sh
@ -96,6 +96,8 @@ run_gate linux_subcontrol_docker_backend \
  "${source_root}/scripts/test-linux-subcontrol-docker-backend.sh"
 run_gate guanghu_first_boot_supervisor \
  "${source_root}/scripts/test-guanghu-first-boot-supervisor.sh"
+run_gate guanghu_root_supervisor \
+  "${source_root}/scripts/test-guanghu-root-supervisor.sh"
 run_gate auditable_line_coverage_100_percent \
  bash -c '
    cargo llvm-cov clean --workspace --manifest-path "$1/Cargo.toml"