Android NAS Lite 是 完整版 的精简版。完整版包含了远程控制、Root 全盘、Web Shell、内网穿透、短信中心等极高危功能，并为此维护了一份详尽的安全警告文档。Lite 版已将这些功能全部移除，因此完整版中大部分“极高危警告”在本项目中并不适用。

但这不等于 Lite 版没有安全边界。本文档只描述 Lite 版保留功能 的真实风险，以及与完整版的安全边界差异。

📌 当前文档版本：v4.5.0-lite.1

Lite 版不独立演进。每次完整版发布大版本后，会在该新版本基础上重新执行一次精简，并将结果同步推送到本仓库。

这意味着：

• 完整版的高危功能不会流入 Lite 版，本文档不需要跟着完整版的安全警告逐条更新；
• 完整版修复的底层鉴权 Bug、路径穿越 Bug、协议解析 Bug 会随精简进入 Lite 版，本文档也不需要重复跟踪；
• 如果某次精简时错误地保留了某个高危功能，或完整版移除了某个 Lite 仍保留的功能，本文档需要同步修订；
• 如果精简本身引入了安全回归（例如 lite.1 的 safeFile 沙箱逃逸），本文档必须显式记录，不能因为“不是漏洞、是回归”就略过；
• 如果 Lite 版主动修复了完整版遗留的安全 Bug（如 4.5.0-lite.1 补的 2FA 防锁死），本文档必须记录，因为这是 Lite 版的独有价值，也是用户选择 Lite 版而非完整版的理由之一。

完整版 v4.5.0 将安全底座从“单一鉴权”升级为“五重防线”，Lite 版完整保留（剔除 Root 与短信依赖后）：

• 算法：纯 Java 手写 TOTP（RFC 6238，HMAC-SHA1），兼容 Google Authenticator / Microsoft Authenticator / 1Password 等标准验证器。
• 开启时机：默认关闭。用户需在网页端「系统设置 → 高级安全控制台」手动勾选，并按提示扫码/手动输入密钥绑定。
• 校验流程：开启后，admin 账号的每次请求必须在 Header 携带 X-TOTP-Code（6 位动态口令），否则返回 401 或 2FA_REQUIRED。
• Lite 版加固：开启前强制验证一次当前 6 位验证码（前端 toggle2FA + 服务端 /api/2fa POST 双端校验），杜绝密钥输错后永久锁死账号。这是 Lite 版主动修复的完整版遗留风险。

⚠️ 2FA 锁死风险（高危必读）

若你在开启 2FA 后，出现以下任一情况：

• Authenticator 手机丢失或数据被清除；
• 密钥录入时有一个字符输错（Lite 版已加验证，但仍可能因网络延迟导致一次验证超时）；
• 浏览器残留的登录态过期，且本地缓存的 X-TOTP-Code 失效；

你将被永久锁死在门外。唯一补救方式是：物理接触服务端设备，清除 App 应用数据（会丢失 nas_core.db 数据库，但不影响存储文件）。

建议：开启 2FA 前，把密钥抄写在离线介质（纸质笔记本、加密 U 盘）并妥善保管。不要只依赖单一手机。

• 机制：在网页端设置一个自定义 secretPath（如 mysecret）。开启后，所有非 API 请求必须在 URL 后附加 ?s=mysecret，否则统一返回伪装 404 Not Found，防扫站脚本探测。
• 豁免：/api/* 接口不强制暗号（走 Basic Auth），/share/{token} 也不强制（分享链接独立鉴权）。

⚠️ 隐藏暗号遗忘风险

若忘记暗号，网页端会永远返回 404。补救方法：

• 在服务端 App 内进入「NAS 驾驶舱 → 高级设置」清空 secretPath；
• 或清除服务端 App 应用数据（会重置数据库）。

建议：暗号设置后立即记入密码管理器，或写入离线笔记。

• 触发条件：连续输错密码触发 Fail2Ban 后。
• 机制：前端请求 /api/captcha 获取随机算数题（如 3 + 5 = ?），计算结果通过 X-Captcha Header 回传。服务端用 ConcurrentHashMap 缓存题目与答案，校验通过后立即移除缓存，防止重放。
• 阻断效果：彻底阻断并发爆破脚本，同时不影响人类用户正常登录。

• 机制：/api/settings、/api/password 等核心接口强制校验来源 IP。isLanIp() 用正则 172\.(1[6-9]|2[0-9]|3[01])\..* 精准覆盖 RFC1918 的 172.16.0.0/12 网段，不会误伤 172.200.x.x 等公网 IP（完整版 4.5.0 的 172.2 前缀 bug 已修复）。
• 豁免：/api/list、/api/download、/api/upload 等常规文件接口不受此锁约束，公网穿透场景下仍可正常读写文件。

⚠️ 局域网锁误杀风险

Lite 版默认开启此锁。若你在公网穿透（frp / ngrok / Cloudflare Tunnel）环境下尝试修改设置、修改密码等敏感操作，会被 403 拦截。补救方法：

• 用 SSH 隧道 / VPN 接入内网后操作；
• 或在网页端「高级安全控制台」临时关闭「高危操作仅限局域网」开关。

• 单 IP QPS 限流：基于 ConcurrentHashMap 的滑动窗口计数器，单 IP 每秒超 30 次请求直接熔断封禁 15 分钟。
• 闲置自动登出：前端 fetch 拦截器读取本地保存的过期时间，无操作超过设定时间（默认 30 分钟）自动清空 Token 并要求重新登录。
• 隐藏 Server 响应头：NasHttpServer 对 / 响应注入 Server: SecureNAS 伪装，防止攻击者通过响应头识别底层 NanoHTTPD 版本。

在 v4.4.0 中，服务端底层引入了 ThreadLocal 存储当前请求的用户身份。无论 HTTP、WebDAV 还是 FTP，每次请求结束时都会在 finally 块中强制清理身份。

• 彻底封死并发串号：在高并发下，A 用户的请求绝不会串到 B 用户的沙箱，也杜绝了因线程复用导致身份残留的越权漏洞。
• 彻底封死路径穿越：NasHttpServer.safeFile() 与 FtpServer.safeFile() 会从 SQLite 读取 root_dir，必须先 replaceAll("^/+", "") 剥离前导斜杠，再用 new File(baseDir, rel) 拼接，最后用 getCanonicalPath 校验，普通用户无法通过 ../ 越权访问。
• 秒传防投毒：为 file_hashes 增加了用户路径匹配校验，A 用户无法通过相同 MD5 命中 B 用户的私密文件。

⚠️ lite.1 沙箱回归事故 (v4.4.0-lite.2 修复)

lite.1 在精简时，safeFile() 被回退为 new File(rootDir, path) 的写法。由于 Java File 构造器遇到绝对路径的第二个参数时会直接忽略第一个参数，导致：

• admin 与 guest 的全站文件操作均被 getCanonicalPath() 判定越权并返回 null，实际上表现为全站 404；
• 更危险的是，如果某个调用点对 null 返回的降级处理不当，理论上存在绕过沙箱访问 root_dir 之外路径的潜在风险。

lite.2 已在 NasHttpServer 与 FtpServer 双端修复为强制剥离前导斜杠。这是 lite.1 期间所有用户必须升级的理由。 已在 lite.1 上暴露过服务的部署，建议审计一次 LogManager 与 audit.log。

Lite 版默认不启用 TLS。8080 / 8081 / 2121 三个端口的所有流量（包括 Basic Auth 里的账号密码、传输的文件内容、剪贴板文本、2FA 动态口令）在局域网内均可被抓包工具直接读取。

• 风险场景：在公共 Wi-Fi（咖啡厅、机场、酒店）下启动服务，同一网络的任何设备都可以嗅探到你的密码、文件甚至 2FA 动态码。
• 缓解措施：
  • 仅在受信任的家庭 / 办公局域网内使用；
  • 使用 WPA3 / WPA2 加密的 Wi-Fi；
  • 需要公网访问时，自行用 frp / ngrok / Cloudflare Tunnel 套一层 TLS；
  • 开启原生 HTTPS（网页端「系统设置」），或定期轮换 admin 密码。

Lite 版移除了多用户管理 UI，底层仅保留 admin 与 guest 双账号 Basic Auth。admin 拥有 WRITE_EXTERNAL_STORAGE 范围内所有目录的读写权限；guest 默认只能访问 /Public。

• 密码存储：底层使用 SHA-256 + 随机盐哈希，不再明文存储。
• 防爆破 (Fail2Ban)：连续输错 5 次密码自动封禁 IP 15 分钟。
• IP 白名单：支持通配符拦截，仅允许受信任网络访问 HTTP / WebDAV / FTP。
• 敏感操作安全码 (PIN)：开启后，修改密码、修改端口等敏感操作需额外输入 PIN。忘记 PIN 只能重装 App 重置数据库。

⚠️ isDefaultPwd 动态判定 (v4.4.0-lite.2 修复)：lite.1 中 DatabaseManager.isDefaultPwd 为静态变量，进程重启后立即回退为 true，即使已改密也会继续弹“默认密码”警告，可能导致用户对警告脱敏。lite.2 新增 isDefaultPassword()，每次请求实际查询 SQLite 并比对加盐哈希，告警准确。4.5.0-lite.1 保持该修复。

• 风险场景：
  • 保留默认密码 admin/admin、guest/guest 直接暴露在局域网；
  • 在 /Public 目录放入私钥、证件照片等敏感文件；
  • 把 admin 密码通过聊天软件明文转发。
• 缓解措施：
  • 首次启动后立即修改 admin 密码（网页端「系统设置」→「修改管理员密码」）；
  • 不要在 /Public 放敏感文件；
  • 只向可信任的家庭成员提供账号。

Lite 版保留了 /api/share 短链分享与 /share/{token} 访问接口。底层鉴权正确——分享访问会绑定 Token 所有者身份进行沙箱解析，有效期由 expire 参数控制（缺省 24 小时）。

⚠️ 提取码未生效 (v4.5.0-lite.1 已知缺口，从 lite.2 延续)

前端分享弹窗仍保留「提取码」输入框，但服务端 ShareInfo 无 pass 字段，/api/share 也未实现 pass 参数解析，/share/{token} 也未做提取码校验。用户在弹窗中填写的提取码会被静默忽略。

• 风险：用户以为加了一层保护，实际生成的链接任何人拿到即可访问。
• 缓解措施：在修复前，不要依赖提取码保护分享链接。改用「短有效期」（1 小时）并仅在受信任渠道分发链接。
• 后续计划：要么补齐服务端 ShareInfo.pass 字段与校验，要么直接下掉前端输入框（避免误导）。

• ZIP 打包服务器资源消耗：/api/download/zip 允许用户请求打包下载多个文件。恶意并发请求可能导致服务端产生海量临时 ZIP 文件，迅速撑爆手机存储空间。
• 大文件秒传与分片上传：MD5 秒传校验与 2MB 分片合并会消耗大量的 CPU 计算资源与临时磁盘空间。在极低配置（如 API 8 老设备）上并发上传大文件，极易导致 NAS 服务卡死（ANR）。
• Range 视频流修复：v4.4.0 已重写 Range 播放逻辑，引入 LimitedInputStream，彻底解决了 RandomAccessFile 导致的高并发句柄泄漏与视频越界崩溃。
• 临时分片清理 (v4.4.0-lite.2 修复)：HttpServerService 的后台清理线程由 while(true) 改为 while(running)，服务停止后随 running 标志一起退出，避免进程被 stopService 后线程仍驻留扫描磁盘。

⚠️ /api/speedtest 无频率限制 (v4.5.0-lite.1 已知边界)

完整版 4.5.0 新增局域网测速接口，默认消耗 5MB 数据流（已从 20MB 下调）。Lite 版保留此接口但未加独立频率限制，依赖「防 CC 限流」兜底（单 IP 每秒 30 次）。恶意刷测速会瞬时打满旧手机 WiFi，建议仅在需要时手动触发。

• Webhook SSRF 与信息泄露风险：Lite 版保留了 Webhook 功能。如果恶意攻击者获取了 NAS 管理员权限并篡改了 Webhook URL，他不仅能窃取到所有文件上传事件、设备别名、温度报警等敏感日志，还可能利用服务端网络发起内网渗透（SSRF）。请务必妥善保管 Webhook 地址，不要将其配置为不可信的第三方服务器。

• 机制：v4.5.0 完整版新增 BatteryProtector，通过 BroadcastReceiver 监听 ACTION_BATTERY_CHANGED，超过 45℃ 触发 Webhook 报警，42℃ 以下自动解除。
• Lite 版裁剪：物理剥离了 Root 自动停充分支（RootManager.execCommand("...charging_enabled")）。Lite 版无 Root 模块，无法自动停充，用户需根据 Webhook 告警手动拔电或移动设备。
• 实际影响：在高温环境（夏季无空调、密闭机柜）下，告警能提醒你及时干预，但不会自动保护。建议把旧手机放在通风处，避免长期高温充电。

• 将网页端“添加到主屏幕”后，Service Worker 会缓存一部分页面静态资源。如果你在网吧或公共电脑上访问，请及时清理浏览器缓存，防止暴露你的 NAS 局域网 IP 与页面结构。

Lite 版只保留基础保活三件套：前台服务常驻通知 + WakeLock（CPU）+ WifiLock（Wi-Fi 高性能）+ BOOT_COMPLETED 开机自启。

• 与完整版的差异：完整版的静音音频欺骗、1 像素 Activity、AlarmManager 心跳、OOM 免死注入、Magisk 特权模块、冻结厂商省电服务均未包含在 Lite 版中。
• 实际影响：在国产 ROM（MIUI / EMUI / ColorOS）的深度清理策略下，Lite 版的服务更容易被系统杀掉。这不是安全漏洞，而是主动取舍——用稳定性换“不做流氓保活”。重新打开 App 或重启设备后服务会自动恢复。

1. 必须升级到 v4.5.0-lite.1 或更高：lite.1（4.4.0 时期的 lite.1）存在沙箱回归（全站 404 + 潜在越权）。若在 lite.1 上暴露过服务，请审计 LogManager 与 /sdcard/AndroidNAS/audit.log。
2. 2FA 密钥离线备份：开启 2FA 前，把密钥抄写在纸质笔记本或加密 U 盘，不要只依赖单一手机。
3. 隐藏暗号记入密码管理器：设置后立即存档，避免遗忘后网页端永远 404。
4. 局域网隔离：最安全的 NAS 是永远不连外网的 NAS。建议将服务端放在专用 IoT 访客路由器下，与主力办公电脑隔离。
5. 强密码：不要使用默认的 admin/admin。请使用 12 位以上复杂密码，并定期在网页端「系统设置」中轮换。开启「敏感操作安全码 (PIN)」以防远程篡改端口/密码。
6. 最小权限：只向需要的家庭成员提供账号；不要在 /Public 放敏感文件；只开放实际使用的协议（例如用不到 FTP 就在设置里关掉）。
7. 分享链接策略：不要依赖提取码（lite.1 服务端仍未实现校验）。使用「1 小时」短有效期，仅通过受信渠道分发。
8. 及时更新：始终从本仓库 Actions 或 Releases 页面下载最新的 Lite 版构建产物。
9. 公网访问：不要将 8080 / 8081 / 2121 端口直接暴露到公网。需要远程访问请自行配置 frp / ngrok / Cloudflare Tunnel 并启用 TLS。开启「高危 API 局域网锁」（默认开启）可防止公网篡改设置。
10. 警惕公共 Wi-Fi：在咖啡厅、机场等场所启动服务前，请关闭 Web / WebDAV / FTP，或改用手机热点。

如果你发现严重安全漏洞（如未授权访问、任意文件读取/写入、路径穿越、鉴权绕过、提取码绕过、2FA 绕过）：

• 若漏洞涉及两版共享代码（如 NasHttpServer、WebDavServer、FtpServer、AuthManager、DatabaseManager、TotpManager、SecurityFilter）→ 请提交到 完整版仓库的 Security Advisory。两版同源，修复会同步进入 Lite 版。
• 若漏洞仅涉及 Lite 版精简范围（如精简后残留的调用、精简脚本误保留的高危分支、lite.1 沙箱回归、isDefaultPassword 动态判定）→ 请提交到本仓库的 Security Advisory。
• 若漏洞源于前后端不一致（如分享提取码未生效）→ 请提交到本仓库的 Security Advisory，并注明「已知缺口」还是「新发现」。
• 若漏洞源于 Lite 版主动修复完整版遗留 Bug 时引入（如 2FA 开启前验证逻辑有缺陷）→ 请提交到本仓库的 Security Advisory，并注明「Lite 版独有代码」。

请不要在公开 Issue 中披露漏洞细节。我会在确认漏洞后，以最快速度发布补丁并在 CHANGELOG.md 中致谢。

本项目按"原样"提供，不提供任何明示或暗示的担保。 使用本项目所带来的任何风险（包括但不限于设备损坏、数据泄露、隐私暴露、2FA 锁死导致无法登录、法律纠纷）均由使用者自行承担。如果你不同意此声明，请立即停止使用并删除本项目。