asset_helper/技术文档/asset_helper_backend 微服务基础架构（V1）.md

asset_helper_backend 微服务基础架构（V1）

请一次性完整生成 asset_helper_backend Monorepo 微服务后端项目，严格遵循以下所有要求，确保所有文件可直接编译运行、Docker Compose 本地一键启动，无任何报错，代码风格统一、类型完整，完全适配单人+AI（Trae）的开发模式；同时需支持本机无额外环境（仅需安装Docker和Docker Compose）即可启动，且包含清晰的启动验证步骤，方便我确认项目启动效果；本项目为第一版基础架构开发，仅搭建架构骨架，不包含任何业务逻辑。

一、严格锁定技术栈版本（一字不差，不可修改）

1. Gateway: FastAPI + WebSocket（唯一对外入口，负责HTTP请求转发和WebSocket实时通信，基于Starlette框架实现异步高并发通信，支持文本与二进制消息传输）

2. 微服务内部通信: FastAPI + gRPC（高性能跨服务通信，基于HTTP/2协议，支持双向流、头部压缩和多路复用，吞吐量优于传统REST API）

3. 数据库: PostgreSQL 18.3-alpine3.23（每个微服务独立DB实例，支持数据持久化和初始化脚本执行，配置健康检查确保服务可用性）

4. 缓存/消息: Redis 8.6.2-alpine（轻量级缓存，支持高并发访问，配置健康检查）

5. 容器化: Docker + Docker Compose（实现服务隔离与快速部署，区分本地开发和生产环境配置）

6. Python: 3.13.7-alpine3.22（轻量级基础镜像，体积小巧，适合容器化部署，支持异步I/O操作）

7. 依赖管理: pyproject.toml + uv（全局统一依赖管理，启用uv workspaces，整合所有子服务依赖）

8. 开发模式: 单人+AI（Trae），Monorepo架构，微服务独立部署、可扩展

二、严格遵循目录结构（一字不差，所有文件必须生成，无遗漏）

asset_helper_backend/

├── docker-compose.yml # 本地开发配置（不变，包含所有服务及健康检查）

├── docker-compose.prod.yml # 生产环境配置（不变，无挂载、配置重启策略）

├── .env.example # 环境变量模板（包含所有必要环境变量，可直接复制为.env使用）

├── Makefile # 单人+AI通用命令入口（实现所有核心命令，可直接执行）

├── .gitignore # 避免AI提交冲突（忽略.env、虚拟环境、编译文件等）

├── pyproject.toml # 全局Python依赖规范（启用uv workspaces，统一依赖版本）

├── scripts/ # 可直接执行脚本（权限配置为可执行，无需手动修改）

│ ├── init-db.sh # 初始化数据库，为每个微服务创建独立库、用户和权限

│ └── proto-gen.sh # 编译gRPC协议文件，输出到各服务指定目录

├── shared/ # 共享核心包（纯工具、无业务逻辑，可被所有服务依赖，贴合第一版基础架构定位）

│ ├── src/shared/

│ │ ├── models/ # Pydantic基模型和SQLAlchemy基类

│ │ ├── exceptions/ # 统一异常类和异常处理器

│ │ ├── middleware/ # 通用中间件（关联ID、日志、异常处理）

│ │ ├── utils/ # 工具类（配置加载、日志、安全、gRPC/Redis客户端）

│ │ └── proto/ # gRPC协议定义文件（先创建user.proto）

│ ├── pyproject.toml # 共享包依赖配置

│ └── Dockerfile # 共享包构建配置

├── services/ # 微服务目录（单人+AI开发，可无限新增）

│ ├── gateway/ # 对外入口：HTTP + WebSocket，仅搭建基础框架，无业务逻辑处理

│ │ ├── app/

│ │ │ ├── api/ # HTTP路由（转发到gRPC服务）

│ │ │ ├── ws/ # WebSocket处理（连接管理、消息处理）

│ │ │ ├── core/ # 配置、启动、依赖注入

│ │ │ └── main.py # FastAPI实例启动（包含HTTP和WebSocket）

│ │ ├── Dockerfile # 基于python:3.13.7-alpine3.22构建，启动uvicorn

│ │ └── requirements.txt # 网关服务依赖

│ └── user-service/ # 用户微服务：纯gRPC接口，无HTTP，仅搭建基础框架，无业务逻辑

│ ├── app/

│ │ ├── api/ # gRPC服务实现（对应proto定义的所有方法）

│ │ ├── core/ # 配置（继承shared.config）

│ │ ├── db/ # 异步SQLAlchemy会话和User模型

│ │ └── main.py # gRPC服务器启动

│ ├── Dockerfile # 基于python:3.13.7-alpine3.22构建，启动gRPC服务

│ └── requirements.txt # 用户服务依赖

└── infra/ # 基础设施（不变，包含数据库、缓存、反向代理配置）

├── postgres/ # PostgreSQL相关配置（数据持久化、初始化）

├── redis/ # Redis相关配置（数据持久化）

└── nginx/ # Nginx反向代理配置

三、核心文件具体要求（必须完全实现，不可省略）

1. 根目录文件

（1）pyproject.toml：指定Python 3.13.7，全局依赖包含fastapi、uvicorn、grpcio、grpcio-tools、pydantic、sqlalchemy、asyncpg、redis、python-dotenv、loguru；开发依赖包含ruff、pytest、pytest-asyncio、pre-commit；启用uv workspaces，包含shared/、services/gateway/、services/user-service/。

（2）Makefile：必须实现all、build、up、down、logs、proto-gen、init-db、test、lint命令，命令可直接执行，无需手动修改。

（3）.gitignore：忽略.env、pycache、.venv、.pyc、dist/、build/、.log、docker-compose.override.yml。

（4）scripts/proto-gen.sh：自动编译shared/src/shared/proto/**/*.proto文件，输出到各服务的app/grpc_generated/目录，添加可执行权限，可直接运行。

（5）scripts/init-db.sh：为每个微服务创建独立PostgreSQL库、用户、权限，添加可执行权限，可直接运行，支持数据库初始化脚本执行。

（6）.env.example：包含ENV、DEBUG、POSTGRES_USER、POSTGRES_PASSWORD、REDIS_URL、GRPC_PORT、HTTP_PORT等必要环境变量，标注默认值。

2. shared共享包

（1）shared/pyproject.toml：名称为asset_helper_shared，依赖包含fastapi、pydantic、grpcio、sqlalchemy、asyncpg、redis、loguru。

（2）shared.models：实现BaseModel（Pydantic基类）、BaseDBModel（SQLAlchemy基类，含id、created_at、updated_at字段）。

（3）shared.exceptions：实现AppException（基类），以及NotFoundError、UnauthorizedError、ForbiddenError、BadRequestError、InternalError等具体异常，同时实现全局异常处理器（可被gateway直接使用）。

（4）shared.middleware：实现CorrelationIdMiddleware、LoggingMiddleware、ExceptionMiddleware，适配FastAPI异步请求流程。

（5）shared.utils：实现config.py（Pydantic Settings加载环境变量）、logger.py（loguru全局日志配置）、security.py（JWT生成与验证、密码哈希）、grpc_client.py（gRPC客户端基类，支持服务调用）、redis_client.py（Redis连接池配置，支持异步操作）。

（6）shared/proto/user.proto：定义UserService服务，包含GetUser、CreateUser、UpdateUser、DeleteUser、ListUsers五个接口，指定proto3版本，定义请求和响应消息结构，字段编号合理分配；仅定义基础接口模板，不包含任何业务规则和业务字段设计，贴合基础架构定位。

3. user-service（纯gRPC微服务）

（1）技术与端口：Python 3.13.7-alpine3.22，gRPC服务监听0.0.0.0:50051，独立PostgreSQL库为user_db。

（2）目录实现：app/main.py启动gRPC服务器；app/core/config.py继承shared.config；app/db/session.py实现异步SQLAlchemy会话；app/db/models.py实现User模型（继承shared.models.BaseDBModel），仅包含基础字段，无业务相关字段；app/api/user_service.py实现UserService所有gRPC方法（仅模拟基础数据库CRUD操作，无任何业务逻辑和业务规则）；app/grpc_generated/目录用于存放自动生成的gRPC代码。

（3）Dockerfile：基于python:3.13.7-alpine3.22，安装依赖、复制代码、启动gRPC服务，配置健康检查。

4. gateway（对外入口）

（1）技术与端口：FastAPI + WebSocket，HTTP服务监听0.0.0.0:8000，WebSocket端点为/ws，内部调用user-service:50051的gRPC服务。

（2）目录实现：app/main.py创建FastAPI实例，集成HTTP和WebSocket；app/core/config.py配置服务参数；app/api/v1/users.py实现用户HTTP CRUD路由（仅负责转发到gRPC服务，无任何业务逻辑处理）；app/ws/manager.py实现WebSocket连接管理器（支持多连接管理）；app/ws/handlers.py实现用户消息处理（支持文本和二进制消息，无业务相关消息处理逻辑）；app/dependencies.py实现gRPC客户端注入。

（3）Dockerfile：基于python:3.13.7-alpine3.22，安装依赖、复制代码、启动uvicorn（支持WebSocket），配置健康检查。

5. Docker Compose配置

（1）docker-compose.yml（本地）：包含postgres（18.3-alpine3.23）、redis（8.6.2-alpine）、user-service、gateway四个服务；所有服务加入asset_helper_net网络；配置服务依赖健康检查（postgres使用pg_isready检查，redis使用redis-cli ping检查）；环境变量从.env读取；配置数据持久化卷；无需本机安装Python、PostgreSQL、Redis等依赖，仅需Docker和Docker Compose即可启动；新增启动前置说明（告知需先安装Docker和Docker Compose，以及复制.env.example为.env的步骤）。

（2）docker-compose.prod.yml（生产）：无本地文件挂载；配置服务重启策略为always；仅暴露gateway:8000端口，其他服务不对外暴露端口；强化安全配置，移除开发环境冗余参数。

四、最终交付要求（必须满足，否则需重新调整）

1. 所有技术栈版本严格匹配，无任何版本偏差；

2. 目录结构与要求完全一致，无遗漏、无多余文件；

3. 执行make proto-gen可正常生成gRPC代码，无编译错误；

4. 执行make init-db可正常初始化所有微服务的独立数据库；

5. 执行make up可一键启动所有容器，所有服务健康运行，无报错；

6. 访问gateway:8000/docs可正常打开Swagger文档，查看HTTP接口；

7. gateway的WebSocket端点/ws可正常连接，支持消息收发；

8. user-service的gRPC端口50051可正常连通，gateway能正常调用其gRPC接口；

9. shared共享包可被所有服务正常导入，无导入错误；

10. 代码类型标注完整，符合Python规范，无语法错误、无冗余代码；

11. 所有脚本可直接执行，无需手动修改权限或配置；

12. 项目支持后续新增微服务，扩展灵活，不影响现有服务运行；

13. 本机无Python、PostgreSQL、Redis等环境也可正常启动，仅需安装Docker和Docker Compose，Trae需在项目根目录生成清晰的「本地启动&验证步骤文档」（命名为STARTUP_VERIFY.md）；

14. STARTUP_VERIFY.md需包含：Docker和Docker Compose安装指引（极简版）、复制.env.example为.env的操作步骤、执行make up启动服务的命令、服务启动后验证步骤（含Swagger访问、WebSocket连接、gRPC连通性的具体操作和预期结果）、常见启动报错排查方法；

15. 启动验证步骤需简单易懂，无需专业技术背景，可直接按步骤操作确认项目启动效果，确保每一步验证都有明确的操作命令和预期反馈；

16. 全程严格遵循“第一版基础架构”定位，所有代码仅包含架构层、工具层实现，不涉及任何业务逻辑、业务规则、业务字段，不添加任何与具体业务相关的代码或配置；

17. user-service的User模型仅包含基础通用字段（如id、created_at、updated_at、username、password_hash），不添加任何业务相关字段（如角色、权限、业务关联信息等），gRPC方法仅实现基础CRUD，无业务逻辑判断。

（注：文档部分内容可能由 AI 生成）