> ## Documentation Index
> Fetch the complete documentation index at: https://java.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 分布式存储（Distributed Store）

AgentScope 将所有需要分布式持久化的组件统一到 `DistributedStore` 接口下。一行配置即可让 Agent 的状态、工作区文件系统、沙箱快照和并发锁全部切到同一个分布式后端。

## 快速上手

```java theme={null}
// Redis 一键配置
DistributedStore store = RedisDistributedStore.fromJedis(
        new JedisPooled("redis://localhost:6379"));

HarnessAgent agent = HarnessAgent.builder()
    .name("my-agent")
    .model("dashscope:qwen-plus")
    .distributedStore(store)
    .filesystem(new RemoteFilesystemSpec()            // baseStore 自动注入
            .isolationScope(IsolationScope.USER))
    .build();
```

## 能力矩阵

| 功能组件        | 接口                      |             Redis            |          OSS         |            MySQL            |
| ----------- | ----------------------- | :--------------------------: | :------------------: | :-------------------------: |
| Agent 状态持久化 | `AgentStateStore`       |    `RedisAgentStateStore`    | `OssAgentStateStore` |    `MysqlAgentStateStore`   |
| 工作区文件系统 KV  | `BaseStore`             |         `RedisStore`         |    `OssBaseStore`    |         `JdbcStore`         |
| 沙箱快照        | `SandboxSnapshotSpec`   |      `RedisSnapshotSpec`     |   `OssSnapshotSpec`  |      `JdbcSnapshotSpec`     |
| 沙箱并发锁       | `SandboxExecutionGuard` | `RedisSandboxExecutionGuard` |           —          | `JdbcSandboxExecutionGuard` |

> OSS 不提供 `SandboxExecutionGuard`——对象存储不适合做分布式锁。需要 sandbox 并发控制的 OSS 用户，用 `DistributedStore.builder()` 混入 Redis 的 guard。

## 混合后端

不同组件可以来自不同的存储后端：

```java theme={null}
DistributedStore mysql = MysqlDistributedStore.create(dataSource);
DistributedStore redis = RedisDistributedStore.fromJedis(jedis);

// MySQL 管状态和文件，Redis 管沙箱锁和快照
DistributedStore mixed = DistributedStore.builder()
    .agentStateStore(mysql.agentStateStore())
    .baseStore(mysql.baseStore())
    .sandboxSnapshotSpec(redis.sandboxSnapshotSpec())
    .sandboxExecutionGuard(redis.sandboxExecutionGuard())
    .build();

HarnessAgent.builder()
    .distributedStore(mixed)
    .filesystem(new DockerFilesystemSpec()
            .image("ubuntu:24.04"))
    .build();
```

## 各组件说明

### AgentStateStore — Agent 状态持久化

Agent 的对话上下文、压缩摘要、权限规则、Plan Mode 状态等，通过 `(userId, sessionId)` 寻址。`distributedStore` 自动注入，也可通过 `.stateStore(...)` 单独覆盖。

### BaseStore — 工作区文件系统 KV

`RemoteFilesystemSpec` 的存储后端，将 `MEMORY.md`、`memory/`、`skills/`、`sessions/` 等路径路由到共享 KV 存储。`distributedStore` 自动注入到 `RemoteFilesystemSpec`（如果用的是无参构造器）。

### SandboxSnapshotSpec — 沙箱快照

将 Docker/K8s 等沙箱的工作区打成 tar 包持久化，下次 `call()` 自动恢复。`distributedStore` 自动注入到 `SandboxFilesystemSpec`。

### SandboxExecutionGuard — 沙箱并发锁

`AGENT` / `GLOBAL` 隔离范围在多副本下需要分布式锁防止并发冲突。`distributedStore` 自动注入到 `SandboxFilesystemSpec`。

## 优先级

```
显式 builder 方法 (.stateStore(), .filesystem() 上的 .snapshotSpec() 等)
    > distributedStore 自动注入
        > 本地默认 (JsonFileAgentStateStore, NoopSnapshotSpec 等)
```

## 后端详细文档

* [Redis](/v2/zh/integration/distributed/redis) — 最全功能覆盖，多副本生产首选
* [MySQL / JDBC](/v2/zh/integration/distributed/mysql) — 已有关系型数据库的场景
* [阿里云 OSS](/v2/zh/integration/distributed/oss) — 对象存储，大容量快照首选

## aistio 托管 Store

若已部署 aistio 控制面，可由控制面托管 `DistributedStore` 的协调类能力（BaseStore、沙箱锁/快照、MessageBus、AsyncToolRegistry、**TaskRepository**、可选 **SessionTurnGate**）。**`AgentStateStore` 仍需自备一个后端**（Redis / MySQL / Postgres / OSS）；core 已提供 `getVersioned` / `saveIfVersion` 乐观并发，但存储不在控制面。

```java theme={null}
ControlPlaneStores cp = ControlPlaneStores.fromEnv();
HarnessAgent.builder()
    .distributedStore(cp.withAgentStateStore(redis.agentStateStore()))
    .filesystem(new RemoteFilesystemSpec().isolationScope(IsolationScope.USER))
    .build();
```

* 控制面开启：`--enable-hosted-store`（生产建议 Postgres）。
* **`withAgentStateStore` 已包含**托管 `TaskRepository` 与 `SessionTurnGate`。使用 **`SandboxFilesystemSpec` 且需要子 agent 后台任务**时，应走此路径（workspace 版 `TaskRepository` 无法跨副本持久化任务）。
* **AgentStateStore versioning**：Redis、Postgres、MySQL、InMemory 支持 CAS；JsonFile / OSS / COS / JPA 仍为 last-writer-wins。多副本建议选支持 versioning 的后端。
* **Turn gate + `ConflictPolicy.FAIL`** 为可选：多副本下减少重复 LLM turn；正确性仍靠 CAS（当后端支持 versioning 时）。
* 当前鉴权为集群内共享 internal token；租户（`agentName` / `namespace`）取自请求体——**不适用于**同一控制面上互不信任的多租户。
* `MessageBus.queueDrain` 为 **destructive**（读即 ack）；租户/key 弄错会丢消息。