3f4165fe78
核心实现：搭建 Monorepo 架构，完成 shared 共享包、gateway、user-service 基础框架开发 技术落地：严格匹配指定技术栈版本，完成 Docker、gRPC、FastAPI、PostgreSQL、Redis 等配置，实现服务间基础连通 配套文件：生成 Makefile、环境变量模板、数据库 / 脚本初始化文件及启动验证文档 架构定位：仅搭建基础架构骨架，无任何业务逻辑、业务规则及业务相关字段，为后续业务开发提供支撑
3.3 KiB
3.3 KiB
Asset Helper Backend 启动验证步骤
本文档提供了 Asset Helper Backend 项目的本地启动和验证步骤，确保您能够在无额外环境的情况下（仅需安装Docker和Docker Compose）成功启动项目并验证其功能。
一、环境准备
1. 安装 Docker
- Windows: 下载并安装 Docker Desktop for Windows
- macOS: 下载并安装 Docker Desktop for Mac
- Linux: 按照 官方文档 安装 Docker
2. 安装 Docker Compose
- Docker Desktop 已包含 Docker Compose，无需单独安装
- 若使用 Linux 系统且未安装 Docker Compose，请按照 官方文档 安装
二、项目启动步骤
1. 进入项目目录
cd asset_helper_backend
2. 配置环境变量
复制环境变量模板文件为实际环境变量文件：
cp .env.example .env
3. 启动服务
使用 Makefile 命令一键启动所有服务：
make up
该命令会：
- 构建所有服务的 Docker 镜像
- 启动 PostgreSQL、Redis、user-service 和 gateway 服务
- 配置服务间的网络连接和依赖关系
三、服务验证步骤
1. 验证服务状态
检查所有服务是否正常运行：
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）连接：
- WebSocket URL:
ws://localhost:8000/ws - 发送消息，预期结果：收到服务器的回复消息
5. 验证 gRPC 服务连通性
使用 gRPC 客户端工具（如 grpcurl）测试 user-service：
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 端点是否正确
五、停止服务
当验证完成后，可以停止所有服务：
make down
六、生产环境部署
使用生产环境配置文件启动：
docker-compose -f docker-compose.prod.yml up -d
通过以上步骤，您可以成功启动和验证 Asset Helper Backend 项目的所有功能。如果遇到任何问题，请参考常见问题排查部分或查看服务日志获取详细信息。