Configuration_CN

配置指南

MSP 的配置文件名为 config.json，位于程序运行的同级目录下。如果不存在，程序启动时会自动生成默认配置。

提示：大部分常用配置（如添加/删除共享目录）都可以直接在网页端的"设置"中完成，无需手动修改文件。

运行时文件

• config.json：运行时配置（包含本机路径等信息，不要提交）。
• msp.db：SQLite 数据库（存储媒体索引和播放进度，不要提交）。
• msp.db-shm, msp.db-wal：SQLite 临时文件（不要提交）。

完整配置示例

{
  "port": 8099,
  "maxItems": 0,
  "shares": [
    {
      "label": "电影",
      "path": "D:\\Movies"
    },
    {
      "label": "音乐",
      "path": "E:\\Music"
    }
  ],
  "logLevel": "info",
  "logFile": "msp.log",
  "blacklist": {
    "extensions": [".tmp", ".bak", "^\\.~.*$"],
    "filenames": ["desktop.ini", "thumbs.db"],
    "folders": ["$RECYCLE.BIN", "System Volume Information"],
    "sizeRule": "<1KB"
  },
  "features": {
    "speed": true,
    "speedOptions": [0.5, 0.75, 1, 1.25, 1.5, 2],
    "quality": false,
    "captions": true,
    "playlist": true
  },
  "ui": {
    "defaultTab": "video",
    "showOthers": false
  },
  "playback": {
    "audio": {
      "enabled": true,
      "shuffle": false,
      "remember": true,
      "scope": "all",
      "transcode": false
    },
    "video": {
      "enabled": true,
      "scope": "folder",
      "transcode": false,
      "resume": true,
      "encoding": {
        "hwAccel": "auto",
        "maxJobs": 0
      }
    },
    "image": {

      "enabled": true,
      "scope": "folder"
    }
  },
  "security": {
    "ipWhitelist": [],
    "ipBlacklist": [],
    "pinEnabled": false,
    "pin": "0000"
  }
}

字段详解

1. 基础设置 (port, shares, log, maxItems)

• port: 服务监听端口，默认为 8099。
• maxItems: 最大扫描文件数
  • 0: 推荐。无限制全量扫描，配合 SQLite 数据库实现增量更新，首次扫描稍慢，后续极快。
  • >0 (如 8000): 限制扫描数量，适合只想快速预览部分文件的场景（注意：达到限制后会停止扫描剩余文件）。
• shares: 共享目录列表。
  • label: 在网页上显示的名称（别名）。
  • path: 本地绝对路径（Windows 下注意转义反斜杠 \\）。
• logLevel: 日志级别。
  • 可选值：debug, info (默认), error, silent。
• logFile: 日志文件路径。
  • 默认：msp.log。
  • 用于存储详细日志（含调试信息），保持控制台界面清爽。

2. 黑名单过滤 (blacklist)

支持强大的文件过滤功能，被匹配的文件将不会在列表中显示。

• extensions: 屏蔽的文件后缀列表。
  • 支持普通后缀（如 .tmp）。
  • 支持 正则表达式（如 ^\\.~.*$ 屏蔽以 ~ 开头的临时文件）。
• filenames: 屏蔽的文件名列表。
  • 支持完全匹配（如 desktop.ini）。
  • 支持 正则表达式。
• folders: 屏蔽的文件夹名称列表。
  • 匹配路径中的任何一级目录名。
• sizeRule: 文件大小过滤规则。
  • 大于/小于：>100MB, <10KB。
  • 区间：10MB-1GB（屏蔽 10MB 到 1GB 之间的文件）。
  • 单位支持：B, KB, MB, GB, TB (不区分大小写)。

3. 功能开关 (features)

• speed: 是否启用倍速播放功能。
• speedOptions: 自定义倍速选项列表。
• captions: 是否启用字幕支持（自动加载同名 .vtt / .srt）。
• playlist: 是否启用播放列表侧边栏。

4. 界面设置 (ui)

• defaultTab: 默认打开的标签页 (video / audio / image / other)。
• showOthers: 是否在"其他"标签页显示非媒体文件。

5. 播放行为 (playback)

控制各类媒体的默认行为。

• audio:

  • shuffle: 是否默认开启随机播放。
  • remember: 是否记住播放进度（刷新后继续播放）。
  • scope: 播放范围 (all: 所有音频; folder: 当前文件夹)。
  • transcode: 是否启用 FFmpeg 转码不支持的格式 (默认: false)。

• video:

  • enabled: 是否启用视频播放。
  • scope: 连播范围 (folder：当前文件夹内连播；all：所有视频连播)。
  • transcode: 是否启用 FFmpeg 转码不支持的格式 (默认：false)。
  • resume: 是否记住播放进度 (默认：true)。
  • encoding: 硬件加速设置（v0.9.0+）。
    • hwAccel: 硬件编码器模式（"auto"（默认）、"none"、"nvenc"、"qsv"、"amf"、"vaapi"、"videotoolbox"）。
    • maxJobs: 最大并发转码数（0 = 自动：软件 2 路，硬件 4 路）。

• image:

  • enabled: 是否启用图片查看。
  • scope: 浏览范围 (folder: 当前文件夹; all: 所有图片)。

6. 安全设置 (security)（v0.7.0+）

控制访问权限和身份验证。

• ipWhitelist: IP 白名单（数组）

  • 为空时不限制访问
  • 不为空时，只有列表中的 IP 可以访问
  • 支持单个 IP："192.168.1.100"
  • 支持 CIDR 范围："192.168.1.0/24", "10.0.0.0/8"

• ipBlacklist: IP 黑名单（数组）

  • 列表中的 IP 将被拒绝访问
  • 支持单个 IP 和 CIDR 范围
  • 优先级高于白名单（黑名单优先）

• pinEnabled: 是否启用 PIN 认证（布尔值）

  • true: 启用，访问时需要输入 PIN 码
  • false: 禁用（默认）

• pin: PIN 码（字符串）

  • 默认值："0000"
  • 可以是任意字符串
  • 建议使用 4-6 位数字

安全配置示例

示例 1：仅允许本地网络访问

{
  "security": {
    "ipWhitelist": ["127.0.0.1", "192.168.1.0/24"],
    "ipBlacklist": [],
    "pinEnabled": false,
    "pin": "0000"
  }
}

示例 2：启用 PIN 认证

{
  "security": {
    "ipWhitelist": [],
    "ipBlacklist": [],
    "pinEnabled": true,
    "pin": "1999"
  }
}

示例 3：组合使用（推荐公网环境）

{
  "security": {
    "ipWhitelist": ["192.168.1.0/24"],
    "ipBlacklist": ["192.168.1.100"],
    "pinEnabled": true,
    "pin": "8888"
  }
}

CIDR 范围说明

• /8：匹配整个 A 类网络
  • 例如：10.0.0.0/8 匹配 10.x.x.x
• /16：匹配整个 B 类网络
  • 例如：192.168.0.0/16 匹配 192.168.x.x
• /24：匹配整个 C 类网络
  • 例如：192.168.1.0/24 匹配 192.168.1.x

安全建议

• 开发环境：可以不启用任何安全功能
• 局域网环境：建议使用 IP 白名单限制访问范围
• 公网环境：强烈建议同时启用 IP 白名单和 PIN 认证
• 定期更换 PIN：建议定期更换 PIN 码以提高安全性

配置热重载（v0.7.0+）

从 v0.7.0 开始，MSP 支持配置文件热重载功能：

• 修改 config.json 文件后，无需重启服务器
• 配置会在 2 秒内自动生效
• 服务器日志会显示：Config file changed, reloading... 和 Config reloaded successfully
• 适用于所有配置项（包括安全设置、共享目录等）

使用方法：

1. 编辑 config.json 文件
2. 保存文件
3. 等待 2 秒，配置自动生效
4. 查看日志确认重载成功

播放策略说明（v0.8.11+）

• 开启 transcode 不代表所有媒体都会转码。
• 常见 MP4(H.264/AAC) 默认仍优先直连。
• 仅在高风险容器（AVI/WMV）或直连真实失败时触发转码。