chore: back up Pi environment
This commit is contained in:
204
PI-BACKUP-README.md
Normal file
204
PI-BACKUP-README.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# Бэкап среды Pi Coding Agent
|
||||
|
||||
Файлы рядом:
|
||||
|
||||
- `pi-env-backup.sh` — скрипт создания, проверки и восстановления бэкапа;
|
||||
- `PI-BACKUP-README.md` — эта инструкция.
|
||||
|
||||
Скрипт переносит именно среду Pi, а не проекты.
|
||||
|
||||
## Что сохраняется
|
||||
|
||||
- `~/.pi/agent/settings.json` — глобальные настройки Pi;
|
||||
- `~/.pi/agent/auth.json` — авторизация и API-ключи;
|
||||
- `~/.pi/agent/mcp.json` и `~/.pi/agent/mcp-oauth/` — MCP;
|
||||
- `~/.pi/agent/models.json`, `models.yml` — настройки моделей;
|
||||
- `~/.pi/agent/extensions/`, `skills/`, `npm/`, `git/` — плагины и Pi packages;
|
||||
- `~/.pi/agent/AGENTS.md`, `keybindings.json`, `trust.json`;
|
||||
- `~/.pi/agent/sessions/` — история сессий (**по умолчанию не сохраняется**);
|
||||
- `~/.pi/agent/pi-hermes-memory/` и `projects-memory/` — память;
|
||||
- `~/.pi/context-mode/` — индексы и локальные данные context-mode (**по умолчанию не сохраняются**);
|
||||
- `~/.pi/agent/ayu/checkpoints/` — checkpoints (**по умолчанию не сохраняются**);
|
||||
- `~/.agents/` — дополнительные пользовательские skills;
|
||||
- `~/.pi/local-docs/`, если каталог существует.
|
||||
|
||||
Архив также содержит манифест версий установленных программ и копию самого скрипта для восстановления.
|
||||
|
||||
> **Внимание:** архив содержит секреты из `auth.json`, MCP OAuth и других конфигов. Не выкладывай его в публичное хранилище.
|
||||
|
||||
---
|
||||
|
||||
## 1. Создать полный бэкап
|
||||
|
||||
Закрой все запущенные Pi:
|
||||
|
||||
```bash
|
||||
pkill -f pi-coding-agent || true
|
||||
```
|
||||
|
||||
Создай каталог для архивов и запусти:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/pi-backups
|
||||
cd /home/smog/main
|
||||
./pi-env-backup.sh backup ~/pi-backups
|
||||
```
|
||||
|
||||
Или сразу на внешний диск:
|
||||
|
||||
```bash
|
||||
./pi-env-backup.sh backup /media/smog/SSD
|
||||
```
|
||||
|
||||
На выходе будут два файла:
|
||||
|
||||
```text
|
||||
pi-backup-YYYYMMDD-HHMMSS.tar.zst
|
||||
pi-backup-YYYYMMDD-HHMMSS.tar.zst.sha256
|
||||
```
|
||||
|
||||
По умолчанию архив НЕ включает `ayu/checkpoints`, историю Pi-сессий и `context-mode`: это кэш/история, не нужные для работы плагинов. Поэтому архив обычно будет порядка **0.8–1 ГБ до сжатия** и ориентировочно **0.4–0.8 ГБ после zstd**. Точный размер скрипт покажет в конце.
|
||||
|
||||
---
|
||||
|
||||
## 2. Проверить архив
|
||||
|
||||
Посмотреть содержимое:
|
||||
|
||||
```bash
|
||||
./pi-env-backup.sh list ~/pi-backups/pi-backup-*.tar.zst
|
||||
```
|
||||
|
||||
Проверить контрольную сумму:
|
||||
|
||||
```bash
|
||||
sha256sum -c ~/pi-backups/pi-backup-*.tar.zst.sha256
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Дополнительные варианты бэкапа
|
||||
|
||||
По умолчанию уже создаётся облегчённый бэкап: плагины, настройки, auth, MCP, memory и skills сохраняются, а checkpoints/сессии/context-mode — нет.
|
||||
|
||||
Включить историю старых Pi-сессий:
|
||||
|
||||
```bash
|
||||
PI_BACKUP_INCLUDE_SESSIONS=1 \
|
||||
./pi-env-backup.sh backup ~/pi-backups
|
||||
```
|
||||
|
||||
Включить context-mode индексы:
|
||||
|
||||
```bash
|
||||
PI_BACKUP_INCLUDE_CONTEXT=1 \
|
||||
./pi-env-backup.sh backup ~/pi-backups
|
||||
```
|
||||
|
||||
Включить старые ayu checkpoints (обычно не нужно):
|
||||
|
||||
```bash
|
||||
PI_BACKUP_INCLUDE_AYU=1 \
|
||||
./pi-env-backup.sh backup ~/pi-backups
|
||||
```
|
||||
|
||||
Включить всё сразу:
|
||||
|
||||
```bash
|
||||
PI_BACKUP_INCLUDE_SESSIONS=1 \
|
||||
PI_BACKUP_INCLUDE_CONTEXT=1 \
|
||||
PI_BACKUP_INCLUDE_AYU=1 \
|
||||
./pi-env-backup.sh backup ~/pi-backups
|
||||
```
|
||||
|
||||
Настройки, auth, MCP, memory, плагины и skills сохраняются во всех вариантах.
|
||||
|
||||
---
|
||||
|
||||
## 4. Восстановить на ноутбуке в WSL
|
||||
|
||||
На ноутбуке установи базовые инструменты:
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y zstd nodejs npm
|
||||
```
|
||||
|
||||
Передай на ноутбук архив и `.sha256` рядом с ним. Проверь архив:
|
||||
|
||||
```bash
|
||||
sha256sum -c pi-backup-YYYYMMDD-HHMMSS.tar.zst.sha256
|
||||
```
|
||||
|
||||
Если бэкап был скачан из этого Git-репозитория, сначала забери LFS-файлы и собери архив из частей:
|
||||
|
||||
```bash
|
||||
git lfs pull
|
||||
chmod +x assemble-pi-backup.sh
|
||||
./assemble-pi-backup.sh pi-backup-YYYYMMDD-HHMMSS.tar.zst
|
||||
```
|
||||
|
||||
Скрипт соберёт `*.part-*` в исходный `.tar.zst` и сразу проверит контрольную сумму.
|
||||
|
||||
Извлеки встроенную копию restore-скрипта:
|
||||
|
||||
```bash
|
||||
zstd -dc pi-backup-YYYYMMDD-HHMMSS.tar.zst \
|
||||
| tar -xOf - meta/pi-env-backup.sh > pi-env-restore.sh
|
||||
|
||||
chmod +x pi-env-restore.sh
|
||||
```
|
||||
|
||||
Запусти восстановление:
|
||||
|
||||
```bash
|
||||
./pi-env-restore.sh restore pi-backup-YYYYMMDD-HHMMSS.tar.zst
|
||||
```
|
||||
|
||||
Скрипт распакует Pi-среду в домашний каталог текущего пользователя WSL. Если `~/.pi/agent` уже существует, он сначала переименует его в каталог вида:
|
||||
|
||||
```text
|
||||
~/.pi/agent.before-restore-YYYYMMDD-HHMMSS
|
||||
```
|
||||
|
||||
Если Pi ещё не установлен, скрипт установит его так:
|
||||
|
||||
```bash
|
||||
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Проверить восстановление
|
||||
|
||||
```bash
|
||||
pi --version
|
||||
pi list
|
||||
```
|
||||
|
||||
Запусти Pi в одном из своих проектов:
|
||||
|
||||
```bash
|
||||
cd ~/main/имя-проекта
|
||||
pi
|
||||
```
|
||||
|
||||
Проверь:
|
||||
|
||||
```text
|
||||
/mcp
|
||||
/login # только если OAuth/API-ключ не восстановился
|
||||
```
|
||||
|
||||
Если какие-то внешние программы нужны плагинам, установи их отдельно: `bun`, `pnpm`, `uv`, `gh`, `jj`, `docker` и т.п. Их бинарники не копируются архивом — архив переносит состояние Pi и список обнаруженных инструментов в `meta/MANIFEST.txt`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Важные замечания
|
||||
|
||||
1. Перед созданием архива закрывай Pi, чтобы не копировать активные session/SQLite-файлы.
|
||||
2. Не используй `PI_BACKUP_ALLOW_RUNNING=1`, если нет особой причины.
|
||||
3. Архив — это переносимая копия пользовательской Pi-среды, но не копия всей ОС.
|
||||
4. Проекты не входят в этот архив: они уже есть в WSL отдельно.
|
||||
5. Project-local файлы вроде `project/.pi/`, `project/.agents/`, `AGENTS.md` и `CLAUDE.md` не входят в глобальный архив, если находятся внутри проектов. Их нужно хранить вместе с проектами или отдельно скопировать.
|
||||
6. Некоторые OAuth-провайдеры могут потребовать повторный `/login` на новом ноутбуке.
|
||||
Reference in New Issue
Block a user