86 lines
5.4 KiB
Markdown
86 lines
5.4 KiB
Markdown
# History Collector
|
|
|
|
Python/FastAPI strežnik za lastno Chrome razširitev: sprejema obiske, jih trajno shrani v SQLite in jih lahko opcijsko pošlje v zaseben Discord kanal prek webhooka.
|
|
|
|
> URL-ji so lahko občutljivi. Uporabi samo na napravah, ki jih upravljaš, z jasnim obvestilom uporabnikom. Strežnika ne izpostavljaj neposredno internetu brez HTTPS in dodatne zaščite.
|
|
|
|
## Zagon
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# V .env nastavi dolg, naključen API_TOKEN.
|
|
docker compose up -d --build
|
|
docker compose logs -f
|
|
curl http://127.0.0.1:8080/healthz
|
|
```
|
|
|
|
Privzeto posluša samo na `127.0.0.1:8080`. Za dostop iz drugih naprav uporabi VPN (Tailscale/WireGuard) ali HTTPS reverse proxy. Ne odpiraj porta neposredno v internet.
|
|
|
|
## API
|
|
|
|
`POST /v1/visits`, z glavo `Authorization: Bearer TVOJ_API_TOKEN`:
|
|
|
|
```json
|
|
{
|
|
"device_id": "otrok-prenosnik",
|
|
"visits": [{
|
|
"url": "https://example.com/clanek",
|
|
"title": "Primer",
|
|
"visit_time": "2026-10-06T18:50:00Z",
|
|
"transition": "observed"
|
|
}]
|
|
}
|
|
```
|
|
|
|
Odgovor `202 Accepted` pomeni, da je paket zapisan v `./data/history.sqlite3`. Podvojeni obiski se ne podvojijo.
|
|
|
|
## Spletni pregledovalnik
|
|
|
|
Odpri `http://127.0.0.1:8080/` in se prijavi z `VIEWER_USERNAME` ter `VIEWER_PASSWORD` iz `.env`. Pregledovalnik omogoča:
|
|
|
|
- filter od/do (čas je UTC),
|
|
- filter po napravi,
|
|
- iskanje po domeni, naslovu ali URL-ju,
|
|
- seznam do 500 zadnjih obiskov,
|
|
- pregled unikatnih domen s številom obiskov in zadnjim obiskom.
|
|
|
|
## Discord (neobvezno)
|
|
|
|
V `.env` nastavi `DISCORD_WEBHOOK_URL`. Najprej se zapis shrani v SQLite, nato se poskusi poslati Discordu. Neuspeh Discorda ne izbriše podatkov.
|
|
|
|
## Nastavitev razširitve
|
|
|
|
Javni `extension/config.js` vsebuje javni privzeti `collectorUrl`, prazen `apiToken` in prazen `deviceId`. Za lokalno uporabo lahko nastaviš kopijo; za upravljane naprave uporabi Chrome managed policy spodaj. Razširitev arhivira in pošilja tudi URL-je prenosov, nikoli pa vsebine prenesenih datotek. Token naj ne konča v repozitoriju. `manifest.json` vsebuje široko dovoljenje za HTTP/HTTPS gostitelje zato, da lahko izbereš lasten API naslov; če želiš strožje dovoljenje, zamenjaj `host_permissions` samo s svojim HTTPS naslovom.
|
|
|
|
## Objavljanje podpisane razširitve
|
|
|
|
Repozitorij in release asseti morajo biti javni ter anonimno dosegljivi prek HTTPS, sicer Chrome ne more preverjati posodobitev. V Gitei omogoči Actions runner z labelom `ubuntu-latest`. Workflow potrebuje najmanj `contents: write`; če Gitea tega ne preslika samodejno, mora imeti vgrajeni `GITEA_TOKEN` v nastavitvah repozitorija pravico za ustvarjanje releaseov in taga `updates`.
|
|
|
|
Gitea mora `.crx` servirati z `Content-Type: application/x-chrome-extension`; v konfiguracijo dodaj `[repository.mimetype_mapping]` z mapiranjem `.crx = application/x-chrome-extension`, ali enak header nastavi v reverse proxyju. Objavljalni skript pred objavo `updates.xml` anonimno preveri HTTP 200, CRX3 glavo in ta MIME tip.
|
|
|
|
Ustvari en RSA zasebni ključ v PEM obliki zunaj repozitorija, ga varno shrani in kot `CRX_PRIVATE_KEY` dodaj v repo Actions secrets (na primer `tmpdir=$(mktemp -d) && openssl genrsa -out "$tmpdir/history-collector.pem" 2048 && chmod 600 "$tmpdir/history-collector.pem"`). Ključa nikoli ne rotiraj: s tem bi se spremenil ID razširitve. Ob tagu `vX.Y.Z` ali `vX.Y.Z.N`, ki se mora ujemati z `version` v `extension/manifest.json`, workflow zgradi in preveri CRX3, ZIP, checksums, `extension-id.txt` in `updates.xml`. V verzionirani release objavi CRX/ZIP/checksums/ID, `updates.xml` pa v poseben prerelease/tag `updates`. ID dobiš iz `extension-id.txt` ali iz `chrome://extensions` pri podpisanem paketu.
|
|
|
|
Za bump spremeni manifest, commitaj in ustvari ustrezen tag, na primer `git tag v1.0.1 && git push origin v1.0.1`. V Windows Chromeu običajen off-store CRX potrebuje enterprise policy; brez podpisa auto-update ne deluje. Force-install policy uporabi:
|
|
|
|
```text
|
|
ExtensionInstallForcelist = <EXTENSION_ID>;https://git.komelt.dev/komelt/history-collector/releases/download/updates/updates.xml
|
|
```
|
|
|
|
V `ExtensionSettings` lahko za isti ID nastaviš `installation_mode: force_installed` in isti `update_url`. Managed storage politika je na Windowsu pod `HKLM\SOFTWARE\Policies\Google\Chrome\3rdparty\extensions\<EXTENSION_ID>\policy`; nastavi vrednosti `collectorUrl` (na primer `https://chrome.komelt.dev/v1/visits`), `apiToken` in `deviceId`. Te vrednosti preglasijo javne privzetke in ostanejo prek posodobitev. V podpisanem paketu je brez managed policy oddaljeno pošiljanje na API neaktivno; lokalni Native Messaging arhiv pa še vedno deluje.
|
|
|
|
Token, ki je bil prej commitan v `extension/config.js`, je še vedno v Git zgodovini: nemudoma ga prekliči in zamenjaj. Nikoli ne objavljaj API skrivnosti v javnem CRX.
|
|
|
|
## Windows native arhiv (neobvezno)
|
|
|
|
Repozitorij vključuje tudi Chrome razširitev in Windows Native Messaging host za lokalni, append-only arhiv obiskov v SQLite.
|
|
|
|
1. V Chromu odpri `chrome://extensions`, vklopi **Developer mode**, klikni **Load unpacked** in izberi mapo `extension`.
|
|
2. Kopiraj 32-znakovni ID razširitve.
|
|
3. V PowerShellu iz korena repozitorija zaženi:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\install-native-host.ps1 -ExtensionId TUKAJ_PRILEPI_ID
|
|
```
|
|
|
|
Lokalni arhiv se privzeto shrani v `%USERPROFILE%\ChromeHistoryArchive\history.sqlite3`. Za pošiljanje obiskov tudi na API uredi lokalni `extension/config.js`; vanj ne zapisuj tokena v commitu.
|