NAS 认证、目录和 HTTP 文件接口

本文描述 NAS 既有 HTTP 接口，可供 APP 局域网接入或经明确配置的 HTTPS 入口使用。所有文件路径通过已有文件身份代理解析，用户选择的是允许的 root 与相对路径，不是向服务器提交任意绝对路径。默认HTTP端口为18080，仅用于可信局域网；远程使用已核验身份的DTLS WebRTC或明确配置且证书可信的HTTPS入口。示例地址是文档占位值，替换为实际NAS，严禁向公网明文HTTP提交密码。

NAS 必需组件

NAS 管理员需先在套件中心正常安装并启用“文件管理”（files）和“文件互传”（transfer）。新版同步门面复用文件互传的原有分块引擎，内部调用继续受官方套件安装、签名和权限门禁约束；只安装“备份中心”并不自动安装可选的文件互传应用。轻量安装或卸载该套件后，原互传接口可能返回 409，新门面可能返回 sync_transfer_rejected。此时先由 NAS 管理员检查套件状态，APP 不应绕过安装确认或构造注册表。

capabilities 的 upload.stagingAvailable 只代表缓存数据卷就绪，不代表所需应用已安装或当前账号拥有写权限；开始备份前还需核对组件状态、transfer.read/write、files.read/write 和目标目录权限。当前生产测试 NAS 数据卷未挂载，create 会先返回 503 transfer_storage_unavailable，即使组件也需要配置，不能把 503 猜成凭据错误。

登录与响应格式

POST /api/v1/auth/login
Content-Type: application/json
 
{"username":"<NAS账号>","password":"<NAS密码>"}

成功为 HTTP 200，JSON 中 data 包含 token、expiresAt 和 user（username、role）。后续请求发送 Authorization: Bearer 加该 token。当前 NAS 会话有效期为 30 分钟，服务重启后需重新登录；过期或撤销时返回 401，APP 不应把它误判为文件不存在。登录受并发、客户端地址和安全策略限制，429 需要退避，不能无限自动试密码。

普通 JSON 成功使用 {“data”:…}；失败通常使用 {“error”:“稳定错误码”}，应同时检查 HTTP 状态。下载是原始字节，不要对所有成功响应一律调用 JSON 解码。当前认证层实时检查接口能力，文件身份代理继续执行 Linux UID/GID/ACL。primary 身份与 SSH root、安装 sudo、应用能力不是可互换的凭据。

枚举根目录

GET /api/v1/files/roots
Authorization: Bearer <NAS token>

返回 data.items 中的允许根；条目至少按当前返回值读取 id、name、path、readOnly。身份代理模式还返回 identity（username、uid、gid、groups），不能把显示的系统路径用作绕过 root 的输入。APP 保存 root 标识，显示用户可辨认名称；根目录不可用或只读时禁用对应写入操作。

分页浏览

GET /api/v1/files?root=<root-id>&path=<relative-directory>&share=<share-id-or-empty>&offset=0
Authorization: Bearer <NAS token>

查询字段需 URL 编码。path 为空或点号表示所选根；share 可为空。返回 data.path、entries、readOnly，可选 nextOffset。每项含 name、directory、size、modified、etag；etag 是列表元数据生成的弱标识，并非文件完整 SHA-256。

每页最多 200 项，offset 为非负整数且不超过 1000000。收到 nextOffset 才继续，不要因为权限过滤后返回少于 200 项就提前停止。分页不是固定目录快照；文件变化时可能需要刷新并按路径去重。隐藏内部暂存文件和无权访问项，不意味着客户端可以按名字猜测路径后绕过权限。

路径必须相对，禁止开头斜线、父目录片段、反斜杠、NUL 和内部 .nas- 路径。不同接口对空路径、点号、隐藏文件名还可能有更严格约束；客户端应按具体接口规范校验，不自行宽松归一化后重试。

创建单级目录

POST /api/v1/files/directory?root=<root-id>&path=<parent-relative-path>&share=
Authorization: Bearer <NAS token>
Content-Type: application/json
 
{"name":"手机备份"}

成功 HTTP 201，data.path 为实际目标相对路径。它只创建单级目录，没有递归 mkdir 标志。名称不能是点或父目录、不含路径分隔符、控制字符或保留内部前缀，且要满足长度限制。重复创建同名位置可能冲突，客户端应先重新枚举判断它是否为目标目录，不能把所有冲突都当成功。

普通文件下载与 Range

GET /api/v1/files/download?root=<root-id>&path=<relative-file>&share=
Authorization: Bearer <NAS token>
Range: bytes=1048576-
If-Range: <上次响应的 Last-Modified>

此接口是流式下载，没有普通上传的 100 MiB 上限。支持单范围、后缀范围及多范围；APP 最小实现使用单范围，处理 206、Content-Range、Content-Length、Accept-Ranges 和 Last-Modified。多范围返回 multipart/byteranges，需要独立解析，不能直接拼接整个响应体。

普通下载不返回完整内容强 ETag 或 X-File-SHA256。If-Range 接受匹配的 HTTP 日期；不能使用目录列表 weak ETag。验证值不匹配时会返回 200 全文件，APP 必须清空旧下载再写，不能把它追加到部分文件后。416 包含 bytes */size，需要重新核对远端元数据和本地长度。普通文件可能被其他任务修改；仅凭大小、日期不能替代端到端强摘要验证。

直接接收与普通上传

POST /api/v1/files/upload 使用 root、path、share、name 查询字段与原始字节，普通上传上限 100 MiB，不支持分块续传。新 APP 的大文件与目录任务应优先使用持久上传协议。

POST /api/v1/files/receive 是已有最终发布引擎：查询 root、path、share、name，原始正文必须带 Content-Length 与 X-Content-SHA256，最大 64 GiB。它检查空间、完整长度/摘要、最终实时权限和目录身份，再原子禁止覆盖地发布；中断需要从头发送。APP 不应把这个接口当成自己的断点实现，也不应提交内部 publication ticket。统一持久上传会在 NAS 内部调用它。

curl 联调例子

以下变量代表开发者自己的测试环境与会话，不要把真实值粘贴到公开记录中。登录正文建议保存到权限受限的临时文件，完成后清理。

NAS_BASE='http://192.168.1.100:18080'
curl --fail-with-body --silent --show-error   -H 'Content-Type: application/json' --data-binary @login-private.json   "$NAS_BASE/api/v1/auth/login"
curl --fail-with-body --silent --show-error   -H "Authorization: Bearer $NAS_TOKEN"   "$NAS_BASE/api/v1/files/roots"
curl --fail-with-body --silent --show-error --get   -H "Authorization: Bearer $NAS_TOKEN"   --data-urlencode "root=$ROOT_ID" --data-urlencode 'path=手机备份'   "$NAS_BASE/api/v1/files"

生产 APP 应使用系统安全存储、TLS 验证与受控错误日志；不要复制网页 localStorage 的会话作为自己的配对方案。另见云端发现与直连 RPC。