# 主机与云环境功能逻辑

状态：2026-09-28 设计，待实现。对应[产品需求 FR-RH-1 至 FR-RH-6](./prd.md)，验收场景使用其中的 AC-RH 编号。

## 对象与关联

| 对象 | 所有权与关系 |
| --- | --- |
| 平台连接 | 云环境管理负责平台类型、账号或 API 端点、凭据引用与查询范围 |
| 云实例 | 以平台连接及该平台稳定资源标识定位，保留必要的账号、区域或私有化资源范围；不能仅靠名称或 IP 判定同一实例 |
| 主机 | 主机管理负责 SSH 地址、账号、认证、Host Key 和执行环境；可选关联云实例 |
| 远程项目 | 继续引用主机与远端目录，执行空间保持 local / ssh |

首版一个云实例最多关联一个受管主机，一个主机最多关联一个云实例；一个主机可被多个项目引用。重复导入显示已关联主机；关联已有主机须由用户选择并验证连接目标，不能根据相同 IP 自动合并。平台凭据和 SSH 凭据分别管理，不复制到项目中。（FR-RH-3、FR-RH-5；AC-RH-3）

## 导入与状态

发现实例后先展示平台返回的事实。用户选择“接入主机”，选定地址和认证配置，复用主机验证流程，成功后保存主机与关联；失败或取消不留下半成品主机，也不改变已有有效关联。保存成功不自动安装环境，由用户显式触发。（FR-RH-2、FR-RH-3；AC-RH-2 至 AC-RH-4）

| 状态维度 | 来源与显示规则 |
| --- | --- |
| 实例运行状态 | 平台 API 查询结果；查询失败显示错误及上次成功时间，不能推断为已删除 |
| SSH 连通性 | 所选主机的连接检查；未检查、成功、失败与检查时间独立显示 |
| 执行环境 | Agent / Runtime 实际检查和安装结果；版本匹配不等于环境健康 |

进入主机页面只读取本地记录，不逐台连接 SSH。云资源刷新只查询平台 API，不顺带验证 SSH 或安装环境。变更连接目标后按现有规则重新验证，不用旧结果宣称新目标就绪。平台报告实例消失时保留主机及项目，显示关联异常并允许用户处理，不自动清理数据。（FR-RH-4；AC-RH-1、AC-RH-4）

## 导航与能力依赖

常驻只控制导航捷径，取消常驻不停止任务、禁用能力或删除数据。应用中心的主机管理设置承载共享远程能力启用状态，迁移保留原 `remoteProjectsEnabled` 值；旧设置不再维护第二个独立开关。云环境应用的启用单独控制云管理入口和新平台操作。（FR-RH-1、FR-RH-4、FR-RH-6）

| 操作 | 目标行为 |
| --- | --- |
| 打开云环境但远程能力未启用 | 允许配置平台及查询实例；接入主机时提供就地启用，保存成功后继续 |
| 取消主机常驻 | 云环境仍可引用主机，已有关联和运行不变 |
| 关闭共享远程能力 | 沿用现有远程项目停用语义，保留主机、凭据和项目；云资源浏览仍可用，依赖操作显示原因与启用入口 |
| 关闭云环境应用 | 保留平台配置和主机关联；已接入的 SSH 主机及远程项目继续可用 |
| 切换业务页面 | 保留搜索、选择与正在进行的操作状态，遵守未保存编辑离开检查 |

能力启用与校验须同时覆盖 UI 和 Main，不能仅移动开关或隐藏按钮。（AC-RH-5）

## 删除语义

移除主机沿用现有本地引用项目及关联数据删除确认，移除成功后清除云实例到该主机的关联，实例重新显示为未接入。操作不连接远端删除目录，也不调用实例销毁 API。

移除平台连接前列出关联主机；确认后移除平台凭据及关联，保留 SSH 主机、凭据和项目，使其继续作为独立主机使用。远端实例生命周期操作属于后续功能，须在云环境页面独立定义影响及结果。（FR-RH-5；AC-RH-6）

## 完整性与待定事项

本文覆盖导航迁移、发现与导入、状态来源、依赖关闭、重复关联及删除。各平台适配顺序、支持版本和验收环境待确认；私钥与私网连接方案属于后续技术选型。实例创建、销毁、网络编排及批量操作不在首版范围，不能从本设计推导其行为。