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

一、引言

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

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

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

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

二、Synology DSM API 概述

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

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

调用流程通常分为两步：

1. 登录：向 /[webapi](https://www.explinks.com/wiki/web-api/)/auth.cgi 发送账号密码换取 sid
2. 业务请求：在后续请求中带上 sid，并指明所用 API 与方法

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

三、远程文件管理 API 接口

3.1 登录获取会话

curl -k -X GET 'https://  :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://  :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://  :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://  :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://  :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://  :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://  :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 支持两种维度的权限：

1. 共享文件夹权限（Share Folder 权限）
2. 基于 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://  :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://  :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://  :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://  :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://  :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://  :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://  :5001/webapi/entry.cgi'
  -d 'api=SYNO.Backup.Task&method=list&version=1'
  -d 'sid=xxx'

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

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

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

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

对其他设计师禁止写入 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))

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](https://www.explinks.com/wiki/web-api/)/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))

七、最佳实践与性能建议

1. 会话管理：避免频繁登录登出，可缓存 sid 并监控其过期状态。
2. 批量操作：对于大量文件或用户操作，使用批量接口（如 multiple 参数）可提升效率。
3. 网络安全：务必通过 HTTPS，且在脚本中保护好 NAS 管理账号与密码。
4. 限速与资源分配：利用 API 设置传输限速，避免备份或大规模文件操作影响生产环境业务。
5. 日志与告警：结合 DSM 日志中心与邮件／短信通知功能，及时掌握任务执行情况与异常。

八、总结

通过本文，你已掌握基于 DSM API 的三大核心能力：

• 远程文件管理：上传、下载、移动、复制、删除文件与目录
• 用户权限管理：从共享文件夹权限到 Windows ACL 细粒度控制
• 自动备份配置：创建、调度与监控备份任务

这些接口可帮助你将 NAS 深度集成到自动化运维、持续交付、企业协作等场景中，实现高效、安全、可扩展的存储管理解决方案。希望本文能为你的 NAS API 开发提供清晰指导，助力构建更智能的存储与备份体系！

原文引自YouTube视频：https://www.youtube.com/watch?v=LihsU5hHm3k