> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# stackkit host

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

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

```bash theme={null}
stackkit host [flags]
```

子命令：[`stackkit host attach-conformance`](#stackkit-host-attach-conformance), [`stackkit host conformance`](#stackkit-host-conformance), [`stackkit host delivery`](#stackkit-host-delivery), [`stackkit host environment`](#stackkit-host-environment), [`stackkit host migrate-browser-ca`](#stackkit-host-migrate-browser-ca), [`stackkit host preflight`](#stackkit-host-preflight), [`stackkit host prepare`](#stackkit-host-prepare), [`stackkit host reboot`](#stackkit-host-reboot), [`stackkit host remediate`](#stackkit-host-remediate), [`stackkit host security`](#stackkit-host-security), [`stackkit host ssh`](#stackkit-host-ssh), [`stackkit host updates`](#stackkit-host-updates)

## stackkit host attach-conformance

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

```bash theme={null}
stackkit host attach-conformance [flags]
```

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

## stackkit host conformance

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

```bash theme={null}
stackkit host conformance [flags]
```

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

## stackkit host delivery

管理此节点的密封主机交付接收方。

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

```bash theme={null}
stackkit host delivery [flags]
```

子命令：[`stackkit host delivery detach`](#stackkit-host-delivery-detach), [`stackkit host delivery recipient`](#stackkit-host-delivery-recipient), [`stackkit host delivery status`](#stackkit-host-delivery-status)

### stackkit host delivery detach

停止向此节点交付主机内容，并列出需要轮换的已交付秘密。

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

```bash theme={null}
stackkit host delivery detach [flags]
```

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

**示例**

```bash theme={null}
stackkit host delivery detach --owner-approve
```

### stackkit host delivery recipient

证明此节点的接收方密钥、固定交付权威或轮换密钥。

打印一份由本地 Owner 密钥签名的声明，将此节点的接收方密钥及其代次绑定到此 Site 和节点，并回显调用方的挑战值。私钥永远不会离开本地托管。

`--authority-key` 为当前代次固定交付权威的 Ed25519 公钥；只有由该密钥签名时，Wallet 项目和 SSH 访问才会打开。已固定的密钥绝不会原地替换。`--rotate` 会在下一代次下重新注册此节点（若同时使用 `--authority-key`，则固定新的权威）：之前的密钥仍可在最多 15 分钟的有效期内打开轮换前签发的交付，之后即被销毁。轮换也会结束分离状态。

```bash theme={null}
stackkit host delivery recipient [flags]
```

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

**示例**

```bash theme={null}
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

显示接收方代次、已固定的权威、分离状态和已交付引用。

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

```bash theme={null}
stackkit host delivery status [flags]
```

## stackkit host environment

观察此主机看起来像家庭网络还是公共服务器。

检测这台机器的网络环境。

这只是观察，并非选择 Kit。安装器和 init 会借助它，在 VPS 上编写本地家庭地址之前，或在局域网主机上使用 Cloud Kit 之前先询问你。STACKKIT\_NETWORK\_ENV=home|vps|cloud|unknown 会覆盖实时检测。

```bash theme={null}
stackkit host environment [flags]
```

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

**示例**

```bash theme={null}
# 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`。客户端必须通过现有的客户端信任交接流程，批准已变更的公共根证书。

```bash theme={null}
stackkit host migrate-browser-ca [flags]
```

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

## stackkit host preflight

检查此主机能否运行所选的 StackKit。

测量此主机，并与 Kit 声明的下限进行比较。

Preflight 只执行只读探测：它从不安装、启动或配置任何东西。Apply 在改动主机之前会执行同样的准入检查。

```bash theme={null}
stackkit host preflight [flags]
```

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

**示例**

```bash theme={null}
# 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 账号上。

```bash theme={null}
stackkit host prepare [flags]
```

**示例**

```bash theme={null}
# 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 保持不变。

```bash theme={null}
stackkit host reboot [flags]
```

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

**示例**

```bash theme={null}
# 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` 时，指定的修复会运行，之后会重新测量当初促成它的检查，因此结果说明的是实际发生的变化，而不仅是尝试过某个操作。

```bash theme={null}
stackkit host remediate [flags]
```

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

**示例**

```bash theme={null}
# 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）。

```bash theme={null}
stackkit host security [flags]
```

子命令：[`stackkit host security repair`](#stackkit-host-security-repair)、[`stackkit host security status`](#stackkit-host-security-status)、[`stackkit host security verify`](#stackkit-host-security-verify)

### stackkit host security repair

在不中断管理路径的情况下恢复发生偏移的基线控制。

规划如何恢复发生偏移的控制，或使用 `--apply` 执行恢复。

不使用 `--apply` 时不会更改任何内容：命令会测量主机，并输出每项修复将执行的操作。使用 `--apply` 时，只会处理指定的（`--control`）或发生偏移的控制，而且每项更改都会先检查：

```text theme={null}
  - 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 的控制重复执行修复不会更改任何内容。

```bash theme={null}
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 需要此项） |

**示例**

```bash theme={null}
# 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：旧的观察结果无法证明主机当前的状态。

```bash theme={null}
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` 后到期。

```bash theme={null}
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 需要此项） |

**示例**

```bash theme={null}
# 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 证书访问。

```bash theme={null}
stackkit host ssh [flags]
```

子命令：[`stackkit host ssh apply`](#stackkit-host-ssh-apply)

### stackkit host ssh apply

从标准输入应用密封的 SSH CA 信任、撤销或主机证书交付。

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

```text theme={null}
  - 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' 会重新安装它。

```bash theme={null}
stackkit host ssh apply [flags]
```

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

**示例**

```bash theme={null}
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'。

```bash theme={null}
stackkit host updates [flags]
```

子命令：[`stackkit host updates apply`](#stackkit-host-updates-apply), [`stackkit host updates plan`](#stackkit-host-updates-plan)

### stackkit host updates apply

只安装经过审阅的更新计划。

只安装经过审阅的 'stackkit host updates plan' 所报告的软件包集合。

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

```bash theme={null}
stackkit host updates apply [flags]
```

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

**示例**

```bash theme={null}
# 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 会拒绝执行。

```bash theme={null}
stackkit host updates plan [flags]
```

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

**示例**

```bash theme={null}
# 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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.