Skip to content

USAGE.md

Latest commit

 

History

History
155 lines (111 loc) · 4.7 KB

USAGE.md

File metadata and controls

155 lines (111 loc) · 4.7 KB

XDS 工具使用说明

工具概述

XDS 是一个便捷的 SSH 服务器管理工具，主要功能包括：

  1. 列出服务器 (xds list) - 自动读取 ~/.ssh/config 并显示所有配置的服务器
  2. 设置默认服务器 (xds set <server>) - 设置默认服务器，后续操作无需重复指定
  3. 上传文件 (xds upload <local> <remote>) - 快速上传文件到服务器
  4. 下载文件 (xds download <remote> <local>) - 快速从服务器下载文件

设计改进建议

基于你的初始想法，我做了以下完善：

1. 增强的命令行体验

  • ✅ 使用 kingpin 库提供更好的命令行参数解析
  • ✅ 支持 -s/--server 参数临时指定服务器，不改变默认设置
  • ✅ 清晰的错误提示和使用建议

2. 智能的服务器管理

  • ✅ 自动读取 ~/.ssh/config，无需额外配置
  • ✅ 支持默认服务器设置，提高使用效率
  • ✅ 配置文件保存在 ~/.xds/config.json

3. 完善的认证支持

  • ✅ 支持 SSH 密钥文件认证（通过 IdentityFile 配置）
  • ✅ 支持 SSH agent 认证（如果未配置密钥文件）
  • ✅ 清晰的错误提示，帮助用户排查认证问题

4. 用户友好的输出

  • ✅ 上传/下载时显示文件大小和传输结果
  • ✅ list 命令显示服务器详细信息
  • ✅ 标记默认服务器，一目了然

可能的扩展功能（未来改进）

如果你想要更多功能，可以考虑：

  1. 目录传输支持

    • xds upload -r ./local_dir /remote/dir - 递归上传目录
    • xds download -r /remote/dir ./local_dir - 递归下载目录

  2. 批量操作

    • xds upload-multi file1 file2 file3 /remote/ - 一次上传多个文件
    • xds download-multi /remote/file1 /remote/file2 ./ - 一次下载多个文件

  3. 连接测试

    • xds test <server> - 测试服务器连接是否正常

  4. 快速 SSH 连接

    • xds connect 或 xds ssh - 快速连接到默认服务器
    • xds connect <server> - 连接到指定服务器

  5. 服务器信息显示

    • xds info <server> - 显示服务器的详细信息

  6. 进度条显示

    • 大文件传输时显示进度条

  7. 配置文件管理

    • xds config show - 显示当前配置
    • xds config reset - 重置配置

使用示例

基本工作流

# 1. 查看所有可用的服务器
xds list

# 2. 设置默认服务器（只需要设置一次）
xds set aliyun_DSW3

# 3. 上传文件（使用默认服务器）
xds upload ./myfile.txt /data/myfile.txt

# 4. 下载文件（使用默认服务器）
xds download /data/result.txt ./result.txt

# 5. 临时使用其他服务器（不改变默认设置）
xds upload -s test_server ./test.txt /tmp/test.txt

高级用法

# 下载文件到当前目录（自动使用远程文件名）
xds download /data/config.json .

# 上传文件并指定服务器
xds upload -s backup_server ./backup.tar.gz /backups/

编译和安装

# 进入项目目录
cd xds

# 安装依赖
go mod download

# 编译
make

# 安装到系统（可选）
make install

注意事项

  1. SSH 配置要求：确保你的 ~/.ssh/config 文件格式正确，XDS 会读取其中的 Host 配置
  2. 认证方式：优先使用 IdentityFile 配置的密钥，如果没有则尝试 SSH agent
  3. 默认服务器：建议先设置默认服务器，这样后续操作更便捷
  4. 路径处理：本地路径支持相对路径和绝对路径，远程路径必须是绝对路径

错误排查

问题：找不到服务器配置

解决：使用 xds list 查看所有可用服务器，确保服务器名称拼写正确

问题：SSH 连接失败

解决：

  • 检查 ~/.ssh/config 中的 HostName 和 Port 是否正确
  • 确保网络连接正常
  • 检查防火墙设置

问题：认证失败

解决：

  • 确保 IdentityFile 指向的密钥文件存在且权限正确（chmod 600）
  • 如果使用 SSH agent，确保 ssh-add 已添加密钥
  • 检查密钥是否已添加到目标服务器

问题：文件传输失败

解决：

  • 检查远程路径的目录是否存在
  • 检查文件权限
  • 确保有足够的磁盘空间

与 AI 协作使用

这个工具设计时考虑了 AI 的使用场景：

  1. 清晰的命令结构：AI 可以轻松理解和使用这些命令
  2. 详细的错误提示：帮助 AI 快速定位和解决问题
  3. 一致的接口：所有命令遵循相同的模式，便于 AI 记忆和使用
  4. 完善的文档：README 和 USAGE 文档提供了完整的使用说明

AI 可以这样使用：

  • 快速上传文件到服务器进行分析
  • 下载服务器上的处理结果
  • 在多个服务器之间传输文件
  • 自动化文件管理任务