使い方 / Docs

misos3 は S3 互換の API を提供します。お手持ちの S3 クライアントから接続して、バケットとオブジェクトを操作できます。

Endpointhttps://s3.misos3.megumiso.com

Region任意 (例: us-east-1)

Path style必須 (bucket をパスで指定)

01概要

エンドポイントは https://s3.misos3.megumiso.com です。パス前置はありません（ルートに指定します）。
認証は AWS Signature V4 (Authorization ヘッダ) です。
リージョンは任意です。SigV4 の署名計算には使われますが、API 側は値に依存しません (慣例的に us-east-1 を指定しておけば問題ありません)。
バケットは path-style で指定します (virtual-hosted style / サブドメイン方式は未対応)。

アクセスキーが1つも登録されていない間は、S3 API は署名なしで利用できます (ブートストラップモード)。アクセスキーを1つ以上作成すると、以降は有効な署名が必須になります。

本番環境では S3 API とダッシュボードを別ホスト名で公開します (例: API は s3.example.com、ダッシュボードは別ホスト)。リバースプロキシは パスを書き換えずホスト名で振り分けてください。パスを書き換えると SigV4 署名が一致しなくなり認証に失敗します。

02アクセスキー

署名に使う資格情報は、ログイン後の Access Keys ページで作成します。

ログイン (未登録なら新規登録) します。
Access Keys ページでキーを作成します。
表示された Access Key ID と Secret Access Key をクライアントに設定します。

Secret Access Key は作成後いつでも Access Keys ページで確認できます。ファイルへの保存や共有は自己責任で行ってください。

03rclone

rclone はそのまま利用できます。

設定 (`rclone config`)

対話式セットアップでは次のように答えます。

n) New remote
name> misos3
Storage> s3
provider> Other
env_auth> false
access_key_id> AKIA...
secret_access_key> ...
region> us-east-1
endpoint> https://s3.misos3.megumiso.com
location_constraint> (空)
acl> (空)

あるいは設定ファイル (~/.config/rclone/rclone.conf) に直接書くこともできます。

[misos3]
type = s3
provider = Other
access_key_id = AKIA...
secret_access_key = ...
region = us-east-1
endpoint = https://s3.misos3.megumiso.com

よく使うコマンド

# バケット一覧
rclone lsd misos3:

# オブジェクト一覧
rclone ls misos3:my-bucket
rclone lsf misos3:my-bucket/dir/

# アップロード / ダウンロード
rclone copy ./local-dir misos3:my-bucket/dir/
rclone copy misos3:my-bucket/dir/ ./local-dir

# 同期 (差分のみ転送 / --delete で削除も反映)
rclone sync ./local-dir misos3:my-bucket/backup/

# マウント (FUSE)
rclone mount misos3:my-bucket ~/mnt/misos3

04AWS CLI

AWS CLI は --endpoint-url でエンドポイントを指定します。

aws configure
# AWS Access Key ID: AKIA...
# AWS Secret Access Key: ...
# Default region name: us-east-1
# Default output format: json

# バケット操作
aws --endpoint-url https://s3.misos3.megumiso.com s3api list-buckets
aws --endpoint-url https://s3.misos3.megumiso.com s3api create-bucket --bucket my-bucket
aws --endpoint-url https://s3.misos3.megumiso.com s3api delete-bucket --bucket my-bucket

# オブジェクト操作
aws --endpoint-url https://s3.misos3.megumiso.com s3 cp hello.txt s3://my-bucket/hello.txt
aws --endpoint-url https://s3.misos3.megumiso.com s3 cp s3://my-bucket/hello.txt ./hello.txt
aws --endpoint-url https://s3.misos3.megumiso.com s3 ls s3://my-bucket/dir/
aws --endpoint-url https://s3.misos3.megumiso.com s3 rm s3://my-bucket/hello.txt

# 同期
aws --endpoint-url https://s3.misos3.megumiso.com s3 sync ./local-dir s3://my-bucket/dir/

毎回指定するのが面倒な場合は、環境変数やエイリアスを利用すると便利です。
例: alias misos3="aws --endpoint-url https://s3.misos3.megumiso.com"

05s3cmd

s3cmd はエンドポイントの host にパスを付けられませんが、 misos3 の S3 API はルートに公開されているため、そのまま利用できます。

s3cmd --configure
# Access Key: AKIA...
# Secret Key: ...
# Default Region: us-east-1
# S3 Endpoint: localhost:9000   (本番は s3.example.com など)
# DNS-style bucket+hostname: %(bucket)s.s3.example.com  ← 空にする (path-style)
# Use HTTPS: 任意
# ... 保存する

# バケット一覧 / 作成
s3cmd ls
s3cmd mb s3://my-bucket

# アップロード / ダウンロード
s3cmd put hello.txt s3://my-bucket/hello.txt
s3cmd get s3://my-bucket/hello.txt ./hello.txt

# 一覧 / 同期 / 削除
s3cmd ls s3://my-bucket/dir/
s3cmd sync ./local-dir s3://my-bucket/dir/
s3cmd del s3://my-bucket/hello.txt

06GUI (WinSCP / Cyberduck)

GUI クライアントは S3 プロトコルで接続します。S3 API はルートに公開されているため、エンドポイントのホストとポートを指定するだけで接続できます。

WinSCP

新規セッションで「ファイルプロトコル」に S3 を選びます。
ホスト名にエンドポイントのホスト、ポートにポート番号を入力します。
「高度な設定」から Access Key ID と Secret Access Key を設定します。
接続後、バケットがフォルダとして表示されます。

Cyberduck

新規接続でプロトコル Amazon S3 を選びます。
サーバー / ポートにエンドポイントのホストとポートを入力します。
「More Options」で Access Key ID と Secret Access Key を設定します。
「Path style requests」を有効にします。

07制限事項

アップロードサイズ

1 リクエストのボディ上限は 256 MiB (268,435,456 バイト) です。これを超えるリクエストは 413 Payload Too Large になります。
単一アップロード (PutObject、ダッシュボードからのアップロード) は 最大 256 MiB です。
マルチパートアップロード では、上記のとおり 1 パートあたり最大 256 MiB ですが、オブジェクト全体は複数パートに分割できるため 256 MiB に縛られません。パート数は最大 10,000 です (理論上のオブジェクト上限は約 256 MiB × 10,000)。
パートは有効なストレージサーバーへランダムに分散保存され、ダウンロード時に順番に結合されます。大きいファイルは マルチパート でアップロードしてください (AWS CLI / rclone などは一定サイズを超えると自動でマルチパートを使います)。
CopyObject はコピー元を一度メモリへ読み込んでから保存するため、大きいオブジェクトのコピーはサーバーのメモリを消費します。

その他の制限

presigned URL (クエリ署名) は未対応です。
chunked ストリーミング署名 (STREAMING-...) は未対応です。
virtual-hosted style (bucket をサブドメインで指定) は未対応です。path-style を使ってください。
アクセスキーが1つ以上ある場合、無署名・不正な署名のリクエストは 403 (AccessDenied / InvalidAccessKeyId / SignatureDoesNotMatch) になります。