105 lines
4.1 KiB
Markdown
105 lines
4.1 KiB
Markdown
Skinbase Enhance
|
|
================
|
|
|
|
Operational notes for the Enhance v1/v1.1 module.
|
|
|
|
For full setup, enablement, worker configuration, verification, and production rollout guidance, see [docs/enhance-setup.md](docs/enhance-setup.md).
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
- `ENHANCE_ENGINE=stub` keeps Enhance in preview mode for local and workflow testing.
|
|
- `ENHANCE_ENGINE=external_worker` uses the prepared external worker adapter boundary.
|
|
- `ENHANCE_QUEUE=default` is the current safe default.
|
|
- `ENHANCE_QUEUE=enhance` is supported when you want a dedicated queue later.
|
|
- If you switch to `ENHANCE_QUEUE=enhance`, Horizon or any worker process must explicitly consume the `enhance` queue in production.
|
|
|
|
Helpful commands
|
|
----------------
|
|
|
|
```bash
|
|
php artisan enhance:health
|
|
php artisan enhance:health --json
|
|
php artisan enhance:cleanup --dry-run
|
|
php artisan enhance:cleanup --force
|
|
php artisan queue:work --queue=enhance,default
|
|
```
|
|
|
|
Cleanup behavior
|
|
----------------
|
|
|
|
- Enhance cleanup only removes files under the configured Enhance prefixes:
|
|
- `enhance/sources`
|
|
- `enhance/outputs`
|
|
- `enhance/previews`
|
|
- Cleanup never deletes artwork originals, thumbnails, avatars, or other non-Enhance paths.
|
|
- Completed jobs can expire automatically via `ENHANCE_COMPLETED_EXPIRES_AFTER_DAYS`.
|
|
- Failed jobs can have stale files pruned via `ENHANCE_FAILED_EXPIRES_AFTER_DAYS`.
|
|
- Soft-deleted jobs respect `ENHANCE_DELETED_FILE_GRACE_DAYS` before file cleanup.
|
|
|
|
Scheduler
|
|
---------
|
|
|
|
- The app schedules `php artisan enhance:cleanup --force` daily from `routes/console.php`.
|
|
- If you disable Laravel's scheduler in an environment, run cleanup manually or through external cron.
|
|
|
|
Queue and Horizon reminder
|
|
--------------------------
|
|
|
|
- Stub mode still dispatches queued Enhance jobs and exercises the same lifecycle.
|
|
- If workers only consume `default` and you later move Enhance to a dedicated queue, completed jobs will stall in `queued` until `enhance` is added to the worker queue list.
|
|
|
|
External Worker v1
|
|
------------------
|
|
|
|
- Set `ENHANCE_ENGINE=external_worker` to switch Laravel from the stub processor to the HTTP worker integration.
|
|
- Recommended local Laravel env:
|
|
|
|
```env
|
|
ENHANCE_ENGINE=external_worker
|
|
ENHANCE_WORKER_URL=http://127.0.0.1:8095
|
|
ENHANCE_WORKER_TIMEOUT=600
|
|
ENHANCE_WORKER_TOKEN=change-this-token
|
|
ENHANCE_WORKER_MAX_DOWNLOAD_MB=60
|
|
ENHANCE_QUEUE=enhance
|
|
```
|
|
|
|
- Keep the worker bound to `127.0.0.1` or a private container network. Do not expose it publicly.
|
|
- Laravel sends the worker a short-lived source URL. If the storage disk cannot issue temporary URLs, Laravel falls back to a temporary signed internal route that serves only the copied Enhance source file.
|
|
- Laravel remains the source of truth: the worker only returns a temporary result, Laravel downloads it, validates it, stores it on the Enhance disk, and then asks the worker to delete the temporary file.
|
|
- Useful commands after enabling the worker:
|
|
|
|
```bash
|
|
php artisan config:clear
|
|
php artisan enhance:health
|
|
php artisan queue:work --queue=enhance,default
|
|
php artisan test --filter=EnhanceExternalWorker
|
|
```
|
|
|
|
Real-ESRGAN Runtime
|
|
-------------------
|
|
|
|
- Laravel still uses `ENHANCE_ENGINE=external_worker`. It does not need to know whether the worker uses Pillow or Real-ESRGAN internally.
|
|
- Use `WORKER_ENGINE=pillow` for local development, CI, and fallback operation.
|
|
- Use `WORKER_ENGINE=realesrgan-ncnn` for the real ncnn-vulkan runtime path.
|
|
- If worker health reports `status: degraded`, keep Laravel on the stub processor or a Pillow worker until the Real-ESRGAN runtime is verified.
|
|
- Do not expose the worker port publicly.
|
|
- Move to the `enhance` Horizon queue only after the worker is healthy and verified in your environment.
|
|
- Real-ESRGAN runtime files are not committed. Install them locally or in deployment with the worker scripts:
|
|
|
|
```bash
|
|
cd services/enhance-worker
|
|
bash scripts/download-realesrgan-ncnn.sh
|
|
bash scripts/verify-realesrgan.sh
|
|
```
|
|
|
|
- Recommended Laravel env when using the real worker:
|
|
|
|
```env
|
|
ENHANCE_ENGINE=external_worker
|
|
ENHANCE_QUEUE=enhance
|
|
ENHANCE_WORKER_URL=http://127.0.0.1:8095
|
|
ENHANCE_WORKER_TIMEOUT=900
|
|
ENHANCE_WORKER_TOKEN=change-this-token
|
|
ENHANCE_WORKER_MAX_DOWNLOAD_MB=60
|
|
``` |