Store documents in an S3-compatible service

Jiandu can use an S3-compatible API by setting the provider's endpoint and signing region. This page gives known configuration shapes for MinIO, Cloudflare R2, Backblaze B2, and Wasabi. An S3 logo is not a complete compatibility guarantee: prove listing, multipart upload, copy, conditional reads, deletion, and recovery against your exact service version and policy.

Common configuration model

Every provider uses the same Jiandu backend:

{
  "schema_version": 1,
  "data_directory": "/var/lib/jiandu",
  "storage": {
    "backend": "s3",
    "bucket": "jiandu-documents",
    "region": "PROVIDER_REGION",
    "endpoint": "https://S3_API_ENDPOINT",
    "prefix": "primary",
    "work_root": "/var/lib/jiandu/storage-work",
    "allow_http": false,
    "virtual_hosted_style": false
  }
}

endpoint must be the S3 API root, without a bucket or prefix path. With the compatibility-oriented default virtual_hosted_style: false, Jiandu sends path-style requests such as https://endpoint.example/jiandu-documents/object-key. Keep it false unless the provider requires bucket-qualified hostnames and you have configured DNS and certificates for them.

Credentials use the AWS environment names even when the provider is not AWS:

export AWS_ACCESS_KEY_ID=replace-with-provider-access-key
export AWS_SECRET_ACCESS_KEY=replace-with-provider-secret-key

Supply those values through the service manager or orchestrator's protected secret mechanism. The S3 adapter does not read AWS_PROFILE or a shared credentials file. If a provider issues temporary credentials, also set AWS_SESSION_TOKEN and ensure rotation updates the running workload in the way that provider supports.

:::caution No per-provider TLS bypass Jiandu verifies the HTTPS certificate with the runtime's system trust store. There is no skip-verification option. For a private CA, install that CA in the host or container trust store. Setting allow_http: true changes the protocol and exposes credentials and document data; it is not a fix for an untrusted certificate. :::

MinIO

Choose MinIO when you already operate and back up it as a service. Use the S3 API endpoint, normally port 9000, not the administrative console endpoint.

MinIO storage block

{
  "backend": "s3",
  "bucket": "jiandu-documents",
  "region": "us-east-1",
  "endpoint": "https://minio.storage.example.net",
  "prefix": "primary",
  "work_root": "/var/lib/jiandu/storage-work",
  "allow_http": false,
  "virtual_hosted_style": false
}

MinIO supports path-style requests by default. If your deployment deliberately enables virtual-hosted buckets, set virtual_hosted_style: true and make endpoint consistent with the bucket-qualified hostname expected by that deployment. DNS and the TLS certificate must cover the bucket hostname. MinIO's path versus virtual-host documentation describes that server-side boundary.

Grant the MinIO service account list access on the bucket and get, put, delete, copy, and multipart access beneath the chosen prefix. A read/write canned policy is broader than necessary; prefer a prefix-scoped custom policy when multiple systems share the bucket.

For an isolated development network, plaintext can be acknowledged explicitly:

{
  "endpoint": "http://minio:9000",
  "allow_http": true
}

Use that only when the network itself is a reviewed trust boundary. Never expose the endpoint or its static access key across an untrusted LAN or the internet.

Cloudflare R2

R2 uses the account-level S3 endpoint and the signing region auto:

Cloudflare R2 storage block

{
  "backend": "s3",
  "bucket": "jiandu-documents",
  "region": "auto",
  "endpoint": "https://0123456789abcdef0123456789abcdef.r2.cloudflarestorage.com",
  "prefix": "primary",
  "work_root": "/var/lib/jiandu/storage-work",
  "allow_http": false,
  "virtual_hosted_style": false
}

Create an R2 S3 API credential with Object Read & Write permission limited to the Jiandu bucket. Map its Access Key ID and Secret Access Key to the corresponding AWS_* environment values. Use the account ID in the endpoint; do not use a public r2.dev URL or a custom domain, because those are object-delivery endpoints rather than the authenticated S3 API.

Cloudflare documents the endpoint and credential mapping in R2 authentication and defines auto as the S3 region in its compatibility reference.

R2 caveats:

• An ordinary Cloudflare API token is not the S3 Access Key ID/Secret Access Key pair.
• Bucket-scoped read-only credentials pass downloads but fail readiness and publication.
• Provider-side lifecycle rules must not expire the live prefix.
• R2 implements a broad S3 surface, but exact feature differences can change; repeat the conformance exercise after material provider or Jiandu upgrades.

Backblaze B2

Use the S3-compatible endpoint printed for the bucket. Its region is part of the hostname and must also be configured as the signing region:

Backblaze B2 storage block

{
  "backend": "s3",
  "bucket": "jiandu-documents",
  "region": "us-west-004",
  "endpoint": "https://s3.us-west-004.backblazeb2.com",
  "prefix": "primary",
  "work_root": "/var/lib/jiandu/storage-work",
  "allow_http": false,
  "virtual_hosted_style": false
}

Create a bucket-restricted application key with list, read, write, and delete capabilities. The B2 key ID becomes AWS_ACCESS_KEY_ID; the application key becomes AWS_SECRET_ACCESS_KEY. A Backblaze master application key is not accepted by the S3-compatible API. If you restrict the key to one bucket, review Backblaze's current listAllBucketNames compatibility requirement.

Backblaze documents the endpoint form and HTTPS requirement and the S3 application-key mapping.

B2 caveats:

• Use the exact endpoint region shown for the bucket; an AWS endpoint or another B2 region fails.
• Enable both write and delete capabilities. B2 maps deletion behavior to more than one native capability.
• File-version lifecycle settings can retain deleted data and add cost. That may be useful, but it does not replace a database-coordinated Jiandu backup.

Wasabi

Wasabi uses regional S3 endpoints. Replace the example region and endpoint with the pair assigned to the bucket:

Wasabi storage block

{
  "backend": "s3",
  "bucket": "jiandu-documents",
  "region": "us-east-1",
  "endpoint": "https://s3.us-east-1.wasabisys.com",
  "prefix": "primary",
  "work_root": "/var/lib/jiandu/storage-work",
  "allow_http": false,
  "virtual_hosted_style": false
}

Create a programmatic user and policy scoped to the bucket/prefix with list, get, put, delete, copy, and multipart permissions. Wasabi storage policies and minimum-retention billing can make short-lived readiness objects, replaced objects, and deleted test data billable for a minimum period. Review the provider's current pricing and immutability policy before using it as a live mutable namespace.

Do not enable compliance-mode immutability for Jiandu's live prefix. If immutable retention is a requirement, apply it to exported recovery backups in a separate destination.

Other S3-compatible systems

Start with path-style requests and a provider-issued region:

{
  "backend": "s3",
  "bucket": "jiandu-documents",
  "region": "us-east-1",
  "endpoint": "https://objects.example.net",
  "prefix": "primary",
  "work_root": "/var/lib/jiandu/storage-work",
  "allow_http": false,
  "virtual_hosted_style": false
}

The service must correctly implement:

• SigV4 authentication;
• prefix listing;
• HEAD, GET, PUT, copy, and delete;
• multipart upload for non-empty content;
• stable ETag or version preconditions used for verified reads; and
• immediate enough read-after-write/list behavior for publication and readiness.

A successful aws s3 ls proves very little. Validate the configuration, start Jiandu, check readiness, upload a file larger than 8 MiB, download it, delete a disposable document, create a backup, and restore it in isolation.

Troubleshoot systematically

Failure	Check
NoCredentials or startup storage error	Credentials are present in the Jiandu process, not only in your CLI profile
Signature mismatch	region, endpoint host, system clock, and whether the provider expects path-style requests
DNS or certificate mismatch	The endpoint is the API hostname and its CA is trusted by the Jiandu runtime
403 on readiness	Credential can put, get, and delete inside the exact prefix
Large upload fails	Multipart permissions and provider multipart compatibility
Delete or recovery fails	Delete/copy capability, retention, legal hold, or immutability policy

Keep the prior namespace untouched when diagnosing a configuration change. Changing endpoint, bucket, region, or prefix does not migrate objects.