企业官网建设流程全解析

Openship API认证指南：Session Cookie、Bearer Token与PAT的3种实战用法

【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship

Openship API 认证是每一位自托管部署平台用户绕不开的功课。Openship 是一个功能强大的自托管部署平台（Self-hosted deployment platform），无论是浏览器里的管理面板、终端中的 CLI，还是接入的 AI 助手，每一次请求都要先回答一个问题：你是谁？本指南带你快速吃透 Openship 的三种核心认证方式——Session Cookie、Bearer Token 与 PAT（个人访问令牌），并附常见错误速查表，看完即可上手。

一、3种认证方式，1张表看懂

一次请求只会走其中一条路径：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 Token：CLI 与脚本的万能钥匙

没有浏览器的环境（服务器、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 个人访问令牌：如何创建、使用与回收

PAT（Personal 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

两种"收窄"手段按需选用：

3️⃣ 让 CLI 记住令牌

openship login --token opsh_pat_xxxx --context prod openship context use prod # 多实例间一键切换

配置保存在~/.openship/config.json（权限 0600），令牌只会以 Bearer 头发送，绝不会被存成 Cookie。

五、MCP OAuth：AI 助手的专属通道

如果你要接入 Claude、Cursor 这类支持 MCP 的 AI 客户端，无需手动分发 PAT：Openship 本身就是一座标准的OAuth 2.1 授权服务器。客户端首次调用POST /api/mcp时会拿到401指引，随后自动完成注册与 PKCE 授权流程，最后在你的浏览器里弹出同意页——在这里你可以勾选"只读"或指定可访问的项目/服务器范围。

⚠️ 没有经过同意页的 OAuth 令牌默认拒绝一切访问，不存在"已认证但未授权"的灰色地带。已连接的客户端可在Settings → MCP中查看并一键断开（断开即吊销全部令牌）。

六、桌面版零认证模式：本地回环的便利

桌面应用运行在你自己的电脑上，强制登录纯属多余，因此启用零认证模式：API 自动创建一个本地管理员，把本机流量当作该用户处理。它只有同时满足三道闸门才生效：仅限桌面应用、认证模式为none、且请求来自内核确认的127.0.0.1（不信任可伪造的 Host 头）。自建服务器实例默认走local模式，缺会话就是普通的401。

七、常见错误码速查表

八、安全最佳实践清单 ✅

1. 能收窄就收窄：CI 用只读令牌，机器人用单项目 scope，别让令牌"默认全权"；
2. 设过期时间：--expires支持 1–365 天，临时任务用短命令牌；
3. 明文只显示一次：生成后立即存入密码管理器或环境变量；
4. 定期清理：openship token list查看使用情况，闲置令牌及时revoke；
5. 改密即踢人：密码重置会自动吊销全部会话，旧会话立刻失效。

📚 相关资料

• 认证模型完整文档：apps/web/content/docs/security/auth.mdx
• Tokens API 参考：apps/web/content/docs/api/tokens.mdx
• CLI 访问与令牌管理：apps/web/content/docs/cli/access.mdx
• PAT 生成与哈希实现：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