自动化脚本如何清理未使用刷新令牌

wen 实用脚本 2026-07-04 26

安全策略与工具实践指南

目录导读

为什么需要清理未使用的刷新令牌？
刷新令牌的核心机制与安全风险
自动化清理脚本的技术方案
主流工具的配置案例与实现步骤
常见问题与问答（FAQ）
最佳实践与安全优化建议

为什么需要清理未使用的刷新令牌？

在OAuth 2.0、OpenID Connect等现代身份认证体系中，刷新令牌（Refresh Token） 是用于长期维持用户会话的关键凭证，但与访问令牌（Access Token）不同，刷新令牌的有效期通常长达数天甚至数月，如果未及时清理已失效或长期未使用的令牌，会带来以下风险：

自动化脚本如何清理未使用刷新令牌

令牌泄露风险扩大：一个被遗忘的刷新令牌若被攻击者获取，可长期伪造用户身份访问API资源。
授权数据库膨胀：未清理的令牌记录会导致数据库存储压力上升，影响查询性能。
违反合规要求：如GDPR要求最小化数据保留，未清理的无效令牌可能被视为非必要数据留存。

自动化清理未使用刷新令牌 是保障认证系统安全性、降低运维成本的必要操作。

刷新令牌的核心机制与安全风险

1 令牌生命周期

刷新令牌通常包含以下属性：

唯一标识符（如UUID）
关联用户ID、客户端ID、权限范围（scope）
创建时间与过期时间（例如30天）
最新使用时间（last_used_at）

当客户端通过刷新令牌换取新访问令牌时,服务器会更新last_used_at字段。未使用的刷新令牌 指那些在指定时间窗口内（如过去7天、30天）从未被用于刷新操作的令牌。

2 典型风险场景

退出登录但令牌未销毁：用户点击“退出所有设备”后，部分旧令牌可能仍在数据库存活。
恶意客户端滥用：攻击者可通过已泄露的刷新令牌长期保持会话，绕过密码变更等安全机制。
令牌泄漏后未撤销：若日志检测到异常刷新行为，但残留的未使用令牌可能为后续攻击提供入口。

自动化清理脚本的技术方案

1 核心设计原则

识别标准：基于last_used_at与过期时间的组合逻辑。
- 已过期（当前时间 > 过期时间）的令牌直接删除。
- 未过期但在最近N天内从未使用的令牌标记为“僵尸令牌”并清除。
安全批量操作：采用分批删除（BATCH DELETE）防止锁表，并记录日志以供审计。
可恢复性：清理前备份数据，或在软删除（设置revoked_at）后再硬删除。

2 技术方案对比

方案类型	语言/工具	适用场景	优点	缺点
SQL脚本	SQL (如PostgreSQL)	小型系统、单数据库环境	简单高效，无需额外依赖	无法处理复杂业务逻辑
脚本语言+ORM	Python + SQLAlchemy	中等规模Web应用	灵活性强，可集成日志与通知	需配置运行环境
定时任务框架	Celery / Sidekiq	分布式系统，需并发清理	支持调度与重试机制	需要额外的消息队列组件
动态数据清理工具	databasin/Octopass	多数据库、跨平台统一管理	可视化界面，适合非技术人员	成本较高

3 关键代码片段示例（Python + FastAPI + SQLAlchemy）

from datetime import datetime, timedelta
from sqlalchemy.orm import Session
from models import RefreshToken
def clean_orphan_refresh_tokens(db: Session, inactive_days: int = 30):
    """清理超过inactive_days未使用的刷新令牌"""
    cutoff_date = datetime.utcnow() - timedelta(days=inactive_days)
    # 查询条件：过期或超过阈值未使用
    tokens_to_delete = db.query(RefreshToken).filter(
        (RefreshToken.expires_at < datetime.utcnow()) |
        (RefreshToken.last_used_at < cutoff_date)
    ).all()
    total = len(tokens_to_delete)
    # 分批删除（每批100条）
    for i in range(0, total, 100):
        batch = tokens_to_delete[i:i+100]
        for token in batch:
            db.delete(token)
        db.commit()
    print(f"Cleaned {total} refresh tokens.")
    return total
# 定时调度（每分钟运行一次）
from apscheduler.schedulers.asyncio import AsyncIOScheduler
scheduler = AsyncIOScheduler()
scheduler.add_job(clean_orphan_refresh_tokens, 'interval', minutes=60, args=(db_session,))
scheduler.start()

提示：若使用 asyncpg 或 aiomysql 异步连接，可进一步提升高并发环境下的清理效率。

主流工具的配置案例与实现步骤

1 案例A：基于数据库定时任务（PostgreSQL + pg_cron）

-- 安装pg_cron扩展（需超级权限）
CREATE EXTENSION IF NOT EXISTS pg_cron;
-- 创建清理函数
CREATE OR REPLACE FUNCTION clean_expired_refresh_tokens()
RETURNS void AS $$
BEGIN
    DELETE FROM refresh_tokens
    WHERE expires_at < NOW() 
       OR last_used_at < NOW() - INTERVAL '30 days';
END;
$$ LANGUAGE plpgsql;
-- 设定每周日凌晨3点执行
SELECT cron.schedule('clean_refresh_tokens', '0 3 * * 0', 'SELECT clean_expired_refresh_tokens();');

优点：零代码侵入，直接数据库操作。
缺点：无法触发外部通知（如Slack告警），且不适用于NoSQL。

2 案例B：使用Redis的TTL与定期清理（Node.js + ioredis）

若刷新令牌存储在Redis（以哈希结构存储），可利用Redis内置的EXPIRE和SCAN命令：

const Redis = require('ioredis');
const redis = new Redis();
async function cleanRedisRefreshTokens() {
    let cursor = '0';
    let total = 0;
    do {
        const result = await redis.scan(cursor, 'MATCH', 'refresh:*', 'COUNT', 100);
        cursor = result[0];
        const keys = result[1];
        for (const key of keys) {
            const tokenData = await redis.hgetall(key);
            const lastUsed = parseInt(tokenData.last_used_at) || 0;
            const now = Date.now();
            // 设定30天内未使用则删除
            if (now - lastUsed > 30 * 24 * 60 * 60 * 1000) {
                await redis.del(key);
                total++;
            }
        }
    } while (cursor !== '0');
    console.log(`Cleaned ${total} unused refresh tokens from Redis.`);
    // 可调用外部API发送清理报告
}

优势：无需额外维护过期时间片，利用Redis原子操作。
注意：务必使用SCAN而非KEYS，避免阻塞主线程。

3 案例C：云平台托管方案（AWS Elasticache + Lambda定时器）

在Lambda中用Python脚本连接Elasticache（Redis），执行类似上文的清理逻辑。
使用EventBridge规则设定每日UTC 2:00触发。
清理日志输出到CloudWatch,并设置告警阈值（如单次清理超过1000条）。

常见问题与问答（FAQ）

Q1：清理未使用的刷新令牌，应该删除还是作废（设置`revoked_at`）？

A：建议“先作废，后删除”。

先设置revoked_at = NOW()并保留24小时，若出现误删，可以手动恢复。
24小时后执行硬删除,通过定时任务移除revoked_at IS NOT NULL的记录，此策略尤其适用于生产环境以避免事故。

Q2：如何区分“僵尸令牌”与“尚未使用的合法令牌”？

对于新注册但未活跃的用户,可设置宽限期，例如创建后7天内自动豁免。
在令牌记录中添加is_initial字段，首次登录后自动标记；未标记且超过创建时间24小时的可视为异常并清理。

Q3：清理后影响正常用户吗？

不会，只要严格按照基于last_used_at的“N天未使用”阈值执行，注意：如果用户使用“记住我”功能，每次刷新令牌时服务器都应更新last_used_at，如果你发现用户因清理被踢出，请检查是否需要延长inactive_days参数，或在业务逻辑中增加“距离过期前的最后一次刷新”判断。

Q4：数据库有上亿条令牌记录，如何防止删除时的锁表？

使用分批删除（如每批500条），并在间隙执行COMMIT。
利用数据库的分区表功能，按月或按用户ID哈希将令牌分区，只清理旧分区。
尝试在业务低峰期运行（如凌晨3点），并设置事务超时时间。

最佳实践与安全优化建议

建立令牌生命周期：
所有令牌生成时即设置last_used_at = created_at，并在每次刷新时更新，避免NULL值干扰清理逻辑。
双重触发机制：
- 定时任务（每晚执行一次全面清理）。
- 实时触发器（在用户注销或密码变更时，立即作废该用户关联的所有令牌）。
审计与监控：
- 记录每次清理的令牌ID、用户ID、清理时间，存入独立审计表。
- 设置Prometheus指标（如cleanup_deleted_count），当单次删除量超过峰值时触发告警。
渐进式清理策略：
初次清理时先设定较宽松的阈值（如180天），观察对业务影响后逐步缩小到30天，切勿直接“一刀切”删除所有早期令牌。
与OAuth2.0服务商协调：
如果使用Auth0、Okta等外部提供程序，它们可能自带“令牌清理”功能，可调用其管理API同步清理本地缓存。