proxmox-admin

Proxmox VE 运维专业知识

AI Agent 技能：用于管理 Proxmox Virtual Environment 基础设施的运维知识

概述

此技能为 AI Agent 提供 Proxmox VE 运维专业知识，涵盖：

• VM 和 LXC 生命周期管理 - 从创建到退役
• 存储操作 - 配置、内容管理、备份策略
• 高可用性 - HA 组、资源管理、故障转移
• 集群操作 - 多节点管理、迁移、复制
• 证书管理 - 安装、续期、ACME 集成
• ACME 配置 - 提供商设置、证书申请、自动化
• 通知 - 目标配置、投递验证、告警
• 故障排查 - 常见问题、API 特性、解决方案模式
• 安全性 - 权限模型、API 令牌最佳实践
• 性能 - 监控、资源优化

目标受众：执行日常 Proxmox 运维、基础设施自动化或事件响应的 AI Agent。

---

架构概述

Proxmox VE 集群概念

节点：运行 Proxmox VE 的物理服务器

• 托管 VM 和 LXC 容器
• 提供本地存储
• 参与集群仲裁

存储：共享或本地存储后端

• 类型：Directory、LVM、ZFS、Ceph、NFS、iSCSI
• 内容类型：镜像、ISO、备份、模板
• 可以是节点本地存储，也可以是集群共享存储

网络：虚拟网络基础设施

• 使用 Linux 网桥实现 VM/LXC 连通性
• 使用 VLAN 进行网络分段
• 使用 SDN（软件定义网络）实现高级场景

集群：协同工作的节点组

• 通过 pmxcfs 共享配置
• 使用 HA 实现自动故障转移
• 在节点之间进行在线迁移

---

运维手册

1. VM 生命周期管理

创建 → 配置 → 监控 → 备份 → 删除

创建

1. Get next available VMID
2. Create VM with basic config (CPU, memory, OS type)
3. Add disk(s) from storage
4. Configure network interface(s)
5. Set boot order
6. Start VM

关键注意事项：

• 为磁盘选择合适的存储（性能与容量之间的权衡）
• 使用 virtio 驱动以获得最佳性能（需要客户机支持）
• 配置 QEMU 客户机代理，以便更好地管理

配置

1. Review current config
2. Resize resources (CPU, memory, disk) as needed
3. Add/remove network interfaces
4. Configure firewall rules
5. Set up snapshots for rollback capability

最佳实践：

• 进行重大更改前创建快照
• 使用 cloud-init 实现自动化配置
• 启用 QEMU 客户机代理，以便执行平稳操作

监控

1. Check VM status (running, stopped, paused)
2. Monitor resource usage (CPU, memory, disk I/O)
3. Review task history for recent operations
4. Check logs for errors or warnings

需关注的指标：

• CPU 使用率和 steal time
• 内存压力和交换空间使用率
• 磁盘 I/O 等待时间
• 网络吞吐量

备份

1. Create snapshot for quick rollback
2. Schedule backup job (vzdump)
3. Verify backup completed successfully
4. Test restore periodically
5. Prune old backups to manage space

备份策略：

• Snapshot 模式：速度快，需要存储支持
• Suspend 模式：备份期间暂停 VM
• Stop 模式：停止 VM，以确保备份一致性

退役

1. Create final backup
2. Stop VM gracefully
3. Remove from HA if configured
4. Delete VM and associated disks
5. Clean up firewall rules
6. Update documentation

---

2. LXC 容器管理

容器与 VM 的对比：

• 更轻量（共享内核）
• 启动速度更快
• 开销更低
• 隔离性不如 VM

容器操作

1. Create from template
2. Configure resources (CPU, memory, swap)
3. Add mount points for storage
4. Configure network
5. Start container
6. Access via console or SSH

与 VM 的主要区别：

• 挂载点使用 mp0、mp1（而非 disk0、disk1）
• 无需配置 BIOS/UEFI
• 可直接访问内核（特权容器）或受限访问（非特权容器）
• 快照/恢复操作速度更快

---

3. 存储管理

存储配置

1. List available storage
2. Add new storage backend (NFS, Ceph, etc.)
3. Configure content types (images, backups, ISOs)
4. Set storage as default for specific content
5. Monitor storage usage

内容管理

1. Upload ISOs/templates to storage
2. Download from URL to storage
3. List storage content
4. Delete unused content
5. Restore files from backups

备份管理

1. Create backup jobs (manual or scheduled)
2. Configure retention policy
3. Prune old backups automatically
4. Restore from backup
5. Verify backup integrity

备份最佳实践：

• 使用压缩以节省空间
• 将备份存储在独立存储中
• 定期测试恢复流程
• 记录备份计划
• 监控备份任务的成功与失败情况

---

4. 高可用性（HA）

HA 配置

1. Create HA group (define node priorities)
2. Add VM/LXC to HA management
3. Configure HA settings (max relocate, max restart)
4. Monitor HA status
5. Test failover scenarios

HA 状态：

• started：资源在指定节点上运行
• stopped：资源已被主动停止
• fence：节点已被隔离，资源将在其他位置重新启动
• error：HA 管理器遇到错误

适用 HA 的场景：

• 需要高运行时间的关键服务
• 需要自动故障转移
• 集群有 3 个或更多节点（以满足仲裁要求）

---

5. 迁移

实时迁移（在线）

1. Verify target node has resources
2. Check shared storage access
3. Initiate migration
4. Monitor migration progress
5. Verify VM running on new node

要求：

• VM 磁盘使用共享存储
• 节点之间网络连通
• CPU 类型兼容（或已屏蔽 CPU 标志）

离线迁移

1. Stop VM/LXC
2. Migrate to target node
3. Start on new node

适用场景：

• 没有可用的共享存储
• 源节点需要维护
• CPU 不兼容

---

故障排查指南

常见问题

1. VM 无法启动

症状：启动操作失败或 VM 立即停止

原因：

• 节点资源不足
• 存储不可用
• 存在锁定文件
• 配置错误

解决方法：

1. Check node resources (memory, CPU)
2. Verify storage is mounted and accessible
3. Remove lock file if stale
4. Review VM config for errors
5. Check logs: /var/log/pve/tasks/

2. 迁移失败

症状：迁移操作报错或超时

原因：

• 网络连接问题
• 存储未共享
• CPU 不兼容
• 目标节点资源不足

解决方法：

1. Verify network between nodes
2. Check storage is accessible from both nodes
3. Review CPU flags compatibility
4. Ensure target node has capacity
5. Try offline migration if live fails

3. 备份作业失败

症状：备份任务显示错误状态

原因：

• 存储空间不足
• VM 被另一个操作锁定
• 创建快照失败
• 网络超时（用于远程存储时）

解决方法：

1. Check storage space availability
2. Verify no other operations running on VM
3. Try manual backup to isolate issue
4. Review backup job logs
5. Prune old backups to free space

4. HA 故障转移不起作用

症状：故障后 VM 未在另一个节点上重启

原因：

• 集群失去法定人数
• HA 服务未运行
• 未配置隔离
• HA 组中的所有节点均不可用

解决方法：

1. Check cluster quorum status
2. Verify HA service running on all nodes
3. Review HA group configuration
4. Check fencing configuration
5. Manually start VM if needed

5. 存储性能问题

症状：VM 性能缓慢，I/O 等待时间长

原因：

• 存储后端过载
• 网络瓶颈（用于远程存储时）
• 磁盘缓存设置不理想
• 同一存储上的 VM 过多

解决方法：

1. Monitor storage backend performance
2. Check network throughput to storage
3. Adjust VM disk cache settings
4. Distribute VMs across multiple storage
5. Consider faster storage tier

更多故障排查信息：请参阅 proxmox-troubleshooting.md

---

安全最佳实践

API 令牌管理

令牌创建：

1. 为自动化创建专用用户
2. 分配所需的最低权限
3. 生成 API 令牌（而非密码）
4. 安全存储令牌（环境变量、机密管理器）
5. 定期轮换令牌

权限模型：

• 使用角色对权限进行分组
• 将角色分配给用户/令牌
• 遵循最小权限原则
• 定期审计权限使用情况

访问控制

用户管理：

• 使用域（PAM、LDAP、AD）进行身份验证
• 创建组以实现基于角色的访问控制
• 将用户分配到组
• 定期检查访问权限

网络安全：

• 通过 IP 限制 API 访问（防火墙规则）
• 对 API 连接使用 SSL/TLS
• 为用户启用双因素身份验证
• 监控身份验证日志

---

性能优化

资源分配

CPU：

• 不要过度超额分配 CPU 核心
• 为非关键 VM 设置 CPU 限制
• 为延迟敏感型工作负载绑定 CPU
• 监控 CPU 窃取时间

内存：

• 启用气球驱动以动态分配
• 设置适当的内存限制
• 监控交换空间使用情况（应尽量减少）
• 为大内存 VM 使用大页

磁盘 I/O：

• 使用 virtio-scsi 以获得最佳性能
• 为 SSD 启用 discard/TRIM
• 配置适当的 I/O 调度器
• 监控磁盘延迟和吞吐量

监控策略

关键指标：

• 节点 CPU、内存和磁盘使用情况
• VM 资源消耗
• 存储性能（IOPS、延迟）
• 网络吞吐量
• 任务完成时间

监控工具：

• Proxmox 内置指标（RRD 数据）
• 外部监控（Prometheus、Grafana）
• 日志聚合（syslog、ELK stack）
• 对关键阈值设置告警

---

运维工作流

如需详细的分步工作流，请参阅：

• proxmox-workflows.md - 常见运维模式

如需故障排查详情，请参阅：

• proxmox-troubleshooting.md - API 特性及解决方案

---

快速参考

VM 状态

• running：VM 已开机
• stopped：VM 已关机
• paused：VM 执行已暂停
• suspended：VM 状态已保存到磁盘

存储类型

• dir：基于目录的存储
• lvm：LVM 卷组
• zfs：ZFS 存储池
• ceph：Ceph RBD
• nfs：NFS 共享
• iscsi：iSCSI 目标

备份模式

• snapshot：速度快，需要存储支持
• suspend：备份期间暂停 VM
• stop：备份时停止 VM

HA 状态

• started：在分配的节点上运行
• stopped：已主动停止
• fence：节点已隔离，正在其他位置重启
• error：HA 管理器错误

---

许可证

MIT 许可证 - 属于 @bldg-7/proxmox-mcp 软件包的一部分