Pigway Frame Flow

简体中文 | English

轻量、自托管的智能画框自动化平台，可独立运行在 NAS 或服务器上，提供自己的 Web 界面、图库、图片渲染、调度器和 REST API。KoKonna 是支持的设备集成之一；外部应用无需持有它的凭据或引入其 SDK。

安装

在 AMD64 主机上使用 Docker Compose：

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:18787，使用刚创建的账号登录。网页使用 HttpOnly 会话 Cookie，无需输入 API Token；勾选记住登录后会话有效期为 30 天，可在设置中修改密码或退出。FRAME_FLOW_TOKEN 用于外部 API 客户端鉴权，与 KoKonna API Key 分开。

默认端口只绑定本机回环地址。需要局域网访问时，显式将 WEB_BIND 设置为 NAS 的局域网地址，并通过 WEB_PORT 选择空闲端口。参见群晖部署、构建镜像源与缓存和 Gitea 部署与回滚。不会自动修改防火墙、路由器或反向代理。

使用 Python 3.14 运行本地 Mock 演示：

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 界面、深浅色主题、账号登录、设备面板与图片预览。
本地暂存和 KoKonna 云端图库，上传、切换、星标、来源/任务筛选及批量操作。
保持比例的 contain/cover/smart 图片转换，彩色/灰度模式与照片数据源的横竖方向选择。
七种模板：家庭早报、天气、日历、一句话、照片与文字、每日诗词、系统告警。
拼图工作室支持 1–12 张图片的拼图与海报；可选 OpenAI 兼容接口排版，以及从数据源自动选图拼接。
绑定设备的定时任务、顺序/随机播放列表、带优先级的临时覆盖、恢复与持久化操作历史。
只读 NAS 文件夹、Synology Photos 人物筛选、WebDAV 和可选网盘连接器；每个数据源独立配置、独立授权。
可选天气、日历、监控、AI、MQTT 与 Webhook 集成。需要配置对应 Provider；尚未授权的数据源不会被当作已连接。

模板会生成图片，纯文字模板也是如此。使用顺序是：选择模板 → 编辑内容 → 生成预览 → 显示到画框。生成预览和保存模板设置都不会更新画框。“照片与文字”和“家庭早报”可以包含指定的本地照片，其他模板不会自动选图；定时模板任务每次运行会重新渲染。参见照片数据源、自动拼图和集成配置及限制。

天气使用配置的服务和地点，在渲染时更新，不会自行刷新已显示的图片。KoKonna 官方小组件与 Frame Flow 模板是两项独立能力；使用官方小组件需要额外授权厂商账号，API Key 接入仍可单独使用。

设备集成与 API

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 启动，也不访问其数据库。参见外部集成契约。

存储与安全

Docker 持久化 /data/frameflow.db、/data 下的图片/生成文件/缓存，以及 /config 下的私有配置和会话文件。容器以 UID/GID 10333 运行，根文件系统只读，使用独立桥接网络、unless-stopped 重启策略和有大小限制的标准输出日志；不需要 privileged、host network 或 Docker socket。

账号密码保存为哈希，网页修改操作有 CSRF 校验。API Key 和 Provider 凭据仅留在服务端，不得提交 Git 或写入日志。CORS 默认不开启，需明确配置来源。/health 检查服务自身，/ready 检查本地依赖，不以云端可用性触发重启。参见公开仓库隐私、LICENSE 和 NOTICE。

KoKonna 是支持的设备集成。本项目与 KoKonna 无隶属关系，也不代表其官方认可。

开发与已知限制

.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 每日艺术调度、更多日历重复规则及设备驱动仍属于后续计划。

6.8 KiB Raw Blame History Unescape Escape

Pigway Frame Flow

安装

功能与边界

设备集成与 API

存储与安全

开发与已知限制

6.8 KiB

Raw Blame History