stackkit host

与提供商无关的主机契约操作。

stackkit host [flags]

子命令：stackkit host attach-conformance, stackkit host conformance, stackkit host delivery, stackkit host environment, stackkit host migrate-browser-ca, stackkit host preflight, stackkit host prepare, stackkit host reboot, stackkit host remediate, stackkit host security, stackkit host ssh, stackkit host updates

stackkit host attach-conformance

在生成计划之前，将确切的主机证据附加到 Inventory。

stackkit host attach-conformance [flags]

标志	类型	默认值	说明
`--binding`	string	—	必填。限定在工作区内的 ExternalHostBinding JSON
`--inventory`	string	—	必填。限定在工作区内、要原子更新的 inventory.json
`--receipt`	string	—	必填。限定在工作区内的 HostConformanceReceipt JSON

stackkit host conformance

在此主机上生成与提供商无关的一致性回执。

stackkit host conformance [flags]

标志	类型	默认值	说明
`--binding`	string	—	必填。本地 ExternalHostBinding JSON 文件
`--output, -o`	string	`-`	回执的输出目标（’-’ 表示在 stdout 输出 JSON）

stackkit host delivery

管理此节点的密封主机交付接收方。密封主机交付会把 Wallet 项目、备份目标和 SSH 访问权限交付到此节点。交付方会用此节点的接收方密钥（HPKE，pkg/hostdelivery）分别密封每个值；只有此节点能将其打开并存入自身托管。Techstack 和 Guard 只传递密文和引用。

stackkit host delivery [flags]

子命令：stackkit host delivery detach, stackkit host delivery recipient, stackkit host delivery status

stackkit host delivery detach

停止向此节点交付主机内容，并列出需要轮换的已交付秘密。将此节点从主机交付中分离：每个已交付的秘密都会被标记为需要轮换，已退役的接收方密钥会被销毁；在使用 ‘host delivery recipient --rotate’ 重新注册此节点之前，不会再打开任何交付。结果列出需要在来源处轮换的引用和版本，且绝不包含任何值。本地托管中已有的值在此仍可使用。

stackkit host delivery detach [flags]

标志	类型	默认值	说明
`--owner-approve`	bool	—	授权分离此节点

示例

stackkit host delivery detach --owner-approve

stackkit host delivery recipient

证明此节点的接收方密钥、固定交付权威或轮换密钥。打印一份由本地 Owner 密钥签名的声明，将此节点的接收方密钥及其代次绑定到此 Site 和节点，并回显调用方的挑战值。私钥永远不会离开本地托管。 --authority-key 为当前代次固定交付权威的 Ed25519 公钥；只有由该密钥签名时，Wallet 项目和 SSH 访问才会打开。已固定的密钥绝不会原地替换。--rotate 会在下一代次下重新注册此节点（若同时使用 --authority-key，则固定新的权威）：之前的密钥仍可在最多 15 分钟的有效期内打开轮换前签发的交付，之后即被销毁。轮换也会结束分离状态。

stackkit host delivery recipient [flags]

标志	类型	默认值	说明
`--authority-key`	string	—	要为此代次固定的交付权威 Ed25519 公钥（base64）
`--authority-key-id`	string	—	交付权威签署信封所用的密钥 ID
`--challenge`	string	—	交付权威提供的新值，声明必须回显该值
`--owner-approve`	bool	—	授权此节点的接收方变更
`--rotate`	bool	—	在下一接收方代次下重新注册

示例

stackkit host delivery recipient --challenge "$CHALLENGE" --authority-key "$WALLET_KEY" --authority-key-id wallet-1 --owner-approve
stackkit host delivery recipient --challenge "$CHALLENGE" --rotate --owner-approve

stackkit host delivery status

显示接收方代次、已固定的权威、分离状态和已交付引用。报告此节点的接收方代次和指纹、仍可打开的已退役代次、已固定的交付权威、此节点是否已分离，以及每个已交付秘密的引用、版本和轮换标记。不会读取任何值。

stackkit host delivery status [flags]

stackkit host environment

观察此主机看起来像家庭网络还是公共服务器。检测这台机器的网络环境。这只是观察，并非选择 Kit。安装器和 init 会借助它，在 VPS 上编写本地家庭地址之前，或在局域网主机上使用 Cloud Kit 之前先询问你。STACKKIT_NETWORK_ENV=home|vps|cloud|unknown 会覆盖实时检测。

stackkit host environment [flags]

标志	类型	默认值	说明
`--json`	bool	—	以 JSON 输出观察结果

示例

# Show whether this host looks like a home network or a public server
stackkit host environment

# The same observation as JSON
stackkit host environment --json

# Override a wrong detection for the next command, here Basement Kit init on a home host
STACKKIT_NETWORK_ENV=home stackkit init basement-kit --catalog-defaults --owner-source=local --owner-email you@example.com

stackkit host migrate-browser-ca

将此节点经过认证的旧版 CA 迁移到支持浏览器的策略。显式迁移旧版 Basement CA 签名密钥，同时保留 Owner 签名密钥、PocketID 身份、运行时秘密、入口叶证书密钥、地址和卷。已是当前版本的根证书保持不变。先应用并验证当前原生计划，再使用 --complete。客户端必须通过现有的客户端信任交接流程，批准已变更的公共根证书。

stackkit host migrate-browser-ca [flags]

标志	类型	默认值	说明
`--complete`	bool	—	在当前原生 Apply 和常规 TLS 验证之后，退役恢复日志
`--owner-approve`	bool	—	授权此节点的显式 CA 迁移

stackkit host preflight

检查此主机能否运行所选的 StackKit。测量此主机，并与 Kit 声明的下限进行比较。 Preflight 只执行只读探测：它从不安装、启动或配置任何东西。Apply 在改动主机之前会执行同样的准入检查。

stackkit host preflight [flags]

标志	类型	默认值	说明
`--json`	bool	—	以机器可读的 JSON 输出带版本的 preflight 报告
`--local-node`	string	—	所提供 ResolvedPlan 中确切的本地节点
`--policy`	string	—	准入策略：strict、warn（默认）或 skip
`--resolved-plan`	string	—	已验证的规范 ResolvedPlan，将检查其主机监听端口

示例

# Check this host against the kit selected in the current deployment directory
stackkit host preflight

# Also refuse on warnings and unknown facts, and print the report as JSON
stackkit host preflight --policy strict --json

stackkit host prepare

在 Cloud Kit apply 之前准备此主机。在主机安全策略禁用 root 登录之前，配置所需的 Cloud 执行通道账号和 SSH 密钥托管。 Cloud Kit 安装器和 apply 会自动调用它。此命令的用途是诊断，以及在手动中断之后让工作区重新收敛。它会在 .stackkit/cloud-host-security/execution-channel/ 下生成或复用由工作区托管的密钥，并将对应的公钥安装到执行通道 Linux 账号上。

stackkit host prepare [flags]

示例

# Converge the execution-channel account after an interrupted Cloud Kit install (run as root in the Cloud Kit deployment directory)
cd my-cloud
stackkit host prepare

stackkit host reboot

安排此节点重启。在短暂延迟后安排此节点重启，并立即返回。返回的 boot_id_before 标识当前这次启动，因此调用方可以通过读取到不同的 boot ID 来判断节点已重新上线。在以下情况下命令会拒绝执行：节点运行着 Techstack 控制平面，apt 或 dpkg 持有其锁或正在进行主机更新，或节点无法无人值守启动（/etc/crypttab 中有需要口令的卷，或没有 apt）。延迟结束时，守卫会再次检查，最多等待 15 分钟让所有包操作完成，并在持有 dpkg 锁的同时请求重启。仍然繁忙的节点不会被重启；其 boot ID 保持不变。

stackkit host reboot [flags]

标志	类型	默认值	说明
`--delay`	duration	`30s`	距离重启开始的时间（1s 到 5m）
`--json`	bool	—	以机器可读的 JSON 输出 stackkit.host-maintenance/v1 结果
`--yes`	bool	—	确认此节点可以重启

示例

# Reboot this node in 30 seconds
sudo stackkit host reboot --yes

# Reboot in two minutes and report the boot ID to compare against
sudo stackkit host reboot --yes --delay 2m --json

stackkit host remediate

显示或执行针对主机 preflight 发现项的修复。列出针对此主机 preflight 发现项的修复，或执行其中一项。不带 --apply 时不会更改任何内容：命令会测量主机，并输出每项修复将执行的操作、是否可以撤销，以及是否需要 root。使用 --apply <id> --yes 时，指定的修复会运行，之后会重新测量当初促成它的检查，因此结果说明的是实际发生的变化，而不仅是尝试过某个操作。

stackkit host remediate [flags]

标志	类型	默认值	说明
`--apply`	string	—	执行指定的解决方案（需要 `--yes`）
`--auto-reversible`	bool	—	执行所有可以无人值守运行的可撤销修复（需要 `--yes`）
`--json`	bool	—	以机器可读的 JSON 输出修复计划或记录
`--policy`	string	—	用于查找发现项的 preflight 策略：strict 或 warn（默认）
`--yes`	bool	—	确认指定的解决方案可以更改此主机

示例

# List the fixes for this host's preflight findings without changing anything
stackkit host remediate

# Carry out one fix by the ID the list printed
stackkit host remediate --apply <resolution-id> --yes

# Carry out every undoable fix that may run unattended
stackkit host remediate --auto-reversible --yes

stackkit host security

使用带版本的证据验证并修复主机安全基线。依据 StackKits 主机安全基线观察此节点，并在不中断管理路径的情况下恢复发生偏移的项目。 ‘verify’ 绝不会更改主机。它会为防火墙、sshd、暴力破解防护、自动和待处理的安全更新、重启状态、内核参数、公开的监听器和证书到期情况，以及已记录的、交付到此节点的 SSH CA 信任和主机证书（‘host ssh apply’）生成 stackkit.host-security-evidence/v1。每项控制的状态为 compliant、drifted、unknown 或经 Owner 批准的例外，且证据会到期：过期的观察结果为 unknown，而 unknown 控制绝不能算作 compliant。它既可独立运行（Standard Mode，无需账号），也可在 Techstack 管理部署时通过固定版本的 CLI 运行（--mode advanced）。

stackkit host security [flags]

子命令：stackkit host security repair、stackkit host security status、stackkit host security verify

stackkit host security repair

在不中断管理路径的情况下恢复发生偏移的基线控制。规划如何恢复发生偏移的控制，或使用 --apply 执行恢复。不使用 --apply 时不会更改任何内容：命令会测量主机，并输出每项修复将执行的操作。使用 --apply 时，只会处理指定的（--control）或发生偏移的控制，而且每项更改都会先检查：

  - the firewall always keeps admitting the ssh sessions in use and every
    --management-source on every sshd port, and a policy that would not is
    refused before it is loaded;
  - password logins are disabled only when an account holds an authorized key;
    without one they stay on, the step is refused with reason no_authorized_key
    and the rest of the baseline is still repaired. The previous sshd and
    firewall configuration is restored if the new one does not validate or does
    not take effect;
  - fail2ban never bans the management path.

无法观察的控制或由 Owner 批准例外的控制不会被处理。Cloud Site 的防火墙和 root 登录由 ‘stackkit apply’ 恢复。每个步骤都会记录控制更改前后的状态；对已经 compliant 的控制重复执行修复不会更改任何内容。

stackkit host security repair [flags]

标志	类型	默认值	说明
`--apply`	bool	—	执行修复；不使用此标志时，命令只进行规划
`--control`	stringArray	—	将修复限制为此控制 ID（可重复指定）
`--declared-port`	stringArray	—	声明的服务端口，格式为 tcp/443 或 udp/5353（可重复指定）
`--exceptions`	string	`/etc/stackkit/host-security/exceptions.json`	由 Owner 控制的例外文件（每个例外都需要 Owner 和到期时间）
`--freshness`	duration	`15m0s`	证据在到期前可被信赖的时长（1 分钟至 24 小时）
`--host-name`	stringArray	—	交付的 SSH 主机证书必须包含的名称（可重复指定；默认：系统主机名）
`--json`	bool	—	以机器可读的 JSON 输出结果
`--kit`	string	—	要记录的 Kit slug（默认为工作区 StackSpec 的 Kit）
`--local-node`	string	—	所提供 ResolvedPlan 中的确切本地 Node
`--management-source`	stringArray	—	必须始终能够访问 ssh 的网络，以 CIDR 表示（可重复指定）
`--mode`	string	`standard`	要记录的生命周期模式：standard；Techstack 管理此部署时为 advanced
`--no-record`	bool	—	不在 .stackkit/ 下写入修复后的证据
`--resolved-plan`	string	—	经过验证的规范 ResolvedPlan，用于依据其声明的监听器判断暴露情况
`--site-kind`	string	—	此主机的 Site 类型：home 或 cloud（默认根据 Kit 推断；modern-homelab 需要此项）

示例

# See what would be repaired
sudo stackkit host security repair --site-kind home

# Restore only the firewall, keeping a jump host reachable
sudo stackkit host security repair --apply --control firewall.default_inbound --management-source 198.51.100.0/24

stackkit host security status

读取当前保存的证据，而不观察主机。读取 ‘verify’ 最后记录在此工作区的证据，并按当前时间进行判断。超过新鲜度期限的证据为 unknown：旧的观察结果无法证明主机当前的状态。

stackkit host security status [flags]

标志	类型	默认值	说明
`--drift-scope`	string	`all`	决定 `--fail-on-drift` 的控制项：all 或 enforced（仅基线本身强制执行的控制项；补丁滞后、待重启、暴露面和证书仍被观测和报告）
`--fail-on-drift`	bool	—	主机为 drifted 时以 5 退出，状态为 unknown 时以 6 退出
`--json`	bool	—	以机器可读的 JSON 输出证据

stackkit host security verify

观察主机安全基线并写入带版本的证据。观察此节点上的每项基线控制并生成 stackkit.host-security-evidence/v1。不会更改主机上的任何内容。大多数控制需要 root 才能观察；无法观察的控制会报告为 unknown 并附带原因，而不是报告为失败。除非指定 --no-record，否则证据会写入工作区的 .stackkit/host-security-evidence.json，并在 --freshness 后到期。

stackkit host security verify [flags]

标志	类型	默认值	说明
`--declared-port`	stringArray	—	声明的服务端口，格式为 tcp/443 或 udp/5353（可重复指定）
`--drift-scope`	string	`all`	决定 `--fail-on-drift` 的控制项：all 或 enforced（仅基线本身强制执行的控制项；补丁滞后、待重启、暴露面和证书仍被观测和报告）
`--exceptions`	string	`/etc/stackkit/host-security/exceptions.json`	由 Owner 控制的例外文件（每个例外都需要 Owner 和到期时间）
`--fail-on-drift`	bool	—	主机为 drifted 时以 5 退出，状态为 unknown 时以 6 退出
`--freshness`	duration	`15m0s`	证据在到期前可被信赖的时长（1 分钟至 24 小时）
`--host-name`	stringArray	—	交付的 SSH 主机证书必须包含的名称（可重复指定；默认：系统主机名）
`--json`	bool	—	以机器可读的 JSON 输出结果
`--kit`	string	—	要记录的 Kit slug（默认为工作区 StackSpec 的 Kit）
`--local-node`	string	—	所提供 ResolvedPlan 中的确切本地 Node
`--management-source`	stringArray	—	必须始终能够访问 ssh 的网络，以 CIDR 表示（可重复指定）
`--mode`	string	`standard`	要记录的生命周期模式：standard；Techstack 管理此部署时为 advanced
`--no-record`	bool	—	不在 .stackkit/ 下写入证据
`--resolved-plan`	string	—	经过验证的规范 ResolvedPlan，用于依据其声明的监听器判断暴露情况
`--site-kind`	string	—	此主机的 Site 类型：home 或 cloud（默认根据 Kit 推断；modern-homelab 需要此项）

示例

# Verify this host and record the evidence
sudo stackkit host security verify

# Machine-readable, advanced mode, exit non-zero on any drifted control
sudo stackkit host security verify --mode advanced --json --fail-on-drift

# What the Techstack host pre-step runs: only the controls the baseline enforces decide the exit code; patch lag, pending reboot, exposure and certificates are still observed and reported
sudo stackkit host security verify --mode advanced --json --fail-on-drift --drift-scope enforced

# Judge exposure against the ports the verified plan declares
sudo stackkit host security verify --resolved-plan plan.json --local-node node-1

stackkit host ssh

此节点所交付的 SSH 证书访问。

stackkit host ssh [flags]

子命令：stackkit host ssh apply

stackkit host ssh apply

从标准输入应用密封的 SSH CA 信任、撤销或主机证书交付。在标准输入读取一个由已固定的交付权威签名的密封 ssh-ca-trust、ssh-ca-revoke 或 ssh-host-certificate 信封，并将其应用到此服务器的 sshd：

  - ssh-ca-trust installs the owner's user CA keys as TrustedUserCAKeys
    (/etc/ssh/stackkit/trusted_user_ca_keys) and one AuthorizedPrincipalsFile
    per local user (/etc/ssh/stackkit/principals/<user>). Root is never a
    target. An empty key list revokes like ssh-ca-revoke.
  - ssh-ca-revoke removes that trust. Revocations take effect at once and are
    never rolled back; one sshd cannot reload for is recorded as cleanup
    pending and finished by 'host security repair'.
  - ssh-host-certificate installs a host certificate beside the host key it
    certifies, only if it names every --host-name (default: the system
    hostname) and is currently valid.

只有在 ‘sshd -t’ 接受新配置后才会重新加载 sshd；失败的更改会被回滚。已应用的状态会记录在 Owner 托管中，因此 ‘host security verify’ 会报告偏移，而 ‘host security repair’ 会重新安装它。

stackkit host ssh apply [flags]

标志	类型	默认值	说明
`--host-name`	stringArray	—	主机证书必须包含的主体名称（可重复指定；默认：系统主机名）
`--owner-approve`	bool	—	授权更改此服务器的 SSH 访问
`--tenant-ref`	string	—	密封交付必须寻址到的租户

示例

sudo stackkit host ssh apply --tenant-ref "$TENANT" --owner-approve < envelope.json

stackkit host updates

规划并应用此节点的操作系统软件包更新。规划并应用此 Debian 或 Ubuntu 节点的操作系统软件包更新。容器运行时（docker.io、docker-ce*、containerd*、runc）会被保留：它会列在计划中，但 apply 永远不会安装它，因为升级它会重启所有工作负载。Apply 从不移除软件包，从不运行 autoremove，也从不重启；如需重启请使用 ‘stackkit host reboot’。

stackkit host updates [flags]

子命令：stackkit host updates apply, stackkit host updates plan

stackkit host updates apply

只安装经过审阅的更新计划。只安装经过审阅的 ‘stackkit host updates plan’ 所报告的软件包集合。会先再次模拟待处理集合；当其摘要与 --plan-digest 不同时不会安装任何内容（plan_stale）。apt 在临时的 systemd 单元（kombify-host-update-*）中以非交互方式运行，并保留现有配置文件，因此 CLI 或 Agent 超时只会停止等待，绝不会中断 dpkg。结果会记录每个软件包更新前后的版本，以及节点现在是否需要重启。

stackkit host updates apply [flags]

标志	类型	默认值	说明
`--json`	bool	—	以机器可读的 JSON 输出 stackkit.host-maintenance/v1 结果
`--plan-digest`	string	—	必填。已审阅计划的 plan_digest（sha256:<hex>）
`--yes`	bool	—	确认可以安装计划中的软件包

示例

# Apply the plan you reviewed
sudo stackkit host updates apply --plan-digest sha256:<digest> --yes

stackkit host updates plan

刷新软件包索引并显示待处理的更新。刷新软件包索引，并显示 ‘stackkit host updates apply’ 将会安装的内容。结果会列出每个待更新软件包及其当前版本和新版本、被保留的容器运行时软件包、apt 暂缓升级的软件包、是否可能需要重启（内核、C 库或 systemd），以及 dpkg 问题。plan_digest 绑定确切的软件包集合；当它不再匹配时，apply 会拒绝执行。

stackkit host updates plan [flags]

标志	类型	默认值	说明
`--json`	bool	—	以机器可读的 JSON 输出 stackkit.host-maintenance/v1 结果

示例

# Show the pending updates of this node
sudo stackkit host updates plan

# Machine-readable plan with its plan_digest
sudo stackkit host updates plan --json

快速入门

指南

参考

stackkit host attach-conformance

stackkit host conformance

stackkit host delivery

stackkit host delivery detach

stackkit host delivery recipient

stackkit host delivery status

stackkit host environment

stackkit host migrate-browser-ca

stackkit host preflight

stackkit host prepare

stackkit host reboot

stackkit host remediate

stackkit host security

stackkit host security repair

stackkit host security status

stackkit host security verify

stackkit host ssh

stackkit host ssh apply

stackkit host updates

stackkit host updates apply

stackkit host updates plan

​stackkit host attach-conformance

​stackkit host conformance

​stackkit host delivery

​stackkit host delivery detach

​stackkit host delivery recipient

​stackkit host delivery status

​stackkit host environment

​stackkit host migrate-browser-ca

​stackkit host preflight

​stackkit host prepare

​stackkit host reboot

​stackkit host remediate

​stackkit host security

​stackkit host security repair

​stackkit host security status

​stackkit host security verify

​stackkit host ssh

​stackkit host ssh apply

​stackkit host updates

​stackkit host updates apply

​stackkit host updates plan

stackkit host attach-conformance

stackkit host conformance

stackkit host delivery

stackkit host delivery detach

stackkit host delivery recipient

stackkit host delivery status

stackkit host environment

stackkit host migrate-browser-ca

stackkit host preflight

stackkit host prepare

stackkit host reboot

stackkit host remediate

stackkit host security

stackkit host security repair

stackkit host security status

stackkit host security verify

stackkit host ssh

stackkit host ssh apply

stackkit host updates

stackkit host updates apply

stackkit host updates plan