====== Nop 平台的微服务部署 ======

Nop 平台支持微服务架构。每个模块都可以独立部署为一个服务，通过 RPC 相互调用。

===== 模块即服务 =====

nop-entropy 是多模块 Maven 项目。每个模块可以单独打包为独立服务：

<code>
nop-auth/nop-auth-app        → 用户权限服务
nop-sys/nop-sys-app          → 系统配置服务
nop-report/nop-report-app    → 报表服务
nop-wf/nop-wf-app            → 工作流服务
</code>

每个 app 模块是完整的 Quarkus 应用，可以独立编译和启动：

<code bash>
cd nop-auth/nop-auth-app
./mvnw compile quarkus:dev
</code>

===== 服务间通信：nop-rpc =====

服务间通过 nop-rpc 模块通信，支持 REST 和 gRPC 两种协议。

定义 API 接口（api.xml 文件）：

<code xml>
<api x:schema="/nop/schema/api.xdef"
     name="IUserService">
  <methods>
    <method name="getUser" type="query">
      <args>
        <arg name="userId" type="String" />
      </args>
      <return type="UserVO" />
    </method>
    <method name="saveUser" type="action">
      <args>
        <arg name="data" type="UserVO" />
      </args>
      <return type="String" />
    </method>
  </methods>
</api>
</code>

按约定的目录结构放置，框架自动注册为 GraphQL/REST/gRPC 端点。

===== 服务发现：Nacos =====

nop-cluster-nacos 模块集成 Nacos，用于服务注册和发现。

配置：

<code properties>
# application.properties
nop.cluster.nacos.server-addr=localhost:8848
nop.cluster.nacos.namespace=public
nop.application.name=auth-service
</code>

启动时自动注册到 Nacos，调用方通过服务名调用：

<code xml>
<!-- 消费者配置 -->
<beans>
  <bean id="userService" class="io.nop.rpc.cluster.ClusterRpcProxyFactoryBean">
    <property name="serviceName" value="auth-service" />
    <property name="apiInterface" value="IUserService" />
  </bean>
</beans>
</code>

支持的服务注册中心：

  * Nacos（生产推荐）
  * ZooKeeper（通过扩展）
  * Consul（通过扩展）
  * 直连（开发调试用）

===== 流量控制：Sentinel =====

nop-cluster-sentinel 模块集成阿里 Sentinel，提供限流和熔断能力。

<code properties>
nop.cluster.sentinel.flow-rules=classpath:sentinel-flow-rules.json
nop.cluster.sentinel.degrade-rules=classpath:sentinel-degrade-rules.json
</code>

规则在运行时热加载，无需重启。

===== 分布式缓存：Hazelcast =====

nop-hazelcast 模块提供分布式缓存支持，多节点共享缓存状态。

<code properties>
nop.hazelcast.config=classpath:hazelcast.xml
</code>

聚合查询、会话共享、配置缓存等场景适用。

===== 集群管理 =====

nop-cluster-admin 模块提供集群管理命令：

  * 优雅关闭（ShutdownCommand）
  * 健康检查
  * 集群成员查看

===== 典型部署架构 =====

===== nop-gateway 网关 =====

nop-gateway 是平台自带的网关模块，支持路由转发、协议转换、拦截器链。可以统一暴露内部微服务接口，也可以在网关层完成 AI API 的协议转换（OpenAI ↔ Claude ↔ Ollama）。

配置路由（gateway.xml）：

<code xml>
<gateway>
  <routes>
    <route id="auth-api" path="/api/auth/**">
      <forward to="http://auth-service:8080" />
    </route>
    <route id="report-api" path="/api/report/**">
      <forward to="http://report-service:8080" />
    </route>
  </routes>
</gateway>
</code>

内置能力：
  * 路径匹配路由转发
  * 自定义拦截器
  * 流式响应
  * AI 协议转换
  * Gateway HTTP Filter 集成

<code>
                     ┌──────────────┐
                     │  nop-gateway  │
                     └──────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
         ┌────▼───┐   ┌────▼───┐   ┌────▼───┐
         │ Auth   │   │ Sys    │   │ Report │
         │ Service│   │ Service│   │ Service│
         └────┬───┘   └────┬───┘   └────┬───┘
              │             │             │
         ┌────▼─────────────▼─────────────▼───┐
         │         Nacos / Hazelcast          │
         └────────────────────────────────────┘
              │             │             │
         ┌────▼───┐   ┌────▼───┐   ┌────▼───┐
         │  MySQL │   │ Redis  │   │ Kafka  │
         └────────┘   └────────┘   └────────┘
</code>

===== 部署步骤 =====

**1. 编译每个服务：**

<code bash>
cd nop-entropy
./mvnw clean install -DskipTests -Dquarkus.package.type=uber-jar
</code>

**2. 打包为 Docker 镜像：**

每个 app 模块的 target 目录下生成 `*-runner.jar`，即为可执行的 fat jar：

<code bash>
java -jar nop-auth-app/target/nop-auth-app-2.0.0-SNAPSHOT-runner.jar
</code>

**3. 编排服务：**

可以用以下方式编排：

  * Docker Compose（开发环境）
  * Kubernetes（生产环境）
  * 单机部署（小规模）

===== 进一步阅读 =====

  * [[.:module_guide|模块使用指南]]
  * [[.:setup_guide|环境配置]]
  * deploy/ 目录下的监控配置（Prometheus + Grafana）