94 lines
6.9 KiB
Markdown
94 lines
6.9 KiB
Markdown
# Pigway Frame Flow
|
||
|
||
简体中文 | [English](README.md)
|
||
|
||
轻量、自托管的智能画框自动化平台，可独立运行在 NAS 或服务器上，提供自己的 Web 界面、图库、图片渲染、调度器和 REST API。KoKonna 是支持的设备集成之一；外部应用无需持有它的凭据或引入其 SDK。
|
||
|
||
### 安装
|
||
|
||
使用 Docker Compose 部署。当前默认配置与已验证平台为 AMD64：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 设置强 FRAME_FLOW_TOKEN；首次保持 mock=true、writes=false。
|
||
chmod 600 .env
|
||
mkdir -p data/images data/generated data/cache config
|
||
sudo chown -R 10333:10333 data config
|
||
./scripts/build-verify.sh
|
||
# 创建网页管理员账号，密码通过交互输入。
|
||
docker compose run --rm --no-deps -e PYTHONPATH=/app \
|
||
-v "$PWD/scripts:/bootstrap:ro" --entrypoint python pigway-frame-flow \
|
||
/bootstrap/create-account.py --username admin --config-dir /config
|
||
docker compose up -d
|
||
```
|
||
|
||
打开 `http://127.0.0.1:6005`，使用刚创建的账号登录。网页使用 HttpOnly 会话 Cookie，无需输入 API Token；勾选记住登录后会话有效期为 30 天，可在设置中修改密码或退出。`FRAME_FLOW_TOKEN` 用于外部 API 客户端鉴权，与 KoKonna API Key 分开。
|
||
|
||
默认端口只绑定本机回环地址。需要局域网访问时，显式将 `WEB_BIND` 设置为 NAS 的局域网地址，并通过 `WEB_PORT` 选择空闲端口。参见[群晖部署](docs/NAS.md)、[构建镜像源与缓存](docs/BUILDING.md)和 [Gitea 部署与回滚](docs/deployment/GITEA_CD.md)。不会自动修改防火墙、路由器或反向代理。
|
||
|
||
使用 Python 3.14 运行本地 Mock 演示：
|
||
|
||
```bash
|
||
python3.14 -m venv .venv
|
||
.venv/bin/python -m pip install -r requirements.lock
|
||
.venv/bin/python scripts/create-account.py --username admin
|
||
.venv/bin/python scripts/run_local.py
|
||
```
|
||
|
||
演示强制使用 Mock，并关闭设备写入。数据与配置保存在 `data/`、`config/`，重启后保留。
|
||
|
||
### 功能与边界
|
||
|
||
- 中英文 Web 界面、深浅色主题、账号登录、设备面板与图片预览。
|
||
- NAS 本地图库和 KoKonna 云端图库；星标、来源/任务筛选及批量操作位于本地图库，上传到云端并显示需单独操作。
|
||
- 保持比例的 contain/cover/smart 图片转换，彩色/灰度模式与照片数据源的横竖方向选择。
|
||
- 七种模板：家庭早报、天气、日历、一句话、照片与文字、每日诗词、系统告警。
|
||
- 拼图工作室支持 1–12 张图片的拼图与海报；可选 OpenAI 兼容接口排版，以及从数据源自动选图拼接。
|
||
- 绑定设备的定时任务、顺序/随机播放列表、带优先级的临时覆盖、恢复与持久化操作历史。
|
||
- 只读 NAS 文件夹、Synology Photos 人物筛选、WebDAV 和可选网盘连接器；每个数据源独立配置、独立授权。
|
||
- 可选天气、日历、监控、AI、MQTT 与 Webhook 集成。需要配置对应 Provider；尚未授权的数据源不会被当作已连接。
|
||
|
||
模板会**生成图片**，纯文字模板也是如此。使用顺序是：选择模板 → 编辑内容 → 生成预览 → 显示到画框。生成预览和保存模板设置都不会更新画框。“照片与文字”和“家庭早报”可以包含指定的本地照片，其他模板不会自动选图；定时模板任务每次运行会重新渲染。参见[照片数据源](docs/PHOTO_SOURCES.md)、[自动拼图](docs/AUTOMATIC_COLLAGE.md)和[集成配置及限制](docs/EXTENSIONS.md)。
|
||
|
||
天气使用配置的服务和地点，在渲染时更新，不会自行刷新已显示的图片。KoKonna 官方小组件与 Frame Flow 模板是两项独立能力；使用官方小组件需要额外授权厂商账号，API Key 接入仍可单独使用。
|
||
|
||
### 设备集成与 API
|
||
|
||
```text
|
||
Provider → 模板 / Renderer → 生成图片
|
||
Web UI / Scheduler / REST API → DisplayService → FrameDeviceDriver → KoKonna
|
||
↓
|
||
SQLite：任务、操作、历史、覆盖状态、图片
|
||
```
|
||
|
||
设备 Key 通过私有 `.env` 或 Secret 文件配置。首次保持 `KOKONNA_MOCK=true`、`KOKONNA_WRITE_ENABLED=false`，Mock 验证后先只读连接，再明确开启写入。多设备使用 `config/devices.yml` 配置，每台设备引用自己的 Key。厂商代码位于 `drivers/kokonna`；Web 界面与外部程序使用相同业务服务。
|
||
|
||
正式 API 为 `/api/v1`，OpenAPI 位于 `/openapi.json`，Swagger 位于 `/docs`。显示、渲染、上传返回 HTTP 202 和操作 ID，通过 `/api/v1/operations/{id}` 查询结果。`Idempotency-Key` 防止重复派发，`X-Request-ID` 串联请求与历史。写入结果不确定时会阻止后续修改，必须只读核对或由管理员明确确认，不会自动重放写请求。
|
||
|
||
Ticktar 集成为可选项，Frame Flow 不依赖 Ticktar 启动，也不访问其数据库。参见[外部集成契约](docs/integrations/TICKTAR.md)。
|
||
|
||
### 存储与安全
|
||
|
||
Docker 持久化 `/data/frameflow.db`、`/data` 下的图片/生成文件/缓存，以及 `/config` 下的私有配置和会话文件。容器以 UID/GID 10333 运行，根文件系统只读，使用独立桥接网络、`unless-stopped` 重启策略和有大小限制的标准输出日志；不需要 privileged、host network 或 Docker socket。
|
||
|
||
账号密码保存为哈希，网页修改操作有 CSRF 校验。API Key 和 Provider 凭据仅留在服务端，不得提交 Git 或写入日志。CORS 默认不开启，需明确配置来源。`/health` 检查服务自身，`/ready` 检查本地依赖，不以云端可用性触发重启。参见[公开仓库隐私](docs/PUBLICATION.md)、[LICENSE](LICENSE) 和 [NOTICE](NOTICE.md)。
|
||
|
||
KoKonna 是支持的设备集成。本项目与 KoKonna 无隶属关系，也不代表其官方认可。
|
||
|
||
### 开发与已知限制
|
||
|
||
```bash
|
||
.venv/bin/python -m pip install -e '.[test]'
|
||
.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 pytest -q
|
||
.venv/bin/python -m pip_audit -r requirements.lock --no-deps --disable-pip
|
||
```
|
||
|
||
测试使用 Mock 云端/设备调用；CI 还验证隔离的 Docker 构建、就绪检查、smoke test、重启与清理。外部 Fork PR 不会在可访问生产环境的 NAS Runner 上执行。
|
||
|
||
云端同步不等于已确认物理屏幕刷新。KoKonna 云端上传会立即切换，因此“仅上传”使用本地暂存。官方接口不支持编辑原生轮播成员，应避免原生轮播与 Frame Flow 播放同时运行。smart 裁切采用显著性启发式，不保证识别人脸。当前服务使用单 Worker，不面向多副本部署。浏览器 OAuth、AI 每日艺术调度、更多日历重复规则及设备驱动仍属于后续计划。
|
||
|
||
相关项目：[PIGWay Raspberry Pi Agent](https://tea.pigway.com/way/pigway-raspberry-pi-agent) · [PIGWay Device Console](https://tea.pigway.com/way/pigway-device-console) · [PIGWay Yahboom Cooling HAT](https://tea.pigway.com/way/pigway-yahboom-cooling-hat)
|