Peas API 完整参考基于 Grape 框架的 RESTful 接口设计与认证全流程教程【免费下载链接】peasDocker and Ruby based PaaS项目地址: https://gitcode.com/gh_mirrors/pe/peasPeas是一个基于 Docker 和 Ruby 的 PaaS平台即服务它的 API 采用Grape 框架构建提供标准化的RESTful 接口并通过SSH 公钥签名 API Key完成用户认证。本文带你快速看懂 Peas API 的整体设计、接口清单与认证全流程。1. Peas API 是什么Grape 框架下的轻量级 REST 网关Peas 的 API 入口非常简洁整个框架的核心配置只有不到 100 行代码位于 config/api.rb框架选型API 类直接继承自Grape::API是 Ruby 生态中比 Rails 更轻量、路由更快的 REST 框架版本管理version v1, using: :header, vendor: peas通过请求头携带版本号未来可平滑升级 v2统一格式format :json所有接口只返回 JSON方便 CLI 和第三方客户端解析自带文档add_swagger_documentation自动生成 Swagger 文档接口即文档。在每次请求之前API 还会执行docker_version_check当宿主机 Docker 版本超过 Peas 已测试的版本时发出警告——这是一种典型的防御式 API 设计。2. 三大核心资源理解接口前先认识这些模型Peas 的 RESTful 路径与数据模型一一对应模型定义在api/models/目录下模型文件通俗解释Appapi/models/app.rb一个应用如 Rails、Node.js 项目拥有配置、Git 仓库、日志Peaapi/models/pea.rb应用的运行实例类似 Heroku 的 dyno本质是一个 Docker 容器Podapi/models/pod.rb运行容器的宿主机多机部署时 Pea 分布在多个 Pod 上Userapi/models/user.rb用户保存 SSH 公钥与 API KeyAddonapi/models/addon.rb附加服务实例如 Postgres、MongoDB 简单记忆App 是图Pea 是粒——一个 App 由多个 Peaweb.1、worker.2…组成。3. Peas RESTful 接口清单一览所有路由定义集中在api/methods/目录按资源分组这是标准的 RESTful 风格组织方式3.1 认证接口/auth—— 唯一无需 API Key 的路径方法路径作用POST/auth/request提交用户名 SSH 公钥返回待签名文档POST/auth/verify提交签名文档换取 API Key3.2 应用管理接口/app定义于 api/methods/app.rb进入该资源前会先执行authenticate!强制鉴权方法路径作用GET/app列出所有应用名称POST/app创建应用可选muse参数提供命名灵感DELETE/app/:name销毁应用连带清除日志、服务实例与仓库GET/app/:name/config查询应用的环境变量PUT/app/:name/config批量创建/更新环境变量DELETE/app/:name/config按 key 列表删除环境变量PUT/app/:name/scale扩缩容如把web进程扩到 3 个一个有趣的设计创建应用时若名字冲突App.divine_name会从 lib/adverbs.txt 中随机挑一个网红副词拼在名字前保证名称唯一且有趣。3.3 管理接口/admin定义于 api/methods/admin.rb方法路径作用GET/admin/settings查看全部默认配置与服务 URIPUT/admin/settings更新 Peas 全局设置自动 upsert4. 认证全流程为什么用 SSH 签名而不是密码Peas 的认证设计借鉴了无密码登录的思路——用 SSH 私钥签名代替密码完整流程分 4 步源码见 api/methods/auth.rb 与 cli/lib/peas/api.rbPOST /auth/requestCLI 把用户名和本地~/.ssh/id_rsa.pub公钥发给 API。若该用户首次注册且数据库中还没有任何用户会被自动提升为管理员API 下发挑战文档服务端生成一个 64 字节的随机串signme存入库中并返回给客户端——这就是挑战-应答机制中的挑战客户端签名CLI 用本地RSA 私钥对该文档做 SHA256 签名再做 URL-safe Base64 编码后提交POST /auth/verify。服务端把 OpenSSH 公钥转为 OpenSSL 格式见 lib/openssh_key_converter.rb用public_key.verify验证签名签发 API Key验证通过后服务端生成一个 64 字节的随机api_key存入 api/models/user.rb 并返回。此后所有请求只需在请求头携带X-Api-Key: your_api_keyAPI 侧通过current_user助手方法按X-Api-Key头查库查不到即返回401 Unauthorised. Invalid or expired token.✅这个设计的好处用户无需在 Peas 上设置密码降低凭据泄露风险公钥同时写入 SSHauthorized_keys见User模型的before_save钩子因此同一把密钥还能直接git push代码部署一钥两用签名验证基于非对称加密服务端永远不接触用户的私钥。5. 统一响应结构与错误处理Peas API 约定了极简的响应包裹格式respond助手见 config/api.rb{ version: x.y.z, message: App lively-node successfully created, remote_uri: gityour-peas-host:app-name.git }version每次响应都携带 API 版本号CLI 会对比本地版本主/次版本不一致时提示升级避免新旧客户端不兼容错误处理未认证返回401路径不存在返回404签名验证失败返回406rescue_from :all会把未捕获异常写入日志开发环境下还会附带错误位置信息便于排错长任务如扩缩容这类耗时操作不直接阻塞等待而是返回一个job任务 ID客户端再通过 Switchboard 消息总线订阅任务进度见 cli/lib/peas/api.rb 中的stream_job。 接口的行为在 spec/api/api_spec.rb 中有完整的集成测试覆盖配合spec/fabricators/下的数据工厂可以快速理解每个接口的请求/响应样例。6. 动手调用从 CLI 源码看一次真实的 API 请求CLI位于cli/目录是最好的接口说明书。API#request方法封装了全部调用逻辑用 HTTParty 发起请求路径形如/app/:name/scale需要鉴权时自动附加x-api-key请求头响应含error键则抛出红色错误信息含job键则转入 Switchboard 流式输出。 如果你只用 curl 手动调试最小可用示例是curl -H X-Api-Key: key https://你的Peas域名/app7. 常见问题 FAQQ哪些接口不需要 API KeyA只有/auth/request和/auth/verify两个认证接口本身免鉴权其余接口/app、/admin都通过before { authenticate! }强制校验。QAPI Key 泄露了怎么办AAPI Key 存储在User文档中管理员删除该用户后旧 Key 即失效after_destroy钩子会同步移除其 SSH 授权重新走一次认证流程即可拿到新 Key。Q如何查看自动生成的接口文档AAPI 启用了add_swagger_documentation在启动 API 服务后访问其文档路径即可获得完整的 Swagger 描述参数名、类型、必填项一应俱全。8. 小结Peas API 用 Grape 框架展示了小而美的 RESTful 设计范式按资源组织路由auth / app / admin模型与接口一一对应SSH 签名认证 无状态 API Key安全且对 CLI 友好统一响应包裹 版本检查为客户端升级留出缓冲Swagger 自动生成 spec 全覆盖文档与测试同源于路由定义。理解了这份接口与认证设计你就掌握了自己对接、扩展 Peas PaaS 的全部钥匙。【免费下载链接】peasDocker and Ruby based PaaS项目地址: https://gitcode.com/gh_mirrors/pe/peas创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考