NAS媒体播放器使用指南

📋 目录

安装部署
基础功能使用
高级功能使用
目录与文件管理
常见问题解答
故障排除

🔧 安装部署

1. 环境要求

操作系统：Linux（推荐Ubuntu 20.04+/Debian 11+）
浏览器要求：Chrome 80+、Firefox 75+、Edge 80+、Safari 14+
硬件要求：CPU双核以上，内存1GB以上，硬盘剩余空间≥10GB（用于媒体存储）

2. 详细安装步骤

海纳思系统直接 ssh 后台安装

进入你的 ssh 后台终端

# apt update
# apt install -y nas-media-player
                
                    重要：请在安装过程中注意返回信息，确保正确安装完成

启动服务
安装完成后，服务已经自动启动，可以通过命令查看状态：
```
systemctl status nas-media-player
```
访问系统
1. 局域网访问：输入 http://[服务器局域网IP]:8800（如http://192.168.1.100:8800）
2. 外网访问：需配置路由器端口映射（将8800端口映射到服务器内网IP），然后通过http://[公网IP]:8800访问

3. 服务自启动配置

NAS重启后服务自动运行，已配置systemd服务：

/etc/systemd/system/nas-media-player.service

🎬 基础功能使用

▶️

媒体播放操作

登录系统后，左侧/上方的目录选择下拉框中选择媒体文件所在的子目录
系统会自动扫描该目录下最多3层子目录中的所有支持格式媒体文件，并显示在媒体选择下拉框中
选择要播放的文件：
- 方式一：直接点击媒体选择下拉框中的目标文件
- 方式二：双击媒体列表中的文件（若界面支持列表视图）
播放控制：
- 视频/音频：使用播放器内置控件进行播放/暂停、进度拖拽、音量调节、全屏切换
- 图片：点击图片区域可查看下一张/上一张，或使用键盘方向键切换

目录扫描说明：
为提升性能和响应速度，系统默认只扫描目录结构的前3层。如果您的媒体文件位于更深层的子目录中，可以通过API参数调整扫描深度，例如：GET /api/directories?max_depth=5（扫描5层）。如需永久调整默认深度，请修改程序代码中的默认参数。

🔄

媒体切换功能

上一个/下一个切换：点击播放器下方的「上一个」「下一个」按钮，或使用键盘快捷键（左箭头/右箭头）
直接选择切换：从「选择媒体」下拉框中直接选择目标文件，播放器会立即加载并播放
自动连播功能：视频/音频文件播放结束后，系统会自动加载并播放当前目录下的下一个文件（图片文件不支持自动连播）
目录切换记忆：切换目录后，系统会记忆上次在该目录中播放的文件位置

📊

媒体信息查看

播放媒体时，页面下方的信息栏会实时显示：

当前播放文件的完整名称（含扩展名）
媒体类型标识（📹视频 / 🎵音频 / 🖼️图片）
当前目录下的媒体文件总数及已播放数量
文件大小信息（部分格式支持）
当前播放进度百分比

⚙️ 高级功能使用

加密目录访问控制

访问加密目录
- 当选择带有密码保护的目录时，系统会自动弹出密码验证弹窗
- 在弹窗中输入该目录的访问密码，点击「确认」按钮
- 密码验证成功后，弹窗关闭并加载该目录下的媒体文件列表
密码有效期
- 验证成功后，浏览器会保存认证Cookie，有效期为1小时
- 有效期内无需重复输入密码即可访问该加密目录及其子目录
- 关闭浏览器或清除Cookie后，需重新验证密码
退出加密目录访问
- 方式一：关闭当前浏览器窗口/标签页
- 方式二：清除浏览器Cookie（找到名称以auth_开头的Cookie并删除）
- 方式三：等待1小时Cookie自动过期

安全警告：
1. 请勿将加密目录密码告知无关人员
2. 建议定期更换重要目录的访问密码
3. 公共网络环境下使用后请及时退出加密目录访问

📁 目录与文件管理

1. 目录创建与管理

创建新子目录
1. 在页面下方「创建新目录」区域操作：
2. 选择父目录：从下拉框中选择新目录的上级目录（只能选择已存在的非加密目录或已验证的加密目录）
3. 输入新目录名称：仅支持字母、数字、下划线、中横线，长度2-30字符，不能包含特殊符号（如/ \ : * ? " < > |）
4. （可选）设置目录访问密码：输入6-16位密码（建议包含字母+数字），留空则不加密
5. 点击「创建目录」按钮，系统会提示创建结果
目录命名规则
- 不能与同级目录重名
- 不能以点号（.）开头（避免创建隐藏目录）
- 建议使用清晰的命名便于管理（如「电影-科幻」「音乐-流行」「照片-2025」）

2. 文件上传操作

基础上传步骤
1. 在「文件上传」区域选择目标目录：从下拉框中选择要上传到的子目录（注意：主目录（根目录）不支持文件上传，必须选择子目录）
2. 点击「选择文件」按钮，在弹出的文件选择窗口中选择要上传的媒体文件（单次可选择多个文件）
3. 确认文件选择后，点击「上传」按钮开始上传
4. 上传过程中可查看：
  - 进度条：显示当前文件的上传进度
  - 速度显示：实时上传速度（如1.2MB/s）
  - 剩余时间：预估完成时间
  - 文件列表：当前上传的文件名及大小
5. 上传完成后，系统会提示「上传成功」，并自动刷新目标目录的媒体列表
支持的文件格式
- 视频文件：mp4、avi、mkv、mov、flv、wmv、m4v、mpeg、mpg
- 音频文件：mp3、wav、flac、aac、m4a、ogg、wma、ape
- 图片文件：jpg、jpeg、png、gif、bmp、webp、tiff、tif
提示：建议优先使用通用格式（如mp4视频、mp3音频、jpg/png图片），兼容性最佳
加密目录上传
1. 选择加密目录作为目标上传目录
2. 若未验证该目录密码，系统会先弹出密码验证弹窗
3. 输入正确密码并验证通过后，方可进行上传操作
4. 上传完成后，文件会保存在加密目录内，仅授权用户可访问
上传限制与注意事项
- 主目录（根目录）禁止上传文件：所有文件必须上传到子目录中，便于分类管理
- 单文件大小限制：默认无硬性限制（受服务器磁盘空间和网络带宽影响），建议单文件不超过2GB（大文件推荐分卷压缩后上传）
- 批量上传数量：建议单次上传不超过10个文件，避免浏览器卡顿
- 网络要求：上传大文件时建议使用有线网络（WiFi可能因信号不稳定导致上传中断）
- 文件覆盖规则：若上传的文件名与目标目录中现有文件重名，会直接覆盖原有文件（请谨慎操作）

❓ 常见问题解答

问题	解答
为什么主目录不能上传文件？	为了便于媒体文件分类管理，系统设计为仅允许在子目录中上传文件，避免主目录文件杂乱无章，同时降低误操作风险。
支持哪些媒体格式？	视频：mp4、avi、mkv、mov等；音频：mp3、wav、flac等；图片：jpg、png、gif等。具体兼容性取决于浏览器，推荐使用mp4/mp3/jpg/png等通用格式。
如何修改媒体根目录？	编辑后端主文件（/opt/nas-media-player/nas-media-player.py）中的`VIDEO_ROOT`变量，修改为新的目录路径，保存后重启服务即可生效（需确保新目录有读写权限）。
加密目录的密码忘记了怎么办？	直接删除该目录下的`/opt/nas-media-player/dir_passwords.json`文件（隐藏文件），删除后该目录将失去密码保护，可重新设置新密码。
可以在手机/平板上使用吗？	可以，系统支持移动端适配，使用手机/平板的现代浏览器访问`http://[服务器IP]:8800`即可，操作逻辑与电脑端一致。
上传的文件在哪里可以找到？	上传的文件会保存在服务器的`VIDEO_ROOT`配置目录下的对应子目录中，可直接通过文件管理器访问服务器上的该目录查看。
为什么部分视频文件无法播放？	可能原因：1. 浏览器不支持该视频编码格式；2. 文件损坏；3. 缺少FFmpeg组件。建议安装FFmpeg或转换视频格式为mp4（H.264编码）。
如何修改服务端口（非8800）？	启动服务时修改端口参数，如`/opt/nas-media-player/override.py`（改为8888端口），同时需确保新端口未被占用且防火墙已开放。

🛠️ 故障排除

1. 无法访问系统（页面无法打开）

检查服务是否正常运行：
- Linux：sudo systemctl status nas-media-player 或ps aux | grep uvicorn
确认端口8800是否被占用：
- Linux：netstat -tulpn | grep 8800 或 lsof -i:8800
检查防火墙设置：
- Linux：确保ufw/iptables已开放8800端口（sudo ufw allow 8800）
- 路由器：外网访问需在路由器中配置端口映射（8800端口映射到服务器内网IP）
确认访问地址是否正确：应为http://[服务器IP]:8800，注意区分http/https（默认使用http）

2. 媒体文件无法播放

检查文件路径：确认文件存在于配置的媒体目录中，且路径中无中文/特殊字符（部分系统对中文路径支持不佳）
检查文件权限：需确保文件有读权限（chmod 644 [文件名]）
检查文件完整性：重新上传文件或在本地验证文件是否可正常播放
查看浏览器控制台错误：按F12打开开发者工具，切换到Console标签，查看具体错误信息（如格式不支持、跨域问题等）
尝试更换浏览器：部分格式在特定浏览器中兼容性较差，建议使用Chrome测试

3. 无法上传文件

确认是否选择了子目录：主目录不支持上传，必须选择子目录
检查目标目录权限：Linux需确保目录有写权限（chmod 755 [目录名]）
检查文件大小：若文件过大（如超过10GB），可能因网络或服务器配置导致上传失败，建议分卷上传
检查网络连接：上传过程中网络中断会导致失败，可尝试缩短上传文件大小或更换网络
加密目录上传失败：确认已正确输入密码并通过验证，Cookie未过期

4. 加密目录验证失败

确认输入的密码是否正确（区分大小写）
清除浏览器Cookie后重新验证：打开浏览器设置→隐私和安全→清除浏览数据→选择Cookie和其他网站数据，清除后重新访问
检查/opt/nas-media-player/dir_passwords.json文件：确认加密目录下的dir_passwords.json文件存在且格式正确（由系统自动生成，请勿手动修改）
验证服务器时间：若服务器时间与客户端时间差异过大（超过1小时），可能导致Cookie验证失败，需同步服务器时间

5. 创建目录失败

检查目录名称：是否包含特殊字符、长度是否符合要求（2-30字符）
检查父目录权限：是否有在父目录中创建子目录的权限
检查目录是否重名：同级目录中是否已存在同名目录
检查磁盘空间：服务器磁盘是否已满，无剩余空间无法创建新目录

📞 技术支持

如遇到使用问题或功能建议，请通过以下方式获取支持：

邮箱支持：teasiu@qq.com
社区论坛：NAS媒体播放器官方论坛（bbs.histb.com）