diff --git a/README.md b/README.md index f1573bc..abab6de 100644 --- a/README.md +++ b/README.md @@ -196,6 +196,11 @@ those fixed nodes and does not provide complete multi-device or hot-plug discove The GHCR image is published for `linux/amd64` and `linux/arm64`. +> [!TIP] +> **NAS / QNAP Container Station Deployment Note**: +> On NAS operating systems like QNAP QTS / QuTS hero (Container Station), custom non-root administrator accounts and volume isolation mechanisms may cause Docker named volumes (e.g. `-v vocat-data:/opt/vocat/data`) to resolve to different isolated paths between the one-off `bootstrap-admin` initialization and the daemon service container, leading to "Incorrect password" errors during Web login. +> For NAS environments, it is strongly recommended to replace named volumes with a host absolute path bind mount (e.g. `-v /share/Container/vocat/data:/opt/vocat/data` on QNAP) for both initialization and runtime to guarantee consistent SQLite database persistence. + ### USB SIM readers USB SIM readers use the Linux PC/SC service. The one-click installer installs diff --git a/docker-compose.yml b/docker-compose.yml index c73e21d..b242dbb 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -53,6 +53,9 @@ services: volumes: # SQLite database + persistent state. + # Note for NAS (e.g. QNAP Container Station / Synology): replace named volume + # with a host absolute path (e.g. /share/Container/vocat/data:/opt/vocat/data) + # to avoid volume isolation issues between bootstrap-admin and runtime. - vocat-data:/opt/vocat/data # Required for modem, MHI/WWAN and PC/SC USB-reader discovery, including # devices added after the container starts. diff --git a/docs/README.ar.md b/docs/README.ar.md index d632d83..75e59da 100644 --- a/docs/README.ar.md +++ b/docs/README.ar.md @@ -185,6 +185,11 @@ Quectel USB المدعومة (معرّف الشركة المصنعة USB `2c7c`) تُنشر صورة GHCR لـ `linux/amd64` و`linux/arm64`. +> [!TIP] +> **ملاحظة حول النشر على NAS / QNAP Container Station**: +> في أنظمة NAS مثل QNAP QTS / QuTS hero (Container Station)، قد تؤدي حسابات المشرفين المخصصة وآليات عزل وحدات التخزين إلى توجيه وحدات تخزين Docker المسماة (مثل `-v vocat-data:/opt/vocat/data`) إلى مسارات معزولة مختلفة بين أمر التهيئة `bootstrap-admin` وحاوية الخدمة الرئيسية، مما يتسبب في ظهور خطأ في كلمة المرور عند تسجيل الدخول عبر الويب. +> بالنسبة لبيئات NAS، يوصى بشدة باستبدال وحدات التخزين المسماة بربط مسار مطلق على المضيف (مثل `-v /share/Container/vocat/data:/opt/vocat/data` على QNAP) لكل من التهيئة والتشغيل لضمان استمرارية متسقة لقاعدة بيانات SQLite. + ## الإعدادات يقرأ Vocat ملف إعدادات JSON اختياريًا من `VOCAT_CONFIG`، ثم يطبق متغيرات البيئة `VOCAT_*`. متغيرات البيئة لها الأولوية. diff --git a/docs/README.es.md b/docs/README.es.md index bbfef05..91e83de 100644 --- a/docs/README.es.md +++ b/docs/README.es.md @@ -187,6 +187,11 @@ dispositivos o de conexión en caliente. La imagen GHCR se publica para `linux/amd64` y `linux/arm64`. +> [!TIP] +> **Nota sobre el despliegue en NAS / QNAP Container Station**: +> En sistemas NAS como QNAP QTS / QuTS hero (Container Station), las cuentas de administrador personalizadas y el aislamiento de volúmenes pueden hacer que los volúmenes con nombre de Docker (ej. `-v vocat-data:/opt/vocat/data`) se resuelvan en rutas aisladas distintas entre la inicialización `bootstrap-admin` y el contenedor del servicio principal, provocando errores de contraseña incorrecta al iniciar sesión en la interfaz web. +> En entornos NAS, se recomienda encarecidamente sustituir los volúmenes con nombre por un montaje bind con ruta absoluta del host (ej. `-v /share/Container/vocat/data:/opt/vocat/data` en QNAP) tanto para la inicialización como para la ejecución, garantizando la persistencia coherente de la base de datos SQLite. + ## Configuración Vocat lee un archivo de configuración JSON opcional desde `VOCAT_CONFIG` y luego aplica las variables de entorno `VOCAT_*`. Las variables de entorno tienen prioridad. diff --git a/docs/README.fr.md b/docs/README.fr.md index 65fbb1b..bd201ff 100644 --- a/docs/README.fr.md +++ b/docs/README.fr.md @@ -187,6 +187,11 @@ pas une découverte multi-périphériques ou à chaud complète. L'image GHCR est publiée pour `linux/amd64` et `linux/arm64`. +> [!TIP] +> **Note de déploiement NAS / QNAP Container Station** : +> Sur les systèmes NAS tels que QNAP QTS / QuTS hero (Container Station), les comptes administrateurs personnalisés et les mécanismes d'isolation de volumes peuvent faire en sorte que les volumes nommés Docker (ex. `-v vocat-data:/opt/vocat/data`) soient résolus vers des chemins isolés différents entre l'initialisation unique `bootstrap-admin` et le conteneur de service principal, entraînant des erreurs de mot de passe incorrect sur l'interface Web. +> Pour les environnements NAS, il est fortement recommandé de remplacer les volumes nommés par un montage bind avec chemin absolu de l'hôte (ex. `-v /share/Container/vocat/data:/opt/vocat/data` sur QNAP) pour l'initialisation et l'exécution afin de garantir une persistance cohérente de la base de données SQLite. + ## Configuration Vocat lit un fichier de configuration JSON optionnel depuis `VOCAT_CONFIG`, puis applique les variables d'environnement `VOCAT_*`. Les variables d'environnement ont la priorité. diff --git a/docs/README.ja.md b/docs/README.ja.md index 497766b..a1457e0 100644 --- a/docs/README.ja.md +++ b/docs/README.ja.md @@ -169,6 +169,11 @@ docker run -d \ GHCR イメージは `linux/amd64` と `linux/arm64` 向けに公開されています。 +> [!TIP] +> **NAS / QNAP Container Station デプロイ時の注意点**: +> QNAP QTS / QuTS hero (Container Station) などの NAS 環境では、非 root カスタム管理者権限とボリューム分離メカニズムにより、Docker の名前付きボリューム（例: `-v vocat-data:/opt/vocat/data`）を使用すると、初回の `bootstrap-admin` 初期化時とデーモン起動時で異なる隔離パスに書き込まれ、Web ログイン時にパスワードエラーとなる場合があります。 +> NAS 環境では、初期化と常駐コンテナの両方で名前付きボリュームの代わりにホストの絶対パスバインドマウント（例: QNAP の `-v /share/Container/vocat/data:/opt/vocat/data`）を使用することを推奨します。 + ## 設定 Vocat は `VOCAT_CONFIG` からオプションの JSON 設定ファイルを読み込み、次に `VOCAT_*` 環境変数を適用します。環境変数が優先されます。 diff --git a/docs/README.ru.md b/docs/README.ru.md index 1e97140..36d54bf 100644 --- a/docs/README.ru.md +++ b/docs/README.ru.md @@ -186,6 +186,11 @@ TUN, настройки сети и устройств, добавленных Образ GHCR публикуется для `linux/amd64` и `linux/arm64`. +> [!TIP] +> **Примечание по развертыванию на NAS / QNAP Container Station**: +> В системах NAS, таких как QNAP QTS / QuTS hero (Container Station), из-за нестандартных прав администратора и механизмов изоляции томов именованные тома Docker (например, `-v vocat-data:/opt/vocat/data`) могут разрешаться в разные изолированные пути между выполнением команды `bootstrap-admin` и основным контейнером службы, что приводит к ошибкам неверного пароля при входе через веб-интерфейс. +> Для сред NAS настоятельно рекомендуется использовать монтирование с абсолютным путем хоста (например, `-v /share/Container/vocat/data:/opt/vocat/data` на QNAP) как для инициализации, так и для запуска службы, чтобы гарантировать согласованность базы данных SQLite. + ## Конфигурация Vocat читает необязательный JSON-файл конфигурации из `VOCAT_CONFIG`, затем применяет переменные окружения `VOCAT_*`. Переменные окружения имеют приоритет. diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md index 37f175a..193b45a 100644 --- a/docs/README.zh-CN.md +++ b/docs/README.zh-CN.md @@ -175,6 +175,11 @@ docker run -d \ GHCR 镜像发布为 `linux/amd64` 与 `linux/arm64`。 +> [!TIP] +> **NAS / 威联通 (QNAP Container Station) 部署说明**： +> 在威联通等 NAS 系统的 Container Station 下部署时，由于系统的非 Root 自定义管理员权限与卷隔离机制，使用 Docker 命名卷（如 `-v vocat-data:/opt/vocat/data`）在执行一次性初始化 `bootstrap-admin` 和启动常驻服务时，两者的卷极易被解析至不同的隔离路径，导致 Web 端登录时提示密码错误。 +> 建议在 NAS 环境下部署时，将 `-v vocat-data:/opt/vocat/data` 替换为宿主机的绝对路径挂载（例如威联通上的 `-v /share/Container/vocat/data:/opt/vocat/data`），以确保初始化与运行期读写同一个 SQLite 数据库文件。 + ### USB SIM 读卡器 USB SIM 读卡器通过 Linux PC/SC 服务访问。一键安装脚本会在支持的软件包管理器上 diff --git a/docs/README.zh-TW.md b/docs/README.zh-TW.md index 758a465..d263c56 100644 --- a/docs/README.zh-TW.md +++ b/docs/README.zh-TW.md @@ -169,6 +169,11 @@ docker run -d \ GHCR 映像發佈為 `linux/amd64` 與 `linux/arm64`。 +> [!TIP] +> **NAS / 威聯通 (QNAP Container Station) 部署說明**： +> 在威聯通等 NAS 系統的 Container Station 下部署時，由於系統的非 Root 自訂管理員權限與磁碟區隔離機制，使用 Docker 具名磁碟區（如 `-v vocat-data:/opt/vocat/data`）在執行一次性初始化 `bootstrap-admin` 與啟動常駐服務時，兩者的磁碟區極易被解析至不同的隔離路徑，導致 Web 端登入時提示密碼錯誤。 +> 建議在 NAS 環境下部署時，將 `-v vocat-data:/opt/vocat/data` 替換為宿主機的絕對路徑掛載（例如威聯通上的 `-v /share/Container/vocat/data:/opt/vocat/data`），以確保初始化與執行期讀寫同一個 SQLite 資料庫檔案。 + ## 配置 Vocat 先從 `VOCAT_CONFIG` 讀取可選的 JSON 配置檔,再套用 `VOCAT_*` 環境變數。環境變數優先級更高。