NotBigGhost/ForbiddenStarsApp
1
1
Fork 0
Code Issues 7 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Документация: сверка README и deploy/*.md с кодом

Browse Source 
- README: test без порта на хосте (только через домен, Secure-cookie), прод из реестра
  (build-push + docker compose up -d), лимиты перебора и регистраций, dev_admin.py в списке
  dev-кода, структура репозитория, раздел о бэкапах, отличия test от prod; отмечены
  известные проблемы (#69, #71, #72, #73).
- deploy/README.md: три сервиса (app + tunnel + backup), источники ключа туннеля для Pi,
  test и dev-туннеля, слот 9000 у временного прода.
- deploy/pi/README.md: контейнер backup, fail-fast по секретам, ADMIN_PASSWORD только при
  первом создании админа (#73), порядок обновления.
- deploy/vps/README.md: туннель-контейнер вместо autossh, сниппет (edge), единые имена
  файлов в примере сборки сертификатов, дописывать authorized_keys через >>.
- deploy/backup/README.md: первый бэкап на новом Pi, выбор снимка с данными при
  восстановлении (#74), метка keep, --no-pre-restore, служебные команды, причины unhealthy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqSoRj99iwVEH5U5fnZgsd
This commit is contained in:
NotBigGhost
2026-09-14 20:06:54 +03:00
co-authored by Claude Opus 5
parent 7579ca2d35
commit 63fd90e017
5 changed files with 206 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files
deploy/README.md
+24 -16
View File
@@ -18,33 +18,41 @@ HTTPS твоими сертификатами и проксирует трафи
└───────────────────────────────────────────────────┘
```
- **PROD** — Pi. `docker compose up -d` поднимает два сервиса: `app` + `tunnel`. У `app`
**портов на хост нет** — наружу его выставляет только туннель-контейнер
(`ssh -R 9000:app:8000` к VPS). Постоянно, Docker сам переподключает. См. [`pi/`](pi/README.md).
- **TEST** — ПК. То же самое: `docker compose -f docker-compose.test.yml up` поднимает
`app` + `tunnel` (`ssh -R 9001:app:8000`). Портов на хост нет — тест виден только на
`forbidden-stars.ru`. Обычно запускается лаунчером при `APP_ENV=test`.
- **PROD** — Pi. `docker compose up -d` поднимает три сервиса: `app` + `tunnel` + `backup`
(образы из Gitea-реестра, собираются на ПК `scripts/build-push.ps1`). У `app` **портов на
хост нет** — наружу его выставляет только туннель-контейнер (`ssh -R 9000:app:8000` к VPS).
Работает постоянно: при обрыве `ssh` завершается, и Docker перезапускает контейнер
(`restart: unless-stopped`). См. [`pi/`](pi/README.md).
- **TEST** — ПК. То же самое: `docker compose -f docker-compose.test.yml up` собирает образы
локально и поднимает `app` + `tunnel` (`ssh -R 9001:app:8000`) + `backup` (без расписания и
без VPS). Портов на хост нет — тест виден только на `forbidden-stars.ru`. Обычно
запускается лаунчером при `APP_ENV=test`.
- **DEV** — ПК, нативно (`uvicorn`+`vite`). По умолчанию только на localhost; при
`LOCAL_PUBLIC=vps` лаунчер (`run.ps1`) дополнительно поднимает SSH-туннель с ПК
`LOCAL_PUBLIC=vps` лаунчер (`run.ps1` / `run.sh`) дополнительно поднимает SSH-туннель с ПК
(`ssh -R 9001:localhost:5173`) → дев виден на `forbidden-stars.ru`.
- DEV и TEST делят слот **9001** (`forbidden-stars.ru`) → поднимай что-то **одно за раз**.
PROD на отдельном слоте **9000** (`forbiddenstars.ru`) — работает независимо.
Временный прод на ПК (`docker-compose.temp.yml`) тоже занимает **9000** — одновременно с Pi нельзя.
Ключ туннеля — **`deploy/tunnel/id_tunnel`** (приватный, в git не идёт). Его публичную
часть добавь в `authorized_keys` пользователя `tunnel` на VPS. Один и тот же ключ годится
для контейнерного туннеля (Pi/ПК) и для dev-туннеля `run.ps1`.
Ключи туннеля (приватные, в git не идут; публичные части — в `authorized_keys` пользователя
`tunnel` на VPS):
- **Pi** — `TUNNEL_KEY_B64` (base64 приватного ключа) в `.env`; файла ключа на Pi нет.
- **ПК, test и временный прод** — файл `deploy/tunnel/id_tunnel`, монтируется в туннель-контейнер.
- **ПК, dev** — `run.ps1`/`run.sh` зовут системный `ssh` без `-i`, то есть с ключом по
умолчанию из `~/.ssh`. Он должен быть в `authorized_keys` (можно тем же, что `id_tunnel`).
Настройка по шагам:
1. **VPS** — [`vps/README.md`](vps/README.md): Caddy, файрвол, пользователь `tunnel`, сертификаты, `Caddyfile`.
2. **Pi (прод)** — [`pi/README.md`](pi/README.md): ключ в `deploy/tunnel/id_tunnel`, `.env`, `docker compose up -d`.
3. **ПК (dev/test)** — тот же ключ в `deploy/tunnel/id_tunnel` (для test-контейнера) и/или
ключ по умолчанию для dev (`run.ps1`); pubkey — в `authorized_keys` у `tunnel@VPS`.
2. **Pi (прод)** — [`pi/README.md`](pi/README.md): ключ туннеля в `TUNNEL_KEY_B64`, `.env`, `docker compose up -d`.
3. **ПК (dev/test)** — ключ в `deploy/tunnel/id_tunnel` (для test-контейнера) и/или ключ по
умолчанию в `~/.ssh` (для dev-туннеля); pubkey — в `authorized_keys` у `tunnel@VPS`.
4. **Бэкапы** — [`backup/README.md`](backup/README.md): контейнер `backup` (restic) делает
снимки на Pi и на VPS (`fsbackup@VPS`, только SFTP), скрипты ПК скачивают их и проверяют
восстановление на тест-клоне.
Секреты не в git: сертификаты/ключи (`*.pem`, `*.key`, `id_tunnel*`) живут на VPS/Pi/ПК,
в репозитории только `Caddyfile`, `deploy/tunnel/` (образ туннеля) и шаблоны.
Секреты не в git: сертификаты/ключи (`*.pem`, `*.key`, `id_tunnel*`, `id_backup*`) живут на
VPS/Pi/ПК, в репозитории только `Caddyfile`, страница-заглушка, образы `deploy/tunnel/` и
`deploy/backup/` и шаблоны.
> Telegram-вход требует HTTPS-домен: у BotFather `/setdomain` укажи оба домена
> (`forbiddenstars.ru` и `forbidden-stars.ru`).
@@ -62,6 +70,6 @@ HTTPS твоими сертификатами и проксирует трафи
внешний брокер (Redis pub/sub), иначе события увидит только тот воркер, что принял мутацию.
SSE-поток сам не закрывается, поэтому uvicorn запускается с `--timeout-graceful-shutdown`
(`entrypoint.sh`, `run.*`). Без него остановка ждёт закрытия всех соединений: в dev
(10 с в `entrypoint.sh`, 2 с в `run.*`). Без него остановка ждёт закрытия всех соединений: в dev
`--reload` при открытой вкладке висит вечно, в контейнере остановку обрывает только SIGKILL
по `stop_grace_period`.
deploy/backup/README.md
+31 -14
View File
@@ -55,8 +55,8 @@
4. удаляет старые снимки по правилам хранения;
5. проверяет, что репозитории целы.
Раз в неделю (воскресенье, 05:30) дополнительно читает часть сохранённых данных и убеждается,
что последний снимок действительно восстанавливается.
Раз в неделю (воскресенье, 05:30) дополнительно читает часть сохранённых данных (10 %) и
убеждается, что БД из последнего снимка извлекается и проходит проверку целостности.
**Словарь**
@@ -646,7 +646,7 @@
| `Игроков` / `Партий` | сколько игроков и партий было в БД в этот момент — по ним легко найти «до поломки» |
| `Размер` | полный объём данных снимка |
| `Прирост` | сколько места снимок реально добавил в репозиторий |
| `Метки` | `scheduled` — по расписанию, `manual` — вручную, `pre-restore` — страховочный, прочие — имя, данное вручную |
| `Метки` | `scheduled` — по расписанию, `manual` — вручную, `pre-restore` — страховочный, `keep` + имя — именованный снимок (`run --tag имя`) |
Если локальный репозиторий повреждён или пуст, смотрите копию на VPS:
`docker compose exec backup fs-backup list vps`.
@@ -737,30 +737,44 @@
```
3. Дождитесь, пока приложение создаст пустую БД (`docker compose ps` → `app` `(healthy)`).
В журнале бэкапа это нормально (`docker compose logs backup`):
Контейнер `backup` стартует одновременно с `app` и сразу пробует сделать первый бэкап. В его
журнале (`docker compose logs backup`) нормально увидеть одно из двух:
```
В БД нет ни игроков, ни партий, а последний снимок в репозитории vps — с данными.
Похоже на новый или очищенный сервер: бэкап НЕ сделан, чтобы пустые данные не вытеснили историю.
```
- если `backup` успел раньше, чем `app` создал БД:
Это защита: пустой новый Pi не перезапишет историю на VPS.
```
ОШИБКА: БД /fs-db/forbidden_stars.db не найдена — приложение ещё ни разу не запускалось?
Первый бэкап не удался — следующая попытка по расписанию.
```
4. Посмотрите снимки на VPS и выберите нужный (обычно самый свежий):
- если БД уже была:
```
В БД нет ни игроков, ни партий, а последний снимок в репозитории vps — с данными.
Похоже на новый или очищенный сервер: бэкап НЕ сделан, чтобы пустые данные не вытеснили историю.
```
Это защита: пустой новый Pi не перезапишет историю на VPS.
4. Посмотрите снимки на VPS и выберите нужный (обычно самый свежий **с данными**):
```bash
docker compose exec backup fs-backup list vps
```
5. Восстановите:
Проверьте, что у выбранного снимка в столбцах `Игроков`/`Партий` числа, а не `0` и не `?`.
Защита выше не распознаёт БД без таблиц: если первый бэкап попал ровно в момент создания
БД, в списке может появиться свежий снимок с `?` (задача #74). Такой снимок не выбирайте.
5. Восстановите, подставив ID из `list vps`:
```bash
docker compose stop app
docker compose exec backup fs-backup restore latest --repo vps --yes
docker compose exec backup fs-backup restore <ID> --repo vps --yes
docker compose start app
```
Вместо `latest` можно указать ID из `list vps`.
Если самый свежий снимок в `list vps` — с данными, вместо ID можно написать `latest`.
6. Проверьте сайт. Затем сделайте снимок вручную, чтобы локальная копия появилась сразу:
@@ -852,7 +866,7 @@ docker compose logs --tail 100 backup
| `снимок '…' не найден в репозитории` | опечатка в ID или снимок в другом репозитории | `fs-backup list` и `fs-backup list vps` |
| `service "backup" is not running` | контейнер не запущен | `docker compose up -d backup` |
| `permission denied while trying to connect to the Docker daemon socket` | пользователь Pi не в группе `docker` | `sudo usermod -aG docker $USER`, перезайти по SSH |
| `docker compose ps` → `backup` `unhealthy` | последний успешный бэкап старше `BACKUP_MAX_AGE_HOURS` | `docker compose exec backup fs-backup health` покажет причину, дальше по таблице |
| `docker compose ps` → `backup` `unhealthy` | последний успешный бэкап старше `BACKUP_MAX_AGE_HOURS`, успешных бэкапов ещё не было или не задан `BACKUP_PASSWORD` | `docker compose exec backup fs-backup health` покажет причину, дальше по таблице |
**Про `recover`.** Команда сама определяет, на каком этапе оборвалось восстановление:
- если замена успела пройти во всех томах — дочищает промежуточные папки, восстановленные
@@ -907,8 +921,11 @@ docker volume rm <имя тома>
| `export <ID\|latest> [--repo …]` | снимок в tar в stdout: `docker compose exec -T backup fs-backup export latest > fs.tar` |
| `restic <local\|vps> <аргументы>` | любая команда restic с настройками контейнера, например `restic vps stats` |
| `help` | краткая справка |
| `init`, `info`, `health`, `has-snapshots` | служебные: создать репозитории, данные снимка для скриптов ПК, healthcheck, проверка «есть ли снимки» при старте |
Без `--yes` команды `restore` и `import` только показывают, что собираются сделать.
Флаг `--no-pre-restore` у `restore`/`import` пропускает страховочный снимок — используйте,
только если текущие данные точно не нужны.
### Скрипт ПК
deploy/pi/README.md
+19 -6
View File
@@ -2,12 +2,13 @@
На Pi нужны только **ДВА файла**: `docker-compose.yml` и `.env`. Репозиторий, сборка и файл
ключа туннеля не нужны:
- образы (`app` + `tunnel`) тянутся из Gitea-реестра (`pull_policy: always`);
- образы (`app` + `tunnel` + `backup`) тянутся из Gitea-реестра (`pull_policy: always`);
- приватный ключ туннеля лежит в `.env` как `TUNNEL_KEY_B64` (base64).
`docker compose up` поднимает два контейнера: `app` (FastAPI+SPA, портов на хост нет) и
`tunnel` (`ssh -R 9000:app:8000` к VPS). Публичная точка — VPS, домен `forbiddenstars.ru`
(Pi за CGNAT — туннель стучится наружу сам).
`docker compose up` поднимает три контейнера: `app` (FastAPI+SPA, портов на хост нет),
`tunnel` (`ssh -R 9000:app:8000` к VPS, стартует после `healthy` у `app`) и `backup` (restic,
см. раздел «Бэкапы»). Публичная точка — VPS, домен `forbiddenstars.ru` (Pi за CGNAT — туннель
стучится наружу сам).
---
@@ -86,6 +87,14 @@ IMAGE_REGISTRY=gitea.arseniev.info/notbigghost # уже значение по
IMAGE_TAG=latest
```
`APP_ENV` (форсится в `production`) и `VPS_TUNNEL_PORT` (прод → 9000) не трогать.
Блок `BACKUP_*` можно оставить пустым: бэкапы включаются позже, по
[`deploy/backup/README.md`](../backup/README.md).
> В production приложение **не стартует**, если `SECRET_KEY` дефолтный или короче 32
> символов, а `ADMIN_PASSWORD` пустой или дефолтный (при `ADMIN_BOOTSTRAP_ENABLED=true`).
> `ADMIN_USERNAME`/`ADMIN_PASSWORD` применяются **только при первом создании** админа: если
> потом поменять их в `.env`, у существующего админа ничего не изменится, а штатной смены
> пароля админа на проде пока нет (задача #73).
## 4. Запуск
```bash
@@ -94,7 +103,8 @@ docker compose up -d # pull_policy: always → тянет обр
docker compose ps # app healthy → поднимется tunnel
docker compose logs -f tunnel # ждём строку: [tunnel] -R 9000:app:8000 -> tunnel@...
```
На старте контейнер сам применит миграции, засидит справочники и создаст админа из `.env`.
На старте контейнер сам применит миграции, засидит справочники и создаст админа из `.env`
(если админа ещё нет).
## 5. Проверка
- Открой `https://forbiddenstars.ru` — должно отдать приложение (не заглушку).
@@ -103,9 +113,12 @@ docker compose logs -f tunnel # ждём строку: [tunnel] -R 9000:a
## Обновление
```bash
# Pi: docker compose exec backup fs-backup run --tag before-update # по желанию, если бэкапы включены
# ПК: .\scripts\build-push.ps1
# Pi: docker compose up -d # always-pull подтянет свежий образ
# Pi: docker compose up -d # always-pull подтянет свежие образы
```
Если в новой версии менялся `docker-compose.yml` или `.env.example`, сначала скачайте
свежий `docker-compose.yml` (шаг 3) и допишите новые переменные в `.env`.
## Автозапуск после перезагрузки
Уже обеспечен: `systemctl enable docker` + `restart: unless-stopped`. После `sudo reboot`
deploy/vps/README.md
+14 -9
View File
@@ -4,8 +4,8 @@
для двух доменов и проксирует трафик в SSH reverse-туннели от Pi (прод) и ПК (dev/test).
```
forbiddenstars.ru → 127.0.0.1:9000 ← Pi (autossh, постоянно) PROD
forbidden-stars.ru → 127.0.0.1:9001 ← ПК (по требованию) DEV/TEST
forbiddenstars.ru → 127.0.0.1:9000 ← Pi (туннель-контейнер, постоянно) PROD
forbidden-stars.ru → 127.0.0.1:9001 ← ПК (контейнер test или ssh dev, по требованию) DEV/TEST
```
> Туннель `ssh -R` по умолчанию слушает на loopback VPS (127.0.0.1) — ровно туда смотрит
@@ -51,7 +51,9 @@ install -d -m 700 -o tunnel -g tunnel /home/tunnel/.ssh
install -m 600 -o tunnel -g tunnel /dev/null /home/tunnel/.ssh/authorized_keys
```
Публичные ключи Pi и ПК добавишь в `/home/tunnel/.ssh/authorized_keys` на шагах настройки
Pi (`deploy/pi/README.md`) и ПК (через `ssh-copy-id`).
Pi (`deploy/pi/README.md`) и ПК (`deploy/tunnel/id_tunnel.pub` и/или ключ по умолчанию из
`~/.ssh` для dev-туннеля). Ключи **дописывай** (`>>`), а не перезаписывай файл (`>`):
иначе туннель другого хоста перестанет пускать.
## 5. Сертификаты
@@ -67,11 +69,11 @@ Caddy читает **PEM** (текст с `-----BEGIN CERTIFICATE-----`). Рас
Удобно собрать прямо на VPS — залей свои файлы и склей:
```bash
mkdir -p /etc/caddy/certs/forbidden-stars.ru /root/certs-tmp
# с локальной машины (пример для домена forbidden-stars.ru):
mkdir -p /etc/caddy/certs/forbidden-stars.ru /etc/caddy/certs/forbiddenstars.ru /root/certs-tmp
# с локальной машины (пример для домена forbidden-stars.ru; имена файлов — свои):
scp forbidden-stars.crt intermediate.crt forbidden-stars.key root@186.246.51.17:/root/certs-tmp/
# на VPS — собрать fullchain (leaf + промежуточный) и положить ключ:
cat /root/certs-tmp/www_forbidden_stars_ru_2026_12_31.crt /root/certs-tmp/intermediate_pem_globalsign_ssl_dv_free_1.crt \
cat /root/certs-tmp/forbidden-stars.crt /root/certs-tmp/intermediate.crt \
> /etc/caddy/certs/forbidden-stars.ru/fullchain.pem
cp /root/certs-tmp/forbidden-stars.key /etc/caddy/certs/forbidden-stars.ru/privkey.pem
# то же для forbiddenstars.ru (свои crt/intermediate/key), затем права
@@ -96,13 +98,16 @@ scp deploy/vps/maintenance.html root@186.246.51.17:/etc/caddy/maintenance/mainte
caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy
```
> Заглушка живёт в сниппете `(offline)` Caddyfile: при ответе апстрима 502/503/504
> Caddy отдаёт `/etc/caddy/maintenance/maintenance.html` со статусом 503 и `Cache-Control: no-store`.
> Заглушка живёт в сниппете `(edge)` Caddyfile (там же security-заголовки и `no-store` для
> HTML): при ответе апстрима 502/503/504 Caddy отдаёт `/etc/caddy/maintenance/maintenance.html`
> со статусом 503 и `Cache-Control: no-store`. Для `/api/events` (SSE) у каждого домена
> отдельный `handle` без `encode` и с `flush_interval -1`.
> Правки текста/вида — в `deploy/vps/maintenance.html`, затем повтори `scp` (reload Caddy не нужен,
> файл читается на каждый запрос).
## 7. Проверка
1. Подними туннель прода на Pi (см. `deploy/pi/README.md`) и/или dev/test на ПК (`run.ps1` при `LOCAL_PUBLIC=vps`).
1. Подними туннель прода на Pi (см. `deploy/pi/README.md`) и/или dev/test на ПК
(лаунчер `run.ps1`: dev — при `LOCAL_PUBLIC=vps`, test — при `APP_ENV=test`).
2. Открой `https://forbiddenstars.ru` и `https://forbidden-stars.ru`.
3. Пока соответствующий туннель не поднят — Caddy отдаёт страницу-заглушку «Технические шоколадки»
(HTTP 503), это ожидаемо.