# 端口规划方案

本文档定义了 B2B AI Shopping Assistant 项目的端口分配规范。

## 📋 端口分配总览

### 1️⃣ 基础设施层 (3000-3999)

用于前端界面、Web 控制台等面向用户的服务。

| 端口 | 服务 | 说明 | 状态 |
|------|------|------|------|
| 3000 | Chatwoot | 客户支持平台主界面 | ✅ 使用中 |
| 3001-3009 | - | 预留给 Web 界面服务 | 🔄 预留 |
| 3010-3099 | - | 预留给基础设施扩展 | 🔄 预留 |

### 2️⃣ 应用服务层 (8000-8999)

核心 AI 和 MCP 后端服务。

| 端口 | 服务 | 说明 | 状态 |
|------|------|------|------|
| 8000 | Agent | LangGraph AI Agent 主服务 | ✅ 使用中 |
| 8001 | Strapi MCP | 知识库和 FAQ 服务 | ✅ 使用中 |
| 8002 | Order MCP | 订单查询服务 | ✅ 使用中 |
| 8003 | Aftersale MCP | 售后服务 | ✅ 使用中 |
| 8004 | Product MCP | 商品服务 | ✅ 使用中 |
| 8005-8009 | - | 预留给其他 MCP 服务 | 🔄 预留 |
| 8010-8099 | - | 预留给应用服务扩展 | 🔄 预留 |

### 3️⃣ 静态资源服务 (8080-8099)

用于静态文件托管、反向代理等。

| 端口 | 服务 | 说明 | 状态 |
|------|------|------|------|
| 8080 | Nginx | 静态文件服务器 (测试页面等) | ✅ 使用中 |
| 8081-8099 | - | 预留给其他静态资源服务 | 🔄 预留 |

### 4️⃣ 内部通信 (9000+)

**注意**：此区间端口仅用于容器内部通信，不对外暴露。

| 服务 | 内部端口 | 说明 |
|------|----------|------|
| PostgreSQL | 5432 | 仅容器内部访问 |
| Redis | 6379 | 仅容器内部访问 |

## 🔧 访问地址

### 生产/开发环境

```bash
# Chatwoot 客服平台
http://localhost:3000

# Nginx 静态文件 (测试页面)
http://localhost:8080/test-chat.html

# Agent API
http://localhost:8000

# MCP Services
http://localhost:8001  # Strapi MCP
http://localhost:8002  # Order MCP
http://localhost:8003  # Aftersale MCP
http://localhost:8004  # Product MCP
```

## 📝 添加新服务时的规则

1. **按功能选择端口区间**
   - 前端界面 → 3000-3999
   - 后端 API → 8000-8999
   - 静态资源/代理 → 8080-8099

2. **查看预留端口**
   - 优先使用预留端口范围内的空闲端口
   - 避免跨区间分配

3. **更新文档**
   - 添加新服务后更新本文档
   - 标注端口用途和服务说明

4. **保持连续性**
   - 相关服务尽量使用连续的端口
   - 便于记忆和管理

## 🔍 端口冲突排查

如果遇到端口冲突：

```bash
# 检查端口占用
lsof -i :<端口>
netstat -tulpn | grep <端口>

# Docker 容器查看
docker ps
docker-compose ps
```

## 📌 注意事项

- ⚠️ **不要使用 3000-3999 范围以外的端口作为前端服务**
- ⚠️ **MCP 服务必须使用 8000-8999 范围**
- ⚠️ **所有数据库端口（5432, 6379 等）仅内部访问，不要映射到宿主机**
- ✅ **添加新服务前先检查端口规划文档**