Windows平台SSH远程开发环境配置与排错SOP

Posted on 2025-10-02 Edited on 2026-02-16 In 工具 Views: Word count in article: 2.5k Reading time ≈ 2 mins.

文档：Windows 平台 SSH 远程开发环境配置与排错 SOP

1. 目标与环境

目标: 在一台Windows主机（服务端）上配置OpenSSH服务，允许另一台Windows主机（客户端）通过互联网进行安全的、基于密钥的无密码远程连接，以实现远程开发。
服务端环境:
- 操作系统: Windows 11
- 内网IP: 192.168.1.103 (通过DHCP保留实现静态分配)
- 账户名: yan02
客户端环境:
- 操作系统: Windows 11
- 账户名: ptlan
网络环境:
- 路由器: TP-Link (管理地址 http://192.168.1.1)
- 公网IP: 124.168.121.187 (示例,可通过该网站查询公网ip)
核心工具:
- OpenSSH for Windows
- Visual Studio Code (Remote Development 扩展)
- Windows PowerShell

2. 配置流程与排错记录

步骤 2.1: 服务端 - 配置静态内网IP (DHCP保留)

操作: 为服务端电脑分配一个固定的局域网IP地址，防止因IP地址变化导致端口转发失效。
工具: 浏览器，访问路由器管理后台。
路径: Network > LAN Settings > Address Reservation。
配置: 基于服务端网卡的MAC地址（90:65:84:...），添加一条地址保留规则，将其IP地址固定为 192.168.1.103。

步骤 2.2: 服务端 - 安装与启动 OpenSSH Server

操作: 安装并启动SSH服务。
工具: Windows 设置，Windows PowerShell (管理员)。

流程:

通过 设置 > 应用 > 可选功能 安装 OpenSSH 服务器。

在管理员PowerShell中执行以下命令以启动并自启服务：

1 2	Start-Service sshd Set-Service -Name sshd -StartupType 'Automatic'

执行以下命令，创建防火墙入站规则以允许TCP 22 端口的通信：

1	New-NetFirewallRule -Name sshd -DisplayName 'OpenSSH Server (sshd)' -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22

步骤 2.3: 路由器 - 配置端口转发

操作: 将公网的特定端口映射至服务端的SSH端口。
工具: 浏览器，访问路由器管理后台。
路径: NAT Forwarding > Virtual Servers。
配置: 添加新规则，具体参数如下：
- Service Type: VSCodeSSH (自定义名称)
- External Port: 22222
- Internal IP: 192.168.1.103
- Internal Port: 22
- Protocol: TCP
- Status: Enabled

步骤 2.4: 客户端 - 首次连接与密码认证问题

操作: 客户端使用VS Code或ssh命令尝试连接。
命令: ssh yan02@124.168.121.187 -p 22222
现象: 连接时被要求输入密码，但服务端账户（yan02）未设置密码，仅使用PIN登录。
原因分析:
1. SSH协议认证基于账户密码(Password)，而非设备PIN码。
2. OpenSSH Server默认配置（sshd_config）禁止空密码账户登录。
解决方案: 在服务端，通过 设置 > 账户 > 登录选项 为yan02账户添加一个强密码。

步骤 2.5: 客户端/服务端 - 配置SSH密钥对

操作: 在客户端生成密钥对。
- 工具 (客户端): PowerShell。
- 命令: ssh-keygen -t rsa -b 4096 (使用默认选项)。
操作: 将公钥部署至服务端。
- 流程:
  1. 在客户端，复制 C:\Users\ptlan\.ssh\id_rsa.pub 文件内容。
  2. 在服务端，创建 C:\Users\yan02\.ssh\authorized_keys 文件，并将公钥内容粘贴进去。
操作: 在服务端禁用密码认证。
- 工具 (服务端): Notepad++ (管理员)。
- 文件: C:\ProgramData\ssh\sshd_config。
- 修改: 将 PasswordAuthentication yes 修改为 PasswordAuthentication no（并移除行首#）。

步骤 2.6: 排错回合一 - `Permission Denied`

现象: 完成密钥配置并重启sshd服务后，连接失败，报错 Permission denied (publickey, keyboard-interactive)。
诊断: 使用客户端ssh -v命令，日志显示公钥被服务端拒绝。问题定位在服务端。

步骤 2.7: 排错回合二 - `authorized_keys` 文件格式与 `sshd_config` 配置

问题: sshd_config 文件末尾的 Match Group administrators 配置块，将管理员的密钥文件路径重定向至 C:\ProgramData\ssh\administrators_authorized_keys。
- 解决方案: 将该配置块的两行用 # 注释掉，使其失效。

步骤 2.8: 排错回合三 - 网络连通性验证与日志缺失

现象: 修复上述问题后，连接依然失败。同时，在sshd_config中设置LogLevel DEBUG3后，服务端的事件查看器 > OpenSSH > Operational 日志为空。
诊断: 使用在线端口检查工具测试公网IP的22222端口，结果显示Open (开启)。
结论: TCP网络路径通畅。问题是sshd服务在收到连接后、记入日志前即发生错误，推断为Windows文件系统ACL权限问题。

步骤 2.9: 最终修复 - Windows 文件系统 ACL 权限

原因分析: sshd服务以SYSTEM账户身份运行，但SYSTEM账户无权访问属于yan02用户目录下的authorized_keys文件。

解决方案: 在服务端，以管理员身份运行PowerShell，执行以下脚本以精确重置文件权限。

命令:

$authorizedKeysFile = "C:\Users\yan02\.ssh\authorized_keys"
$acl = Get-Acl $authorizedKeysFile
$acl.SetOwner([System.Security.Principal.NTAccount]"yan02")
$acl.Access | ForEach-Object { $acl.RemoveAccessRule($_) } | Out-Null
$acl.SetAccessRuleProtection($true, $false)
$acl.AddAccessRule((New-Object System.Security.AccessControl.FileSystemAccessRule("yan02", "FullControl", "Allow")))
$acl.AddAccessRule((New-Object System.Security.AccessControl.FileSystemAccessRule("SYSTEM", "FullControl", "Allow")))
$acl.AddAccessRule((New-Object System.Security.AccessControl.FileSystemAccessRule("Administrators", "FullControl", "Allow")))
Set-Acl $authorizedKeysFile $acl

操作: 重启 sshd 服务。
- 命令: Restart-Service sshd

步骤 2.10: 最终验证

操作: 客户端再次尝试连接。
结果: 连接成功。实现了无需密码的密钥认证登录。

3. 核心问题总结

本次配置过程中的关键障碍点为Windows环境下OpenSSH服务的权限问题。最终成功是基于以下关键修复：

停用sshd_config中针对administrators组的AuthorizedKeysFile路径覆盖规则。
修正authorized_keys文件的ACL权限，确保运行sshd服务的SYSTEM账户，拥有对用户目录下authorized_keys文件的完全控制权限。