字
字节笔记本
2026年2月23日
synologydsm-api：Synology DSM Python API 库
本文介绍 synologydsm-api，一个用于与 Synology DSM（群晖磁盘Station管理器）进行交互的 Python API 库。该库提供了完整的 DSM API 封装，支持登录认证、存储管理、下载站、监控站等功能的程序化访问。
项目简介
synologydsm-api 是一个开源的 Python 库，由 HACF 社区维护（原项目从 ProtoThis/python-synology 分叉）。该项目在 GitHub 上获得 33 stars，使用 Python 编写，采用 Black 代码格式化规范。
该库的主要用途是：
- 通过 Python 代码自动化管理 Synology NAS
- 集成 DSM 功能到 Home Assistant 等智能家居平台
- 开发基于 DSM API 的第三方应用
核心特性
- 完整的 API 覆盖：支持 DSM 核心功能、存储管理、下载站、监控站等模块
- 自动认证管理：支持用户名/密码登录、双因素认证（2SA）、设备令牌持久化
- 会话管理：自动处理会话过期和重连机制
- SSL/TLS 支持：支持 HTTPS 连接，可配置证书验证
- 调试模式：提供详细的请求/响应日志输出
- 异常处理：完善的错误类型定义，便于问题诊断
技术栈
- Python 3.6+ - 主要编程语言
- requests - HTTP 请求处理
- urllib3 - 底层 HTTP 客户端
- Poetry - 依赖管理和打包
安装指南
使用 pip 安装
bash
pip install synologydsm-api使用 Poetry 安装
bash
poetry add synologydsm-api快速开始
基础用法
python
from synology_dsm import SynologyDSM
# 创建 API 实例
api = SynologyDSM(
dsm_ip="192.168.1.100",
dsm_port=5000,
username="admin",
password="your_password",
use_https=True,
verify_ssl=False
)
# 登录（可选，首次请求会自动登录）
api.login()获取系统信息
python
# 更新信息模块数据
api.information.update()
print(f"型号: {api.information.model}")
print(f"内存: {api.information.ram} MB")
print(f"序列号: {api.information.serial}")
print(f"温度: {api.information.temperature} °C")
print(f"运行时间: {api.information.uptime}")
print(f"DSM 版本: {api.information.version_string}")获取系统利用率
python
api.utilisation.update()
print(f"CPU 负载: {api.utilisation.cpu_total_load} %")
print(f"内存使用率: {api.utilisation.memory_real_usage} %")双因素认证（2SA）支持
python
from synology_dsm.exceptions import SynologyDSMLogin2SARequiredException
try:
api.login()
except SynologyDSMLogin2SARequiredException:
# 需要输入 OTP 验证码
otp_code = input("请输入 OTP 验证码: ")
api.login(otp_code)
# 保存设备令牌以便下次免密登录
device_token = api.device_tokenAPI 模块详解
核心模块
| 模块 | 访问方式 | 说明 |
|---|---|---|
| 系统信息 | api.information | DSM 版本、型号、序列号等 |
| 网络信息 | api.network | 网络配置和状态 |
| 系统状态 | api.system | 系统健康状态 |
| 升级信息 | api.upgrade | DSM 更新状态 |
存储模块
| 模块 | 访问方式 | 说明 |
|---|---|---|
| 存储管理 | api.storage | 磁盘、存储池、卷信息 |
| 共享文件夹 | api.share | 共享文件夹管理 |
应用模块
| 模块 | 访问方式 | 说明 |
|---|---|---|
| 下载站 | api.download_station | Download Station 管理 |
| 监控站 | api.surveillance_station | Surveillance Station 管理 |
| 安全顾问 | api.security | 安全扫描和报告 |
核心类解析
SynologyDSM 类
主类 SynologyDSM 提供了与 DSM 交互的所有功能：
python
class SynologyDSM:
def __init__(
self,
dsm_ip: str, # DSM IP 地址或域名
dsm_port: int, # DSM 端口（默认 5000/5001）
username: str, # 用户名
password: str, # 密码
use_https: bool = False, # 是否使用 HTTPS
verify_ssl: bool = False, # 是否验证 SSL 证书
timeout: int = None, # 请求超时时间（默认 10 秒）
device_token: str = None, # 设备令牌（用于 2SA）
debugmode: bool = False, # 调试模式
)请求方法
python
# GET 请求
result = api.get("SYNO.API.Info", "query")
# POST 请求
result = api.post("SYNO.API.Auth", "login", params={
"account": "username",
"passwd": "password"
})更新所有模块
python
# 更新所有已初始化的模块
api.update()
# 同时更新信息和网络模块
api.update(with_information=True, with_network=True)异常处理
库中定义了多种异常类型，便于精确捕获错误：
python
from synology_dsm.exceptions import (
SynologyDSMLoginInvalidException, # 登录凭据无效
SynologyDSMLoginDisabledAccountException, # 账户已禁用
SynologyDSMLoginPermissionDeniedException, # 权限不足
SynologyDSMLogin2SARequiredException, # 需要双因素认证
SynologyDSMLogin2SAFailedException, # 2SA 验证失败
SynologyDSMAPINotExistsException, # API 不存在
SynologyDSMAPIErrorException, # API 错误
SynologyDSMRequestException, # 请求异常
)项目链接
- GitHub 仓库：https://github.com/hacf-fr/synologydsm-api
- PyPI 包：https://pypi.org/project/synologydsm-api
- Home Assistant 集成：该库是 Home Assistant Synology DSM 集成的底层依赖
注意事项
- DSM 版本兼容性：该库支持 DSM 5.x 及以上版本，部分功能在不同 DSM 版本中可能有差异
- 权限要求：某些 API 需要管理员权限才能访问
- 会话过期：DSM 会话有过期时间，库会自动处理重连
- SSL 证书：使用自签名证书时需要设置
verify_ssl=False - 项目归档：该仓库已于 2025 年 2 月 9 日被所有者归档，现为只读状态
分享: