# 资产管理系统后端骨架 - 技术需求 V1（Docker 全环境版）
> 执行目标：基于纯 Docker 环境构建可编译、可运行的最小化后端骨架，无宿主机依赖（无全局 Go/Protoc/Postgres/Redis 环境）
> 技术栈锁定：golang:1.26.1-alpine3.23、postgres:18.3-alpine3.23、redis:8.6.2-alpine、Docker/Docker Compose

## 一、核心调整说明
1. **基础镜像版本统一**：所有 Go 构建/运行、数据库、缓存镜像均替换为指定版本
2. **纯 Docker 环境闭环**：
   - 宿主机无依赖（无需安装 Go/Protoc/Make 等）
   - 所有构建/编译/运行操作均通过 Docker 容器完成
   - 新增 Protoc 构建容器（解决 proto 文件编译依赖）
3. **路径与权限优化**：适配 Alpine 3.23 镜像特性，调整文件权限和执行逻辑

## 二、完整目录结构（./backend/ 根）
```
./backend/
├── gateway/
│   ├── cmd/
│   │   └── main.go
│   ├── internal/
│   │   ├── config/
│   │   │   └── config.go
│   │   ├── ws/
│   │   │   ├── hub.go
│   │   │   ├── client.go
│   │   │   └── message.go
│   │   └── router/
│   │       └── router.go
│   ├── go.mod
│   └── Dockerfile
├── services/
│   └── user-svc/
│       ├── cmd/
│       │   └── main.go
│       ├── internal/
│       │   ├── config/
│       │   │   └── config.go
│       │   ├── domain/
│       │   │   └── user.go
│       │   ├── repository/
│       │   │   └── repo.go
│       │   ├── service/
│       │   │   └── service.go
│       │   └── grpcserver/
│       │       └── server.go
│       ├── proto/
│       │   └── user.proto
│       ├── migrations/
│       │   └── 001_init.sql
│       ├── go.mod
│       └── Dockerfile
├── shared/
│   ├── proto/
│   │   ├── common/
│   │   │   └── common.proto
│   │   └── generate.go
│   └── pkg/
│       ├── logger/
│       │   └── logger.go
│       ├── errors/
│       │   └── errors.go
│       ├── database/
│       │   └── postgres.go
│       └── cache/
│           └── redis.go
├── scripts/
│   ├── dev-start.sh          # 纯 Docker 启动脚本
│   ├── gen-proto.sh          # Docker 内编译 proto
│   └── docker-proto-builder/ # Protoc 编译容器配置
│       └── Dockerfile
├── docker-compose.yml        # 全服务编排（含 proto 编译、Go 构建）
├── docker-compose.dev.yml    # 开发模式编排（挂载源码、热更新）
├── Makefile                  # 封装 Docker 命令（兼容无宿主机 Make 环境）
└── README.md                 # 纯 Docker 环境使用说明
```

## 三、核心文件调整（适配指定技术栈 + 纯 Docker 环境）

### 3.1 基础镜像统一替换
所有 Dockerfile/Compose 文件中的基础镜像替换为指定版本：
- Go 构建/运行：`golang:1.26.1-alpine3.23`
- PostgreSQL：`postgres:18.3-alpine3.23`
- Redis：`redis:8.6.2-alpine`
- 基础运行镜像：`alpine:3.23`

### 3.2 ./backend/gateway/Dockerfile
```dockerfile
# 构建阶段：使用指定 Go 版本
FROM golang:1.26.1-alpine3.23 AS builder
WORKDIR /build

# 安装依赖（Alpine 3.23 适配）
RUN apk add --no-cache git ca-certificates tzdata
ENV TZ=Asia/Shanghai

# 复制共享代码和网关代码
COPY ../shared /shared
COPY . /build

# 替换模块路径并构建（关闭 CGO 适配 Alpine）
RUN go mod download
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o gateway ./cmd

# 运行阶段：轻量 Alpine
FROM alpine:3.23
RUN apk add --no-cache ca-certificates tzdata
ENV TZ=Asia/Shanghai
WORKDIR /app

# 复制构建产物
COPY --from=builder /build/gateway .
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

# 权限优化（非 root 运行）
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
RUN chown -R appuser:appgroup /app
USER appuser

EXPOSE 8080
# 优雅退出配置
STOPSIGNAL SIGTERM
CMD ["./gateway"]
```

### 3.3 ./backend/services/user-svc/Dockerfile
```dockerfile
# 构建阶段
FROM golang:1.26.1-alpine3.23 AS builder
WORKDIR /build

RUN apk add --no-cache git ca-certificates tzdata
ENV TZ=Asia/Shanghai

# 复制共享代码和用户服务代码
COPY ../../shared /shared
COPY . /build

RUN go mod download
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o user-svc ./cmd

# 运行阶段
FROM alpine:3.23
RUN apk add --no-cache ca-certificates tzdata
ENV TZ=Asia/Shanghai
WORKDIR /app

COPY --from=builder /build/user-svc .
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

# 非 root 运行
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
RUN chown -R appuser:appgroup /app
USER appuser

EXPOSE 50051
STOPSIGNAL SIGTERM
CMD ["./user-svc"]
```

### 3.4 ./backend/scripts/docker-proto-builder/Dockerfile
```dockerfile
# Protoc 编译专用容器（解决宿主机无 Protoc 依赖）
FROM golang:1.26.1-alpine3.23

# 安装 Protoc 及 Go 插件
RUN apk add --no-cache protobuf git
RUN go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.34.0
RUN go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.5.1

# 配置环境变量
ENV PATH="$PATH:/go/bin"
ENV GOPATH="/go"

WORKDIR /proto
CMD ["protoc", "--version"]
```

### 3.5 ./backend/scripts/gen-proto.sh
```bash
#!/bin/sh
# 纯 Docker 环境编译 Proto 文件（无宿主机 Protoc 依赖）
set -e

# 进入项目根目录
SCRIPT_DIR=$(cd $(dirname $0)/.. && pwd)
cd $SCRIPT_DIR

# 构建 Protoc 编译容器并执行编译
docker build -t proto-builder:latest ./scripts/docker-proto-builder/

# 运行编译容器（挂载 proto 目录）
docker run --rm \
  -v $SCRIPT_DIR/shared/proto:/proto \
  -w /proto \
  proto-builder:latest \
  sh -c "for f in */*.proto; do \
           protoc --go_out=. --go_opt=paths=source_relative \
                  --go-grpc_out=. --go-grpc_opt=paths=source_relative \
                  \$f; \
         done"

echo "✅ Proto 文件编译完成（Docker 环境）"
```

### 3.6 ./backend/docker-compose.yml
```yaml
version: '3.8'
services:
  # Proto 编译服务（一次性执行）
  proto-builder:
    build: ./scripts/docker-proto-builder/
    volumes:
      - ./shared/proto:/proto
    command: sh -c "/proto/../scripts/gen-proto.sh"
    profiles: ["proto"]

  # 网关服务
  gateway:
    build: ./gateway
    ports:
      - "8080:8080"
    environment:
      - WS_ADDR=:8080
      - REDIS_ADDR=redis:6379
    depends_on:
      - redis
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    networks:
      - backend-network

  # 用户服务
  user-svc:
    build: ./services/user-svc
    ports:
      - "50051:50051"
    environment:
      - DB_HOST=user-db
      - DB_PORT=5432
      - DB_USER=postgres
      - DB_PASSWORD=postgres
      - DB_NAME=user_db
      - GRPC_ADDR=:50051
    depends_on:
      - user-db
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    networks:
      - backend-network

  # PostgreSQL 数据库（指定版本）
  user-db:
    image: postgres:18.3-alpine3.23
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_DB=user_db
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_INITDB_ARGS=--encoding=UTF8 --lc-collate=C --lc-ctype=C
    volumes:
      - user_data:/var/lib/postgresql/data
      - ./services/user-svc/migrations:/docker-entrypoint-initdb.d
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d user_db"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - backend-network

  # Redis 缓存（指定版本）
  redis:
    image: redis:8.6.2-alpine
    ports:
      - "6379:6379"
    command: redis-server --appendonly yes --requirepass ""
    volumes:
      - redis_data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - backend-network

volumes:
  user_data:
  redis_data:

networks:
  backend-network:
    driver: bridge
```

### 3.7 ./backend/docker-compose.dev.yml（开发模式，挂载源码）
```yaml
version: '3.8'
services:
  gateway:
    build: ./gateway
    ports:
      - "8080:8080"
    environment:
      - WS_ADDR=:8080
      - REDIS_ADDR=redis:6379
    depends_on:
      - redis
    volumes:
      - ./gateway:/build
      - ./shared:/shared
    command: sh -c "go run cmd/main.go"
    restart: on-failure
    networks:
      - backend-network

  user-svc:
    build: ./services/user-svc
    ports:
      - "50051:50051"
    environment:
      - DB_HOST=user-db
      - DB_PORT=5432
      - DB_USER=postgres
      - DB_PASSWORD=postgres
      - DB_NAME=user_db
      - GRPC_ADDR=:50051
    depends_on:
      - user-db
    volumes:
      - ./services/user-svc:/build
      - ./shared:/shared
    command: sh -c "go run cmd/main.go"
    restart: on-failure
    networks:
      - backend-network

  # 复用主 Compose 的数据库/缓存服务
  user-db:
    extends:
      file: docker-compose.yml
      service: user-db

  redis:
    extends:
      file: docker-compose.yml
      service: redis

volumes:
  user_data:
  redis_data:

networks:
  backend-network:
    driver: bridge
```

### 3.8 ./backend/scripts/dev-start.sh
```bash
#!/bin/sh
set -e

# 纯 Docker 环境启动脚本（无宿主机依赖）
SCRIPT_DIR=$(cd $(dirname $0)/.. && pwd)
cd $SCRIPT_DIR

echo "======================================"
echo "  Asset Helper Backend (Docker 环境)  "
echo "======================================"

# 停止旧容器
echo "🔄 停止旧容器..."
docker-compose -f docker-compose.yml down -v 2>/dev/null || true

# 编译 Proto 文件（Docker 内执行）
echo "📝 编译 Proto 文件..."
./scripts/gen-proto.sh

# 启动开发环境
echo "🚀 启动开发容器..."
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d

# 等待服务就绪
echo "⌛ 等待服务初始化..."
sleep 10

# 检查服务状态
echo "✅ 服务状态检查："
docker-compose -f docker-compose.yml ps

# 健康检查
echo "\n📊 健康检查："
docker run --rm --network backend_backend-network curlimages/curl:8.7.1 -s http://gateway:8080/health || echo "⚠️ Gateway 服务未就绪"

# 输出访问信息
echo "\n📌 访问信息："
echo "Gateway WebSocket: ws://localhost:8080/ws"
echo "Health Check: http://localhost:8080/health"
echo "User gRPC: localhost:50051"
echo "PostgreSQL: localhost:5432 (user: postgres, pass: postgres, db: user_db)"
echo "Redis: localhost:6379"

echo "\n💡 查看日志：docker-compose -f docker-compose.yml logs -f"
echo "💡 停止服务：docker-compose -f docker-compose.yml down -v"
```

### 3.9 ./backend/Makefile（兼容无宿主机 Make 环境）
```makefile
.PHONY: dev build proto test down logs clean

# 兼容无宿主机 Make 环境：通过 Docker 执行核心操作
dev:
  @echo "启动开发环境（纯 Docker）..."
  @./scripts/dev-start.sh

build:
  @echo "构建生产镜像..."
  @docker-compose -f docker-compose.yml build

proto:
  @echo "编译 Proto 文件（Docker 内）..."
  @./scripts/gen-proto.sh

test:
  @echo "执行健康检查..."
  @docker run --rm --network backend_backend-network curlimages/curl:8.7.1 -s http://gateway:8080/health || echo "Gateway 服务未运行"

down:
  @echo "停止并清理容器..."
  @docker-compose -f docker-compose.yml -f docker-compose.dev.yml down -v

logs:
  @echo "实时查看日志..."
  @docker-compose -f docker-compose.yml -f docker-compose.dev.yml logs -f

clean: down
  @echo "清理镜像和数据卷..."
  @docker system prune -f
  @docker volume rm backend_user_data backend_redis_data 2>/dev/null || true
```

### 3.10 ./backend/README.md（纯 Docker 环境说明）
```markdown
# Asset Helper Backend
资产管理系统后端服务（纯 Docker 环境版）

## 核心特性
- 📦 全 Docker 环境：无需宿主机安装 Go/Protoc/Postgres/Redis 等依赖
- 🔒 安全配置：非 root 用户运行容器、权限最小化
- 🚀 开发/生产双模式：开发模式挂载源码，生产模式构建镜像
- 🛡️ 健康检查：自动检测服务状态，快速定位问题

## 环境要求
- Docker 20.10+
- Docker Compose 2.0+
- 无其他宿主机依赖（无需 Go/Protoc/Make/Postgres/Redis）

## 快速开始
```bash
# 进入后端目录
cd ./backend

# 启动开发环境（自动编译 Proto + 启动所有服务）
make dev

# 检查服务状态
make test

# 查看实时日志
make logs

# 停止并清理环境
make down

# 清理所有镜像/数据卷（彻底重置）
make clean
```

## 服务端口
| 服务         | 端口    | 说明                  |
|--------------|---------|-----------------------|
| gateway      | 8080    | WebSocket + HTTP 入口 |
| user-svc     | 50051   | gRPC 用户服务         |
| user-db      | 5432    | PostgreSQL 数据库     |
| redis        | 6379    | Redis 缓存            |

## 开发模式 vs 生产模式
### 开发模式（默认）
- 挂载本地源码到容器，支持实时修改
- 使用 `docker-compose.dev.yml` 扩展配置
- 自动重启 Go 服务（代码修改后需手动重启）

### 生产模式
```bash
# 构建生产镜像
make build

# 启动生产环境（无源码挂载）
docker-compose -f docker-compose.yml up -d
```

## 关键操作
### 编译 Proto 文件
```bash
make proto
```

### 健康检查
```bash
make test
# 或直接执行
curl http://localhost:8080/health
```

### 测试 WebSocket
```bash
# 安装 wscat（或使用 Docker 版）
docker run --rm -it --network backend_backend-network jmalloc/websocket-client wss://gateway:8080/ws
> {"id":"1","type":"test","service":"user","action":"health"}
```

## 目录结构
```
./backend/          # 后端服务根目录
├── gateway/        # 网关服务（WebSocket + HTTP）
├── services/       # 微服务目录（user-svc 示例）
├── shared/         # 共享代码/Proto/工具包
├── scripts/        # 自动化脚本（Docker 环境适配）
├── docker-compose.yml       # 生产环境编排
├── docker-compose.dev.yml   # 开发环境编排
└── Makefile                # 快捷命令封装
```

## 技术栈版本
- Go: 1.26.1-alpine3.23
- PostgreSQL: 18.3-alpine3.23
- Redis: 8.6.2-alpine
- Docker: 20.10+
- Docker Compose: 2.0+
```

## 四、验证标准（纯 Docker 环境）
### 4.1 执行命令
```bash
cd ./backend
make dev
```

### 4.2 预期结果
1. 容器启动：`gateway`/`user-svc`/`user-db`/`redis` 4 个容器状态为 `Up`
2. Proto 编译：无报错，`shared/proto/common/` 生成 `common.pb.go` 和 `common_grpc.pb.go`
3. 健康检查：`make test` 返回 `{"status":"ok"}`
4. 端口可访问：
   - `ws://localhost:8080/ws` 可建立 WebSocket 连接
   - `localhost:5432` 可连接 PostgreSQL
   - `localhost:6379` 可连接 Redis

### 4.3 生产环境验证
```bash
# 构建生产镜像
make build

# 启动生产环境
docker-compose up -d

# 验证无源码挂载，服务正常运行
docker-compose ps
curl http://localhost:8080/health
```

## 五、关键优化点（适配纯 Docker 环境）
1. **Protoc 编译容器化**：无需宿主机安装 Protoc，通过专用容器完成 proto 编译
2. **依赖全内置**：所有 Go 模块、系统依赖均在 Docker 内安装，无宿主机依赖
3. **权限安全**：容器内使用非 root 用户运行服务，降低安全风险
4. **健康检查**：PostgreSQL/Redis 增加健康检查，确保服务就绪后启动应用
5. **日志与重启策略**：配置合理的重启策略和日志输出，便于问题排查
6. **网络隔离**：使用自定义网络，避免端口冲突和网络安全问题

## 六、执行说明（给 Trae 的指令）
1. 确保目标机器已安装 Docker 和 Docker Compose
2. 将上述目录结构和文件完整生成到 `./backend/` 目录
3. 执行 `cd ./backend && make dev` 启动环境
4. 验证 `make test` 返回 `{"status":"ok"}` 即完成基础架构搭建
5. 后续业务逻辑开发可基于此骨架，通过挂载源码的开发模式迭代