<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/glitternetwork/pinme) · [上游 README](https://github.com/glitternetwork/pinme/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<p align="center">
  <a href="https://pinme.eth.limo/">
    <img src="https://2egc5b44.pinit.eth.limo/" height="92" alt="PinMe logo">
    <h3 align="center">PinMe</h3>
  </a>
</p>

<p align="center">
  一条命令即可创建并部署你的 Web 应用。
</p>

# PinMe

[PinMe](https://pinme.eth.limo/) 是一款零配置部署 CLI（Command Line Interface，命令行界面），专注于全栈项目的一条命令创建与部署。

它让你无需繁琐配置，即可快速搭建并启动包含集成前端、Worker 后端和数据库的完整项目。PinMe 旨在大幅简化全栈交付流程，显著提升开发效率。

网站：[https://pinme.eth.limo/](https://pinme.eth.limo/)

> **PinMe Skill**
>
> 在 agent 工作流中使用 PinMe 之前，请先安装 PinMe skill：
>
> ```bash
> npx skills add glitternetwork/pinme
> ```

## 目录

- [快速开始](#quick-start)
- [面向 AI Agent](#for-ai-agents)
- [安装](#installation)
- [PinMe 项目工作流](#pinme-project-workflow)
- [认证与账户命令](#authentication-and-account-commands)
- [静态上传与 IPFS 工具](#static-uploads-and-ipfs-utilities)
- [命令参考](#command-reference)
- [开发与测试](#development-and-testing)
- [限制与运维说明](#limits-and-operational-notes)
- [示例](#examples)
- [支持](#support)

## 快速开始

### 前置条件

- Node.js `>= 16.13.0`

### 创建新的 Worker 项目

```bash
npm install -g pinme
pinme login
pinme create my-app
cd my-app
pinme save
```

该工作流将为你提供：

- 基于官方模板生成的 PinMe 项目
- 平台侧 Worker 与数据库资源开通
- 位于 `pinme.toml` 的本地项目配置
- 通过单一 CLI 完成前端与 Worker 部署

### 仅更新你修改的部分

```bash
pinme update-worker
pinme update-db
pinme update-web
```

### 当你不需要项目工作流时上传静态构建产物

```bash
pinme login
pinme upload dist
```

常见构建目录包括 `dist`、`build`、`out` 和 `public`。

## 面向 AI Agent

当用户需要前端加后端加数据库，或仓库中已包含 `pinme.toml` 时，优先使用 PinMe 项目工作流。

### 项目模式协议

当用户需要 Worker 应用、数据库迁移或持续的项目更新时，使用以下流程。

1. 检查 Node.js：

```bash
node --version
```

2. 确保 CLI 可用：

```bash
npm install -g pinme
```

3. 认证：

```bash
pinme login
```

4. 选择正确的项目命令：

- 创建新项目：`pinme create <name>`
- 从 PinMe 项目根目录部署全部内容：`pinme save`
- 仅更新 Worker：`pinme update-worker`
- 仅更新 SQL 迁移：`pinme update-db`
- 仅更新前端：`pinme update-web`

5. 如果仓库包含 `pinme.toml`，请在该目录下运行项目命令。

6. 对于前端部署，返回 CLI 打印的最终项目 URL。对于仅 Worker 或仅数据库更新，返回相关的成功结果，不要伪造 URL。

### 静态上传回退方案

仅当任务只是“发布已构建的前端”，且不涉及 PinMe 项目工作流时使用。

1. 认证：

```bash
pinme login
```

或用于自动化场景：

```bash
pinme set-appkey <AppKey>
```

2. 按以下顺序查找构建输出目录：

- `dist/`
- `build/`
- `out/`
- `public/`

3. 确认目录存在，且包含 `index.html` 等构建产物。

4. 上传：

```bash
pinme upload <folder>
```

### 防护规则

- 不要上传 `src/` 等源码目录。
- 不要上传 `node_modules`、`.git` 或 `.env`。
- 不要声称在 PinMe 项目模板流程之外支持后端托管。
- 对于项目命令，不要在缺少 `pinme.toml` 的 PinMe 项目根目录之外运行 `update-*` 命令。

## 安装

从 npm 安装：

```bash
npm install -g pinme
```

验证安装：

```bash
pinme --version
```

## PinMe 项目工作流

### `create` 会完成哪些设置

`pinme create <name>` 不仅仅是脚手架文件。该命令会：

- 要求已认证的会话
- 先创建平台侧项目资源
- 下载官方 Worker 项目模板
- 将项目元数据写入 `pinme.toml`
- 写入后端元数据与前端配置文件
- 安装工作区依赖
- 构建 Worker
- 上传 Worker 代码与 SQL 文件
- 构建前端并尝试进行首次前端上传

创建完成后，CLI 会打印项目管理 URL，并建议使用 `pinme save` 进行下一次部署。

### 创建项目

```bash
pinme login
pinme create my-app
```

如果目标目录已存在，CLI 会在覆盖前询问确认，除非使用了 `--force`。

### 部署整个项目

在包含 `pinme.toml` 的项目根目录下运行：

```bash
pinme save
pinme save --domain my-site
pinme save --domain example.com
```

`save` 会执行完整部署路径：

- 安装项目依赖
- 使用 `npm run build:worker` 构建 Worker
- 从 `db/` 上传 Worker 代码与 SQL 文件
- 使用 `npm run build:frontend` 构建前端
- 上传 `frontend/dist`
- 在前端部署后可选绑定域名

### 仅更新某一层

当只有某一部分发生变更时，使用针对性命令：

```bash
pinme update-worker
pinme update-db
pinme update-web
```

各命令的预期行为：

- `update-worker`：从当前 PinMe 项目构建并上传 Worker 代码
- `update-db`：仅从 `db/` 上传 `.sql` 文件
- `update-web`：构建并上传 `frontend/dist`

### 删除项目

```bash
pinme delete
pinme delete my-app
pinme delete my-app --force
```

这会删除平台侧的 Worker、域名绑定和 D1 数据库。本地文件保持不变。

## 认证与账户命令

### 登录与 AppKey

```bash
pinme login
pinme login --env test

pinme set-appkey
pinme set-appkey <AppKey>

pinme show-appkey
pinme appkey

pinme logout
```

说明：

- `pinme login` 是项目命令的推荐方式。
- `set-appkey` 是 CLI 与自动化场景的替代认证方式。

### 域名、钱包与历史记录

```bash
pinme my-domains
pinme domain

pinme wallet
pinme wallet-balance
pinme balance

pinme list
pinme ls
pinme list -l 5
pinme list -c
```

## 静态上传与 IPFS 工具

当你已有构建产物且不需要完整 Worker 项目流程时，这些命令很有用。

### 上传目录或文件

```bash
pinme upload
pinme upload ./dist
pinme upload ./dist --domain my-site
pinme upload ./dist --domain example.com
pinme upload ./dist --domain my-site --dns
```

域名处理：

- 包含点号的域名被视为 DNS 域名
- 不包含点号的域名被视为 PinMe 子域名
- `--dns` 强制使用 DNS 模式

### 上传时绑定

```bash
pinme bind ./dist --domain my-site
pinme bind ./dist --domain example.com
```

`bind` 需要钱包余额。

### 导入或导出 CAR 文件

```bash
pinme import
pinme import ./site.car
pinme import ./site.car --domain my-site

pinme export <cid>
pinme export <cid> --output ./exports
```

### 移除已上传内容

```bash
pinme rm
pinme rm <value>
```

## 命令参考

| Command                                                   | What it does                                                 |
| --------------------------------------------------------- | ------------------------------------------------------------ |
| `pinme create [name]`                                     | 基于官方模板创建新的 PinMe Worker 项目 |
| `pinme save [--domain <name>]`                            | 部署当前 PinMe 项目：Worker、SQL 与前端  |
| `pinme update-worker`                                     | 仅构建并上传 Worker 代码                            |
| `pinme update-db`                                         | 仅从 `db/` 上传 SQL 迁移                        |
| `pinme update-web`                                        | 仅构建并上传前端                           |
| `pinme delete [name] [--force]`                           | 删除平台项目                                    |
| `pinme upload [path]`                                     | 将文件或目录上传到 IPFS                           |
| `pinme bind [path] --domain <name>`                       | 上传并绑定域名                                     |
| `pinme import [path]`                                     | 导入 CAR 文件                                            |
| `pinme export <cid> [--output <dir>]`                     | 将 IPFS 内容导出为 CAR 文件                            |
| `pinme rm [value]`                                        | 移除已上传内容                                      |
| `pinme login [--env test\|prod]`                          | 通过浏览器登录                                            |
| `pinme set-appkey [AppKey]`                               | 使用 AppKey 设置认证                            |
| `pinme show-appkey` / `pinme appkey`                      | 显示脱敏后的 AppKey 信息                                      |
| `pinme my-domains` / `pinme domain`                       | 列出当前账户拥有的域名                    |
| `pinme wallet` / `pinme wallet-balance` / `pinme balance` | 显示当前钱包余额                                  |
| `pinme list` / `pinme ls`                                 | 显示上传历史                                          |
| `pinme help`                                              | 显示 CLI 帮助                                                |

## 开发与测试

PinMe 使用 Vitest 进行单元/集成测试，使用真实的 `dist/index.js` CLI 冒烟测试、npm 包检查，以及 Stryker 进行较慢的变异测试（mutation testing）。

```bash
npm run test           # Unit and integration tests
npm run test:coverage  # Coverage gate for core modules
npm run test:cli       # Real CLI black-box tests
npm run test:pack      # npm pack/package-shape checks
npm run verify         # Full pull-request gate
npm run test:mutation  # Slow mutation tests for manual/nightly runs
```

测试不得调用实时的 PinMe/IPFS/CAR 服务。API 与 CLI 场景请使用 `nock`、本地回环（loopback）服务器、fixtures 以及临时 HOME 目录。

完整的测试策略、目录布局与变异测试指南，请参阅
[TESTING.md](TESTING.md)。

## 限制与运维说明

- 默认单文件上传限制：`100MB`
- 默认目录上传限制：`500MB`
- 这些上传默认值来自 CLI，可通过环境变量覆盖
- `update-db` 对每次运行强制执行 `10MB` 的 SQL 载荷总大小限制
- `upload`、`import` 及项目命令需要身份验证
- 域名绑定（domain binding）需要钱包余额
- `save`、`update-worker`、`update-db` 与 `update-web` 预期从 PinMe 项目根目录运行，并配合 `pinme.toml`

## 示例

本仓库包含示例项目与文档：

- [example/docs](./example/docs)
- [example/pinme-blog](./example/pinme-blog)
- [example/supabase](./example/supabase)

## 支持

- 网站：[https://pinme.eth.limo/](https://pinme.eth.limo/)
- GitHub：[https://github.com/glitternetwork/pinme](https://github.com/glitternetwork/pinme)