wecome-middleware/quick-start.md

# 🚀 WeCom Middleware 快速启动指南

## 📋 项目概述
这是一个企业微信与OpenClaw双向通信中间件，基于Spring Boot + Vue + Docker架构。

## 🏗️ 项目结构
```
wecom-middleware/
├── backend/          # Spring Boot后端
├── frontend/         # Vue前端
├── docker/           # Docker配置
├── scripts/          # 数据库脚本
├── docker-compose.yml # Docker Compose配置
├── build.sh          # 构建脚本
├── start.sh          # 启动脚本
└── README.md         # 项目文档
```

## ⚡ 快速启动

### 1. 环境要求
- Docker & Docker Compose
- Java 17+ (仅用于本地开发)
- Node.js 18+ (仅用于本地开发)
- Maven 3.8+ (仅用于本地开发)

### 2. 一键启动（推荐）
```bash
# 克隆项目后，进入项目目录
cd wecom-middleware

# 给脚本执行权限
chmod +x start.sh

# 一键启动
./start.sh
```

### 3. 手动启动步骤

#### 3.1 配置环境变量
```bash
# 复制环境配置模板
cp .env.example .env

# 编辑 .env 文件，配置企业微信和OpenClaw参数
vim .env
```

#### 3.2 启动服务
```bash
# 构建并启动所有服务
docker-compose up -d

# 或者分步执行
docker-compose build
docker-compose up -d
```

#### 3.3 查看服务状态
```bash
# 查看容器状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f backend
docker-compose logs -f frontend
```

## 🌐 访问地址

服务启动后，可以通过以下地址访问：

| 服务 | 地址 | 说明 |
|------|------|------|
| 前端管理界面 | http://localhost:3000 | Vue管理界面 |
| 后端API | http://localhost:8080 | Spring Boot后端 |
| 系统状态 | http://localhost:8080/api/system/status | 查看系统状态 |
| 健康检查 | http://localhost:8080/api/system/health | 健康检查接口 |
| 数据库管理 | http://localhost:8081 | Adminer数据库管理工具 |
| MySQL数据库 | localhost:3306 | 数据库服务 |
| Redis缓存 | localhost:6379 | 缓存服务 |

## 🔧 配置说明

### 企业微信配置
在 `.env` 文件中配置：
```bash
WECOM_BOT_ID=your_bot_id_here
WECOM_BOT_SECRET=your_bot_secret_here
```

### OpenClaw配置
```bash
OPENCLAW_GATEWAY_URL=ws://localhost:18789
OPENCLAW_GATEWAY_TOKEN=your_openclaw_token_here
```

### 数据库配置（默认）
```bash
MYSQL_ROOT_PASSWORD=wecom123456
MYSQL_DATABASE=wecom_middleware
MYSQL_USER=wecom
MYSQL_PASSWORD=wecom123456
REDIS_PASSWORD=redis123456
```

## 📊 系统功能

### 已实现功能
1. ✅ 完整的项目架构
2. ✅ 数据库设计（MySQL + Redis）
3. ✅ Spring Boot后端框架
4. ✅ Vue前端框架
5. ✅ Docker容器化部署
6. ✅ 双WebSocket客户端架构
7. ✅ 消息路由服务
8. ✅ REST API接口
9. ✅ 系统监控和管理界面

### 待配置功能
1. ⚙️ 企业微信Bot ID和Secret
2. ⚙️ OpenClaw网关连接配置
3. ⚙️ 生产环境配置

## 🛠️ 开发指南

### 后端开发
```bash
cd backend
mvn clean package
mvn spring-boot:run
```

### 前端开发
```bash
cd frontend
npm install
npm run dev
```

### 数据库操作
```bash
# 进入MySQL容器
docker exec -it wecom-mysql mysql -uwecom -pwecom123456 wecom_middleware

# 查看表结构
SHOW TABLES;
DESC users;
```

## 🔍 故障排除

### 常见问题

#### 1. 端口冲突
如果端口被占用，可以修改 `docker-compose.yml` 中的端口映射。

#### 2. 构建失败
```bash
# 清理并重新构建
docker-compose down -v
docker-compose build --no-cache
docker-compose up -d
```

#### 3. 数据库连接失败
```bash
# 检查MySQL服务
docker-compose logs mysql

# 重启数据库
docker-compose restart mysql
```

#### 4. WebSocket连接失败
- 检查OpenClaw网关是否运行
- 检查企业微信Bot配置是否正确
- 查看后端日志：`docker-compose logs -f backend`

### 查看日志
```bash
# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f mysql
docker-compose logs -f redis
```

## 📞 技术支持

### 系统状态检查
```bash
# 健康检查
curl http://localhost:8080/api/system/health

# 系统状态
curl http://localhost:8080/api/system/status

# 系统信息
curl http://localhost:8080/api/system/info
```

### 重启服务
```bash
# 重启所有服务
docker-compose restart

# 重启特定服务
docker-compose restart backend
docker-compose restart frontend
```

### 停止服务
```bash
# 停止并清理
docker-compose down

# 停止但保留数据
docker-compose stop
```

## 🎯 下一步

1. **配置企业微信Bot**：获取Bot ID和Secret
2. **配置OpenClaw**：确保网关服务运行
3. **测试消息路由**：发送测试消息验证双向通信
4. **生产环境部署**：配置域名、SSL证书等

---

**项目状态**: ✅ 基础架构完成，可运行测试

**最后更新**: 2026-03-09