Apache jclouds 2.7.0 配置参数详解

jclouds 是纯嵌入式 SDK（无守护进程），"配置"集中在 ContextBuilder 构建上下文时传入的 provider 名、credentials、overrides 与 modules。本文实测环境：jclouds 2.7.0（filesystem provider + jclouds-allblobstore）+ Temurin 17.0.20.1 + Maven 3.9.16（Ubuntu 22.04 容器）。标注"实测"的内容为容器内真实回显；标注"参考"的内容来自官方文档/源码常量。

一、ContextBuilder 五段配置链路

BlobStoreContext ctx = ContextBuilder.newBuilder("filesystem")   // 1. provider 标识
        .credentials("identity", "credential")                    // 2. 凭证
        .endpoint("https://...")                                  // 3. 端点（可选，私有云/自建网关）
        .overrides(overrides)                                     // 4. Properties 覆盖
        .modules(modules)                                         // 5. 注入模块（可选）
        .build(BlobStoreContext.class);

段	必填	说明
`newBuilder(provider)`	是	provider 名，决定整个 API 绑定（实测 `filesystem`）
`credentials(identity, credential)`	是	字符串对；filesystem 这类本地 provider 不校验但不可传 null（实测传任意非空串可跑）
`endpoint(...)`	否	覆盖 provider 默认端点，私有云（如自建 OpenStack/S3 网关）用
`overrides(Properties)`	否	运行时属性覆盖，见第二章
`modules(...)`	否	额外 Guice 模块/HTTP 引擎，见第六章

二、overrides 属性

2.1 filesystem provider 的关键属性（实测）

Properties overrides = new Properties();
overrides.setProperty("jclouds.filesystem.basedir", "/tmp/blobstore");

jclouds.filesystem.basedir 指定本地对象存储根目录，落盘结构实测为 basedir/<桶名>/<对象名>。不指定时依赖 provider 默认值，落盘位置不可控——生产必须显式指定。

2.2 通用 jclouds.* 属性（参考，源码 org.jclouds.Constants）

属性	作用
`jclouds.connection-timeout`	建连超时（毫秒）
`jclouds.so-timeout`	Socket 读超时（毫秒）
`jclouds.max-retries`	请求最大重试次数
`jclouds.retry-delay-start` / `jclouds.retry-delay-limit`	重试退避起止
`jclouds.max-session-failures`	会话失效阈值（触发重认证）
`jclouds.logger.prototype`	日志格式模板
`jclouds.user-threads` / `jclouds.tool-threads`	线程池规模

命名规律：provider 专属属性以 jclouds.<provider名>. 为前缀（如 jclouds.filesystem.basedir），通用属性为 jclouds.<名字>。

三、credentials 各 provider 差异（参考）

provider	identity	credential
filesystem	任意非空串	任意非空串（不校验，实测）
aws-s3	Access Key ID	Secret Access Key
azureblob	Storage Account	Account Key
google-cloud-storage	项目/服务账号	JSON 私钥
openstack-swift	`tenant:user`	password
rackspace-cloudfiles-us	用户名	API Key

凭据安全：从环境变量/Vault 注入，不要写进源码或打包进 jar。

四、endpoint 与私有云接入（参考）

ContextBuilder.newBuilder("aws-s3")
        .endpoint("https://minio.internal:9000")
        .credentials("minio", "minio123")
        .build(BlobStoreContext.class);

典型场景：S3 协议兼容对象存储（MinIO/Ceph RGW）走 aws-s3 provider + 自定义 endpoint；OpenStack Swift 内网走 openstack-swift + Keystone endpoint。endpoint 不传时用 provider 内置公共云端点。

五、BlobStore 上下文 API 面（实测涉及的方法）

实测示例使用到的核心 API：

BlobStore bs = ctx.getBlobStore();
bs.createContainerInLocation(null, "demo-container");  // 建桶
bs.putBlob("demo-container", blob);                    // 上传
bs.getBlob("demo-container", "hello.txt");             // 下载
bs.list("demo-container");                             // 列举对象
ctx.getBlobStore().listAssignableBlobStores()...       // 列举桶（filesystem）

配置相关注意：createContainerInLocation(null, name) 的 Location 参数在 filesystem provider 下传 null 即可；桶名/对象名各 provider 有命名约束，filesystem 较宽松，公有云较严格。

六、Guice 模块与 HTTP 引擎（参考）

默认 HTTP 引擎 jdk；可用 modules(ImmutableSet.of(new ApacheHCHttpModule())) 等替换（依赖需自加）；
注入自定义 InvocationContext 拦截器做审计/限流；
大多数场景不需要自定义 modules，保持默认。

七、日志配置（实测）

classpath 无 SLF4J 绑定 → 完全静默（运行期不输任何日志）；引入 slf4j-simple（实测 2.0.13）→ 简明 INFO 输出。jclouds 日志器按"层级"命名（jclouds.headers、jclouds.wire、jclouds.compute 等），细粒度调日志级别用 log4j2/logback 配置对应 logger。

八、provider 清单与选型速查（参考）

类别	provider
本地/测试	filesystem
AWS	aws-s3、aws-ec2、aws-sqs、aws-elb
Azure	azureblob
Google	google-cloud-storage
OpenStack	openstack-swift、openstack-nova、openstack-neutron
其他公有云	rackspace-*、glesys、digitalocean2

模块坐标规律：BlobStore API 聚合包 org.apache.jclouds:jclouds-allblobstore，单 provider API 在 org.apache.jclouds.api:<name>（实测 filesystem 正是如此），计算类 provider 在 org.apache.jclouds.provider:<name>。

九、资源释放与生命周期（实测）

BlobStoreContext 持有连接池/线程池，用完必须关闭：

ctx.close();

实测说明：demo 在 finally 块中 close；生产建议 try-with-resources（BlobStoreContext 实现 AutoCloseable）。长期驻留的服务进程建议按"目标云"缓存 Context 实例复用，避免反复握手。

十、FAQ

Q1：filesystem provider 也必须传 credentials 吗？ API 层必填（不传抛异常），但内容不校验——实测 credentials("identity","credential") 直接可跑。

Q2：jclouds.filesystem.basedir 不设置会怎样？ 依赖 provider 默认值，落盘目录不可控；实测建议显式设置，demo 用 /tmp/blobstore。

Q3：MinIO 怎么接？ provider 用 aws-s3 + endpoint 指向 MinIO（第四章参考用法）；jclouds 无专门 MinIO provider。

Q4：2.7.0 需要 Java 几？ 实测 Java 17 编译运行全通过；官方支持基线为 Java 8+。

Q5：能同时开多个 provider 的 Context 吗？ 能。Context 之间独立，按目标云分别 build/close。

Q6：overrides 里的属性名写错会怎样？ 未知属性被静默忽略——没有严格校验，注意拼写（对照源码 Constants）。

Q7：怎么开请求级调试日志？ 绑定 SLF4J 后把 jclouds.headers/jclouds.wire logger 调 DEBUG/TRACE。

Q8：putBlob 的 etag 有什么用？ 服务端内容指纹；filesystem 实测返回 MD5（示例 etag=a3a4252fe7d5160bb03d371206877c3a 对应内容 "Hello jclouds filesystem blobstore!"），可用于上传后校验。

Q9：容器/桶能改名吗？ 不能，只能新建后迁移对象。

Q10：API 代差怎么看（jclouds 已退役的影响）？ jclouds 2.7.0 为最终版（项目已入 Apache Attic）；已有依赖可继续使用，新功能无后续，新项目选型需评估（见介绍篇第七章）。

参考链接

jclouds 配置参考：https://jclouds.apache.org/reference/configuration/
BlobStore 文档：https://jclouds.apache.org/guides/blobstore/
介绍篇实测：《Apache jclouds 介绍与集成入门详解》