flnxi-Wu/docs/deployment/多品牌 NAS 与 Linux 交付差异清单.md

多品牌 NAS 与 Linux 交付差异清单

1. 这份清单解决什么问题

这套系统的目标环境不是单一机器，也不是单一品牌的 NAS（网络存储）。

后续真实交付时，可能遇到：

• fnOS（飞牛系统）
• DSM（群晖系统）
• 其他品牌 NAS（网络存储）
• 通用 Linux（服务器系统）

这些环境虽然都可能支持 Docker（容器），但不代表它们的：

• 路径规则一样
• 权限模型一样
• 端口管理一样
• 反向代理方式一样
• 日志和自启动方式一样
• CPU（处理器） 架构一样

所以，任何“在某一台测试机上跑通”的做法，都不能直接当成客户交付标准。

一句话结论：

FLNXI 素材库 的交付基线应该是“可参数化的容器化方案”，而不是“绑定某一台机器习惯”的方案。

2. 当前项目的固定基线

不管客户机器是什么品牌，后续都应尽量坚持这些不变项：

• 最终使用者只通过浏览器访问系统，不承担部署动作。
• 主交付单元优先是 docker compose（容器编排） + .env（环境变量文件）。
• 环境差异优先收敛到 .env、挂载目录、端口、反向代理，而不是改业务代码。
• 许可证链路、初始化链路、备份恢复链路必须可重复执行，不能依赖一次性手工操作。
• 共享机器部署时，容器名、卷名、网络名必须项目级隔离。

3. 不同机器最容易出问题的地方

差异项	常见差异	对本项目的含义	交付前必须确认
CPU（处理器） 架构	x86_64、arm64、旧型号低性能 CPU	镜像、依赖、转码能力可能不兼容	目标机器是 x86_64 还是 arm64；主镜像和依赖镜像是否支持
容器入口	有的机器支持 docker compose（容器编排），有的只给图形界面	交付步骤不能默认客户会命令行	目标机器是否支持 docker compose v2；若不支持，是否已有可接受的替代入口
宿主机目录	Linux（服务器系统） 常见 /opt/...、/srv/...，NAS（网络存储） 常见品牌自定义挂载点	数据卷路径不能写死	客户最终要把数据放到哪个宿主机目录
权限模型	有的机器是 root（管理员） 直登，有的只有图形界面管理员	挂载目录、上传目录、备份目录权限会不同	是否可 SSH；是否可创建目录；是否允许容器写入挂载目录
端口管理	有的机器已有 80/443/9000/9001 等服务占用	默认端口不一定能直接用	客户可用端口范围；是否已有反向代理占用
反向代理 / TLS（证书）	有的机器有内置反代，有的要自己配 Nginx（反向代理）	域名、HTTPS、回调地址不能写死	是否使用域名；证书由谁托管；最终外部访问地址是什么
网络出站	有的内网机器不能直接访问镜像仓库或授权服务	镜像拉取、许可证验证可能失败	是否能访问 Registry（镜像仓库）、license-server（许可证服务）、必要的外部 DNS
文件系统性能	NAS（网络存储） 上机械盘、阵列、快照策略差异大	上传、预览、转码体验差异明显	数据盘类型；是否是 SSD；是否允许视频转码落盘
日志与自启动	有的机器靠 systemd（系统服务），有的靠品牌图形界面	运维说明不能只写一种方式	客户如何看日志、重启服务、设置开机自启
共享宿主机	测试机 / 客户机可能不只跑这一个项目	容器名、卷名、网络名、端口必须隔离	是否独占机器；若不是，现有项目占用了什么

4. 商业化交付时的机器分级

建议交付前先把客户机器分成 3 类，不要混着处理。

A 类：标准 Linux 服务器

特征：

• 可 SSH
• 可执行 docker compose（容器编排）
• 可自由创建宿主机目录
• 端口和反向代理由实施方控制

处理建议：

• 这是最适合当前项目标准交付链路的环境。
• 优先走通用 compose + .env 方案。

B 类：可 SSH 的 NAS

特征：

• 品牌系统上有图形化容器管理
• 同时保留 SSH 或命令行能力
• 路径、权限、反向代理存在品牌差异

处理建议：

• 这是当前项目最需要兼容的主场景。
• 仍优先使用通用容器方案，但要提前适配：
  • 挂载路径
  • 端口
  • 反代入口
  • 目录权限

C 类：强品牌绑定、命令行能力弱的环境

特征：

• 只能主要依赖图形界面
• compose（容器编排） 支持弱或不稳定
• 权限、网络、目录能力受限较多

处理建议：

• 不要先承诺“按标准脚本一键部署”。
• 先做品牌专项验证，再决定是否提供该品牌专用安装说明。

5. 客户机器交付前必须采集的信息

每次客户部署前，至少要收集下面这份信息，不要跳过。

项目	要确认的内容
品牌与型号	机器品牌、型号、系统名称、系统版本
CPU（处理器）	架构、核心数、是否支持当前镜像
内存	总内存、可用内存
磁盘	可用空间、是否 SSD、数据盘路径
容器能力	Docker（容器） 版本、docker compose（容器编排） 是否可用
SSH 能力	是否可 SSH；是否有管理员权限
端口	可用端口、已占用端口、是否已有反向代理
域名与证书	是否有正式域名；HTTPS 是否由客户现有网关处理
网络出站	能否访问镜像仓库、许可证服务、DNS
共享情况	是否独占机器；若共享，已有项目名单和端口名单
备份	备份目录、备份责任人、恢复演练方式
视频能力	是否启用转码；是否具备 ffmpeg（视频处理工具） 和足够磁盘

6. 这套项目目前必须坚持的交付约束

后续如果继续做商业化交付，下面这些约束不能松：

• 不能把某一台测试机的固定 IP、固定目录、固定端口当成客户默认值。
• 不能把某个品牌 NAS（网络存储） 的宿主机路径写死到通用文档。
• 不能把共享测试机的容器名、卷名、网络名直接搬到客户环境。
• 不能默认所有客户机器都能直接访问 Registry（镜像仓库） 或许可证服务。
• 不能默认所有客户机器都有高性能 CPU 或 SSD。
• 不能把“内部测试机能跑通”当成“客户环境已可交付”。

7. 当前项目的实际落地建议

结合当前仓库现状，后续建议这样执行：

1. 通用交付主线只保留一套：docker compose（容器编排） + .env（环境变量文件）。
2. 品牌差异只落在部署前检查、目录映射、端口、反代和权限上。
3. 如果某品牌确实需要特殊步骤，再单独补“品牌补充说明”，不要污染主部署文档。
4. 共享测试机只用于内部验证，不代表客户标准机型。
5. 每次客户交付前，先填完本清单第 5 节，再开始部署。

8. 目前哪些内容不能直接当客户模板

当前仓库中仍有一些“固定服务器 / 固定环境”的历史部署写法。

这些内容可以作为内部参考，但不能直接视为客户默认模板：

• 固定公网服务器地址
• 固定测试机地址
• 固定镜像仓库凭据
• 固定端口直接复用
• 固定容器名直接复用

后续若发现这类信息仍在主文档里，应继续收口成“示例”或“内部历史记录”，不要继续当标准交付口径。