149 lines
6.3 KiB
Markdown
149 lines
6.3 KiB
Markdown
# Synology NAS deployment / 群晖部署
|
|
|
|
当前生产服务已迁至 Ubuntu Server（参见 `scripts/server-release.py`）。以下内容仅适用于自行选择群晖容器部署的安装，不代表当前生产环境。
|
|
|
|
Target: DS923+, DSM 7.4.1 (verified on target; originally specified 7.3.1), AMD64, Container Manager.
|
|
Directory: /volume2/docker/pigway-frame-flow. Default published port: 6005.
|
|
The container still listens on 18787; Compose maps host 6005 to container 18787.
|
|
Existing installations must update their own WEB_PORT and recreate the service to activate the change.
|
|
|
|
## 1. Package and upload / 打包上传
|
|
|
|
From the repository:
|
|
|
|
```sh
|
|
python3 scripts/package-nas.py
|
|
scp -O dist/pigway-frame-flow-nas.tar.gz nas-example:/tmp/pigway-frame-flow-nas.tar.gz
|
|
ssh nas-example
|
|
```
|
|
|
|
The package contains tracked source/config examples/scripts only, never .env,
|
|
actual keys, data or .git. It is a deployment artifact, not a Git backup.
|
|
Use `git bundle create frame-flow.bundle --all` separately for history backups.
|
|
|
|
## 2. Prepare project directory / 准备目录
|
|
|
|
Verify target is empty or explicitly backed up before extracting. Do not extract
|
|
onto another existing installation or other services. If the directory exists,
|
|
inspect it first; preserve its .env and data.
|
|
|
|
```sh
|
|
mkdir -p /volume2/docker/pigway-frame-flow
|
|
# Only for an empty/new target:
|
|
tar -xzf /tmp/pigway-frame-flow-nas.tar.gz -C /volume2/docker
|
|
cd /volume2/docker/pigway-frame-flow
|
|
mkdir -p data/images data/generated data/cache config
|
|
sudo chown -R 10333:10333 data config
|
|
cp .env.example .env
|
|
chmod 600 .env
|
|
```
|
|
|
|
Edit `.env` on the NAS. Set FRAME_FLOW_TOKEN to a strong random token. API key
|
|
stays empty. KOKONNA_MOCK=true and KOKONNA_WRITE_ENABLED=false.
|
|
Set WEB_BIND to the actual NAS LAN address (recommended) or explicitly 0.0.0.0;
|
|
WEB_PORT=6005. The latter binds every NAS interface, so use the LAN IP when
|
|
strict LAN-only binding is required. No firewall/router/proxy edits are performed.
|
|
Copy deploy/devices.yml.example to config/devices.yml if multiple devices are desired.
|
|
|
|
Set `FRAME_FLOW_STORAGE_NAME` to the NAS display name. The gallery tab shows
|
|
this name followed by “本地图库” (or “Local gallery”). For Actions deployment,
|
|
set the repository Variable of the same name. It is a display label, not a path.
|
|
|
|
## 3. Validate, build, start / 验证构建启动
|
|
|
|
Synology Docker is /usr/local/bin/docker. The SSH user may require sudo. Do not
|
|
change socket ownership, groups, Docker network settings or other containers.
|
|
|
|
```sh
|
|
sudo /usr/local/bin/docker compose config --quiet
|
|
sudo /usr/local/bin/docker compose build --pull
|
|
sudo /usr/local/bin/docker compose up -d
|
|
sudo /usr/local/bin/docker compose ps
|
|
sudo /usr/local/bin/docker compose logs --tail 100
|
|
sudo /usr/local/bin/docker inspect pigway-frame-flow \
|
|
--format 'id={{.Id}} started={{.State.StartedAt}} health={{.State.Health.Status}} restart={{.HostConfig.RestartPolicy.Name}} ports={{json .NetworkSettings.Ports}} mounts={{json .Mounts}} network={{json .NetworkSettings.Networks}}'
|
|
sudo /usr/local/bin/docker image inspect pigway-frame-flow:latest \
|
|
--format 'id={{.Id}} size={{.Size}} architecture={{.Architecture}}'
|
|
```
|
|
|
|
Do not print unfiltered `docker inspect`: its environment can contain keys/tokens.
|
|
Likewise do not print `docker compose config` without --quiet on a live installation.
|
|
Run the read-only smoke checker from a machine with Python and set FRAME_FLOW_URL
|
|
to http://NAS_LAN_IP:6005; FRAME_FLOW_TOKEN stays in private env/file.
|
|
|
|
Health: GET /health → 200. Readiness: GET /ready → 200 when SQLite, driver config,
|
|
auth and Scheduler are ready. Missing credentials in live mode → 503. The cloud
|
|
is not probed by readiness. Cloud loss does not cause healthcheck restart loops.
|
|
|
|
## 4. Verify persistence / 持久化
|
|
|
|
Create a disabled test schedule in Web UI and locally stage one image (Mock only).
|
|
Record the job and asset IDs, then:
|
|
|
|
```sh
|
|
sudo /usr/local/bin/docker compose restart pigway-frame-flow
|
|
```
|
|
|
|
Wait for healthy state, check /health and /ready, and verify the same job/asset
|
|
IDs and history remain. Database is data/frameflow.db with WAL/SHM alongside it;
|
|
back up while stopped or use SQLite backup API, not a lone live DB file copy.
|
|
Restart policy must read unless-stopped. Do not reboot the NAS for acceptance.
|
|
|
|
## 5. Live read-only verification / 实机只读
|
|
|
|
After Mock acceptance, fill KOKONNA_API_KEY; set mock=false, keep writes=false.
|
|
Recreate only this service to apply env. Query device and images metadata only.
|
|
Verify known model/geometry/timezone/name against real data; missing vendor model
|
|
fields are not claimed verified. No original downloads are necessary. Stop on
|
|
mismatch; never try to fix cloud state automatically. Obtain explicit owner
|
|
permission before any upload/switch/delete. See REAL_DEVICE_TEST.md.
|
|
|
|
## Layout
|
|
|
|
```
|
|
/volume2/docker/pigway-frame-flow/
|
|
docker-compose.yml
|
|
Dockerfile
|
|
.env
|
|
requirements.lock
|
|
pigway_frame_flow/
|
|
vendor/
|
|
scripts/
|
|
config/
|
|
data/
|
|
frameflow.db
|
|
images/
|
|
generated/
|
|
cache/
|
|
```
|
|
|
|
Container runs UID/GID 10333:10333; only data/config need ownership. Avoid recursive
|
|
ownership changes outside this project's paths. Standard Compose bridge is private
|
|
and isolated by project name. Logs use stdout/stderr with Docker's capped json-file.
|
|
No logs directory or Docker socket mount.
|
|
|
|
## Restricted Docker Hub connectivity
|
|
|
|
If Docker Hub is unreachable from NAS, import the exact official AMD64 base image
|
|
from a trusted download machine. Verify its manifest, compressed blob SHA-256 and
|
|
all uncompressed rootfs diff IDs before loading. With the verified local tag loaded:
|
|
|
|
```sh
|
|
sudo env DOCKER_BUILDKIT=1 /usr/local/bin/docker compose build \
|
|
--build-arg PYTHON_BASE=python:3.14.8-alpine3.24
|
|
```
|
|
|
|
This per-build override does not change global registry or network configuration.
|
|
|
|
A slow Alpine CDN can be overridden for this build, retaining APK signature
|
|
verification and changing no NAS system settings:
|
|
|
|
```sh
|
|
sudo /usr/local/bin/docker compose build --build-arg ALPINE_MIRROR=mirrors.tuna.tsinghua.edu.cn
|
|
```
|
|
|
|
Optional `build-cache/wheels/` can hold all locked Linux AMD64/Python 3.14 musllinux wheels
|
|
and `SHA256SUMS`, verified against official PyPI release metadata. Builds verify
|
|
the manifest and use pip `--no-index`; incomplete caches fail explicitly.
|
|
Build commit/time are set after dependency installation to preserve build cache.
|