<p><img src="docs/brand/pigway-logo.png" alt="PIGWay" width="96" height="96"></p>

# PIGWay Frame Flow

开发环境目前支持 Python 3.14.x。参见[贡献指南](CONTRIBUTING.md)和[安全问题报告](SECURITY.md)。

简体中文 | [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 分开。

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

默认端口只绑定本机回环地址。需要局域网访问时，显式将 `WEB_BIND` 设置为 NAS 的局域网地址，并通过 `WEB_PORT` 选择空闲端口。参见[群晖部署](docs/NAS.md)、[构建镜像源与缓存](docs/BUILDING.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/`，重启后保留。

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

### 功能与边界

- 中英文 Web 界面、深浅色主题、账号登录、设备面板与图片预览。
- NAS 本地图库和 KoKonna 云端图库；星标、来源/任务筛选及批量操作位于本地图库，上传到云端并显示需单独操作。
- 保持比例的 contain/cover/smart 图片转换，彩色/灰度模式与照片数据源的横竖方向选择。
- 七种模板：家庭早报、天气、日历、一句话、照片与文字、每日诗词、系统告警。
- 拼图工作室支持 1–12 张图片的拼图与海报；可选 OpenAI 兼容接口排版，以及从数据源自动选图拼接。
- 绑定设备的定时任务、顺序/随机播放列表、带优先级的临时覆盖、恢复与持久化操作历史。
- 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)。

Console 监控接入提供独立只读 ZIP 插件，支持服务就绪、画框在线/电量及任务最近结果，见 [Console 插件安装说明](https://tea.pigway.com/way/pigway-console-adapter-frame-flow/src/branch/main/README.zh-CN.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)

[文档目录](docs/README.md)