Redwood Baremetal 部署磁盘空间检查机制freeSpaceRequired 配置、默认值与排障实践【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood本篇文章基于 Redwood 仓库中的变更记录 .changesets/11638.md 展开深入解析该 breaking change 引入的裸金属baremetal部署磁盘空间硬性校验当目标服务器剩余空间不足时部署流程会直接抛出错误并中止而不是在磁盘写满时失败。读完本文你将掌握freeSpaceRequired配置项的作用域、默认值与校验规则理解df检查在部署生命周期中的位置与底层实现并学会在真实部署中配置、跳过或排查这一检查。一次 breaking change 的背景为什么部署前要查磁盘.changesets/11638.md的内容只有一行breaking(baremetal): Throw an error if there is not enough available space (#11638) by Tobbe它传达的信息非常明确Redwood 的 baremetal 部署命令yarn rw deploy baremetal environment从该版本起会在检测到服务器可用磁盘空间不足时抛出错误并终止部署而不是继续执行克隆、安装依赖、构建等后续步骤。之所以标记为breaking是因为此前的行为并不会因为空间不足而中断——一旦部署进行到git clone、yarn install或构建阶段才发现磁盘已满往往已经造成了半成品发布目录、不完整的依赖树等难以收拾的状态。现在这个检查被前置到部署的最开始把“失败”提前到代价最小的时刻。从源码结构看这一能力由 packages/cli/src/commands/deploy/baremetal.js 中的df任务承载是整个部署任务链deployTasks的第一个任务紧跟在 SSH 连接成功之后执行。磁盘空间检查在部署生命周期中的位置官方文档 docs/docs/deploy/baremetal.md 将一次 baremetal 部署描述为按顺序执行的若干步骤磁盘检查排在第一位df—— 确认服务器上有足够的可用磁盘空间git clone --depth1—— 拉取最新代码为新的发布目录创建指向应用目录共享.env的符号链接yarn install—— 安装依赖执行 Prisma 数据库迁移生成 Prisma Client执行数据迁移data migrations构建 web / api 侧将最新发布目录符号链接为current重启服务进程清理旧的发布目录在 baremetal.js 的实现中df任务是deployTasks里第一个被 push 进任务列表的任务标题为Checking available disk space...。它先于update克隆、symlinkEnv、install、migrate、build、symlinkCurrent、restart和cleanup执行因此只要磁盘检查不通过后续所有高开销操作都不会发生。核心实现剖析df 任务是如何工作的磁盘检查并非在本地执行而是通过 SSH 在目标服务器上运行df命令再对输出进行解析与比较。baremetal.js 中的关键命令为df serverConfig.path | awk NR 2 {print df:$4}即取出df输出第二行文件系统数据行的第 4 列可用块数并加上df:前缀标记。随后按以下逻辑处理baremetal.js过滤噪声输出SSH 非交互会话可能在真实输出前附带Non-interactive shell detected之类的提示行因此代码用stdout.split(\n).find((line) line.startsWith(df:))找到带标记的那一行。取不到信息的兜底如果找不到df:行或该行为空任务会以警告Warning: Could not get disk space information跳过而不是让部署失败——因为某些受限环境可能拿不到df输出。解析失败兜底把数字部分parseInt(df.replace(df:, ), 10) / 1024换算成 MB若结果为NaN则警告Warning: Could not parse disk space information并跳过。空间比较与硬失败将当前可用空间MB与阈值freeSpaceRequired比较若不足则抛出错误错误信息形如Not enough disk space. You need at least 2048MB free space to continue. (Currently 1832MB available)需要说明的是可用空间数值来自df第 4 列以 1024 字节块为单位除以 1024 得到 MB因此单位换算与df的输出格式强相关。--verbose模式下任务还会通过task.output输出Available disk space: xxxMB便于调试。默认值与 CLI 开关DEFAULT_SERVER_CONFIGbaremetal.js中定义了磁盘检查相关的默认值export const DEFAULT_SERVER_CONFIG { port: 22, branch: main, packageManagerCommand: yarn, monitorCommand: pm2, sides: [api, web], keepReleases: 5, freeSpaceRequired: 2048, }即默认要求服务器至少剩余2048 MB2 GB可用空间。命令行的--df选项baremetal.js默认值为true用于总开关控制--df Check available disk space [boolean] [default: true]df任务在两个条件下会被跳过skip判定见 baremetal.js命令行传入了--no-df即yargs.df false配置中freeSpaceRequired为0或0。deploy.toml 配置指南yarn rw setup deploy baremetal会在项目根目录生成deploy.toml。模板文件 packages/cli/src/commands/setup/deploy/templates/baremetal.js 中已经包含了该配置项[[production.servers]] host server.com username user agentForward true sides [api,web] packageManagerCommand yarn monitorCommand pm2 path /var/www/app processNames [serve] repo gitgithub.com:myorg/myapp.git branch main keepReleases 5 freeSpaceRequired 2048官方文档 docs/docs/deploy/baremetal.md 对该字段的说明是freeSpaceRequired- [可选] 服务器上要求的可用空间大小单位为 MB默认 2048 MB。可设置为0跳过检查。配置值校验规则verifyServerConfigbaremetal.js会对该值做严格校验不合法时抛出freeSpaceRequired must be an integer 0根据 packages/cli/src/commands/deploy/tests/baremetal.test.js 中的测试用例以下写法都会被拒绝非法写法拒绝原因freeSpaceRequired not a number字母字符串freeSpaceRequired 100.5/100.5浮点数含字符串形式freeSpaceRequired 3GB/2048 MB携带单位freeSpaceRequired -1/-1负数而以下写法是合法的baremetal.test.jsfreeSpaceRequired 0或0—— 合法用于显式跳过磁盘检查freeSpaceRequired 2024之类的正整数 —— 合法。结论是该字段只接受以 MB 为单位的非负整数不支持GB、MB等带单位的写法也不接受小数。环境变量插值与redwood.toml类似deploy.toml支持${VAR:default}形式的环境变量插值。配置解析经由 baremetal.js 中的parseConfig先调用string-env-interpolation对环境变量进行替换再交给smol-toml解析为 TOML 对象。因此你可以把磁盘阈值提升为环境变量驱动例如[[production.servers]] host ${PROD_HOST:server.com} path /var/www/app repo gitgithub.com:myorg/myapp.git freeSpaceRequired ${FREE_SPACE_REQUIRED:2048}注意插值发生在 TOML 解析之前替换后的值最终仍需满足“非负整数”的校验若环境变量提供了非法值部署会在verifyServerConfig阶段报错。命令行实操触发、跳过与查看帮助完整命令可通过yarn rw deploy baremetal --help查看对应 baremetal.js 中 yargs 定义的选项。正常部署默认执行磁盘检查要求剩余空间 ≥ 2048 MByarn rw deploy baremetal production首次部署同样包含磁盘检查yarn rw deploy baremetal production --first-run跳过磁盘检查两种等价写法yarn rw deploy baremetal production --no-df yarn rw deploy baremetal production --dffalse把阈值调大例如要求剩余 4 GBfreeSpaceRequired 4096把检查彻底关掉等价于--no-df的效果freeSpaceRequired 0失败时的表现磁盘不足时部署会被Listr任务链中止handler捕获异常后以红色边框boxen打印错误并process.exitbaremetal.js。控制台将看到形如下面的输出并退出码非 0Not enough disk space. You need at least 2048MB free space to continue. (Currently 1832MB available)由于该任务是第一个部署步骤此时服务器上不会产生新的发布目录也不会执行任何克隆、安装或构建避免了对既有运行的污染。测试验证行为如何被锁定baremetal.test.js 用 mock 的ssh.exec返回值验证了磁盘检查的完整行为矩阵默认任务列表9 个任务第一个即Checking available disk space...baremetal.test.js。--no-df跳过检查df: false时tasks[0].skip()为真baremetal.test.js。freeSpaceRequired 0跳过检查baremetal.test.js。空间不足抛错mockdf:1875893约 1832 MB且未配置freeSpaceRequired时抛出Not enough disk space. You need at least 2048MB free space to continue. (Currently 1832MB available)baremetal.test.js。自定义阈值生效freeSpaceRequired: 4096且可用约 3785 MBdf:3875893时抛出需要 4096 MB 的错误baremetal.test.js。拿不到信息时降级为警告stdout为空时跳过并警告Could not get disk space informationbaremetal.test.js。解析失败时降级为警告stdout为df:/dev/sda1这类无法解析的内容时警告Could not parse disk space informationbaremetal.test.js。这些用例同时覆盖了verifyServerConfig对freeSpaceRequired的 10 余种合法/非法输入校验意味着“非负整数、以 MB 为单位”的约束是被测试锁定的稳定契约。排障实践遇到磁盘空间错误怎么办确认当前剩余空间SSH 到目标服务器执行df -h path对照deploy.toml中path所在分区判断实际可用空间。临时放行若只是紧急发布、空间确属紧张可用--no-df或临时将freeSpaceRequired调低/置 0 放行但应尽快清理磁盘。清理旧发布cleanup任务默认只保留keepReleases默认 5个发布目录。若空间被历史发布占满可手动清理path下时间戳目录或调低keepReleases。关注非交互 SSH 环境df任务依赖远程df命令可用。若输出被 shell 提示污染导致解析失败部署会以警告跳过而非失败此时应检查部署用户的 shell 配置参见 docs/docs/deploy/baremetal.md 中关于非交互会话的说明。核对单位freeSpaceRequired只接受 MB 单位的非负整数误写3GB、2048 MB、100.5都会在校验阶段直接报错。小结.changesets/11638.md这一行 breaking change背后是一套完整的“前置磁盘体检”机制freeSpaceRequired默认 2048 MB支持在deploy.toml中按服务器覆盖接受严格校验的非负整数可通过--no-df或置 0 跳过df任务通过 SSH 在远端执行df并解析可用块数空间不足时抛出明确错误并中止部署拿不到信息时则降级为警告。无论是理解 Redwood baremetal 部署的可靠性设计还是为自有服务器配置磁盘阈值本文给出的源码路径与测试用例都能作为继续深入的第一手索引。【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考