云原生后端运维【免费下载链接】TerminusOpen-Source Personal Cloud OS for Always-On Agents项目地址https://gitcode.com/gh_mirrors/terminus2/Terminus点击查看免费下载本篇技术指南以 Olares 开源仓库中olares-cli的认证参考文档 olares-auth.md 为骨架结合仓库内的命令实现与认证源码系统讲解 olares-cli 的 Profile 身份模型、密码/TOTP 登录、refresh token 导入、profile 状态判定、平台签发凭据、令牌存储后端与自动刷新机制。读完你将掌握如何为 Agent 或脚本正确配置 Olares 身份、如何读懂profile list的每一种状态并采取正确的恢复动作以及为什么在授权失败时重登一遍往往不是正确答案。Profile 模型一个身份、一对令牌、一个目标在 olares-cli 中一个 profile 等于一个 Olares 实例加上一个用户身份以olaresId如aliceolares.com作为唯一键。每个 profile 各自持有自己的 access token / refresh token 令牌对二者独立存储、互不串用。这一模型有两个关键推论当前选中的 profile 决定了所有profile-backed依赖身份的命令的目标实例与身份不存在每次调用单独指定的--profile覆盖参数。切换身份只能通过olares-cli profile use name显式完成这一约束在源码层有明确注释CredentialProvider.Resolve中identity is switched explicitly viaolares-cli profile use name见 provider.go。从源码结构看整个认证体系分三层cmd/ctl/profile负责命令面参数解析、交互提示pkg/auth负责协议面Authelia/api/firstfactor、/api/secondfactor/totp、/api/refresh三类接口调用pkg/credential负责编排面把配置文件 存储令牌解析成命令可用的完整凭据视图见 types.go。profile 命令树与常用标志profile是 olares-cli 根命令下的一个子命令树完整注册见 root.go。注意没有独立的auth login/auth logout命名空间登出就是profile remove。命令用途profile login用密码可选 TOTP认证profile 不存在时自动创建profile import用已有 refresh token 引导bootstrap出 access tokenprofile list列出所有 profile、本地认证状态与缓存的 Olares 后端版本profile use name\|-切换当前 profile-表示切回上一个类似cd -profile remove name删除 profile 及其存储的令牌profile whoami [--refresh]显示当前 profile 的身份与缓存角色即olares-cli settings users me的别名用olares-cli profile --help查看全部标志。login与import共享一组公共凭据标志定义见 credentials.go标志说明--olares-id idolaresId如aliceolares.com必填--name aliasprofile 别名默认取 olaresId--no-switch成功后不切换当前 profile脚本友好--auth-url-override url覆盖推导出的认证 URL开发/内部用--local-url-prefix prefix在认证子域名与 terminus 名之间插入的标签开发/内部用--insecure-skip-verify该 profile 下禁用 TLS 校验开发/内部用此外profile树还挂了两个持久标志--olares-version ver可覆盖检测到的 Olares 后端版本跳过/api/olares-info探测--refresh-version强制重新读取/api/olares-info——因为后端版本是每个 profile 自己的属性登录时急切缓存见 root.go。密码登录与 TOTP 二次认证最基本的登录olares-cli profile login --olares-id olaresId交互式登录会不回显地提示输入密码若账户开启了 2FA随后会提示输入 TOTP 验证码。对脚本化输入使用--password-stdin开启 2FA 时还要同时传入短时效的--totp code因为脚本路径下不会有第二次提示。登录的实现逻辑login.go先做一次探测登录请求固定携带NeedTwoFactortrue把targetURL指向desktop.name/让 Authelia 按 2FA 访问策略评估并如实回报fa2true若只发 vault 的targetURL2FA 账户会被静默降级为fa2false用户将永远等不到 TOTP 提示底层走 auth.Login先 POST/api/firstfactor密码按md5(passwordOlares2025)加盐见 login.go若服务端回报fa2再 POST/api/secondfactor/totp两次请求共用一个带 cookie jar 的http.Client让 first-factor 种下的 Authelia 会话 cookie 自动附着到 second-factor 请求上首次交互时若未带--totp且命中ErrTOTPRequired且 stdin 是 TTYCLI 会原地再提示一次6 位验证码并重试重发 first-factor不重输密码非 TTY 环境则直接报错re-run with --totp。安全红线不要把密码放进命令行参数。要让用户输入时启动交互式命令使其停在密码提示处把提示转发给用户进程退出后再读取结果除非用户明确要求绝不要代用户登录。TOTP 是短时效、不可复用的动态口令不是可长期保存的配置。严禁把它写进共享脚本、文件或任务记录里。导入已有 refresh token当 refresh token 是从别处取得如 LarePass、wizard 激活流程时用profile import引导出 access tokenolares-cli profile import \ --olares-id olaresId \ --refresh-token $OLARES_REFRESH_TOKEN实现上profile import通过 auth.Refresh 对/api/refresh发起恰好一次调用以用户提供的 refresh token 换取全新 Token随后与登录走完全相同的持久化路径见 import.go。refresh token 应来自环境变量或密钥管理服务绝不要以命令字面量形式粘贴也不要 echo 到终端。检查 profile 状态与身份profile list报告的是本地令牌库无需网络调用即可证明的状态因此它既是身份清单也是认证健康度仪表盘状态含义Agent 应执行的动作logged-inaccess token 本地可用或没有可解析的过期时间继续执行expiredaccess token 的过期时间已过去继续执行下一条命令通常会刷新它invalidated服务端拒绝了 refresh 授权停止执行profile login或profile importnever从未存储过令牌停止执行profile login或profile importpending平台签发的 profile 尚未兑换其授权继续执行下一条命令会完成兑换unknown/logged-in (unparseable token)令牌存储或 JWT 解析无法确定状态执行命令若类型化认证错误持续再重新登录状态判定逻辑在 list.go显式失效标记InvalidatedAt 0优先于 JWTexp检查服务端已拒绝 refresh 授权即使 access token 的 JWT 还有效整个授权也已死亡JWT 缺少exp声明时报logged-in客户端无法判定选择信任直到服务端拒绝。列表还包含三列附加信息VERSION列缓存的 Olares 后端版本未检测到时显示-profile list --refresh-version会重新读取/api/olares-info刷新当前 profile 的缓存见 list.go。行首*标记当前选中的 profile。SOURCE列仅当存在平台签发的 profile 时出现见 list.go取值local、platform或platform(app)。平台签发的 Profile应用容器内的身份当一个应用声明了permission.loginOlaresCLI权限时平台会向该应用的容器挂载一份凭据CLI 会把这份挂载自动转成 profile。profile list会在SOURCE列标记为platform(app)。这背后是一条完整的挂载链路平台侧app-service 的 cli-credential webhook写入credential.json包含refreshToken、olaresId、appName三字段结构见 managed_credential.goCLI 通过环境变量OLARES_CLI_CREDENTIALS_DIR指向只读挂载的 Secret与OLARES_CLI_CACHE_DIR指向可写的 emptyDir感知我是一个被托管的容器每次启动命令前ImportManagedCredential 会把挂载凭据与 config.json 对账并在首次导入时立即把挂载的 refresh token 兑换为 access token——否则profile list无法区分坏了与还没开始见 managed_import.go。这类 profile不是用户能自行管理的profile login、profile import、profile remove对平台签发的 profile一律拒绝RequireNotManaged守卫见 provider.go因为平台持有授权的唯一副本卸载该应用才是吊销它的方式平台签发 profile 的恢复手段是重装或修复那个应用而不是重新登录——登录行为会被拒且即使放行也无法从本地铸就平台授权。这也改变了没有配置 profile的含义在应用容器内它意味着挂载未能变成 profile挂载缺失、损坏、字段不全而不是没有人登录过。把这种情况上报为登录问题会把用户引向一个无法提供帮助的岔路。从源码看noProfileError的错误文案正是区分了这两种场景检测到托管凭据挂载存在时提示reinstall or repair the application否则才提示profile login见 provider.go。重新认证与旧版存储迁移profile login与profile import会就地替换过期、失效或不存在的凭据无需先删 profile。但有一条保护规则仍然有效的令牌不会被意外覆盖。若该 olaresId 已存在一个仍在有效期内的令牌CLI 会拒绝重复认证并提示先执行olares-cli profile remove id——只有在你有意替换该身份时才这样做。判定逻辑见 credentials.go显式失效的令牌总是放行用户应当能单条命令恢复只有 JWTexp仍在未来或无法解析时才拦截。旧版存储说明更早的构建把凭据以明文存在~/.olares-cli/tokens.json该存储已废弃当前实现为每个 olaresId 一条独立的密钥库条目见 token_store.go。如果升级后的安装显示未登录应重新认证而不是拷贝旧文件。令牌存储后端登录/导入成功后CLI 会报告令牌落在哪个后端。跨平台映射如下操作系统存储后端macOS系统钥匙串Keychainservice 为olares-cliaccount 为 olaresIdLinuxOlares CLI 数据目录下的 AES-256-GCM 加密文件Windows当前用户注册表 HKCU 下的 DPAPI 保护值各平台实现细节均加密存储来自 keychain 目录macOSkeychain_darwin.go主密钥存在系统钥匙串带 5 秒超时防挂死系统钥匙串被拒沙箱/CI时回退到与加密 blob 同目录、0600 权限的master.key.file形成 Linux 等价姿态Linuxkeychain_other.go每个 service 一份随机主密钥master.key令牌 blob 用 AES-256-GCM 加密目录权限 0700、文件权限 0600写入采用临时文件 rename 防撕裂存储目录可经$OLARES_CLI_DATA_DIR重定位Windowskeychain_windows.go注册表根Software\OlaresCli\keychain每个 account 值名用 URL-safe base64 编码规避 olaresId 中的/.密文用 DPAPICryptProtectData且以service\x00account作熵绑定密文拷到别的身份槽位也无法解密。后端会返回标签system-keychain/file-fallback/file/registrydpapi登录后提示形如token stored via ...见 credentials.go。其中file-fallback后端的安防属性与 OS 级钥匙串不同如 macOS 沙箱环境回退、或 Linux 容器内无法写 HOME 时落到os.TempDir()的兜底目录应按其实际安全等级对待。自动刷新令牌旋转与并发协调CLI 会透明地轮换过期的 access token可重放的请求在收到认证拒绝后会刷新并重试一次流式上传在令牌接近过期时会先刷新再发送数据块——因为已被消费的文件流无法安全重放必须提前换新令牌刷新协调覆盖同一进程内的多个 goroutine 与多个并发的 olares-cli 进程确保全局最多发起一次/api/refresh。实现上 Refresher 采用三层去重进程内互斥锁 加锁后重读令牌库的取后比较若存储值已与调用方观察值不同说明别人已刷新直接返回不动网络 跨进程的磁盘 flockolaresId.refresh.lock并且在拿到 flock 后还要再重读一次令牌库当/api/refresh返回 401/403/459 时令牌库被盖上InvalidatedAt时间戳MarkInvalidated后续命令跳过网络往返直接提示登录459 是 Olares 特有的auth failed边缘状态码Authelia ext-authz 经 l4-bfl-proxy 的透传与 SPA 端459 → TOKE_INVILID的映射保持一致见 refresh.go。因此Agent 与脚本不要自己写认证重试循环因为 CLI 已把刷新做进每次请求Agent 不要叠加自己的认证重试循环。正确的做法是凭据缺失、被失效或持续收到 401/459 时跟随 CLI 显式的 login/import 动作去恢复而不是重试业务命令403 权限拒绝不是登录能修复的——那是当前身份对资源/动作没有权限http_auth_error.go 对 403 专门建议用olares-cli profile whoami --refresh核查身份权限而不是提示登录网络错误、5xx 同样不是登录信号。Agent 实操决策清单把上文压缩成可执行的判定流程执行olares-cli profile list看状态本地可判定无需网络。logged-in/expired/pending→ 直接继续执行CLI 会在下一条请求中完成刷新。never/invalidated→ 停止执行profile login或profile import除非SOURCE显示platform(app)——那是平台发给应用的凭据本地无法铸就或吊销恢复方式是重装/修复该应用。应用容器内无 profile → 说的是挂载失败答案同样是修复应用而不是请登录。unknown/ 不可解析的令牌 → 直接跑业务命令按其类型化错误回应不要凭空猜测。持续 401/459 且 CLI 打印登录动作 → 跟随该动作403 与 5xx 不是登录信号永远不要构建认证重试循环。这六条与 skill 层的认证就绪门槛见 SKILL.md以及结构化错误码约定-o json下的auth_no_profile、auth_not_logged_in、auth_token_expired、auth_token_invalidated、timeout见 SKILL.md保持一致是 Agent 在 Olares 上安全操作的身份基座。赞分享云原生后端运维【免费下载链接】TerminusOpen-Source Personal Cloud OS for Always-On Agents项目地址https://gitcode.com/gh_mirrors/terminus2/Terminus点击查看免费下载相关推荐bulletproof-react身份认证JWT令牌管理与刷新机制bulletproof react身份认证JWT令牌管理与刷新机制 引言现代React应用的身份认证挑战 在当今的前端开发中身份认证是构建生产级应用的核心示例工程前端Feathers 认证客户端feathersjs/authentication-client完整指南登录、令牌存储与自动重认证Feathers 认证客户端feathersjs/authentication client完整指南登录、令牌存储与自动重认证 导读 feathers后端Web框架Librespot设备认证令牌管理安全存储与刷新机制Librespot设备认证令牌管理安全存储与刷新机制 在音乐流媒体应用开发中设备认证令牌Token的安全管理直接关系到用户账户安全和服务可用性。Libr音频处理上一篇终极指南如何用LinkSwift全平台网盘直链下载工具告别限速烦恼下一篇深入解析 Relay 的 Inconsistent __typename 错误全局唯一 ID 约束、根因排查与服务端修复方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考