463 lines
25 KiB
Markdown
463 lines
25 KiB
Markdown
# 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
|
||
```
|