way/pigway-frame-flow

Fork 0

Files

T

渡口浪人 30bc5a0bad

Community checks / verify (push) Skipped

Details

Verify Frame Flow / verify (push) Failing after 11m49s

Details

fix: recognize displayed terminal versions and clean obsolete gallery remnants

2026-10-23 22:57:53 +08:00

9.1 KiB

Raw Blame History

PIGWay Frame Flow

开发环境目前支持 Python 3.14.x。参见贡献指南和安全问题报告。

简体中文 | English

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

图库与终端

图库分为来源图库和终端图库。每个来源有自己的生成方案；每个终端单选一个来源及其中一个方案，同一方案可以被多个终端共用。任务一次选图，分别生成相框与手表版本。参见使用与架构说明。

安装

使用 Docker Compose 部署。当前默认配置与已验证平台为 AMD64：

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 分开。

网页仅支持一个用户，不提供公开注册。密码为 8–256 位，支持密码管理器；使用带随机盐的 scrypt（N=16384、r=8、p=5）保存，旧哈希登录成功后自动升级。连续 5 次失败后按账号和来源 IP 限制登录 5 分钟。修改密码需验证当前密码，成功后撤销全部会话；写入请求校验 CSRF Token，登录拒绝跨来源请求。公网访问应通过 HTTPS，HTTPS 下会话 Cookie 自动启用 Secure。

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

使用 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/，重启后保留。

Synology Photos 可使用独立的 API 来源，无需 /photos 或 NFS 挂载；支持共享 / 当前账号个人空间、人物筛选和按需 XL 预览缓存。原图下载不在本次已验证支持范围内。见 API 来源与 Ubuntu 候选迁移说明。

功能与边界

中英文 Web 界面、深浅色主题、账号登录、设备面板与图片预览。
来源图库管理源画面和来源内生成方案；终端图库按绑定管理成品。NAS 选图支持分页、预览及元数据筛选，旧图库页面已退役，已有任务兼容逻辑保留。
保持比例的 contain/cover/smart 图片转换，彩色/灰度模式与照片数据源的横竖方向选择。
七种模板：家庭早报、天气、日历、一句话、照片与文字、每日诗词、系统告警。
拼图工作室支持 1–12 张图片的拼图与海报；可选 OpenAI 兼容接口排版，以及从数据源自动选图拼接。
绑定设备的定时任务、顺序/随机播放列表、带优先级的临时覆盖、恢复与持久化操作历史。
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 启动，也不访问其数据库。参见外部集成契约。

Console 监控接入提供独立只读 ZIP 插件，支持服务就绪、画框在线/电量及任务最近结果，见 Console 插件安装说明。

存储与安全

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

文档目录

历史记录支持服务端翻页、图片名称/请求 ID/任务 ID/来源搜索，以及状态、操作、设备和日期（上海时区）筛选；可选择当前页记录进行单条或批量删除，操作前需确认。删除仅从历史列表移除，内部执行凭据继续供图库来源、幂等及恢复使用，不会删除图片或取消任务；运行中的任务不能删除。

来源图库的源画面支持“星标保留”和“不再选用／恢复选用”，二者互斥；后续自动选图和自动拼图跳过被标记的照片。图片仍保留，可手动预览、生成或恢复。标记按来源和图片 ID 独立保存，不取消已提交任务，也不修改网盘原文件。

9.1 KiB Raw Blame History Unescape Escape