poison-flower/simple-updater
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

major fixes test

Browse Source
This commit is contained in:
poison-flower
2026-09-09 12:30:40 +03:00
parent b184ea76f4
commit bcd200b1e8
9 changed files with 1785 additions and 226 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+80 -168
View File
@@ -1,199 +1,111 @@
# Universal Game Updater
# simple-updater
A simple, self-hosted updater for distributing game client files. Consists of three parts:
Лёгкий self-hosted обновлятор для игры/приложения: HTTP-сервер, который раздаёт файлы клиентам, и Windows-обновлятор (`updater.py` → `updater.exe`), который сравнивает локальные файлы с манифестом на сервере и докачивает то, что изменилось.
- **`updater.py`** — the client-side app (compiled to `updater.exe`) that players run. Checks the server for changed files and downloads only what's needed.
- **`server.py`** — a lightweight HTTP server that serves client files and manifests.
- **`generate_manifest.py`** — a script you run on your build machine to generate the manifest the server distributes.
- **`generate_key.py`** — a helper to generate access keys (see [Access keys](#access-keys) below).
## Возможности
Works with any game — just fill in the configuration blocks at the top of each script.
- **Раздача нескольких версий клиента** с одного сервера (например `Main` и `Test`) через отдельные access-ключи в URL.
- **Подпись манифестов (Ed25519)** — сервер не может незаметно подменить список файлов или их хэши; обновлятор проверяет подпись публичным ключом перед тем, как довериться манифесту.
- **Сжатие файлов** — при генерации манифеста каждый файл сжимается gzip'ом; если сжатая копия меньше оригинала, обновлятор скачивает её и разжимает локально.
- **Self-update** — сам `updater.exe` умеет проверять и устанавливать собственные новые версии, без отдельной ручной раздачи.
- **Единый `config.json`** — все настройки (сервер, клиенты, ключи, вид окна, лимиты) в одном файле.
- **`quickstart.py`** — генерирует ключи, манифесты и (по флагу) собирает exe одной командой.
## How it works
1. You put your game's files in a folder on the server (e.g. `game_client/`).
2. You run `generate_manifest.py` on that folder. It walks the folder, hashes every file (MD5), and writes a `manifest.json` listing metadata for every file. It also gzip-compresses every file into a `<file>.gz` copy next to the original — if the compressed copy isn't actually smaller (common for already-compressed formats like `.jpg`, `.mp3`, `.zip`), the `.gz` copy is discarded and the manifest just records the original.
3. `server.py` serves that folder over HTTP, keyed by an access key defined in `config.json`.
4. Players run `updater.exe`. It downloads the server's `manifest.json`, compares hashes against their local files, and for anything missing or different: downloads the `.gz` copy if one exists, verifies it, decompresses it locally, and writes the result — or downloads the original directly if there's no compressed copy.
5. Once everything matches, the "Play" button launches the game executable.
## Setup
### 1. Server
Install Python 3 (no external dependencies needed — everything uses the standard library).
Generate an access key for each client version you want to distribute:
## Быстрый старт
```bash
python generate_key.py
pip install -r requirements.txt
# сгенерировать ключи + положить файлы игры в game_client/ + собрать манифесты
python quickstart.py
# то же самое, но и собрать updater.exe
python quickstart.py --build-exe
```
This prints a random 64-character hex string. Generate one per client (e.g. one for `main`, one for `test`).
Первый запуск создаст пустые папки клиентов (`game_client`, `game_client_test` — имена берутся из `config.json`'s `clients`), сгенерирует access-ключи и пару ключей для подписи манифестов. Положите файлы игры в `game_client/`, запустите `quickstart.py` ещё раз — манифест сгенерируется и подпишется автоматически.
Edit `config.json`:
```json
{
"host": "0.0.0.0",
"port": 3232,
"clients": {
"<your-generated-hex-key>": "game_client",
"<another-generated-hex-key>": "game_client_test"
}
}
```
- `host` / `port` — what the server listens on.
- `clients` — maps an access key to the folder (relative to `server.py`) that key serves.
Put your game files in the folders referenced above (`game_client/`, etc.), then generate the manifest for each:
```bash
python generate_manifest.py game_client
python generate_manifest.py game_client_test
```
Re-run this after every update to the client files, then start (or restart) the server:
Запустить сервер:
```bash
python server.py
```
Files become available at `http://<server-address>:<port>/<access-key>/...`.
## config.json
### 2. Updater (client)
Все настройки проекта живут здесь, вложенными секциями:
Edit the configuration block at the top of `updater.py`:
| Секция | Что настраивает |
|---|---|
| `server` | host, port, лимит соединений на IP |
| `clients` | имя клиента → папка с файлами (`"Main": "game_client"`) |
| `access_keys` | имя клиента → access-ключ (генерируется автоматически) |
| `default_client` | какой клиент выбран в обновляторе по умолчанию |
| `signing_keys` | публичный ключ подписи + имя файла с приватным ключом |
| `require_signature` | обязательна ли подпись манифеста (по умолчанию да) |
| `connection` | адрес и порт сервера, HTTPS вкл/выкл — то, к чему подключается обновлятор |
| `updater_ui` | название игры, размеры окна и баннера |
| `paths` | путь к exe игры, баннеру, иконке, файлу настроек |
| `manifest` | имя файла манифеста, настройки сжатия, лимит размера файла |
| `ignore` | какие файлы/папки/расширения не попадают в манифест |
| `self_update` | включён ли self-update, текущая версия обновлятора |
```python
GAME_NAME = "My Game"
UPDATER_NAME = "Launcher"
WINDOW_WIDTH = 450
WINDOW_HEIGHT = 300
BANNER_WIDTH = 430
BANNER_HEIGHT = 140
Чтобы что-то поменять — правьте `config.json` и перезапускайте `quickstart.py` (или `server.py` для настроек сервера). Ручное редактирование `updater.py`/`generate_manifest.py` не нужно — все они читают значения оттуда.
SERVER_ADDRESS = "update.mygame.com" # domain or IP
SERVER_PORT = "443" # 80/443 for HTTP/HTTPS, or a custom port for direct IP
USE_HTTPS = True
### Приватный ключ подписи
CLIENT_KEYS = {
"Main": "<same-hex-key-as-in-server-config.json>",
"Test": "<same-hex-key-as-in-server-config.json>",
}
DEFAULT_CLIENT = "Main"
Единственный настоящий секрет в проекте — приватный ключ подписи манифестов. Он **не хранится в `config.json`**, а лежит в отдельном файле `SIGNING_PRIVATE_KEY.txt` (имя настраивается через `signing_keys.private_key_file`). Публичный ключ — в `config.json`, его можно раскрывать сколько угодно, зашивать в exe и т.д.
GAME_EXE_RELATIVE_PATH = os.path.join("system", "game.exe")
BANNER_RELATIVE_PATH = "banner.png"
ICON_RELATIVE_PATH = "icon.ico"
Держите `SIGNING_PRIVATE_KEY.txt` только на машине, где генерируются манифесты — не копируйте его вместе с остальным проектом, добавьте в `.gitignore`, если используете git.
## Как всё это работает вместе
```
config.json ──┬──> generate_key.py ────────> access-ключи в config.json
│ приватный ключ в SIGNING_PRIVATE_KEY.txt
│ публичный ключ в config.json
│
├──> generate_manifest.py ───> game_client/manifest.json + .sig
│
├──> generate_updater_manifest.py ──> game_client/updater_manifest.json + .sig
│
└──> quickstart.py ──> запускает все шаги выше по порядку,
патчит updater.py и собирает updater.exe
server.py ──> раздаёт содержимое клиентских папок по HTTP(S) под access-ключом в URL
updater.py / updater.exe ──> скачивает манифест, проверяет подпись,
докачивает изменившиеся файлы, запускает игру
```
- `SERVER_ADDRESS` accepts either a domain name or a raw IP — nothing else needs to change.
- `SERVER_PORT` / `USE_HTTPS` should match how your server is actually reachable. If nginx force-redirects port 80 to 443, set `SERVER_PORT = "443"` and `USE_HTTPS = True` directly rather than relying on the redirect — the updater downloads files one request at a time, so an extra 80→443 redirect on every file adds real overhead on large clients.
- `CLIENT_KEYS` maps a friendly name shown in the UI to the actual access key sent in the request URL. Keys must match `config.json` on the server exactly.
- `GAME_EXE_RELATIVE_PATH` is where the updater looks for the game's executable, relative to the folder the updater itself is placed in.
- `BANNER_WIDTH` / `BANNER_HEIGHT` — the banner image is always scaled to exactly this size, so it doesn't matter what dimensions the source `banner.png` actually has; the layout won't shift.
## Ручной запуск отдельных шагов
Banner scaling uses [Pillow](https://pypi.org/project/Pillow/) if it's installed (`pip install Pillow`), for proper resizing. If Pillow isn't available, the updater falls back to Tkinter's built-in (cruder, integer-only) zoom/subsample — it'll still work, just less precisely scaled. Install Pillow for best results, and make sure it's bundled when compiling (see below).
Then compile with your favorite tool, e.g. [PyInstaller](https://pyinstaller.org/):
Если `quickstart.py` не подходит (например, генерация ключей и манифестов происходит на разных машинах), каждый скрипт можно запускать по отдельности:
```bash
pyinstaller --onefile --noconsole --icon=icon.ico --add-data "banner.png;." --add-data "icon.ico;." updater.py
# access-ключ для клиента, сохранить в config.json
python generate_key.py --client Main --save
# пара ключей для подписи манифестов
python generate_key.py --signing-keypair --save
# сгенерировать и подписать манифест для одной клиентской папки
python generate_manifest.py game_client
# опубликовать новую версию updater.exe для self-update
python generate_updater_manifest.py dist/updater.exe game_client --version 2
# запустить сервер
python server.py
```
Ship the resulting `updater.exe` alongside the game folder.
## Требования
## Settings
On first run, the updater creates a `settings.ini` file next to itself with the selected client version:
```ini
[updater]
client = Main
```
pip install -r requirements.txt
```
Whenever the player changes the client version dropdown, it's saved immediately so the choice persists across restarts. If `settings.ini` is missing, corrupted, or contains an unrecognized client name, the updater silently falls back to `DEFAULT_CLIENT` and continues — it never crashes over a bad settings file.
`cryptography` — подпись/проверка манифестов (Ed25519), нужен и при генерации манифестов, и при сборке `updater.exe`.
`Pillow` — опционален, используется `updater.py` для качественного масштабирования баннера; без него баннер всё равно отрисуется, просто грубее.
This is currently the only setting. To add more later, extend `load_settings()` / `save_settings()` in `updater.py` with additional keys under the same `[updater]` section.
## Access keys
Client folders are addressed by a long random hex key instead of a plain name like `main`, so the update path isn't obvious or easy to stumble on by guessing.
**This is obscurity, not real security.** The key has to live inside `updater.exe` for it to work, and anyone motivated enough to disassemble the executable or inspect network traffic can recover it. Don't rely on it to gate anything sensitive.
If a key leaks and you want to rotate it:
1. Generate a new key with `generate_key.py`.
2. Update it in the server's `config.json`.
3. Update it in `updater.py`'s `CLIENT_KEYS`.
4. Rebuild and redistribute `updater.exe`.
No folder renaming or manifest regeneration needed.
## Ignoring files during manifest generation
Edit the configuration block at the top of `generate_manifest.py`:
```python
IGNORE_FILES = {
MANIFEST_FILENAME,
"updater.exe",
"Option.ini",
"WindowsInfo.ini",
}
IGNORE_FOLDERS = {
"screenshots",
"logs",
"replays",
}
IGNORE_EXTENSIONS = {
".log",
}
```
Add any player-specific files (settings, saves, screenshots, logs) here so the updater never overwrites or deletes them.
## Compression
`generate_manifest.py` gzip-compresses every distributable file into a `<file>.gz` copy alongside the original, unconditionally — no file-type filtering. If the compressed copy ends up the same size or larger than the original (common for already-compressed formats), it's discarded automatically and that file is just served uncompressed; there's nothing to configure per file type.
The manifest records both the original file's hash/size and, when a compressed copy exists, its hash/size too:
```json
{
"script.txt": {
"hash": "d3650c70e7d942736c3ca77daf381262",
"size": 60000,
"compressed": true,
"compressed_size": 177,
"compressed_hash": "852ab2df07a4c65cddd6ed3ec0282301"
},
"texture.bin": {
"hash": "1b6d041423b9863dee54e87fed1f0cdd",
"size": 20000,
"compressed": false
}
}
```
`updater.py` uses this to download the smaller `.gz` copy when one is available, verifies its hash, decompresses it in memory, and verifies the decompressed result against the original hash before writing it to disk. If anything about the compressed copy fails (missing, corrupted, hash mismatch), it automatically falls back to downloading the uncompressed original — a bad `.gz` on the server never blocks an update.
Two settings control this, and must be kept in sync between `generate_manifest.py` and `updater.py`:
- `COMPRESSED_SUFFIX` (default `.gz`) — the suffix used for compressed copies.
- `COMPRESSION_LEVEL` (default `6`, in `generate_manifest.py` only) — gzip level 1 (fastest, larger) to 9 (slowest, smallest).
Re-run `generate_manifest.py` after any change to the client files — it regenerates both the manifest and the `.gz` copies. Compressed output is generated with a fixed mtime so re-running it without any real file changes produces byte-identical `.gz` files and stable hashes.
## Notes / limitations
- File integrity is checked with MD5 — fine for detecting changed files, not intended as a cryptographic guarantee.
- Compression roughly doubles the disk space needed on the server for each client version (original + `.gz` copies), in exchange for faster downloads for compressible files.
- The server has no built-in rate limiting or HTTPS; put it behind a reverse proxy (nginx, Caddy) if you need either.
- The server never serves directory listings — a bare `/`, an unknown key, or a path that tries to escape the client folder (`..`) all get a 404, including the server's own script/config files.
- `updater.py` uses Tkinter for the UI, which ships with most standard Python installs on Windows.
Для сборки `updater.exe` также нужен `pyinstaller` (`pip install pyinstaller`), если запускаете `quickstart.py --build-exe`.