Openship API认证指南Session Cookie、Bearer Token与PAT的3种实战用法【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openshipOpenship API 认证是每一位自托管部署平台用户绕不开的功课。Openship 是一个功能强大的自托管部署平台Self-hosted deployment platform无论是浏览器里的管理面板、终端中的 CLI还是接入的 AI 助手每一次请求都要先回答一个问题你是谁本指南带你快速吃透 Openship 的三种核心认证方式——Session Cookie、Bearer Token 与 PAT个人访问令牌并附常见错误速查表看完即可上手。一、3种认证方式1张表看懂方式你要提供什么适用场景Session Cookie浏览器自动携带的 httpOnly Cookie管理面板Dashboard日常操作Bearer TokenAuthorization: Bearer opsh_pat_…请求头CLI、脚本、服务器间调用MCP OAuthAI 客户端自动获取的 OAuth 2.1 令牌Claude、Cursor 等 AI 助手一次请求只会走其中一条路径Openship 先检查 Bearer 令牌没有再看 Session Cookie两者都没有时才考虑桌面版的本地回环模式。二、Session Cookie浏览器登录一次30天无忧登录管理面板后Openship 会给你的浏览器发一个签名的 httpOnly Session Cookie之后每次请求都由浏览器自动携带你完全无感。几个值得了解的设计细节httpOnly 保护页面上的 JavaScript 读不到这个 Cookie即使恶意脚本混入页面也无法窃取你的会话30 天有效期且每小时自动续期日常使用基本不会掉线Cookie 带模式前缀自托管实例是openship.session_token云端模式则是openship-cloud.session_token两种模式同机部署也互不干扰安全开关自动适配只有在 HTTPS 下才会附加 Secure 属性本地 HTTP 实例不会出现登录后被弹回登录页的怪圈。相关实现可参考 apps/api/src/lib/session-cookie.ts 与 apps/api/src/lib/auth.ts。三、Bearer TokenCLI 与脚本的万能钥匙没有浏览器的环境服务器、CI、脚本就需要在请求头里显式携带令牌Authorization: Bearer opsh_pat_…这里有个新手常踩的安全坑浏览器来源的请求携带 Bearer 令牌会被直接拒绝401 BEARER_NOT_ALLOWED_FROM_BROWSER。这是刻意为之——从面板页面里发出 Bearer 令牌往往是凭证被盗取后回放的信号所以大门直接关上而 CLI 不发Origin头自然畅通无阻。令牌解析的统一入口见 apps/api/src/lib/bearer.ts完整鉴权流程见 apps/api/src/middleware/auth.ts。四、PAT 个人访问令牌如何创建、使用与回收PATPersonal Access Token是 Bearer Token 的标准形态格式固定为opsh_pat_加 43 位随机密钥256 位熵。两个关键安全特性要牢记⚠️明文只显示一次服务器只保存它的 SHA-256 哈希创建时看到的明文永远无法再次查看。丢了只能吊销重建令牌永远以创建者身份行动除非你主动收窄它的权限。1️⃣ 在面板中创建打开Settings → Personal Access Tokens填写名称并选择权限即可生成令牌并当场复制。2️⃣ 用 CLI 创建推荐脚本场景# 完整权限令牌必须显式声明 --full-access openship token create my-laptop --full-access # 只读 90天过期的 CI 令牌 openship token create ci-readonly --read-only --expires 90 --full-access # 只绑定单个项目的部署机器人令牌 openship token create deploy-bot --grant project:proj_123:read,write两种收窄手段按需选用手段效果典型用途--read-only拒绝一切写操作POST/PUT/PATCH/DELETE监控、看板、只读审计--grant限制到指定资源令牌变成受限主体部署机器人、受限代理3️⃣ 让 CLI 记住令牌openship login --token opsh_pat_xxxx --context prod openship context use prod # 多实例间一键切换配置保存在~/.openship/config.json权限 0600令牌只会以 Bearer 头发送绝不会被存成 Cookie。五、MCP OAuthAI 助手的专属通道如果你要接入 Claude、Cursor 这类支持 MCP 的 AI 客户端无需手动分发 PATOpenship 本身就是一座标准的OAuth 2.1 授权服务器。客户端首次调用POST /api/mcp时会拿到401指引随后自动完成注册与 PKCE 授权流程最后在你的浏览器里弹出同意页——在这里你可以勾选只读或指定可访问的项目/服务器范围。⚠️ 没有经过同意页的 OAuth 令牌默认拒绝一切访问不存在已认证但未授权的灰色地带。已连接的客户端可在Settings → MCP中查看并一键断开断开即吊销全部令牌。六、桌面版零认证模式本地回环的便利桌面应用运行在你自己的电脑上强制登录纯属多余因此启用零认证模式API 自动创建一个本地管理员把本机流量当作该用户处理。它只有同时满足三道闸门才生效仅限桌面应用、认证模式为none、且请求来自内核确认的127.0.0.1不信任可伪造的 Host 头。自建服务器实例默认走local模式缺会话就是普通的401。七、常见错误码速查表状态码含义怎么办401 INVALID_TOKEN令牌错误、过期或已吊销检查令牌内容必要时重建401 BEARER_NOT_ALLOWED_FROM_BROWSER浏览器来源携带了 Bearer 令牌从 CLI/服务器发送请求403 TOKEN_READ_ONLY只读令牌尝试了写操作用有写权限的令牌403 TOKEN_ORG_SCOPE令牌绑定的是另一个组织在令牌所属组织内使用503 AUTH_UNAVAILABLE会话校验本身故障如数据库异常稍后重试它绝不会悄悄降级为免认证八、安全最佳实践清单 ✅能收窄就收窄CI 用只读令牌机器人用单项目 scope别让令牌默认全权设过期时间--expires支持 1–365 天临时任务用短命令牌明文只显示一次生成后立即存入密码管理器或环境变量定期清理openship token list查看使用情况闲置令牌及时revoke改密即踢人密码重置会自动吊销全部会话旧会话立刻失效。 相关资料认证模型完整文档apps/web/content/docs/security/auth.mdxTokens API 参考apps/web/content/docs/api/tokens.mdxCLI 访问与令牌管理apps/web/content/docs/cli/access.mdxPAT 生成与哈希实现apps/api/src/lib/pat.ts认证中间件主流程apps/api/src/middleware/auth.ts掌握 Session Cookie、Bearer Token 与 PAT 这三把钥匙你就能从容驾驭 Openship 的整个 API 体系——浏览器里无感登录、终端里一键部署、AI 助手中安全协作各得其所。【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Openship API认证指南：Session Cookie、Bearer Token与PAT的3种实战用法
Openship API认证指南Session Cookie、Bearer Token与PAT的3种实战用法【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openshipOpenship API 认证是每一位自托管部署平台用户绕不开的功课。Openship 是一个功能强大的自托管部署平台Self-hosted deployment platform无论是浏览器里的管理面板、终端中的 CLI还是接入的 AI 助手每一次请求都要先回答一个问题你是谁本指南带你快速吃透 Openship 的三种核心认证方式——Session Cookie、Bearer Token 与 PAT个人访问令牌并附常见错误速查表看完即可上手。一、3种认证方式1张表看懂方式你要提供什么适用场景Session Cookie浏览器自动携带的 httpOnly Cookie管理面板Dashboard日常操作Bearer TokenAuthorization: Bearer opsh_pat_…请求头CLI、脚本、服务器间调用MCP OAuthAI 客户端自动获取的 OAuth 2.1 令牌Claude、Cursor 等 AI 助手一次请求只会走其中一条路径Openship 先检查 Bearer 令牌没有再看 Session Cookie两者都没有时才考虑桌面版的本地回环模式。二、Session Cookie浏览器登录一次30天无忧登录管理面板后Openship 会给你的浏览器发一个签名的 httpOnly Session Cookie之后每次请求都由浏览器自动携带你完全无感。几个值得了解的设计细节httpOnly 保护页面上的 JavaScript 读不到这个 Cookie即使恶意脚本混入页面也无法窃取你的会话30 天有效期且每小时自动续期日常使用基本不会掉线Cookie 带模式前缀自托管实例是openship.session_token云端模式则是openship-cloud.session_token两种模式同机部署也互不干扰安全开关自动适配只有在 HTTPS 下才会附加 Secure 属性本地 HTTP 实例不会出现登录后被弹回登录页的怪圈。相关实现可参考 apps/api/src/lib/session-cookie.ts 与 apps/api/src/lib/auth.ts。三、Bearer TokenCLI 与脚本的万能钥匙没有浏览器的环境服务器、CI、脚本就需要在请求头里显式携带令牌Authorization: Bearer opsh_pat_…这里有个新手常踩的安全坑浏览器来源的请求携带 Bearer 令牌会被直接拒绝401 BEARER_NOT_ALLOWED_FROM_BROWSER。这是刻意为之——从面板页面里发出 Bearer 令牌往往是凭证被盗取后回放的信号所以大门直接关上而 CLI 不发Origin头自然畅通无阻。令牌解析的统一入口见 apps/api/src/lib/bearer.ts完整鉴权流程见 apps/api/src/middleware/auth.ts。四、PAT 个人访问令牌如何创建、使用与回收PATPersonal Access Token是 Bearer Token 的标准形态格式固定为opsh_pat_加 43 位随机密钥256 位熵。两个关键安全特性要牢记⚠️明文只显示一次服务器只保存它的 SHA-256 哈希创建时看到的明文永远无法再次查看。丢了只能吊销重建令牌永远以创建者身份行动除非你主动收窄它的权限。1️⃣ 在面板中创建打开Settings → Personal Access Tokens填写名称并选择权限即可生成令牌并当场复制。2️⃣ 用 CLI 创建推荐脚本场景# 完整权限令牌必须显式声明 --full-access openship token create my-laptop --full-access # 只读 90天过期的 CI 令牌 openship token create ci-readonly --read-only --expires 90 --full-access # 只绑定单个项目的部署机器人令牌 openship token create deploy-bot --grant project:proj_123:read,write两种收窄手段按需选用手段效果典型用途--read-only拒绝一切写操作POST/PUT/PATCH/DELETE监控、看板、只读审计--grant限制到指定资源令牌变成受限主体部署机器人、受限代理3️⃣ 让 CLI 记住令牌openship login --token opsh_pat_xxxx --context prod openship context use prod # 多实例间一键切换配置保存在~/.openship/config.json权限 0600令牌只会以 Bearer 头发送绝不会被存成 Cookie。五、MCP OAuthAI 助手的专属通道如果你要接入 Claude、Cursor 这类支持 MCP 的 AI 客户端无需手动分发 PATOpenship 本身就是一座标准的OAuth 2.1 授权服务器。客户端首次调用POST /api/mcp时会拿到401指引随后自动完成注册与 PKCE 授权流程最后在你的浏览器里弹出同意页——在这里你可以勾选只读或指定可访问的项目/服务器范围。⚠️ 没有经过同意页的 OAuth 令牌默认拒绝一切访问不存在已认证但未授权的灰色地带。已连接的客户端可在Settings → MCP中查看并一键断开断开即吊销全部令牌。六、桌面版零认证模式本地回环的便利桌面应用运行在你自己的电脑上强制登录纯属多余因此启用零认证模式API 自动创建一个本地管理员把本机流量当作该用户处理。它只有同时满足三道闸门才生效仅限桌面应用、认证模式为none、且请求来自内核确认的127.0.0.1不信任可伪造的 Host 头。自建服务器实例默认走local模式缺会话就是普通的401。七、常见错误码速查表状态码含义怎么办401 INVALID_TOKEN令牌错误、过期或已吊销检查令牌内容必要时重建401 BEARER_NOT_ALLOWED_FROM_BROWSER浏览器来源携带了 Bearer 令牌从 CLI/服务器发送请求403 TOKEN_READ_ONLY只读令牌尝试了写操作用有写权限的令牌403 TOKEN_ORG_SCOPE令牌绑定的是另一个组织在令牌所属组织内使用503 AUTH_UNAVAILABLE会话校验本身故障如数据库异常稍后重试它绝不会悄悄降级为免认证八、安全最佳实践清单 ✅能收窄就收窄CI 用只读令牌机器人用单项目 scope别让令牌默认全权设过期时间--expires支持 1–365 天临时任务用短命令牌明文只显示一次生成后立即存入密码管理器或环境变量定期清理openship token list查看使用情况闲置令牌及时revoke改密即踢人密码重置会自动吊销全部会话旧会话立刻失效。 相关资料认证模型完整文档apps/web/content/docs/security/auth.mdxTokens API 参考apps/web/content/docs/api/tokens.mdxCLI 访问与令牌管理apps/web/content/docs/cli/access.mdxPAT 生成与哈希实现apps/api/src/lib/pat.ts认证中间件主流程apps/api/src/middleware/auth.ts掌握 Session Cookie、Bearer Token 与 PAT 这三把钥匙你就能从容驾驭 Openship 的整个 API 体系——浏览器里无感登录、终端里一键部署、AI 助手中安全协作各得其所。【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考