Mrixs/MrixsCraft
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update main repo

Browse Source
This commit is contained in:
Vladimir Zagainov
2026-06-09 18:14:59 +03:00
parent 7a53666245
commit f603d99587
6 changed files with 1326 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

462
docs/state.md Normal file
View File

@@ -0,0 +1,462 @@
# MrixsCraft — Текущее состояние проекта
> Дата: 2026-06-05
> Версия: dev (pre-alpha)
---
## 1. Обзор проекта
MrixsCraft — приватный Minecraft-сервер с веб-лаунчером. Проект состоит из двух независимых репозиториев, объединённых через git submodules:
- **`server/`** — бэкенд на Go (net/http + PostgreSQL)
- **`launcher/`** — десктопный лаунчер на Go + Fyne GUI
Домен: `minecraft.mrixs.me`
CDN: `cdn.mrixs.me`
Registry: `gitea.mrixs.me/mrixs/mrixscraft-server`
---
## 2. Структура файлов
```
MC-server/
├── .gitmodules # Submodules: launcher, server
├── docs/
│ ├── server/Specification.md # Спецификация серверной части (RU)
│ └── launcher/Specification.md # Спецификация лаунчера (RU)
│
├── launcher/ # Git submodule (MrixsCraft-launcher)
│ ├── go.mod # Module: gitea.mrixs.me/Mrixs/MrixsCraft-launcher (Go 1.22)
│ ├── go.sum
│ ├── README.md
│ ├── cmd/launcher/main.go # Точка входа лаунчера
│ ├── internal/
│ │ ├── auth/auth.go # Yggdrasil клиент (authenticate/refresh/validate)
│ │ ├── config/config.go # Настройки лаунчера, системные пути
│ │ ├── fetcher/fetcher.go # HTTP-загрузчик файлов с SHA-1 верификацией
│ │ ├── java/java.java # Поиск/загрузка JRE
│ │ ├── launch/
│ │ │ ├── launch.go # Запуск Minecraft (classpath, аргументы, exec)
│ │ │ └── manifest.go # Парсинг manifest.json
│ │ ├── selfupdate/selfupdate.go # Автообновление лаунчера
│ │ └── ui/
│ │ ├── ui.go # Fyne bootstrap, главное окно
│ │ ├── screens/screens.go # Экраны (Main, Login, Settings)
│ │ ├── components/components.go # Виджеты (ServerCard, PlayButton, Avatar)
│ │ └── theme/theme.go # Minecraft-стилизация Fyne
│ └── pkg/utils/utils.go # SHA1File, SHA1Bytes, Unzip
│
└── server/ # Git submodule (MrixsCraft-server)
├── go.mod # Module: gitea.mrixs.me/Mrixs/MrixsCraft-server (Go 1.25)
├── go.sum
├── README.md
├── Dockerfile # Multi-stage build (~20 MB, golang:1.25-alpine + alpine:3.19)
├── docker-compose.yml # Caddy + backend + postgres + watchtower
├── Caddyfile # Reverse proxy, CDN, HTTPS
├── .env.example # Шаблон переменных окружения
├── .gitignore
├── .gitea/
│ └── workflows/
│ └── ci.yml # CI: lint → test → build → docker push
├── migrations/
│ ├── README.md # Инструкция по применению миграций
│ ├── 001_init.sql # Полная схема БД (6 таблиц + индексы)
│ └── 002_migration_history.sql # Таблица отслеживания миграций
├── cmd/
│ ├── server/main.go # Точка входа: маршруты, middleware, graceful shutdown
│ └── ci-release/main.go # CLI-утилита для загрузки релиза лаунчера из CI
├── internal/
│ ├── admin/admin.go # CRUD модпаков, загрузка файлов, манифесты, launcher release
│ ├── api/api.go # Публичное API: регистрация, логин, скины, плащи, launcher
│ ├── auth/auth.go # Yggdrasil протокол: authenticate/refresh/validate/invalidate
│ ├── cas/cas.go # Content-Addressable Storage: отдача файлов по SHA-1 хэшу
│ ├── config/config.go # Конфигурация из ENV (порт, БД, CAS, JWT, CI token)
│ ├── database/database.go # PostgreSQL (pgx/pgxpool), модели данных
│ ├── middleware/middleware.go # CORS, Logging, Recovery, RateLimiter
│ ├── session/cleanup.go # Фоновая очистка expired-сессий
│ └── templates/
│ ├── templates.go # Go html/template: per-page parsing (base+page pair)
│ └── html/
│ ├── base.html # Базовый layout (тёмная тема, зелёный акцент)
│ ├── index.html # Главная страница сервера
│ ├── login.html # Форма входа (POST → /api/web/login)
│ ├── register.html # Форма регистрации (POST → /api/web/register)
│ └── profile.html # Профиль игрока (скины, плащи, лаунчер)
└── pkg/utils/utils.go # SHA1Bytes, SHA256Bytes, SHA1File, WriteJSON, WriteError, Unzip
```
---
## 3. Серверная часть (server/)
### 3.1. Технологический стек
| Компонент | Технология |
|-----------|-----------|
| Язык | Go 1.25 |
| HTTP | net/http (стандартная библиотека) |
| База данных | PostgreSQL 16 + pgx/v5 |
| Аутентификация | bcrypt, crypto/rand токены |
| Хеширование | SHA-1 (CAS), SHA-256 (релизы лаунчера) |
| Контейнеризация | Docker multi-stage build |
| Reverse proxy | Caddy 2 |
| Автообновление | Watchtower + Gitea Container Registry |
| CI/CD | Gitea Actions (.gitea/workflows/ci.yml) |
**Зависимости go.mod:**
- `github.com/jackc/pgx/v5 v5.6.0` — PostgreSQL драйвер
- `golang.org/x/crypto` — bcrypt для хеширования паролей
### 3.2. База данных
Файлы миграций: `server/migrations/`
| Миграция | Назначение |
|----------|-----------|
| `001_init.sql` | Начальная схема: 6 таблиц + 9 индексов |
| `002_migration_history.sql` | Таблица для отслеживания применённых миграций |
| `README.md` | Инструкция по ручному применению |
**7 таблиц:**
| Таблица | Назначение |
|---------|-----------|
| `users` | Пользователи (username, email, password_hash, uuid, role) |
| `player_textures` | Скины и плащи (skin_hash, cape_hash → CAS) |
| `yggdrasil_sessions` | Сессии авторизации (access_token, client_token, expires_at) |
| `modpacks` | Модпаки/серверы (slug, name, minecraft_version, java_version, server_ip) |
| `global_files` | CAS-реестр файлов (sha1 PK, size_bytes, file_name, mime_type) |
| `launcher_releases` | Релизы лаунчера (version, os, arch, sha256, file_path) |
| `migration_history` | Отслеживание применённых миграций (filename, applied_at) |
**Индексы:** 9 индексов для быстрого поиска по токенам, UUID, username, email, role, файлам.
### 3.3. API Endpoints
#### Yggdrasil (Mojang-совместимый)
| Метод | Путь | Описание |
|-------|------|----------|
| POST | `/authserver/authenticate` | Аутентификация по логину/паролю |
| POST | `/authserver/refresh` | Обновление токена |
| POST | `/authserver/validate` | Проверка токена (204 No Content) |
| POST | `/authserver/invalidate` | Инвалидация токена |
| POST | `/authserver/signout` | Выход (удаление всех сессий пользователя) |
| GET | `/sessionserver/session/minecraft/profile/{uuid}` | Профиль игрока с текстурами |
#### Публичное API (сайт)
| Метод | Путь | Описание |
|-------|------|----------|
| POST | `/api/web/register` | Регистрация игрока (email через net/mail.ParseAddress) |
| POST | `/api/web/login` | Логин на сайт |
| POST | `/api/web/profile/skin` | Загрузка скина (PNG, валидация размеров) |
| POST | `/api/web/profile/cape` | Загрузка плаща (PNG) |
| DELETE | `/api/web/profile/skin` | Удаление скина |
| DELETE | `/api/web/profile/cape` | Удаление плаща |
| GET | `/api/web/profile/{uuid}` | Профиль игрока (UUID, username, текстуры) |
#### Лаунчер
| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/api/launcher/latest` | Последняя версия лаунчера (?os=&arch=) |
| GET | `/api/servers.json` | Список активных модпаков |
| GET | `/api/instances/{slug}/manifest.json` | Манифест модпака |
#### Файловый сервер (CAS)
| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/files/{hash}` | Файл по SHA-1 хэшу (40 hex chars) |
| GET | `/files/launcher/{version}/{os}/{arch}/{filename}` | Бинарник лаунчера |
| GET | `/skins/{hash}` | Скин/плащ по хэшу |
#### Веб-шаблоны (HTML)
| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/` | Главная страница (Minecraft-стиль) |
| GET | `/login` | Страница логина (форма → /api/web/login) |
| GET | `/register` | Страница регистрации (форма → /api/web/register) |
| GET | `/profile` | Профиль игрока (скины, плащи, скачивание лаунчера) |
#### Админ-панель (Bearer token + role=admin)
| Метод | Путь | Описание |
|-------|------|----------|
| GET | `/api/admin/modpacks` | Список модпаков |
| POST | `/api/admin/modpacks` | Создать модпак |
| PUT | `/api/admin/modpacks/{id}` | Обновить модпак |
| DELETE | `/api/admin/modpacks/{id}` | Деактивировать модпак |
| POST | `/api/admin/modpacks/{slug}/upload` | Загрузка файлов (multipart, до 500 MB) |
| POST | `/api/admin/modpacks/{slug}/manifest` | Генерация manifest.json |
| POST | `/api/admin/launcher/release` | Загрузка релиза лаунчера (X-CI-Token) |
| GET | `/admin` | Веб-интерфейс админ-панели (требует роль admin) |
### 3.4. Middleware цепочки
```
Recovery → Logging → RateLimit → CORS → mux
(outermost) (innermost)
```
Порядок применения (от внешнего к внутреннему):
1. **Recovery** — catch panics → 500 + stack trace log
2. **Logging** — method, path, status, duration, remote addr
3. **RateLimit** — per-IP token bucket (30 req/min, burst 60)
4. **CORS** — `Access-Control-Allow-*` headers + OPTIONS handling
### 3.5. Content-Addressable Storage (CAS)
Путь хранения: `<CASDir>/<first_2_chars_of_hash>/<full_40_char_hash>`
Пример: `/var/www/cdn/files/a1/a1b2c3d4e5...`
- Иммутабельность: файлы никогда не перезаписываются
- Cache-Control: `public, max-age=31536000, immutable` (1 год)
- Content-Type определяется по расширению оригинального имени файла (из `global_files.file_name`)
- Верификация: `VerifyAndStore` — сравнивает SHA-1 загруженных данных с ожидаемым хэшем (constant-time)
- **Конкурентная безопасность:** per-hash `sync.Mutex` предотвращает race condition при параллельной записи одного файла. `StoreFile` идемпотентен — если файл уже записан другим воркером, возвращает существующий hash.
Экспортируемые функции (`cas` пакет):
- `StoreFile(casDir, data) → (hash, error)` — сохранение в CAS (потокобезопасен)
- `FileExists(casDir, hash) → bool` — проверка наличия
- `VerifyAndStore(casDir, data, expectedHash) → (hash, error)` — верификация + сохранение
### 3.6. Валидация email
Реализована через стандартную библиотеку `net/mail.ParseAddress()`:
- Проверка длины: ≤ 254 символов (RFC 5321)
- Синтаксический разбор: `mail.ParseAddress()` (RFC 5322)
- Отклоняет адреса типа `a@b.`, `user@`, `@domain.com`
### 3.7. CI/CD Pipeline
Файл: `.gitea/workflows/ci.yml` (Gitea Actions, совместим с GitHub Actions).
| Шаг | Что делает | Условие |
|-----|-----------|---------|
| `lint` | `go vet ./...` + `gofmt -l .` | Всегда |
| `test` | `go test ./... -v -race -cover` | После lint |
| `build` | `go build -o mrixscraft-server ./cmd/server` | После test |
| `docker` | `docker build` + `push` в реестр | Только `master` ветка |
Registry: `gitea.mrixs.me/mrixs/mrixscraft-server:latest`, `:sha`
**Docker аутентификация:** PAT (Personal Access Token) через `secrets.PACKAGES_TOKEN` + `gitea.repository_owner`. GITHUB_TOKEN read-only для packages в Gitea (issue #23642).
**Required secrets:**
- `PACKAGES_TOKEN` — PAT с scopes: `read:package`, `write:package`
### 3.8. Переменные окружения
| Переменная | По умолчанию | Обязательная |
|------------|-------------|--------------|
| `SERVER_PORT` | 8080 | Нет |
| `DATABASE_URL` | — | **Да** |
| `CAS_DIR` | `/var/www/cdn/files` | Нет |
| `SKINS_DIR` | `/var/www/cdn/skins` | Нет |
| `JWT_SECRET` | — | **Да** |
| `CI_SECRET` | — | Нет |
| `BASE_URL` | `https://minecraft.mrixs.me` | Нет |
### 3.9. Docker Compose сервисы
| Сервис | Образ | Роль |
|--------|-------|------|
| `caddy` | caddy:2-alpine | Reverse proxy, HTTPS, статика |
| `backend` | gitea.mrixs.me/mrixs/mrixscraft-server:latest | Go-приложение, порт 8080 |
| `postgres` | postgres:16-alpine | БД, healthcheck, авто-миграции |
| `watchtower` | containrrr/watchtower | Авто-обновление контейнеров (5 мин) |
Volumes: `pgdata`, `cdn_files` (rw для backend, ro для caddy), `caddy_data`, `caddy_config`
---
## 4. Лаунчер (launcher/)
### 4.1. Технологический стек
| Компонент | Технология |
|-----------|-----------|
| Язык | Go 1.22 |
| GUI | Fyne v2.4.5 |
| Авторизация | Yggdrasil API (серверная часть) |
| Хеширование | SHA-1 (файлы), SHA-256 (автообновление) |
**Зависимости go.mod:**
- `fyne.io/fyne/v2 v2.4.5` — GUI фреймворк
### 4.2. Архитектура пакетов
| Пакет | Назначение |
|-------|-----------|
| `internal/auth` | Yggdrasil клиент: authenticate, refresh, validate, ensureValid, сохранение session.json |
| `internal/config` | launcher.json (ServerURL, MemoryMB, ExtraArgs, окно), системные пути |
| `internal/fetcher` | Download() с SHA-1 верификацией, WorkerPool (4 воркера) |
| `internal/java` | Поиск JRE (JavaDir/version/bin/java), заглушка для автозагрузки |
| `internal/launch` | Manifest (парсинг), Game (Prepare, BuildCommand, Start, cleanupUnknownMods) |
| `internal/selfupdate` | Check(), Apply(), Restart() — SHA-256 верификация, rename для Windows |
| `internal/ui` | Fyne bootstrap, главное окно |
| `internal/ui/screens` | MainScreen, LoginScreen, SettingsScreen |
| `internal/ui/components` | ServerCard, PlayButton, SettingsButton, LogoutButton, AvatarImage, ProgressBar |
| `internal/ui/theme` | MinecraftTheme — тёмная тема, зелёный акцент |
| `pkg/utils` | SHA1File, SHA1Bytes, Unzip |
### 4.3. Жизненный цикл лаунчера
```
main() → config.EnsureRoot() → config.Load() → auth.NewFromConfig() → EnsureValid() → ui.Launch()
```
1. Загрузка настроек из `launcher.json` (или defaults)
2. Проверка сессии: `validate` → `refresh` → если неудачно → показ экрана логина
3. GUI: BorderLayout (left=серверы, center=контент, bottom=управление)
4. Выбор сервера → MainScreen
5. PLAY → (заглушка, TODO: launch.Prepare → Game.Start)
6. Настройки: слайдер RAM (1024–16384 MB), дополнительные JVM-флаги
### 4.4. Файловая структура клиента
| ОС | Корневая директория |
|----|---------------------|
| Windows | `%APPDATA%\MrixsCraft\` |
| macOS | `~/Library/Application Support/MrixsCraft/` |
| Linux | `~/.MrixsCraft/` |
Содержимое: `launcher.json`, `session.json`, `Java/{8,17,21}/`, `assets/`, `libraries/`, `instances/{slug}/` (mods, config, resourcepacks, mods_backup)
### 4.5. Запуск игры (`launch`)
1. **Prepare:**
- Скачивание манифеста с сервера
- LoadManifest → парсинг JSON
- Java.Find(version) → поиск или (TODO) загрузка JRE
- WorkerPool(4) → параллельная загрузка файлов с SHA-1 проверкой
- cleanupUnknownMods → неизвестные моды в mods_backup/
2. **BuildCommand:**
- JVM args: `-Xms/-Xmx` (RAM), пользовательские аргументы
- Authlib-injector: `-javaagent:authlib-injector.jar=<URL>`
- Classpath: все .jar из манифеста + `libraries/*`
- Game args: интерполяция `${player_name}`, `${auth_uuid}`, `${auth_access_token}`, и т.д.
3. **Start:** `exec.Command(java, args...).Run()`
---
## 5. Общие утилиты
### 5.1. `server/pkg/utils/`
Функции:
- `SHA1Bytes(data) → string` — SHA-1 hex digest
- `SHA256Bytes(data) → string` — SHA-256 hex digest
- `SHA1File(path) → (string, error)` — SHA-1 файла
- `WriteJSON(w, status, v)` — HTTP JSON response
- `WriteError(w, status, msg)` — HTTP JSON error (`{"error": msg}`)
- `Unzip(data, dest) → ([]string, error)` — распаковка ZIP с zip-slip защитой
Потребители: `internal/auth`, `internal/admin`, `internal/api`, `internal/cas`
### 5.2. `launcher/pkg/utils/`
Функции:
- `SHA1File(path) → (string, error)` — SHA-1 файла
- `SHA1Bytes(data) → string` — SHA-1 hex digest
- `Unzip(src, dest) → error` — распаковка ZIP-файла с zip-slip защитой
Потребитель: `internal/fetcher`
**Примечание:** Утилиты SHA-1/SHA-256/Unzip дублируются между сервером и лаунчером (разные модули). Это нормально, т.к. лаунчер — отдельный модуль.
---
## 6. Тестирование
### 6.1. Серверные тесты
| Файл | Пакет | Что тестирует |
|------|-------|--------------|
| `internal/cas/cas_test.go` | `cas` | `isValidHash`, `StoreFile`, `FileExists`, `VerifyAndStore`, `detectContentType`, `StoreFile_ConcurrentSameHash` |
| `internal/auth/auth_test.go` | `auth` | `GenerateToken`, `GenerateUUID`, `HashPassword`, `VerifyPassword`, `IsBcryptHash`, `ExtractBearer` |
| `internal/api/api_test.go` | `api` | Валидация register/login (email, длина, пустые поля), параметры launcherLatest, auth middleware, регистрация маршрутов |
| `internal/session/cleanup_test.go` | `session` | `StartCleanupWorker` с nil DB (graceful no-op) |
Тесты используют `testing` + `httptest`. DB-интеграционные тесты отсутствуют (ручное тестирование).
### 6.2. Тесты лаунчера
Отсутствуют (тестирование GUI затруднено).
---
## 7. Известные TODO и незавершённые части
### Сервер
- [ ] **Поиск по БД**: API не имеет полнотекстового поиска файлов.
- [ ] **Автодеплой релизов лаунчера**: CI собирает и пушит Docker-образ, но не вызывает `POST /api/admin/launcher/release`. Обработчик на сервере и CLI-утилита (`cmd/ci-release/`) есть, но не подключены к CI-пайплайну.
- [ ] **SIGHUP reload**: Reload конфига без рестарта — отложен (требует рефакторинга handler'ов на `config.Atomic`).
### Лаунчер
- [ ] **PLAY кнопка**: Привязка к `launch.Prepare` + `Game.Start` не реализована (заглушка).
- [ ] **Server list**: Список серверов hardcoded (`hitech`, `vanilla`), не загружается с `/api/servers.json`.
- [ ] **Java auto-download**: `java.Find()` возвращает ошибку вместо загрузки JRE.
- [ ] **Автообновление**: `selfupdate.Check()` вызывается только в `main.go` если `version != "dev"`.
- [ ] **Аватарка**: 8x64 лицо из скина не рендерится (заглушка — пустое изображение).
- [ ] **Новости/патчноуты**: TODO в MainScreen.
- [ ] **servers.dat**: Добавление сервера в NBT-файл не реализовано.
### Инфраструктура
- [ ] **Миграции**: Ручное применение (нет автоматического Go-мигратора).
- [ ] **backup скрипт**: Не добавлен в cron (только описан в спецификации).
- [ ] **Graceful restart лаунчера**: Windows `.old` rename не протестирован.
---
## 8. Архитектурные заметки
### Паттерны
- **handler-per-domain**: Каждый домен (auth, admin, api, cas, templates) имеет свой `Handler` с методами `NewHandler(db, cfg)` и `RegisterRoutes(mux)`.
- **Shared utilities**: `pkg/utils` содержит общие HTTP и crypto функции, используемые несколькими пакетами.
- **Middleware chain**: Функциональная композиция через `var handler http.Handler = mux`.
- **CAS**: Content-Addressable Storage — файлы хранятся по хэшу, дедупликация автоматическая. Per-hash mutex для конкурентной безопасности.
- **Per-page templates**: Каждая HTML-страница парсит `base.html` + свой файл отдельно (`template.New("base.html").ParseFS(..., "html/base.html", "html/page.html")`), хранится в `map[string]*template.Template`. Это предотвращает перезапись `{{define "content"}}` блоков при wildcard-парсинге (баг исправлен 2026-06-04).
### Безопасность
- bcrypt для паролей (cost=default)
- SHA-1 для CAS (не криптографический контекст — целостность файлов)
- ConstantTimeCompare для хэш-сравнений
- Bearer token для API авторизации
- X-CI-Token для CI/CD эндпоинта (constant-time comparison)
- Path traversal защита в CAS и launcher asset serving
- Zip-slip защита при распаковке
- Rate limiting (token bucket, per-IP)
- Recovery middleware (panic → 500)
- Email validation через net/mail.ParseAddress (RFC 5322)
### Разделение модулей
- `server/` и `launcher/` — **разные Go модули** (разные `go.mod`).
- Лаунчер может собираться и работать автономно.
- Единственная связь — HTTP API (Yggdrasil + REST).
---
## 9. Команды
### Сервер
```bash
cd server/
go build -o mrixscraft-server ./cmd/server
go test ./...
go run ./cmd/server
```
### Лаунчер
```bash
cd launcher/
go build -o mrixscraft-launcher ./cmd/launcher
go run ./cmd/launcher
```
### Docker
```bash
cd server/
docker compose up -d
```