3. 流水线集成平台门户概述
流水线集成平台门户是开发者与基础设施之间的统一交互界面，它屏蔽了底层CI/CD引擎、API网关、配置中心的复杂性，提供“服务目录、API文档、自助申请”三大核心能力。本节将拆解门户的功能模块，并展示其与CI/CD流水线的两种主流集成模式。
3.1 门户三大核心功能
| 功能模块 | 核心能力 | 面向角色 | 典型输出 |
|---|---|---|---|
| 服务目录 | 注册、发现、版本管理、依赖关系可视化 | 开发者、架构师 | 服务列表、元数据、健康状态 |
| API文档 | OpenAPI/Swagger在线预览、Mock测试、变更Diff | 前端、后端、测试 | 交互式文档页、请求示例 |
| 自助申请 | 环境权限、网关路由、配置变更、资源配额 | 开发者、SRE | 工单、审批流、自动生效 |
关键设计原则： 门户不直接操作Kong Admin API或Kubernetes资源，而是通过“声明式工单 + 异步执行器”模式，确保所有变更都经过版本控制和审计。
3.2 服务目录与API文档的联动关系
服务目录是“骨架”，API文档是“血肉”。当开发者在流水线中发布新版本时，门户自动完成以下联动：
- 服务注册：流水线产物（如Docker镜像Tag）推送到制品库后，触发Webhook更新服务目录中的版本字段。
- 文档同步：流水线中集成的OpenAPI Lint步骤将校验通过的规范文件推送至门户文档中心。
- 网关映射：门户根据服务目录中的“路由前缀”和“上游Host”，自动生成Kong Service/Route的待审批配置。
3.3 自助申请：从工单到网关配置生效
自助申请是门户与Kong网关回滚护栏结合最紧密的模块。开发者无需登录Kong Manager或使用Admin API，只需在门户填写申请表单，系统自动生成标准化的网关配置变更请求。
最佳实践： 自助申请应支持“预检”功能——在提交前模拟计算当前网关配置与申请配置的差异，并自动检测是否触发回滚护栏规则（如路由冲突、上游超时阈值超限）。
3.3.1 自助申请典型流程
- 选择服务：从服务目录下拉选择目标服务，自动填充当前网关路由前缀。
- 配置变更：填写新增路由路径、上游超时时间、插件参数（如限流速率）。
- 预检与审批：系统调用“配置差异引擎”生成Diff，并匹配护栏规则；若命中高风险规则，自动转人工审批。
- 异步生效：审批通过后，配置变更写入Kong声明式配置文件（如deck dump），由CI/CD流水线执行同步。
3.4 与CI/CD流水线的集成方式
门户与CI/CD流水线存在两种互补的集成模式，实际落地时通常混合使用：
| 集成模式 | 触发方向 | 典型场景 | 优势 | 注意事项 |
|---|---|---|---|---|
| 流水线推送 | CI/CD → 门户 | 部署后自动更新服务目录版本、推送API文档 | 实时性高，减少人工操作 | 需在流水线中集成门户CLI或API |
| 门户回调 | 门户 → CI/CD | 自助申请审批后触发流水线执行Kong同步 | 变更可追溯，支持审批流 | 需配置Webhook回调地址及幂等性处理 |
3.5 集成配置示例
以下为Jenkins流水线中集成门户推送API文档的声明式代码片段：
// Jenkinsfile 片段
stage('Push API Doc to Portal') {
steps {
script {
// 使用门户CLI推送OpenAPI规范
sh """
portal-cli doc push \\
--service ${SERVICE_NAME} \\
--version ${BUILD_NUMBER} \\
--file ./openapi.yaml \\
--api- ${PORTAL_}
"""
}
}
}
安全提醒： 门户API 不应明文存储在Jenkinsfile中，建议使用Jenkins Credentials Binding插件或Vault动态密钥。