一、引言

在傳統的文件服務器架構中，管理員需要通過文件共享協議（如 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

#你可能也喜歡這些API文章!

API 設計原理：從理論到實踐

DeepSeek R1 × 飛書多維表格賦能教育領域

使用NestJS和Prisma構建REST API：身份驗證

一步步教你進行 Python REST API 身份驗證

微信API接口調用憑證+Access token泄露

REST API 基礎：定義、示例及使用方法

HTTP API vs WebSocket API：選擇哪個來實現實時通信？