这是本节的多页打印视图。
点击此处打印 .
返回本页常规视图 .
Piglet 文档
搭建 AI 就绪的 PostgreSQL 工作空间，理解它的工作方式，并可靠地运行它。
欢迎阅读 Piglet 文档。
Piglet 是构建在 Pigsty 之上的轻量运行时配置。它把一台 Linux 主机变成人类与 Agent 共享的完整环境：AI 编程、PostgreSQL、持久化存储、可观测性与 Web 交付都在同一个世界里。
文档结构
文档按四类问题组织：
快速入口
核心能力
1 - 关于
了解 Piglet Run 项目、开源协议、社区与支持方式。
Piglet Run 是 Pigsty 的轻量运行时环境，专为 AI Web Coding 设计的云端编码沙箱。
什么是 Piglet Run？
Piglet Run 集成了：
PostgreSQL 18 及 400+ 扩展JuiceFS 分布式存储，支持 PITRVS Code Server 网页版开发环境JupyterLab 数据科学工具Claude Code AI 辅助编码Grafana 可观测性监控
一键部署，开箱即用。
项目链接
章节目录
1.1 - 开源协议
Piglet Run 是基于 Apache 2.0 协议开源的软件。
Apache License 2.0
Piglet Run 基于 Apache License 2.0 协议开源。
Copyright 2025 Ruohang Feng
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
这意味着什么
Apache 2.0 协议允许您：
✅ 使用 - 以任何目的使用本软件
✅ 修改 - 修改源代码
✅ 分发 - 分发软件副本
✅ 商用 - 用于商业项目
✅ 专利授权 - 包含贡献者的专利授权
使用要求
使用 Piglet Run 时，您需要：
包含许可证和版权声明
说明对代码所做的任何重大更改
如果存在 NOTICE 文件，需要包含它
第三方组件
Piglet Run 包含以下第三方开源组件：
请参阅各组件的许可证了解具体条款。
2 - 概念
理解 Piglet Run 的核心概念、架构设计与设计理念。
概念 文档帮助你理解 Piglet Run 背后的原理和架构。
你将学到
Piglet Run 的底层工作原理
设计哲学和架构
快照、克隆、存储等关键概念
主题
2.1 - 概述
什么是 Piglet Run？
Piglet Run （小猪运行时）是 Pigsty 的轻量运行时环境，专为 AI Web Coding 打造的云端编码沙箱 。它将 PostgreSQL 数据库、JuiceFS 分布式存储、VS Code、JupyterLab 等工具整合为一体。
为什么选择 Piglet Run？
在 AI 辅助开发的时代，开发者需要：
即用型开发环境 ，开箱即用强大的数据库 ，所有扩展都可用安全的实验环境 ，轻松回滚无缝协作 ，人与 AI Agent 协同工作
Piglet Run 将这一切整合在一个软件包中。
核心特性
适用人群
独立开发者 ：需要强大开发环境开发团队 ：需要共享开发基础设施AI 开发者 ：使用 Claude Code 等工具数据科学家 ：使用 PostgreSQL 和 Jupyter学习者 ：探索 PostgreSQL 和 Web 开发
工作原理
┌─────────────────────────────────────────────────────────────┐
│ Piglet Run │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ VS Code │ │ Jupyter │ │ Claude │ │ Nginx │ │
│ │ Server │ │ Lab │ │ Code │ │ Proxy │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └────────────┴────────────┴────────────┘ │
│ │ │
│ ┌──────────────────────┴──────────────────────┐ │
│ │ JuiceFS (共享存储) │ │
│ └──────────────────────┬──────────────────────┘ │
│ │ │
│ ┌──────────────────────┴──────────────────────┐ │
│ │ PostgreSQL 18 + 400+ 扩展 │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ VictoriaMetrics + Grafana (监控) │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
下一步
2.2 - 架构概述
Piglet 里有什么，怎么组织
Piglet 是什么
Piglet 是专为 AI 辅助编程设计的 Agentic Postgres 运行时。
它不只是一个数据库，而是一个完整的云端开发环境：从一台 0.64 元的裸 VM，到完整的生产级网站，开箱即用。
产品本质
Piglet 是一个"缝合怪 "——它集成了：
核心价值 ：由生产级方案（Pigsty）改造成的个人级方案——降维打击。
核心组件
┌─────────────────────────────────────────────────────────────────┐
│ Piglet Runtime │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ VS Code │ │ Jupyter │ │ Claude │ │ Your │ │
│ │ Server │ │ Lab │ │ Code │ │ App │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └─────────────┴─────────────┴─────────────┘ │
│ │ │
│ ┌─────┴─────┐ │
│ │ Nginx │ 反向代理 + SSL │
│ └─────┬─────┘ │
│ │ │
├──────────────────────────┼──────────────────────────────────────┤
│ │ │
│ ┌──────────────────────┴──────────────────────┐ │
│ │ PostgreSQL 17 │ │
│ │ 生产级数据库 + PITR 时间旅行 │ │
│ └──────────────────────┬──────────────────────┘ │
│ │ │
│ ┌──────────────────────┴──────────────────────┐ │
│ │ JuiceFS (PITRFS) │ │
│ │ 文件系统也能时间旅行的秘密武器 │ │
│ └─────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Grafana │ │ Victoria │ │ Loki │ │
│ │ 监控面板 │ │ Metrics │ │ 日志 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘
组件清单
Agentic 设计
Piglet 的核心设计理念是 Human-Agent Parity （人机对等）：
人看到的 = Agent 看到的，同一套工具、同一个视角。
人机分工
Agent 可能比很多用户更懂环境里有什么能用，但最终还是人类说了算。
用户画像
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 的关系
Piglet 是 Pigsty 的精简版 ，继承了生产级的可靠性，但去掉了企业级的复杂性。
下一步
2.3 - 存储
JuiceFS 共享存储
Piglet Run 使用 JuiceFS 提供基于 PostgreSQL 的分布式文件系统。
为什么选择 JuiceFS？
POSIX 兼容 ：像普通文件系统一样工作数据库后端 ：数据存储在 PostgreSQL快照支持 ：时间点恢复多用户 ：跨会话共享工作空间
工作原理
┌────────────────────────────────────────────┐
│ 应用层 │
│ (VS Code, Jupyter, Claude Code 等) │
└──────────────────┬─────────────────────────┘
│ POSIX API
▼
┌────────────────────────────────────────────┐
│ JuiceFS FUSE │
│ (用户空间文件系统) │
└──────────────────┬─────────────────────────┘
│
┌──────────┴──────────┐
│ │
▼ ▼
┌───────────────┐ ┌───────────────┐
│ 元数据 │ │ 数据块 │
│ (PostgreSQL) │ │ (PostgreSQL) │
└───────────────┘ └───────────────┘
特性
下一步
2.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
使用场景
备份管理
# 查看备份状态
pig pb info
# 查看备份日志
pig pb log tail
# 创建增量备份
pig pb backup incr
# 创建差异备份
pig pb backup diff
下一步
2.5 - 克隆
瞬间克隆
Piglet Run 支持 Copy-on-Write（写时复制）克隆，实现快速数据库分支。
工作原理
Copy-on-Write 意味着：
克隆时零拷贝
只有修改的块 才消耗存储
TB 级数据库毫秒级 克隆
原始数据库
┌─────────────────────┐
│ Block A │ Block B │ Block C │
└────┬────┴────┬────┴────┬────┘
│ │ │
▼ ▼ ▼
┌────────────────────────────┐
│ 共享存储 │
└────────────────────────────┘
▲ ▲ ▲
│ │ │
┌────┴────┬────┴────┬────┴────┐
│ Block A │ Block B │ Block C │ (共享)
│ │ Block B'│ │ (克隆中修改)
└─────────┴─────────┴─────────┘
克隆数据库
使用场景
数据库克隆
使用 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
下一步
2.6 - 监控
全栈可观测性
Piglet Run 包含基于 VictoriaMetrics 和 Grafana 的完整监控栈。
组件
仪表盘
访问 Grafana：http://<ip>/ui
可用仪表盘：
Claude Code ：AI Agent 监控PostgreSQL ：数据库性能System ：主机指标JuiceFS ：文件系统统计
指标
收集超过 3000+ 指标：
数据库查询、连接、锁
系统 CPU、内存、磁盘、网络
应用特定指标
告警
配置告警用于：
高 CPU/内存使用
数据库连接限制
磁盘空间警告
查询性能问题
下一步
2.7 - 安全
安全模型
Piglet Run 为开发环境提供多层安全保护。
访问控制
认证
默认认证方式：
VS Code ：密码或令牌Jupyter ：基于令牌Grafana ：用户名/密码PostgreSQL ：基于角色访问
加密
最佳实践
立即更改默认密码
为所有服务启用 SSL
限制网络访问
定期安全更新
下一步
3 - 教程
从零开始学习 Piglet Run 的分步指南。
教程 文档提供从零开始学习 Piglet Run 的分步指南。
学习路径
按顺序学习以下教程：
安装 快速开始 VS Code Jupyter Claude Code 数据库
主题
/Users/vonng/pgsty/piglet.run/static/img/logo/piglet.png
3.1 - 完整安装
Piglet 安装的完整流程
准备工作
你需要什么
还没有服务器？ 参考 采购云服务器 指南，各大云厂商最低 0.64 元/小时起。
获取服务器访问权限
你需要能 SSH 登录到服务器：
一键安装（推荐）
最快的方式，适合大多数用户：
# 中国用户（推荐）
curl -fsSL https://repo.pigsty.io/pig | bash && pig sty install -m piglet
# 海外用户
curl -fsSL https://repo.pigsty.io/pig | bash && pig sty install -m piglet
就这一行命令。等它跑完，你的 Agentic Postgres 运行时就准备好了。
分步安装
如果你想了解每一步在做什么，或者需要自定义配置：
第一步：安装 Pig CLI
# 中国镜像
curl -fsSL https://repo.pigsty.io/pig | bash
# 海外 CDN
curl -fsSL https://repo.pigsty.io/pig | bash
Pig 是 Piglet 的命令行工具，安装完成后会自动添加到 PATH。
第二步：配置软件源
pig repo set # 自动检测系统，配置所有必要的软件源
如果你在中国大陆，使用镜像源会更快：
pig repo add all --region china # 使用中国镜像
第三步：初始化并安装
pig sty init # 下载 Pigsty 到 ~/pigsty
pig sty boot # 安装 Ansible（自动化工具）
pig sty conf -m piglet # 生成 Piglet 专用配置
pig sty deploy # 运行安装（这一步可能需要几分钟）
验证安装
安装完成后，检查一切是否正常：
pig status # 整体状态
pig pg status # PostgreSQL 状态
访问你的服务
打开浏览器，访问服务器 IP：
默认凭据
安全提示 ：首次登录后请立即修改密码！
配置 Claude Code（可选）
如果你要用 Claude Code 进行 AI 辅助编程：
# 在你的本地机器上
claude config set apiKey YOUR_ANTHROPIC_API_KEY
# 连接到 Piglet 服务器
claude connect ssh root@your-server-ip
详见 Claude Code 配置 。
故障排除
查看日志
pig pg log tail # PostgreSQL 日志
journalctl -u nginx -f # Nginx 日志
journalctl -u code-server -f # VS Code 日志
常见问题
重新安装
如果需要从头开始：
pig sty destroy # 清理现有安装
pig sty deploy # 重新部署
下一步
安装完成了！接下来：
快速开始教程 配置 Claude Code 架构概述
3.2 - 快速开始
安装 Piglet，用 Claude Code 做一个静态网页
目标
这个教程会带你完成：
登录你的 Piglet 环境
用 Claude Code 生成一个数据可视化网页
把它部署上线
完成后，你会有一个可以公开访问的网页，展示一个交互式 ECharts 图表。
第一步：登录环境
方式 A：网页版 VS Code（推荐新手）
打开浏览器，访问：
输入密码 piglet（首次使用请修改）。
方式 B：本地 VS Code + SSH（推荐日常使用）
在本地 VS Code 中：
安装 Remote - SSH 扩展
按 Cmd+Shift+P / Ctrl+Shift+P，选择 Remote-SSH: Connect to Host
输入 root@你的服务器IP
方式 C：Claude Code 直连（AI 编程）
# 在本地终端
claude connect ssh root@你的服务器IP
第二步：创建项目目录
打开终端，创建工作目录：
cd ~/data
mkdir my-first-site
cd my-first-site
第三步：让 Claude 帮你写代码
这是 Piglet 的魔法时刻。
如果你用 Claude Code：
直接告诉它你想要什么：
给我做一个网页，展示一个 ECharts 柱状图，数据是过去 7 天的访问量（随便编一些数据）。
要求：
- 单个 HTML 文件，内联所有 CSS 和 JS
- 使用 ECharts CDN
- 页面要好看，有标题
Claude 会直接在当前目录创建 index.html。
如果你手动写：
创建 index.html：
<!DOCTYPE html>
< html lang = "zh" >
< head >
< meta charset = "UTF-8" >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
< title > 我的第一个 Piglet 网页</ title >
< script src = "https://cdn.jsdelivr.net/npm/[email protected] /dist/echarts.min.js" ></ script >
< style >
* { margin : 0 ; padding : 0 ; box-sizing : border-box ; }
body {
font-family : - apple-system , BlinkMacSystemFont , 'Segoe UI' , Roboto , sans-serif ;
background : linear-gradient ( 135 deg , #667eea 0 % , #764ba2 100 % );
min-height : 100 vh ;
display : flex ;
flex-direction : column ;
align-items : center ;
padding : 40 px 20 px ;
}
h1 {
color : white ;
margin-bottom : 30 px ;
font-size : 2 rem ;
text-shadow : 0 2 px 4 px rgba ( 0 , 0 , 0 , 0.2 );
}
. chart-container {
background : white ;
border-radius : 16 px ;
padding : 30 px ;
box-shadow : 0 20 px 60 px rgba ( 0 , 0 , 0 , 0.3 );
width : 100 % ;
max-width : 800 px ;
}
# chart { width : 100 % ; height : 400 px ; }
. footer {
color : rgba ( 255 , 255 , 255 , 0.8 );
margin-top : 30 px ;
font-size : 0.9 rem ;
}
</ style >
</ head >
< body >
< h1 > 过去 7 天访问量</ h1 >
< div class = "chart-container" >
< div id = "chart" ></ div >
</ div >
< p class = "footer" > 由 Piglet 驱动 | Code Fearlessly, Ship Instantly.</ p >
< script >
const chart = echarts . init ( document . getElementById ( 'chart' ));
const option = {
tooltip : { trigger : 'axis' },
xAxis : {
type : 'category' ,
data : [ '周一' , '周二' , '周三' , '周四' , '周五' , '周六' , '周日' ]
},
yAxis : { type : 'value' , name : '访问量' },
series : [{
data : [ 820 , 932 , 901 , 1290 , 1330 , 1520 , 1680 ],
type : 'bar' ,
itemStyle : {
borderRadius : [ 8 , 8 , 0 , 0 ],
color : new echarts . graphic . LinearGradient ( 0 , 0 , 0 , 1 , [
{ offset : 0 , color : '#667eea' },
{ offset : 1 , color : '#764ba2' }
])
}
}]
};
chart . setOption ( option );
window . addEventListener ( 'resize' , () => chart . resize ());
</ script >
</ body >
</ html >
第四步：预览
在终端中启动一个简单的 HTTP 服务器：
python3 -m http.server 8080
然后访问 http://你的服务器IP:8080，你应该能看到一个漂亮的柱状图页面。
按 Ctrl+C 停止服务器。
第五步：部署上线
让这个网页可以通过正式的 URL 访问：
# 复制到 Nginx 静态文件目录
sudo cp index.html /www/my-first-site/
或者使用 pig deploy 命令：
pig deploy . --name my-first-site
现在访问 http://你的服务器IP/my-first-site/ 就能看到你的网页了。
恭喜！
你刚刚完成了：
✅ 登录 Piglet 开发环境
✅ 用 Claude Code（或手动）创建了一个数据可视化网页
✅ 把它部署到了互联网上
从想法到上线，就是这么简单。
发生了什么
让我们回顾一下 Piglet 为你做了什么：
这就是 Code Fearlessly, Ship Instantly 的含义。
下一步
现在你已经熟悉了基本流程，可以继续：
第一个 Web 应用 配置 Claude Code 灾难恢复
3.3 - VS Code
网页版 VS Code
学习在 Piglet Run 中使用网页版 VS Code 服务器。
访问
打开浏览器访问：
功能
网页版 VS Code 包含：
完整的浏览器中 VS Code 体验
扩展支持
集成终端
Git 集成
Python、Go、Node.js 支持
开始使用
1. 打开文件夹
点击"打开文件夹"，选择 /root/workspace。
2. 安装扩展
推荐扩展：
Python
Pylance
GitLens
Database Client
3. 配置设置
按 Ctrl+, 打开设置。
技巧
使用 Ctrl+Shift+P 打开命令面板
`Ctrl+`` 打开集成终端
Ctrl+B 切换侧边栏
下一步
3.4 - Jupyter
JupyterLab 教程
学习在 Piglet Run 中使用 JupyterLab 进行数据分析。
访问
访问：
功能
交互式 Python 笔记本
丰富输出（图表、表格、图像）
PostgreSQL 集成
多内核（Python、SQL）
开始使用
1. 创建笔记本
点击 Notebook 下的"Python 3"。
2. 连接 PostgreSQL
import psycopg
import pandas as pd
conn = psycopg . connect ( "postgres://postgres@localhost/postgres" )
df = pd . read_sql ( "SELECT * FROM pg_stat_activity" , conn )
df . head ()
3. 数据可视化
import matplotlib.pyplot as plt
df [ 'state' ] . value_counts () . plot ( kind = 'bar' )
plt . show ()
技巧
使用 Shift+Enter 运行单元格
将笔记本保存到 /root/workspace/notebooks
下一步
3.5 - Claude Code 配置
配置 Claude Code 进行 AI 辅助编程
什么是 Claude Code
Claude Code 是 Anthropic 官方的 AI 编程助手。它能：
理解你的代码库
根据自然语言指令编写代码
执行命令、创建文件、修改代码
直接操作你的 Piglet 环境
在 Piglet 中，Claude Code 开箱能用 ——环境已经预配置好了 CLAUDE.md，告诉 AI 这里有什么工具可以用。
获取 API Key
第一步：注册 Anthropic 账号
访问 console.anthropic.com 注册账号。
第二步：创建 API Key
登录后进入 API Keys 页面
点击 Create Key
复制生成的密钥（以 sk-ant- 开头）
注意 ：API Key 只显示一次，请妥善保存。
第三步：充值
Claude Code 按 token 计费。建议先充值 $5-10 试用。
配置方式
方式 A：本地 Claude Code 连接远程服务器（推荐）
这是最流畅的体验——在本地终端运行 Claude Code，但它操作的是远程 Piglet 服务器。
1. 在本地安装 Claude Code
# macOS / Linux
npm install -g @anthropic-ai/claude-code
# 或使用 Homebrew
brew install claude-code
2. 配置 API Key
claude config set apiKey sk-ant-your-api-key-here
3. 连接到 Piglet 服务器
claude connect ssh root@你的服务器IP
现在你可以直接对话：
> 帮我看看这个服务器上有什么
> 在 ~/data 下创建一个 Flask 项目
> 写一个爬虫，抓取 Hacker News 首页标题，存到 PostgreSQL
方式 B：在服务器上直接运行
如果你通过网页版 VS Code 或 SSH 登录到服务器：
1. 配置环境变量
# 临时生效
export ANTHROPIC_API_KEY = "sk-ant-your-api-key-here"
# 永久生效（写入 .bashrc）
echo 'export ANTHROPIC_API_KEY="sk-ant-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
2. 启动 Claude Code
方式 C：VS Code 扩展（可选）
如果你用本地 VS Code + Remote SSH：
安装 Claude 扩展
在设置中配置 API Key
按 Cmd+Shift+P 输入 Claude 使用
CLAUDE.md：告诉 AI 环境里有什么
Piglet 在 ~/CLAUDE.md 预置了一份环境说明文件。Claude Code 会自动读取它，了解：
这是一个 Piglet 环境
PostgreSQL 数据库连接方式
可用的命令行工具（pig、psql 等）
文件系统结构
部署方式
你可以编辑这个文件，添加项目特定的说明：
例如：
## 项目说明
这是一个电商网站项目，使用：
- 后端：FastAPI
- 数据库：PostgreSQL（已配置）
- 前端：React（在 /www/shop-frontend）
## 数据库结构
- users 表：用户信息
- products 表：商品信息
- orders 表：订单信息
## 部署命令
pig deploy ./dist --name shop
使用示例
创建项目
> 在 ~/data/blog 创建一个 Flask 博客应用，带文章的增删改查，使用 PostgreSQL 存储
调试问题
> 看看 PostgreSQL 的日志，最近有什么错误吗
> 这个 Python 脚本报错了，帮我修一下
部署应用
> 把 ~/data/blog 部署到 /www/blog，配置 Nginx 反向代理
数据库操作
> 帮我创建一个 users 表，包含 id、name、email、created_at 字段
> 给我写一个 SQL 查询，统计过去 7 天每天的注册用户数
监控诊断
> 给我生成一份服务器巡检报告
> 看看磁盘空间和内存使用情况
搞砸了也不怕
这是 Piglet 的核心价值之一：Code Fearlessly 。
如果 Claude 搞砸了什么：
# 查看最近的文件系统快照
pig snapshot list
# 回滚到某个时间点
pig snapshot restore --time "2024-01-15 14:30:00"
数据库也一样：
# 数据库时间旅行
pig pg pitr --time "2024-01-15 14:30:00"
所以放心大胆地让 Claude 去尝试。
最佳实践
费用参考
Claude Code 使用 Claude Sonnet 模型，按 token 计费：
日常使用，$5-10 可以用很久。
故障排除
下一步
3.6 - 数据库
PostgreSQL 基础
学习在 Piglet Run 中使用 PostgreSQL。
连接
使用 psql
psql postgres://postgres@localhost/postgres
使用 Python
import psycopg
conn = psycopg . connect ( "postgres://postgres@localhost/postgres" )
创建数据库
安装扩展
PostgreSQL 18 有 400+ 扩展可用：
-- 向量搜索
CREATE EXTENSION vector ;
-- 时序数据
CREATE EXTENSION timescaledb ;
-- 全文搜索（中文）
CREATE EXTENSION zhparser ;
基本操作
-- 创建表
CREATE TABLE users (
id SERIAL PRIMARY KEY ,
name TEXT NOT NULL ,
email TEXT UNIQUE ,
created_at TIMESTAMPTZ DEFAULT NOW ()
);
-- 插入数据
INSERT INTO users ( name , email ) VALUES ( 'Alice' , '[email protected] ' );
-- 查询
SELECT * FROM users ;
监控
在以下位置查看数据库性能：
http://<ip>/ui/d/pgsql-overview
下一步
3.7 - 第一个 Web 应用
做一个带登录功能的 Flask 应用，连接 PostgreSQL
目标
这个教程会带你创建一个完整的 Web 应用：
Flask 后端框架
PostgreSQL 数据库存储用户
用户注册、登录、注销功能
Session 管理
部署上线
完成后，你会有一个真正可用的 Web 应用，不只是 Hello World。
前置条件
已完成 快速开始教程
已登录 Piglet 环境（VS Code 或 SSH）
第一步：创建项目
cd ~/data
mkdir my-flask-app
cd my-flask-app
创建 Python 虚拟环境并安装依赖：
python3 -m venv venv
source venv/bin/activate
pip install flask psycopg[ binary] python-dotenv
第二步：创建数据库表
连接 PostgreSQL：
psql postgres://postgres:piglet@localhost/postgres
创建用户表：
CREATE TABLE users (
id SERIAL PRIMARY KEY ,
username VARCHAR ( 50 ) UNIQUE NOT NULL ,
password_hash VARCHAR ( 255 ) NOT NULL ,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- 退出 psql
\ q
第三步：编写应用代码
创建 app.py：
import os
import hashlib
from flask import Flask , render_template , request , redirect , url_for , session , flash
import psycopg
app = Flask ( __name__ )
app . secret_key = os . urandom ( 24 )
# 数据库连接
DB_URL = "postgres://postgres:piglet@localhost/postgres"
def get_db ():
return psycopg . connect ( DB_URL )
def hash_password ( password ):
return hashlib . sha256 ( password . encode ()) . hexdigest ()
# 首页
@app.route ( '/' )
def index ():
user = session . get ( 'user' )
return render_template ( 'index.html' , user = user )
# 注册
@app.route ( '/register' , methods = [ 'GET' , 'POST' ])
def register ():
if request . method == 'POST' :
username = request . form [ 'username' ]
password = request . form [ 'password' ]
with get_db () as conn :
with conn . cursor () as cur :
# 检查用户名是否已存在
cur . execute ( "SELECT id FROM users WHERE username = %s " , ( username ,))
if cur . fetchone ():
flash ( '用户名已存在' , 'error' )
return redirect ( url_for ( 'register' ))
# 创建用户
cur . execute (
"INSERT INTO users (username, password_hash) VALUES ( %s , %s )" ,
( username , hash_password ( password ))
)
conn . commit ()
flash ( '注册成功，请登录' , 'success' )
return redirect ( url_for ( 'login' ))
return render_template ( 'register.html' )
# 登录
@app.route ( '/login' , methods = [ 'GET' , 'POST' ])
def login ():
if request . method == 'POST' :
username = request . form [ 'username' ]
password = request . form [ 'password' ]
with get_db () as conn :
with conn . cursor () as cur :
cur . execute (
"SELECT id, username FROM users WHERE username = %s AND password_hash = %s " ,
( username , hash_password ( password ))
)
user = cur . fetchone ()
if user :
session [ 'user' ] = { 'id' : user [ 0 ], 'username' : user [ 1 ]}
flash ( f '欢迎回来， { user [ 1 ] } ！' , 'success' )
return redirect ( url_for ( 'index' ))
else :
flash ( '用户名或密码错误' , 'error' )
return render_template ( 'login.html' )
# 注销
@app.route ( '/logout' )
def logout ():
session . pop ( 'user' , None )
flash ( '已退出登录' , 'success' )
return redirect ( url_for ( 'index' ))
if __name__ == '__main__' :
app . run ( host = '0.0.0.0' , port = 5000 , debug = True )
第四步：创建模板
创建模板目录：
创建 templates/base.html（基础模板）：
<!DOCTYPE html>
< html lang = "zh" >
< head >
< meta charset = "UTF-8" >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
< title > {% block title %}我的应用{% endblock %}</ title >
< style >
* { margin : 0 ; padding : 0 ; box-sizing : border-box ; }
body {
font-family : - apple-system , BlinkMacSystemFont , 'Segoe UI' , Roboto , sans-serif ;
background : #f5f5f5 ;
min-height : 100 vh ;
}
. navbar {
background : linear-gradient ( 135 deg , #667eea 0 % , #764ba2 100 % );
padding : 1 rem 2 rem ;
display : flex ;
justify-content : space-between ;
align-items : center ;
}
. navbar a { color : white ; text-decoration : none ; margin-left : 1 rem ; }
. navbar a : hover { text-decoration : underline ; }
. logo { color : white ; font-size : 1.5 rem ; font-weight : bold ; }
. container { max-width : 600 px ; margin : 2 rem auto ; padding : 0 1 rem ; }
. card {
background : white ;
border-radius : 8 px ;
padding : 2 rem ;
box-shadow : 0 2 px 10 px rgba ( 0 , 0 , 0 , 0.1 );
}
. flash { padding : 1 rem ; border-radius : 4 px ; margin-bottom : 1 rem ; }
. flash . success { background : #d4edda ; color : #155724 ; }
. flash . error { background : #f8d7da ; color : #721c24 ; }
input {
width : 100 % ;
padding : 0.75 rem ;
margin : 0.5 rem 0 1 rem ;
border : 1 px solid #ddd ;
border-radius : 4 px ;
font-size : 1 rem ;
}
button {
width : 100 % ;
padding : 0.75 rem ;
background : linear-gradient ( 135 deg , #667eea 0 % , #764ba2 100 % );
color : white ;
border : none ;
border-radius : 4 px ;
font-size : 1 rem ;
cursor : pointer ;
}
button : hover { opacity : 0.9 ; }
h1 , h2 { margin-bottom : 1 rem ; }
p { color : #666 ; line-height : 1.6 ; }
a { color : #667eea ; }
</ style >
</ head >
< body >
< nav class = "navbar" >
< span class = "logo" > MyApp</ span >
< div >
< a href = "{{ url_for('index') }}" > 首页</ a >
{% if session.user %}
< a href = "{{ url_for('logout') }}" > 退出 ({{ session.user.username }})</ a >
{% else %}
< a href = "{{ url_for('login') }}" > 登录</ a >
< a href = "{{ url_for('register') }}" > 注册</ a >
{% endif %}
</ div >
</ nav >
< div class = "container" >
{% with messages = get_flashed_messages(with_categories=true) %}
{% for category, message in messages %}
< div class = "flash {{ category }}" > {{ message }}</ div >
{% endfor %}
{% endwith %}
{% block content %}{% endblock %}
</ div >
</ body >
</ html >
创建 templates/index.html：
{% extends "base.html" %}
{% block title %}首页{% endblock %}
{% block content %}
< div class = "card" >
{% if user %}
< h1 > 欢迎，{{ user.username }}！</ h1 >
< p > 你已成功登录。这是一个由 Piglet 驱动的 Flask 应用。</ p >
< p style = "margin-top: 1rem;" >
< a href = "{{ url_for('logout') }}" > 退出登录</ a >
</ p >
{% else %}
< h1 > 欢迎来到 MyApp</ h1 >
< p > 这是一个由 Piglet 驱动的 Flask 应用，使用 PostgreSQL 存储用户数据。</ p >
< p style = "margin-top: 1rem;" >
< a href = "{{ url_for('login') }}" > 登录</ a > 或
< a href = "{{ url_for('register') }}" > 注册</ a > 开始使用
</ p >
{% endif %}
</ div >
{% endblock %}
创建 templates/login.html：
{% extends "base.html" %}
{% block title %}登录{% endblock %}
{% block content %}
< div class = "card" >
< h2 > 登录</ h2 >
< form method = "POST" >
< label > 用户名</ label >
< input type = "text" name = "username" required >
< label > 密码</ label >
< input type = "password" name = "password" required >
< button type = "submit" > 登录</ button >
</ form >
< p style = "margin-top: 1rem; text-align: center;" >
还没有账号？< a href = "{{ url_for('register') }}" > 注册</ a >
</ p >
</ div >
{% endblock %}
创建 templates/register.html：
{% extends "base.html" %}
{% block title %}注册{% endblock %}
{% block content %}
< div class = "card" >
< h2 > 注册</ h2 >
< form method = "POST" >
< label > 用户名</ label >
< input type = "text" name = "username" required >
< label > 密码</ label >
< input type = "password" name = "password" required >
< button type = "submit" > 注册</ button >
</ form >
< p style = "margin-top: 1rem; text-align: center;" >
已有账号？< a href = "{{ url_for('login') }}" > 登录</ a >
</ p >
</ div >
{% endblock %}
第五步：运行测试
访问 http://你的服务器IP:5000，试试：
点击"注册"，创建一个账号
用刚才的账号登录
看到欢迎页面
点击"退出"
第六步：部署上线
开发完成后，用 Gunicorn 部署到生产环境：
# 安装 Gunicorn
pip install gunicorn
# 创建 systemd 服务
sudo tee /etc/systemd/system/myapp.service << EOF
[Unit]
Description=My Flask App
After=network.target
[Service]
User=root
WorkingDirectory=/root/data/my-flask-app
Environment="PATH=/root/data/my-flask-app/venv/bin"
ExecStart=/root/data/my-flask-app/venv/bin/gunicorn -w 2 -b 127.0.0.1:5000 app:app
Restart=always
[Install]
WantedBy=multi-user.target
EOF
# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable myapp
sudo systemctl start myapp
配置 Nginx 反向代理：
sudo tee /etc/nginx/conf.d/myapp.conf << EOF
server {
listen 80;
server_name myapp.你的域名.com;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
}
}
EOF
sudo nginx -t && sudo systemctl reload nginx
让 Claude 帮你做
上面的步骤看起来很多？试试让 Claude Code 来做：
帮我在 ~/data/my-flask-app 创建一个 Flask 应用：
- 用户注册、登录、注销功能
- 使用 PostgreSQL 存储用户（连接串：postgres://postgres:piglet@localhost/postgres）
- 界面要好看
- 帮我创建数据库表
- 最后帮我部署到 Nginx
Claude 会自动完成所有步骤。
你学到了什么
✅ 创建 Flask 应用
✅ 连接 PostgreSQL 数据库
✅ 实现用户认证（注册/登录/注销）
✅ 使用 Jinja2 模板
✅ 部署到生产环境
下一步
数据应用 监控可视化 灾难恢复
4 - 参考手册
Piglet 配置、CLI、API、Portal 与编辑器的准确说明。
当你已经知道要找什么，需要确认准确的命令、参数、路径或端点时，请使用参考手册。
下面分别提供 Piglet 配置、CLI、API、Nginx Portal 与 VS Code 的详细说明。
4.1 - CLI
Piglet Run 命令行接口参考。
概述
pig CLI 提供对 Piglet Run 实例的完整控制。
安装
CLI 随 Piglet Run 自动安装。验证安装：
全局选项
命令
状态命令
pig status # 显示系统状态
pig status db # 数据库状态
pig status services # 所有服务状态
服务命令
pig start [ service] # 启动服务
pig stop [ service] # 停止服务
pig restart [ service] # 重启服务
pig logs [ service] # 查看日志
数据库命令
pig db list # 列出数据库
pig db create NAME # 创建数据库
pig db drop NAME # 删除数据库
pig db connect [ NAME] # 连接数据库
备份命令
pig backup create # 创建备份
pig backup list # 列出备份
pig backup restore ID # 恢复备份
用户命令
pig user list # 列出用户
pig user create NAME # 创建用户
pig user delete NAME # 删除用户
pig user passwd NAME # 修改密码
配置命令
pig config show # 显示配置
pig config set KEY VAL # 设置配置
pig config get KEY # 获取配置
环境变量
配置文件
默认位置：/etc/piglet/piglet.yml
database :
host : localhost
port : 5432
user : dba
services :
vscode : true
jupyter : true
grafana : true
log :
level : info
file : /var/log/piglet/piglet.log
退出码
另请参阅
4.2 - 配置
Piglet Run 配置文件参考。
概述
Piglet Run 使用位于 /etc/piglet/ 的 YAML 配置文件。
主配置
文件：/etc/piglet/piglet.yml
# Piglet Run 配置
# 系统设置
system :
hostname : piglet
timezone : UTC
locale : en_US.UTF-8
# 数据库设置
database :
host : localhost
port : 5432
user : dba
database : postgres
max_connections : 100
shared_buffers : 256MB
# 服务
services :
vscode :
enabled : true
port : 8080
jupyter :
enabled : true
port : 8888
grafana :
enabled : true
port : 3000
# 存储
storage :
data_dir : /data
backup_dir : /data/backup
temp_dir : /tmp/piglet
# 日志
logging :
level : info
file : /var/log/piglet/piglet.log
max_size : 100M
max_files : 10
数据库配置
文件：/etc/piglet/database.yml
# PostgreSQL 配置
postgresql :
version : 17
data_directory : /data/postgres
# 连接设置
listen_addresses : localhost
port : 5432
max_connections : 100
# 内存设置
shared_buffers : 256MB
effective_cache_size : 768MB
work_mem : 4MB
maintenance_work_mem : 64MB
# WAL 设置
wal_level : replica
max_wal_size : 1GB
min_wal_size : 80MB
# 日志
log_destination : csvlog
logging_collector : on
log_directory : pg_log
服务配置
VS Code 服务器
文件：/etc/piglet/vscode.yml
vscode :
enabled : true
port : 8080
auth : password
extensions :
- ms-python.python
- rust-lang.rust-analyzer
JupyterLab
文件：/etc/piglet/jupyter.yml
jupyter :
enabled : true
port : 8888
notebook_dir : /home/dba/notebooks
kernels :
- python3
- ir
备份配置
文件：/etc/piglet/backup.yml
backup :
enabled : true
schedule : "0 2 * * *"
retention : 7
database :
type : full
compress : true
files :
enabled : true
paths :
- /home/dba
- /etc/piglet
网络配置
文件：/etc/piglet/network.yml
network :
# 域名设置
domain : localhost
# SSL 设置
ssl :
enabled : false
cert : /etc/piglet/ssl/cert.pem
key : /etc/piglet/ssl/key.pem
# 代理设置
proxy :
enabled : false
host : proxy.example.com
port : 8080
环境变量
使用环境变量覆盖配置：
export PIG_DATABASE_PORT = 5433
export PIG_SERVICES_VSCODE_ENABLED = false
export PIG_LOGGING_LEVEL = debug
另请参阅
4.3 - VS Code 服务器
Piglet Run 的 VS Code 服务器配置和详情。
概述
Piglet Run 包含预配置的 VS Code 服务器 (code-server)，用于基于浏览器的开发。
访问
默认 URL：http://<ip>/code
配置
文件：/etc/piglet/vscode.yml
vscode :
enabled : true
bind_addr : 127.0.0.1 : 8080
auth : password
password : ${VSCODE_PASSWORD}
cert : false
# 用户数据目录
user_data_dir : /home/dba/.local/share/code-server
# 扩展目录
extensions_dir : /home/dba/.local/share/code-server/extensions
预装扩展
安装扩展
通过 CLI
code-server --install-extension ms-python.python
通过设置
在浏览器中打开 VS Code
进入扩展 (Ctrl+Shift+X)
搜索并安装扩展
设置
默认设置位置：/home/dba/.local/share/code-server/User/settings.json
{
"editor.fontSize" : 14 ,
"editor.tabSize" : 2 ,
"editor.formatOnSave" : true ,
"terminal.integrated.defaultProfile.linux" : "bash" ,
"python.defaultInterpreterPath" : "/usr/bin/python3" ,
"files.autoSave" : "afterDelay"
}
服务管理
# 启动 VS Code 服务器
pig start vscode
# 停止 VS Code 服务器
pig stop vscode
# 重启 VS Code 服务器
pig restart vscode
# 查看日志
pig logs vscode
快捷键
故障排除
连接问题
# 检查服务状态
systemctl status code-server
# 检查端口绑定
ss -tlnp | grep 8080
# 查看日志
journalctl -u code-server -f
扩展问题
# 列出已安装扩展
code-server --list-extensions
# 重新安装扩展
code-server --uninstall-extension EXTENSION_ID
code-server --install-extension EXTENSION_ID
另请参阅
4.4 - Nginx
Piglet Run 的 Nginx Web 服务器配置。
概述
Piglet Run 使用 Nginx 作为所有服务的反向代理和 Web 服务器。
配置
主配置：/etc/nginx/nginx.conf
站点配置：/etc/nginx/conf.d/
默认配置
文件：/etc/nginx/conf.d/piglet.conf
# Piglet Run Nginx 配置
upstream vscode {
server 127.0.0.1 : 8080 ;
}
upstream jupyter {
server 127.0.0.1 : 8888 ;
}
upstream grafana {
server 127.0.0.1 : 3000 ;
}
server {
listen 80 ;
server_name _ ;
# 主页
location / {
root /www/piglet ;
index index.html ;
}
# VS Code 服务器
location /code {
proxy_pass http://vscode ;
proxy_http_version 1 .1 ;
proxy_set_header Upgrade $http_upgrade ;
proxy_set_header Connection "upgrade" ;
proxy_set_header Host $host ;
proxy_set_header X-Real-IP $remote_addr ;
}
# JupyterLab
location /jupyter {
proxy_pass http://jupyter ;
proxy_http_version 1 .1 ;
proxy_set_header Upgrade $http_upgrade ;
proxy_set_header Connection "upgrade" ;
proxy_set_header Host $host ;
}
# Grafana
location /ui {
proxy_pass http://grafana ;
proxy_set_header Host $host ;
proxy_set_header X-Real-IP $remote_addr ;
}
}
SSL 配置
文件：/etc/nginx/conf.d/piglet-ssl.conf
server {
listen 443 ssl http2 ;
server_name example.com ;
ssl_certificate /etc/piglet/ssl/cert.pem ;
ssl_certificate_key /etc/piglet/ssl/key.pem ;
ssl_protocols TLSv1.2 TLSv1.3 ;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256 ;
ssl_prefer_server_ciphers off ;
# ... location 块 ...
}
# HTTP 重定向到 HTTPS
server {
listen 80 ;
server_name example.com ;
return 301 https:// $server_name$request_uri ;
}
服务管理
# 启动 Nginx
pig start nginx
# 停止 Nginx
pig stop nginx
# 重启 Nginx
pig restart nginx
# 重载配置
pig reload nginx
# 测试配置
nginx -t
自定义站点配置
创建自定义站点配置：
cat > /etc/nginx/conf.d/mysite.conf << 'EOF'
server {
listen 80;
server_name mysite.example.com;
root /www/mysite;
index index.html;
location / {
try_files $uri $uri/ =404;
}
}
EOF
nginx -t && systemctl reload nginx
代理配置
WebSocket 支持
location /ws {
proxy_pass http://backend ;
proxy_http_version 1 .1 ;
proxy_set_header Upgrade $http_upgrade ;
proxy_set_header Connection "upgrade" ;
proxy_read_timeout 86400 ;
}
Node.js 应用
location /app {
proxy_pass http://127.0.0.1:3001 ;
proxy_set_header Host $host ;
proxy_set_header X-Real-IP $remote_addr ;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for ;
proxy_set_header X-Forwarded-Proto $scheme ;
}
日志
访问日志：/var/log/nginx/access.log
错误日志：/var/log/nginx/error.log
log_format main ' $remote_addr - $remote_user [ $time_local] " $request" '
' $status $body_bytes_sent " $http_referer" '
'" $http_user_agent" " $http_x_forwarded_for"' ;
access_log /var/log/nginx/access.log main ;
速率限制
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s ;
location /api {
limit_req zone=api burst=20 nodelay ;
proxy_pass http://backend ;
}
故障排除
# 测试配置
nginx -t
# 检查错误日志
tail -f /var/log/nginx/error.log
# 检查访问日志
tail -f /var/log/nginx/access.log
# 查看连接
ss -tlnp | grep nginx
另请参阅
4.5 - REST API
Piglet Run 的 REST API 参考。
概述
Piglet Run 提供 REST API，用于编程访问所有功能。
基础 URL
认证
API 密钥
curl -H "Authorization: Bearer YOUR_API_KEY" \
http://localhost/api/v1/status
生成 API 密钥
pig api key create --name mykey
端点
系统
获取状态
响应：
{
"status" : "healthy" ,
"version" : "2.5.0" ,
"uptime" : 86400 ,
"services" : {
"postgres" : "running" ,
"vscode" : "running" ,
"jupyter" : "running"
}
}
获取系统信息
响应：
{
"hostname" : "piglet" ,
"os" : "Ubuntu 22.04" ,
"cpu" : 4 ,
"memory" : "8GB" ,
"disk" : "100GB"
}
数据库
列出数据库
响应：
{
"databases" : [
{
"name" : "postgres" ,
"owner" : "dba" ,
"size" : "50MB"
}
]
}
创建数据库
POST /api/v1/databases
Content-Type: application/json
{
"name": "mydb",
"owner": "dba"
}
删除数据库
DELETE /api/v1/databases/{name}
备份
列出备份
响应：
{
"backups" : [
{
"id" : "backup-20240115" ,
"type" : "full" ,
"size" : "1.2GB" ,
"created_at" : "2024-01-15T02:00:00Z"
}
]
}
创建备份
POST /api/v1/backups
Content-Type: application/json
{
"type": "full",
"databases": ["postgres"]
}
恢复备份
POST /api/v1/backups/{id}/restore
Content-Type: application/json
{
"target_time": "2024-01-15T14:30:00Z"
}
服务
列出服务
响应：
{
"services" : [
{
"name" : "postgres" ,
"status" : "running" ,
"port" : 5432
},
{
"name" : "vscode" ,
"status" : "running" ,
"port" : 8080
}
]
}
控制服务
POST /api/v1/services/{name}/{action}
操作：start、stop、restart
快照
列出快照
创建快照
POST /api/v1/snapshots
Content-Type: application/json
{
"name": "snap-20240115",
"description": "升级前"
}
恢复快照
POST /api/v1/snapshots/{name}/restore
用户
列出用户
创建用户
POST /api/v1/users
Content-Type: application/json
{
"username": "newuser",
"password": "secure_password",
"databases": ["mydb"]
}
错误响应
{
"error" : {
"code" : "NOT_FOUND" ,
"message" : "数据库未找到" ,
"details" : {
"database" : "nonexistent"
}
}
}
错误代码
速率限制
响应头：
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200
SDK 示例
Python
import requests
api_key = "YOUR_API_KEY"
base_url = "http://localhost/api/v1"
headers = { "Authorization" : f "Bearer { api_key } " }
# 获取状态
response = requests . get ( f " { base_url } /status" , headers = headers )
print ( response . json ())
# 创建数据库
response = requests . post (
f " { base_url } /databases" ,
headers = headers ,
json = { "name" : "mydb" , "owner" : "dba" }
)
JavaScript
const apiKey = "YOUR_API_KEY" ;
const baseUrl = "http://localhost/api/v1" ;
// 获取状态
fetch ( ` ${ baseUrl } /status` , {
headers : { Authorization : `Bearer ${ apiKey } ` }
})
. then ( res => res . json ())
. then ( data => console . log ( data ));
另请参阅
5 - 任务
面向目标的操作指南，如备份、恢复、部署等具体任务。
任务 文档提供面向目标的具体操作指南。
如何使用
每个任务指南专注于完成一个具体目标：
问题导向 ：从你想要实现的目标出发逐步操作 ：清晰的步骤说明实战场景 ：真实世界的应用场景
主题
5.1 - 备份
了解如何在 Piglet Run 中备份数据库和文件。
概述
Piglet Run 提供多种备份方式来保护您的数据：
数据库备份 ：PostgreSQL 全量和增量备份文件备份 ：用户文件和配置快照 ：完整系统状态捕获
快速备份
使用单个命令创建完整备份：
备份数据库
全量数据库备份
增量备份
pig backup db --incremental
备份指定数据库
备份文件
备份用户文件
备份配置
定时备份
在 /etc/piglet/backup.yml 中配置自动备份：
backup :
schedule : "0 2 * * *" # 每天凌晨 2 点
retention : 7 # 保留 7 天
type : incremental
备份存储
备份存储位置：
下一步
5.2 - 恢复
了解如何从备份或快照恢复数据库和文件。
概述
Piglet Run 支持多种恢复场景：
时间点恢复 ：恢复到任意时间点全量恢复 ：从完整备份恢复选择性恢复 ：恢复特定数据库或文件
快速恢复
从最新备份恢复：
恢复数据库
列出可用备份
恢复全量备份
pig restore db --backup 2024-01-15
时间点恢复
pig restore db --time "2024-01-15 14:30:00"
恢复指定数据库
pig restore db mydb --backup 2024-01-15
恢复文件
恢复所有文件
pig restore files --backup 2024-01-15
恢复指定目录
pig restore files /home/dba/projects --backup 2024-01-15
从快照恢复
pig snapshot restore snap-20240115
验证
恢复后验证数据完整性：
pig verify db
pig verify files
下一步
5.3 - 克隆
了解如何在 Piglet Run 中克隆数据库和环境。
概述
克隆允许您创建以下内容的精确副本：
数据库 ：为测试或开发克隆数据库环境 ：克隆整个 Piglet Run 实例仅结构 ：克隆结构而不包含数据
快速克隆
即时克隆数据库：
pig clone db mydb mydb_copy
克隆数据库
完整克隆
pig clone db production development
仅结构
pig clone db production development --schema-only
带数据过滤的克隆
pig clone db production development --filter "created_at > '2024-01-01'"
克隆环境
创建环境克隆
pig clone env --name staging
克隆到远程服务器
pig clone env --target user@remote-server
从快照克隆
pig clone snapshot snap-20240115 --name dev-clone
克隆选项
使用场景
开发 ：克隆生产环境用于本地开发测试 ：创建隔离的测试环境分析 ：克隆用于报表而不影响生产环境
下一步
5.4 - 部署
了解如何在 Piglet Run 上部署 Web 应用。
概述
Piglet Run 支持部署多种 Web 应用：
静态站点 ：HTML、CSS、JavaScriptNode.js ：Express、Next.js、ReactPython ：Flask、Django、FastAPIPHP ：Laravel、WordPress
快速部署
部署静态站点：
部署静态站点
从本地目录
pig deploy ./dist --name my-site
从 Git 仓库
pig deploy https://github.com/user/repo --name my-site
部署 Node.js 应用
基本部署
cd my-node-app
pig deploy --type nodejs
自定义端口
pig deploy --type nodejs --port 3000
配置
在项目中创建 piglet.yml：
type : nodejs
entry : server.js
port : 3000
env :
NODE_ENV : production
部署 Python 应用
Flask 应用
pig deploy --type python --framework flask
Django 应用
pig deploy --type python --framework django
部署管理
列出部署
查看日志
重启应用
pig deploy restart my-site
移除部署
pig deploy remove my-site
下一步
5.5 - SSL
了解如何配置 SSL 证书以启用安全的 HTTPS 连接。
概述
Piglet Run 支持多种 SSL 证书选项：
Let’s Encrypt ：免费自动证书自签名 ：用于开发和测试自定义 ：使用您自己的证书
快速设置
使用 Let’s Encrypt 启用 SSL：
pig ssl enable --domain example.com
Let’s Encrypt 证书
为域名启用
多个域名
pig ssl letsencrypt --domain example.com --domain www.example.com
通配符证书
pig ssl letsencrypt --domain "*.example.com" --dns cloudflare
自签名证书
生成自签名证书
pig ssl self-signed --domain localhost
用于开发
pig ssl self-signed --domain dev.local --days 365
自定义证书
安装自定义证书
pig ssl install --cert /path/to/cert.pem --key /path/to/key.pem
包含证书链
pig ssl install \
--cert /path/to/cert.pem \
--key /path/to/key.pem \
--chain /path/to/chain.pem
证书管理
查看证书
检查过期时间
续期证书
配置
/etc/piglet/ssl.yml 中的 SSL 设置：
下一步
5.6 - 域名
了解如何为 Piglet Run 服务设置自定义域名。
概述
为以下内容配置自定义域名：
主应用 ：您的主域名子域名 ：服务专用子域名多域名 ：支持多个域名
快速设置
添加自定义域名：
pig domain add example.com
DNS 配置
所需 DNS 记录
将您的域名指向 Piglet Run：
使用 Cloudflare
pig domain add example.com --dns cloudflare --api-key YOUR_API_KEY
添加自定义域名
主域名
pig domain add example.com --primary
服务子域名
pig domain add code.example.com --service vscode
pig domain add jupyter.example.com --service jupyter
域名管理
列出域名
移除域名
pig domain remove old-domain.com
设置主域名
pig domain primary example.com
配置
/etc/piglet/domains.yml 中的域名设置：
domains :
primary : example.com
aliases :
- www.example.com
services :
vscode : code.example.com
jupyter : jupyter.example.com
grafana : monitor.example.com
验证域名
检查域名配置：
pig domain verify example.com
下一步
5.7 - 扩容
了解如何扩展或缩减 Piglet Run 资源。
概述
Piglet Run 支持扩展：
数据库 ：调整 PostgreSQL 资源存储 ：扩展磁盘容量服务 ：扩展服务资源
快速扩容
扩展数据库资源：
pig scale db --cpu 4 --memory 8G
扩展数据库
增加资源
pig scale db --cpu 4 --memory 16G
调整连接限制
pig scale db --max-connections 200
配置共享缓冲区
pig scale db --shared-buffers 4G
扩展存储
扩展磁盘
pig scale storage --size 100G
添加存储卷
pig scale storage add --mount /data/extra --size 50G
扩展服务
VS Code 服务器
pig scale service vscode --memory 4G
JupyterLab
pig scale service jupyter --memory 8G
资源限制
查看当前资源分配：
示例输出：
服务 CPU 内存 存储
--------- ---- ------ -------
PostgreSQL 2 4G 20G
VS Code 1 2G -
Jupyter 1 2G -
Nginx 0.5 512M -
配置
/etc/piglet/resources.yml 中的扩展设置：
resources :
postgres :
cpu : 2
memory : 4G
storage : 20G
vscode :
cpu : 1
memory : 2G
jupyter :
cpu : 1
memory : 2G
最佳实践
扩展前监控资源使用情况
逐步扩展以避免中断
先在开发环境测试更改
下一步
5.8 - 迁移
了解如何从其他系统迁移数据到 Piglet Run。
概述
Piglet Run 支持从以下系统迁移：
其他 PostgreSQL ：从现有 PostgreSQL 实例迁移MySQL/MariaDB ：从 MySQL 转换并迁移云数据库 ：AWS RDS、Google Cloud SQL、Azure Database文件 ：从 SQL 转储或 CSV 文件导入
快速迁移
从另一个 PostgreSQL 迁移：
pig migrate postgres://user:pass@source-host/dbname
从 PostgreSQL 迁移
直接连接
pig migrate pg \
--host source.example.com \
--port 5432 \
--user migrate_user \
--database production
从 pg_dump 文件
pig migrate import backup.sql
仅结构
pig migrate pg --host source.example.com --schema-only
从 MySQL 迁移
直接迁移
pig migrate mysql \
--host mysql.example.com \
--user migrate_user \
--database myapp
带类型映射
pig migrate mysql --host source --type-map mysql-to-pg.yml
从云迁移
AWS RDS
pig migrate rds \
--instance mydb-instance \
--region us-west-2 \
--profile aws-profile
Google Cloud SQL
pig migrate cloudsql \
--instance myproject:region:instance \
--credentials /path/to/credentials.json
导入文件
SQL 转储
pig migrate import dump.sql --database mydb
CSV 文件
pig migrate csv data.csv --table users --database mydb
多个 CSV 文件
pig migrate csv ./data/ --database mydb
迁移选项
验证
验证迁移：
pig migrate verify --source postgres://source/db --target postgres://target/db
下一步
5.9 - 监控
了解如何为 Piglet Run 实例设置告警和监控。
概述
Piglet Run 包含全面的监控功能：
Grafana 仪表盘 ：可视化监控告警 ：可配置的告警指标 ：基于 Prometheus 的指标日志 ：集中式日志
快速设置
访问监控仪表盘：
pig monitor open
# 在 http://<ip>/ui 打开 Grafana
Grafana 仪表盘
可用仪表盘
访问仪表盘
# 默认凭据
URL: http://<ip>/ui
用户: admin
密码: ( 安装时显示)
设置告警
启用邮件告警
启用 Slack 告警
pig alert slack --webhook https://hooks.slack.com/services/...
启用 Webhook 告警
pig alert webhook --url https://api.example.com/alerts
告警规则
查看告警规则
添加自定义告警
pig alert add \
--name "High CPU" \
--condition "cpu_usage > 80" \
--duration 5m \
--severity warning
默认告警
配置
/etc/piglet/alerts.yml 中的告警配置：
alerts :
email :
enabled : true
to : [email protected]
smtp :
host : smtp.example.com
port : 587
slack :
enabled : false
webhook : ""
rules :
- name : high_cpu
expr : cpu_usage > 80
for : 5m
severity : warning
查看日志
# 所有服务日志
pig logs
# 特定服务
pig logs postgres
pig logs nginx
下一步
5.10 - 升级
了解如何升级 Piglet Run 安装。
概述
Piglet Run 升级包括：
小版本更新 ：Bug 修复和安全补丁大版本升级 ：新功能和改进PostgreSQL 升级 ：数据库版本升级
快速升级
升级到最新版本：
检查更新
查看当前版本
检查可用更新
执行升级
标准升级
升级到特定版本
pig upgrade --version 2.5.0
试运行
升级 PostgreSQL
检查兼容版本
升级数据库版本
pig upgrade pg --version 17
带完整备份
pig upgrade pg --version 17 --backup
升级前准备
创建备份
检查兼容性
pig upgrade check --verbose
查看发布说明
回滚
如果升级失败：
从备份恢复
pig restore --backup pre-upgrade
回滚到之前版本
升级历史
查看升级历史：
示例输出：
版本 日期 状态
------- ---------- -------
2.5.0 2024-01-15 当前
2.4.1 2024-01-01 之前
2.4.0 2023-12-15 已归档
配置
/etc/piglet/upgrade.yml 中的升级设置：
upgrade :
auto_backup : true
notify : true
channel : stable # stable, beta, nightly
下一步