3f4165fe78
核心实现：搭建 Monorepo 架构，完成 shared 共享包、gateway、user-service 基础框架开发 技术落地：严格匹配指定技术栈版本，完成 Docker、gRPC、FastAPI、PostgreSQL、Redis 等配置，实现服务间基础连通 配套文件：生成 Makefile、环境变量模板、数据库 / 脚本初始化文件及启动验证文档 架构定位：仅搭建基础架构骨架，无任何业务逻辑、业务规则及业务相关字段，为后续业务开发提供支撑
105 lines
3.3 KiB
Markdown
105 lines
3.3 KiB
Markdown
# 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 项目的所有功能。如果遇到任何问题，请参考常见问题排查部分或查看服务日志获取详细信息。
|