本地项目与Docker化项目代码差异致应用故障排查

项目环境与配置 #

项目采用NodeJS（ExpressJS）后端、React前端、PostgreSQL数据库，全栈TypeScript，ORM为Prisma，使用三容器架构（后端、数据库、前端），相关配置如下：

前端Dockerfile #

FROM node:alpine

WORKDIR /usr/src/frontend

COPY package*.json ./

RUN npm install

COPY . .
EXPOSE 3000

CMD ["npm", "run", "start"]

后端Dockerfile #

FROM node:lts

WORKDIR /usr/src/backend

COPY package*.json ./

RUN npm install

COPY . .
EXPOSE 8000

RUN npx prisma generate
CMD ["npm", "run", "dev"]

后端.dockerignore #

node_modules/

docker-compose.yml #

version: '3.9'

services:
  db:
    image: 'postgres'
    ports:
      - '5432:5432'
    environment:
      POSTGRES_USER: 'postgres'
      POSTGRES_PASSWORD: 'postgres'
      POSTGRES_DB: 'hucuplant'
  server:
    build:
      context: ./backend_express 
    ports: 
      - "8000:8000"
    environment:
      DATABASE_URL: 'postgresql://postgres:postgres@localhost:5432/hucuplant?schema=public'
  client:
    build:
      context: ./frontend
    ports:
      - "3000:3000"

问题现象 #

执行docker-compose up --build后服务启动正常，但尝试注册用户时出现以下错误：

Error: 
hucuplant-server-1  | Invalid `prisma.user.findUnique()` invocation in
hucuplant-server-1  | /usr/src/backend/src/routes/Auth.ts:44:57
hucuplant-server-1  | 
hucuplant-server-1  |   41 auth.post("/register", async (req: Request, res: Response) => {
hucuplant-server-1  |   42   const { email, username, password } = req.body;
hucuplant-server-1  |   43 
hucuplant-server-1  | → 44   const usernameResult: User | null = await prisma.user.findUnique({
hucuplant-server-1  |          where: {
hucuplant-server-1  |        ?   username?: String,
hucuplant-server-1  |        ?   id?: Int,
hucuplant-server-1  |        ?   email?: String
hucuplant-server-1  |          }
hucuplant-server-1  |        })

但本地Auth.ts第44行代码是正确的查询：

auth.post("/register", async (req: Request, res: Response) => {
  const { email, username, password } = req.body;

  const usernameResult: User | null  = await prisma.user.findUnique({
    where: {
      username: username,
    },
  });

项目本地运行完全正常，容器化后出现上述问题。

原因分析 #

1. 数据库连接地址错误：Docker容器内的后端服务使用localhost无法访问PostgreSQL容器——每个容器是独立的网络实例，localhost指的是后端容器自身，而非宿主机或数据库容器。需改用docker-compose中定义的服务名db作为数据库主机地址。
2. 数据库未初始化：容器启动后PostgreSQL数据库为空，未执行Prisma迁移来创建用户表及username字段的唯一约束，导致Prisma无法识别username作为findUnique的合法查询条件。
3. 服务启动顺序问题：后端服务可能在数据库完全就绪前就启动，导致Prisma无法正常连接数据库、生成正确的客户端逻辑。

解决步骤 #

1. 修正数据库连接地址 #

修改docker-compose.yml中server服务的DATABASE_URL，将localhost替换为数据库服务名db：

server:
  # ... 其他配置
  environment:
    DATABASE_URL: 'postgresql://postgres:postgres@db:5432/hucuplant?schema=public'

2. 执行Prisma迁移初始化数据库 #

在后端服务启动时添加迁移命令，确保数据库表结构正确：

方式一：修改后端Dockerfile（适合生产环境）

FROM node:lts

WORKDIR /usr/src/backend

COPY package*.json ./

RUN npm install

COPY . .
EXPOSE 8000

RUN npx prisma generate
# 添加迁移命令，确保表结构同步
RUN npx prisma migrate deploy
CMD ["npm", "run", "dev"]

方式二：在docker-compose中配置启动命令（适合开发环境）

server:
  # ... 其他配置
  command: sh -c "npx prisma migrate deploy && npm run dev"
  depends_on:
    - db

3. 确保后端等待数据库就绪 #

为避免后端在数据库未就绪时启动，可添加等待逻辑：
比如在后端Dockerfile中安装wait-for-it工具：

RUN apt-get update && apt-get install -y wait-for-it

然后修改docker-compose的启动命令：

server:
  # ... 其他配置
  command: sh -c "wait-for-it db:5432 -- npx prisma migrate deploy && npm run dev"

4. 验证Prisma Schema正确复制 #

确认后端的.dockerignore未排除prisma/schema.prisma文件（当前配置仅排除node_modules/，符合要求），确保构建容器时Schema文件被正确复制。

完成上述修改后，重新执行docker-compose up --build启动服务，即可解决注册报错问题。

内容的提问来源于stack exchange，提问作者Jakub Sapko