开发工具前端【免费下载链接】PubliiThe most intuitive Static Site CMS designed for SEO-optimized and privacy-focused websites.项目地址https://gitcode.com/gh_mirrors/pu/Publii点击查看免费下载node-ftpnpm 包名ftp是一个面向 node.js 的 FTP 客户端模块它提供了与 FTP 服务器通信的完整异步接口连接、认证、列目录、上传下载、文件操作等能力全部以事件与回调的方式暴露。在 Publii 这个开源静态站点 CMS 中node-ftp 被作为 vendored 依赖内置于 app/back-end/modules/custom-changes/ftp 目录是 Publii FTP(S) 部署链路的底层传输引擎。读完本文你将完整掌握 node-ftp 的安装方式、事件模型、全部 API含 RFC 959 / RFC 3659 命令分层、连接配置项及其默认值并理解 Publii 是如何基于它实现同步上传、增量删除与连接测试的。一、模块定位Publii 中的 FTP 传输引擎在 Publii 仓库中node-ftp 以custom-changes定制改动目录形式随源码分发。从 package.json 可以看到其版本锁定为ftp^0.3.10即 0.3.10声明依赖readable-stream 1.1.x与xregexp 2.0.0入口文件为./lib/connection引擎要求node 0.8.0采用 MIT 协议。Publii 对它的消费位于 app/back-end/modules/deploy/ftp.jsFTP部署类直接require(./../custom-changes/ftp)创建客户端实例实现站点静态文件到 FTP(S) 服务器的同步。可以推断Publii 将第三方模块以源码形式 vendored 进仓库是为了在不依赖运行时 npm 安装的情况下保证可移植性与版本可控。二、环境要求与安装原文档明确的环境要求为node.js —— v0.8.0 或更新版本安装方式常规 npm 用法npm install ftp从源码层面看模块由 lib/connection.js客户端主体约 1070 行与 lib/parser.js响应与列表解析器组成。connection.js顶层引入了fs、tls、zlib、net.Socket与events.EventEmitter这决定了它天然支持 TLS/SSL 加密连接、gzip 压缩传输MODE Z以及基于事件流的异步模型。三、快速上手三个典型示例原文档提供了三个直接可运行的示例完整保留如下并补充源码层面的解读。3.1 获取远程工作目录列表var Client require(ftp); var c new Client(); c.on(ready, function() { c.list(function(err, list) { if (err) throw err; console.dir(list); c.end(); }); }); // connect to localhost:21 as anonymous c.connect();ready事件表示连接与认证全部完成此时才能安全发起命令。list()返回的数组项由 parser.js 中的parseListEntry解析生成——它内置了 UnixREX_LISTUNIX与 MS-DOSREX_LISTMSDOS两套目录列表正则自动识别type/rights/owner/group/size/date等字段。3.2 下载远程文件到本地var Client require(ftp); var fs require(fs); var c new Client(); c.on(ready, function() { c.get(foo.txt, function(err, stream) { if (err) throw err; stream.once(close, function() { c.end(); }); stream.pipe(fs.createWriteStream(foo.local-copy.txt)); }); }); // connect to localhost:21 as anonymous c.connect();get()的回调会收到一个可读流fileStream这正是 Publii 下载远端files.publii.json清单时使用的机制——见 ftp.js 中的downloadFilesList()它将流式 chunk 拼接为完整 JSON 后与本地文件清单比对。3.3 上传本地文件到服务器var Client require(ftp); var fs require(fs); var c new Client(); c.on(ready, function() { c.put(foo.txt, foo.remote-copy.txt, function(err) { if (err) throw err; c.end(); }); }); // connect to localhost:21 as anonymous c.connect();put()的input参数支持可读流、Buffer 或本地文件路径三种形态。在 connection.js 的_store()内部实现中字符串参数会先经fs.stat判断是否为文件路径存在则fs.createReadStream(input).pipe(dest)流式上传不存在则当作字符串数据直接写入。这也是 Publii 的uploadFile()与uploadNewFileList()方法的基础。四、事件EventsAPI客户端继承自EventEmitter对外暴露以下事件greeting(stringmsg) —— 连接建立后触发msg是服务器连接时发送的欢迎文本。源码在 connection.js 处发出初次响应会被用作认证握手AUTH TLS / USER的起点。ready() —— 连接与认证成功时触发。握手序列为USER→PASS→FEAT→TYPE I最终在TYPE响应后触发ready见 connection.js。close(booleanhadErr) —— 连接完全关闭时触发。Publii 在 ftp.js 中监听该事件若同步尚未完成却收到关闭事件会判定为服务器空闲超时等异常并向主进程上报错误。end() —— 连接结束时触发对端发起 FIN 后。error(Errorerr) —— 出错时触发。对于协议级错误err对象会带code属性对应 FTP 三位数字响应码如 421、425、450、550 等该code由 connection.js 的makeError()注入。Publii 的实践在 ftp.js 中同时监听error事件对包含ECONNRESET的字符串错误进行计数最多容忍 5 次超出后销毁连接并向 UI 发送app-connection-error若 20 秒内未收到ready则由超时定时器兜底销毁连接。五、连接配置connect() 全部参数connect(objectconfig)建立到 FTP 服务器的连接其合法配置属性及默认值如下与 connection.js 的options赋值一一对应参数类型说明默认值hoststringFTP 服务器主机名或 IPlocalhostportintegerFTP 服务器端口21securemixed设为true表示控制连接与数据连接均加密control仅加密控制连接implicit表示隐式加密控制连接现代已较少使用通常配合端口 990falsesecureOptionsobject传递给tls.connect()的附加选项无userstring认证用户名anonymouspasswordstring认证密码anonymousconnTimeoutinteger等待控制连接建立的最长时间毫秒10000pasvTimeoutinteger等待 PASV 数据连接建立的最长时间毫秒10000keepaliveinteger发送空操作NOOP命令以保持连接的心跳间隔毫秒10000三个超时/心跳机制的源码依据connTimeout连接建立定时器在 connection.js 实现超时后发出Timeout while connecting to server错误并销毁 socketpasvTimeout数据连接定时器在_pasvConnect()connection.js中实现超时则报Timed out while making data connectionkeepaliveNOOP 心跳逻辑在donoop()connection.js中实现——仅在无进行中请求且队列为空时发送NOOP\r\n避免与真实命令冲突。Publii 的实际连接参数可在 ftp.js 看到它把connTimeout、pasvTimeout设为 15000ms并额外传入debug回调内部connectionDebugger会拦截PASS命令的调试输出将密码替换为星号后打印secure依据站点部署协议是否为ftp决定——协议为ftptls时开启加密同时secureOptions中透传rejectUnauthorized供用户控制证书校验。六、连接生命周期end() 与 destroy()end() —— 待所有已入队命令执行完毕后关闭服务器连接。源码中若队列仍有命令会置_ending true待队列清空后在_send()内触发_reset()connection.js。destroy() —— 立即关闭连接丢弃未执行的排队命令connection.js等价于直接调用_reset()。Publii 中二者的典型组合出现在uploadNewFileList()上传完files.publii.json后依次调用logout()→end()→destroy()确保 QUIT 握手完成且资源被彻底回收ftp.js。七、标准命令RFC 959以下命令属 RFC 959 定义的标准命令协议级错误同样会在回调的err.code中携带三位响应码。list([stringpath, ][booleanuseCompression, ]functioncallback) —— 获取path默认当前工作目录的目录列表。useCompression默认false。回调参数(err, list)list为对象数组元素属性包括type—— 单个字符表示条目类型d目录、-文件l符号链接仅 *NIXname—— 条目名称size—— 字节数stringdate—— 最后修改时间的Date对象rights—— 权限对象仅 *NIX含user、group、other三组字符串值为r/w/x的任意组合或空串owner—— 归属用户或 UID仅 *NIXgroup—— 归属组或 GID仅 *NIXtarget—— 符号链接目标路径仅 *NIXsticky—— 是否设置 sticky 位仅 *NIX。get(stringpath, [booleanuseCompression, ]functioncallback) —— 下载path处文件。回调参数(err, fileStream)fileStream为可读流开启压缩时内部会经zlib.createInflate()解压connection.js。put(mixedinput,stringdestPath, [booleanuseCompression, ]functioncallback) —— 上传数据到destPath。input可为 ReadableStream、Buffer 或本地文件路径。回调参数(err)。append(mixedinput,stringdestPath, [booleanuseCompression, ]functioncallback) —— 与put()相同但destPath已存在时执行追加而非覆盖底层发送APPE命令。rename(stringoldPath,stringnewPath,functioncallback) —— 重命名远程文件底层为RNFRRNTO两步connection.js。logout(functioncallback) —— 注销当前用户发送QUIT。delete(stringpath,functioncallback) —— 删除远程文件发送DELE。cwd(stringpath,functioncallback) —— 切换当前工作目录。回调参数(err, currentDir)currentDir仅在服务器响应文本中包含路径时返回connection.js。abort(functioncallback) —— 中止进行中的数据传输如 get/put/list发送ABOR若存在活跃数据连接还会将其标记为abortingconnection.js。site(stringcommand,functioncallback) —— 通过 SITE 发送服务器扩展命令例如CHMOD 755 foo、QUOTA。回调参数(err, responseText, responseCode)。status(functioncallback) —— 获取服务器状态的可读信息发送STAT。回调参数(err, status)。ascii(functioncallback) —— 将传输类型设为 ASCII发送TYPE A。binary(functioncallback) —— 将传输类型设为二进制这也是连接建立时的默认类型发送TYPE I。八、可选标准命令RFC 959以下命令同样源自 RFC 959但被标记为可选——服务器可能不支持调用时需做好err.code 502之类的兼容处理。mkdir(stringpath, [booleanrecursive, ]functioncallback) —— 创建目录。recursive启用类似mkdir -p的逐级创建算法默认false。其递归实现connection.js会先PWD记录原工作目录逐段CWD探测、MKD创建后回到原目录。Publii 的uploadDirectory()正是以mkdir(output, true, cb)的形式递归创建远程目录树。rmdir(stringpath, [booleanrecursive, ]functioncallback) —— 删除目录recursive为真时先list()目录内容再递归删除子目录/文件最后删除目录本身connection.js。Publii 的removeDirectory()传true使用该递归能力。cdup(functioncallback) —— 切换到父目录服务器返回 502 时会回退为CWD ..。pwd(functioncallback) —— 获取当前工作目录。回调参数(err, cwd)服务器不支持PWD502时回退为CWD .探测connection.js。system(functioncallback) —— 获取服务器操作系统标识发送SYST。回调参数(err, OS)。listSafe([stringpath, ][booleanuseCompression, ]functioncallback) —— 与list()类似但会临时cwd到目标目录再取列表适用于对目录名含空格、引号处理不佳的服务器它依赖pwd()可用故归入可选connection.js。九、扩展命令RFC 3659RFC 3659 定义的扩展命令同样需要服务器端支持size(stringpath,functioncallback) —— 获取文件大小。回调参数(err, numBytes)服务器不支持SIZE502时回退为list()单条目的size字段connection.js。lastMod(stringpath,functioncallback) —— 获取文件最后修改时间。回调参数(err, lastModified)通过MDTM命令与REX_TIMEVAL正则解析不支持时同样回退到目录列表connection.js。restart(integerbyteOffset,functioncallback) —— 为下一次 get/put 传输设置文件字节偏移发送REST可用于断点续传。十、内部机制深挖从源码理解连接与数据流10.1 命令队列与串行模型_send(cmd, cb, promote)connection.js是全部命令的底层通道命令对象进入 FIFO 队列每次仅有一个当前请求_curReq在途收到终结响应后才继续发送下一条promote参数为真时命令被插入队首用于 PASV 数据连接建立前的关键命令如TYPE、MODE。这种串行化保证了 FTP 命令与响应的一一对应。10.2 PASV 被动模式与数据连接所有数据传输list/get/put都先通过_pasv()connection.js发起PASV用RE_PASV正则解析服务器返回的(h1,h2,h3,h4,p1,p2)六元组计算数据端口p1*256p2若连接失败且服务器给出的 IP 与控制连接 IP 不同还会自动改用控制连接的对端地址重试这是对服务器返回内网 IP这一常见配置问题的内建兜底。10.3 协议响应解析器parser.js 是一个WritableStream式的解析器以\r?\n终止行为单位用正则RE_RES_END匹配\d{3}终结响应码并剥离多行响应中每行的前导NNN-最终触发response(code, text)。响应码按首位数字划分为五类RETVAL常量1xx 预备、2xx 成功、3xx 等待、4xx 临时错误、5xx 永久错误4xx/5xx 会转化为带code的Error。10.4 加密连接的握手序列当secure: true时连接建立后先发送AUTH TLS若服务器不支持则回退AUTH SSL再依次完成PBSZ 0、PROT P、USER、PASS的完整 TLS 升级流程connection.jssecure: implicit则直接以tls.connect()建立加密 socket。Publii 的ftptls协议即走此路径而普通ftp则使用明文连接。十一、Publii 中的真实调用链结合源码可将 node-ftp 在 Publii 部署流程中的位置梳理如下workers/deploy/deployment.js 是部署 worker 进程入口收到主进程消息后创建 modules/deploy/deployment.js 的Deployment实例Deployment.initSession()根据siteConfig.deployment.protocol分支ftp/ftptls落入FTP类即本模块useAltFtp为真时则改用基于basic-ftp的 ftp-alt.js 备选实现FTP.initConnection()构造new ftpClient()并传入host/port/user/password/secure/connTimeout/pasvTimeout等连接参数ready事件触发后调用downloadFilesList()用get()拉取远端files.publii.json与本地清单比对出新增/变更/删除文件随后按差异调用put()/mkdir()/delete()/rmdir()批量同步失败文件自动重试至多 5 次超出计入硬错误列表完成后put()上传新清单logout()end()destroy()收尾。此外FTP.testConnection()ftp.js会用该客户端向服务器上传并立即删除一个publii.test测试文件以验证连接与写权限对应界面中测试连接功能。十二、已知限制与演进方向仓库自带的 TODO 记录了该模块的待办事项增加对部分 SITE 命令如 CHMOD、CHGRP、QUOTA的支持支持主动非被动数据连接支持 IPv6。这也解释了为何 Publii 同时维护了基于basic-ftp的替代实现 ftp-alt.js 作为可切换的后备方案以规避旧模块在部分服务器兼容性上的局限。结语node-ftp 以简洁的事件 回调 可读流异步模型完整覆盖了 FTP 协议的标准、可选与扩展命令目录列表解析、TLS 升级、被动模式兜底、命令串行队列等内部设计在 lib/connection.js 与 lib/parser.js 中均有清晰的实现依据。在 Publii 中它承担着 FTP(S) 部署的核心传输职责理解其 API 与源码细节无论对于二次开发部署插件还是排查同步问题都极具参考价值。赞分享开发工具前端【免费下载链接】PubliiThe most intuitive Static Site CMS designed for SEO-optimized and privacy-focused websites.项目地址https://gitcode.com/gh_mirrors/pu/Publii点击查看免费下载相关推荐深入解析 Kubernetes Python 异步客户端中的 V1NodeStatus 节点状态模型深入解析 Kubernetes Python 异步客户端中的 V1NodeStatus 节点状态模型 本文以 Kubernetes 官方 Python 客户端后端云原生容器编排Kubernetes Python 客户端异步 Watch 指南kubernetes.aio.watch 模块深入解析Kubernetes Python 客户端异步 Watch 指南kubernetes.aio.watch 模块深入解析 本篇技术指南聚焦于官方 Python后端云原生容器编排Kubernetes Python 客户端异步动态资源发现模块解析kubernetes.aio.dynamic.discovery 深入指南Kubernetes Python 客户端异步动态资源发现模块解析kubernetes.aio.dynamic.discovery 深入指南 kubernet后端云原生容器编排创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考