oss

中文 | English

S3 프로토콜 기반 크로스 클라우드 객체 스토리지 명령줄 도구. 하나의 바이너리로 주요 클라우드 업체의 객체 스토리지를 조작합니다: AWS S3, 알리바바 클라우드 OSS, 텐센트 클라우드 COS, 화웨이 클라우드 OBS, 바이두 클라우드 BOS, 킹소프트 클라우드 KS3, UCloud US3, 징둥 클라우드 OSS, Google Cloud Storage, Cloudflare R2, Scaleway, Wasabi, DigitalOcean Spaces, Backblaze B2, MinIO 및 기타 S3 호환 서비스.

• 🌐 익명 버킷 탐색: URL만 주면 공개 읽기 버킷을 나열/다운로드할 수 있으며 자격 증명이 필요 없습니다
• 🔗 URL이 곧 진입점: https://... URL 접근을 지원하며 각 업체 도메인을 인식해 버킷 이름/리전을 파싱합니다; URL 쿼리 파라미터(prefix, delimiter, max-keys, continuation-token, marker, start-after)는 필터 조건으로 직접 사용되며, aws-s3-bucket-browser와 유사합니다
• 📁 디렉터리 형태로 전달되는 버킷: 리버스 프록시/CDN이 버킷을 경로 아래에 마운트한 시나리오를 지원합니다 (예: https://files.example.com/mybucket/), 자동으로 path-style로 파싱하며 S3 API를 그대로 전달해 나열 및 다운로드가 가능합니다
• 🎫 추가 파라미터 전달: URL의 비목록 파라미터(예: ?token=abc 인증 게이트웨이)는 모든 API 요청(나열/다운로드/업로드/사전 서명)에 자동으로 주입되며, SigV4 서명 전에 주입됩니다
• 🔑 다양한 인증: AK/SK, STS 임시 자격 증명(session token), AWS profile(assume-role 포함), 익명
• 🗂 목록 캐시: 나열된 내용은 기본적으로 로컬에 캐시되어 반복 나열/내보내기/다운로드가 즉시 열립니다(-d처럼 전체 스캔이 필요한 시나리오에서 수백 배 속도 향상)
• 📤 파일 목록 내보내기: 필터 조건에 따라 txt / csv / xlsx / yaml / markdown으로 내보내기(--export)
• ⬇️ 필터링 일괄 다운로드: cp -r로 --include/--exclude/--prefix에 따라 일치하는 모든 파일을 다운로드하며 key 디렉터리 구조를 유지합니다
• 🔍 버킷 소속 찾기: find로 일괄(명령줄 다수/표준 입력) 버킷이 어느 클라우드 스토리지에 있는지 탐지하며, 버킷 이름과 전체 버킷 URL을 지원합니다; 익명으로 탐지하고 동시에 익명 디렉터리 나열 가능 여부를 식별하며, 익명 나열이 가능한 버킷은 명령줄에서 밝은 녹색 ★으로 강조되고, --export는 전용 listable_url 필드를 포함한 txt/csv/xlsx/yaml/md를 내보냅니다
• 🔌 외부 서비스: oss serve는 하나의 포트에서 REST API + OpenAPI 3 문서 + MCP 도구 엔드포인트를 제공하며, oss mcp stdio|http|sse는 ls/stat/cat/presign/find를 MCP 도구로 Claude 등 클라이언트에서 호출할 수 있게 합니다
• 🎨 터미널 친화적: 대화형 터미널에서는 자동으로 컬러 강조, 파이프/스크립트 시나리오에서는 자동으로 일반 텍스트 출력(--color auto|always|never)
• 🌍 중영문 도움말: 시스템 언어를 자동 인식하여 중국어 환경에서는 중국어 도움말, 그 외에는 영어를 표시합니다(OSS_LANG=zh|en으로 강제 가능)
• 📄 대용량 버킷 최적화: 스트리밍 페이지 나열(상수 메모리), NDJSON 스트리밍 출력, 제한된 동시 다운로드로 수백만 개 객체도 메모리를 차지하지 않습니다
• 🚀 병렬 전송: 다중 파일 동시 + 단일 파일 분할 동시, 진행 표시줄, 중단점 건너뛰기, .part 원자적 저장
• 🛠 네트워크 제어: -x 프록시, -H 사용자 정의 헤더(UA / Cookie …), -k 인증서 검증 건너뛰기

설치

방법 1: Homebrew(macOS / Linux, 권장)```bash brew install ejfkdev/tap/oss

**방법 2: go install** (Go 1.24+ 필요)```bash
go install github.com/ejfkdev/oss@latest

방법 3: 사전 컴파일된 바이너리

GitHub Releases에서 해당 플랫폼의 압축 패키지를 다운로드하세요 (linux/darwin/windows × amd64/arm64), 압축을 풀면 바로 사용할 수 있습니다. Release 산출물은 이미 심볼 테이블이 제거되어 있으며, Linux/Windows 버전은 UPX로 압축되었습니다 (macOS 버전은 압축하지 않음: UPX로 패킹된 Mach-O는 커널에 의해 차단됩니다). 각 버전에는 SHA256 체크섬 파일이 첨부되어 있습니다.

방법 4: 소스 컴파일 (Go 1.24+ 필요):```bash git clone https://github.com/ejfkdev/oss && cd oss make build # 产物为 ./oss make install # 安装到 $GOPATH/bin make release # 本地交叉编译全部平台到 dist/

## 빠른 시작```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" ./

Target 작성법

형식	예시
scheme	s3://bucket/prefix, oss://, cos://, obs://
버킷 이름만	mybucket/prefix (--provider / -e와 함께 사용)
HTTP URL	https://bucket.s3.us-east-1.amazonaws.com/prefix?prefix=logs/

URL에서 자동 인식되는 벤더 도메인 (endpoint / region / bucket 파싱):

벤더	도메인 예시
AWS	bucket.s3.region.amazonaws.com, s3.region.amazonaws.com/bucket
알리바바 클라우드	bucket.oss-cn-hangzhou.aliyuncs.com (accelerate 포함)
텐센트 클라우드	bucket-appid.cos.ap-guangzhou.myqcloud.com
화웨이 클라우드	bucket.obs.cn-north-4.myhuaweicloud.com
바이두 클라우드 BOS	bucket.s3.bj.bcebos.com, s3.bj.bcebos.com/bucket
킹소프트 클라우드 KS3	bucket.ks3-cn-beijing.ksyuncs.com
UCloud US3	bucket.s3-cn-sh2.ufileos.com
징둥 클라우드 OSS	s3.cn-north-1.jdcloud-oss.com/bucket (path-style)
티엔이 클라우드 OOS	bucket.oos-cn.ctyunapi.cn (리소스 풀 및 홍콩 노드 endpoint 포함)
차이나 유니콤 클라우드 OSS	bucket.obs-helf.cucloud.cn (산업 클라우드 리전)
차이나 모바일 클라우드 EOS	bucket.eos-wuxi-1.cmecloud.cn (30개 리전)
칭윈 QStor	bucket.s3.pek3a.qsstor.com (S3 호환 도메인 qsstor.com)
Scaleway	bucket.s3.fr-par.scw.cloud (fr-par/nl-ams/pl-waw)
Wasabi	bucket.s3.us-east-1.wasabisys.com (14개 리전)
DigitalOcean Spaces	nyc3.digitaloceanspaces.com/bucket (9개 리전)
Yandex	bucket.storage.yandexcloud.net
Exoscale SOS	bucket.ch-gva-2.sos.exoscale.com (6개 리전)
Arvan Cloud	bucket.s3.ir-thr-at1.arvanstorage.ir
Cloudflare R2	bucket.<account_id>.r2.cloudflarestorage.com
GCS	storage.googleapis.com/bucket (HMAC 키)

기타 호스트 (MinIO, Ceph, 리버스 프록시 버킷 전달, CNAME…)는 일괄적으로 path-style로 파싱합니다: 첫 번째 경로 세그먼트를 버킷 이름으로, 나머지를 key로 사용합니다. 예: https://files.example.com/mybucket/sub/key.jpg → 버킷 mybucket, key sub/key.jpg. 호스트가 버킷을 직접 가리키는 경우 (CNAME), --bucket NAME으로 명시적으로 지정합니다. URL이 비어 있으면 (oss ls) 모든 버킷을 나열합니다.

URL 쿼리 파라미터는 두 가지로 분류됩니다:

• 목록 API 파라미터 (prefix delimiter max-keys continuation-token marker start-after encoding-type list-type) → 목록 필터 조건으로 해석
• 나머지 파라미터 (예: token=abc) → 추가 파라미터로 간주하여 해당 대상에 대한 모든 요청에 전달 (ListObjects / GetObject / PutObject / Presign 등), 인증 파라미터가 있는 게이트웨이에 적합; 파라미터는 SigV4 서명 전에 주입되어 서명에 참여하므로 AK/SK 자격 증명과 동시에 사용 가능

인증

다음 순서로 파싱하며, 일치하면 중단합니다:

1. --ak / --sk / --token (STS session token)
2. 환경 변수 OSS_ACCESS_KEY_ID / OSS_SECRET_ACCESS_KEY / OSS_SESSION_TOKEN
3. 환경 변수 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN
4. --profile NAME 또는 ~/.aws/credentials|config (assume-role 등 STS profile 지원)
5. 모두 없음 → 익명 접근 (--anonymous로 강제 가능)

명령

oss ls — 버킷/객체 나열```bash

oss ls # 列举所有桶 oss ls s3://b/dir/ --limit 50 # 默认目录式（delimiter=/），首页 50 条 oss ls s3://b/dir/ --limit 50 # 再次运行自动从断点继续（token 已缓存） oss ls s3://b/dir/ --reset # 忽略缓存，从头列举 oss ls s3://b/dir/ --next-token # 显式指定 token（覆盖缓存） oss ls s3://b/dir/ -d # 只列目录（PRE=目录/公共前缀） oss ls s3://b/dir/ -f --include "*.gz" # 只列文件，glob 过滤 oss ls s3://b --all # 流式列举全部（常数内存） oss ls s3://b -r # 平铺所有 key（不分目录） oss ls s3://b --all -j > list.ndjson # NDJSON 流式输出，适合管道处理 oss ls s3://b --export list.xlsx # 导出文件列表为 Excel

ls는 "보기"(나열/필터링/목록 내보내기)만 담당합니다. **다운로드/업로드는 `cp`를 사용하세요** (아래 참조).