KM Dev Instance

自动创建本地 SSH 配置并在 VSCode 中打开远程开发环境的扩展。

功能

• 一键创建 SSH 配置文件到 ~/.ssh/km/ 目录
• 自动更新 ~/.ssh/config 添加 Include 语句
• 自动打开 VSCode Remote-SSH 连接
• 跨平台支持：Windows、macOS、Linux

平台兼容性

Windows 特别说明

1. OpenSSH 客户端：Windows 10/11 内置 OpenSSH，需确保已启用

   • 设置 → 应用 → 可选功能 → 添加功能 → OpenSSH 客户端

2. SSH 目录位置：C:\Users\<用户名>\.ssh\

3. 路径处理：扩展会自动将 Windows 路径（\）转换为 SSH 配置格式（/）

使用方法

开发和测试

1. 安装依赖

   cd vscode-extension
   npm install
   

2. 调试扩展

   • 在 VSCode 中打开 vscode-extension 目录
   • 按 F5 启动调试（会打开一个新的 VSCode 窗口）
   • 在新窗口中按 Cmd+Shift+P (macOS) 或 Ctrl+Shift+P (Windows/Linux)
   • 输入 KM: Open Dev Instance 并执行
   • 扩展会自动创建配置并连接到远程环境

安装扩展

1. 打包扩展

   # 安装 vsce 工具
   npm install -g @vscode/vsce
   
   # 打包扩展
   vsce package
   

   这会生成一个 .vsix 文件。

2. 安装到 VSCode

   • 打开 VSCode
   • 进入扩展面板 (Cmd+Shift+X / Ctrl+Shift+X)
   • 点击右上角的 ... 菜单
   • 选择 "从 VSIX 安装..."
   • 选择生成的 .vsix 文件

3. 使用扩展

   • 按 Cmd+Shift+P (macOS) 或 Ctrl+Shift+P (Windows/Linux) 打开命令面板
   • 输入 KM: Open Dev Instance
   • 执行命令

通过 URI Scheme 连接

扩展支持通过 URI Scheme 直接唤醒：

vscode://km.km-dev-instance/open-remote?hostName=my-server&hostname=192.168.1.100&port=22&user=root&workspacePath=/root/workspace

参数说明：

• hostName: SSH 连接名称
• hostname: 服务器地址
• port: SSH 端口（可选，默认 22）
• user: 用户名（可选，默认 root）
• identityFile: 私钥路径（可选，默认 ~/.ssh/id_rsa）
• workspacePath: 远程工作目录（可选）

工作原理

1. 解析 URI 参数或读取配置信息
2. 在 ~/.ssh/km/ 目录创建配置文件（如：my-server.conf）
3. 检查并更新 ~/.ssh/config，添加 Include ~/.ssh/km/*.conf
4. 使用 VSCode Remote-SSH 扩展的 API 打开远程连接

配置示例

macOS/Linux 生成的配置

Host test-dev-server
    HostName 117.50.172.62
    Port 32177
    User root
    IdentityFile ~/.ssh/id_rsa
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

Windows 生成的配置

Host test-dev-server
    HostName 117.50.172.62
    Port 32177
    User root
    IdentityFile C:/Users/username/.ssh/id_rsa
    StrictHostKeyChecking no
    UserKnownHostsFile NUL

前置要求

• VSCode 版本 >= 1.75.0
• 已安装 Remote-SSH 扩展
• OpenSSH 客户端
  • macOS/Linux: 系统内置
  • Windows: 需在可选功能中启用

自定义配置

支持多个环境

如果需要支持多个 SSH 环境，可以修改 extension.js 添加配置选择：

// 定义多个配置
const SSH_CONFIGS = {
    'dev': {
        hostName: 'dev-server',
        hostname: '192.168.1.100',
        // ...
    },
    'staging': {
        hostName: 'staging-server',
        hostname: '192.168.1.101',
        // ...
    }
};

// 在命令中让用户选择
const selected = await vscode.window.showQuickPick(Object.keys(SSH_CONFIGS), {
    placeHolder: '选择要连接的环境'
});

const config = SSH_CONFIGS[selected];

从配置文件读取

也可以从 VSCode 设置或外部配置文件读取：

// 从 VSCode 配置读取
const config = vscode.workspace.getConfiguration('km-dev-instance');
const sshConfig = config.get('sshConfig');

// 从 JSON 文件读取
const configPath = path.join(__dirname, 'config.json');
const sshConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));

故障排除

扩展无法加载

• 确保已运行 npm install 安装依赖
• 检查 VSCode 版本是否满足要求

SSH 连接失败

• 检查服务器地址和端口是否正确
• 确保私钥文件存在且权限正确
  • macOS/Linux: chmod 600 ~/.ssh/id_rsa
  • Windows: 使用文件属性设置权限
• 检查网络连通性

Windows 特定问题

1. 找不到 SSH 命令

   • 确认已安装 OpenSSH 客户端
   • 检查 PATH 环境变量是否包含 OpenSSH 路径

2. 权限被拒绝

   • 右键私钥文件 → 属性 → 安全 → 高级
   • 禁用继承，删除所有用户，只添加当前用户

3. 路径格式错误

   • 扩展会自动处理路径格式，如仍有问题请提交 issue

权限错误

扩展会自动设置正确的文件权限：

• macOS/Linux:
  • ~/.ssh 和 ~/.ssh/km 目录: 700
  • 配置文件: 600
• Windows:
  • 使用 Windows ACL 管理权限

开发

项目结构：

vscode-extension/
├── extension.js        # 扩展主文件（跨平台兼容）
├── package.json        # 扩展清单
├── .vscode/
│   └── launch.json    # 调试配置
└── README.md          # 说明文档

跨平台开发说明

扩展使用以下策略实现跨平台兼容：

1. 路径处理：使用 path.join() 处理本地路径，SSH 配置中使用正斜杠
2. 权限设置：仅在 Unix 系统设置文件权限，Windows 使用 ACL
3. Null 设备：Unix 使用 /dev/null，Windows 使用 NUL
4. 平台检测：使用 process.platform 检测操作系统

License

MIT