ai-portal/Docker部署说明.md

Docker 部署说明

项目概述

基于 Next.js 15 的 AI 智能体门户系统，使用 Prisma + SQLite 作为数据存储，采用 output: 'standalone' 模式构建自包含的生产镜像。

前置要求

• Docker >= 20.10
• Docker Compose >= 2.0（可选，推荐使用）

目录结构说明

├── Dockerfile          # 多阶段构建（3 阶段）
├── docker-compose.yml  # 编排配置
├── .dockerignore       # 构建上下文排除
├── .env                # 环境变量（仅开发参考）
└── prisma/
    ├── schema.prisma   # 数据库模型
    ├── seed.ts         # 种子数据脚本
    └── migrations/     # 数据库迁移文件

环境变量

变量名	说明	示例值
DATABASE_URL	SQLite 数据库文件路径	file:/app/data/dev.db
NEXTAUTH_SECRET	NextAuth JWT 加密密钥	your-secret-key
NEXTAUTH_URL	应用公网访问地址	http://your-domain.com

注意：生产环境请使用强随机字符串替换 NEXTAUTH_SECRET，可通过 openssl rand -base64 32 生成。

快速启动

方式一：使用 docker-compose（推荐）

# 1. 创建数据持久化目录
sudo mkdir -p /opt/nextapp/data

# 2. 启动服务
docker-compose up -d

# 3. 查看日志
docker-compose logs -f

方式二：手动 docker 命令

# 1. 构建镜像
docker build -t nextapp .

# 2. 创建数据目录
mkdir -p /opt/nextapp/data

# 3. 运行容器
docker run -d \
  --name nextapp \
  -p 3000:3000 \
  -e DATABASE_URL=file:/app/data/dev.db \
  -e NEXTAUTH_SECRET=your-secret-key \
  -e NEXTAUTH_URL=http://localhost:3000 \
  -v /opt/nextapp/data/dev.db:/app/data/dev.db \
  --restart unless-stopped \
  nextapp

方式三：使用 Docker Compose 带数据库初始化

若需在首次启动时自动执行数据库迁移和种子数据初始化，可使用如下 docker-compose.yml：

version: '3.8'
services:
  nextapp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=file:/app/data/dev.db
      - NEXTAUTH_SECRET=your-secret-key
      - NEXTAUTH_URL=http://localhost:3000
    volumes:
      - /opt/nextapp/data:/app/data
    command: >
      sh -c "npx prisma migrate deploy && npx prisma db seed && node server.js"
    restart: unless-stopped

Dockerfile 多阶段构建详解

阶段	基础镜像	作用
base	node:20-alpine	基础环境，设置工作目录
deps	base	安装全部 npm 依赖（含 devDependencies）
builder	base	生成 Prisma Client + next build
runner	base	最小运行时：仅复制 standalone 产物、静态文件、prisma schema，创建非 root 用户

构建产出：.next/standalone/ 目录下的自包含 Node.js 服务器（server.js），无需 next start。

数据库管理

手动执行迁移

若容器已运行，需手动执行数据库迁移：

docker exec -it nextapp sh -c "npx prisma migrate deploy"

手动执行种子数据

docker exec -it nextapp sh -c "npx prisma db seed"

初始化后可使用以下默认账号登录管理后台：

• 地址：http://localhost:3000/admin/login
• 用户名：admin
• 密码：admin123

数据持久化

SQLite 数据库文件通过 volume 挂载到宿主机，路径为 /opt/nextapp/data/dev.db。建议定期备份此文件：

cp /opt/nextapp/data/dev.db /opt/nextapp/data/backup-$(date +%Y%m%d).db

生产部署建议

反向代理（Nginx）

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

使用 HTTPS（推荐使用 certbot / acme.sh 自动申请证书）：

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

更新部署

# 拉取最新代码
git pull

# 重新构建并启动
docker-compose down
docker-compose up -d --build

# 执行数据库迁移（如有 schema 变更）
docker exec -it nextapp sh -c "npx prisma migrate deploy"

查看日志

# 实时日志
docker-compose logs -f

# 最近 100 行
docker-compose logs --tail=100

常见问题

1. 数据库文件权限问题

确保宿主机上的数据目录对容器内 nextjs 用户（UID 1001）可写：

sudo chown -R 1001:1001 /opt/nextapp/data

2. 端口冲突

修改 docker-compose.yml 中的宿主机端口映射：

ports:
  - "8080:3000"   # 将宿主机 8080 映射到容器 3000

3. 构建性能

首次构建较慢，可配置 Docker BuildKit 加速：

export DOCKER_BUILDKIT=1
docker-compose build

4. NEXTAUTH_URL 配置错误

若通过反向代理访问，NEXTAUTH_URL 需设置为公网可访问的地址（含 https），否则 NextAuth 回调会失败。

镜像优化说明

• 使用 node:20-alpine 作为基础镜像（约 120MB）
• 采用多阶段构建，最终运行时镜像仅包含必要产物
• output: 'standalone' 模式将应用代码打包为单文件 server.js
• 运行阶段使用非 root 用户 nextjs，提升安全性