Struct SaTokenManager 

pub struct SaTokenManager {
    pub config: Arc<SaTokenConfig>,
    /* private fields */
}

sa-token 管理器：对外 API 门面，业务逻辑委托给 service / repository 层。

The sa-token manager: a thin facade delegating to the service and repository layers.

Fields

config: Arc<SaTokenConfig>

对外兼容：manager.config.token_name 经 Deref 仍可用。 Public field kept for compatibility; Arc derefs to SaTokenConfig. 构建期只包装一次，Clone Manager 只加引用计数，不再深拷贝配置。 Wrapped once at construction; cloning the manager is a refcount bump.

Implementations

impl SaTokenManager

pub async fn disable_level_with_type( &self, login_type: &str, login_id: &str, service: &str, level: i32, time: i64, ) -> Result<(), SaTokenError>

Disable at a level for a login type | 按登录类型分级禁用

pub async fn disable_with_type( &self, login_type: &str, login_id: &str, time: i64, ) -> Result<(), SaTokenError>

Disable for a login type | 按登录类型禁用

pub async fn get_disable_level_with_type( &self, login_type: &str, login_id: &str, service: &str, ) -> Result<i32, SaTokenError>

Read disable level for a login type | 按登录类型读取禁用等级

pub async fn is_disable_level_with_type( &self, login_type: &str, login_id: &str, service: &str, level: i32, ) -> Result<bool, SaTokenError>

Whether disabled at/above level | 是否达到指定禁用等级

pub async fn check_disable_level_with_type( &self, login_type: &str, login_id: &str, service: &str, level: i32, ) -> Result<(), SaTokenError>

Fail if disabled at/above level | 达到禁用等级则报错

pub async fn check_disable_services_with_type( &self, login_type: &str, login_id: &str, services: &[&str], level: i32, ) -> Result<(), SaTokenError>

Fail if any listed service is disabled | 任一服务被禁用则报错

pub async fn untie_disable_with_type( &self, login_type: &str, login_id: &str, service: &str, ) -> Result<(), SaTokenError>

Clear disable for a login type | 按登录类型解除禁用

pub async fn disable_level( &self, login_id: &str, service: &str, level: i32, time: i64, ) -> Result<(), SaTokenError>

Disable at a level (default login type) | 分级禁用（默认登录类型）

pub async fn disable( &self, login_id: &str, time: i64, ) -> Result<(), SaTokenError>

Disable account/service | 禁用账号或服务

pub async fn get_disable_level( &self, login_id: &str, service: &str, ) -> Result<i32, SaTokenError>

Read disable level | 读取禁用等级

pub async fn is_disable_level( &self, login_id: &str, service: &str, level: i32, ) -> Result<bool, SaTokenError>

Whether disabled at/above level | 是否达到指定禁用等级

pub async fn check_disable_level( &self, login_id: &str, service: &str, level: i32, ) -> Result<(), SaTokenError>

Fail if disabled at/above level | 达到禁用等级则报错

pub async fn check_disable_services( &self, login_id: &str, services: &[&str], level: i32, ) -> Result<(), SaTokenError>

Fail if any listed service is disabled | 任一服务被禁用则报错

pub async fn untie_disable( &self, login_id: &str, service: &str, ) -> Result<(), SaTokenError>

Clear disable flag | 解除禁用

impl SaTokenManager

pub async fn open_safe( &self, token: &TokenValue, service: &str, safe_time: i64, ) -> Result<(), SaTokenError>

为指定 token 开启二级认证

pub async fn is_safe( &self, token: &TokenValue, service: &str, ) -> Result<bool, SaTokenError>

判断 token 是否已通过指定业务的二级认证

pub async fn check_safe( &self, token: &TokenValue, service: &str, ) -> Result<(), SaTokenError>

校验二级认证；未通过抛出 SaTokenError::NotSafe

pub async fn close_safe( &self, token: &TokenValue, service: &str, ) -> Result<(), SaTokenError>

关闭二级认证

pub async fn get_safe_time( &self, token: &TokenValue, service: &str, ) -> Result<Option<i64>, SaTokenError>

获取二级认证剩余有效时间（秒）；未认证返回 None

impl SaTokenManager

pub async fn get_token_session( &self, token: &TokenValue, ) -> Result<SaSession, SaTokenError>

获取 Token-Session（不存在时按配置决定是否落盘创建）

pub async fn get_anon_token_session( &self, token: &TokenValue, ) -> Result<SaSession, SaTokenError>

匿名 Token-Session：跳过登录校验，且从不自动落盘

pub async fn save_token_session( &self, token: &TokenValue, session: &SaSession, ) -> Result<(), SaTokenError>

保存 Token-Session（TTL 与 token 生命周期对齐）

pub async fn delete_token_session( &self, token: &TokenValue, ) -> Result<(), SaTokenError>

删除 Token-Session

impl SaTokenManager

pub fn new(storage: Arc<dyn SaStorage>, config: SaTokenConfig) -> SaTokenManager

创建管理器实例。

配置只包装一次进 Arc，此后各层共享，Clone Manager 不再深拷贝配置。 Config is wrapped once into Arc; cloning the manager no longer deep-copies it.

pub fn with_key_layout(self, layout: SaKeyLayout) -> SaTokenManager

运行时替换存储键布局（主要用于测试与迁移工具）

pub fn with_serializer(self, serializer: SharedSerializer) -> SaTokenManager

替换序列化器（如启用 fory）。

显式复用原 event_bus，避免丢弃已注册的监听器。

pub fn with_stp_interface(self, iface: Arc<dyn StpInterface>) -> SaTokenManager

注册权限/角色数据源 | Register the permission/role data source

pub fn with_permission_matcher( self, matcher: Arc<dyn PermissionMatcher>, ) -> SaTokenManager

Replace the permission matcher used by AuthzService. 替换 AuthzService 使用的权限匹配器。

pub fn with_role_matcher( self, matcher: Arc<dyn PermissionMatcher>, ) -> SaTokenManager

替换角色匹配策略（默认按 config.role_wildcard 选择精确/分段匹配）。 Replaces the role matching strategy (default follows config.role_wildcard).

pub fn with_online_manager(self, manager: Arc<OnlineManager>) -> SaTokenManager

注册在线用户管理器 | Register the online user manager

pub fn with_distributed_manager( self, manager: Arc<DistributedSessionManager>, ) -> SaTokenManager

注册分布式 Session 管理器 | Register the distributed session manager

pub fn with_distributed_online(self) -> SaTokenManager

Attach a Dao-backed online manager (cross-instance presence). 挂上基于 Dao 的在线管理器（跨实例 presence）。

pub fn start_background_cleanup( &self, config: CleanupConfig, ) -> BackgroundCleanupTask

Start optional background cleanup (disabled unless CleanupConfig.enabled). 启动可选后台清理（除非 CleanupConfig.enabled 否则不跑）。

pub fn with_event_bus(self, event_bus: SaTokenEventBus) -> SaTokenManager

注入共享事件总线（支持多 Manager 共享 / 测试 mock）

Injects a shared event bus (supports multi-Manager sharing / test mocking).

示例 | Example

let shared_bus = SaTokenEventBus::with_config(EventBusConfig {
    dispatch_mode: DispatchMode::Detached,
    listener_timeout: Some(Duration::from_secs(10)),
});
let mgr1 = SaTokenManager::new(storage1, config1).with_event_bus(shared_bus.clone());
let mgr2 = SaTokenManager::new(storage2, config2).with_event_bus(shared_bus.clone());
shared_bus.register(Arc::new(MyListener));

pub fn keys(&self) -> &SaKeys

存储键构造器（A3 契约：返回引用，避免热路径克隆）

pub fn storage(&self) -> &Arc<dyn SaStorage>

底层存储 | Underlying storage

pub fn dao(&self) -> &Arc<SaTokenDao>

存储访问层 | Storage access layer

pub fn serializer(&self) -> &SharedSerializer

当前序列化器 | Current serializer

pub fn auth_service(&self) -> &Arc<AuthService>

认证服务 | Authentication service

pub fn token_repo(&self) -> &Arc<TokenRepo>

Token 仓储 | Token repository

pub fn session_repo(&self) -> &Arc<SessionRepo>

Session 仓储 | Session repository

pub fn authz_service(&self) -> &Arc<AuthzService>

授权服务：权限/角色的读写与校验入口 | Authorization service

pub fn grant_repo(&self) -> &Arc<GrantRepo>

👎Deprecated since 0.2.0:

Use SaTokenManager::authz_service() so cache invalidation and StpInterface precedence are honoured

授权仓储（纯存储，绕过数据源优先级与缓存失效）。 请改用 authz_service()。

The storage-only grant repository, bypassing data-source precedence and cache invalidation. Use authz_service() instead.

pub fn event_bus(&self) -> &SaTokenEventBus

事件总线 | Event bus

pub fn online_manager(&self) -> Option<&Arc<OnlineManager>>

在线用户管理器 | Online user manager

pub fn distributed_manager(&self) -> Option<&Arc<DistributedSessionManager>>

分布式 Session 管理器 | Distributed session manager

pub async fn login( &self, login_id: impl Into<String>, ) -> Result<TokenValue, SaTokenError>

登录：为指定账号创建 token | Log in and issue a token

pub async fn login_with_options( &self, login_id: impl Into<String>, login_type: Option<String>, device: Option<String>, extra_data: Option<Value>, nonce: Option<String>, expire_time: Option<DateTime<Utc>>, ) -> Result<TokenValue, SaTokenError>

登录（完整可选参数）。签名保持不变以维持对外兼容， 内部转换为 LoginRequest 后委托 AuthService。

pub async fn login_with_token_info( &self, token_info: TokenInfo, ) -> Result<TokenValue, SaTokenError>

登录：使用完整 TokenInfo（SSO / 自定义 token 场景）。

pub async fn logout(&self, token: &TokenValue) -> Result<(), SaTokenError>

登出指定 token | Log out a token

pub async fn kick_out_by_token( &self, token: &TokenValue, ) -> Result<(), SaTokenError>

踢下线指定 token（标记 -5）| Kick out a token, marker -5

pub async fn replaced_by_token( &self, token: &TokenValue, ) -> Result<(), SaTokenError>

顶下线指定 token（标记 -4）| Replace a token, marker -4

pub async fn logout_by_login_id( &self, login_type: &str, login_id: &str, ) -> Result<(), SaTokenError>

按账号登出全部 token | Log out every token of an account

pub async fn kick_out( &self, login_type: &str, login_id: &str, ) -> Result<(), SaTokenError>

按账号踢下线全部 token | Kick out every token of an account

pub async fn get_token_info( &self, token: &TokenValue, ) -> Result<TokenInfo, SaTokenError>

读取并校验 token | Read and validate a token

pub async fn get_token_by_login_id( &self, login_type: &str, login_id: &str, ) -> Result<TokenValue, SaTokenError>

按 login_type + login_id 读取当前映射 token Read the mapped token for login_type + login_id

pub async fn get_all_tokens_by_login_id( &self, login_type: &str, login_id: &str, ) -> Result<Vec<TokenValue>, SaTokenError>

列出在线 token（B1 list 原语） List online tokens (B1 list primitive)

pub async fn update_extra_data( &self, token: &TokenValue, extra_data: Value, ) -> Result<(), SaTokenError>

更新 extra_data 并经 TokenRepo 落盘 Update extra_data and persist via TokenRepo

pub async fn update_active_timeout( &self, token: &TokenValue, seconds: i64, ) -> Result<(), SaTokenError>

Set per-token idle timeout. Errors unless dynamic_active_timeout is on. 设置单 token 闲置超时。未开启 dynamic_active_timeout 时返回 ConfigError。

pub fn stp_logic(&self, login_type: &str) -> SaLogic

创建绑定 login_type 的廉价 Clone 门面 Create a cheap Clone facade bound to login_type

pub async fn is_valid(&self, token: &TokenValue) -> bool

token 是否有效 | Whether the token is valid

pub async fn renew_timeout( &self, token: &TokenValue, timeout_seconds: i64, ) -> Result<(), SaTokenError>

续期 token 到指定秒数 | Renew a token to an explicit lifetime

pub async fn get_session( &self, login_id: &str, ) -> Result<SaSession, SaTokenError>

读取账号 Session（默认 login_type）

pub async fn get_session_with_type( &self, login_type: &str, login_id: &str, ) -> Result<SaSession, SaTokenError>

读取账号 Session（指定 login_type，A3 契约）

pub async fn save_session( &self, session: &SaSession, ) -> Result<(), SaTokenError>

保存账号 Session（修 B1-9：以 session.id 自身作为命名空间回写）

pub async fn save_session_with_type( &self, login_type: &str, login_id: &str, session: &SaSession, ) -> Result<(), SaTokenError>

保存账号 Session（指定 login_type）

pub async fn delete_session(&self, login_id: &str) -> Result<(), SaTokenError>

删除账号 Session（默认 login_type）

pub async fn delete_session_with_type( &self, login_type: &str, login_id: &str, ) -> Result<(), SaTokenError>

删除账号 Session（指定 login_type）

pub async fn get_terminal_list( &self, login_type: &str, login_id: &str, device_type: Option<&str>, ) -> Result<Vec<SaTerminalInfo>, SaTokenError>

获取指定账号的终端列表 | Terminal list of an account

pub async fn get_token_value_list_by_login_id( &self, login_type: &str, login_id: &str, device_type: Option<&str>, ) -> Result<Vec<String>, SaTokenError>

获取指定账号的 token 列表（来自终端列表）

pub async fn get_terminal_info_by_token( &self, token: &TokenValue, ) -> Result<Option<SaTerminalInfo>, SaTokenError>

按 token 反查终端信息 | Look up terminal info by token

pub async fn get_permissions_with_type( &self, login_type: &str, login_id: &str, ) -> Result<Vec<String>, SaTokenError>

获取权限列表（指定账号体系）| Permission list for a login type

pub async fn set_permissions_with_type( &self, login_type: &str, login_id: &str, permissions: Vec<String>, ) -> Result<(), SaTokenError>

覆盖权限列表（指定账号体系）| Overwrite the permission list for a login type

pub async fn add_permission_with_type( &self, login_type: &str, login_id: &str, permission: String, ) -> Result<(), SaTokenError>

追加单个权限（指定账号体系，B2-35 新增） Append one permission for a login type (added in B2-35).

pub async fn remove_permission_with_type( &self, login_type: &str, login_id: &str, permission: &str, ) -> Result<(), SaTokenError>

移除单个权限（指定账号体系，B2-35 新增） Remove one permission for a login type (added in B2-35).

pub async fn clear_permissions_with_type( &self, login_type: &str, login_id: &str, ) -> Result<(), SaTokenError>

清空权限（指定账号体系，B2-35 新增） Clear permissions for a login type (added in B2-35).

pub async fn get_roles_with_type( &self, login_type: &str, login_id: &str, ) -> Result<Vec<String>, SaTokenError>

获取角色列表（指定账号体系）| Role list for a login type

pub async fn set_roles_with_type( &self, login_type: &str, login_id: &str, roles: Vec<String>, ) -> Result<(), SaTokenError>

覆盖角色列表（指定账号体系）| Overwrite the role list for a login type

pub async fn add_role_with_type( &self, login_type: &str, login_id: &str, role: String, ) -> Result<(), SaTokenError>

追加单个角色（指定账号体系，B2-35 新增） Append one role for a login type (added in B2-35).

pub async fn remove_role_with_type( &self, login_type: &str, login_id: &str, role: &str, ) -> Result<(), SaTokenError>

移除单个角色（指定账号体系，B2-35 新增） Remove one role for a login type (added in B2-35).

pub async fn clear_roles_with_type( &self, login_type: &str, login_id: &str, ) -> Result<(), SaTokenError>

清空角色（指定账号体系，B2-35 新增） Clear roles for a login type (added in B2-35).

pub async fn get_permissions( &self, login_id: &str, ) -> Result<Vec<String>, SaTokenError>

获取权限列表 | Permission list

pub async fn set_permissions( &self, login_id: &str, permissions: Vec<String>, ) -> Result<(), SaTokenError>

覆盖权限列表 | Overwrite the permission list

pub async fn add_permission( &self, login_id: &str, permission: String, ) -> Result<(), SaTokenError>

追加单个权限 | Append one permission

pub async fn remove_permission( &self, login_id: &str, permission: &str, ) -> Result<(), SaTokenError>

移除单个权限 | Remove one permission

pub async fn clear_permissions( &self, login_id: &str, ) -> Result<(), SaTokenError>

清空权限 | Clear all permissions

pub async fn get_roles( &self, login_id: &str, ) -> Result<Vec<String>, SaTokenError>

获取角色列表 | Role list

pub async fn set_roles( &self, login_id: &str, roles: Vec<String>, ) -> Result<(), SaTokenError>

覆盖角色列表 | Overwrite the role list

pub async fn add_role( &self, login_id: &str, role: String, ) -> Result<(), SaTokenError>

追加单个角色 | Append one role

pub async fn remove_role( &self, login_id: &str, role: &str, ) -> Result<(), SaTokenError>

移除单个角色 | Remove one role

pub async fn clear_roles(&self, login_id: &str) -> Result<(), SaTokenError>

清空角色 | Clear all roles

Trait Implementations

impl Clone for SaTokenManager

fn clone(&self) -> SaTokenManager

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SaTokenManager

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.