# https://github.com/filecoin-project/filecoin-pin 项目说明书

生成时间：2026-06-25 23:13:13 UTC

## 目录

- [Project Overview & Architecture](#page-1)
- [CLI Commands Reference](#page-2)
- [JavaScript Library & Core API](#page-3)
- [Configuration, Deployment & Operations](#page-4)

<a id='page-1'></a>

## Project Overview & Architecture

### 相关页面

相关主题：[CLI Commands Reference](#page-2), [JavaScript Library & Core API](#page-3), [Configuration, Deployment & Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md)
- [documentation/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/README.md)
- [documentation/behind-the-scenes-of-adding-a-file.md](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/behind-the-scenes-of-adding-a-file.md)
- [documentation/glossary.md](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/glossary.md)
- [src/core/data-set/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/index.ts)
- [src/core/payments/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md)
- [src/core/payments/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/index.ts)
- [src/core/payments/constants.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/constants.ts)
- [src/core/utils/format.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/utils/format.ts)
- [src/core/car/car-storage-backend.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/car/car-storage-backend.ts)
- [src/utils/cli-auth.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts)
- [upload-action/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/README.md)
- [upload-action/src/types.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/src/types.ts)
- [upload-action/src/github.js](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/src/github.js)

</details>

# 项目概览与架构

## 一、项目定位与目标

**filecoin-pin** 是一个将数据存储到 [Filecoin Onchain Cloud](https://filecoin.cloud) 的参考实现与工具集。它通过封装底层的 [Synapse SDK](https://synapse.filecoin.services/)，为开发者提供一致、简单且可复用的接口，将文件以 IPFS 内容寻址方式上传至 Filecoin 网络并生成可检索的 CID。

项目的核心定位包括三方面（资料来源：[README.md:1-15]()）：

1. **多种用户交互形式**：CLI 命令行工具、JavaScript 库、可复用的 GitHub Action，以及一个处于 Beta 阶段的 IPFS Pinning Server（`filecoin-pin server`）。
2. **共享核心库**：所有交互层复用 `filecoin-pin/core/*` 模块，确保行为一致。
3. **遥测与可观测性**：内置遥测默认开启，但始终支持用户禁用（README 明确说明 "Telemetry always has a way to be disabled"）。

> 📦 安装方式：`npm install --save filecoin-pin`（资料来源：[README.md:10-15]()）

## 二、整体系统架构

项目在用户交互层与 Filecoin Onchain Cloud 智能合约、存储提供者（SP）之间建立了一个清晰的分层。CLI、GitHub Action 与 JS 库均通过共享的 `core/` 模块调用 Synapse SDK，再由 SDK 与 PDP 服务、WarmStorage 合约以及 Filecoin Pay 合约交互。

```mermaid
flowchart TB
    subgraph 用户层["User-facing Affordances"]
        CLI["filecoin-pin CLI"]
        LIB["filecoin-pin (JS Library)"]
        ACT["upload-action (GitHub Action)"]
        SVR["filecoin-pin server (IPFS Pinning API)"]
    end

    subgraph 核心层["Shared Core Library (src/core)"]
        SYNAPSE["core/synapse"]
        UPLOAD["core/upload"]
        DATA["core/data-set"]
        PAY["core/payments"]
        CAR["core/car"]
        UTIL["core/utils"]
    end

    subgraph 外部["Filecoin Onchain Cloud"]
        SDK["@filoz/synapse-sdk"]
        WS["WarmStorage 合约"]
        FP["Filecoin Pay 合约"]
        SP["存储提供者 (PDP)"]
    end

    CLI --> SYNAPSE
    LIB --> SYNAPSE
    ACT --> UPLOAD
    SVR --> SYNAPSE

    SYNAPSE --> SDK
    UPLOAD --> SDK
    DATA --> SDK
    PAY --> SDK
    CAR --> UPLOAD
    UTIL --> PAY

    SDK --> WS
    SDK --> FP
    SDK --> SP
```

> 资料来源：[README.md:55-80]()、[src/core/payments/README.md:1-25]()

## 三、核心模块组成

`src/core/` 是所有用户交互层共享的业务逻辑入口。下表列出主要子模块及其职责。

| 模块 | 路径 | 职责 |
|------|------|------|
| `core/synapse` | `src/core/synapse/index.ts` | SDK 初始化、网络选择、私钥/会话密钥管理、WebSocket 清理、单例服务模式（资料来源：[src/utils/cli-auth.ts:1-50]()） |
| `core/upload` | `src/core/upload/index.ts` | CAR 文件统一上传接口、进度回调、CID 与 Piece 关联、SP 直链生成 |
| `core/data-set` | `src/core/data-set/index.ts` | 列出/查询数据集、获取 Piece 详情、按元数据解析、实际存储计算（资料来源：[src/core/data-set/index.ts:1-25]()） |
| `core/payments` | `src/core/payments/index.ts` | FIL/USDFC 余额查询、Filecoin Pay 存款与提款、资金计划（Funding Plan）（资料来源：[src/core/payments/index.ts:1-40]()） |
| `core/car` | `src/core/car/` | CAR 块存储抽象（内存/文件系统后端），见 [src/core/car/car-storage-backend.ts:1-40]() |
| `core/utils` | `src/core/utils/format.ts` | 数值格式化（FIL/USDFC）、运行时间（runway）人类可读化输出 |

支付层定义了一组关键常量，如 `MIN_FIL_FOR_GAS`、`DEFAULT_LOCKUP_DAYS`、`USDFC_DECIMALS` 等，统一集中于 [src/core/payments/constants.ts:1-30]()，便于在 CLI、库与 Action 中保持一致行为。

## 四、CLI 与 GitHub Action 用户层

### 4.1 CLI 命令行

`filecoin-pin` CLI 提供多种命令组，覆盖上传、检索、支付、数据集管理与服务器模式。社区近期关注点包括：

- **命令分组与快速入门**（[#576](https://github.com/filecoin-project/filecoin-pin/issues/576)）：建议重排 `--help` 输出，将 `add`、`import` 提前，并提示 `payments` 需在首次上传前完成。
- **`data-set list` 紧凑视图**（[#578](https://github.com/filecoin-project/filecoin-pin/issues/578)）：v1.1.0 中已实现紧凑摘要输出，详细数据通过 `data-set show <id>` 获取。
- **`--dry-run` 预估算**（[#591](https://github.com/filecoin-project/filecoin-pin/issues/591)）：用户希望在真正上传前获得 packed size 与费用估算。
- **检索闭环**（[#575](https://github.com/filecoin-project/filecoin-pin/issues/575)）：提议新增 `filecoin-pin get` 命令，从 SP 拉回存储内容。

### 4.2 GitHub Action（upload-action）

`upload-action/` 是一个独立的 GitHub Action，使用语义化版本标签发布（`@v0`、`@v0.9.1` 等）。它接收 PR 上下文、构建产物（CAR），并通过 `core/upload` 完成上传（资料来源：[upload-action/README.md:1-60]()、[upload-action/src/types.ts:1-80]()）。

关键安全约束包括：

- 拒绝 fork PR 的上传事件，防止非维护者 PR 触发钱包操作。
- 强制硬编码 `minRunwayDays` 和 `maxBalance`，禁止在不可信工作流中放宽。
- 使用 GitHub Environments 进行人工审批，规避资金滥用风险。
- 对 `pull_request_target` 触发器与 `workflow_run` 的产物进行来源校验（资料来源：[upload-action/README.md:30-80]()）。

## 五、社区与近期发展

v1.1.0（2026-06-25）主要变更（资料来源：[GitHub Releases v1.1.0](https://github.com/filecoin-project/filecoin-pin/releases/tag/v1.1.0)）：

- ✅ `data-set list` 紧凑摘要输出
- ✅ 重排 CLI `--help` 分组与快速入门示例
- ✅ 升级 `synapse-sdk` 到 v1.0.1、`synapse-core` 到 v0.7.0（含 BREAKING CHANGES）

社区持续讨论的开放议题：

- [#527](https://github.com/filecoin-project/filecoin-pin/issues/527)：将 `upload-action` 提取为独立仓库以实现独立版本管理。
- [#589](https://github.com/filecoin-project/filecoin-pin/issues/589)：调研 1Password / LastPass / Bitwarden 等私密保险库对私钥的集成。
- [#306](https://github.com/filecoin-project/filecoin-pin/issues/306)：跟进 IPIP-499 提案的 `unixfs-v1-2025` 现代 CID 配置，评估目录包裹与隐藏文件策略。
- [#464](https://github.com/filecoin-project/filecoin-pin/issues/464)：将 `--egress-provider beam` 作为 `add`/`import` 的默认行为。
- [#581](https://github.com/filecoin-project/filecoin-pin/issues/581)：确认 `data-set terminate` 中 `skipProvider: true` 是否仍是正确默认。

## See Also

- [Behind the Scenes of Adding a File](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/behind-the-scenes-of-adding-a-file.md) — 深入解析 `add` 流程的底层细节。
- [Filecoin Pin Glossary](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/glossary.md) — 统一术语表（Synapse、PDP、FWSS 等）。
- [Content Routing FAQ](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/content-routing-faq.md) — IPNI 缓存、Provider 管理与索引器常见问题。
- [Retrieving Your Data](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/retrieval.md) — 从 SP、信任网关或 IPFS CID 检索数据的方法。
- [Progress Events](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/progress-events.md) — 库级 `onProgress` 事件类型约定。
- [DEVELOPMENT.md](https://github.com/filecoin-project/filecoin-pin/blob/main/DEVELOPMENT.md) — 本地开发、脚本、HTTP 追踪与未发布 Synapse SDK 的工作流。

---

<a id='page-2'></a>

## CLI Commands Reference

### 相关页面

相关主题：[Project Overview & Architecture](#page-1), [JavaScript Library & Core API](#page-3), [Configuration, Deployment & Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md)
- [documentation/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/README.md)
- [src/utils/cli-auth.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts)
- [src/utils/cli-options.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options.ts)
- [src/utils/cli-logger.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-logger.ts)
- [src/utils/cli-helpers.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-helpers.ts)
- [src/utils/cli-options-metadata.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options-metadata.ts)
- [src/core/payments/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/index.ts)
- [src/core/data-set/types.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/types.ts)
- [upload-action/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/README.md)
- [upload-action/examples/cli-recipe/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/examples/cli-recipe/README.md)
</details>

# CLI Commands Reference

## 概述与设计目标

`filecoin-pin` 是一个面向 Filecoin Onchain Cloud 的"即插即用"工具集，CLI 是其主要交互形式之一。CLI 以 Commander.js 框架为基础构建，按"命令组（command groups）+ 共享选项（shared options）+ 全局标志（global flags）"的模式组织：每个命令暴露统一的身份认证、网络与 RPC、Provider / DataSet 选择与元数据选项，确保 CLI、GitHub Action 与 JavaScript 库三者行为一致。

CLI 的核心目标可以归纳为以下几点：

- **降低 Filecoin 存储的接入门槛**：通过 `add`、`import`、`get` 等少数命令完成"打包 → 上链 → 检索"完整闭环，无需用户直接处理 Synapse SDK、合约、Provider 选择等底层细节。
- **保证多入口一致性**：CLI 与 [`filecoin-pin` JavaScript 库](README.md) 共享 `src/core/` 下的业务逻辑层。
- **支持脚本化与 CI 场景**：通过 `applyVerboseLogLevel`、环境变量回退（`PRIVATE_KEY`、`SESSION_KEY`、`RPC_URL` 等）以及非 TTY 输出降级，CLI 能在 CI 与交互终端下表现一致。
- **可观测性**：CLI 自带遥测开关；通过 `-v/--verbose` 在调试时打开 `LOG_LEVEL=debug`，参见 [src/utils/cli-logger.ts:14-23](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-logger.ts)。

v1.1.0 版本（[release notes](https://github.com/filecoin-project/filecoin-pin/releases/tag/v1.1.0)）重点重构了 `--help` 输出：使用命令组（例如 `Upload`、`Payments`、`Data sets`）并附 quick-start 示例，回应了社区长期反馈（如 [#576](https://github.com/filecoin-project/filecoin-pin/issues/576) "reorganize `--help` output with command groups"）。

## 全局标志与共享选项

CLI 大多数命令都会复用以下选项，集中在 `src/utils/` 中以 Commander.js 工厂函数形式提供：

| 选项 / 环境变量 | 说明 | 主要来源 |
|---|---|---|
| `--private-key <key>` / `PRIVATE_KEY` | 用于标准身份认证的私钥（也支持 `--wallet-address` + `--session-key` 模式） | [src/utils/cli-options.ts:25-27](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options.ts) |
| `--session-key <key>` / `SESSION_KEY` | 会话密钥签名模式 | [src/utils/cli-options.ts:29-31](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options.ts) |
| `--rpc-url <url>` / `RPC_URL` | 覆盖默认 RPC 节点；与 `--network` 互斥 | [src/utils/cli-options.ts:33-35](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options.ts) |
| `--network <mainnet\|calibration\|devnet>` / `NETWORK` | 切换 Filecoin 网络；默认 mainnet | [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md) |
| `--provider-id <id>`（可重复）/ `--provider-ids` | 限定 Storage Provider，可使用逗号分隔别名 | [src/utils/cli-auth.ts:22-30](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts) |
| `--data-set-id <id>`（可重复）/ `--data-set-ids` | 限定或复用现有 DataSet | [src/utils/cli-auth.ts:31-38](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts) |
| `--metadata <key=value>` | 重复设置 piece 元数据 | [src/utils/cli-options-metadata.ts:33-39](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options-metadata.ts) |
| `--data-set-metadata <key=value>` / `--dataset-metadata`（别名） | 重复设置 data set 元数据 | [src/utils/cli-options-metadata.ts:41-51](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options-metadata.ts) |
| `--erc8004-type <type>` | 可选的 ERC-8004 工件类型 | [src/utils/cli-options-metadata.ts:53-58](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options-metadata.ts) |
| `-v/--verbose`、`-h/--help`、`-V/--version` | 全局行为开关 | [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md) |

注意 `--network` 与 `--rpc-url` 二者不能同时设置，否则报错；当使用 `--rpc-url` 时，CLI 会在启动时探测 `eth_chainId` 并自动推断所属链（mainnet / calibration / 已配置的 devnet），见 [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md)。

## 命令组与典型工作流

CLI 命令按职责归类（v1.1.0 起 `--help` 改用命令组视图）。下面是按组归类后的常用命令及其作用：

### 上传与导入（Upload / Import）

- `filecoin-pin add <path>`：读取本地文件或目录，通过 Helia 打包为 UnixFS CAR，再经 `core/upload` 经由 Synapse SDK 推送到所选 Provider。社区正在提议的 `--dry-run`（[#591](https://github.com/filecoin-project/filecoin-pin/issues/591)）允许在真正提交前估算 packed size 与成本。
- `filecoin-pin import <car>`：跳过打包阶段，直接上传已存在的 CAR 文件，适合在 CI 里把构建产物直接转给 Filecoin。

`add` 与 `import` 还可能消费 `--egress-provider`（[#464](https://github.com/filecoin-project/filecoin-pin/issues/464)）：默认 `beam`（通过 Beam 中转加速回源），可通过 `--egress-provider none` 关闭。

### 数据集管理（Data sets）

- `data-set list`：列出当前钱包持有的全部数据集。v1.1.0 后默认采用紧凑摘要视图，详细数据需通过 `data-set show <datasetID>` 查阅，对应 [#578](https://github.com/filecoin-project/filecoin-pin/issues/578)。
- `data-set show <datasetID>`：展示指定数据集的完整信息；当数据集较大时输出容易膨胀，社区讨论中的 `piece-status` 分页（[#579](https://github.com/filecoin-project/filecoin-pin/issues/579)）正是为了解决相同根因。
- `data-set terminate <datasetID>`：调用 Synapse SDK 的 `terminateService` 终止合约；CLI 显式传入 `skipProvider: true`（参见 [#581](https://github.com/filecoin-project/filecoin-pin/issues/581)），跳过 Provider 端动作，直接走链上结算路径。

### 支付与预付金（Payments）

`payments` 子命令组封装 [src/core/payments/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/index.ts) 中的 `Synapse` 支付操作，主要能力包括：

- 查询 native FIL（用于 gas）与 USDFC（用于服务费）余额；
- 计算锁仓（lockup）与按 `--min-runway-days` / `--max-balance` 决定的额外充值金额（参见 [src/core/payments/funding.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/funding.ts) 中 `planFilecoinPayFunding`）；
- 与 Service 合约之间的 approve / deposit / withdraw / set-approval-for-all 流程。

社区普遍反馈 `payments` 应当被列在 `--help` 顶部，并明确提示"必须先充值再上传"，该诉求正是 [#576](https://github.com/filecoin-project/filecoin-pin/issues/576) 的核心内容。

### 检索与守护进程（Get / Server）

- `filecoin-pin get <cid>`：基于上传得到的 IPFS Root CID 从 Provider 处拉回内容，闭环"上传 → 检索"，对应 [#575](https://github.com/filecoin-project/filecoin-pin/issues/575)。
- `filecoin-pin server`：在本地启动符合 [IPFS Pinning Service API 规范](https://ipfs.github.io/pinning-services-api-spec/) 的 daemon，使 `ipfs pin remote` 等标准工具能直接对接 Filecoin（参见 [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md)，处于 Beta 阶段）。

### 元数据（Metadata）

`--metadata` 与 `--data-set-metadata` 是上传命令最常用的元数据注入入口；`src/utils/cli-options-metadata.ts` 中的 `parseKeyValuePairs` 会校验 `key=value` 格式、禁止空键与重复键，避免下游 Synapse SDK 收到非法输入。元数据最终会通过 `core/upload` 关联到 Piece 或 DataSet 上。

## 典型工作流

下面是一个最小化的"充值 → 上传 → 检索"流程示例（命令可在 TTY 与 CI 两种环境下运行）：

```bash
# 1. 配置网络与钱包（环境变量方式）
export NETWORK=calibration
export PRIVATE_KEY=0x...

# 2. 检查 / 调整支付（locks up + deposit）
filecoin-pin payments status
filecoin-pin payments deposit --auto-fund --min-runway-days 30 --max-balance 100

# 3. 上传本地目录
filecoin-pin add ./dist --provider-id 1 --metadata "env=ci" --metadata "commit=$GITHUB_SHA"

# 4. 检索内容（v1.1.0 起的 get 命令对应 #575）
filecoin-pin get <root-cid> --output ./downloaded
```

若需要更强的可观测性，可以在脚本里追加 `-v`：

```bash
filecoin-pin -v add ./dist
# 等价于: LOG_LEVEL=debug filecoin-pin add ./dist
```

## 失败模式与社区关注的限制

- **GitHub Action 版本引用**：README 与早期文档建议 `filecoin-project/filecoin-pin@v1`，但 `@v1` 在 monorepo 阶段不可用；正确入口是 `filecoin-project/filecoin-pin/upload-action@v0.9.1`（见 [#130](https://github.com/filecoin-project/filecoin-pin/issues/130)）。社区已在 [#527](https://github.com/filecoin-project/filecoin-pin/issues/527) 中提议将 `upload-action/` 拆分为独立仓库，以允许其独立发版。
- **CLI 错误码矩阵尚未自动化**：v1.x 之前手写 15 个错误场景 bash 扫描验证；[#470](https://github.com/filecoin-project/filecoin-pin/issues/470) 提议把它沉淀为可复用的 smoke test 套件。
- **私钥来源**：当前私钥来源仅支持直接提供（环境变量 / 文件）；[#589](https://github.com/filecoin-project/filecoin-pin/issues/589) 与 [#457](https://github.com/filecoin-project/filecoin-pin/issues/457) 跟踪 1Password / Bitwarden 等安全保险库的接入。
- **UnixFS CID 概况**：CLI 仍以"包一层命名目录"的 UnixFS 形式生成 CAR，与 IPIP-499 默认 `unixfs-v1-2025` 存在差异，见 [#306](https://github.com/filecoin-project/filecoin-pin/issues/306)。

## See Also

- [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md) — 项目总览与安装方式
- [documentation/behind-the-scenes-of-adding-a-file.md](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/behind-the-scenes-of-adding-a-file.md) — `add` 命令的底层流程
- [documentation/retrieval.md](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/retrieval.md) — 检索相关概念与 `filecoin-pin get`
- [documentation/progress-events.md](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/progress-events.md) — 程序化使用时的进度事件
- [src/core/payments/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md) — Synapse SDK 支付集成示例
- [upload-action/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/README.md) — GitHub Action 安全与版本说明

---

<a id='page-3'></a>

## JavaScript Library & Core API

### 相关页面

相关主题：[Project Overview & Architecture](#page-1), [CLI Commands Reference](#page-2), [Configuration, Deployment & Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/filecoin-project/filecoin-pin/blob/main/package.json)
- [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md)
- [documentation/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/README.md)
- [src/core/payments/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md)
- [src/core/synapse/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/synapse/index.ts)
- [src/core/upload/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/upload/index.ts)
- [src/core/payments/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/index.ts)
- [src/core/payments/funding.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/funding.ts)
- [src/core/payments/top-up.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/top-up.ts)
- [src/core/utils/format.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/utils/format.ts)
- [src/core/data-set/list-data-sets.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/list-data-sets.ts)
- [src/utils/cli-auth.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts)
- [src/utils/cli-options-metadata.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-options-metadata.ts)
</details>

# JavaScript Library & Core API

## 目的与定位

`filecoin-pin` 仓库同时交付 CLI、GitHub Action 与 IPFS Pinning Server，但 JavaScript 库是所有这些交互方式共享的“业务核心”。README 指出，库被组织为两层：高层的 `import { … } from 'filecoin-pin'` 覆盖最常见的用例，而底层的 `import { … } from 'filecoin-pin/core/*'` 则暴露 CAR 文件、支付、Synapse SDK、Upload、UnixFS 等子模块，供需要更细粒度控制的开发者复用。资料来源：[README.md](README.md)

这种分层使得 CLI 命令、Action 步骤、dApp Demo 都共享同一份业务逻辑，避免在多个 affordance 中重复实现上传与支付流程。`documentation/README.md` 进一步将文档划分为 Cookbook、API Reference、Progress Events、Events & Metrics 等多个专题，库 API 是其中“如果你要在程序中调用”这条主线的入口。资料来源：[documentation/README.md](documentation/README.md)

## 模块结构与导出

`package.json` 中 `exports` 字段明确划分了若干子路径，最关键的有：

| 导出路径 | 用途 |
| --- | --- |
| `.` | 高层入口（推荐入口） |
| `./core` | 核心模块聚合 |
| `./core/synapse` | Synapse SDK 初始化与生命周期 |
| `./core/upload` | CAR 文件上传到 Filecoin |
| `./core/payments` | Filecoin Pay 支付与充值 |
| `./core/data-set` | 数据集管理与列表 |
| `./core/unixfs` | UnixFS 打包 |
| `./core/car` | CAR 块存储（Node/Browser 双入口） |
| `./core/utils` | 格式化、校验等工具函数 |
| `./version-check` | 与 Synapse SDK 版本兼容性检查 |

资料来源：[package.json](package.json)

`bin` 字段同时声明了 `filecoin-pin` 可执行命令，意味着同一个打包产物既可作为库导入，也可作为 CLI 运行——这是该仓库“单一代码库、双重消费模式”设计的直接体现。

## Synapse 生命周期与 SDK 封装

`core/synapse` 模块承担 SDK 初始化的全部职责，README 与源代码都强调：Synapse 是与 [Filecoin Onchain Cloud](glossary.md#filecoin-onchain-cloud) 智能合约、存储服务提供方交互的主要库。`src/core/payments/README.md` 列举了 SDK 初始化的核心模式，包括网络选择、RPC URL、私钥管理、存储上下文创建、事件回调与 WebSocket 资源回收。资料来源：[src/core/payments/README.md](src/core/payments/README.md)

CLI 侧通过 `src/utils/cli-auth.ts` 中的 `CLIAuthOptions` 接口将 `--private-key`、`--wallet-address`、`--session-key`、`--view-address` 等多种认证方式统一抽象，并在解析阶段把 `--provider-id` 与已废弃的 `--provider-ids`（逗号分隔）合并到同一个数组，`--data-set-id` 同理。资料来源：[src/utils/cli-auth.ts](src/utils/cli-auth.ts)

```mermaid
flowchart LR
  A[CLI/Action/库调用方] --> B[cli-auth 解析]
  B --> C[initializeSynapse]
  C --> D[Synapse SDK]
  D --> E[Filecoin Onchain Cloud]
  D --> F[Service Providers]
```

## 上传与数据集管理

`core/upload` 模块提供“统一的 CAR 上传接口”，把 CAR 文件推送到 Filecoin，并暴露上传进度、Piece 添加、确认等回调。`src/core/payments/README.md` 描述了它在上传过程中会关联 IPFS CID 与 Filecoin Piece，并返回存储服务提供方的直连下载 URL。资料来源：[src/core/payments/README.md](src/core/payments/README.md)

数据集侧，`src/core/data-set/list-data-sets.ts` 暴露的 `listDataSets(synapse, options?)` 会通过 `synapse.storage.findDataSets({ address })` 拉取当前地址的全部数据集，并通过 `DEFAULT_DATA_SET_METADATA` 标记哪些数据集是由 `filecoin-pin` 创建的。资料来源：[src/core/data-set/list-data-sets.ts](src/core/data-set/list-data-sets.ts)。社区正在讨论的 [feat: add compact summary view to `data-set list` (#578)](https://github.com/filecoin-project/filecoin-pin/issues/578) 与 [feat: add pagination to `piece-status` (#579)](https://github.com/filecoin-project/filecoin-pin/issues/579) 直接影响该 API 的输出形态与性能特征，建议在调用前查阅最新版本。

## 支付与充值

支付模块基于 Filecoin Pay（ERC-20 USDFC）实现两阶段充值：`approve` + `deposit`，并管理服务运营商的额度授权。`src/core/payments/index.ts` 顶部注释明确了核心常量：`DEFAULT_LOCKUP_DAYS`、`MAX_LOCKUP_ALLOWANCE`、`MAX_RATE_ALLOWANCE`、`MIN_FIL_FOR_GAS` 等，并对价格非零做了强校验。资料来源：[src/core/payments/index.ts](src/core/payments/index.ts)

`src/core/payments/funding.ts` 中的 `formatFundingReason()` 把底层 reason code（`none`、`piece-upload`、`runway-insufficient`、`runway-with-piece`、`target-deposit`、`withdrawal-excess`）翻译成人类可读的提示，方便 CLI 输出与库消费者复用。`planFilecoinPayFunding()` 接受外部传入的 `PaymentStatus` 与 `accountSummary`，可在不发起网络请求的情况下计算纯函数形式的资金计划。资料来源：[src/core/payments/funding.ts](src/core/payments/funding.ts)

`src/core/payments/top-up.ts` 则提供 `clampDepositToLimit()` 这类纯函数——当用户指定了 `maxBalance` 上限时，把请求的充值额截断到不会超过上限的值，并返回 `passthrough` / `already-at-limit` / `clamped` 三种 reason。CLI 中的 `--max-balance` 行为直接复用此函数。资料来源：[src/core/payments/top-up.ts](src/core/payments/top-up.ts)

## 通用工具与已知限制

`core/utils/format.ts` 暴露的 `formatFIL()` 会根据数值动态扩展小数位，避免把极小的 tFIL/FIL 余额四舍五入显示成 `0`，并区分主网与测试网的单位（FIL vs tFIL）。资料来源：[src/core/utils/format.ts](src/core/utils/format.ts)。`src/utils/cli-options-metadata.ts` 则把 `--with-piece-metadata`、`--with-dataset-metadata`、ERC-8004 artifact 等元数据相关 CLI 旗标集中注册，库消费者也可以复用同一份 `MetadataOptionConfig`。

社区中值得关注的限制与演进方向：

- **上传前预估成本**：[feat: add `--dry-run` flag to `filecoin-pin add` (#591)](https://github.com/filecoin-project/filecoin-pin/issues/591) 计划在提交前计算 packed size 与预估费用，目前只能通过完整 `add` 流程得知。
- **检索闭环**：[feat: add `filecoin-pin get` retrieval command (#575)](https://github.com/filecoin-project/filecoin-pin/issues/575) 提议补齐“上传—存储—检索”闭环，库 API 也将相应扩展。
- **私钥管理**：[investigate support for 1pass/lastpass/bitwarden secure vaults (#589)](https://github.com/filecoin-project/filecoin-pin/issues/589) 关注在库与 CLI 中接入第三方密钥库。
- **终止语义**：[data-set terminate: confirm skipProvider as the default (#581)](https://github.com/filecoin-project/filecoin-pin/issues/581) 跟踪 `src/data-set/run.ts:314` 的 `skipProvider: true` 行为，使用 `terminateDataSet()` 时需确认默认路径。
- **GitHub Action 独立版本化**：[Extract upload-action into a standalone repository (#527)](https://github.com/filecoin-project/filecoin-pin/issues/527) 一旦完成，Action 标签 `filecoin-project/filecoin-pin/upload-action@…` 将脱离主仓库版本（[#130](https://github.com/filecoin-project/filecoin-pin/issues/130) 已记录过类似混淆）。

## See Also

- [documentation/README.md](documentation/README.md) — 文档总览与各专题入口
- [src/core/payments/README.md](src/core/payments/README.md) — 支付模块的 Synapse SDK 映射说明
- [behind-the-scenes-of-adding-a-file.md](documentation/behind-the-scenes-of-adding-a-file.md) — `add` 命令的端到端执行细节
- [progress-events.md](documentation/progress-events.md) — `onProgress` 事件命名与消费约定
- [events-and-metrics.md](documentation/events-and-metrics.md) — 匿名遥测事件与指标清单

---

<a id='page-4'></a>

## Configuration, Deployment & Operations

### 相关页面

相关主题：[Project Overview & Architecture](#page-1), [CLI Commands Reference](#page-2), [JavaScript Library & Core API](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/README.md)
- [documentation/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/documentation/README.md)
- [package.json](https://github.com/filecoin-project/filecoin-pin/blob/main/package.json)
- [src/utils/cli-auth.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts)
- [src/core/payments/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/README.md)
- [src/core/payments/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/index.ts)
- [src/core/payments/funding.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/funding.ts)
- [src/core/data-set/index.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/index.ts)
- [upload-action/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/README.md)
- [upload-action/examples/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/examples/README.md)
- [upload-action/examples/cli-recipe/README.md](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/examples/cli-recipe/README.md)
- [upload-action/src/types.ts](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/src/types.ts)
</details>

# Configuration, Deployment & Operations

本页汇总 filecoin-pin 的运行配置、部署形态与日常运维要点，涵盖 CLI、GitHub Action、JavaScript 库与 Pinning Server 四种"affordance"（用户接触面）在认证、网络、资金、遥测、安全等方面的共性设置。

## 一、配置体系

### 1.1 认证与网络选项

CLI 与库共享同一组认证入参，集中在 [`src/utils/cli-auth.ts`](https://github.com/filecoin-project/filecoin-pin/blob/main/src/utils/cli-auth.ts) 的 `CLIAuthOptions` 接口中：

| 选项 | 用途 |
|------|------|
| `privateKey` | 标准私钥模式（用于签名与签名交易） |
| `walletAddress` + `sessionKey` | 会话密钥模式（受限于预批准的操作） |
| `viewAddress` | 只读地址（不发起任何链上交易） |
| `network` | `mainnet` 或 `calibration` |
| `rpcUrl` | 自定义 RPC 端点（优先级高于 `network`） |
| `providerIds` | 存储服务商 ID 覆盖（可重复 `--provider-id` 标志） |
| `dataSetIds` | 数据集 ID 覆盖（可重复 `--data-set-id` 标志） |

RPC 端点解析逻辑在 [`src/common/get-rpc-url.ts`](https://github.com/filecoin-project/filecoin-pin/blob/main/src/common/get-rpc-url.ts) 中实现：当指定 `rpcUrl` 时优先使用；否则根据 `NETWORK_CHAINS` 选择主网或校准网的默认端点；针对本地开发场景，函数 `resolveDevnetConfig` 会读取 `LOTUS_RPC_URL`/`LOTUS_WS_URL` 等环境变量来拼接 devnet 配置。

### 1.2 支付相关常量与限制

`src/core/payments/index.ts` 中导出了一组用于支付与资金规划的运行时常量，包括 `DEFAULT_LOCKUP_DAYS`、`MAX_LOCKUP_ALLOWANCE`、`MAX_RATE_ALLOWANCE`、`MIN_FIL_FOR_GAS`、`STORAGE_SCALE_MAX`、`USDFC_DECIMALS` 等。这些常量被 `planFilecoinPayFunding` 用以决定 USDFC 充值上限与锁仓周期。读者在调整运行时参数时应以这些常量为基准，避免绕开内置的安全护栏（资料来源：[src/core/payments/index.ts:1-80]()）。

### 1.3 遥测与版本检查

- **遥测**：`src/read-telemetry-config-from-env.ts` 解析 `FILECOIN_PIN_TELEMETRY_DISABLED`、`DO_NOT_TRACK` 等环境变量，文件 README 强调"遥测默认开启但始终可禁用、且不收集 PII"（资料来源：[README.md:1-200]()）。
- **版本检查**：每次 CLI 启动会查询 npm，命中更新时打印提醒；可通过 `--no-update-check` 关闭（资料来源：[README.md:1-200]()）。

## 二、部署形态

filecoin-pin 仓库同时承载多种交付物，[`package.json`](https://github.com/filecoin-project/filecoin-pin/blob/main/package.json) 中通过 `exports` 字段将以下入口暴露给消费方：

```text
"bin":        { "filecoin-pin": "dist/cli.js" }
"./core/*":   核心模块（payments、upload、synapse、unixfs、utils、data-set）
"./version-check"
"./read-telemetry-config-from-env"
```

下表总结四种主要部署形态及其状态：

| 形态 | 命令/产物 | 状态 | 典型场景 |
|------|----------|------|----------|
| CLI | `npx filecoin-pin add/import/payments/data-set` | 生产就绪 | 手工上传、调试、CI 脚本 |
| GitHub Action | `filecoin-project/filecoin-pin/upload-action@v0.9.1` | 生产就绪 | 自动部署静态站点（参见 `filecoin-pin-website` 工作流） |
| JavaScript 库 | `npm install filecoin-pin` | 生产就绪 | dApp、长期服务、Dealbot 等 |
| Pinning Server | `filecoin-pin server` | Beta，状态在内存 | 兼容 `ipfs pin remote` 等标准 IPFS 工具 |

> 社区反馈（[#130](https://github.com/filecoin-project/filecoin-pin/issues/130)）指出旧文档中 `filecoin-project/filecoin-pin@v1` 标签并不存在；正确引用方式为 `filecoin-project/filecoin-pin/upload-action@<version>`。

### 2.1 GitHub Action 部署模式

[`upload-action/README.md`](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/README.md) 与 [`upload-action/examples/README.md`](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/examples/README.md) 描述了三种工作流模板：

- **双工作流模式**（推荐）：`build.yml` 在不可信上下文中构建产物，`upload-to-filecoin.yml` 在可信上下文中使用 `FILECOIN_WALLET_KEY` 拉取构件并上传。
- **单工作流模式**：构建与上传合并到同一可信工作流，仅适用于受信仓库。
- **CLI 配方**：[`upload-action/examples/cli-recipe/README.md`](https://github.com/filecoin-project/filecoin-pin/blob/main/upload-action/examples/cli-recipe/README.md) 演示在自定义步骤中直接调用 `filecoin-pin add`，以便与第三方打包步骤组合。

不论采用哪种模板，`upload-action/src/types.ts` 中 `PaymentConfig` 的 `minStorageDays` 与 `filecoinPayBalanceLimit`（即运行时的 `--min-runway-days` / `--max-balance`）都必须硬编码在可信工作流中，**禁止**通过 PR 输入注入，以防止恶意 PR 触发超额充值（资料来源：[upload-action/src/types.ts:1-120]()）。

### 2.2 数据集操作入口

[`src/core/data-set/index.ts`](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/data-set/index.ts) 统一导出对数据集的查询与操作函数（`list-data-sets`、`get-data-set-pieces`、`get-detailed-data-set`、`calculate-actual-storage`、`resolve-by-metadata`），CLI 子命令 `data-set list/show/terminate/piece-status` 均构建于其上。社区已通过 [#581](https://github.com/filecoin-project/filecoin-pin/issues/581) 确认 `data-set terminate` 默认采用 `skipProvider: true` 的本地终止路径：两端最终都会触发相同的链上调用，但 filecoin-pin 选择跳过提供商请求路径以加快回收速度。

## 三、运维与排错

### 3.1 资金规划工作流

[`src/core/payments/funding.ts`](https://github.com/filecoin-project/filecoin-pin/blob/main/src/core/payments/funding.ts) 提供 `planFilecoinPayFunding` 与纯计算版 `calculateFilecoinPayFunding`，输出形如：

- `runway-insufficient`：当前 runway 不足，需补足到 `targetRunwayDays`
- `runway-with-piece`：考虑本次上传后的 runway
- `withdrawal-excess`：可提取的余额
- `target-deposit`：达到 `targetDeposit` 的差额

`formatFundingReason` 会把这些原因码转译为中英文友好的提示，方便在 CLI 与 Action 日志中直接呈现。

### 3.2 安全与密钥管理

- **私钥注入**：`PRIVATE_KEY`/`FILECOIN_WALLET_KEY` 通过环境变量传入；强烈建议结合 GitHub Environments + 人工审批门禁（资料来源：[upload-action/README.md:1-200]()）。
- **密钥保管扩展**：社区正在讨论 1Password/LastPass/Bitwarden 等隐私保险库与 OpenWallet 标准的兼容方案（[#589](https://github.com/filecoin-project/filecoin-pin/issues/589)），目前仍需用户手动将密钥注入 secrets。
- **分支保护**：建议在 `main` 分支启用必须由维护者审阅的规则，并配置 `CODEOWNERS` 强制安全团队批准工作流变更（资料来源：[upload-action/README.md:1-200]()）。

### 3.3 常见故障与提示

- **action 版本错误**：参考上文 2.1，使用 `upload-action@v0.9.1`（[#130](https://github.com/filecoin-project/filecoin-pin/issues/130)）。
- **大数据集输出冗长**：`data-set show` 与 `piece-status` 默认无界抓取所有 piece，社区已记录此问题（[#579](https://github.com/filecoin-project/filecoin-pin/issues/579)），可通过分页或过滤缓解。
- **成本预估缺失**：用户希望在上传前看到打包大小与存储成本，社区已提议 `--dry-run` 标志（[#591](https://github.com/filecoin-project/filecoin-pin/issues/591)），目前需手动复核资金计划。
- **回环缺口**：上传完成后无内置检索命令，社区正在设计 `filecoin-pin get`（[#575](https://github.com/filecoin-project/filecoin-pin/issues/575)），当前需使用 Kubo、`curl` 或公共信任网关。
- **CLI 错误矩阵**：CLI 错误码验证仍依赖手工脚本（[#470](https://github.com/filecoin-project/filecoin-pin/issues/470)），开发 PR 涉及 `CliFatal` 行为时请同步更新 smoke test。

## 四、参考阅读

- [Builder Cookbook（官方逐步指南）](https://docs.filecoin.io/builder-cookbook/filecoin-pin)
- [DEVELOPMENT.md（开发与调试）](./DEVELOPMENT.md)
- [Behind the scenes of adding a file（`add` 命令内部流程）](./documentation/behind-the-scenes-of-adding-a-file.md)
- [Retrieving Your Data（检索方式）](./documentation/retrieval.md)
- [Content Routing FAQ（IPNI 与路由）](./documentation/content-routing-faq.md)
- [Filecoin Pin 术语表](./documentation/glossary.md)

## See Also

- [Add a file (CLI)](./add-cli.md) — `filecoin-pin add` 的详细参数与示例
- [Data Set management](./data-set.md) — 数据集生命周期与 piece 查询
- [GitHub Action integration](./upload-action.md) — 双工作流模式与安全最佳实践
- [Payments & Funding](./payments.md) — Filecoin Pay 充值与 runway 管理

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：filecoin-project/filecoin-pin

摘要：发现 28 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：feat: add `filecoin-pin get` retrieval command。

## 1. 安装坑 · 来源证据：feat: add `filecoin-pin get` retrieval command

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: add `filecoin-pin get` retrieval command
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/575 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 运行坑 · 来源证据：feat: add pagination to `piece-status`

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：feat: add pagination to `piece-status`
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/579 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安全/权限坑 · 失败模式：security_permissions: Add CLI error-scenario smoke test matrix for devs

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: Add CLI error-scenario smoke test matrix for devs
- 对用户的影响：Developers may expose sensitive permissions or credentials: Add CLI error-scenario smoke test matrix for devs
- 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/470 | Add CLI error-scenario smoke test matrix for devs

## 4. 安全/权限坑 · 来源证据：Add CLI error-scenario smoke test matrix for devs

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add CLI error-scenario smoke test matrix for devs
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/470 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 5. 安全/权限坑 · 来源证据：Extract upload-action into a standalone repository for independent versioning

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Extract upload-action into a standalone repository for independent versioning
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/527 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 失败模式：installation: Extract upload-action into a standalone repository for independent versioning

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Extract upload-action into a standalone repository for independent versioning
- 对用户的影响：Developers may fail before the first successful local run: Extract upload-action into a standalone repository for independent versioning
- 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/527 | Extract upload-action into a standalone repository for independent versioning

## 7. 安装坑 · 失败模式：installation: feat: add compact summary view to `data-set list`

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: feat: add compact summary view to `data-set list`
- 对用户的影响：Developers may fail before the first successful local run: feat: add compact summary view to `data-set list`
- 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/578 | feat: add compact summary view to `data-set list`

## 8. 安装坑 · 失败模式：installation: v0.22.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.22.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.22.1
- 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.22.1 | v0.22.1

## 9. 安装坑 · 失败模式：installation: v0.23.2

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.23.2
- 对用户的影响：Upgrade or migration may change expected behavior: v0.23.2
- 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.23.2 | v0.23.2

## 10. 安装坑 · 来源证据：feat: add compact summary view to `data-set list`

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: add compact summary view to `data-set list`
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/578 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 11. 配置坑 · 失败模式：configuration: v0.22.3

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.22.3
- 对用户的影响：Upgrade or migration may change expected behavior: v0.22.3
- 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.22.3 | v0.22.3

## 12. 配置坑 · 失败模式：configuration: v0.23.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.23.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.23.0
- 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.23.0 | v0.23.0

## 13. 配置坑 · 失败模式：configuration: v1.0.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.0.1
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.1
- 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v1.0.1 | v1.0.1

## 14. 能力坑 · 来源证据：feat: reorganize `--help` output with command groups and quick-start example

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：feat: reorganize `--help` output with command groups and quick-start example
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/576 | 来源类型 github_issue 暴露的待验证使用条件。

## 15. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/filecoin-project/filecoin-pin | README/documentation is current enough for a first validation pass.

## 16. 运行坑 · 失败模式：runtime: feat: add pagination to `piece-status`

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: feat: add pagination to `piece-status`
- 对用户的影响：Developers may hit a documented source-backed failure mode: feat: add pagination to `piece-status`
- 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/579 | feat: add pagination to `piece-status`

## 17. 维护坑 · 失败模式：migration: v0.21.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v0.21.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.21.0
- 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.21.0 | v0.21.0

## 18. 维护坑 · 失败模式：migration: v0.22.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v0.22.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.22.0
- 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.22.0 | v0.22.0

## 19. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/filecoin-project/filecoin-pin | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/filecoin-project/filecoin-pin | no_demo; severity=medium

## 21. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/filecoin-project/filecoin-pin | no_demo; severity=medium

## 22. 能力坑 · 失败模式：capability: data-set terminate: confirm skipProvider as the default termination path

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: data-set terminate: confirm skipProvider as the default termination path
- 对用户的影响：Developers may hit a documented source-backed failure mode: data-set terminate: confirm skipProvider as the default termination path
- 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/581 | data-set terminate: confirm skipProvider as the default termination path

## 23. 能力坑 · 失败模式：capability: feat: add `--dry-run` flag to `filecoin-pin add` for pre-upload cost estimates

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: feat: add `--dry-run` flag to `filecoin-pin add` for pre-upload cost estimates
- 对用户的影响：Developers may hit a documented source-backed failure mode: feat: add `--dry-run` flag to `filecoin-pin add` for pre-upload cost estimates
- 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/591 | feat: add `--dry-run` flag to `filecoin-pin add` for pre-upload cost estimates

## 24. 能力坑 · 失败模式：capability: feat: reorganize `--help` output with command groups and quick-start example

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: feat: reorganize `--help` output with command groups and quick-start example
- 对用户的影响：Developers may hit a documented source-backed failure mode: feat: reorganize `--help` output with command groups and quick-start example
- 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/576 | feat: reorganize `--help` output with command groups and quick-start example

## 25. 能力坑 · 失败模式：capability: investigate support for 1pass/lastpass/bitwarden secure vaults for private keys

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: investigate support for 1pass/lastpass/bitwarden secure vaults for private keys
- 对用户的影响：Developers may hit a documented source-backed failure mode: investigate support for 1pass/lastpass/bitwarden secure vaults for private keys
- 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/589 | investigate support for 1pass/lastpass/bitwarden secure vaults for private keys

## 26. 能力坑 · 失败模式：conceptual: feat: add `filecoin-pin get` retrieval command

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: feat: add `filecoin-pin get` retrieval command
- 对用户的影响：Developers may hit a documented source-backed failure mode: feat: add `filecoin-pin get` retrieval command
- 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/575 | feat: add `filecoin-pin get` retrieval command

## 27. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/filecoin-project/filecoin-pin | issue_or_pr_quality=unknown

## 28. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/filecoin-project/filecoin-pin | release_recency=unknown

<!-- canonical_name: filecoin-project/filecoin-pin; human_manual_source: deepwiki_human_wiki -->