diff --git a/README.md b/README.md index f9384e3..7d23c78 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/glitternetwork/pinme) · [上游 README](https://github.com/glitternetwork/pinme/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 +

PinMe logo @@ -6,46 +12,46 @@

- Create and deploy your web in one command. + 一条命令即可创建并部署你的 Web 应用。

# 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 ` -- 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 ` +- 从 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 ``` -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 ``` -### 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 ` does more than scaffold files. The command: +`pinme create ` 不仅仅是脚手架文件。该命令会： -- 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 pinme export --output ./exports ``` -### Remove uploaded content +### 移除已上传内容 ```bash pinme rm pinme rm ``` -## Command Reference +## 命令参考 | Command | What it does | | --------------------------------------------------------- | ------------------------------------------------------------ | -| `pinme create [name]` | Create a new PinMe Worker project from the official template | -| `pinme save [--domain ]` | 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 ` | Upload and bind a domain | -| `pinme import [path]` | Import a CAR file | -| `pinme export [--output ]` | 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 ]` | 部署当前 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 ` | 上传并绑定域名 | +| `pinme import [path]` | 导入 CAR 文件 | +| `pinme export [--output ]` | 将 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)