外观
API Token 与最小权限
写一个备份检查脚本、接一个自动化工具，第一反应往往是把 root 的密码填进配置文件。这篇教你用 API Token 替代——权限可控、能单独撤销、不影响账号本身。
为什么需要它
用账号密码调 API 有几个问题：
- 改密码，所有用它的脚本一起失效。
- 密码等于账号的全部权限，没法只给「查看状态」这一项。
- 密码泄露了，只能改密码，影响所有用到这个密码的地方。
API Token 是挂在某个用户名下的独立凭证，这几点都能解决。
开始之前
- 需要一个已存在的用户（任何认证域都行），建议专门建一个用途单一的用户，比如
monitor@pve，而不是直接用root@pam。 - 先读完用户、组、角色与权限路径，创建 Token 前要想清楚它需要哪些路径的哪个角色。
操作步骤
1. 创建 Token
数据中心 → 权限 → API Tokens → 添加：
| 字段 | 说明 |
|---|---|
| User | Token 挂在哪个用户下 |
| Token ID | 自己起名，例如 monitor-token |
| Privilege Separation | 默认勾选，建议保持勾选 |
| Expire | 建议填一个到期时间，忘了撤销的 Token 到期后自动失效 |
命令行等价操作：
sh
# 宿主机 shell
pveum user token add monitor@pve monitor-token --privsep 1 --expire 0Token Secret 只显示这一次
创建成功后弹出的 Secret，关闭弹窗就再也看不到，只能删除重建。立刻复制进密码管理器，不要临时存在聊天记录或便签里，更不要写进会提交到 Git 仓库的配置文件。
2. 理解 Privilege Separation
- 勾选（默认，推荐）：Token 需要单独授权，它的最终权限是「用户权限」和「Token 自己权限」的交集。就算挂着的用户是管理员，没给 Token 单独授权，它什么都做不了。
- 不勾选：Token 直接继承用户的全部权限，等同于用密码的效果，只是换了一种凭证形式。只有确定这个集成需要用户全部权限时才关掉。
3. 给 Token 授权
保持 Privilege Separation 开启时，必须单独给 Token 授权，路径和角色的用法与用户完全一样：
数据中心 → 权限 → 添加 → API Token 权限，或者：
sh
# 只给这个 Token 只读权限，路径限定在需要监控的范围
pveum acl modify / --tokens 'monitor@pve!monitor-token' --roles PVEAuditor4. 在请求里使用
Token 通过 HTTP 头传递，格式固定：
text
Authorization: PVEAPIToken=USER@REALM!TOKENID=UUID例如用 curl 验证一次连通性：
sh
# 本地电脑或任意能访问 PVE API 的机器
curl -k -H "Authorization: PVEAPIToken=monitor@pve!monitor-token=<刚才复制的Secret>" \
https://<pve地址>:8006/api2/json/nodes-k 是跳过证书校验，仅用于测试自签证书环境；生产环境应该配置受信任证书，见宿主机加固。
检查结果
pveum user token list monitor@pve：确认 Token 存在且未过期。pveum user token permissions monitor@pve monitor-token --path /：确认 Token 的实际有效权限，不是「看起来给了」，而是真正生效的交集。- 用上面的 curl 命令实际发一次请求，确认能拿到预期数据，且不能访问未授权的路径（故意换一个更敏感的接口试试，应该被拒绝）。
常见问题
创建了 Token、也授权了，请求还是 401/403。 确认 Header 里的等号和感叹号没写错——格式是 USER@REALM!TOKENID=SECRET，! 和 = 都不能少或写反位置。
Token 突然失效。 检查是不是设置了 --expire，到期后 Token 自动拒绝所有请求，需要重新创建或修改过期时间。
忘了 Secret 怎么办。 没有办法找回，只能 pveum user token modify <user> <tokenid> --regenerate 1 重新生成（会让旧 Secret 立刻失效，用到旧值的地方要一起更新），或者删掉重建。
禁用了用户，Token 还能用吗。 用户被禁用或删除后，挂在它下面的 Token 也会失效，因为最终权限计算离不开用户本身的状态。