统一后端端口规划

backend/PORT_ALLOCATION.md

@@ -0,0 +1,53 @@
+# 后端端口分配规范
+
+## 规划原则
+
+- **起始端口**：`20000` 起，远离系统端口和常见开发端口（3000、5000、8000、8080 等）
+- **百位分段**：每个服务域独占一个百位段（`20xxx`），单域最多容纳 100 个端口
+- **子段细分**：每段内部再按功能分层，便于快速定位
+
+## 全局分配表
+
+| 端口段 | 用途 | 说明 |
+|--------|------|------|
+| `20000-20099` | 基础设施 | Nginx 网关、监控、日志、管理后台等 |
+| `20100-20199` | 用户服务 | `user-service`：账号/邮箱的登录、注册、用户管理 |
+| `20200-20999` | 预留扩展 | 未来新增服务域 |
+
+## 用户服务段（20100-20199）细分
+
+| 子段 | 用途 | 已分配端口 |
+|------|------|-----------|
+| `20100-20109` | 数据层 | `20101` Postgres、`20103` Redis |
+| `20110-20149` | 认证/登录类 | `20111` 账号登录、`20113` 邮箱登录 |
+| `20150-20189` | 注册/管理类 | `20112` 账号注册、`20114` 邮箱注册 |
+| `20190-20199` | 预留/调试 | 预留 |
+
+### user-service 端口明细
+
+| 服务名 | 宿主机端口 | 容器端口 | 说明 |
+|--------|-----------|---------|------|
+| user-postgres | `20101` | `5432` | PostgreSQL |
+| user-redis | `20103` | `6379` | Redis 缓存 |
+| user-login-account | `20111` | `8080` | 账号密码登录 |
+| user-register-account | `20112` | `8080` | 账号注册 |
+| user-login-email | `20113` | `8080` | 邮箱密码登录 |
+| user-register-email | `20114` | `8080` | 邮箱注册 |
+
+## 使用方式
+
+1. **新增服务前先查表**：确认目标服务域的百位段是否还有空余子段
+2. **`.env` 覆盖**：`docker-compose.yml` 中端口使用 `${VAR:-default}` 语法，本地冲突时修改 `.env`，不动 compose 文件
+3. **及时更新本文档**：分配新端口后，同步修改上表并提交
+
+## 示例 .env
+
+```bash
+# user-service/.env
+USER_POSTGRES_PORT=20101
+USER_REDIS_PORT=20103
+USER_LOGIN_ACCOUNT_PORT=20111
+USER_REGISTER_ACCOUNT_PORT=20112
+USER_LOGIN_EMAIL_PORT=20113
+USER_REGISTER_EMAIL_PORT=20114
+```

backend/services/user-service/docker-compose.yml

@@ -14,7 +14,7 @@ services:
       - SERVICE_PORT=8080
       - JWT_SECRET=${JWT_SECRET:-dev-secret-key}
     ports:
-      - "8001:8080"
+      - "${USER_LOGIN_ACCOUNT_PORT:-20111}:8080"
     depends_on:
       user-db:
         condition: service_healthy
@@ -41,7 +41,7 @@ services:
       - SERVICE_NAME=user-register-account
       - SERVICE_PORT=8080
     ports:
-      - "8002:8080"
+      - "${USER_REGISTER_ACCOUNT_PORT:-20112}:8080"
     depends_on:
       user-db:
         condition: service_healthy
@@ -69,7 +69,7 @@ services:
       - SERVICE_PORT=8080
       - JWT_SECRET=${JWT_SECRET:-dev-secret-key}
     ports:
-      - "8003:8080"
+      - "${USER_LOGIN_EMAIL_PORT:-20113}:8080"
     depends_on:
       user-db:
         condition: service_healthy
@@ -96,7 +96,7 @@ services:
       - SERVICE_NAME=user-register-email
       - SERVICE_PORT=8080
     ports:
-      - "8004:8080"
+      - "${USER_REGISTER_EMAIL_PORT:-20114}:8080"
     depends_on:
       user-db:
         condition: service_healthy
@@ -122,7 +122,7 @@ services:
       - user-postgres-data:/var/lib/postgresql/data
       - ./migrations:/docker-entrypoint-initdb.d:ro
     ports:
-      - "5432:5432"
+      - "${USER_POSTGRES_PORT:-20101}:5432"
     networks:
       - user-network
     restart: unless-stopped
@@ -138,7 +138,7 @@ services:
     volumes:
       - user-redis-data:/data
     ports:
-      - "6379:6379"
+      - "${USER_REDIS_PORT:-20103}:6379"
     networks:
       - user-network
     restart: unless-stopped