这是本节的多页打印视图。 .

概念

理解 Piglet Run 的核心概念、架构设计与设计理念。

1: 概述
2: 架构概述
3: 存储
4: 快照
5: 克隆
6: 监控
7: 安全

概念文档帮助你理解 Piglet Run 背后的原理和架构。

你将学到

Piglet Run 的底层工作原理
设计哲学和架构
快照、克隆、存储等关键概念

主题

主题	描述
概述	什么是 Piglet Run，为什么使用它
架构	系统架构和组件
存储	JuiceFS 和共享存储
快照	时光机器和 PITR
克隆	Copy-on-Write 数据库克隆
监控	可观测性技术栈
安全	访问控制和加密

1 - 概述

什么是 Piglet Run？

Piglet Run（小猪运行时）是 Pigsty 的轻量运行时环境，专为 AI Web Coding 打造的云端编码沙箱。它将 PostgreSQL 数据库、JuiceFS 分布式存储、VS Code、JupyterLab 等工具整合为一体。

为什么选择 Piglet Run？

在 AI 辅助开发的时代，开发者需要：

即用型开发环境，开箱即用
强大的数据库，所有扩展都可用
安全的实验环境，轻松回滚
无缝协作，人与 AI Agent 协同工作

Piglet Run 将这一切整合在一个软件包中。

核心特性

特性	说明
🤖 AI 编码	预装 Claude Code、OpenCode、VS Code、Jupyter
🐘 数据全能	PostgreSQL 18 + 400+ 扩展
💾 共享存储	JuiceFS 将工作目录存入数据库
⏱️ 时光机器	数据库 PITR + 文件系统快照
🔀 瞬间克隆	Copy-on-Write 零拷贝克隆
🌐 一键上线	内置 Nginx，自动 SSL
📊 全栈监控	VictoriaMetrics + Grafana
🇨🇳 国内畅通	全球 CDN + 国内镜像

适用人群

独立开发者：需要强大开发环境
开发团队：需要共享开发基础设施
AI 开发者：使用 Claude Code 等工具
数据科学家：使用 PostgreSQL 和 Jupyter
学习者：探索 PostgreSQL 和 Web 开发

工作原理

┌─────────────────────────────────────────────────────────────┐
│                      Piglet Run                             │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐       │
│  │ VS Code │  │ Jupyter │  │ Claude  │  │  Nginx  │       │
│  │ Server  │  │   Lab   │  │  Code   │  │ Proxy   │       │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘       │
│       │            │            │            │             │
│       └────────────┴────────────┴────────────┘             │
│                         │                                   │
│  ┌──────────────────────┴──────────────────────┐           │
│  │              JuiceFS (共享存储)              │           │
│  └──────────────────────┬──────────────────────┘           │
│                         │                                   │
│  ┌──────────────────────┴──────────────────────┐           │
│  │         PostgreSQL 18 + 400+ 扩展           │           │
│  └─────────────────────────────────────────────┘           │
│                                                             │
│  ┌─────────────────────────────────────────────┐           │
│  │      VictoriaMetrics + Grafana (监控)       │           │
│  └─────────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────────┘

下一步

安装 Piglet Run 开始使用
了解架构
探索存储系统

2 - 架构概述

Piglet 里有什么，怎么组织

Piglet 是什么

Piglet 是专为 AI 辅助编程设计的 Agentic Postgres 运行时。

它不只是一个数据库，而是一个完整的云端开发环境：从一台 0.64 元的裸 VM，到完整的生产级网站，开箱即用。

产品本质

Piglet 是一个"缝合怪"——它集成了：

能力	对标产品	Piglet 提供
数据库即服务	Neon, Supabase	PostgreSQL + PITR 时间旅行
云端 IDE	GitHub Codespaces	VS Code Server + Jupyter
AI 编程	Cursor, Windsurf	Claude Code 原生支持
应用托管	Vercel, Railway	Nginx + Node.js + Python
监控可观测	Datadog	Grafana + VictoriaMetrics

核心价值：由生产级方案（Pigsty）改造成的个人级方案——降维打击。

核心组件

┌─────────────────────────────────────────────────────────────────┐
│                         Piglet Runtime                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐        │
│   │ VS Code │   │ Jupyter │   │ Claude  │   │  Your   │        │
│   │ Server  │   │   Lab   │   │  Code   │   │  App    │        │
│   └────┬────┘   └────┬────┘   └────┬────┘   └────┬────┘        │
│        │             │             │             │              │
│        └─────────────┴─────────────┴─────────────┘              │
│                          │                                      │
│                    ┌─────┴─────┐                                │
│                    │   Nginx   │  反向代理 + SSL                │
│                    └─────┬─────┘                                │
│                          │                                      │
├──────────────────────────┼──────────────────────────────────────┤
│                          │                                      │
│   ┌──────────────────────┴──────────────────────┐               │
│   │              PostgreSQL 17                   │               │
│   │         生产级数据库 + PITR 时间旅行          │               │
│   └──────────────────────┬──────────────────────┘               │
│                          │                                      │
│   ┌──────────────────────┴──────────────────────┐               │
│   │               JuiceFS (PITRFS)               │               │
│   │        文件系统也能时间旅行的秘密武器          │               │
│   └─────────────────────────────────────────────┘               │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐          │
│   │  Grafana    │   │ Victoria    │   │   Loki      │          │
│   │  监控面板    │   │  Metrics    │   │   日志      │          │
│   └─────────────┘   └─────────────┘   └─────────────┘          │
└─────────────────────────────────────────────────────────────────┘

组件清单

组件	角色	访问方式
Nginx	反向代理，SSL 终止，静态文件托管	:80, :443
VS Code Server	网页版 IDE，支持远程 SSH	/code
JupyterLab	数据科学笔记本	/jupyter
PostgreSQL 17	主数据库，带 340+ 扩展	:5432
JuiceFS	分布式文件系统（PITRFS）	~/data
VictoriaMetrics	时序指标存储	:8428
Grafana	监控仪表盘	/grafana
Loki	日志聚合	-

Agentic 设计

Piglet 的核心设计理念是 Human-Agent Parity（人机对等）：

人看到的 = Agent 看到的，同一套工具、同一个视角。

人机分工

角色	职责
你（人类）	提出需求、派活、验收
Agent（AI）	利用环境里的工具实现需求

Agent 可能比很多用户更懂环境里有什么能用，但最终还是人类说了算。

用户画像

用户类型	他们想要什么	Agent 扮演的角色
DBA/专家	利用 Agent 自动化专业任务	执行助手
普通开发者	快速上线 Web 应用	懂行的队友
小白	只说"我要一个 XX"	全能代理

Claude.md

Piglet 提供 CLAUDE.md 文件，告诉 AI Agent 环境里有什么、能做什么：

可用的数据库和连接方式
可用的命令行工具
文件系统结构
部署和发布方式

存储架构

Piglet 的杀手锏是 PITRFS——文件系统也能像数据库一样任意时间点回滚。

┌─────────────────────────────────────┐
│          你的代码和数据              │
│         ~/data/workspace            │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│            JuiceFS                  │
│     POSIX 兼容 + 时间旅行能力        │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│          PostgreSQL                 │
│     元数据 + 数据块 + WAL 归档       │
└─────────────────────────────────────┘
               │
               ▼
        任意时间点恢复 (PITR)

这意味着：

数据库可以回滚：标准 PostgreSQL PITR
文件系统也可以回滚：基于 JuiceFS + PostgreSQL 的 PITRFS
搞砸了也不怕：误删代码？回到 10 分钟前。Agent 把数据库搞崩了？一条命令恢复。

网络架构

所有服务通过 Nginx 统一暴露，支持 HTTPS：

Internet
    │
    ▼
┌─────────────────────────────────────┐
│  Nginx (:80, :443)                  │
│  - SSL 终止                          │
│  - 反向代理                          │
│  - 静态文件托管                       │
└────┬────────┬────────┬────────┬─────┘
     │        │        │        │
     ▼        ▼        ▼        ▼
  /code   /jupyter  /grafana   /*
 VS Code  Jupyter   Grafana   你的应用

与 Pigsty 的关系

维度	Pigsty	Piglet
定位	企业级 PostgreSQL 发行版	个人级 Agentic 运行时
目标用户	DBA、运维、企业	个人开发者、AI 编程者
规模	多节点集群	单节点
复杂度	功能完整、配置丰富	开箱即用、极简配置
调性	专业、严谨、可靠	方便、灵活、好玩

Piglet 是 Pigsty 的精简版，继承了生产级的可靠性，但去掉了企业级的复杂性。

下一步

快速开始 - 10 分钟上手
PITRFS 原理 - 理解时间旅行
Agentic 设计 - 深入人机协作

3 - 存储

JuiceFS 共享存储

Piglet Run 使用 JuiceFS 提供基于 PostgreSQL 的分布式文件系统。

为什么选择 JuiceFS？

POSIX 兼容：像普通文件系统一样工作
数据库后端：数据存储在 PostgreSQL
快照支持：时间点恢复
多用户：跨会话共享工作空间

工作原理

┌────────────────────────────────────────────┐
│              应用层                         │
│   (VS Code, Jupyter, Claude Code 等)       │
└──────────────────┬─────────────────────────┘
                   │ POSIX API
                   ▼
┌────────────────────────────────────────────┐
│               JuiceFS FUSE                 │
│         (用户空间文件系统)                  │
└──────────────────┬─────────────────────────┘
                   │
        ┌──────────┴──────────┐
        │                     │
        ▼                     ▼
┌───────────────┐    ┌───────────────┐
│    元数据     │    │   数据块      │
│  (PostgreSQL) │    │  (PostgreSQL) │
└───────────────┘    └───────────────┘

特性

特性	描述
透明	像本地文件系统一样使用
持久	数据存储在数据库中
并发	多用户/Agent 同时访问
快照	时间点恢复

下一步

了解快照
理解克隆

4 - 快照

时光机器

Piglet Run 为数据库和文件系统都提供时间点恢复功能。

数据库 PITR

PostgreSQL 内置的 PITR（时间点恢复）允许您将数据库恢复到任意时间点。由 pgBackRest 管理。

# 显示备份信息
pig pb info

# 列出所有备份
pig pb ls

# 创建全量备份
pig pb backup full

# 恢复到最新备份
pig pb restore

# 恢复到指定时间
pig pb restore -t "2025-01-29 10:00:00"

文件系统快照

JuiceFS 快照保存工作区状态：

# 创建快照（使用 juicefs CLI）
juicefs snapshot create /jfs/data snapshot-before-experiment

# 列出快照
juicefs snapshot list /jfs/data

# 从快照恢复
juicefs snapshot restore /jfs/data snapshot-before-experiment

使用场景

场景	解决方案
AI 写坏代码	恢复文件系统快照
数据库迁移失败	使用 `pig pb restore -t <time>`
实验失败	回滚整个环境
需要干净状态	恢复到基线快照

备份管理

# 查看备份状态
pig pb info

# 查看备份日志
pig pb log tail

# 创建增量备份
pig pb backup incr

# 创建差异备份
pig pb backup diff

下一步

了解克隆
查看恢复任务
查看备份任务

5 - 克隆

瞬间克隆

Piglet Run 支持 Copy-on-Write（写时复制）克隆，实现快速数据库分支。

工作原理

Copy-on-Write 意味着：

克隆时零拷贝
只有修改的块才消耗存储
TB 级数据库毫秒级克隆

原始数据库
┌─────────────────────┐
│ Block A │ Block B │ Block C │
└────┬────┴────┬────┴────┬────┘
     │         │         │
     ▼         ▼         ▼
┌────────────────────────────┐
│        共享存储             │
└────────────────────────────┘
     ▲         ▲         ▲
     │         │         │
┌────┴────┬────┴────┬────┴────┐
│ Block A │ Block B │ Block C │ (共享)
│         │ Block B'│         │ (克隆中修改)
└─────────┴─────────┴─────────┘
克隆数据库

使用场景

场景	优势
开发	克隆生产环境用于测试
AI 实验	每个实验一个分支
功能分支	每个分支一个数据库
培训	每个学员一份副本

数据库克隆

使用 PostgreSQL 工具：

# 从模板创建数据库
pig pg psql -c "CREATE DATABASE dev TEMPLATE prod"

# 或使用 pg_dump/pg_restore 跨服务器克隆
pg_dump -Fc prod > prod.dump
pg_restore -d dev prod.dump

使用 pgBackRest 克隆

# 恢复到新集群作为克隆
pig pb restore --target-pgdata=/data/pg-clone

# 或恢复到特定时间点
pig pb restore -t "2025-01-29 10:00:00" --target-pgdata=/data/pg-clone

使用 JuiceFS 克隆文件系统

# 使用 JuiceFS 快照克隆目录
juicefs snapshot create /jfs/workspace ws-snapshot
juicefs snapshot restore /jfs/workspace-clone ws-snapshot

下一步

查看克隆任务
了解快照

6 - 监控

全栈可观测性

Piglet Run 包含基于 VictoriaMetrics 和 Grafana 的完整监控栈。

组件

组件	角色
VictoriaMetrics	时序数据库
Grafana	可视化仪表盘
node_exporter	系统指标
pg_exporter	PostgreSQL 指标

仪表盘

访问 Grafana：http://<ip>/ui

可用仪表盘：

Claude Code：AI Agent 监控
PostgreSQL：数据库性能
System：主机指标
JuiceFS：文件系统统计

指标

收集超过 3000+ 指标：

数据库查询、连接、锁
系统 CPU、内存、磁盘、网络
应用特定指标

告警

配置告警用于：

高 CPU/内存使用
数据库连接限制
磁盘空间警告
查询性能问题

下一步

查看监控任务
了解 Grafana 参考

7 - 安全

安全模型

Piglet Run 为开发环境提供多层安全保护。

访问控制

层级	机制
网络	防火墙、VPN 支持
Web	Nginx 认证
数据库	PostgreSQL 角色
文件系统	Unix 权限

认证

默认认证方式：

VS Code：密码或令牌
Jupyter：基于令牌
Grafana：用户名/密码
PostgreSQL：基于角色访问

加密

类型	支持
传输中	SSL/TLS
静态	数据库加密
备份	加密备份

最佳实践

立即更改默认密码
为所有服务启用 SSL
限制网络访问
定期安全更新

下一步

配置 SSL
设置域名