116 lines
4.6 KiB
Markdown
116 lines
4.6 KiB
Markdown
# Synology NAS deployment / 群晖部署
|
|
|
|
Target: DS923+, DSM 7.3.1, AMD64, Container Manager.
|
|
Directory: /volume1/docker/pigway-frame-flow. Port: 18787.
|
|
|
|
## 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 /volume1/docker/pigway-frame-flow
|
|
# Only for an empty/new target:
|
|
tar -xzf /tmp/pigway-frame-flow-nas.tar.gz -C /volume1/docker
|
|
cd /volume1/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=18787. 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.
|
|
|
|
## 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:18787; 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
|
|
|
|
```
|
|
/volume1/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.
|