glitternetwork--pinme/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

PinMe

一条命令即可创建并部署你的 Web 应用。

PinMe

PinMe 是一款零配置部署 CLI（Command Line Interface，命令行界面），专注于全栈项目的一条命令创建与部署。

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

网站：https://pinme.eth.limo/

PinMe Skill

在 agent 工作流中使用 PinMe 之前，请先安装 PinMe skill：

npx skills add glitternetwork/pinme

目录

• 快速开始
• 面向 AI Agent
• 安装
• PinMe 项目工作流
• 认证与账户命令
• 静态上传与 IPFS 工具
• 命令参考
• 开发与测试
• 限制与运维说明
• 示例
• 支持

快速开始

前置条件

• Node.js >= 16.13.0

创建新的 Worker 项目

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

该工作流将为你提供：

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

仅更新你修改的部分

pinme update-worker
pinme update-db
pinme update-web

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

pinme login
pinme upload dist

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

面向 AI Agent

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

项目模式协议

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

1. 检查 Node.js：

node --version

2. 确保 CLI 可用：

npm install -g pinme

3. 认证：

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. 认证：

pinme login

或用于自动化场景：

pinme set-appkey <AppKey>

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

• dist/
• build/
• out/
• public/

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

4. 上传：

pinme upload <folder>

防护规则

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

安装

从 npm 安装：

npm install -g pinme

验证安装：

pinme --version

PinMe 项目工作流

create 会完成哪些设置

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

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

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

创建项目

pinme login
pinme create my-app

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

部署整个项目

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

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
• 在前端部署后可选绑定域名

仅更新某一层

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

pinme update-worker
pinme update-db
pinme update-web

各命令的预期行为：

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

删除项目

pinme delete
pinme delete my-app
pinme delete my-app --force

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

认证与账户命令

登录与 AppKey

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 与自动化场景的替代认证方式。

域名、钱包与历史记录

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 项目流程时，这些命令很有用。

上传目录或文件

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 模式

上传时绑定

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

bind 需要钱包余额。

导入或导出 CAR 文件

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

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

移除已上传内容

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）。

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。

限制与运维说明

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

示例

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

• example/docs
• example/pinme-blog
• example/supabase

支持

• 网站：https://pinme.eth.limo/
• GitHub：https://github.com/glitternetwork/pinme