如何使用 authentik Flow Inspector 查看流程上下文并排查流程执行问题-育师

如何使用 authentik Flow Inspector 查看流程上下文并排查流程执行问题

【免费下载链接】authentikThe authentication glue you need.项目地址: https://gitcode.com/GitHub_Trending/au/authentik

当你在 authentik 中配置了自定义 Flow 后，可能会遇到这些问题：某个 Stage 没有被执行、Stage 绑定上的策略没有通过、或者流程重启后丢失了状态。authentik 的 Flow Inspector 就是针对这种情况的排查工具：它让你手动执行一个 Flow，在每一步推进时查看当前计划执行的 Stage、已执行的 Stage 历史，以及当前 flow context 中的具体数据（例如 identification 阶段之后出现的pending_user）。适用前提是你在 Admin 界面拥有目标 Flow 的访问权限，并且已满足下文所述的权限条件。

权限准备：确认可以打开 Inspector

Inspector 只对拥有Can inspect a Flow's execution权限的用户开放，该权限可以直接授予用户，也可以通过角色授予；Superuser 则始终可以检查 Flow 的执行。

推荐的做法是授予这个权限，而不是使用 debug 模式。如果你正在开发 authentik 并启用了 debug 模式，Inspector 会默认启用，未认证用户和普通用户也能访问，但文档明确指出 debug 模式只应用于开发场景。

授权或查看权限的操作路径可参考 Manage permissions：

在 Admin 界面进入Directory > Roles，选中角色后在Permissions页签下通过Assigned global permissions授予全局权限；
查看某个 Flow 上已分配的权限：进入Flows and Stages > Flows，点击 Flow 名称打开详情页，再查看Permissions页签，把鼠标悬停在任意勾选项上可以看到该权限来自全局权限还是对象权限。

权限概念详见 Permissions。

用 Inspector 手动执行一个 Flow

:::warning 打开 Inspector 运行 Flow 时，该 Flow 会被真实执行。例如其中的 User write 阶段确实会写入用户数据，在排查前请确认目标 Flow 不会产生你不想在测试中触发的副作用。 :::

主路径按以下步骤操作：

打开 Admin 界面，导航到Flows and Stages > Flows。
在列表中点击目标 Flow 的名称，进入 Flow 详情页。
在页面左侧Execute flow区域，点击Use inspector。
该 Flow 会在新浏览器标签页中启动，Flow Inspector 显示在流程界面的右侧，随流程推进同步更新。

两种替代入口，供有相应权限的用户按需使用：

在 Flow 的 URL 后追加查询参数?inspector，URL 打开后即可启动 Inspector；
有权限的用户在默认 flow executor 界面右上角可以看到一个按钮，点击即可打开 Inspector。

阅读 Inspector 的四类信息

Inspector 显示的内容来自当前活跃的 flow plan，分为四部分：

Next stage：当前计划执行的下一个 Stage，显示其名称、类型和唯一 ID。注意：如果 Stage 绑定策略配置为"运行时评估"，该 Stage 在被展示之前仍可能被跳过。
Plan history：概览哪些 Stage 已经执行、哪个当前处于活动状态、下一个计划执行的是哪个。用它对照 Flow 配置，可以快速定位流程"停在了哪里"。
Current plan context：当前 flow context 的内容。字段取决于活动 Stage，例如执行过 identification 阶段后可以看到pending_user被定义。这份数据不做清洗——如果流程涉及输入密码，密码也会在这里明文显示，查看和截图时注意保密。
Session ID：当前会话的唯一 ID，文档指明它可用于调试流程重启、丢失状态类的问题。

判断 Stage 为何被跳过：结合 Planner 规则

Flow Planner 文档指出，Flow Planner 负责为每个进入 Flow 的请求确定要执行的 Stage 及其顺序。排查"Stage 没执行"时，关键看该 Stage 绑定上的策略是在哪个时点被评估的：

Evaluate when flow is planned：策略在 flow plan 创建时评估，不通过则该 Stage 根本不会进入计划；
Evaluate when stage is run（默认）：策略在 Stage 即将展示前的瞬间评估，不通过则跳过该 Stage，继续执行下一个计划中的 Stage。

同一个 Stage 绑定可以两种都启用。文档给出的判断依据是：如果策略在任意 Stage 运行之前就能评估，用 planning-time；如果策略依赖前面 Stage 写入 flow context 的数据（例如pending_user），就必须用 run-time 评估。

具体排查时，用 Inspector 的Current plan context检查策略依赖的键（如pending_user）在评估时点是否已经存在，再对照Plan history看该 Stage 是"从未进入计划"还是"运行前被跳过"，即可区分上述两种失败模式。pending_user等保留键的完整定义见 Flow Context。

排查：Inspector 打不开或行为不符合预期

以下两种现象及文档给出的原因，与"流程执行排查"直接相关：

现象 1：Flow Inspector 无法启动，显示 "Bad request" 错误。文档给出的两个可能原因：

你选择的 Flow 上直接绑定了一个会阻止访问的策略（Flow 本身无法执行，Inspector 因此打不开）；
你没有对该 Flow 的 view permission。

对应检查：在 Flow 详情页确认绑定策略，并按上文方法查看自己是否具备该 Flow 的权限。

现象 2：修改了 Stage 绑定或策略后，Flow 行为没有变化。Planner 文档说明，活跃的 flow plan 存储在 HTTP session 中，已存在的会话可能已经带着旧计划在执行；浏览器端和 API 端的 flow executor 在流程运行期间必须持续使用同一个 session。因此文档给出的做法是：先启动一次新的 Flow 执行，再开始排查，不要在旧会话上验证新配置。

流程重启/状态丢失问题：使用 Inspector 显示的Session ID进行调试。