reginleif88/proxtagger

ProxTagger

概述

ProxTagger提供简单而强大的Web界面，用于管理Proxmox虚拟机（VM）和容器的标签。它通过单个和批量操作简化标签管理，支持自动条件标签规则，并提供备份与恢复功能，以保护当前Proxmox Backup Server未备份的标签系统。

核心功能和特性

综合标签管理

• 通过交互式表格（由DataTables提供支持）查看所有VM和容器及其标签，支持排序和分页。
• 通过简洁直观的界面为单个VM添加/删除标签，并提供增强的视觉反馈。
• 对多个VM执行批量添加或删除标签操作，选择状态在页面/筛选器切换时保持不变。
• 一键清除批量操作面板中的当前VM选择。

高级过滤与搜索

• 使用专用过滤面板按主机、VMID范围和名称模式筛选VM/容器。
• 一键选择所有符合当前筛选条件的VM/容器。
• 全局搜索栏支持正则表达式，可对所有列进行强大的表格过滤。

条件标签管理

• 创建基于VM/容器属性自动应用或移除标签的规则。
• 带有AND/OR逻辑运算符的高级条件构建器，支持复杂过滤。
• THEN/ELSE操作 - 对匹配和非匹配VM执行不同行为。
• 通过cron表达式安排规则自动运行或手动执行。
• 测试模式与模拟运行功能，可预览更改。
• 规则执行历史记录和全面日志。

备份与恢复

• 将标签配置下载为JSON文件。
• 从先前备份中恢复标签。

交互式UI

• 动态表格，支持浏览大量VM/容器。
• 一致的 Toast 通知，为用户操作提供反馈。

安全与灵活性

• 使用Proxmox API令牌进行安全认证。
• 采用官方Proxmox API。

使用场景和适用范围

适用于Proxmox VE环境中需要高效管理大量VM和容器标签的用户，包括：

• 系统管理员和IT运维人员，需简化多VM标签的添加、删除和批量操作。
• 需要通过自动规则（如基于资源配置、HA状态）动态管理标签的场景。
• 希望保护标签配置（Proxmox Backup Server未涵盖）的用户，需备份与恢复功能。
• 需要高级筛选和搜索功能来快速定位特定VM/容器并管理其标签的场景。

使用方法和配置说明

前提条件

• Proxmox VE服务器
• 具有适当权限的API令牌（详见API令牌设置部分）
• Docker（若以容器方式运行）
• Python 3.6+（若本地构建）

使用Docker运行

使用docker compose

创建docker-compose.yml文件（或使用仓库中的配置）运行ProxTagger容器：

yaml
services:
  proxtagger:
    image: reginleif88/proxtagger:latest
    container_name: proxtagger_app
    ports:
      - "5660:5660"
    environment:
      - PORT=5660
    volumes:
      - proxtagger_config:/app
    restart: unless-stopped

volumes:
  proxtagger_config:
    name: proxtagger_config
    driver: local

执行以下命令启动容器，然后在浏览器中访问http://localhost:5660：

bash
docker compose up -d

使用docker run

拉取最新镜像并运行容器，映射端口、设置环境变量、使用持久卷存储配置：

bash
# 拉取最新镜像
docker pull reginleif88/proxtagger:latest

# 运行容器
docker run --detach --name proxtagger_app \
  --publish 5660:5660 \
  --env PORT=5660 \
  --volume proxtagger_config:/app \
  --restart unless-stopped \
  reginleif88/proxtagger:latest

在浏览器中访问http://localhost:5660。

配置

API令牌设置

需创建具有以下权限的Proxmox API令牌：

必需权限：

• VM.Audit（列出VM和容器）
• VM.Config.Options（读取和修改标签）

可选权限（用于条件标签功能）：

• Sys.Audit（获取HA状态和集群资源）
• VM.Backup（检查备份状态）
• VM.Snapshot（检查快照信息）
• Datastore.Audit（可能需要用于备份信息）

注意：若无可选权限，基本标签功能仍可使用，但基于HA状态、备份或快照的条件标签规则可能无法正常工作。

创建API令牌步骤：

1. 登录Proxmox Web界面
2. 导航至“数据中心 → 权限 → API令牌”
3. 点击“添加”并按照提示操作
4. 重要：记录令牌ID/名称和密钥 - 密钥仅显示一次！

首次设置

1. 首次启动后，系统会提示输入Proxmox连接详情：

   • 主机（IP或域名）
   • 端口（默认：8006）
   • 用户（如：root@pam）
   • 令牌名称和值
   • SSL验证开关（自签名证书需禁用）

2. 连接成功后，系统会自动创建初始标签备份。

使用指南

VM/容器表格

• 使用右上角搜索栏筛选表格，支持正则表达式，可跨所有列过滤。
• 点击列标题进行排序，使用分页控件浏览多页结果。
• 通过表格第一列的复选框选择VM/容器，选择状态在页面/筛选器切换时保持。

标签管理

单个标签操作

• 点击“标签”列中的“+”按钮，为单个VM添加标签；点击标签芯片上的“x”移除标签。

批量标签操作

• 使用“批量标签管理”面板：
  • 通过“筛选VM”部分按主机、VMID范围或名称模式缩小范围，点击“选择所有筛选结果”快速选择匹配VM。
  • 点击“清除所选VM”按钮取消当前选择。
  • 选择“添加标签”或“移除标签”操作，选择现有标签或创建新标签（仅添加模式支持），点击“应用”执行批量操作。

条件标签

1. 访问：点击导航菜单中的“条件标签”进入自动标签系统。

2. 快速模板：使用预构建模板快速创建规则：

   • Debian LXC标签：自动将所有基于Debian的容器标记为“deb-lxc”
   • HA验证：为同时启用复制和HA的VM添加“HA”标签，其他VM移除该标签
   • 高资源VM：将具有4核以上CPU和8GB以上内存的VM标记为“high-resource”

3. 自定义规则：使用规则构建器创建自定义规则：

   • 添加基于VM属性（CPU、内存、操作系统类型、HA状态等）的条件。
   • 使用AND/OR逻辑组合多个条件。
   • 设置THEN操作（对匹配VM添加/移除标签）。
   • 设置ELSE操作（对非匹配VM添加/移除标签）。
   • 通过cron表达式配置自动执行计划。

4. 测试与管理：

   • 使用“测试规则”执行模拟运行，预览受影响的VM。
   • 从规则表格查看、编辑、删除规则，手动执行规则，监控执行历史和结果。

备份与恢复

• 导出标签：点击侧边栏中的“导出标签”下载备份JSON文件。
• 导入标签：点击“导入标签”并选择先前导出的备份文件。

注意：恢复标签时，系统通过VMID、节点和类型匹配VM，并用导入的标签替换现有标签。若备份文件中的VM未找到，会提供反馈。

故障排除

常见问题

• 无VM显示：确保API令牌在适当级别（/或特定节点）具有VM.Audit和VM.Config.Options权限。

• 条件标签问题：特定条件属性无法工作时：

  • HA属性：需Sys.Audit权限
  • 备份状态：需VM.Backup权限，可能还需Datastore.Audit权限
  • 快照信息：需VM.Snapshot权限

• 连接失败：检查主机名、端口和网络连接。

• SSL错误：自签名证书需禁用SSL验证。

• 正则表达式搜索问题：确保使用有效的JavaScript正则表达式语法，无效模式可能导致错误或意外结果（检查开发者控制台）。

技术细节

ProxTagger基于以下技术构建：

• 后端：Python（Flask Web框架），使用Jinja2模板引擎。
• 前端：Bootstrap 5（样式），DataTables（表格交互），自定义JavaScript（ES模块组织）。
• 存储：本地.json文件存储连接详情和数据。