# @backloghq/opslog-s3 中文文档

规范地址：https://npmcn.com/package/%40backloghq/opslog-s3/

版本：0\.4\.1
npm 元数据更新时间：2026-05-05T10:32:23.060Z
中文译文更新时间：2026-11-07T23:48:06.090Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40backloghq/opslog-s3
原文对照：https://npmcn.com/package/%40backloghq/opslog-s3/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：28.2 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：@backloghq/opslog \>=0\.8\.0
- 首次发布：2026-04-09T17:55:23.844Z
- 最新版本发布：2026-05-05T10:32:22.936Z
- 近 30 天下载量：1982（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

@backloghq/opslog的S3存储后端. 通过亚马逊 S3 启用多写机货币跨机.

## 安装

```sh
npm install @backloghq/opslog-s3
```

也可以使用：`pnpm add @backloghq/opslog-s3`、`yarn add @backloghq/opslog-s3`、`bun add @backloghq/opslog-s3`

## README

# 行动日志-s3

Amazon S3 存储后端 [@ backloghq/ opslog 页面存档备份,存于互联网档案馆](https://github.com/backloghq/opslog)。将您的事件源数据存储在 S3 中,并允许多写机的货币.

## 安装

```bash
npm install @backloghq/opslog @backloghq/opslog-s3
```

## 使用量

```typescript
import { Store } from "@backloghq/opslog";
import { S3Backend } from "@backloghq/opslog-s3";

const store = new Store<{ title: string; status: string }>();
await store.open("my-store", {
  backend: new S3Backend({
    bucket: "my-bucket",
    prefix: "opslog/my-store",
    region: "us-east-1",
  }),
  agentId: "agent-A",
});

await store.set("task-1", { title: "Build API", status: "active" });
const task = store.get("task-1");
await store.close();
```

另一台不同机器上的代理可以写给同一商店:

```typescript
const store = new Store<{ title: string; status: string }>();
await store.open("my-store", {
  backend: new S3Backend({
    bucket: "my-bucket",
    prefix: "opslog/my-store",
    region: "us-east-1",
  }),
  agentId: "agent-B",
});

// Sees agent-A's writes
store.get("task-1"); // { title: "Build API", status: "active" }

// Writes to its own WAL — no contention with agent-A
await store.set("task-2", { title: "Write tests", status: "active" });
await store.close();
```

## 选项

```typescript
new S3Backend({
  bucket: "my-bucket",         // S3 bucket name (required)
  prefix: "path/to/store",    // Key prefix (optional, no trailing slash)
  region: "us-east-1",        // AWS region (required if no client provided)
  client: myS3Client,         // Pre-configured S3Client (optional)
  lockTtlMs: 60000,           // Lock TTL in ms (default: 60000)
});
```

### 预配置客户端

自己传 `S3Client` 如果您需要自定义配置( 证书、 终点、 中间软件) :

```typescript
import { S3Client } from "@aws-sdk/client-s3";

const client = new S3Client({
  region: "us-east-1",
  endpoint: "http://localhost:9000", // MinIO, LocalStack, etc.
  forcePathStyle: true,
});

const backend = new S3Backend({ bucket: "my-bucket", client });
```

## 如何运作

### 存储布局

```
s3://bucket/prefix/
  manifest.json                       # Store metadata
  snapshots/snap-<ts>.jsonl           # Immutable state captures (JSONL)
  ops/agent-<id>-<ts>.jsonl           # Per-agent WAL files
  archive/archive-<period>.json       # Archived records
```

### WAL 操作( 每批对象)

S3没有本地附件。 S3Backend 不再下载,并重新加载一个正在增长的单一文件,而是将每个文件作为单独的S3对象存储:

```
ops/agent-A-1744200000/
  batch-1744200001-0000.jsonl   (ops from first write)
  batch-1744200002-0000.jsonl   (ops from second write)
  batch-1744200003-0000.jsonl   (ops from third write)
```

-   **附录**: 单发对象( 不需要下载)
-   **读取**: List ObjectsV2 + 平行 Get Object 每批, 有增量缓存( 在后续读取时只下载了新批)
-   **截断**: 删除上一个批次对象(或如果包含多个操作则修改)

用 v. 1. 0 (单) 创建的存储 `.jsonl` 文件)是透明支持的——后端自动检测出格式.

### 锁定

使用 S3 有条件的写法( U)`IfNoneMatch: *`)用于锁定获取——如果锁定已经存在,则在解剖上失败. 被锁的物体携带TTL;从坠毁的特工中自动取回被困的锁.

### Blob 存储 + 字节范围读取

```typescript
await backend.writeBlob("data/records.jsonl", buffer);
const full = await backend.readBlob("data/records.jsonl");
const range = await backend.readBlobRange("data/records.jsonl", 1024, 256); // HTTP Range header
```

`readBlobRange` 使用 S3 `GetObject` 与 `Range: bytes=N-M` 页眉 — 只读取请求的字节 。 在JSONL唱片商店中启用O(1)点取景,而无需下载完整对象.

### 解决冲突

当多个代理给同一密钥写信时,OPslog的Lamport时钟命令通过最后的写作胜出解决冲突. 见 [操作日志多写文件](https://github.com/backloghq/opslog#multi-writer-mode) 详细情况.

## IAM 权限

S3Backend 在桶/前缀上需要这些 S3 权限 :

```json
{
  "Effect": "Allow",
  "Action": [
    "s3:GetObject",
    "s3:PutObject",
    "s3:DeleteObject",
    "s3:ListBucket"
  ],
  "Resource": [
    "arn:aws:s3:::my-bucket",
    "arn:aws:s3:::my-bucket/opslog/*"
  ]
}
```

## 发展

```bash
npm run build          # Compile TypeScript
npm run lint           # ESLint
npm test               # Run tests (uses in-memory mock S3, no AWS needed)
npm run test:coverage  # Tests with coverage
```

## 许可证

麻省理工学院

## 常见问题

### @backloghq/opslog-s3 是什么？

@backloghq/opslog的S3存储后端\. 通过亚马逊 S3 启用多写机货币跨机\.

### 如何安装 @backloghq/opslog-s3？

在项目目录运行 npm install @backloghq/opslog-s3，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@backloghq/opslog（\>=0\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @backloghq/opslog-s3 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @backloghq/opslog-s3 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @backloghq/opslog-s3 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @backloghq/opslog-s3 可以商用吗？

@backloghq/opslog-s3 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @backloghq/opslog-s3 的下载量有多少？

根据 npm 官方下载统计，@backloghq/opslog-s3 在 2026/10/08 – 2026/11/06 这 30 天内被下载 1,982 次，日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @backloghq/opslog-s3 还在维护吗？

最新版本 0\.4\.1 发布于 2026/05/05（6 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/04/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。