JupyterHub RBAC 升级实战指南：从 OAuth/API Token 双轨制迁移到基于 Scope 的权限框架-平芜编程栈

后端
微服务

【免费下载链接】jupyterhub

Multi-user server for Jupyter notebooks

项目地址：https://gitcode.com/gh_mirrors/ju/jupyterhub

JupyterHub 2.0 引入的 RBAC（Role Based Access Control）框架改变了权限体系的底层数据模型：它消除了 OAuth Token 与 API Token 的区分，要求把原先分属两张数据库表的令牌合并为一张，因此升级过程与以往任何版本都不同——所有已存在的令牌会被 Hub 在数据库升级期间删除并重建，而手动签发或持久化存储的令牌则必须由管理员在升级后重新签发。本文以 docs/source/rbac/upgrade.md 为主线，结合仓库中的 Alembic 迁移脚本与角色实现源码，完整讲解升级前的准备、逐步操作、升级后权限调整的推荐流程，以及 OAuth/API Token 在新旧体系下的本质区别，帮助部署者安全、无遗漏地完成这次迁移。

升级背景：RBAC 为什么需要完全不同的数据库设置

RBAC 框架与 JupyterHub 所有历史版本的关键差异在于：它不再区分 OAuth Token 和 API Token（详见下文"OAuth vs API tokens"一节）。由于令牌的两种形态被统一，原先分别存储它们的两张数据库表必须合并成一张：

旧版中，OAuth Token 用于识别登录用户（存储在浏览器 cookie 中）；
旧版中，API Token 用于服务与 Hub API 之间的通信；
新版中，API Token 承担一切动作，包括登录与认证，OAuth Token 被彻底移除。

这一结构性变更的直接后果是：所有在升级前创建的令牌都不再符合新数据库结构，必须全部替换。仓库中的迁移脚本印证了这一点——jupyterhub/alembic/versions/833da8570507_rbac.py 在upgrade()中直接执行：

op.drop_table('api_tokens') op.drop_table('oauth_access_tokens')

脚本注释对此作出了明确说明（"FIXME, maybe: currently drops all api tokens and forces recreation!"）：

这能保证数据库的一致性，但要求：1. 升级前必须停止所有服务器；2. 任何手动签发/存储的令牌都必须重新签发。通过配置文件加载的令牌会在启动时自动重建，不受影响。

也就是说，升级的令牌处理策略是"先全删、再按需重建"，而不是逐行迁移。后续的迁移脚本 jupyterhub/alembic/versions/651f5419b74d_api_token_scopes.py 再为重建后的api_tokens表补充scopes列、为oauth_clients表补充allowed_scopes列，把旧的"角色关联"（api_token_role_map、oauth_client_role_map）折算为具体的 scope 集合，从而完成权限模型的数据落地。

升级影响范围

被删除：数据库中全部已有令牌（包括 OAuth Token 与 API Token）。
自动重建：通过jupyterhub_config.py配置文件加载的令牌，会以更新后的结构在 Hub 启动时自动创建。
需要手动处理：任何通过 API、UI 或脚本手动签发、以及被持久化存储在其他系统中的令牌，不会被自动重建，必须手动重新签发。
不受影响：除令牌外，其他所有数据库记录（用户、组、服务、服务器信息等）均不受影响。

升级前的充分准备

RBAC 升级属于"破坏性"迁移，动手之前应当完成以下准备工作（详细流程见 docs/source/howto/upgrading.md）：

通知用户：默认配置下由 JupyterHub 托管configurable-http-proxy时，升级期间用户将经历服务中断，应选择影响最小的时段并提前告知。
备份数据库：备份 JupyterHub 数据库（默认是 SQLite，即jupyterhub.sqlite文件；若使用 MySQL/Postgres 则备份相应数据库）。
备份配置：备份jupyterhub_config.py文件。
备份用户数据：用户主目录虽一般不受升级直接影响，但属于关键数据，建议一并备份。
盘点手动令牌：列出所有通过 API（/hub/token或POST /users/:username/tokens）签发、以及通过jupyterhub_config.py之外的方式持久化存储的令牌清单，便于升级后逐一重新签发。

升级步骤（核心三步）

依据 docs/source/rbac/upgrade.md 的Upgrade steps一节，完整流程如下：

第 1 步：停止所有正在运行的服务器

所有正在运行的服务器（single-user server）必须在升级前停止。这不仅是为了避免迁移期间数据竞争，也是迁移脚本drop_table('api_tokens')的硬性前提——正在运行的服务器持有旧结构令牌，若不停止，其后续 API 调用将因表被删除而失败。

第 2 步：按标准流程升级 Hub

按 Upgrading JupyterHub 的标准步骤执行：

关闭 Hub 进程：使用进程管理器（systemd、supervisord、docker等）对应的命令停止 JupyterHub。
升级软件包：Hub 环境与 notebook 用户环境中安装的jupyterhub版本必须一致。pip 安装方式执行：
```
python3 -m pip install --upgrade jupyterhub==<version>
```
conda 安装方式执行：
```
conda install -c conda-forge jupyterhub==<version>
```
同时留意所用 Authenticator 与 Spawner 的新版本。
升级数据库：在jupyterhub_config.py所在目录执行：
```
jupyterhub upgrade-db
```
该命令会自动定位数据库并执行必要的 Alembic 迁移，即上文分析的两个迁移脚本所完成的工作：删除api_tokens与oauth_access_tokens表、重建令牌相关结构、为角色/scope 建立新的关联模型。
重启 JupyterHub：迁移完成后重新启动 Hub 进程。

⚠️重要建议：升级完成、Hub 首次重启后，暂时不要在jupyterhub_config.py中定义任何新角色。这样能保留 Hub 的"当前"状态（所有既有实体自动获得默认角色），之后任意一次后续启动中再定义和分配新角色都完全可行。

第 3 步：重新签发所有手动令牌

重启后，立即重新签发所有此前手动签发（即非通过jupyterhub_config.py加载）的令牌，包括：

用户通过 API 或/hub/token页面申请的个人 API Token；
以脚本或外部系统方式签发并持久化存储的令牌；
任何在升级前已写入其他服务（如 CI 系统、监控脚本）的令牌。

这些令牌在升级时已被数据库迁移删除，不重新签发将导致对应集成失效。

升级后首次启动会发生什么

当 JupyterHub 在升级后第一次重启时，所有存储在数据库中、或通过配置文件重新加载的用户、服务与令牌，都会被分配其默认角色：

用户 → 默认user角色（拥有self元作用域，可访问与操作自身资源）；
管理员用户 → 额外获得admin角色（包含全部可用 scope，且该角色不可被编辑）；
令牌 → 默认token角色（inherit元作用域，解析为与令牌持有者相同的权限）；
服务 → 默认无角色（没有角色则无法访问受保护的 API 端点）；
组 → 默认无角色（组内用户自动继承组的权限）。

这一逻辑直接对应 jupyterhub/roles.py 中的assign_default_roles()：

def assign_default_roles(db, entity): if isinstance(entity, orm.Group): return kind = type(entity).__name__ if entity.admin: grant_role(db, entity=entity, rolename="admin") else: admin_role = orm.Role.find(db, 'admin') if admin_role in entity.roles: strip_role(db, entity=entity, rolename="admin") if kind == "User": grant_role(db, entity=entity, rolename="user")

四个默认角色的完整 scope 定义见同一文件中的get_default_roles()（jupyterhub/roles.py）。在此之后新建的实体，只有在没有请求其他特定角色时，才会被赋予默认角色；一旦通过配置或 API 指定了特定角色，则以指定为准。

升级后如何开始调整权限

完成上述升级步骤后，RBAC 框架即可投入使用。你可以定义新角色、修改默认角色（admin除外）并将其分配给实体，详细方法见 docs/source/rbac/roles.md 中"Defining Roles"一节的说明。

官方推荐的 RBAC 起步流程如下：

识别目标：确定哪些管理员用户与服务，你希望仅授予其实际所需的最小权限。
剥离 admin 状态：通过 API 或 UI 移除这些用户/服务的 admin 状态，其角色将从admin降为user。
注意：从实体上移除角色目前只能通过jupyterhub_config.py完成（重新定义角色时不列出该实体即可使其脱离该角色，参见 docs/source/rbac/roles.md 中关于移除角色的说明）。
定义新角色：在jupyterhub_config.py中用合适的 scope 定义新角色，并分配给这些实体。
重启生效：重启 JupyterHub 使新角色生效。

一个典型的角色定义示例（load_roles以字典列表形式配置）：

# in jupyterhub_config.py c.JupyterHub.load_roles = [ { 'name': 'server-rights', 'description': 'Allows parties to start and stop user servers', 'scopes': ['servers'], 'users': ['alice', 'bob'], 'services': ['idle-culler'], 'groups': ['admin-group'], } ]

角色名必须满足：长度 3–255 字符、仅含小写 ASCII 字母/数字及 URL 保留字符-_.~、以字母开头、以字母或数字结尾（校验逻辑见 jupyterhub/roles.py 中的_role_name_pattern与_validate_role_name）。users、services、groups字段只能引用数据库中已存在、或文件中先前已定义的实体——不能通过定义角色隐式创建新用户。若新角色未定义任何 scope，JupyterHub 会给出警告；提供不存在的 scope 则会直接报错。若同名角色已存在于数据库，其定义与 scopes 将被覆盖（admin角色除外，试图覆盖会抛出RoleValueError）。

更完整的实战场景（如 idle-culler 服务、API 启动器、按组授权的教师角色等）可参考 docs/source/rbac/use-cases.md。

理解关键前提：OAuth vs API tokens

要正确执行本次升级，必须理解新旧两套令牌模型的差异。以下是 docs/source/rbac/upgrade.md 中"OAuth vs API tokens"一节的完整阐释。

RBAC 之前：双轨制令牌

旧版 JupyterHub 使用两种令牌：

OAuth Token: 用户登录时由 Hub 签发给 single-user server。存储在浏览器 cookie 中，用于在 OAuth 流程中标识拥有该服务器的用户。默认情况下，cookie 到期（默认 2 周；JupyterHub 1.3.0 之前为 1 小时）时该令牌随之过期。

API Token: Hub 在启动 single-user server 时签发，用于服务器与 Hub API 通信，例如上报活动（activity）或完成 OAuth 流程。默认永不过期。

此外，API Token 还可以通过以下途径签发给用户与服务：

API 接口/hub/token（令牌页面）；
POST /users/:username/tokens（REST API）；
服务通过jupyterhub_config.py配置获得，用于执行 API 请求。

RBAC 之后：统一令牌

RBAC 框架通过附加在角色上的 scope授予令牌不同级别的权限。单独的 OAuth Token 所承担的"仅用于身份识别"这一用途不再需要——API Token 可以用于所有动作，包括登录与认证，此时使用一个不带角色（即不含任何可用 scope）的 API Token 即可。

因此，OAuth Token 在升级到 RBAC 框架的 Hub 中被正式移除。这也是升级过程中oauth_access_tokens表被直接删除、相关 cookie 需要重新登录的根本原因：升级后所有用户都需要重新登录一次，以在新体系下获得基于 API Token 的新会话。

迁移的源码级验证与注意事项

为便于读者在仓库中核对，这里汇总本次升级相关的实现证据：

删除旧令牌表：jupyterhub/alembic/versions/833da8570507_rbac.py（RBAC 基础迁移，JupyterHub 2.0 引入）直接drop_table('api_tokens')与drop_table('oauth_access_tokens')，并注释说明了"停止服务器、重新签发手动令牌"两大前提。其downgrade()同样不可逆地删除api_tokens及相关角色映射表，升级前务必做好数据库备份。
重建令牌与 scope 结构：jupyterhub/alembic/versions/651f5419b74d_api_token_scopes.py 为api_tokens增加scopes列、为oauth_clients增加allowed_scopes列，并把旧的角色关系（api_token_role_map、oauth_client_role_map）折算为 scope 集合；oauth_codes为短生命周期数据，直接新增scopes列即可，无需逐条迁移。
默认角色分配：jupyterhub/roles.py 的assign_default_roles()与 jupyterhub/roles.py 的get_default_roles()共同决定了升级后首次启动时各实体的默认角色行为。
scope 体系：scope 的语法约定（read:、list:、admin:、access:、<resource>:<subresource>、!user=等水平/垂直过滤）与全部可用 scope 层级见 docs/source/rbac/scopes.md；token 请求与 API 请求时的权限解析流程见 docs/source/rbac/tech-implementation.md。

给部署者的三点提醒

备份优先：由于downgrade()同样是破坏性的（直接删除令牌表），回滚也意味着令牌全部失效，务必在升级前保留完整数据库备份。
令牌清单化：升级前把"配置文件令牌"与"手动令牌"分开清单管理。前者会自动重建、无需干预；后者必须人工重发，遗漏会导致外部集成（CI、监控、自动脚本）静默失效。
分批启用 RBAC：首次重启后保持配置不变，确认 Hub 状态正常、所有实体获得默认角色后，再在后续启动中逐步定义新角色并剥离不必要的 admin 权限，以最小化风险。

至此，你的 JupyterHub 已升级至 RBAC 框架：令牌体系统一、权限粒度可控、实体（用户/服务/组）均可通过角色获得精确的 scope 集合，为"最小权限原则"下的精细化治理打下了基础。