logto/tunnel CLI 使用指南本地调试与云端部署 Logto 自定义登录界面【免费下载链接】logto‍ Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logtologto/tunnel是 Logto 官方提供的一款命令行工具CLI它通过在本机与 Logto Cloud 之间建立一条隧道tunnel服务打通Logto 云认证服务 — 你的应用 — 你的自定义登录 UI三方链路让开发者无需将自定义 Sign-in Experience 页面部署上线就能在本地实时调试登录流程同时它还提供deploy命令可将本地 UI 资产一键上传到 Logto Cloud 租户。本文以仓库中的 packages/tunnel/CHANGELOG.md 为主线结合该包的完整源码入口文件、tunnel 命令、deploy 命令系统讲解其安装、两种工作模式、环境变量、底层实现原理与版本演进帮助读者完整掌握这套自定义 UI 开发调试与部署工作流。一、工具定位为什么要用 TunnelLogto 的 Sign-in Experience 允许开发者完全替换内置登录页面但自定义页面在开发期面临一个现实问题登录请求必须打到真实的 Logto Cloud 租户端点而自定义 UI 又跑在本地开发服务器上二者难以在同一个源origin下协同会话 Cookie 与 Experience API 的交互也容易受阻。从 CHANGELOG 0.1.0 条目可以看到logto/tunnel的诞生正是为了解决这一痛点该命令将在以下三个实体之间建立隧道服务Logto 云认证服务Logto cloud auth services、你的应用your application、你的自定义登录 UIyour custom sign-in UI。它本质上是一个运行在本地、监听指定端口默认 9000的 HTTP 服务凡是发往 Logto 的请求如/oidc/auth、/api/interaction/submit、/consent由它代理到真实租户端点凡是访问自定义 UI 的请求则由它代理到你本地开发服务器或静态文件目录。这样你的应用只需把 Logto endpoint 配置指向http://localhost:9000/就能在保持完整会话语义的前提下使用自定义登录页。二、安装与版本要求与 Logto 其他包一样logto/tunnel以 npm 包形式发布包名为logto/tunnel并提供全局可用的二进制命令logto-tunnelnpm i logto/tunnel -g从 package.json 可确认二进制入口bin: { logto-tunnel: bin/index.js }全局安装后直接使用logto-tunnel命令运行时要求engines: { node: ^22.14.0 }这与 CHANGELOG 中 0.3.0 的bump node version to ^22.14.0对应Node.js 版本需不低于 22.14.0依赖栈基于yargs命令行解析、http-proxy-middlewareHTTP 代理、dotenvfind-up环境变量加载、adm-zipzip 打包、ora进度提示、mimeMIME 类型推断等实现。当前仓库快照对应版本为0.3.11。另外在 monorepo 中你也可以在packages/tunnel目录下执行pnpm build node .对应start:dev脚本从源码运行 CLI。三、本地调试模式logto-tunnel命令3.1 场景一自定义 UI 运行在本地开发服务器假设你的自定义登录页跑在http://localhost:4000则执行logto-tunnel --endpoint https://tenant-id.logto.app --port 9000 --experience-uri http://localhost:40003.2 场景二自定义 UI 是纯静态文件如果你的 UI 没有独立开发服务器而是一份静态资源目录改用--experience-pathlogto-tunnel --endpoint https://tenant-id.logto.app --port 9000 --experience-path /path/to/your/custom/ui3.3 场景三启用了自定义域名Custom Domain隧道命令同样兼容自定义域名场景只需把 endpoint 换成你的自定义域名logto-tunnel --endpoint https://your-custom-domain.com --port 9000 --experience-path /path/to/your/custom/ui3.4 完整参数表从 tunnel 命令源码与 类型定义可以整理出全部参数参数别名类型默认值说明--experience-uri--uristring无自定义登录页开发服务器的 URI如http://localhost:4000--experience-path--pathstring无自定义登录页静态资源在本地的目录路径--endpoint无string无Logto 实例端点如https://tenant-id.logto.app/必填且必须是合法 URL--port-pnumber9000隧道服务监听端口--verbose无booleanfalse打印详细输出含每个请求/响应的原始内容参数校验逻辑见checkExperienceInpututils.ts--experience-uri与--experience-path二选一同时提供会直接报错终止两者都未提供同样报错终止--experience-uri必须是合法 URL--experience-path指定的目录下必须存在index.html。3.5 启动后的验证方式启动成功后CLI 会输出如下提示源码见 tunnel/index.ts自定义 UI 被托管在http://localhost:9000/记得把应用里的 Logto endpoint URI 从https://tenant-id.logto.app改为http://localhost:9000/若使用社交登录social sign-in回调地址也要相应设置为http://localhost:9000/callback/connector-id按CtrlC停止服务--verbose可打印详细日志。之后运行你的应用点击登录按钮就会跳转到自定义登录页同时携带有效会话Cookie可继续与 Logto 的 Experience API 交互。若端口被占用EADDRINUSE服务会自动尝试port 1继续启动见 index.ts。四、隧道服务工作原理源码级解析4.1 请求路由规则隧道服务收到请求后按以下顺序分流index.tsLogto 请求若请求路径以/oidc/或/api/开头或路径恰为/consent见isLogtoRequestPathutils.ts则代理到 Logto 端点开发服务器请求若配置了--experience-uri其余请求全部代理到该 URI静态文件请求若配置了--experience-path其余请求由静态文件代理处理。例如/oidc/.well-known/openid-configuration、/oidc/auth、/api/interaction/submit、/consent都属于 Logto 请求会透传到真实租户。4.2 响应内容改写URL 重写三板斧隧道服务的巧妙之处在于它不仅要转发请求还要把 Logto 响应中指向真实端点的 URL 改写成隧道地址否则浏览器里的跳转、表单提交都会绕过隧道。createLogtoResponseHandlerutils.ts按响应类型处理三种情况重定向响应改写响应头location中的 Logto endpoint 为隧道地址JSON 响应体遍历 JSON 顶层键凡键名为redirectTo或以_endpoint结尾且值为字符串的执行同样的 URL 替换HTML 响应体替换form的action属性前缀。同时源码注释特别强调/oidc/.well-known响应中的issuer与jwks_uri不应被改写以保证 OIDC 发现协议语义正确。4.3 静态文件托管SPA 回退与缓存策略createStaticFileProxyutils.ts实现了一套完整的静态站点服务逻辑只处理GET/HEAD请求对非文件资产路径无扩展名的路由自动回退到index.htmlSPA 路由支持回退响应使用no-cache, no-store, must-revalidate缓存头对真正的静态资产使用max-age604_800_0007 天的强缓存并通过mime库推断content-type支持 Range 请求见下文。4.4 视频背景与 Range 请求支持0.2.1CHANGELOG 0.2.1 专门记录了一个 Safari 兼容性修复Safari 浏览器通过 Range 请求拉取视频数据但此前logto/tunnel不支持该特性导致想用视频做登录页背景的用户无法正常播放。修复方案是根据range请求头部分读取视频文件流并设置正确的响应头与状态码206。对应实现readFileutils.ts支持按字节区间读取文件setRangeHeaders设置Accept-Ranges: bytes与Content-Range命中 Range 请求时返回206 Partial Content不可满足的区间返回416。这一能力直接服务于视频背景自定义登录页这类真实需求。4.5 安全加固路径穿越防护与压缩协商两个值得关注的补丁0.3.9prevent static file requests from reading files outside the configured experience path。对应getSafeStaticFilePathutils.ts对 URL 先做解码、拒绝含反斜杠的路径、再用path.resolvepath.relative校验解析结果必须落在静态根目录内否则返回 404防止..目录穿越读取任意文件0.2.6disallow zstd compression to fix potential garbled text response。对应createProxy中把转发请求的Accept-Encoding固定为gzip, deflate, brutils.ts因为http-proxy-middleware暂不支持zstd压缩禁用以避免乱码。五、云端部署模式deploy命令0.2.0 起本地调试完成后需要把自定义 UI 正式发布到 Logto Cloud 租户。0.2.0 新增的deploy命令专门承担这一职责。5.1 前置条件在 Logto 租户中创建一个机器对机器Machine-to-Machine, M2M应用并授予 Management API 权限拿到该应用的app-id:app-secret凭证用于 OIDCclient_credentials流程换取访问令牌。5.2 使用方式一上传目录npx logto/tunnel deploy --auth your-m2m-app-id:your-m2m-app-secret --endpoint https://tenant-id.logto.app --management-api-resource https://tenant-id.logto.app/api --experience-path /path/to/your/custom/ui5.3 使用方式二上传现成 zip也可以直接指定一个已打包好的 zip 文件npx logto/tunnel deploy --auth your-m2m-app-id:your-m2m-app-secret --endpoint https://tenant-id.logto.app --zip-path /path/to/your/custom/ui.zip注意事项沿用 CHANGELOG 原文要点使用默认 Logto 域名时--management-api-resource或--resource可以省略CLI 会自动推断若 Logto 端点使用了自定义域名则必须显式提供该参数--experience-path与--zip-path二选一不能同时使用。5.4 deploy 参数表从 deploy 命令源码整理参数别名类型说明--auth无stringM2M 应用凭证格式app-id:app-secret必填--endpoint无stringLogto 实例端点必填且须为合法 URL--path--experience-pathstring自定义 UI 本地目录路径--zip--zip-pathstring现成 zip 包路径--resource--management-api-resourcestringManagement API resource indicator自定义域名场景必填--verbose无boolean详细输出默认 false5.5 部署前置校验checkExperienceAndZipPathInputsdeploy/utils.ts保证输入合法--zip-path与--experience-path二选一两者都未提供时报错zip 文件必须存在且根目录下必须包含index.htmlzip 内条目层级不超过 2 层且末段为index.html目录方式下experience-path/index.html必须存在。5.6 部署流程四步流水线deployToLogtoClouddeploy/utils.ts把整个部署拆成 4 步--verbose模式下会逐步输出进度准备 zip目录方式下用adm-zip将本地目录打包自动过滤以.开头的隐藏文件/目录zip 方式则直接读取文件换取访问令牌向endpoint/oidc/token发起client_credentials授权请求Authorization: Basic base64(auth)resource取自显式参数或自动推断scope: all拿到access_token上传 UI 资产以multipart/form-data方式向/api/sign-in-exp/default/custom-ui-assetsPOST 上传 zip返回customUiAssetId保存到租户用PATCH /api/sign-in-exp将customUiAssets: { id, createdAt }写入租户的 Sign-in Experience 配置。resource 自动推断规则getManagementApiResourceFromEndpointUrideploy/utils.ts从 endpoint 域名中取第一段作为 tenant id拼出https://tenant-id.logto.app/api该 resource 域名在所有环境固定为logto.app。这也解释了为什么自定义域名下必须手动传--resource——此时域名无法再按租户 id规则拆分。部署成功后CLI 会提示你的应用应继续把 Logto endpoint URI 指向真实端点如https://tenant-id.logto.app/社交登录回调地址为endpoint/callback/connector-id。六、环境变量支持0.2.0 起deploy与 tunnel 的所有关键参数都可以通过环境变量提供便于 CI/CD 场景使用。CLI 在启动时通过dotenvfind-upindex.ts自动查找并加载.env文件——查找范围为CLI 所在目录及其所有父目录同时 yargs 配置了.env(LOGTO)前缀映射环境变量会作为同名参数的兜底值。支持的变量清单含简写见 CHANGELOG 0.2.0完整变量名简写别名对应 CLI 参数LOGTO_AUTH—--authLOGTO_ENDPOINT—--endpointLOGTO_EXPERIENCE_PATHLOGTO_PATH--experience-pathLOGTO_EXPERIENCE_URILOGTO_URI--experience-uriLOGTO_MANAGEMENT_API_RESOURCELOGTO_RESOURCE--management-api-resourceLOGTO_ZIP_PATHLOGTO_ZIP--zip-path两种使用姿势CHANGELOG 原文在 CLI 所在目录或其任意父目录创建.env文件写入变量或直接在命令行内联指定LOGTO_ENDPOINThttps://tenant-id.logto.app npx logto/tunnel ...以.env为例一份典型的部署配置可写成LOGTO_AUTHyour-m2m-app-id:your-m2m-app-secret LOGTO_ENDPOINThttps://tenant-id.logto.app LOGTO_EXPERIENCE_PATH/path/to/your/custom/ui这样部署命令可简化为npx logto/tunnel deploy。七、版本演进速览结合 CHANGELOG 与源码logto/tunnel的核心演进脉络如下版本类型关键变更0.1.0Minor新增logto-tunnel本地隧道命令支持--endpoint/--port/--experience-uri/--experience-path打通 Logto 云、应用与自定义 UI 三方链路0.2.0Minor新增deploy命令支持目录与 zip 两种输入新增全套LOGTO_*环境变量支持0.2.1Patch支持 Range 请求解决 Safari 下 mp4 视频背景无法播放的问题206 状态码0.2.6Patch禁用 zstd 压缩修复可能的响应乱码0.3.0MinorNode 运行时要求提升至^22.14.00.3.9Patch静态文件服务防目录穿越禁止读取配置的 experience 路径之外的文件0.3.11Patch依赖同步升级logto/core-kit2.13.0、logto/shared3.4.3其余版本0.2.2–0.2.5、0.3.1–0.3.8、0.3.10以依赖更新为主其中 0.2.5 与 0.3.2 还包含针对依赖项的安全更新security update。八、小结logto/tunnel用两个命令覆盖了自定义登录 UI 的全生命周期开发期用logto-tunnel在本地建立隧道让自定义页面无缝接入真实租户的认证流程自动处理 URL 改写、SPA 回退、Range 视频流、路径穿越防护等细节上线期用deploy完成打包 → 换 token → 上传资产 → 写入租户配置的一键发布。配合环境变量与--resource推断规则它既能服务交互式开发也能嵌入 CI 流水线。想深入阅读实现细节可依次查看CLI 入口与环境变量加载packages/tunnel/src/index.ts隧道命令参数与启动逻辑packages/tunnel/src/commands/tunnel/index.ts代理、静态文件、URL 改写与安全校验packages/tunnel/src/commands/tunnel/utils.tsdeploy 命令参数与部署流水线packages/tunnel/src/commands/deploy/index.ts、packages/tunnel/src/commands/deploy/utils.ts包元数据与脚本packages/tunnel/package.json【免费下载链接】logto‍ Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考