企业官网建设流程全解析

Open edX 用户退出的特殊场景处理：从 ERRORED 恢复、状态重跑与撤销退出请求

【免费下载链接】openedx-platformThe Open edX LMS & Studio, powering education sites around the world!项目地址: https://gitcode.com/GitHub_Trending/ed/openedx-platform

本篇指南基于 Open edX 用户退出（user retirement）流水线中的特殊场景处理文档，讲解运维人员面对退出流水线三类典型异常时的处理方法：如何从ERRORED错误态恢复单个用户的退出流程、如何借助幂等设计重跑全部或部分退出状态，以及如何通过 Django 管理命令撤销仍处于PENDING状态的退出请求。读完后你将能够独立诊断退出流水线卡点，并安全地执行状态重置、批量重跑与退出撤销操作。

退出流程状态机：理解特殊场景处理的前提

要处理任何特殊场景，先要理解退出流水线驱动脚本（retirement driver）背后的状态机模型。每个用户的退出进度由UserRetirementStatus记录跟踪（对应数据库表user_api_userretirementstatus），其current_state字段在退出流水线各阶段之间流转。从 驱动脚本 可以看到，脚本定义了四个具有特殊含义的"魔术状态"：

# scripts/user_retirement/retire_one_learner.py # "Magic" states with special meaning, these are required to be in LMS START_STATE = 'PENDING' ERROR_STATE = 'ERRORED' COMPLETE_STATE = 'COMPLETE' ABORTED_STATE = 'ABORTED' END_STATES = (ERROR_STATE, ABORTED_STATE, COMPLETE_STATE)

状态流转主线为：PENDING→RETIRING_ENROLLMENTS→ENROLLMENTS_COMPLETE→RETIRING_FORUMS→FORUMS_COMPLETE→ … →COMPLETE。每个"进行中"状态（如RETIRING_FORUMS）失败时都可能跌入ERRORED这一终态；PENDING则可直接转入ABORTED。ERRORED、COMPLETE、ABORTED三者共同构成终态（terminal states）。

驱动脚本的工作方式（以 retire_one_learner.py 为典型）是：读取学习者当前的current_state，在配置的retirement_pipeline状态序列中定位其索引，从该位置继续向后执行尚未完成的阶段。正是这种"从当前状态续跑"的设计，决定了下面所有特殊场景的操作方式——只要手动把状态回拨到正确位置，下一次执行驱动脚本时流程就会自动从这里恢复。

退出流水线各阶段（论坛、邮件列表、课程注册、LMS、License Manager、电商、凭证等）在 YAML 配置中以状态对形式声明，例如：

retirement_pipeline: - ['RETIRING_LICENSE_MANAGER', 'LICENSE_MANAGER_COMPLETE', 'LICENSE_MANAGER', 'retire_learner'] - ['RETIRING_FORUMS', 'FORUMS_COMPLETE', 'LMS', 'retirement_retire_forum'] - ['RETIRING_EMAIL_LISTS', 'EMAIL_LISTS_COMPLETE', 'LMS', 'retirement_retire_mailings'] - ['RETIRING_ENROLLMENTS', 'ENROLLMENTS_COMPLETE', 'LMS', 'retirement_unenroll'] - ['RETIRING_LMS', 'LMS_COMPLETE', 'LMS', 'retirement_lms_retire']

从 ERRORED 状态恢复

触发条件：退出 API 返回失败即置为 ERRORED

当某个退出 API 返回 4xx 或 5xx 状态码时，驱动脚本会立即将该用户的状态置为ERRORED。这不是可自动重试的中间态，而是需要人工介入的终态：驱动脚本后续执行时会跳过处于END_STATES中的用户，不会自行恢复。

第一步：通过 responses 字段定位故障原因

排查入口是用户退出状态记录中的responses字段。在user_api_userretirementstatus表（User Retirement Status）中找到该用户对应的行，responses字段中保存了流水线各阶段对退出 API 的应答日志，可用于确认是哪个阶段、哪次 API 调用返回了什么错误。

第二步：在 Django Admin 中回拨状态到"应重试状态的前一状态"

问题解决后，需要手动把该用户的current_state设置为应重试状态的前一个状态。文档给出的示例：某用户的退出流程在论坛（forums）退出阶段出错，即从RETIRING_FORUMS跌入ERRORED。此时应将状态从ERRORED手动回拨为ENROLLMENTS_COMPLETE——即RETIRING_FORUMS的直接前驱状态：

PENDING -> RETIRING_ENROLLMENTS -> ENROLLMENTS_COMPLETE -> RETIRING_FORUMS | v ERRORED | (via django admin，手动回拨) v ENROLLMENTS_COMPLETE

回拨完成后，下一次执行退出驱动脚本时，该用户的退出流程会自动从ENROLLMENTS_COMPLETE之后（即RETIRING_FORUMS）恢复执行，无需其他干预。这一自动续跑行为正是由驱动脚本"定位当前状态索引并从其后继续"的实现逻辑保证的。

重跑部分或全部退出状态

适用场景

以下两种情况需要把已完成的用户批量重置回PENDING从头重跑：

1. 流水线在全部用户退出完成之后新增了阶段（但退出队列尚未清理），需要让所有已退出用户补跑新阶段；
2. 某个阶段/退出 API 当时有缺陷但仍返回成功，导致流水线把所有用户错误地推到了COMPLETE，修复后需要重新验证全部用户。

操作方式

将所有current_state == COMPLETE的退出记录，把current_state设置为PENDING。

这一步之所以安全，关键在于退出 API 被设计为幂等（idempotent）：对于某个用户已经执行过的阶段，重跑时这些 API 调用应当是无副作用的空操作（no-op）。因此批量回拨到PENDING不会造成重复注销、重复删除数据等问题，只会让尚未真正完成的阶段重新执行。

重跑的驱动方式

重置完成后，可通过 get_learners_to_retire.py 获取待处理用户列表，再由 retire_one_learner.py 逐用户驱动状态机推进；脚本入口别名参见 entry_points.sh。运行环境搭建（uv 虚拟环境、YAML 配置文件格式）详见 user_retirement 目录 README。

撤销退出请求（Cancelling a Retirement）

适用场景

用户刚提交账户注销（账户删除）申请、退出状态仍停留在PENDING时，可能通过邮件等方式联系管理员，要求撤回注销申请。edx-platform 为此提供了专门的 Django 管理命令，供管理员手动撤销退出：该命令会恢复指定用户的登录能力，并将其从所有退出队列中移除。

命令语法：

$ ./manage.py lms --settings=<your-settings> cancel_user_retirement_request <email-of-user-to-cancel-retirement>

命令实现与硬性约束

该命令实现在 cancel_user_retirement_request.py，从源码可以看到两条关键约束：

1. 只接受 PENDING 状态。命令按original_email查找UserRetirementStatus记录；若查不到则抛出CommandError: No retirement request with email address '...' exists.。若找到但current_state.state_name != 'PENDING'，则直接报错：

   # openedx/core/djangoapps/user_api/management/commands/cancel_user_retirement_request.py if retirement_status.current_state.state_name != 'PENDING': raise CommandError( "Retirement requests can only be cancelled for users in the PENDING state." " Current request state for '{}': {}".format(...) )

   也就是说，该命令只能撤销"尚未开始执行"的退出——一旦退出状态已越过PENDING（数据开始被删除），撤回请求就无法通过此命令完成，需要走数据恢复流程。命令文档字符串也明确写着："The command can't cancel a retirement that has already commenced - only pending retirements."

2. 用户需要重置密码才能恢复访问。撤销成功后，用户须自行重置密码以重新获得账户访问权限。

撤销动作的核心逻辑封装在handle_retirement_cancellation工具函数中（见 utils.py），负责恢复登录能力并清理退出队列；命令的行为验证见对应测试 test_cancel_retirement.py。

操作要点小结

三类操作共同依赖退出流水线的两个设计特性：驱动脚本按当前状态续跑的断点恢复语义，以及退出 API 的幂等性。理解这两点之后，上述文档中的每个手动干预步骤——回拨状态、批量重置、撤销请求——都能安全、可预期地落地。

延伸阅读

• 特殊场景处理原始文档：special_cases.rst
• 用户退出脚本总览与运行环境搭建：README
• 单用户退出驱动脚本：retire_one_learner.py
• 待退出用户批量获取：get_learners_to_retire.py
• 退出数据归档与清理：retirement_archive_and_cleanup.py
• 撤销命令测试：test_cancel_retirement.py

【免费下载链接】openedx-platformThe Open edX LMS & Studio, powering education sites around the world!项目地址: https://gitcode.com/GitHub_Trending/ed/openedx-platform