315 lines
9.3 KiB
Markdown
315 lines
9.3 KiB
Markdown
# 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)
|