企业官网建设流程全解析

Peas API 完整参考：基于 Grape 框架的 RESTful 接口设计与认证全流程教程

【免费下载链接】peasDocker and Ruby based PaaS项目地址: https://gitcode.com/gh_mirrors/pe/peas

🌱Peas是一个基于 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/目录下：

💡 简单记忆：App 是"图"，Pea 是"粒"——一个 App 由多个 Pea（web.1、worker.2…）组成。

3. Peas RESTful 接口清单一览

所有路由定义集中在api/methods/目录，按资源分组，这是标准的 RESTful 风格组织方式：

3.1 认证接口（/auth）—— 唯一无需 API Key 的路径

3.2 应用管理接口（/app）

定义于 api/methods/app.rb，进入该资源前会先执行authenticate!强制鉴权：

一个有趣的设计：创建应用时若名字冲突，App.divine_name会从 lib/adverbs.txt 中随机挑一个"网红副词"拼在名字前，保证名称唯一且有趣。

3.3 管理接口（/admin）

定义于 api/methods/admin.rb：

4. 认证全流程：为什么用 SSH 签名而不是密码？

Peas 的认证设计借鉴了"无密码登录"的思路——用 SSH 私钥签名代替密码，完整流程分 4 步（源码见 api/methods/auth.rb 与 cli/lib/peas/api.rb）：

1. POST /auth/request：CLI 把用户名和本地~/.ssh/id_rsa.pub公钥发给 API。若该用户首次注册且数据库中还没有任何用户，会被自动提升为管理员；

2. API 下发挑战文档：服务端生成一个 64 字节的随机串signme存入库中，并返回给客户端——这就是"挑战-应答"机制中的挑战；

3. 客户端签名：CLI 用本地RSA 私钥对该文档做 SHA256 签名，再做 URL-safe Base64 编码后提交POST /auth/verify。服务端把 OpenSSH 公钥转为 OpenSSL 格式（见 lib/openssh_key_converter.rb），用public_key.verify验证签名；

4. 签发 API Key：验证通过后，服务端生成一个 64 字节的随机api_key存入 api/models/user.rb 并返回。此后所有请求只需在请求头携带：

   X-Api-Key: <your_api_key>

   API 侧通过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": "git@your-peas-host:app-name.git" }

• version：每次响应都携带 API 版本号，CLI 会对比本地版本，主/次版本不一致时提示升级，避免新旧客户端不兼容；
• 错误处理：未认证返回401，路径不存在返回404，签名验证失败返回406；rescue_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方法封装了全部调用逻辑：

1. 用 HTTParty 发起请求，路径形如/app/:name/scale；
2. 需要鉴权时自动附加x-api-key请求头；
3. 响应含error键则抛出红色错误信息；含job键则转入 Switchboard 流式输出。

💡 如果你只用 curl 手动调试，最小可用示例是：

curl -H "X-Api-Key: <key>" https://你的Peas域名/app

7. 常见问题 FAQ

Q：哪些接口不需要 API Key？A：只有/auth/request和/auth/verify两个认证接口本身免鉴权，其余接口（/app、/admin）都通过before { authenticate! }强制校验。

Q：API Key 泄露了怎么办？A：API Key 存储在User文档中，管理员删除该用户后旧 Key 即失效（after_destroy钩子会同步移除其 SSH 授权）；重新走一次认证流程即可拿到新 Key。

Q：如何查看自动生成的接口文档？A：API 启用了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