wehub-resource-sync
398 lines
11 KiB
Markdown
398 lines
11 KiB
Markdown
<!-- 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)
|