ADMIN_TOOLS.md

🔧 管理员工具

用户配额管理

📝 脚本: admin_adjust_user_quota.py

用于调整用户的每日调用次数配额。

---

🚀 使用方法

1. 查看用户状态

export HF_TOKEN='your_hf_token_here'
python admin_adjust_user_quota.py <username> show

示例:

python admin_adjust_user_quota.py learnmlf show

输出: ```

📊 用户状态: learnmlf

日期: 2026-01-09 已用次数: 3/4 剩余次数: 1 状态: ✅ 可用

---

### 2. 重置用户配额（给满4次）

```bash
python admin_adjust_user_quota.py <username> reset

作用: 将用户今天的已用次数设为0，相当于给他4次新配额

示例:

python admin_adjust_user_quota.py learnmlf reset

流程:

1. 显示当前状态
2. 要求确认（输入 yes）
3. 重置为0
4. 显示更新后的状态

---

3. 设置已用次数

python admin_adjust_user_quota.py <username> set <count>

作用: 直接设置用户今天已用的次数

示例:

# 设置为已用2次（剩余2次）
python admin_adjust_user_quota.py learnmlf set 2

# 设置为已用0次（剩余4次）
python admin_adjust_user_quota.py learnmlf set 0

---

4. 增加额外配额

python admin_adjust_user_quota.py <username> add <extra_count>

作用: 给用户增加额外的调用次数（超过默认的4次）

示例:

# 给用户额外增加2次配额
python admin_adjust_user_quota.py learnmlf add 2

# 如果用户原本已用3次，增加2次后，变为已用1次（相当于总共6次配额）

逻辑:

• 原理：减少已用次数 = 增加剩余次数
• 如果用户已用3次，增加2次配额后，已用次数变为1次
• 用户实际可用：4 - 1 = 3次（比重置多2次）

---

📊 使用场景

场景1: 用户配额用完了，但需要紧急使用

# 快速重置，给他4次新配额
python admin_adjust_user_quota.py user123 reset

场景2: VIP用户，给他每天8次配额

# 假设他今天用了2次，给他增加4次额外配额
python admin_adjust_user_quota.py vip_user add 4
# 结果：已用次数从2变为-2，相当于还能用6次（总共8次）

场景3: 用户误操作浪费了配额

# 重置给他4次新配额
python admin_adjust_user_quota.py user456 reset

场景4: 查看用户使用情况

# 查看某个用户今天用了多少次
python admin_adjust_user_quota.py user789 show

---

🔐 安全注意事项

1. HF_TOKEN 权限: 需要对 Dataset 有写入权限的 Token
2. 确认操作: 所有修改操作都需要输入 yes 确认
3. 不可撤销: 修改后立即生效，无法撤销（但可以再次调整）
4. 日期隔离: 每天的配额独立，修改今天的不影响昨天/明天

---

📂 数据存储位置

HF Dataset: learnmlf/video-evaluations
├── call_counts/
│   └── 2026-01-09/
│       └── username.json  ← 这个文件被修改

文件格式:

{
  "user": "username",
  "date": "2026-01-09",
  "count": 2,
  "last_updated": "2026-01-09T12:34:56",
  "note": "Set to 2 by admin"
}

---

💡 常见问题

Q: 增加配额会影响其他天吗？

A: 不会。每天的配额独立存储，只影响当天。

Q: 可以给用户设置负数吗？

A: 可以，使用 add 命令增加足够多次数即可。负数意味着用户有"额外"配额。

Q: 用户看得到管理员的调整吗？

A: 用户只能看到剩余次数，看不到 note 字段的备注。

Q: 如何批量调整多个用户？

A: 可以写个 bash 循环：

for user in user1 user2 user3; do
    python admin_adjust_user_quota.py $user reset
done

---

🔄 与应用的集成

用户在前端看到的次数会实时更新：

• 应用从 call_counts/{date}/{username}.json 读取
• 管理员修改文件后，用户刷新页面即可看到新配额
• 无需重启应用

---

📝 日志

所有修改都会在 note 字段留下记录：

• "Reset by admin" - 管理员重置
• "Set to X by admin" - 管理员设置为X
• "Added X extra calls by admin (was Y)" - 管理员增加X次（原来是Y）