第 6 篇 / 共 8 篇
06｜PVE 身份、ACL、API Token 和 AI 只读审计设计
知识分类：安全与访问控制｜2026-10-17 整理｜PVE Token 权限规则经官方文件核实；现场账号、角色、Token 与插件安装状态未验证。
一、将人、服务与审计账号拆开
PVE 使用 Realm、用户、角色（Role）、访问控制列表（ACL）、API Token 组合控制权限。可采用日常 Web 管理身份、受控应急身份与专用审计身份三层架构；审计身份不得复用宿主 root 或管理员 API 令牌。知识库真实用户名、令牌 ID、密钥、TOTP 种子均不写入本文。
官方角色 PVEAuditor 是只读角色，PVEAdmin 并非“只读管理员”。按职责对 /nodes/<node>、/vms/<id>、/storage/<storage> 等路径授予最少权限。审计工具能看到某种资源并不代表理应获得访问其他资源的权限。
二、Token privsep=1 的正确理解
Proxmox 官方规定，权限分离 Token 的有效权限 = 对应用户权限与 Token 自身路径 ACL 的交集。为用户赋予读权限而不给 Token 分配读 ACL，Token 可能仍返回 403；只配 Token 不配用户也可能无效。不要为绕过 403 把 Token 改为 privsep=0，因为它会直接继承用户全部权限。API Token 不自动经过用户交互式 TOTP 验证，必须当作独立机密管理。
只读查看示例（仅授权管理员、勿分享原始输出）：
pveum user list
pveum role list
pveum acl list
pveum user permissions <AUDITOR_USER@pve>
pveum user token permissions <AUDITOR_USER@pve> <TOKEN_NAME>保密要求：不读取、不输出、不复制 Secret 到聊天、日志、文档或 Git。Token 创建时密钥一般只展示一次；轮换、撤销需独立审批，避免误中断正常监控。
三、日志权限和最小 GET 接口
节点状态、VM/CT 配置、存储摘要与节点日志可能需要不同权限。官方权限表中 Sys.Audit 表示读取节点状态/配置；VM.Audit 用于 VM 配置；Datastore.Audit 用于存储；Sys.Syslog 用于系统日志。不要假定 PVEAuditor 自动包括所有需要的日志权限；要以当前版本 API Viewer 的端点要求核对。日志包含个人资料、Token 头、内部 IP 时还要再次脱敏。
推荐“正向白名单”：只允许明确的只读 GET 路径，节点、VM/CT ID 固定集合，单次请求受限、响应大小受限。即使 API Token 本身只读，运行进程依然不能获得通用 shell、宿主文件写入或任意网络访问。GET 的低风险只以已核实的端点行为与权限为前提，不意味着所有 URL 都可安全抓取。
四、AI 审计工具应有哪些硬限制
| 审计功能 | 必要约束 | 输出 |
|---|---|---|
资产摘要 inventory | 固定节点、限定字段 | VM/CT 数量、状态摘要 |
配置摘要 guest-config | 已授权 ID 白名单 | CPU/内存/挂载等脱敏差异 |
节点日志 node-logs | 明确时间窗口、最多 200 条等自定义上限 | 结构化错误摘要与截断标识 |
故障分类 node-errors | 不跳转到未授权节点或目录 | 证据、原因假设、验证动作 |
200 条、输出大小及时间窗口是内部拟定的审计合同，而非 PVE API 的固定限制；不同方案存在 15 分钟和 1/6/24/48 小时等差异，正式使用前必须统一版本。工具不能以修改 allowlist 解决权限失败，更不能使用 curl -k 长期关闭证书校验。
五、分层诊断 401 / 403 / allowlist / EACCES
| 现象 | 优先判断 | 不应采取的措施 |
|---|---|---|
| HTTP 401 | Token 格式、签名/过期/禁用等认证失败 | 直接给管理员权限 |
| HTTP 403 | 路径权限、用户/Token ACL 交集、端点附加权限 | 关闭权限分离 |
allowlist miss | 执行器不允许此命令/参数 | 放开 bash 或任意 exec |
EACCES | 本地文件、目录、可执行位或进程权限问题 | 全局 chmod 777 |
| TLS 错误 | CA、证书时间、主机名/IP SAN、信任链 | 永久跳过校验 |
| 超时 | 网络、API 进程、负载和路径可达性 | 反复无间隔重试 |
API 或执行器错误未解决之前只能撰写建议，不能宣称插件已部署成功或监控已在线。
关联资料与验证依据
- 内部资料：《PVE 安全整改中文操作手册》；历史“只读 PVE API 审计脚本/插件设计”属于方案而非现场验收。
- 官方：https://github.com/proxmox/pve-docs/blob/master/pveum.adoc
- 官方：https://pve.proxmox.com/pve-docs/api-viewer/
结论：真正的只读须同时满足身份最小权限、接口白名单、执行器白名单、日志脱敏和写入拒绝测试五个条件。
2026-10-17 第二阶段核验补充（必须替换旧状态）
- 2026-10-16 已有现场记录确认：用于固定审计查询的权限分离 Token（
privsep=1）和PVEAuditor最小权限路径已核对；通过可信 CA 成功执行过固定inventory和guest-configGET。原文“固定 GET 尚未验收”已过时。 - 2026-10-17 本轮以不同 SSH 登录身份尝试固定
inventory，遇到读取服务账号私有.env的EACCES。这是当前会话身份的本地文件权限拒绝，不能据此推翻此前以服务账号成功的记录，也不能当作 API 401/403。 - 不改
.env属主、权限或 Token；不通过 root/sudo、复制密钥或禁用 TLS 校验绕过限制。实时权限表、日志接口及完整拒绝测试仍未在本轮获得直接证据。