ftp-relay-cli

上传静态产物到 FTP Relay 的命令行工具。
自动从 GitLab / GitHub CI 环境变量（或本地 git）填充审计 Header，无需手写一长串 curl -H。

安装

npm install -g ftp-relay-cli
# 或项目内
npm install -D ftp-relay-cli

npx ftp-relay upload ./dist --url http://127.0.0.1:8080 --token tok_xxx --wait

用法

export FTP_RELAY_URL=http://127.0.0.1:8080
export FTP_RELAY_TOKEN=tok_xxxxxxxx

# 上传目录（默认打成 tgz 压缩包；自动带 X-Remote-Subdir=<目录名>，落到项目 remotePath 下）
ftp-relay upload ./202607101806 --wait
# 例：项目 remotePath=/test-ftp → 远端 /test-ftp/202607101806

# 不压缩（仅 tar）
ftp-relay upload ./dist --format tar --wait

# 已有归档（不带 X-Remote-Subdir，内容直接落到 remotePath）
ftp-relay upload ./dist.tar --wait

# 单/多文件（打平、不保留本地结构），落到 remotePath 或 remotePath/<subdir>
ftp-relay upload a.png img/b.png --subdir photos --wait

GitLab CI 示例

deploy:
  script:
    - npx -y -p ftp-relay-cli ftp-relay upload ./dist --wait
  variables:
    FTP_RELAY_URL: "https://ftp-relay.example.com"
    # FTP_RELAY_TOKEN 配在 CI 变量里

CI 下会自动带上：

| Header | 来源 | |--------|------| | X-Source | ci | | X-Commit | CI_COMMIT_SHA / GITHUB_SHA / git rev-parse HEAD | | X-Branch | CI_COMMIT_REF_NAME / GITHUB_REF_NAME | | X-Actor | GITLAB_USER_LOGIN / GITHUB_ACTOR / git user.name | | X-Repo | CI_PROJECT_PATH / GITHUB_REPOSITORY | | X-Pipeline-Url | CI_PIPELINE_URL / GitHub Actions run URL | | X-Message | 仅 --message 显式传入（写入 webhook 详情「说明」） |

可用 --commit / --actor 等覆盖；--message 不会从 CI 环境变量自动填充。

上传结果若含 skipped 数组，CLI 会列出同名跳过文件并提示开启项目「允许覆盖已有文件」。

多文件上传不保留本地目录结构（同名冲突会直接报错）；目标文件夹已存在时需项目开启「允许合并到已有目录」，同名文件遵循「允许覆盖已有文件」开关。

选项

ftp-relay upload <dir|archive>
  --url <url>         或环境变量 FTP_RELAY_URL
  --token <token>     或环境变量 FTP_RELAY_TOKEN
  --format tar|tgz    目录打包格式，默认 tgz（多文件模式默认 tar）
  --subdir <name>     多文件模式指定远端子目录（单段，落到 remotePath/<name>）
  --wait              同步等待结果
  --source / --commit / --branch / --actor / --repo / --pipeline-url
  --message <text>    自定义 webhook 详情说明（可选）

作为库

import { upload } from "ftp-relay-cli";

await upload({
  url: process.env.FTP_RELAY_URL!,
  token: process.env.FTP_RELAY_TOKEN!,
  path: "./dist",
  wait: true,
});