Openship REST API 速查指南：Projects、Deployments、Domains、Tokens 四大核心端点全解析
【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship
Openship 是一款开源的自托管部署平台（self-hosted deployment platform），能从 Git 仓库一键构建、部署应用，并自动处理域名路由与 TLS 证书。本文是一份Openship REST API 速查，面向新手与集成开发者，汇总 Projects（项目）、Deployments（部署）、Domains（域名）、Tokens（令牌）四大核心端点，帮你快速上手用 API 驱动整套部署流程 🔑
认证方式：用 Bearer Token 访问 API
所有/api/*端点都要求认证。推荐流程：先在 Web 控制台的 Settings 里创建一个PAT（个人访问令牌），然后在每个请求中携带：
- 请求头：
Authorization: Bearer <你的令牌> - 令牌的解析逻辑见 bearer.ts，它是所有 Bearer 认证的唯一入口
💡 提示：为 CI/CD 流水线单独创建一个作用域受限的 PAT，用完即撤销，比共用账号密码安全得多。
Projects 项目端点：创建、更新与查询
项目路由挂载在/api/projects（见 project.routes.ts），是 Openship REST API 中使用频率最高的一组端点。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/projects | 列出组织内所有项目 |
| POST | /api/projects | 从 Git 仓库或本地源创建项目 |
| GET | /api/projects/:id | 获取项目详情（配置、源、路由、状态） |
| PATCH | /api/projects/:id | 更新项目构建配置 |
| DELETE | /api/projects/:id | 删除项目（建议先看删除预览） |
| GET | /api/projects/:id/deletion-preview | 只读预览删除会移除哪些资源 |
| GET | /api/projects/:id/environments | 列出环境（production / 预览） |
| POST | /api/projects/:id/environments | 创建预览环境 |
| GET | /api/projects/:id/env | 查看环境变量（密钥值自动掩码） |
| PATCH | /api/projects/:id/env | 合并式修改环境变量，未提及的变量保持不变 |
| POST | /api/projects/:id/enable | 启用项目，允许部署 |
| POST | /api/projects/:id/disable | 停用项目，暂停部署 |
| GET | /api/projects/:id/deployments | 列出该项目部署历史 |
| GET | /api/projects/:id/pending-actions | 查看阻塞项及每项的具体解决方式 |
| GET | /api/projects/:id/logs | 获取运行时日志（非流式） |
| POST | /api/projects/:id/routing/retry | 重试免费域名的边缘路由同步 |
📌 新手最常踩的坑：改环境变量请用PATCH 合并（upserts + deletes），不要尝试全量覆盖，避免误清空密钥类变量。路由定义可参考 project.routes.ts。
Deployments 部署端点：触发构建、回滚与取消
部署路由挂载在/api/deployments（见 deployment.routes.ts），覆盖"触发 → 跟踪 → 决策 → 回滚"的完整生命周期。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/deployments | 列出组织内部署，可用?projectId过滤 |
| POST | /api/deployments | 从已关联的 Git 源触发部署（推送即部署） |
| POST | /api/deployments/build/access | 向导式部署入口，支持文件夹上传流程 |
| GET | /api/deployments/:id | 查看部署状态、URL、耗时与错误摘要 |
| GET | /api/deployments/:id/build | 实时构建进度：当前步骤、各服务状态 |
| GET | /api/deployments/:id/logs | 获取构建 / 运行日志 |
| GET | /api/deployments/:id/pending | 部署卡住时查看等待项及解锁调用 |
| POST | /api/deployments/:id/build/respond | 回答阻塞决策（如端口冲突：释放端口或中止） |
| POST | /api/deployments/:id/redeploy | 重跑该项目最近一次部署 |
| POST | /api/deployments/:id/rollback | 回滚到指定部署的产物 / 提交 |
| POST | /api/deployments/:id/cancel | 取消进行中的部署 |
| POST | /api/deployments/:id/restart | 重启该部署正在运行的容器 |
| DELETE | /api/deployments/:id | 删除部署记录 |
🧠 排障心法：当部署"看起来卡住了"，先轮询GET /:id/pending——它会直接告诉你阻塞原因（例如端口已被占用）以及具体该调用哪个端点来解除。更多操作端点可参考 deployment.routes.ts。
Domains 域名端点：DNS 验证与 SSL 续期
域名路由挂载在/api/domains（见 domain.routes.ts），支持免费子域与自定义域名的验证、DNS 自动配置和证书续期。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/domains | 列出组织 / 项目的域名 |
| POST | /api/domains | 添加域名（免费子域或自定义域名） |
| POST | /api/domains/preview | 添加前预览该域名所需的 DNS 记录 |
| GET | /api/domains/:id | 查看单个域名的验证与 SSL 状态 |
| POST | /api/domains/:id/verify | 验证域名所有权 / DNS |
| POST | /api/domains/:id/primary | 将该域名设为主域名 |
| GET | /api/domains/:id/records | 获取需要配置的 DNS 记录 |
| GET | /api/domains/:id/dns/plan | 只读预览：通过已连接供应商自动配置会改什么 |
| POST | /api/domains/:id/dns/apply | 通过已连接 DNS 供应商自动写入记录 |
| POST | /api/domains/:id/renew | 续期该域名的 SSL 证书 |
| POST | /api/domains/:id/verify-ssl | 检查并验证 SSL 证书 |
| POST | /api/domains/renew-all | 批量续期全部证书 |
| DELETE | /api/domains/:id | 删除域名 |
🌐 推荐顺序：preview预览 DNS → 添加 →verify验证 →renew等证书签发。dns/plan与dns/apply是先预览后落盘的两步式设计，永远不会静默修改你的 DNS。
Tokens 令牌端点：PAT 管理与 MCP 授权
令牌路由挂载在/api/tokens（见 token.routes.ts），每个操作都只作用于当前调用者自己的令牌，天然隔离。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/tokens | 列出我的 PAT |
| POST | /api/tokens | 创建 PAT（可指定作用域，如项目级读写） |
| DELETE | /api/tokens/:id | 撤销（吊销）PAT |
| POST | /api/tokens/mcp-authorize | 授权一个 MCP 客户端 |
| GET | /api/tokens/mcp-clients | 列出已连接的 MCP 客户端 |
| DELETE | /api/tokens/mcp-clients/:clientId | 断开 MCP 客户端 |
🔐 安全建议：给每个自动化场景（CI、脚本、MCP 工具）发一个独立令牌并设定最小作用域，出问题时精准吊销即可，不影响其他集成。端点细节见 token.routes.ts。
一条链完成部署：REST API 常见工作流
把上面四组端点串起来，就是一个完整的 API 驱动部署流水线 🚀：
- 创建/确认项目：
POST /api/projects（Git 源）→GET /api/projects/:id拿到id - 触发部署：
POST /api/deployments或/api/deployments/build/access，返回deployment_id - 跟踪进度：轮询
GET /api/deployments/:id/build；卡住就看GET /:id/pending并按resolveWith提示作答 - 接上域名：
POST /api/domains→POST /:id/verify→ 等待证书就绪 - 兜底操作：出问题
POST /:id/rollback秒级回滚，或POST /:id/cancel取消构建
一个最小的调用示例（其余请求同理，仅需替换方法与路径）：
curl -H "Authorization: Bearer <你的令牌>" \ https://你的Openship地址/api/projects掌握这份 Openship REST API 速查后，你就可以把自建部署平台完全纳入脚本、CI 与自动化体系，让"推送代码 → 上线"只需一条 API 调用 ⚡
【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
