# Asset Helper Backend 启动验证步骤

本文档提供了 Asset Helper Backend 项目的本地启动和验证步骤，确保您能够在无额外环境的情况下（仅需安装Docker和Docker Compose）成功启动项目并验证其功能。

## 一、环境准备

### 1. 安装 Docker
- **Windows**: 下载并安装 [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop)
- **macOS**: 下载并安装 [Docker Desktop for Mac](https://www.docker.com/products/docker-desktop)
- **Linux**: 按照 [官方文档](https://docs.docker.com/engine/install/) 安装 Docker

### 2. 安装 Docker Compose
- Docker Desktop 已包含 Docker Compose，无需单独安装
- 若使用 Linux 系统且未安装 Docker Compose，请按照 [官方文档](https://docs.docker.com/compose/install/) 安装

## 二、项目启动步骤

### 1. 进入项目目录
```bash
cd asset_helper_backend
```

### 2. 配置环境变量
复制环境变量模板文件为实际环境变量文件：
```bash
cp .env.example .env
```

### 3. 启动服务
使用 Makefile 命令一键启动所有服务：
```bash
make up
```

该命令会：
- 构建所有服务的 Docker 镜像
- 启动 PostgreSQL、Redis、user-service 和 gateway 服务
- 配置服务间的网络连接和依赖关系

## 三、服务验证步骤

### 1. 验证服务状态
检查所有服务是否正常运行：
```bash
docker-compose ps
```
预期结果：所有服务状态为 `Up`

### 2. 验证 Gateway HTTP 服务
- 打开浏览器访问：`http://localhost:8000`
- 预期结果：显示 `{"message": "Asset Helper Gateway is running"}`

### 3. 验证 Swagger 文档
- 打开浏览器访问：`http://localhost:8000/docs`
- 预期结果：显示 FastAPI 自动生成的 Swagger 文档，包含用户相关的 HTTP 接口

### 4. 验证 WebSocket 连接
使用 WebSocket 客户端工具（如 [WebSocket Echo Test](https://www.websocket.org/echo.html)）连接：
- WebSocket URL: `ws://localhost:8000/ws`
- 发送消息，预期结果：收到服务器的回复消息

### 5. 验证 gRPC 服务连通性
使用 gRPC 客户端工具（如 `grpcurl`）测试 user-service：
```bash
docker run --network asset_helper_backend_asset_helper_net --rm fullstorydev/grpcurl -plaintext user-service:50051 list user.UserService
```
预期结果：列出 UserService 的所有方法

## 四、常见问题排查

### 1. 服务启动失败
- **检查日志**：使用 `make logs` 查看服务日志
- **检查端口占用**：确保 8000、50051、5432、6379 端口未被占用
- **检查环境变量**：确保 .env 文件配置正确

### 2. 数据库连接失败
- 执行 `make init-db` 初始化数据库
- 检查 PostgreSQL 服务是否正常运行

### 3. gRPC 服务调用失败
- 检查 user-service 是否正常启动
- 检查服务间网络连接是否正常

### 4. WebSocket 连接失败
- 检查 gateway 服务是否正常运行
- 检查 WebSocket 端点是否正确

## 五、停止服务

当验证完成后，可以停止所有服务：
```bash
make down
```

## 六、生产环境部署

使用生产环境配置文件启动：
```bash
docker-compose -f docker-compose.prod.yml up -d
```

---

通过以上步骤，您可以成功启动和验证 Asset Helper Backend 项目的所有功能。如果遇到任何问题，请参考常见问题排查部分或查看服务日志获取详细信息。