最近在整理一台 Linux 备份机想找一个能在命令行里直接操作百度网盘的小工具。前后试了几个方案最后留下的是 ByPy命令名是bypy。如果你也有类似需求服务器日志定期同步、数据库备份上传、NAS 异地归档并且不想给 Linux 装图形界面这篇配置指南应该能帮你省下不少排查时间。我会把安装、授权、常用命令、定时备份以及我实际踩过的坑一次讲清楚。不涉及任何非官方手段ByPy 本质上是调用网盘官方开放接口的 Python 客户端。1. ByPy 是什么为什么在服务器上用它1.1 一个没有界面的网盘客户端ByPy 是一个用 Python 写的命令行网盘客户端项目按习惯写成 ByPy终端里对应的命令是bypy。它和 Windows 上常见的网盘客户端不是一回事图形客户端有界面、有托盘、常驻内存ByPy 运行完就退出不占资源只在你需要的时候做一次文件操作。从技术原理上看ByPy 基于 OAuth2 授权模型开发。第一次运行后它会打印一个授权地址你用自己的百度账号在浏览器里同意访问后把授权码回填给终端工具拿到访问令牌后保存到本地配置目录。后续的上传、下载、列目录、删除操作都是调用网盘官方开放接口完成的。这里有一个很多人第一次用会蒙的点ByPy 操作的并不是你网盘根目录下的所有文件而是专门的应用文件夹也就是/apps/bypy。这是网盘对第三方应用的一种权限隔离方式相当于第三方应用只能看到自己的抽屉看不到你网盘里其他私人物品。所以bypy list里的根目录对应的是网页端某个应用数据目录而不是网盘首页。1.2 和手工传文件相比优势在哪里浏览器传文件的痛点是文件多、量大时不方便批量操作服务器上往往也没有浏览器环境或者你只是想在凌晨两点自动把数据库备份推上去总不能每天半夜爬起来拖文件。ByPy 的价值是把网盘操作变成可编程、可脚本化的命令。和同类工具相比ByPy 的优势有三点。第一安装简单pip install bypy一条命令完成依赖少不需要编译。第二跨平台Windows、macOS、Linux 都能跑尤其适合 Linux 服务器、树莓派、NAS。第三命令设计直接上传、下载、同步、对比每个动作就是一个动词容易写进 shell 脚本和计划任务。缺点也有它不是一个全功能网盘客户端不能像桌面客户端那样自动监测本地文件夹变化并实时同步。另外因为走的是第三方应用接口操作速度受接口配额和网络环境影响。如果想做实时多端同步最好还是用官方客户端如果只是想要一个能写进脚本的“命令式网盘”ByPy 非常合适。1.3 适用人群和不适合的场景我实际使用下来最适合三类人一是手上有 Linux 服务器或 NAS需要定期把数据放到网盘做异地备份的人二是写 Python 脚本较多希望文件备份动作融入现有脚本体系的人三是不想为一次性上传安装一个臃肿桌面客户端的人。不太适合的场景也很清楚如果你需要把网盘当日常同步盘用要求本地删文件、远端也跟着删或者需要双向多端实时同步那就不要选 ByPy它的同步逻辑更接近单向备份工具。理解了工具边界后面用起来才不会有错误预期。2. 环境准备与安装2.1 确认 Python 和 pipByPy 需要 Python 3。macOS 一般自带 Python 3Windows 需要自己装Ubuntu/Debian 需要先装python3和python3-pip。开始之前先看版本python --version pip --version如果系统同时存在 Python 2 和 Python 3建议用带数字的命令例如python3 --version pip3 --version看到 Python 3.6 以上且 pip 可用环境就满足条件。如果服务器上已经有业务在跑建议建一个虚拟环境再装不要在全局环境里随便装。原因很简单ByPy 本身依赖不多但升级时会带动一些包更新使用虚拟环境可以减少对现有依赖的干扰。2.2 安装 ByPy确认 pip 后安装很简单pip install bypy之前装过旧版本可以顺便升级pip install -U bypy账号没有系统 Python 包目录的写权限时加上--userpip install --user bypy安装完成后先用帮助命令验证bypy --help如果提示命令找不到在 Windows 上多半是 Python Scripts 目录没有加入 PATH在 Linux 上可以试试python3 -m bypy --help这种调用方式等于通过 Python 解释器执行 ByPy能解决可执行文件路径找不到的问题。2.3 安装后先做四件事装完不要急着上传先把下面四件事做掉确认which bypy能输出真实路径。如果输出为空说明命令不在 PATH 里后面脚本里要改用python3 -m bypy。确认~/.bypy目录是否在授权后正常生成。授权没成功之前这个目录可能不存在。执行一次bypy --help看一眼可用的子命令避免记错名字。如果准备写定时任务先用虚拟环境里的 Python 绝对路径手动执行一次命令确认能和 crontab 环境匹配。我踩过一个小坑在虚拟环境里装了bypy写 crontab 时直接写bypy任务跑不起来。原因很简单crontab 的环境变量和交互式 shell 不一样找不到虚拟环境里的可执行文件。后来把定时任务里的命令全部写成虚拟环境 Python 的绝对路径问题就消失了。3. 授权流程把网盘权限交给命令行3.1 首次授权要做什么环境准备好以后第一次使用先跑一条最简单的命令bypy infoByPy 检测到本地还没有授权信息会打印一个很长的授权地址。你需要把地址完整复制下来粘贴到电脑浏览器的地址栏打开。浏览器会要求登录百度账号然后出现询问是否授权的页面。点击同意后页面会跳转到一个带授权码的地址把授权码复制出来粘贴回终端回车即可。授权码的有效期很短通常只有几分钟。不要先开终端再跑去做别的事等回来再操作。如果你发现页面提示“授权码已过期”或者粘贴后报错不要反复试同一个码重新跑一次bypy info生成新码更快。授权成功后工具内部会利用 OAuth2 的刷新机制在令牌快到期时自动刷新。正常情况下授权一次就可以用很久不用每天重新登录。3.2 配置目录和多个账号授权完成后ByPy 会在用户主目录下创建一个.bypy目录里面保存令牌、文件缓存和日志。Linux 下是~/.bypy/Windows 下是C:\Users\你的用户名\.bypy\。ByPy 提供了--config-dir参数用来指定配置目录。这个参数非常实用如果你有两个百度账号想在同一台机器上分别管理只要各准备一个配置目录就能互不干扰。用法是bypy --config-dir ~/.bypy-work info bypy --config-dir ~/.bypy-home info每个配置目录都做一次独立授权后面的 list、upload 等操作也加上同一个--config-dir参数就能对应不同账号。授权信息保存在配置目录里不要把.bypy目录整个复制到别的机器也不要传到代码仓库。它相当于你的“钥匙串”一旦落到别人手里对方即使不知道密码也能操作这个应用目录下的文件。3.3 应用目录的隔离逻辑授权完后可以先执行bypy list正常情况下会看到一个根目录第一眼可能觉得是空目录这很正常。ByPy 的根目录映射到网盘/apps/bypy。你在网页端登录网盘后从应用数据文件夹里能看到这个目录在命令行里新建的文件夹也会出现在这个应用目录下。知道了这个限制你就明白为什么 ByPy 适合做备份而不适合当“第二个网盘根目录”来用。正常存放在网盘根目录的文件ByPy 看不到。如果备份文件本来就在默认目录使用前要先通过官方客户端或网页端把它们移入应用目录或者在脚本里把备份文件统一放到该目录下。4. 常用命令详解上传、下载、同步和目录管理4.1 查看目录和配额最常用的查看命令# 列出当前应用目录下的文件 bypy list # 列出指定目录 bypy list /logs/2024 # 查看网盘配额和已用空间 bypy quotabypy list会输出文件或目录名、类型、大小和修改时间。如果觉得信息不够加上--verboseByPy 会打印更详细的日志包括请求地址、MD5 校验信息等。刚入门时建议多用--verbose它能让你看到操作是否真的发生了网络请求而不是傻等在缓冲里。4.2 上传文件和目录上传命令的基本格式是bypy upload 本地路径 远端目录把本地 backup 目录上传到远端 ops 目录下bypy upload /home/user/data/backup /ops/2024如果远端目录不存在ByPy 会在上传过程中自动创建。上传目录时ByPy 会保留本地目录结构也就是说/home/user/data/backup/report.pdf上传后对应/ops/2024/report.pdf当然前面还套着/apps/bypy这一层。上传之前我强烈建议先跑一次空载演练bypy --dry-run upload /home/user/data/backup /ops/2024--dry-run的意思是只对比和计算需要上传哪些文件不真正传。这样能提前看到脚本的行为避免误传一个超大的临时目录。4.3 下载文件和目录下载命令的格式相反bypy download 远端路径 本地目录把刚才上传的整个目录拉下来bypy download /ops/2024 /home/user/restore下载单个文件也一样bypy download /ops/2024/report.pdf /home/user/download第一次跑下载时要保证本地目录存在至少保证用户对目录有写入权限。ByPy 一般不会主动帮你创建本地目录。我遇到过目标目录少写了一层导致文件直接下载到上级目录的情况。保险起见脚本里先mkdir -p再执行下载。4.4 同步命令的定位ByPy 的同步命令是syncup和syncdown# 把本地目录同步到远端 bypy syncup /home/user/data /backup/data # 把远端目录同步到本地 bypy syncdown /backup/data /home/user/restore同步的原理是ByPy 会比较本地和远端的文件大小、修改时间和 MD5 值有差异才传输。第二次、第三次跑同一个同步命令时未变化的文件会很快跳过达到近似增量备份的效果。特别要注意ByPy 的同步不是双向自动同步盘那种逻辑。它更像一个带比对能力的单向传输工具。syncup的主要工作是“把新增和更新的文件推上去”并不保证远端一定删除你本地已经删除的文件反之syncdown也不一定会删除本地多余文件。如果你期望“本地删了文件远端也自动删除”需要研究它是否支持删除标记参数并在正式使用前先小范围测试。我的个人建议是把 ByPy 当成备份工具不要当成双向实时同步工具这样对数据安全的预期才不会失控。4.5 目录管理命令除了传输ByPy 还提供基本的文件管理能力# 创建远端目录 bypy mkdir /newfolder # 删除远端文件或目录 bypy delete /oldfolder/expired.zip # 移动或重命名 bypy move /oldfolder/expired.zip /archive/2024/expired.zip # 复制 bypy copy /source.zip /backup/source.zip删除操作不可逆建议在删除前先用bypy list /oldfolder看清目标关键数据先下载备份再执行删除。命令行工具没有“回收站”的概念这和网页端删了还能找回的逻辑不一样所以delete要用得谨慎。4.6 几个关键选项的用法ByPy 常见的选项包括--verbose输出详细日志适合定位问题。--dry-run只计算差异不真正传输。--retry N网络失败时自动重试 N 次。--timeout N设置请求超时秒数。--config-dir PATH指定配置目录。组合使用效果很好。比如网络波动较大的场景可以这样写bypy --retry 5 --timeout 60 --verbose upload /data/large.tar.gz /backup/large我建议在脚本里固定几个选项不要每次手工输入一堆。命令越固定出问题的概率越低。5. 实际场景用定时任务实现自动备份5.1 写一个 Linux 备份脚本现在把命令组合起来做一个每天凌晨自动备份的脚本。假设本地备份源是/data/mysql_backup远端目标是/daily/mysql。先写脚本#!/bin/bash # 把虚拟环境中 bypy 的绝对路径放到脚本里 BYPY/home/user/backup_venv/bin/bypy DATE$(date %Y%m%d) # 创建当天日期目录 $BYPY mkdir /daily/mysql/$DATE # 执行同步 $BYPY syncup /data/mysql_backup /daily/mysql/$DATE /home/user/logs/bypy_backup.log 21逻辑是先用date生成当天日期作为远端目录名这样每天备份进一个新的日期目录不会互相覆盖然后把本地目录同步到当天的远端目录。和21是为了把输出和错误日志保留到本地日志文件方便第二天早晨排查。脚本写好后授予执行权限并加入 crontabchmod x /home/user/bin/backup_mysql.sh crontab -e在 crontab 里加0 2 * * * /home/user/bin/backup_mysql.sh意思就是每天凌晨两点整运行一次。为什么选凌晨两点因为凌晨通常是业务低峰期网盘压力小备份脚本本身占用的 CPU 也不算高。5.2 首次运行前把检查放在前面定时任务里的坑我在开头提过环境变量问题。另外还有两个容易忽略的点。第一crontab 中的命令路径、脚本路径都建议写绝对路径。即使路径中出现空格也要用引号包起来因为 crontab 默认的环境变量很干净不一定包含你手动安装的 Python 目录。第二第一次跑定时任务之前先手工执行一次脚本确认能跑通。手工执行和定时执行的差别往往就在环境变量上。如果你在交互式 shell 下跑没问题但 crontab 里报“找不到 bypy”十有八九是路径问题或者脚本开头的#!/bin/bash路径不对。5.3 Windows 环境下的自动备份Windows 下思路类似只是调度工具变成任务计划程序。把 ByPy 命令写进一个.bat文件echo off set PYTHONC:\Python312\python.exe %PYTHON% -m bypy syncup D:\data\backup /daily\windows D:\logs\bypy.log 21然后在任务计划程序里创建每日任务触发器设为每天凌晨操作指定这个.bat文件。这里仍要用python.exe的绝对路径不要直接写bypy。在 Windows 上用 ByPy 还有一个注意点任务计划程序默认的起始目录可能不对如果脚本依赖相对路径很容易报文件找不到。最好在脚本开头cd /d D:\data\backup切到固定目录脚本上下文保持一致。5.4 备份脚本里建议叠加的步骤我之前一度只在脚本里写同步命令后来发现有两个问题一是误删后无法找回二是远端文件没有做完整性校验。现在的脚本里会多叠两步。第一步本地先加密或压缩。把要备份的文件用 tar 打包再配合 GnuPG 做对称加密。这样即使网盘账号出现问题泄露出去也是一堆无法直接读取的密文。第二步同步完成后执行一次bypy compare。这个命令会把本地和远程的差异再次打印出来我可以快速确认远端备份和本地是否一致。日志文件和 diff 结果一起保留备份有没有跑成功早上扫一眼就知道。第三步清理过期备份。每天一个日期目录时间久了目录会越来越多。建议在脚本末尾保留最近 N 天的目录更早的直接用bypy delete删除。删除前记得加一个“只保留最近 30 天”的判断避免误删。6. 常见问题与排查技巧实录6.1 授权失败或授权码无效现象复制授权地址到浏览器后页面提示授权码过期或者粘贴回终端后报 token 相关错误。排查步骤确认系统时间准确。OAuth 授权对系统时间很敏感如果服务器时间差了几分钟令牌验证会直接失败。Linux 上用timedatectl看时间必要时开启网络时间同步。授权码有效期只有几分钟务必在生成后立刻使用。如果多次失败删除配置目录里的授权文件后重新执行bypy info。注意是删除.bypy目录里的授权相关文件而不是整个网盘账号。我试过一次最离谱的情况服务器时钟比真实时间快了接近五分钟ByPy 每次授权都报验证失败。后来排查到是虚拟机硬件时间漂移同步时间后立刻就好了。如果你的环境也是虚拟机这个坑值得提前排除。6.2 上传大文件中断现象几个 GB 的文件传到一半网络抖动后报错重新传又要从头开始。我的处理办法是先在本地把大文件拆成 1GB 到 2GB 的分卷压缩包再上传。这样做有三个好处第一单个任务耗时短失败重试的成本低第二远端文件结构更清晰第三可以配合--retry参数让 ByPy 在断网时自动重试。命令像这样bypy --retry 5 --timeout 60 upload /data/large.tar.gz /backup/large另外不要在磁盘空间已经不足的情况下跑上传ByPy 会在本地生成一些临时缓存或日志空间不足时上传会莫名其妙地失败。6.3 网络导致的慢速和超时需要先说明一个原则ByPy 走的是网盘官方开放接口文件传输速度主要受你的网络环境、网盘服务器容量和接口配额影响并没有任何特殊手段能绕过限制。如果网络链路本身不稳定可以调大超时时间并增加重试次数。有些服务器在海外传输速度确实不理想。我的处理方式是分时段执行把定时任务放在当地时间凌晨执行避开繁忙时段。同时不要在脚本里同时跑多个上传任务尽量串行执行减少相互抢占带宽的概率。如果上传下载速度长期低于可用带宽先检查是不是本地磁盘 IO 瓶颈。ByPy 在上传前会计算文件 MD5这个过程需要大量读取磁盘机械硬盘上的表现会明显慢于固态硬盘。先把源文件放到本地高速磁盘上再传输是最直接的排查方向。6.4 常见问题速查表现象可能原因解决办法首次授权后 list 为空正常操作的是/apps/bypy应用目录到网页端应用数据目录查看bypy命令找不到Python Scripts 目录未加入 PATH用python3 -m bypy执行定时任务里报找不到 bypycrontab 环境变量不完整使用绝对路径调用上传速度很慢网络或接口配额限制分卷上传注意避开高峰授权码过期授权码有效期只有几分钟重新执行bypy info报 token 无效时间偏差或令牌损坏同步系统时间重新授权本地删了文件但远端未删同步逻辑不是双向删除手动 delete 或官方工具处理断网后大文件重传单任务失败后没重试使用--retry拆分大文件6.5 个人使用习惯与经验用 ByPy 时间久了我总结出几个固定习惯。第一每个备份任务都对应一个远端目录命名里带日期目录不会越攒越乱。第二所有脚本里保留--dry-run参数开关日常调试时开着真正执行时再关掉。第三动手删除远端数据前一定先bypy list确认路径命令行里路径打错了删错数据的影响比图形界面更隐蔽。还有一点bypy的日志会写到配置目录里默认文件名一般是.log后缀。如果发现命令执行了但没有输出到终端不要着急去配置目录看日志文件很多偶发问题的根因都在日志里。把日志也纳入自己的备份体系会让这个命令行小工具在关键时刻更值得信任。最后再分享一个小技巧尽量把bypy封装成自己的脚本而不是每次都把一串参数打在终端里。比如写一个backup_upload.sh里面统一处理路径、日志、重试和远端目录命名。这样即使隔几个月再回来维护你打开脚本就能明白当时做了什么而不是靠搜索记忆里的命令。