在群晖 Synology NAS 上部署 NetAlertX：Container Manager Project 编排、卷挂载与权限修复实战指南

• 后端
• 网络
• 运维
• 数据可视化

本指南完整讲解如何在 Synology NAS 上通过Container manager 的 Project（docker-compose）功能部署 NetAlertX，覆盖数据目录规划、compose 模板参数逐项解析、端口与卷路径调整，以及 Synology 上最常见的宿主目录权限问题（SSH 命令修复与任务计划程序 UI 修复两种方案）。读完本文，你将能在群晖上独立完成 NetAlertX 的容器化部署，并理解其底层权限模型（UID/GID 20211 与 root-priming 机制），为后续 Subnets 与 Plugins 配置打好基础。

NetAlertX 在 Synology 上的部署方式概览

在 Synology 上安装 NetAlertX 有多种途径，包括 SSH 登录后在命令行手动运行docker run。本指南选择Container manager -> Project方式，原因在于：

• Project 基于 docker-compose，可将镜像、网络、卷、环境变量等全部声明式地保存在一个 YAML 模板中，便于版本化与日后维护；
• 群晖的 Container manager 对 Project 提供了可视化创建、构建与日志查看入口，无需记忆大量 CLI 参数；
• 项目配置与数据库持久化在宿主机目录中，升级镜像、重建容器时数据不丢失。

部署完成后，NetAlertX 容器将承担集中式网络设备发现与监控任务：通过 ARP 扫描、DHCP 租约、各类导入插件持续发现设备、检测变更并产生通知。整个应用栈（详见 entrypoint.sh 的启动逻辑）包含 cron 调度器（supercronic）、php-fpm、nginx 与 Python 后端四个核心服务，由 entrypoint 统一拉起并监控。

第一步：创建宿主机数据目录结构

NetAlertX 的配置（config）与数据库（db）保存在宿主机目录中，容器崩溃或重建后仍可恢复。请定期备份这两个目录。

在文件管理器（File Station）中按以下步骤创建：

1. 在希望存放数据的磁盘（如volume1）下新建一个父文件夹，命名为netalertx；
2. 在其内部创建db子文件夹（存放 SQLite 数据库文件，如app.db，见 back/app.db）；
3. 在其内部创建config子文件夹（存放应用配置app.conf，见 back/app.conf 及设备启发式规则 device_heuristics_rules.json 等）；
4. 右键这两个子文件夹 -> 属性，记下各自的位置（Location），后续 compose 卷映射需要用到。

提示：目录结构并非必须预先创建——容器首次启动时 entrypoint 会自动补齐（详见下文 root-priming 部分）。但预先创建并记录位置，可以让你清楚地知道数据落在宿主机的哪个路径，便于备份与排错。

第二步：在 Container manager 中创建 Project

1. 打开Container manager -> Project，点击Create（创建）；
2. 填写项目信息：
   • Project name（项目名称）：netalertx
   • Path（路径）：例如/app_storage/netalertx（以你第一步记录的位置为准，各机器不同）
   • 将下方 YAML 模板粘贴进编辑器：

services: netalertx: container_name: netalertx # use the below line if you want to test the latest dev image # image: "ghcr.io/netalertx/netalertx-dev:latest" image: "ghcr.io/netalertx/netalertx:latest" network_mode: "host" restart: unless-stopped cap_drop: # Drop all capabilities for enhanced security - ALL cap_add: # Re-add necessary capabilities - NET_RAW - NET_ADMIN - NET_BIND_SERVICE - CHOWN - SETUID - SETGID volumes: - /app_storage/netalertx:/data # to sync with system time - /etc/localtime:/etc/localtime:ro tmpfs: # All writable runtime state resides under /tmp; comment out to persist logs between restarts - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime" environment: - PORT=20211

3. 将volumes中的/app_storage/netalertx替换为你自己的路径（例如/volume1/app_storage/netalertx），并注释掉不需要的挂载行：

volumes: - /volume1/app_storage/netalertx:/data

4. （可选）若20211端口已被占用，将PORT改为其它未使用端口；
5. 点击构建（Build）并等待镜像拉取与容器启动。

compose 模板关键参数解析

这份模板并非随机拼凑，每一项都与容器运行机制强相关，结合仓库实际配置逐一说明：

关于可写路径的完整清单，可参考 docs/FILE_PERMISSIONS.md 中的 "Writable Paths" 表格：/data/config（应用配置）、/data/db（数据库）、/tmp/log（日志）、/tmp/api（API 缓存）、/tmp/nginx/active-config（nginx 配置覆盖）、/tmp/run（nginx 与 PHP 运行时目录）等。将/tmp整体挂为tmpfs即可自动覆盖其全部子目录。

启动后初始化

构建完成后，浏览器访问<Synology URL>:20211（或自定义端口）进入 Web UI。随后按以下顺序完成初始化配置：

1. 阅读并配置 Subnets：指定SCAN_SUBNETS网络与网段（含接口与 VLAN 参数），这是设备发现的根基；
2. 阅读并配置 Plugins：启用所需的扫描/导入/发布插件；
3. 按需阅读 Initial Setup、Device Management 等文档完善后续设置。

注意：SCAN_SUBNETS等设置建议通过 Web UI 的 Settings 页面配置，以保证app.conf格式正确，仅在确有必要时才直接编辑back/app.conf。

第三步：解决宿主目录权限问题

Synology 上最常见的部署失败现象是容器启动时报 "Permission Denied"，根源通常是：宿主目录由之前的 root 容器或其它 UID 创建，而 NetAlertX 容器内部以专用低权限用户netalertx（UID 20211 / GID 20211）运行，无法写入那些目录。

背景：NetAlertX 运行在基于 Alpine 的只读容器中，所有可写路径要么是挂载的持久卷、要么是 tmpfs。容器内文件统一归20211:20211所有，宿主机上表现为这些文件属于20211:20211。完整说明见 docs/FILE_PERMISSIONS.md。

方式一：SSH 命令行修复（推荐）

SSH 登录你的 Synology 后执行以下两条命令，将/db与/config所在父目录（local_data_dir替换为你的实际路径）的属主改为 20211 并放开访问权限：

sudo chown -R 20211:20211 /local_data_dir sudo chmod -R a+rwx /local_data_dir

执行后重启容器即可正常读写数据库与配置文件。

方式二：通过群晖 UI 的"任务计划程序"执行

如果你不方便使用 SSH，可将上述命令放入一次性计划任务中执行：

1. 打开控制面板 -> 任务计划程序；
2. 点击创建 -> 计划的任务 -> 用户定义的脚本；
3. 为任务命名；
4. 在计划中指定仅运行一次（例如 5 分钟后执行），给自己留出保存时间；
5. 在任务设置中粘贴上面 SSH 小节的两条命令，并将/local_data_dir替换为你/db与/config文件夹的父目录；
6. 等待任务执行时间到达，验证文件属主已变为20211:20211。

底层机制：root-priming 权限修复

为什么手动chown到 20211 是"标准答案"？因为容器在 root 启动阶段会主动做同样的事情。仓库中的 root-entrypoint.sh 是容器的"root 预热"入口：

• 若容器以 root 启动，它会先执行_prime_paths()：对/data、/tmp及各运行时子目录执行chown -R "${PUID}:${PGID}"（默认即 20211:20211），随后通过su-exec降权到目标 UID/GID 再执行真正的 entrypoint.sh；
• 该脚本注释中明确提到，这类宿主卷属主/模式问题"在 Synology 这类 Docker 卷 copy-up 能力受限的设备上很常见"；
• 如果宿主目录是 root 创建、无法被降权后的进程写入，就会出现 Permission Denied——此时宿主机侧chown 20211:20211正是补齐这一环的关键；
• 另外 PUID_PGID_SECURITY.md 说明：PUID/PGID环境变量只接受纯数字，任何非数字值（如注入式20211 && rm -rf /）都会被判定为畸形输入并直接致命退出，这是 root 阶段防注入的安全措施。因此不要在 compose 中给这两个变量传非数字值。

如果你不想在宿主机手工改属主，也可以按 docs/FILE_PERMISSIONS.md 的说明，以 root（--user "0"）临时运行一次容器，让 entrypoint 自动执行chown -R 20211:20211修复所有卷的属主后 Ctrl+C 停止，再按正常 compose 启动。但需注意：运行 root 容器期间务必保持PUID/PGID为纯数字环境变量，且 root 模式仅用于修复，不应长期使用（可参阅 PUID/PGID 安全说明）。

常见问题与排错指引

• 端口被占用：若20211已被其它套件占用，修改 compose 中environment.PORT为未使用端口，重建容器后访问新端口（可参考 WEB_UI_PORT_DEBUG 排查）。
• 扫描不到设备：network_mode: host是前提；若仍无结果，在容器内执行sudo arp-scan --interface=eth0 192.168.1.0/24验证网络可达性，并按 Subnets 中的排查清单检查接口名、VLAN 与防火墙限制。
• 仍遇权限报错：复查宿主目录属主是否为20211:20211、chmod是否生效，并对照 Permission overview guide 逐一核对可写路径清单。
• 数据备份：netalertx父目录（含db与config）是 NetAlertX 的全部持久状态，建议纳入群晖 Hyper Backup 或定期复制备份。

总结

在 Synology 上部署 NetAlertX 的核心流程可归纳为三步：规划并记录netalertx/db与netalertx/config宿主机目录 → 在 Container manager 的 Project 中粘贴（并定制）compose 模板、调整卷路径与端口 → 遇到权限问题时用 SSH 或任务计划程序将目录属主修正为20211:20211。理解容器"只读 + 20211 用户 + root-priming 修复"的安全模型后，你就能在群晖上稳定运行 NetAlertX，并继续深入 Subnets（子网/接口/VLAN 配置）与 Plugins（扫描与通知插件）完成整套设备发现与告警体系。

• 后端
• 网络
• 运维
• 数据可视化