Преминаване от стария панел

Entrosity Matrix произлиза от панел за управление на правилата на залите в едно училище, който пилотното училище използва на https://network.coding.local (приложение на Django със собствена база данни SQLite, собствен API ключ за FortiGate и ролите администратор и оператор с разрешени зали). Matrix прави същото в Entrosity Hub, със същите проверки във FortiGate. Тази страница прехвърля училището без момент, в който две системи записват в защитната стена, и без да се губят правата на учителите по зали или историята.

Етап	Стар панел	Matrix	Записва във FortiGate
1. Подготовка	Използва се	Тенант, хора, конектор, защитна стена	Старият панел
2. Паралелна работа	Използва се	Само чете (превключвателите са изключени, защитата не е приета)	Старият панел
3. Прехвърляне	Използва се	Правата по зали и историята са прехвърлени	Старият панел
4. Преминаване	Ключът е само за четене	Превключвателите са включени, защитата е приета	Matrix
5. Извеждане от експлоатация	Спрян, архивиран, ключът е изтрит	Използва се	Matrix

Никога не позволявайте и двете да записват

Старият панел и Matrix заключват правило само за себе си; нито един от тях не пази от промени, направени от другия. До преминаването Matrix не бива да може да записва (двата превключвателя изключени и защитата неприета); след него не бива да може старият панел (ключът му е само за четене).

1. Подготовка

Тенант. Администратор на платформата включва Entrosity Matrix за организацията на училището в Hub (Първи стъпки).

Хора. Всеки потребител на стария панел, който продължава да работи, има нужда от акаунт в Entrosity Hub (своя имейл адрес) в организацията, с роля в Matrix:

Стар панел	Роля в Matrix
Администратор (активен)	Администратор на тенанта
Оператор (активен)	Учител
Деактивиран	няма

Акаунтите се съпоставят по имейл в стъпка 3, а правата по зали се прехвърлят само за хора, които вече имат ролята Учител в Matrix.

API администратор на FortiGate за Matrix. Създайте нов REST API администратор за Matrix (не използвайте този на стария панел): минимален профил, VDOM root и компютърът с конектора като единствен доверен хост (Настройка на FortiGate). Администраторът на стария панел има доверие на хоста на стария панел; новият – на този на конектора.
Конектор. Инсталирайте конектора на компютър с Windows в административната мрежа, от който се достига портът за управление на FortiGate (Конектори).

Защитна стена. Добавете защитната стена в Matrix с настройките на стария панел (неговите настройки FORTIGATE_* и правилото за имената на залите от документацията му):

Поле в Matrix	Стойност за пилотното училище
Адрес, Порт, VDOM	Както в адреса на FortiGate и VDOM на стария панел (`root`)
Входящ интерфейс или зона → Изходящ интерфейс или зона	`Students` → `INTERNET`
Шаблон за имената на правилата	`Internet Access for (?P<room>(?:SB[0-9]+\|FB\|HAC)-[0-9]{3})`
Имена на сградите	`FB` → Фирма, `HAC` → ЦВП (SB1, SB2, … се показват като Сграда 1, Сграда 2)
Окончание на имената на компютрите	`.coding.local`
Очаквана версия на FortiOS	Версията, която работи на FortiGate (`7.4.11` към момента на писане)
Проверка на TLS сертификата на FortiGate	Включена, с CA на FortiGate. Старият панел работи с изключена проверка по желание на собственика; изключете я в Matrix само ако CA все още не е наличен.
Разреши включване и изключване на правилата за зали, Разреши промяна и добавяне на компютри	Изключени

Запазете ключа на новия администратор (Защитни стени → API ключ).

2. Паралелна работа (само четене)

Оставете двата превключвателя изключени и не изпълнявайте guard accept на компютъра с конектора: тогава Matrix само чете. Учителите продължават да използват стария панел.

Изпълнете Провери за защитната стена. Сравнете със стария панел: същите зали (SB, FB и HAC), същите адресни групи и брой компютри. Използвайте Проверка на шаблона с Имената от последната проверка, за да се уверите, че никое друго правило не съответства.
Прочетете предупрежденията. Документацията на стария панел вече отбелязва, че общото включено правило ACCEPT Internet Access for Students идва след правилата на залите и обхваща всички техни компютри: очаквайте предупреждение later_accept_policy за всяка зала, докато това не бъде поправено във FortiGate. Дотогава изключена зала не доказва, че интернетът ѝ е спрян, в нито една от двете системи (Какво означава изключването на зала).
Наблюдавайте Зали няколко учебни дни: когато учител превключи зала в стария панел, Matrix показва новото състояние в рамките на интервала на данните.
Нека администраторите и няколко учители влязат и разгледат (учителите не виждат зали, докато правата им не бъдат прехвърлени, и ги превключват едва след преминаването).

3. Прехвърляне на правата и историята

matrix-server import-stop-internet пренася данните на стария панел в тенанта и защитната стена:

разрешените зали на всеки активен учител стават права по зали в Matrix за защитната стена (отбелязани като запис Права по зали imported from stop-internet);
историята на превключванията на зали, промените на IP и новите компютри става история в Matrix с оригиналния си час, потребител, IP и резултат, отбелязана като Прехвърлено от стария панел (източник stop-internet). Влизанията, промените в акаунтите и записите за отказан достъп не се прехвърлят; записите, които все още чакат в стария панел, се прехвърлят като Непотвърдено.

Повторното изпълнение добавя само новото, така че може да се изпълни по време на паралелната работа и още веднъж при преминаването.

Експорт от стария панел (само четене)

Нищо в стария панел не се променя: експортът отваря базата му данни само за четене (mode=ro) в работещия контейнер и пише на стандартния изход. Запазете това като export_stop_internet.py на хоста на стария панел, до неговия compose.yaml:

# Read-only export of the old room panel for import-stop-internet.
import json, sqlite3, sys

db = sqlite3.connect("file:/app/data/db.sqlite3?mode=ro", uri=True)
db.row_factory = sqlite3.Row

def utc(v):  # Django stores UTC as "YYYY-MM-DD HH:MM:SS[.ffffff]"
    return v.replace(" ", "T") + ("" if v.endswith("Z") or "+" in v else "Z")

users = [
    {"username": r["username"], "role": r["role"], "is_active": bool(r["is_active"]),
     "allowed_rooms": json.loads(r["allowed_rooms"] or "[]")}
    for r in db.execute("SELECT username, role, is_active, allowed_rooms FROM panel_user ORDER BY username")
]
history = [
    {"id": r["id"], "created_at": utc(r["created_at"]), "username": r["username"], "ip": r["ip"] or "",
     "kind": r["kind"], "room": r["room"], "policy_id": r["policy_id"], "policy_name": r["policy_name"],
     "previous": r["previous"], "desired": r["desired"], "result": r["result"], "detail": r["detail"],
     "object_name": r["object_name"], "group_name": r["group_name"],
     "operation_id": r["operation_id"] or "", "metadata": json.loads(r["metadata"] or "{}")}
    for r in db.execute("SELECT * FROM panel_auditevent ORDER BY id")
]
json.dump({"users": users, "history": history}, sys.stdout, ensure_ascii=False, indent=1)

Изпълнете го и изведете потребителските имена за users.csv:

docker compose exec -T app python - < export_stop_internet.py > export.json
python3 -c 'import json; [print(u["username"] + ",") for u in json.load(open("export.json"))["users"] if u["is_active"]]' > users.csv

Допълнете users.csv ръчно: по един ред за всеки активен потребител, потребителското име в стария панел и имейл адреса на акаунта в Hub на същия човек, с незадължителен заглавен ред:

username,email
teacher-sb1,[email protected]

export.json и users.csv съдържат потребителски имена, имейл адреси и IP адреси: пазете ги с ограничен достъп, пренасяйте ги до сървъра на Matrix само през SSH и ги изтрийте след прехвърлянето.

Изпълнение на прехвърлянето

На сървъра на Matrix, като оператор на сървъра, в директорията за внедряване (/opt/entrosity/deploy), с двата файла в папка import/, достъпна за четене от контейнера. Идентификаторът на тенанта е в адреса на Matrix (/matrix/t/<tenant id>/), а този на защитната стена – в адреса на нейната страница (…/settings/firewalls/<firewall id>):

docker compose -f docker-compose.prod.yml --env-file .env --profile matrix run --rm --no-deps \
  -v "$PWD/import:/import:ro" matrix \
  import-stop-internet --tenant <tenant id> --firewall <firewall id> \
  --users /import/users.csv --export /import/export.json

Командата извежда предупреждение за всеки потребител, когото не е успяла да съпостави (все още няма акаунт в Hub с този имейл в Matrix или не е Учител), и за зали, които защитната стена не отчита, а след това обобщение:

warning: user teacher-x ([email protected]) is not a Matrix user: rooms not granted
room grants added: 42 (users: 17); history imported: 3120, skipped: 850

Отстранете причините за предупрежденията (поканете човека, дайте му ролята Учител, изчакайте минута) и я изпълнете отново; тя добавя само липсващото. След това проверете Права по зали и История в Matrix.

4. Преминаване

Изберете време извън учебните часове. В този ред:

Завършете незавършените операции в стария панел. Всяка незавършена операция с адрес (Провери / повтори) трябва да бъде завършена или решена там: те не се прехвърлят.
Направете стария панел само за четене във FortiGate. Дайте на REST API администратора на стария панел профил само за четене, така че ключът му вече да не може да записва:
```
config system accprofile
    edit "room-panel-readonly"
        set netgrp read
        set fwgrp read
    next
end
config system api-user
    edit "<old panel's API administrator>"
        set accprofile "room-panel-readonly"
    next
end
```
Потвърдете промяната в конфигурацията на FortiGate (а не чрез превключване на зала в стария панел). Оттук нататък всяка промяна, опитана там, се отказва от FortiGate.
Прехвърлете още веднъж (стъпка 3), за да пренесете последната история и правата, променени междувременно.
Приемете защитата на компютъра с конектора (matrix-connector guard accept <firewall id>; за промени на адреси също guard set <firewall id> --address-writes on) и включете Разреши включване и изключване на правилата за зали (и Разреши промяна и добавяне на компютри) (Първи стъпки).
Проверете на тестовата зала, уговорена с администратора на FortiGate: изключете, проверете от компютър в залата, включете. За адресите – тестов компютър и група.
Съобщете на учителите новия адрес, https://hub.entrosity.com/matrix, и че влизат с акаунта си в Hub.

Връщане назад през първите дни: изключете двата превключвателя на Matrix и изпълнете matrix-connector guard reset <firewall id>, след което върнете предишния профил на API администратора на стария панел. Никога не допускайте и двете да са включени.

5. Извеждане от експлоатация

След няколко седмици само с Matrix:

Последно архивно копие на стария панел, както е описано в документацията му (спрете приложението, копирайте db.sqlite3), и го пазете с ограничен достъп, докато училището пази историята. .env и secret.txt вече не са нужни.
Спрете стария панел: docker compose down в папката му (без -v, докато архивното копие не бъде проверено; down -v изтрива тома му с данни).
Изтрийте API администратора на стария панел във FortiGate (което отменя ключа му) и след това изтрийте сигурно secret.txt.
Изведете адреса от употреба: премахнете хоста network.coding.local от конфигурацията на уеб сървъра (пренасочването HTTP → HTTPS за това име, инсталирано със стария панел) и от вътрешния DNS или го насочете към страница с връзка към https://hub.entrosity.com/matrix. Сертификатът му не трябва да се подновява.
Премахнете правилата на защитната стена и отворените портове на хоста на стария панел, които вече не са нужни.

1. Подготовка​

2. Паралелна работа (само четене)​

3. Прехвърляне на правата и историята​

Експорт от стария панел (само четене)​

Изпълнение на прехвърлянето​

4. Преминаване​

5. Извеждане от експлоатация​