# Nacos 服务注册与发现中心

本文档说明 ERP 微服务架构中 Nacos 的配置与使用方法。

## 📁 目录结构

```
nacos/
├── README.md                          # 本文档
├── docker-compose.standalone.yml      # 单机模式 Docker Compose
├── docker-compose.cluster.yml         # 集群模式 Docker Compose (3节点)
├── init/
│   └── mysql-schema.sql               # Nacos MySQL 持久化 Schema
├── cluster/
│   └── nginx.conf                     # Nacos 集群 Nginx 负载均衡配置
├── examples/
│   ├── nacos-api-usage.md             # Nacos REST API 使用示例
│   ├── ServiceRegistrationExample.java # 服务注册示例代码
│   ├── HealthCheckConfig.java         # 健康检查配置示例
│   └── client-config/
│       ├── nacos-client.properties     # 通用 Nacos 客户端配置
│       ├── bootstrap.yml               # Spring Cloud bootstrap 配置模板
│       └── user-service-nacos.yml      # user-service 完整配置示例
└── scripts/
    └── startup.sh                     # Nacos 启动脚本
```

## 🚀 快速开始

### 1. 启动 Nacos（单机模式）

```bash
cd /root/.openclaw/workspace/erp-java-backend/nacos

# 方式一：使用脚本
chmod +x scripts/startup.sh
./scripts/startup.sh --mode standalone

# 方式二：直接使用 Docker Compose
docker compose -f docker-compose.standalone.yml up -d

# 方式三：使用 docker-compose 命令
docker-compose -f docker-compose.standalone.yml up -d
```

### 2. 访问 Nacos 控制台

- **地址**: http://localhost:8848/nacos
- **用户名**: `nacos`
- **密码**: `nacos123456`

### 3. 验证服务注册

访问控制台 → **服务管理** → **服务列表**，应能看到已注册的服务。

---

## 🏗 架构说明

### 单机模式 (Standalone)

```
┌─────────────────┐
│  Microservices  │
│  (Spring Boot)  │
└───────┬─────────┘
        │ HTTP/gRPC
        ▼
┌─────────────────┐
│  Nacos Server   │ ◄── 单节点
│  (v2.2.3)       │
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│     MySQL       │ ◄── 持久化存储
│    (8.0)        │
└─────────────────┘
```

### 集群模式 (Cluster)

```
                        ┌─────────────────┐
                        │  Nginx (LB)     │
                        │  :8848, :9848   │
                        └───────┬─────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
┌───────────────┐      ┌───────────────┐      ┌───────────────┐
│ Nacos Node 1  │      │ Nacos Node 2  │      │ Nacos Node 3  │
│   :8848       │◄────►│   :8848       │◄────►│   :8848       │
│   :9848       │      │   :9848       │      │   :9848       │
│   :9849       │      │   :9849       │      │   :9849       │
└───────┬───────┘      └───────┬───────┘      └───────┬───────┘
        │                       │                       │
        └───────────────────────┼───────────────────────┘
                                │
                                ▼
                        ┌───────────────┐
                        │    MySQL      │
                        │   (8.0)       │
                        └───────────────┘
```

---

## ⚙️ 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `NACOS_SERVER_ADDR` | Nacos 服务器地址 | `127.0.0.1:8848` |
| `NACOS_NAMESPACE` | 命名空间 ID | `public` |
| `NACOS_GROUP` | 分组名称 | `DEFAULT_GROUP` |
| `NACOS_USERNAME` | Nacos 用户名 | `nacos` |
| `NACOS_PASSWORD` | Nacos 密码 | `nacos123456` |
| `SPRING_PROFILES_ACTIVE` | Spring 环境 | `dev` |

### 微服务配置

#### 方式一：修改 application.yml

在各微服务的 `application.yml` 中添加：

```yaml
spring:
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
        namespace: public
        group: DEFAULT_GROUP
        prefer-ip-address: true
        cluster-name: DEFAULT
      config:
        server-addr: ${spring.cloud.nacos.discovery.server-addr}
        file-extension: yaml
        shared-configs:
          - data-id: common-config.yaml
            group: DEFAULT_GROUP
            refresh: true
```

#### 方式二：使用 bootstrap.yml（推荐）

将 `examples/client-config/bootstrap.yml` 复制到微服务 `src/main/resources/`，并根据需要修改。

#### 方式三：环境变量覆盖

```bash
java -jar app.jar \
  -DNACOS_SERVER_ADDR=127.0.0.1:8848 \
  -DNACOS_NAMESPACE=public \
  -DNACOS_GROUP=DEFAULT_GROUP
```

---

## 📋 微服务列表与配置

| 服务名 | 端口 | Context Path | 说明 |
|--------|------|--------------|------|
| `api-gateway` | 8080 | `/` | API网关 |
| `user-service` | 8082 | `/user` | 用户服务 |
| `tenant-service` | 8083 | `/tenant` | 租户服务 |
| `product-service` | 8084 | `/product` | 产品服务 |
| `order-service` | 8085 | `/order` | 订单服务 |
| `inventory-service` | 8086 | `/inventory` | 库存服务 |
| `finance-service` | 8087 | `/finance` | 财务服务 |
| `notification-service` | 8088 | `/notification` | 通知服务 |
| `file-service` | 8089 | `/file` | 文件服务 |
| `admin-service` | 8090 | `/admin` | 管理服务 |

---

## 🏥 健康检查配置

### 默认健康检查

Nacos 默认通过 **TCP 端口检测** 判断实例健康状态。

### 自定义健康检查（推荐）

使用 Spring Boot Actuator：

```yaml
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
  endpoint:
    health:
      show-details: always
  health:
    nacos:
      enabled: true
```

### 健康检查流程

```
1. 客户端每 5秒 向 Nacos 发送心跳
2. Nacos 15秒 未收到心跳，标记为不健康
3. Nacos 30秒 未收到心跳，删除实例
4. 服务恢复后，自动重新注册
```

---

## 🌐 Nacos API 调用

详细 API 调用示例见 [nacos-api-usage.md](examples/nacos-api-usage.md)

### 服务注册

```bash
curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance' \
  -d 'serverIp=127.0.0.1' \
  -d 'serverPort=8082' \
  -d 'serviceName=user-service'
```

### 服务发现

```bash
curl -s 'http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=user-service'
```

### 配置管理

```bash
# 发布配置
curl -X POST 'http://127.0.0.1:8848/nacos/v1/cs/configs' \
  -d 'dataId=user-service.yaml' \
  -d 'group=DEFAULT_GROUP' \
  -d 'content=spring: datasource: url: jdbc:mysql://localhost:3307'

# 查询配置
curl -s 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=user-service.yaml&group=DEFAULT_GROUP'
```

---

## 🔐 安全配置

### 生产环境必改项

1. **修改默认密码**
   ```yaml
   NACOS_AUTH_ENABLE: "true"
   NACOS_AUTH_TOKEN: "YourNewSecretKeyHere..."
   ```

2. **启用认证**
   ```yaml
   spring.cloud.nacos.discovery.username=nacos
   spring.cloud.nacos.discovery.password=YourNewPassword
   ```

3. **网络隔离**
   - 使用内网 IP，不暴露公网
   - 配置防火墙规则
   - 使用 VIP/Nginx 做负载均衡

---

## 🚢 部署到 Kubernetes

集群模式配置见 [docker-compose.cluster.yml](docker-compose.cluster.yml)

### 关键配置

- **3节点部署**: 推荐奇数节点，保证 Raft 共识算法正常
- **MySQL 外部化**: 生产环境使用主从 MySQL
- **Nginx 负载均衡**: 统一入口，分发到 3 个 Nacos 节点
- **持久化**: 使用 PVC 挂载日志和数据目录

---

## ❓ 常见问题

### 1. 微服务无法注册到 Nacos

- 检查 Nacos 是否启动：`curl http://localhost:8848/nacos/v1/console/health/readiness`
- 检查网络连通性：`telnet localhost 8848`
- 检查防火墙：`firewall-cmd --list-ports`

### 2. 控制台登录失败

- 默认用户名/密码：`nacos` / `nacos123456`
- 检查认证是否启用：`NACOS_AUTH_ENABLE=true`

### 3. gRPC 端口无法连接

- Nacos 2.x 使用 9848/9849 端口进行 gRPC 通信
- 确保这些端口已开放

### 4. 配置不生效

- 检查 `refresh-enabled: true` 是否设置
- 使用 `@RefreshScope` 注解刷新配置
- 检查命名空间和分组是否匹配

---

## 📚 相关文档

- [Nacos 官方文档](https://nacos.io/zh-cn/docs/what-is-nacos.html)
- [Spring Cloud Alibaba Nacos Discovery](https://spring-cloud-alibaba-group.github.io/github-pages/2023.0.1.0/zh-cn/documentation/spring-cloud-alibaba-nacos-discovery.html)
- [Spring Cloud Alibaba Nacos Config](https://spring-cloud-alibaba-group.github.io/github-pages/2023.0.1.0/zh-cn/documentation/spring-cloud-alibaba-nacos-config.html)