在 Cursor 、 Vscode 中配置 SFTP 实现安全的手动文件上传

前言

在开发过程中，我们经常需要将本地代码上传到服务器进行部署。虽然现代开发流程中 Git 部署和 CI/CD 已经非常普及，但在某些场景下，手动上传文件仍然是必要的。比如：

快速修复线上 bug 需要立即部署
开发环境与生产环境差异较大
服务器环境特殊，无法使用自动化部署
需要精确控制上传的文件和时机

本文将详细介绍如何在 Cursor 编辑器中配置 SFTP，实现安全、高效的手动文件上传。

为什么选择 SFTP？

在众多文件传输协议中，SFTP（SSH File Transfer Protocol）具有以下优势：

安全性：基于 SSH 协议，所有数据传输都经过加密
可靠性：支持断点续传和文件完整性校验
跨平台：支持 Windows、macOS、Linux 等所有主流操作系统
权限管理：可以精确控制文件访问权限

准备工作

1. 安装 SFTP 扩展

首先，我们需要在 Cursor 中安装 SFTP 扩展：

按 Ctrl+Shift+X 打开扩展面板
搜索 "SFTP"
推荐安装以下扩展之一：
- "SFTP" by Natizyskunk（最受欢迎，功能最全面）
- "FTP-Simple" by humy2833（轻量级选择）
- "SFTP/FTP sync" by Natizyskunk（专注于同步功能）

2. 生成 SSH 密钥对

为了安全起见，我们使用 SSH 密钥认证而不是密码认证：

bash 复制代码

# 生成 RSA 密钥对
ssh-keygen -t rsa -b 4096 -C "your-email@example.com"

# 或者生成更安全的 Ed25519 密钥对
ssh-keygen -t ed25519 -C "your-email@example.com"

生成过程中会提示：

密钥保存位置（建议使用默认位置）
密码短语（可选，但建议设置）

3. 查看公钥内容

bash 复制代码

# Windows
type C:\Users\YourUsername\.ssh\id_rsa.pub

# macOS/Linux
cat ~/.ssh/id_rsa.pub

公钥内容类似：

复制代码

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDi3wPVWYxgcFwaz+DH7mT8k9DOe78PeSF8qe+31guQ1qf7P+CJg4eZy87EFm9fQNtzwzTqcmVl+bmFJ1I/B4AknWRFF6VNrVeRUfGvhCgf07bCIq3LkaoAvDMu76U3SNPpAZprAodAuOlSa2RDTisoJ1YDH0XemUn7R1+Ofz3wD6NFawukh1zxduMxc75tO25SGDdx1PHyCt9D5LnofbCcmwqQs0gS+XzJahAL3UA1C4kRVSIvhMaknaJ/jz1Zd2b0RaptKVS0Y+TblhHivqYwaGcElvrzvRz8Aa7GpFdC138AzzSMph7PbCe5KWM13L5HkWwUU4MJQZM4tGPUo9iNd8fdYTo2nilRkuLpDd81YFoGMvXgScjHAIySX7ls/XUnIHw3yXMKmRuUjTh3bmPPE4rl9lNcKc+adWHWyU1DnE9DEPm2izbRlolaqf2Yueyk7H7XCCn+pg3g6OmlxVBhSYpD8XMEXMiYgYmCgTKyd/cxG4gjK+A6 your-email@example.com

配置 SFTP 连接

1. 创建配置文件

在项目根目录创建 .vscode/sftp.json 文件：

json 复制代码

{
    "name": "Production Server",
    "host": "your-server-ip",
    "protocol": "sftp",
    "port": 22,
    "username": "your-username",
    "privateKeyPath": "C:\\Users\\YourUsername\\.ssh\\id_rsa",
    "remotePath": "/path/to/your/project",
    "uploadOnSave": false,
    "ignore": [
        ".vscode",
        ".git",
        ".gitignore",
        ".DS_Store",
        "node_modules",
        "vendor",
        "runtime",
        "composer.lock",
        ".env",
        "*.log",
        "*.tmp",
        "*.cache"
    ],
    "watcher": {
        "files": "**/*",
        "autoUpload": false,
        "autoDelete": false
    },
    "syncOption": {
        "delete": false
    }
}

2. 配置参数详解

name: 连接名称，用于标识不同的服务器
host: 服务器 IP 地址或域名
protocol: 传输协议，使用 "sftp"
port: SSH 端口，通常为 22
username: 服务器用户名
privateKeyPath: 私钥文件路径
remotePath: 服务器上的项目路径
uploadOnSave: 是否在保存时自动上传（建议设为 false）
ignore: 忽略的文件和目录列表
watcher: 文件监听配置
syncOption: 同步选项

3. 将公钥添加到服务器

方法一：使用 ssh-copy-id（推荐）

bash 复制代码

ssh-copy-id -i ~/.ssh/id_rsa.pub username@server-ip

方法二：手动添加

bash 复制代码

# 连接到服务器
ssh username@server-ip

# 创建 .ssh 目录
mkdir -p ~/.ssh
chmod 700 ~/.ssh

# 创建或编辑 authorized_keys 文件
touch ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

# 添加公钥
echo "your-public-key-content" >> ~/.ssh/authorized_keys

4. 测试连接

bash 复制代码

# 测试 SSH 连接
ssh -i ~/.ssh/id_rsa username@server-ip "echo 'Connection successful'"

# 或者在 Cursor 中使用命令面板测试
# Ctrl+Shift+P → "SFTP: Test Connection"

使用 SFTP 功能

1. 基本操作

上传文件

右键菜单：在文件资源管理器中右键点击文件 → "SFTP: Upload"
命令面板 ：Ctrl+Shift+P → "SFTP: Upload Active File"
快捷键：可以自定义快捷键

上传项目

命令面板 ：Ctrl+Shift+P → "SFTP: Upload Project"

下载文件

右键菜单：右键点击文件 → "SFTP: Download"
命令面板 ：Ctrl+Shift+P → "SFTP: Download"

2. 高级功能

同步功能

本地到远程 ：Ctrl+Shift+P → "SFTP: Sync Local → Remote"
远程到本地 ：Ctrl+Shift+P → "SFTP: Sync Remote → Local"

文件比较

命令面板 ：Ctrl+Shift+P → "SFTP: Compare Active File with Remote"

浏览远程文件

命令面板 ：Ctrl+Shift+P → "SFTP: Browse Remote"

实际应用场景

1. PHP 项目部署

以本文中的 Webman 框架项目为例：

json 复制代码

{
    "name": "Webman Production",
    "host": "159.75.104.212",
    "protocol": "sftp",
    "port": 22,
    "username": "root",
    "privateKeyPath": "C:\\Users\\Administrator\\.ssh\\id_rsa",
    "remotePath": "/www/askme-webman",
    "uploadOnSave": false,
    "ignore": [
        ".vscode",
        ".git",
        "vendor",
        "runtime",
        "composer.lock",
        ".env",
        "*.log"
    ]
}

2. 多环境配置

可以为不同环境创建不同的配置文件：

json 复制代码

// .vscode/sftp-dev.json
{
    "name": "Development Server",
    "host": "dev-server-ip",
    "remotePath": "/var/www/dev-project"
}

// .vscode/sftp-prod.json
{
    "name": "Production Server", 
    "host": "prod-server-ip",
    "remotePath": "/var/www/prod-project"
}

3. 团队协作

在团队中，每个开发者可以有自己的配置文件：

json 复制代码

{
    "name": "Team Server",
    "host": "team-server-ip",
    "username": "developer-username",
    "privateKeyPath": "~/.ssh/team_key"
}

安全最佳实践

1. 密钥管理

使用强密码：为 SSH 密钥设置强密码短语
定期轮换：定期更换 SSH 密钥
权限控制：确保私钥文件权限为 600

bash 复制代码

chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub

2. 服务器安全

禁用密码认证：在服务器上禁用密码登录
限制用户权限：使用非 root 用户进行部署
防火墙配置：只允许特定 IP 访问 SSH 端口

3. 配置文件安全

添加到 .gitignore：确保 SFTP 配置文件不被提交到版本控制
环境变量：敏感信息可以使用环境变量

json 复制代码

{
    "host": "${SFTP_HOST}",
    "username": "${SFTP_USERNAME}",
    "privateKeyPath": "${SSH_KEY_PATH}"
}

故障排除

1. 常见问题

连接被拒绝

bash 复制代码

# 检查 SSH 服务状态
sudo systemctl status sshd

# 检查防火墙设置
sudo ufw status

权限被拒绝

bash 复制代码

# 检查文件权限
ls -la ~/.ssh/
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub

密钥不被接受

bash 复制代码

# 检查 authorized_keys 文件
cat ~/.ssh/authorized_keys

# 重新添加公钥
ssh-copy-id -i ~/.ssh/id_rsa.pub username@server-ip

2. 调试技巧

启用 SSH 详细日志

bash 复制代码

ssh -v -i ~/.ssh/id_rsa username@server-ip

检查 SFTP 扩展日志

打开 Cursor 的输出面板
选择 SFTP 扩展的输出
查看详细的连接和传输日志

性能优化

1. 传输优化

压缩传输：启用 SSH 压缩
并行传输：配置多个并发连接
增量同步：只传输修改的文件

2. 网络优化

使用 SSH 连接复用：减少连接建立时间
配置 SSH 客户端：优化连接参数

bash 复制代码

# ~/.ssh/config
Host your-server
    HostName your-server-ip
    User your-username
    IdentityFile ~/.ssh/id_rsa
    Compression yes
    ControlMaster auto
    ControlPath ~/.ssh/control-%h-%p-%r
    ControlPersist 1h

总结

通过本文的详细指导，你已经学会了如何在 Cursor 中配置 SFTP 进行安全的手动文件上传。这种方法的优势包括：

安全性高：使用 SSH 密钥认证，数据传输加密
操作简单：集成在编辑器中，操作便捷
功能丰富：支持文件同步、比较等高级功能
可定制性强：可以根据项目需求灵活配置

在实际开发中，建议将 SFTP 上传作为自动化部署的补充，用于快速修复和紧急部署场景。对于常规的代码部署，仍然推荐使用 Git 工作流和 CI/CD 流程。

记住，安全永远是第一位的。定期更新密钥、监控访问日志、遵循最小权限原则，这些都是确保部署安全的重要措施。

希望这篇文章能帮助你在开发工作中更加高效地管理文件上传和部署流程！