NAS设备API接口全解析：远程文件管理、用户权限与自动备份

随着家庭和中小型企业对数据存储需求的不断增长，NAS（Network Attached Storage，网络附加存储）设备因其高性价比、易管理性和丰富的功能在各类场景中广受欢迎。尤其是支持开放API接口的NAS，更能让开发者和系统管理员灵活地将存储设备与自动化、监控、备份等体系深度集成。本文将基于 Synology DSM（DiskStation Manager）API，全面解析三大关键能力：远程文件管理、用户权限配置与自动备份。

一、引言

在传统的文件服务器架构中，管理员需要通过文件共享协议（如 SMB、NFS）手动分配权限，往往效率低、易出错。现代NAS设备不仅提供友好的Web界面，更开放了丰富的RESTful API，让我们可以通过脚本或程序自动化完成：

远程文件管理：上传、下载、移动、复制、删除文件与文件夹
用户权限管理：创建用户账号／用户组、分配共享文件夹权限、基于ACL的细粒度权限控制
自动备份：定时快照、本地与远程备份任务创建与管理

结合本文演示示例，你将掌握如何使用 DSM API 构建：

利用脚本批量管理共享文件
动态调整用户和组的访问权限
自动化配置备份任务并监控执行状态

二、Synology DSM API 概述

Synology DSM 提供一整套基于 HTTP/HTTPS 的 RESTful 接口，官方称为 Synology API。它涵盖：

Auth API：用于登录登出，获取会话（sid）
File Station API：提供远程文件浏览和操作接口
Privilege API：用于应用程序级权限设定
Share Folder API：管理共享文件夹
Backup & Replication API：管理备份任务与快照

调用流程通常分为两步：

登录：向 /webapi/auth.cgi 发送账号密码换取 sid
业务请求：在后续请求中带上 sid，并指明所用 API 与方法

所有请求均以 GET 或 POST 方式提交，返回 JSON 格式数据。

三、远程文件管理 API 接口

3.1 登录获取会话

curl -k -X GET 'https:// < nas-ip > :5001/webapi/auth.cgi' \
  -d 'api=SYNO.API.Auth&method=login&version=6' \
  -d 'account=admin&passwd=YourPassword&session=FileStation&format=sid'

api：接口名称
method：调用方法
version：接口版本
session：指定会话场景，此处为 FileStation
format：返回格式（sid 即简洁模式）

响应示例：

{
  "success": true,
  "data": { "sid": "xxx_your_session_id_xxx" }
}

3.2 列举文件与文件夹

curl -k -X GET 'https:// < nas-ip > :5001/webapi/entry.cgi' \
  -d 'api=SYNO.FileStation.List&version=2&method=list_share' \
  -d 'sid=xxx_your_session_id_xxx'

list_share：列举所有共享文件夹
响应包含文件夹名称、大小、权限等信息

若需列出指定路径的子目录与文件：

curl -k -X GET 'https:// < nas-ip > :5001/webapi/entry.cgi' \
  -d 'api=SYNO.FileStation.List&version=2&method=list' \
  -d 'folder_path=/home/user' \
  -d 'additional=["size","time","owner","perm"]' \
  -d 'sid=xxx_your_session_id_xxx'

3.3 上传与下载

上传

curl -k -X POST 'https:// < nas-ip > :5001/webapi/entry.cgi' \
-F 'api=SYNO.FileStation.Upload&version=2&method=upload' \
-F 'path=/home/user/uploads' \
-F 'create_parents=true' \
-F 'file=@local_file.txt' \
-F 'sid=xxx_your_session_id_xxx'

create_parents=true 可在目标路径不存在时自动创建父目录。

下载

curl -k -X GET 'https:// < nas-ip > :5001/webapi/entry.cgi' \
-d 'api=SYNO.FileStation.Download&version=2&method=download' \
-d 'path=/home/user/uploads/local_file.txt' \
-d 'mode=open' \
-d 'sid=xxx_your_session_id_xxx' \
--output ./downloaded_file.txt

3.4 文件/文件夹操作

移动

curl -k -X POST 'https:// < nas-ip > :5001/webapi/entry.cgi' \
-d 'api=SYNO.FileStation.CopyMove&version=3&method=move' \
-d 'path=["/source/path"]' \
-d 'dest_folder_path=/target/path' \
-d 'sid=xxx_your_session_id_xxx'

复制：将 method=move 改为 method=copy

删除

curl -k -X POST 'https:// < nas-ip > :5001/webapi/entry.cgi' \
-d 'api=SYNO.FileStation.Delete&version=1&method=delete' \
-d 'path=["/target/path"]' \
-d 'sid=xxx_your_session_id_xxx'

四、用户权限管理 API 接口

在企业或团队协作场景中，细粒度的权限控制至关重要。DSM 支持两种维度的权限：

共享文件夹权限（Share Folder 权限）
基于 Windows ACL 的细粒度权限（File Station 中 ACL）

下文将结合字幕演示与 API 接口解析，逐步完成权限配置。

4.1 创建用户与用户组

4.1.1 在 Web 界面中的手动流程（字幕摘要）

0:40–2:49

Control Panel → User & Group → Create

输入用户名、描述、邮箱、随机密码

配置通知邮件、密码重置链接及过期设置

选择是否允许用户更改密码

将用户加入某一组（同组成员共享相同权限设定）

配置共享文件夹访问权限：No Access、Read Only、Read/Write

配置应用访问权限、传输速度限制

点击Done完成创建

4.1.2 对应 API 调用

创建用户

curl -k -X POST 'https:// < nas-ip > :5001/webapi/entry.cgi' \
-d 'api=SYNO.Core.User&method=create&version=1' \
-d 'name=newuser&passwd=RandomPass123' \
-d 'email=user@example.com&description="Project member"' \
-d 'force_pw_change=false' \
-d 'groups=["users","designers"]' \
-d 'sid=xxx'

设置共享文件夹权限

curl -k -X POST 'https:// < nas-ip > :5001/webapi/entry.cgi' \
-d 'api=SYNO.Core.Share&method=perm&version=1' \
-d 'folder_path=/projects' \
-d 'share_name=projects' \
-d 'user=newuser' \
-d 'rights=R'   # R / RW / no
-d 'sid=xxx'

4.2 基于 ACL 的细粒度权限

字幕中示例演示了在 File Station 中针对子文件夹 “Cafe Mori” 应用 ACL，将普通设计师设为只读，将特定用户 Forrest 设为读写。

4.2.1 Web 操作流程（字幕摘要）

3:01–5:03

File Station → 右键文件夹 → Properties → Permission → Create

对其他用户／组设置 Type = Deny、Permission = Write

自定义权限会覆盖继承权限

4.2.2 对应 API 调用

列举当前 ACL

curl -k -X GET 'https:// < nas-ip > :5001/webapi/entry.cgi' \
-d 'api=SYNO.FileStation.Acl&method=get&version=2' \
-d 'path=/projects/Cafe Mori' \
-d 'sid=xxx'

添加自定义 ACL 条目

curl -k -X POST 'https:// < nas-ip > :5001/webapi/entry.cgi' \
-F 'api=SYNO.FileStation.Acl&method=set&version=2' \
-F 'path=/projects/Cafe Mori' \
-F 'add_list=[{"user":"designerA","type":"deny","permission":"write"},{"user":"designerB","type":"deny","permission":"write"}]' \
-F 'sid=xxx'

清除自定义 ACL

curl -k -X POST 'https:// < nas-ip > :5001/webapi/entry.cgi' \
-d 'api=SYNO.FileStation.Acl&method=remove&version=2' \
-d 'path=/projects/Cafe Mori' \
-d 'remove_list=["designerA","designerB"]' \
-d 'sid=xxx'

通过以上接口，你可以在脚本中批量调整文件夹或文件的读写／执行／删除等权限，满足多用户协作场景下的细粒度安全需求。

五、自动备份 API 接口

数据安全不仅需要权限管控，还要定期备份以防误删或硬件故障。DSM 提供 Hyper Backup 与 Snapshot Replication 两大备份体系。以下示例聚焦于常见的 Hyper Backup 备份任务创建。

5.1 创建备份目的地

以备份到本地共享文件夹为例：

curl -k -X POST 'https:// < nas-ip > :5001/webapi/entry.cgi' \
  -d 'api=SYNO.Backup.Task&method=create&version=1' \
  -d 'name=DailyBackup' \
  -d 'backup_destination_type=local' \
  -d 'backup_destination_path=/home/backup/daily' \
  -d 'source=["/projects","/home/user"]' \
  -d 'schedule_type=day&schedule_time=02:00' \
  -d 'rotation=&keep_snapshot=false' \
  -d 'sid=xxx'

name：任务名称
backup_destination_type：本地 local、远程 rsync、云端方案等
source：需要备份的文件夹列表
schedule_type：hour、day、week 等
schedule_time：执行时间
rotation：保留规则

5.2 监控备份状态

curl -k -X GET 'https:// < nas-ip > :5001/webapi/entry.cgi' \
  -d 'api=SYNO.Backup.Task&method=list&version=1' \
  -d 'sid=xxx'

响应中 last_status、last_finish_time、error 字段可用于监控和告警集成。

六、实战示例：Python 脚本批量管理

下面提供一个简化版 Python 示例，展示如何：

登录 DSM
创建用户并赋予共享文件夹读写权限
设置 ACL 让指定用户只读

import requests

NAS_URL = 'https://nas.example.com:5001'
USERNAME = 'admin'
PASSWORD = 'YourPassword'

def auth():
    params = {
        'api': 'SYNO.API.Auth',
        'version': 6,
        'method': 'login',
        'account': USERNAME,
        'passwd': PASSWORD,
        'session': 'FileStation',
        'format': 'sid'
    }
    r = requests.get(f'{NAS_URL}/webapi/auth.cgi', params=params, verify=False)
    data = r.json()['data']
    return data['sid']

def create_user(sid, user, passwd, groups):
    data = {
        'api': 'SYNO.Core.User',
        'version': 1,
        'method': 'create',
        'name': user,
        'passwd': passwd,
        'force_pw_change': 'false',
        'groups': str(groups).replace("'", '"'),
        'sid': sid
    }
    r = requests.post(f'{NAS_URL}/webapi/entry.cgi', data=data, verify=False)
    return r.json()

def set_share_perm(sid, folder, user, rights):
    data = {
        'api': 'SYNO.Core.Share',
        'version': 1,
        'method': 'perm',
        'share_name': folder,
        'user': user,
        'rights': rights,
        'sid': sid
    }
    r = requests.post(f'{NAS_URL}/webapi/entry.cgi', data=data, verify=False)
    return r.json()

def set_acl(sid, path, acl_list):
    files = {
        'api': 'SYNO.FileStation.Acl',
        'version': 2,
        'method': 'set',
        'path': path,
        'add_list': str(acl_list).replace("'", '"'),
        'sid': sid
    }
    r = requests.post(f'{NAS_URL}/webapi/entry.cgi', data=files, verify=False)
    return r.json()

if __name__ == '__main__':
    sid = auth()
    # 创建用户
    print(create_user(sid, 'forrest', 'SecurePass!', ['designers']))
    # 赋予 projects 共享文件夹读写
    print(set_share_perm(sid, 'projects', 'forrest', 'RW'))
    # 对其他设计师禁止写入 Cafe Mori
    acl_list = [
        {'user':'designerA','type':'deny','permission':'write'},
        {'user':'designerB','type':'deny','permission':'write'}
    ]
    print(set_acl(sid, '/projects/Cafe Mori', acl_list))