【转】Synology DiskStation Administration CLI Guide 官方文档导读与命令速查
先说结论
Synology 这份官方 CLI 管理指南并不是一本面向普通 DSM 图形界面用户的入门手册，而是一份给脚本、自动化和系统集成场景准备的命令参考。它覆盖了 DSM 中最常见的几类管理动作：本地用户、本地群组、共享文件夹、网络配置、服务控制、工作组或 ADS 域设置，以及错误码查询。
这篇文章是基于 Synology 官方 PDF《CLI Administrator Guide for Synology NAS》整理的中文导读和命令速查。由于原 PDF 属于 Synology 官方版权文档，本文不会全文复制或逐段翻译原文，而是按博客阅读习惯重新组织成一份便于检索、理解和日常运维使用的双语整理稿。需要逐字核对参数定义、版本差异或法律声明时，请直接阅读文末的官方 PDF 来源。
1. 这份指南适合谁看
如果你只是偶尔在 DSM 控制面板里新建用户、建共享文件夹、启停套件服务，那么图形界面通常已经足够。但在下面这些场景里，CLI 指南会更有价值：
- 需要用脚本批量创建、修改或删除账号。
- 需要在初始化 NAS 时自动设置共享目录、网络和域信息。
- 需要让外部程序调用 DSM 底层管理能力。
- 需要排查 DSM 返回的错误码含义。
- 需要在 SSH 环境中快速确认某个系统对象的状态。
这些命令都偏系统管理，很多动作需要 root 或等价权限。不要把它们当作普通用户命令随手执行，尤其是删除用户、删除群组、修改网络、重启服务这几类操作，执行前应该先确认目标对象和当前连接方式。
2. 文档结构
官方 PDF 很短，但信息密度比较高，大致分成三块：
| 章节 | 内容 | 阅读重点 |
|---|---|---|
| Chapter 1 | 简介 | 说明这些工具用于让应用程序使用 Synology DiskStation 资源 |
| Chapter 2 | 管理命令 | 用户、群组、共享文件夹、网络、服务、工作组和域 |
| Chapter 3 | 错误码 | DSM 命令和程序返回值的含义 |
真正有日常价值的是第二章。它把几个常用命令按对象分开：synouser 管用户，synogroup 管组，synoshare 管共享文件夹，synonet 管网络接口，synoservice 管服务，synowin 管 Windows 工作组或 ADS 域相关设置。
3. 用户管理：synouser
synouser 负责本地用户账号的增删改查类动作。官方文档列出的核心能力包括：
| 动作 | 用途 | 运维注意点 |
|---|---|---|
| help | 查看命令帮助 | 先用帮助确认当前 DSM 版本支持的参数 |
| add | 新建一个本地用户 | 需要提供用户名、密码、描述、过期状态、邮箱和应用权限 |
| del | 删除已有用户 | 系统、admin、guest 这类特殊账号不能按普通账号处理 |
| rename | 重命名本地用户 | 新用户名不能与现有账号冲突 |
| modify | 修改用户信息 | 适合批量更新描述、邮箱或过期状态 |
从自动化角度看，synouser 最容易踩坑的是字段顺序和用户名限制。用户名大小写不敏感，长度和字符集有明确限制；开头和结尾也有额外约束。脚本里最好先做一层输入校验，避免把非法用户名直接传给 DSM 命令。
密码字段也要谨慎处理。不要把明文密码写进可长期保存的脚本、日志或 CI 输出中。更稳妥的做法是从受控的密钥管理系统、临时环境变量或只读配置中读取，再确保命令执行日志不会泄露参数。
4. 群组管理：synogroup
synogroup 面向本地群组。它的操作模型和用户管理类似，但关注点从“账号属性”变成“组对象和成员关系”。
| 动作 | 用途 | 运维注意点 |
|---|---|---|
| add | 新建本地群组 | 适合初始化权限模型 |
| del | 删除群组 | 删除前先确认共享文件夹和 ACL 是否依赖该组 |
| rename | 重命名群组 | 避免和现有群组重名 |
| modify | 修改群组描述或成员 | 成员列表建议由脚本生成，减少手工误差 |
| get | 查询群组信息 | 适合发布前或变更后做校验 |
实际使用时，不建议把用户逐个绑定到共享文件夹权限上。更可维护的方式是先建立面向角色的群组，例如 media-admin、backup-writer、project-readonly，再把用户放进对应群组。这样后续用户变动时，只需要调整成员关系，不需要反复修改每个共享目录的权限。
5. 共享文件夹信息：synoshare
synoshare 处理共享文件夹相关信息。对于 NAS 来说，共享文件夹是权限、存储和服务入口的交汇点，所以这类命令要比用户和群组更谨慎。
官方指南把 synoshare 放在管理命令中，是因为脚本化场景经常需要读取或设置共享目录信息。例如：
| 场景 | 为什么需要 CLI |
|---|---|
| 初始化新设备 | 自动创建约定好的共享目录 |
| 部署备份任务 | 检查目标共享目录是否存在 |
| 权限巡检 | 对比共享目录配置和预期模板 |
| 服务迁移 | 批量确认共享目录名称和状态 |
如果只是查询信息，风险相对可控；如果要创建、删除或修改共享目录，务必先做 dry-run 或至少输出目标清单。共享目录通常承载真实数据，误删和误改的影响远大于普通配置项。
6. 网络设置：synonet
synonet 涉及网络配置。这个命令在远程 SSH 场景里尤其危险，因为网络配置一旦改错，当前 SSH 会话可能立刻断开，甚至需要到现场或通过其他管理通道恢复。
阅读这一节时，建议把它分成两类：
| 类别 | 典型用途 | 风险 |
|---|---|---|
| 查询类 | 查看网卡、地址或当前网络状态 | 低 |
| 修改类 | 调整 IP、网关、DNS 或接口配置 | 高 |
如果必须远程修改网络，建议先确认以下事项：
- 是否有第二条可用管理通道，例如 IPMI、虚拟机控制台、同网段备用地址或现场人员。
- 是否已经记录当前 IP、网关、DNS、网卡名称和路由。
- 是否能用一次性脚本在失败时自动回滚。
- 是否避开正在运行的备份、同步、下载或业务访问窗口。
网络命令不是不能自动化，而是必须把回滚路径设计在自动化之前。
7. 服务控制：synoservice
synoservice 是很多运维脚本会接触到的命令，因为它可以查询、启停或重启 DSM 服务。它适合处理下面这些任务：
| 任务 | 示例 |
|---|---|
| 状态检查 | 确认某个服务是否正在运行 |
| 故障恢复 | 服务异常后尝试重启 |
| 维护窗口 | 升级或迁移前暂停相关服务 |
| 自动化验证 | 发布脚本执行后确认依赖服务可用 |
使用这类命令时要避免“看到异常就重启”的反射动作。服务异常可能只是表象，底层原因可能是磁盘空间不足、数据库损坏、端口冲突、权限错误或配置文件不合法。更稳妥的顺序是：先查状态，再看日志，再确认依赖，最后才决定是否重启。
8. 工作组和 ADS 域：synowin
synowin 面向 Windows 工作组或 ADS 域相关设置。对于家庭或小团队 NAS，工作组配置可能已经足够；对于公司环境，NAS 往往需要加入域，统一使用域账号和权限策略。
这类命令的重点不是“能不能执行”，而是“执行后认证链路是否仍然完整”。在加入或修改域设置前，至少要确认：
- DNS 是否能正确解析域控。
- NAS 时间是否与域控保持同步。
- 管理员凭据是否有效。
- 本地备用管理员账号是否仍可登录。
- SMB、ACL 和共享目录权限是否符合预期。
域相关操作一旦失败，影响的不只是某个用户，而可能是所有依赖域认证的访问路径。
9. 错误码：不要只看数字
官方 PDF 的第三章列出了 Synology 错误编号。错误码很适合做脚本判断，但不能只看数字就直接下结论。更好的方式是把错误码、命令、参数、当前对象状态和系统日志放在一起看。
例如，一个“对象不存在”类错误，可能代表：
- 目标用户或群组确实不存在。
- 脚本传参顺序错了。
- 用户名大小写或特殊字符处理不一致。
- 命令在错误的 DSM 实例上执行。
- 权限不足导致查询结果不完整。
错误码是入口，不是完整诊断。
10. 建议的使用方式
如果要把这些命令纳入自己的运维脚本，我建议按下面的方式组织：
# 1. 先查询当前状态
# 2. 计算期望状态和当前状态的差异
# 3. 打印即将执行的变更
# 4. 明确确认后再修改
# 5. 修改后再次查询并校验
对于用户、群组、共享目录这类对象，脚本最好具备幂等性：目标已经存在时不重复创建，目标不存在时不盲目删除，属性一致时不做无意义修改。对于网络和域配置，还应该额外准备回滚方案。
11. 一页速查
| 命令 | 管理对象 | 适合场景 |
|---|---|---|
synouser |
本地用户 | 批量开户、改描述、过期账号、删除离职账号 |
synogroup |
本地群组 | 角色权限、成员关系、权限模板 |
synoshare |
共享文件夹 | 共享目录巡检、初始化、迁移前检查 |
synonet |
网络配置 | 查询网络状态、维护窗口内调整网络 |
synoservice |
DSM 服务 | 状态检查、启停服务、故障恢复 |
synowin |
工作组和 ADS 域 | Windows 网络、域加入、域设置维护 |
12. 小结
这份 Synology CLI 管理指南的价值不在于篇幅，而在于它把 DSM 中几个关键管理对象的命令入口集中列出来了。对于日常 NAS 用户，它可以当作 SSH 运维时的查阅资料；对于需要自动化的人，它是设计脚本时的边界清单；对于排障，它提供了命令层面的入口和错误码参考。
真正落地时要记住三点：
- 先查询，后修改。
- 先备份或记录当前状态，再执行高风险动作。
- 以官方 PDF 为最终依据，博客整理只作为阅读和速查辅助。
来源
本文为基于 Synology 官方文档的中文导读、速查和翻译整理，并非官方 PDF 全文转载。