sf-push / sf-pull

基于火山引擎 TOS 对象存储中转的命令行文件传输工具（公司内部 spirit-ai 文件传输）。

• sf-push 文件/文件夹 → 自动压缩成 zip → 上传到 TOS bucket → 返回 12 位提取码
• sf-pull 12位提取码 → 从 TOS bucket 下载 → 解压到当前目录

发布到 npm 后全局安装即可使用：npm i -g sf-push（一个包同时提供 sf-push 和 sf-pull 两个命令）。

两端全部匿名访问，无需任何配置、无需 AccessKey。中转配置硬编码：bucket 为 file-switch、endpoint 为 tos-cn-beijing.volces.com（公开读写 + 内网访问限制）。对象生命周期由 TOS bucket 生命周期规则控制。

特性

• 文件/文件夹一键压缩上传，生成 12 位提取码（避免 0/O、1/I/L 等易混淆字符）
• 上传/下载均为匿名访问（bucket 公开读写 + 内网限制），无需任何凭证
• 单文件大小上限默认 500M，可用环境变量 SF_PUSH_MAX_SIZE_MB 调整，最高 2048M（超过上限将报错且不执行任何操作）
• 中转配置全部硬编码，开箱即用；无 TTL 逻辑，过期清理交给 TOS 生命周期规则
• 纯 Node.js 实现，不依赖系统 zip/unzip/curl 等命令，跨平台可用

安装

npm i -g sf-push

需要 Node.js ≥ 18.17。

快速开始

1. 推送

sf-push ./report.pdf
sf-push ./my-project/

输出 12 位提取码，例如：

[ok] 上传成功
ABCDEFGHJKM2

2. 拉取

任意机器（同内网）上：

sf-pull ABCDEFGHJKM2

自动下载并解压到当前目录。

中转配置（硬编码）

| 配置项 | 值 | | --- | --- | | Bucket | file-switch | | Endpoint（内网，优先） | tos-cn-beijing.ivolces.com | | Endpoint（公网，回退） | tos-cn-beijing.volces.com | | Region | cn-beijing |

均不可配置，开箱即用。上传/下载会先尝试内网 endpoint；遇 403 或网络不通时自动回退到公网 endpoint；若两者均不可用则报「网络不通（内网/公网均不可用）」。

说明：因为优先走内网地址，公司内网机器会走内网流量（更快更稳）；内网不可达时（如不在公司网络）自动改用公网地址。

环境变量

| 变量 | 默认 | 说明 | | --- | --- | --- | | SF_PUSH_MAX_SIZE_MB | 500 | 单文件大小上限（MB），默认 500M，最高 2048M，超限报错且不执行任何操作 |

TOS 侧准备

1. 创建 bucket file-switch（cn-beijing）。
2. bucket 策略配置为公开读写，并通过内网访问限制 / 安全组仅允许内网访问（安全由网络隔离保证）。
3. 配置生命周期规则：按前缀 sf-push/ 定期删除对象（如 N 天后删除），控制空间占用。对象过期后 sf-pull 会返回 404「文件不存在（或已被清理）」。

工作原理

• 12 位提取码直接映射为 bucket 内的固定对象 key：sf-push/<CODE>.zip（CODE 统一大写），上传与下载使用同一规则，无需中间数据库。
• sf-push 匿名 PUT、sf-pull 匿名 GET，请求对象 key 为 sf-push/<CODE>.zip，CODE 需为 12 位字母数字，无路径穿越风险。
• 压缩时保留目录结构（含空文件夹）；解压使用 yauzl 并自带 zip-slip / 绝对路径 / 符号链接防护，避免从共享 bucket 下载不可信 zip 时写入目标目录之外。

安全说明

• 12 位随机码碰撞概率极低（约 31^12 种组合），配合网络隔离使用。
• 上传/下载均匿名，安全边界完全由「公开读写 + 内网访问限制」的网络隔离保证，请勿对公网开放该 bucket 的读写权限。

License

MIT