oss

中文 | English

Ferramenta de linha de comando para armazenamento de objetos multicloud baseada no protocolo S3. Um único binário para operar o armazenamento de objetos dos principais provedores de nuvem: AWS S3, Alibaba Cloud OSS, Tencent Cloud COS, Huawei Cloud OBS, Baidu Cloud BOS, Kingsoft Cloud KS3, UCloud US3, JD Cloud OSS, Google Cloud Storage, Cloudflare R2, Scaleway, Wasabi, DigitalOcean Spaces, Backblaze B2, MinIO e outros serviços compatíveis com S3.

• 🌐 Navegação anônima de buckets: basta fornecer uma URL para listar/baixar buckets de leitura pública, sem necessidade de credenciais
• 🔗 URL como ponto de entrada: suporta acesso via URL https://..., identifica domínios de cada provedor e resolve nome do bucket/região; parâmetros de consulta da URL (prefix, delimiter, max-keys, continuation-token, marker, start-after) são usados diretamente como filtros, semelhante ao aws-s3-bucket-browser
• 📁 Buckets encaminhados em formato de diretório: suporta cenários em que proxy reverso/CDN monta o bucket sob um caminho (como https://files.example.com/mybucket/), com resolução automática em path-style, permitindo listar e baixar via passthrough da API S3
• 🎫 Passagem de parâmetros extras: parâmetros não relacionados a listagem na URL (como ?token=abc para gateway de autenticação) são injetados automaticamente em cada requisição de API (listar/baixar/enviar/pré-assinar), e antes da assinatura SigV4
• 🔑 Múltiplos tipos de autenticação: AK/SK, credenciais temporárias STS (session token), perfil AWS (incluindo assume-role), anônimo
• 🗂 Cache de listagem: conteúdos já listados são armazenados em cache local por padrão, tornando listagens/exportações/downloads repetidos instantâneos (cenários que exigem varredura completa como -d ficam centenas de vezes mais rápidos)
• 📤 Exportar lista de arquivos: exporta conforme filtros para txt / csv / xlsx / yaml / markdown (--export)
• ⬇️ Download em lote com filtros: cp -r baixa todos os arquivos correspondentes conforme --include/--exclude/--prefix, mantendo a estrutura de diretórios das keys
• 🔍 Descoberta de provedor do bucket: find em lote (múltiplos na linha de comando/entrada padrão) detecta em qual armazenamento em nuvem o bucket está, suportando nome do bucket e URL completa do bucket; detecção anônima que também identifica se é possível listar o diretório anonimamente, buckets listáveis anonimamente são destacados na linha de comando com ★ em verde brilhante, e --export gera txt/csv/xlsx/yaml/md com campo dedicado listable_url
• 🔌 Serviço exposto: oss serve fornece em uma única porta REST API + documentação OpenAPI 3 + endpoint de ferramentas MCP, oss mcp stdio|http|sse expõe ls/stat/cat/presign/find como ferramentas MCP para clientes como Claude
• 🎨 Amigável ao terminal: destaque colorido automático em terminais interativos, saída em texto puro automática em pipes/scripts (--color auto|always|never)
• 🌍 Ajuda em chinês e inglês: detecta automaticamente o idioma do sistema, exibindo ajuda em chinês em ambientes chineses e em inglês nos demais (pode forçar com OSS_LANG=zh|en)
• 📄 Otimizado para buckets grandes: listagem paginada em streaming (memória constante), saída NDJSON em streaming, download com concorrência limitada, sem consumo de memória para milhões de objetos
• 🚀 Transferência paralela: concorrência entre múltiplos arquivos + concorrência por partes em arquivo único, barra de progresso, retomada com salto de partes concluídas, gravação atômica em .part
• 🛠 Rede controlável: -x proxy, -H cabeçalhos personalizados (UA / Cookie …), -k ignorar validação de certificado

Instalação

Método 1: Homebrew (macOS / Linux, recomendado)```bash brew install ejfkdev/tap/oss

**Método dois: go install** (requer Go 1.24+)```bash
go install github.com/ejfkdev/oss@latest

Método três: binários pré-compilados

Baixe o pacote compactado correspondente à sua plataforma em GitHub Releases (linux/darwin/windows × amd64/arm64), descompacte e use. Os artefatos do Release já têm a tabela de símbolos removida, as versões para Linux/Windows são comprimidas com UPX (a versão para macOS não é comprimida: Mach-O empacotado com UPX é bloqueado pelo kernel). Cada versão vem com um arquivo de checksum SHA256.

Método quatro: compilação a partir do código-fonte (requer Go 1.24+):```bash git clone https://github.com/ejfkdev/oss && cd oss make build # 产物为 ./oss make install # 安装到 $GOPATH/bin make release # 本地交叉编译全部平台到 dist/

## Início rápido```bash
# 匿名浏览公共桶（无需凭证）
oss ls https://noaa-nwm-pds.s3.amazonaws.com/?delimiter=/
oss ls "https://noaa-nwm-pds.s3.amazonaws.com/?prefix=nwm.20250101/&delimiter=/&max-keys=20"
oss cp -r https://noaa-nwm-pds.s3.amazonaws.com/nwm.20250101/ ./nwm/ --jobs 32

# 阿里云 OSS
oss ls oss://mybucket/logs/ --ak <AK> --sk <SK> --region cn-hangzhou
export OSS_ACCESS_KEY_ID=xxx OSS_SECRET_ACCESS_KEY=yyy   # 或者用环境变量
oss ls mybucket --provider aliyun                         # 裸桶名写法

# 腾讯云 COS / 华为云 OBS
oss ls s3://bucket-1250000000 --provider tencent --region ap-guangzhou
oss ls https://bucket.obs.cn-north-4.myhuaweicloud.com/prefix/

# Yandex / Exoscale / Arvan
oss ls s3://mybucket --provider yandex
oss ls s3://mybucket --provider exoscale --region ch-gva-2

# MinIO / 自建 S3
oss ls s3://mybucket -e http://127.0.0.1:9000 --ak minioadmin --sk minioadmin
oss ls http://127.0.0.1:9000/mybucket/prefix/             # IP/端口自动识别为 path-style

# 走代理、自定义 UA / Cookie
oss ls s3://mybucket -x http://127.0.0.1:7890 \
    -H "User-Agent: my-agent/1.0" -H "Cookie: session=abc"

# 目录形式转发的桶（反代把桶挂在路径下，S3 API 透传）
oss ls "https://files.example.com/mybucket/?prefix=2026/&max-keys=10"
oss cp "https://files.example.com/mybucket/<key>" ./

# 附带额外参数的访问（token 等会自动带到每个请求）
oss ls "http://gateway.example.com/bucket?token=abc"
oss cp "http://gateway.example.com/bucket/file.bin?token=abc" ./

Formato do Target

Forma	Exemplo
scheme	s3://bucket/prefix、oss://、cos://、obs://
nome do bucket puro	mybucket/prefix（com --provider / -e）
URL HTTP	https://bucket.s3.us-east-1.amazonaws.com/prefix?prefix=logs/

Domínios de provedores reconhecidos automaticamente pela URL (extraindo endpoint / region / bucket):