跳转到主要内容

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

返回本页常规视图.

参考手册

Piglet 配置、CLI、API、Portal 与编辑器的准确说明。

当你已经知道要找什么，需要确认准确的命令、参数、路径或端点时，请使用参考手册。

下面分别提供 Piglet 配置、CLI、API、Nginx Portal 与 VS Code 的详细说明。

1 - CLI

Piglet Run 命令行接口参考。

概述

pig CLI 提供对 Piglet Run 实例的完整控制。

安装

CLI 随 Piglet Run 自动安装。验证安装：

pig --version

全局选项

选项 描述
--help, -h 显示帮助
--version, -v 显示版本
--config, -c 配置文件路径
--verbose 详细输出
--quiet, -q 静默模式
--json JSON 输出

命令

状态命令 

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      # 获取配置

环境变量

变量 描述
PIG_HOME Piglet Run 主目录
PIG_CONFIG 配置文件路径
PIG_LOG_LEVEL 日志级别 (debug, info, warn, error)

配置文件

默认位置：/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

退出码

代码 描述
0 成功
1 一般错误
2 参数无效
3 服务未找到
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

另请参阅

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

预装扩展

扩展 描述
ms-python.python Python 语言支持
ms-toolsai.jupyter Jupyter 笔记本支持
rust-lang.rust-analyzer Rust 语言支持
golang.go Go 语言支持
dbaeumer.vscode-eslint JavaScript 代码检查
esbenp.prettier-vscode 代码格式化
mtxr.sqltools SQL 工具

安装扩展

通过 CLI 

code-server --install-extension ms-python.python

通过设置

  1. 在浏览器中打开 VS Code
  2. 进入扩展 (Ctrl+Shift+X)
  3. 搜索并安装扩展

设置

默认设置位置：/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

快捷键

快捷键 操作
Ctrl+Shift+P 命令面板
Ctrl+P 快速打开文件
Ctrl+Shift+E 资源管理器
Ctrl+Shift+F 搜索
Ctrl+`` 终端
Ctrl+Shift+G Git

故障排除

连接问题 

# 检查服务状态
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 - 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

另请参阅

5 - REST API

Piglet Run 的 REST API 参考。

概述

Piglet Run 提供 REST API，用于编程访问所有功能。

基础 URL 

http://<ip>/api/v1

认证

API 密钥 

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost/api/v1/status

生成 API 密钥 

pig api key create --name mykey

端点

系统

获取状态 

GET /api/v1/status

响应：

{
  "status": "healthy",
  "version": "2.5.0",
  "uptime": 86400,
  "services": {
    "postgres": "running",
    "vscode": "running",
    "jupyter": "running"
  }
}

获取系统信息 

GET /api/v1/system

响应：

{
  "hostname": "piglet",
  "os": "Ubuntu 22.04",
  "cpu": 4,
  "memory": "8GB",
  "disk": "100GB"
}

数据库

列出数据库 

GET /api/v1/databases

响应：

{
  "databases": [
    {
      "name": "postgres",
      "owner": "dba",
      "size": "50MB"
    }
  ]
}

创建数据库 

POST /api/v1/databases
Content-Type: application/json

{
  "name": "mydb",
  "owner": "dba"
}

删除数据库 

DELETE /api/v1/databases/{name}

备份

列出备份 

GET /api/v1/backups

响应：

{
  "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"
}

服务

列出服务 

GET /api/v1/services

响应：

{
  "services": [
    {
      "name": "postgres",
      "status": "running",
      "port": 5432
    },
    {
      "name": "vscode",
      "status": "running",
      "port": 8080
    }
  ]
}

控制服务 

POST /api/v1/services/{name}/{action}

操作：start、stop、restart

快照

列出快照 

GET /api/v1/snapshots

创建快照 

POST /api/v1/snapshots
Content-Type: application/json

{
  "name": "snap-20240115",
  "description": "升级前"
}

恢复快照 

POST /api/v1/snapshots/{name}/restore

用户

列出用户 

GET /api/v1/users

创建用户 

POST /api/v1/users
Content-Type: application/json

{
  "username": "newuser",
  "password": "secure_password",
  "databases": ["mydb"]
}

错误响应 

{
  "error": {
    "code": "NOT_FOUND",
    "message": "数据库未找到",
    "details": {
      "database": "nonexistent"
    }
  }
}

错误代码

代码 HTTP 状态 描述
UNAUTHORIZED 401 无效或缺少 API 密钥
FORBIDDEN 403 权限不足
NOT_FOUND 404 资源未找到
CONFLICT 409 资源已存在
INTERNAL_ERROR 500 服务器错误

速率限制

  • 默认：每分钟 100 个请求
  • 突发：20 个请求

响应头：

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));

另请参阅