wehub/glitternetwork--pinme
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: make Chinese README the default
CI / Verify on Node 16.13.0 (push) Has been cancelled
Details
CI / Verify on Node 18.x (push) Has been cancelled
Details
CI / Verify on Node 20.x (push) Has been cancelled
Details
CI / Mutation tests (push) Has been cancelled
Details
CI / Dependency audit (push) Has been cancelled
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 10:58:49 +00:00
parent 37f0831fdb
commit 5c09a12879
1 changed files with 150 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+150 -144
View File
@@ -1,3 +1,9 @@
<!-- 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">
@@ -6,46 +12,46 @@
</p>
<p align="center">
Create and deploy your web in one command.
一条命令即可创建并部署你的 Web 应用。
</p>
# PinMe
[PinMe](https://pinme.eth.limo/) is a zero-config deployment CLI focused on one-command creation and deployment for full-stack projects.
[PinMe](https://pinme.eth.limo/) 是一款零配置部署 CLI（Command Line Interface，命令行界面），专注于全栈项目的一条命令创建与部署。
It lets you quickly set up and launch a complete project with an integrated frontend, Worker backend, and database, without tedious configuration. PinMe is built to make full-stack delivery much simpler and significantly improve development efficiency.
它让你无需繁琐配置，即可快速搭建并启动包含集成前端、Worker 后端和数据库的完整项目。PinMe 旨在大幅简化全栈交付流程，显著提升开发效率。
Website: [https://pinme.eth.limo/](https://pinme.eth.limo/)
网站：[https://pinme.eth.limo/](https://pinme.eth.limo/)
> **PinMe Skill**
>
> Install the PinMe skill before using PinMe in agent workflows:
> 在 agent 工作流中使用 PinMe 之前，请先安装 PinMe skill：
>
> ```bash
> npx skills add glitternetwork/pinme
> ```
## Table of Contents
## 目录
- [Quick Start](#quick-start)
- [For AI Agents](#for-ai-agents)
- [Installation](#installation)
- [PinMe Project Workflow](#pinme-project-workflow)
- [Authentication and Account Commands](#authentication-and-account-commands)
- [Static Uploads and IPFS Utilities](#static-uploads-and-ipfs-utilities)
- [Command Reference](#command-reference)
- [Development and Testing](#development-and-testing)
- [Limits and Operational Notes](#limits-and-operational-notes)
- [Examples](#examples)
- [Support](#support)
- [快速开始](#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)
## Quick Start
## 快速开始
### Prerequisites
### 前置条件
- Node.js `>= 16.13.0`
### Create a new Worker project
### 创建新的 Worker 项目
```bash
npm install -g pinme
@@ -55,14 +61,14 @@ cd my-app
pinme save
```
What this workflow gives you:
该工作流将为你提供：
- a generated PinMe project from the official template
- platform-side Worker and database provisioning
- local project config in `pinme.toml`
- frontend and Worker deployment from one CLI
- 基于官方模板生成的 PinMe 项目
- 平台侧 Worker 与数据库资源开通
- 位于 `pinme.toml` 的本地项目配置
- 通过单一 CLI 完成前端与 Worker 部署
### Update only the part you changed
### 仅更新你修改的部分
```bash
pinme update-worker
@@ -70,135 +76,135 @@ pinme update-db
pinme update-web
```
### Upload a static build when you do not need the project workflow
### 当你不需要项目工作流时上传静态构建产物
```bash
pinme login
pinme upload dist
```
Common build directories are `dist`, `build`, `out`, and `public`.
常见构建目录包括 `dist`、`build`、`out` 和 `public`。
## For AI Agents
## 面向 AI Agent
Prefer the PinMe project workflow when the user wants a frontend plus backend plus database, or when the repo already contains `pinme.toml`.
当用户需要前端加后端加数据库，或仓库中已包含 `pinme.toml` 时，优先使用 PinMe 项目工作流。
### Project-mode protocol
### 项目模式协议
Use this flow when the user wants a Worker app, database migrations, or ongoing project updates.
当用户需要 Worker 应用、数据库迁移或持续的项目更新时，使用以下流程。
1. Check Node.js:
1. 检查 Node.js：
```bash
node --version
```
2. Ensure the CLI is available:
2. 确保 CLI 可用：
```bash
npm install -g pinme
```
3. Authenticate:
3. 认证：
```bash
pinme login
```
4. Choose the right project command:
4. 选择正确的项目命令：
- create a new project: `pinme create <name>`
- deploy everything from a PinMe project root: `pinme save`
- update Worker only: `pinme update-worker`
- update SQL migrations only: `pinme update-db`
- update frontend only: `pinme update-web`
- 创建新项目：`pinme create <name>`
- 从 PinMe 项目根目录部署全部内容：`pinme save`
- 仅更新 Worker：`pinme update-worker`
- 仅更新 SQL 迁移：`pinme update-db`
- 仅更新前端：`pinme update-web`
5. If the repo contains `pinme.toml`, run project commands from that directory.
5. 如果仓库包含 `pinme.toml`，请在该目录下运行项目命令。
6. Return the final project URL printed by the CLI for frontend deploys. For Worker-only or DB-only updates, return the relevant success result instead of fabricating a URL.
6. 对于前端部署，返回 CLI 打印的最终项目 URL。对于仅 Worker 或仅数据库更新，返回相关的成功结果，不要伪造 URL。
### Static-upload fallback
### 静态上传回退方案
Use this only when the task is just "publish the built frontend" and there is no PinMe project workflow involved.
仅当任务只是“发布已构建的前端”，且不涉及 PinMe 项目工作流时使用。
1. Authenticate:
1. 认证：
```bash
pinme login
```
Or for automation:
或用于自动化场景：
```bash
pinme set-appkey <AppKey>
```
2. Find the built output directory in this order:
2. 按以下顺序查找构建输出目录：
- `dist/`
- `build/`
- `out/`
- `public/`
3. Verify the directory exists and contains built assets such as `index.html`.
3. 确认目录存在，且包含 `index.html` 等构建产物。
4. Upload it:
4. 上传：
```bash
pinme upload <folder>
```
### Guardrails
### 防护规则
- Do not upload source folders such as `src/`.
- Do not upload `node_modules`, `.git`, or `.env`.
- Do not claim unsupported backend hosting outside the PinMe project template flow.
- For project commands, do not run `update-*` commands outside a PinMe project root with `pinme.toml`.
- 不要上传 `src/` 等源码目录。
- 不要上传 `node_modules`、`.git` 或 `.env`。
- 不要声称在 PinMe 项目模板流程之外支持后端托管。
- 对于项目命令，不要在缺少 `pinme.toml` 的 PinMe 项目根目录之外运行 `update-*` 命令。
## Installation
## 安装
Install from npm:
从 npm 安装：
```bash
npm install -g pinme
```
Verify installation:
验证安装：
```bash
pinme --version
```
## PinMe Project Workflow
## PinMe 项目工作流
### What `create` sets up
### `create` 会完成哪些设置
`pinme create <name>` does more than scaffold files. The command:
`pinme create <name>` 不仅仅是脚手架文件。该命令会：
- requires an authenticated session
- creates the platform project resources first
- downloads the official Worker project template
- writes project metadata into `pinme.toml`
- writes backend metadata and frontend config files
- installs workspace dependencies
- builds the Worker
- uploads Worker code and SQL files
- builds the frontend and attempts an initial frontend upload
- 要求已认证的会话
- 先创建平台侧项目资源
- 下载官方 Worker 项目模板
- 将项目元数据写入 `pinme.toml`
- 写入后端元数据与前端配置文件
- 安装工作区依赖
- 构建 Worker
- 上传 Worker 代码与 SQL 文件
- 构建前端并尝试进行首次前端上传
After creation, the CLI prints the project management URL and suggests `pinme save` for the next deploy.
创建完成后，CLI 会打印项目管理 URL，并建议使用 `pinme save` 进行下一次部署。
### Create a project
### 创建项目
```bash
pinme login
pinme create my-app
```
If the target directory already exists, the CLI asks before overwriting it unless `--force` is used.
如果目标目录已存在，CLI 会在覆盖前询问确认，除非使用了 `--force`。
### Deploy the whole project
### 部署整个项目
Run this from the project root that contains `pinme.toml`:
在包含 `pinme.toml` 的项目根目录下运行：
```bash
pinme save
@@ -206,18 +212,18 @@ pinme save --domain my-site
pinme save --domain example.com
```
`save` performs the full deploy path:
`save` 会执行完整部署路径：
- installs project dependencies
- builds the Worker with `npm run build:worker`
- uploads Worker code and SQL files from `db/`
- builds the frontend with `npm run build:frontend`
- uploads `frontend/dist`
- optionally binds a domain after the frontend deploy
- 安装项目依赖
- 使用 `npm run build:worker` 构建 Worker
- 从 `db/` 上传 Worker 代码与 SQL 文件
- 使用 `npm run build:frontend` 构建前端
- 上传 `frontend/dist`
- 在前端部署后可选绑定域名
### Update only one layer
### 仅更新某一层
Use targeted commands when only one part changed:
当只有某一部分发生变更时，使用针对性命令：
```bash
pinme update-worker
@@ -225,13 +231,13 @@ pinme update-db
pinme update-web
```
What each command expects:
各命令的预期行为：
- `update-worker`: builds and uploads Worker code from the current PinMe project
- `update-db`: uploads `.sql` files from `db/`
- `update-web`: builds and uploads `frontend/dist`
- `update-worker`：从当前 PinMe 项目构建并上传 Worker 代码
- `update-db`：仅从 `db/` 上传 `.sql` 文件
- `update-web`：构建并上传 `frontend/dist`
### Delete a project
### 删除项目
```bash
pinme delete
@@ -239,11 +245,11 @@ pinme delete my-app
pinme delete my-app --force
```
This deletes the platform-side Worker, domain binding, and D1 database. Local files remain unchanged.
这会删除平台侧的 Worker、域名绑定和 D1 数据库。本地文件保持不变。
## Authentication and Account Commands
## 认证与账户命令
### Login and AppKey
### 登录与 AppKey
```bash
pinme login
@@ -258,12 +264,12 @@ pinme appkey
pinme logout
```
Notes:
说明：
- `pinme login` is the recommended path for project commands.
- `set-appkey` is the alternative authentication method for CLI and automation usage.
- `pinme login` 是项目命令的推荐方式。
- `set-appkey` 是 CLI 与自动化场景的替代认证方式。
### Domains, wallet, and history
### 域名、钱包与历史记录
```bash
pinme my-domains
@@ -279,11 +285,11 @@ pinme list -l 5
pinme list -c
```
## Static Uploads and IPFS Utilities
## 静态上传与 IPFS 工具
These commands are useful when you already have artifacts and do not need the full Worker project flow.
当你已有构建产物且不需要完整 Worker 项目流程时，这些命令很有用。
### Upload a directory or file
### 上传目录或文件
```bash
pinme upload
@@ -293,22 +299,22 @@ pinme upload ./dist --domain example.com
pinme upload ./dist --domain my-site --dns
```
Domain handling:
域名处理：
- domains containing a dot are treated as DNS domains
- domains without a dot are treated as PinMe subdomains
- `--dns` forces DNS mode
- 包含点号的域名被视为 DNS 域名
- 不包含点号的域名被视为 PinMe 子域名
- `--dns` 强制使用 DNS 模式
### Bind while uploading
### 上传时绑定
```bash
pinme bind ./dist --domain my-site
pinme bind ./dist --domain example.com
```
`bind` requires wallet balance.
`bind` 需要钱包余额。
### Import or export CAR files
### 导入或导出 CAR 文件
```bash
pinme import
@@ -319,39 +325,39 @@ pinme export <cid>
pinme export <cid> --output ./exports
```
### Remove uploaded content
### 移除已上传内容
```bash
pinme rm
pinme rm <value>
```
## Command Reference
## 命令参考
| Command | What it does |
| --------------------------------------------------------- | ------------------------------------------------------------ |
| `pinme create [name]` | Create a new PinMe Worker project from the official template |
| `pinme save [--domain <name>]` | Deploy the current PinMe project: Worker, SQL, and frontend |
| `pinme update-worker` | Build and upload Worker code only |
| `pinme update-db` | Upload SQL migrations from `db/` only |
| `pinme update-web` | Build and upload the frontend only |
| `pinme delete [name] [--force]` | Delete a platform project |
| `pinme upload [path]` | Upload a file or directory to IPFS |
| `pinme bind [path] --domain <name>` | Upload and bind a domain |
| `pinme import [path]` | Import a CAR file |
| `pinme export <cid> [--output <dir>]` | Export IPFS content as a CAR file |
| `pinme rm [value]` | Remove uploaded content |
| `pinme login [--env test\|prod]` | Login via browser |
| `pinme set-appkey [AppKey]` | Set authentication with an AppKey |
| `pinme show-appkey` / `pinme appkey` | Show masked AppKey info |
| `pinme my-domains` / `pinme domain` | List domains owned by the current account |
| `pinme wallet` / `pinme wallet-balance` / `pinme balance` | Show current wallet balance |
| `pinme list` / `pinme ls` | Show upload history |
| `pinme help` | Show CLI help |
| `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 帮助 |
## Development and Testing
## 开发与测试
PinMe uses Vitest for unit/integration tests, real `dist/index.js` CLI smoke tests, npm package checks, and Stryker for slower mutation testing.
PinMe 使用 Vitest 进行单元/集成测试，使用真实的 `dist/index.js` CLI 冒烟测试、npm 包检查，以及 Stryker 进行较慢的变异测试（mutation testing）。
```bash
npm run test # Unit and integration tests
@@ -362,30 +368,30 @@ npm run verify # Full pull-request gate
npm run test:mutation # Slow mutation tests for manual/nightly runs
```
Tests must not call live PinMe/IPFS/CAR services. Use `nock`, local loopback servers, fixtures, and temporary HOME directories for API and CLI scenarios.
测试不得调用实时的 PinMe/IPFS/CAR 服务。API 与 CLI 场景请使用 `nock`、本地回环（loopback）服务器、fixtures 以及临时 HOME 目录。
For the full testing policy, layout, and mutation-testing guidance, see
[TESTING.md](TESTING.md).
完整的测试策略、目录布局与变异测试指南，请参阅
[TESTING.md](TESTING.md)。
## Limits and Operational Notes
## 限制与运维说明
- Default single-file upload limit: `100MB`
- Default directory upload limit: `500MB`
- These upload defaults come from the CLI and can be overridden with environment variables
- `update-db` enforces a total SQL payload limit of `10MB` per run
- `upload`, `import`, and project commands require authentication
- domain binding requires wallet balance
- `save`, `update-worker`, `update-db`, and `update-web` expect to run from a PinMe project root with `pinme.toml`
- 默认单文件上传限制：`100MB`
- 默认目录上传限制：`500MB`
- 这些上传默认值来自 CLI，可通过环境变量覆盖
- `update-db` 对每次运行强制执行 `10MB` 的 SQL 载荷总大小限制
- `upload`、`import` 及项目命令需要身份验证
- 域名绑定（domain binding）需要钱包余额
- `save`、`update-worker`、`update-db` 与 `update-web` 预期从 PinMe 项目根目录运行，并配合 `pinme.toml`
## Examples
## 示例
This repo includes example projects and docs:
本仓库包含示例项目与文档：
- [example/docs](./example/docs)
- [example/pinme-blog](./example/pinme-blog)
- [example/supabase](./example/supabase)
## Support
## 支持
- Website: [https://pinme.eth.limo/](https://pinme.eth.limo/)
- GitHub: [https://github.com/glitternetwork/pinme](https://github.com/glitternetwork/pinme)
- 网站：[https://pinme.eth.limo/](https://pinme.eth.limo/)
- GitHub：[https://github.com/glitternetwork/pinme](https://github.com/glitternetwork/pinme)