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

作者：xiaoxin.gao · 2025-09-26 · 阅读时间：11分钟
NAS NAS设备 NAS远程文件管理API RESTful API Synology DSM API 用户权限管理

文章目录

  1. 一、引言
  2. 二、Synology DSM API 概述
  3. 三、远程文件管理 API 接口
  4. 四、用户权限管理 API 接口
  5. 五、自动备份 API 接口
  6. 六、实战示例：Python 脚本批量管理
  7. 七、最佳实践与性能建议
  8. 八、总结

随着家庭和中小型企业对数据存储需求的不断增长，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/auth.cgi 发送账号密码换取 sid
  2. 业务请求：在后续请求中带上 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 支持两种维度的权限：

  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:// < 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 示例，展示如何：

  1. 登录 DSM
  2. 创建用户并赋予共享文件夹读写权限
  3. 设置 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))

七、最佳实践与性能建议

  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
热门推荐
一个账号试用1000+ API
助力AI无缝链接物理世界 · 无需多次注册
3000+提示词助力AI大模型
和专业工程师共享工作效率翻倍的秘密

热门API

最新文章