部署拓扑与 License
本文说明 ApiGo 的生产部署结构和 License 授权机制。涉及地址、账号、密钥的内容一律通过环境变量或外置配置文件注入，文档不记录任何真实值。
部署拓扑
组件清单
| 组件 | 是否必需 | 说明 |
|---|---|---|
| MySQL 8.4+ | 必需 | 平台元数据；未启用 ES 时也存储调用日志 |
| Redis 7+ | 必需 | 运行态配置中枢、Pub/Sub 变更通知、分布式锁、响应缓存 |
| 注册中心（Nacos 2.3+ 或 Eureka） | 集群部署必需 | 服务发现、集群节点数探测；单机直连可省略 |
| Elasticsearch 7+ | 可选 | 调用日志检索；启用后日志不再落 MySQL |
| apigo-admin | 必需 | 管理端 API 与配置下发 |
| apigo-api | 必需 | 接口执行引擎 |
| apigo-gateway | 必需 | 统一入口与治理 |
| apigo-web | 必需 | 前端门户静态资源 |
启动顺序
- MySQL、Redis、注册中心（及可选的 Elasticsearch）
apigo-adminapigo-apiapigo-gatewayapigo-web
管理端启动时会加载数据源、把运行态配置写入 Redis；网关依赖这些数据构建路由。顺序颠倒时网关可能短暂无路由，等待下一次对账后自愈，但首次部署仍建议按序启动。
端口约定
| 服务 | 默认端口 |
|---|---|
| apigo-admin | 9377 |
| apigo-api | 9366 |
| apigo-gateway | 9600 |
| apigo-web | Nginx 80（容器映射 8080）；开发模式 Vite 默认 7000 |
开放接口统一从网关 9600 进入，不直接暴露 apigo-api。
配置安全
以下配置必须外置，不得写入代码仓库或文档：
- 数据库地址、账号、密码
- Redis 地址与密码
- AI 模型 API Key
- SMTP / 短信 / Webhook 凭证
- License 文件与私钥
建议通过环境变量、配置中心或挂载的 application-*.yml 注入，并限制文件权限。数据源密码在平台内使用 RSA/SM2 加密存储，但这不替代对配置文件的访问控制。
License 机制
保护范围
apigo-admin、apigo-api、apigo-gateway 均依赖 apigo-license 模块。三个服务启动时都会校验授权；任一服务校验失败都不能启动 。
校验流水线
- 验签：使用发布包 jar 内置的公钥（信任锚）验证签名，防止伪造与篡改；开发构建可通过
apigo.license.public-key指定。 - 时间窗口：当前时间必须落在
notBefore与notAfter之间。 - 服务白名单：
serviceIds非空时，当前服务的spring.application.name必须在列表内，防止一份 License 通用于所有服务。 - 类型化校验：按授权类型检查 MAC 或集群节点数。
- 时钟回拨：与状态文件记录的时间水位比较；回拨超过容差判定为篡改。
三种授权类型
| 类型 | 校验内容 | 适用场景 |
|---|---|---|
SIMPLE | 仅时间窗口 | 演示、PoC、全动态环境 |
STANDARD | 时间 + 服务器 MAC 绑定 | 单机、物理机、固定集群 |
CLUSTER | 时间 + 集群节点数上下限（不校验 MAC） | Kubernetes、Swarm 等容器动态环境 |
CLUSTER 的节点数取 max(注册中心实例数, 配置下限)。配置值只能声明下限，无法下调真实探测值，避免通过改配置绕过节点上限。
License 载荷
| 字段 | 含义 |
|---|---|
licenseId | 授权编号（UUID） |
licensee | 被授权方名称 |
productCode | 产品线编码（可选） |
type | SIMPLE / STANDARD / CLUSTER |
algorithm | 签名算法：RSA 或 SM2 |
issueAt / notBefore / notAfter | 签发、生效、过期时间（epoch 秒） |
macs | 授权 MAC 列表（STANDARD） |
maxNodes / minNodes | 节点数上限 / 下限（CLUSTER） |
serviceIds | 服务白名单（可选） |
关键配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
apigo.license.enabled | false | 仅开发构建可关闭；发布包内置信任锚后强制启用 |
apigo.license.license-file | - | 外置授权文件路径，支持裸路径、file:、classpath: |
apigo.license.check-interval | 24h | 定时校验周期，最小 1 分钟 |
apigo.license.clock-skew-tolerance | 24h | 时钟回拨容差 |
apigo.license.state.file | ~/.apigo/license.state | 回拨水位状态文件 |
apigo.license.state.strict | true | 状态文件不可用时拒绝运行（fail-closed） |
apigo.license.mac.primary-interface | 自动识别 | 指定校验的主网卡 |
apigo.license.cluster.node-count | 1 | 授权节点数下限 |
apigo.license.cluster.on-provider-error | fail | 节点探测异常时终止或告警 |
apigo.license.cluster.node-limit-action | fail | 节点数越界时终止或告警 |
状态文件必须持久化
容器部署必须把 state.file 所在目录挂载到持久卷。状态文件丢失在 strict=true 下会导致服务拒绝启动；这是为了防止通过删除状态文件绕过时钟回拨检测。
失效处置
| 场景 | 行为 |
|---|---|
| 启动校验失败 | 抛出异常，进程以非 0 退 出码终止 |
| 运行期定时校验失败 | 记录 ERROR，按优雅停机策略退出，退出码 1 |
| 注册中心抖动等非预期异常 | 记录 ERROR，下个周期重试，不立即退出 |
节点数超出上限且策略为 fail | 终止运行；策略为 warn 时告警后继续 |
退出码 1 用于与正常停机（0）区分，便于编排系统识别是授权问题而非普通重启。
错误码
| 错误码 | 含义 |
|---|---|
L001 | 未配置 License |
L002 | License 格式非法 |
L003 | 签名校验失败 |
L004 | 公钥配置非法 |
L005 | 不支持的签名算法或缺少依赖 |
L006 | License 尚未生效 |
L007 | License 已过期 |
L008 | 服务器 MAC 与授权不匹配 |
L009 | 集群节点数超过授权上限 |
L010 | 检测到系统时钟回拨 |
L011 | 当前服务不在授权范围 |
L012 | 状态文件校验失败（疑似篡改） |
L013 | 状态文件不可用 |
L014 | 集群节点数探测失败 |
L015 | 集群节点数低于授权下限 |
运维检查清单
- MySQL、Redis 可用，字符集为
utf8mb4 - 已执行
db/mysql/ddl.sql与必要的升级脚本 - 三个 Java 服务使用同一套 Redis，且网络互通
- License 文件挂载为只读，状态目录可写且持久化
- 服务启动顺序正确，网关能读到路由
- 前端 Nginx 已配置 API 反向代理与静态资源缓存
- 日志、监控、告警通道已接通