oss

中文 | English

Herramienta de línea de comandos para almacenamiento de objetos multicloud basada en el protocolo S3. Un solo binario para operar el almacenamiento de objetos de los principales proveedores de nube: 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 y otros servicios compatibles con S3.

• 🌐 Navegación de buckets anónimos: basta con proporcionar una URL para listar/descargar buckets de lectura pública, sin necesidad de credenciales
• 🔗 La URL como punto de entrada: admite acceso mediante URL https://..., identifica los dominios de cada proveedor y resuelve el nombre del bucket/región; los parámetros de consulta de la URL (prefix, delimiter, max-keys, continuation-token, marker, start-after) se utilizan directamente como condiciones de filtrado, de forma similar a aws-s3-bucket-browser
• 📁 Buckets reenviados en forma de directorio: admite escenarios en los que un proxy inverso/CDN monta el bucket bajo una ruta (por ejemplo, https://files.example.com/mybucket/), resolviendo automáticamente en estilo path-style; basta con pasar la API de S3 para listar y descargar
• 🎫 Paso de parámetros adicionales: los parámetros no relacionados con el listado presentes en la URL (como ?token=abc de una pasarela de autenticación) se inyectan automáticamente en cada solicitud a la API (listar/descargar/subir/presignar), y se inyectan antes de la firma SigV4
• 🔑 Múltiples métodos de autenticación: AK/SK, credenciales temporales STS (session token), perfil de AWS (incluido assume-role), anónimo
• 🗂 Caché de listados: el contenido ya listado se almacena en caché localmente por defecto, lo que permite repetir listados/exportaciones/descargas de forma instantánea (escenarios como -d que requieren un escaneo completo se aceleran cientos de veces)
• 📤 Exportar listas de archivos: exporta según condiciones de filtrado a txt / csv / xlsx / yaml / markdown (--export)
• ⬇️ Descarga masiva filtrada: cp -r descarga todos los archivos que coincidan según --include/--exclude/--prefix, manteniendo la estructura de directorios de las claves
• 🔍 Búsqueda de pertenencia de buckets: find sondea por lotes (varios en la línea de comandos/entrada estándar) en qué almacenamiento en la nube se encuentra un bucket, admite nombres de bucket y URL completas de bucket; sondea de forma anónima e identifica simultáneamente si es posible listar el directorio de forma anónima; los buckets que permiten listar directorios de forma anónima se resaltan en la línea de comandos con ★ en verde brillante; --export exporta a txt/csv/xlsx/yaml/md con un campo dedicado listable_url
• 🔌 Servicio externo: oss serve ofrece en un solo puerto una API REST + documentación OpenAPI 3 + endpoints de herramientas MCP; oss mcp stdio|http|sse expone ls/stat/cat/presign/find como herramientas MCP para que las invoquen clientes como Claude
• 🎨 Compatible con la terminal: resaltado en color automático en terminales interactivas, salida en texto plano automática en escenarios de tuberías/scripts (--color auto|always|never)
• 🌍 Ayuda en chino e inglés: detecta automáticamente el idioma del sistema; en entornos en chino muestra la ayuda en chino y en el resto en inglés (se puede forzar con OSS_LANG=zh|en)
• 📄 Optimizado para buckets grandes: listado paginado en streaming (memoria constante), salida en streaming NDJSON, descarga con concurrencia acotada; millones de objetos sin consumir memoria
• 🚀 Transferencia en paralelo: concurrencia de múltiples archivos + concurrencia por fragmentos de un solo archivo, barra de progreso, omisión de puntos de reanudación, escritura atómica en disco con .part
• 🛠 Red controlable: -x proxy, -H cabeceras personalizadas (UA / Cookie …), -k omitir la verificación de certificados

Instalación

Opción uno: Homebrew (macOS / Linux, recomendado)```bash brew install ejfkdev/tap/oss

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

Opción tres: binarios precompilados

Descarga el paquete comprimido correspondiente a tu plataforma desde GitHub Releases (linux/darwin/windows × amd64/arm64), descomprímelo y úsalo directamente. Los artefactos de Release ya tienen la tabla de símbolos eliminada; las versiones de Linux/Windows están comprimidas con UPX (la versión de macOS no se comprime: los Mach-O empaquetados con UPX son bloqueados por el kernel). Cada versión incluye un archivo de suma de verificación SHA256.

Opción cuatro: compilación desde el código fuente (requiere Go 1.24+):```bash git clone https://github.com/ejfkdev/oss && cd oss make build # 产物为 ./oss make install # 安装到 $GOPATH/bin make release # 本地交叉编译全部平台到 dist/

## Inicio 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 de Target

Forma	Ejemplo
scheme	s3://bucket/prefix、oss://、cos://、obs://
nombre de bucket simple	mybucket/prefix（junto con --provider / -e）
URL HTTP	https://bucket.s3.us-east-1.amazonaws.com/prefix?prefix=logs/

Dominios de proveedores reconocidos automáticamente por URL (se resuelven endpoint / region / bucket):