Build Pigway Frame Flow with bilingual UI, complete KoKonna driver and safe automation
This commit is contained in:
Pigway
@@ -0,0 +1,161 @@
|
||||
# Pigway Frame Flow
|
||||
|
||||
Pigway Frame Flow is a lightweight self-hosted platform for programmable smart-frame automation.
|
||||
|
||||
独立运行的智能画框服务：中英文 Web UI、深浅色模式、设备驱动抽象、KoKonna 全部已公开接口、图片处理、模板、SQLite 调度与播放列表、临时覆盖恢复和 REST API。
|
||||
|
||||
KoKonna is a supported device integration and is not affiliated with this project unless otherwise stated.
|
||||
|
||||
## Quick Start / 快速开始
|
||||
|
||||
```sh
|
||||
python3 -m venv .venv
|
||||
.venv/bin/python -m pip install -r requirements.lock
|
||||
.venv/bin/python scripts/run_local.py
|
||||
```
|
||||
|
||||
Open http://127.0.0.1:18787. The local demo creates a private `.env` with a random
|
||||
FRAME_FLOW_TOKEN. Read that token locally in an editor and enter it on the login
|
||||
screen. Do not paste a KoKonna API Key into Web UI. Demo always forces mock mode
|
||||
and disables real writes. It leaves data persistent in ./data and ./config.
|
||||
|
||||
打开页面后输入 `.env` 中的 FRAME_FLOW_TOKEN；Token 只留在当前页面内存，刷新后需重新输入。
|
||||
|
||||
## Architecture / 架构
|
||||
|
||||
```
|
||||
providers → templates / renderers → generated image
|
||||
↓
|
||||
Web UI / external REST → DisplayService → FrameDeviceDriver → KokonnaDriver
|
||||
Scheduler / Playlist ─────────────┘
|
||||
SQLite: operations / history / jobs / overrides / assets
|
||||
```
|
||||
|
||||
Package: pigway_frame_flow. Device composition is in core/registry.py;
|
||||
vendor-specific code is in drivers/kokonna. One process, one worker, no Redis,
|
||||
message broker, OpenClaw, Home Assistant or external application dependency.
|
||||
|
||||
## Configuration / 配置
|
||||
|
||||
Copy `.env.example` to `.env`, set a strong FRAME_FLOW_TOKEN, chmod 600 .env.
|
||||
- KOKONNA_MOCK=true: independent persistent demo, no cloud calls.
|
||||
- KOKONNA_WRITE_ENABLED=false: live write protection, mandatory before verification.
|
||||
- KOKONNA_API_KEY: device key, never stored in DB or returned to Web UI.
|
||||
- *_FILE: optional Docker Secret equivalent.
|
||||
- WEB_BIND/WEB_PORT: Compose host bind and port. Internal app binds container network.
|
||||
- CORS_ALLOWED_ORIGINS: exact comma-separated origins; default empty.
|
||||
- IMAGE_URL_ALLOWED_HOSTS: exact public HTTPS hosts; default disabled. Redirects denied.
|
||||
- TZ=Asia/Shanghai; DATA_DIR=/data; CONFIG_DIR=/config.
|
||||
|
||||
For multiple devices copy deploy/devices.yml.example into config/devices.yml,
|
||||
reference a separate environment key per device. Jobs bind a device_id. Layout
|
||||
currently targets 1200 × 1600; incompatible geometry is refused before writes.
|
||||
|
||||
## Docker
|
||||
|
||||
```sh
|
||||
cp .env.example .env
|
||||
# Configure a token; keep API key empty, mock true, writes false.
|
||||
mkdir -p data/images data/generated data/cache config
|
||||
sudo chown -R 10333:10333 data config
|
||||
./scripts/build-verify.sh
|
||||
docker compose up -d
|
||||
python3 scripts/smoke-test.py
|
||||
```
|
||||
|
||||
Image pigway-frame-flow:latest, service/container pigway-frame-flow, AMD64,
|
||||
Python 3.14.5, pinned runtime dependencies, CJK fonts, non-root UID/GID 10333,
|
||||
read-only root filesystem, writable /data and /config, no capabilities, no host
|
||||
network, no Docker socket. Restart unless-stopped. JSON-file logs capped 10m × 3.
|
||||
Healthcheck uses service /health, not cloud availability. No second log database.
|
||||
|
||||
## Synology NAS
|
||||
|
||||
Target `/volume1/docker/pigway-frame-flow/`. See [NAS deployment](docs/NAS.md).
|
||||
Set WEB_BIND to the NAS LAN IP to restrict the published interface, or explicitly
|
||||
0.0.0.0 when desired. Port 18787 must be free. No router/firewall/reverse proxy
|
||||
rules are modified. Source and persistent volumes stay in this project directory.
|
||||
No artificial logs directory is required. Compose creates its own bridge network.
|
||||
|
||||
## KoKonna Setup / 真实设备
|
||||
|
||||
First deploy Mock and verify persistence. Then set KOKONNA_MOCK=false and fill
|
||||
KOKONNA_API_KEY through private environment/secret. Keep writes false. /ready checks
|
||||
configuration/DB/worker/token without a cloud call. Query device and images metadata;
|
||||
compare model, geometry, timezone, heartbeat, battery, imageId, coverId, sync.
|
||||
If different, stop and report. **Do not enable writes or perform the single test
|
||||
until the owner explicitly authorizes it.** Test design: [REAL_DEVICE_TEST.md](docs/REAL_DEVICE_TEST.md).
|
||||
|
||||
## Security
|
||||
|
||||
All protected /api/v1 capabilities use Frame Flow Bearer auth and scope checks.
|
||||
SQLite stores token hashes. Device keys live only in env/secret and runtime memory.
|
||||
Cloud original-image endpoint embeds a key upstream; backend proxies it with no
|
||||
redirects and no access/transport logging. Key never enters browser URLs or DB.
|
||||
Request validation and exceptions use sanitized standard errors. Strong tokens,
|
||||
trusted LAN and no public exposure are the intended deployment model.
|
||||
|
||||
## API
|
||||
|
||||
OpenAPI 3.x at /openapi.json; Swagger at /docs; stable /api/v1. Display/render/upload
|
||||
return 202 + operation_id. Poll /api/v1/operations/{id}; completion requires matching
|
||||
image ID and cloud synced flag. Idempotency-Key retained seven days. X-Request-ID
|
||||
traces history. UNKNOWN writes block later mutations; read-only reconciliation
|
||||
and explicit admin acknowledgement release the block, never replay a write.
|
||||
The older /api/display route is retained and deprecated (same v1 payload).
|
||||
See [external integration contract](docs/integrations/TICKTAR.md).
|
||||
|
||||
## Scheduler / Playback
|
||||
|
||||
Cron (5 fields), daily, weekdays, weekends, date and temporary tasks; Shanghai time.
|
||||
Use source {"type":"restore"} for explicit restore jobs. Unique job/slot and persistent
|
||||
idempotency prevent duplicate dispatch. Overdue tasks >5 minutes are skipped rather
|
||||
than unexpectedly overwriting artwork after downtime. State persists across restart.
|
||||
Overrides use priority then recency; lower priorities wait without uploading.
|
||||
If another app changes the frame, expired overrides do not overwrite its artwork.
|
||||
Frame Flow playlists support ordered/random cloud image IDs and >=5-minute intervals;
|
||||
only one enabled playlist per device. They pause for overrides/unknown writes.
|
||||
Native cloud slideshow mode/interval are readable; membership/editing are unavailable
|
||||
in the official API. Avoid having native and Frame Flow playback compete.
|
||||
|
||||
## Templates / 图片
|
||||
|
||||
Six JSON layout templates: daily-dashboard, weather, calendar, quote, photo-text,
|
||||
system-alert. color and grayscale profiles. Photo data accepts photo_id = local asset
|
||||
ID. Mock weather is clearly labeled; no unreliable lunar date is fabricated.
|
||||
Contain preserves composition with margins; cover crops centrally; smart is an
|
||||
edge-saliency heuristic. Always inspect preview; face-aware guarantees are not claimed.
|
||||
Cloud uploads activate immediately, so gallery-only means **local staging**.
|
||||
|
||||
## Development / Testing
|
||||
|
||||
```sh
|
||||
.venv/bin/python -m pip install -e '.[test]'
|
||||
.venv/bin/python -m pytest -q
|
||||
.venv/bin/python -m ruff check pigway_frame_flow tests scripts
|
||||
.venv/bin/python -m ruff format --check pigway_frame_flow tests scripts
|
||||
.venv/bin/python -m mypy pigway_frame_flow
|
||||
.venv/bin/python -m pip_audit -r requirements.lock --no-deps --disable-pip
|
||||
```
|
||||
|
||||
Tests mock every cloud request; no real-device writes. scripts/ui-smoke.cjs runs an
|
||||
isolated headless browser and checks settings.mock before acting. CI builds AMD64,
|
||||
validates Compose, starts a container, checks health/ready and restarts for persistence.
|
||||
|
||||
## Known Limitations / 已知边界
|
||||
|
||||
Cloud acknowledgements do not prove physical display pixels. Model fields may be
|
||||
omitted and are explicitly marked configured. No native slideshow membership API,
|
||||
no cloud upload-only API, no automatic retries after uncertain writes. Cache has no
|
||||
automatic quota/GC in 0.1.0; monitor data volume. Rendering assets are local, limited
|
||||
to 25M pixels/20 MiB. This release uses a single worker and is not multi-replica.
|
||||
Gallery reads have no pagination because upstream documents none. Web UI hides
|
||||
secrets and lazy-loads thumbnails; generating a first thumbnail fetches one original.
|
||||
Multi-client provisioning UI/webhook delivery are not implemented. Docker build/NAS
|
||||
status is recorded honestly in docs/ACCEPTANCE.md.
|
||||
|
||||
## Roadmap
|
||||
|
||||
Additional drivers; scoped token administration; signed webhooks; cache retention;
|
||||
face-aware cropping; public weather provider; Google Calendar, Home Assistant, MQTT,
|
||||
NAS monitoring and AI integrations through the same API. External integration is optional.
|
||||
Reference in New Issue
Block a user