📦 Olares Settings (olares-cli settings) — Olares 设置（olares-cli settings）

设置（Olares 设置 UI 镜像） CRITICAL — 执行任何操作前，必须用 Read 工具读取 ../olares-shared/SKILL.md，获取 profile 选择、登录及 HTTP 401/403 恢复规则，所有命令均依赖这些规则。

本命令树 olares-cli settings … 是 Olares 桌面 SPA 设置页面的 CLI 镜像（文档见 https://docs.olares.com/manual/olares/settings/）。身份与传输均来自当前 profile —— 与 SPA 共用同一套 profile 模型、access token、edge-auth 链（Authelia + l4-bfl-proxy）。

根命令注册 13 个区域子树（见 cli/cmd/ctl/settings/root.go）： users appearance apps integration vpn network gpu video search backup restore advanced 外加第 13 个非规范树 me，承载 SPA 头像 / Person 下拉自助项；me 故意不在 12 个规范设置文档章节内，仅出于 CLI 可发现性置于 settings 下。

命令格式恒为 olares-cli settings 或当区域含多子资源时 settings 例：settings vpn devices list、settings backup plans list 所有动词继承全局 --profile 标志。

认证与传输

• 每个请求经 factory 注入的 http.Client 及 cmdutil.Factory 解析的 profile 发出，无 kubeconfig 依赖。
• Base URL 按区域拆分：

– 默认用 rp.DesktopURL – rp.SettingsURL 用于仅设置端点：vpn (/headscale/)、backup/restore (/apis/backup/v1/)

• 两套 nginx 配置共享 /api/（均转发至 user-service:3010），其余路径分流：

– Settings nginx 独占 /admin/（Infisical）、/drive、/vault、/images、/api/cloud/sign – Desktop nginx 独占 /api/device → settings-service、/api/logout → authelia-svc、/api/refresh → authelia-backend-svc 因此 me 区域的 SSO 列表（/api/device/sso）及任何读取 /api/device/ 的代码必须走 DesktopURL；移动后将静默切换后端。 同样，三个 whoami 别名（profile whoami、settings users me、settings me whoami）读取桌面入口缓存的身份。

• Auth 头：X-Authorization: （非 Authorization: Bearer …），由 factory 的 refreshingTransport 自动注入；access_token 过期时自动轮换。
• 服务器返回 401/403 时，transport 访问 /api/refresh，持久化新 token 并重试一次，对调用方透明。用户无需因 token 过期而重新 profile login，仅当 refresh_token 本身失效时才需重新登录。
• 并发、跨进程 flock、类型化错误 credential.ErrTokenInvalidated / credential.ErrNotLoggedIn 详见 SKILL.md「Automatic token refresh」。禁止在这些错误上再写重试循环，唯一恢复方式是 profile login / profile import。

入口前缀

• /api/（主体）→ user-service，反向代理 BFL / app-service / Headscale / terminusd / search3 / HAMI 等
• /apis/backup/v1/（backup/restore）→ 直连 BFL 的 backup-server

角色缓存 + 软预检 profile 本地缓存用户在 Olares 实例的角色（owner/admin/normal），使 CLI 可短路受控动词，无需往返。缓存字段：ProfileConfig.OwnerRole、WhoamiRefreshedAt（见 cli/pkg/cliconfig），通过以下途径更新：

• olares-cli profile login 成功 → 立即 whoami 获取，5 秒超时（见 cli/cmd/ctl/profile/