══════════════════════════════════════════════════════════════════
      AI SSH 运维 Agent —— 添加 Windows 主机指南
      （把 Windows 电脑 / 服务器添加进主机清单，交给 AI 管理）
══════════════════════════════════════════════════════════════════

适用版本：AI-SSH 运维 Agent（2026-10 版，Web GUI 与 CLI 均适用）
配套文档：《Windows主机接入指引.txt》（目标机配置详解，本文第一章为其精简版）
更新日期：2026-10-04

【给新手的话】

本文讲两件事：一是把目标 Windows 机器准备好（启用 OpenSSH 服务），
二是把它的连接信息登记进 Agent 的主机清单（Web 界面或配置文件）。
完成后即可在 AI 对话里让 AI 直接管理这台 Windows。

  - 命令放在虚线框内，整段复制即可，块内 # 开头的行是注释
  - <尖括号> 是占位符，替换成你的实际值（如 <登录密码>）
  - 带 ★ 的步骤最容易出错，务必照做

【目录导航】

  第一章  目标机准备：启用 OpenSSH（四步）——在要被管理的 Windows 上操作
  第二章  Web 界面添加主机（推荐）——点几下完成，保存即连
  第三章  配置文件添加主机——免界面 / 批量登记场景
  第四章  本机自动纳管——让运行 Agent 的电脑自己进列表
  第五章  添加后验证——确认连接与 AI 巡检可用
  第六章  常见问题与排错——现象 → 原因 → 解决

================================================================
==  第一章  目标机准备：启用 OpenSSH（四步）
================================================================

【本章目标】
Windows 默认没有开 SSH 服务。要被 Agent 管理，需在目标机以管理员
权限完成四步：安装 OpenSSH Server → 启动并自启 → 防火墙放行 →
把默认 Shell 设为 PowerShell。全程约 3 分钟，装完不用重启。

1.1 安装并启动（管理员 PowerShell 整段复制）

------
# 以管理员身份打开 PowerShell，以下整段复制执行
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType Automatic
------

【预期结果】无报错即成（可用 Get-Service sshd 确认 Status 为
Running）。若在线安装失败（报错或状态一直 NotPresent），改用
离线 zip 安装，见《Windows主机接入指引.txt》第八章第 3 条。

1.2 防火墙放行 22 端口

------
Get-NetFirewallRule -Name *OpenSSH-Server* | Select-Object Name, Enabled
# 显示 Enabled=True 即已放行；若为 False 补一句：
Enable-NetFirewallRule -Name *OpenSSH-Server*
------

1.3 默认 Shell 设为 PowerShell（★ 必做）

------
New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell -Value "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" -PropertyType String -Force
# 已装 PowerShell 7 的机器建议用 pwsh：
# New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell -Value "C:\Program Files\PowerShell\7\pwsh.exe" -PropertyType String -Force
------

【预期结果】不设置时 Agent 会落到 cmd 兜底（功能可用但 AI 输出
质量下降，中文易乱码），★ 建议必做。

1.4 本地管理员账号的 UAC 远程过滤（★ 用本地管理员账号时必做）

------
New-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System" -Name LocalAccountTokenFilterPolicy -Value 1 -PropertyType DWord -Force
------

【预期结果】用本地管理员账号（如 administrator）远程登录时不被
UAC 过滤降权。域账号登录一般不需要这一步。

================================================================
==  第二章  Web 界面添加主机（推荐）
================================================================

【本章目标】浏览器打开 Agent Web 界面，点「+ 添加」填一张表完成
登记，密码自动存进 .env，保存即可连接。

2.1 打开添加弹窗

Web 界面左侧主机列表上方点「+ 添加」。

2.2 逐字段填写

  名称（唯一标识）：如 server-2019。仅用于列表显示与切换，
    不要求与目标机计算机名一致，但清单内不能重名
  设备类型：★ 必须选「Windows（SSH）」——选成 Linux 的话 AI
    会按 Linux 方言执行（安全规则、编码前导、提示词全错位）
  端口：22
  IP / 主机名：目标机 IP（如 10.10.10.134）
  用户名：目标机本地账号，常用 administrator；域账号写
    域名\用户名。注意 Windows 没有 Linux 那样的 root
  密码：★ 必填，即这台 Windows 的 Windows 登录密码
  备注：可选，如「机房 Windows Server 2019」

2.3 保存并连接

点「保存并连接」。密码写入 .env（变量名 HOST_PW_<名称大写>），
hosts.yml 只存引用不存明文。

【预期结果】主机列表出现新主机，双击/选中可建立连接。

================================================================
==  第三章  配置文件添加主机
================================================================

【本章目标】不想点界面、或需要批量登记时，直接编辑 config/hosts.yml。
在 Agent 关闭状态下编辑，保存后启动即生效。

3.1 hosts.yml 追加条目

------
# config/hosts.yml 的 hosts: 段追加（保持两级缩进）
  win-01:
    host: 192.168.1.50
    port: 22
    user: administrator
    device_type: windows
    auth:
      method: password
      password_env: HOST_PW_WIN_01
    note: 机房 Windows Server 2019
------

3.2 密码写入 .env（密码绝不写进 yml）

------
# config/.env 追加一行
HOST_PW_WIN_01=<Windows登录密码>
------

【预期结果】启动 Agent 后主机列表可见 win-01，可正常连接。

★ device_type: windows 这一行不能漏——缺省会按 Linux 处理。

★ 不要用对话指令 add_host 添加 Windows 主机：add_host 目前不带
设备类型参数，登记出来的主机会被当作 Linux（方言与安全规则错位）。
Windows 主机请用第二章 Web 界面，或本章 hosts.yml 方式。

================================================================
==  第四章  本机自动纳管
================================================================

【本章目标】让「运行 Agent 的这台电脑」也出现在主机列表里，AI 可
直接管理本机（本机走 127.0.0.1 回环 SSH，与远程主机同一通道）。

4.1 自动纳管的行为

每次 CLI / Web 启动时自动检测 127.0.0.1:22：

  - 本机已启用 OpenSSH → 自动加入清单：名称=计算机名、
    用户名=当前登录用户，无需任何手工操作
  - 本机没装 OpenSSH → 自动跳过（列表里没有本机是正常的，
    加了也连不上）
  - 已存在的回环主机不会重复添加；eNSP 等网络设备的 127.0.0.1
    端口映射不受影响

4.2 本机没在列表里？装上 OpenSSH 即可

------
# 本机管理员 PowerShell 整段执行
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType Automatic
------

然后重启 Agent（CLI 或 Web），本机自动出现在列表。

首次连接密码 = 本机 Windows 登录密码；Web 下长期免输，在
config/.env 加一行（变量名见 Agent 启动时控制台的提示）：

------
HOST_PW_<机器名大写>=<本机Windows登录密码>
------

================================================================
==  第五章  添加后验证
================================================================

【本章目标】确认链路通、AI 能干活。

5.1 连接

选中该主机建立连接，界面出现 [Windows] 标识即连上。

5.2 让 AI 做一次只读巡检

对 AI 说：看一下这台机器的 CPU、内存和系统版本

【预期结果】AI 用 Get-CimInstance 返回系统信息，中文无乱码
（Agent 已内置 UTF-8 前导 + GBK 双重解码，Server 2019 也不乱）。

5.3 纳入值守监测（可选）

Web 侧边栏「一键值守」启动后，可在 config/monitor.yml 对应主机
条目加 roles: [windows]，自动监控 CPU / 内存 / C 盘与服务状态
（IIS / SQL Server / MySQL 自动识别，服务异常与恢复均告警）。

================================================================
==  第六章  常见问题与排错
================================================================

现象：添加弹窗里没有「Windows（SSH）」选项
  原因：浏览器缓存了旧版页面（升级发行包后的常见场景）
  解决：Ctrl+F5 强制刷新。新版已带 no-cache 响应头，此后升级
        不再需要强刷

现象：点「保存并连接」报 Failed to fetch
  原因：Web 服务没在运行（页面开着，但 AI-SSH-Agent-Web.exe
        已退出或正在重启）
  解决：重新启动 AI-SSH-Agent-Web.exe，刷新页面再保存

现象：连接报 Authentication failed / 认证失败
  原因：密码不对；本地管理员账号没做 1.4 的 UAC 过滤；域账号
        格式不对
  解决：核对 Windows 登录密码；本地管理员补 1.4 注册表；域账号
        写 域名\用户名

现象：目标机装 OpenSSH 报错 / 状态一直 NotPresent
  原因：FoD 在线源拉不到（部分 Server 环境常见）
  解决：改用 GitHub Win32-OpenSSH zip 离线安装，
        见《Windows主机接入指引.txt》第八章第 3 条

现象：AI 输出中文乱码
  原因：目标机 DefaultShell 不是 PowerShell（落到 cmd 兜底）
  解决：按 1.3 设置后重连

现象：列表里没有本机
  原因：本机没装 OpenSSH，自动纳管按设计跳过
  解决：见第四章 4.2

================================================================
文档结束
================================================================
