feat: improve Docker deployment and Dify API configuration

- Use environment variables for Dify API key/URL - Add host.docker.internal support in docker-compose - Add DATABASE_URL env and prisma db push to Dockerfile - Clean up test/requirement files and add deployment docs
2026-05-09 16:05:23 +08:00
parent fa84aef544
commit 2336a2bd30
11 changed files with 373 additions and 57 deletions
@@ -0,0 +1,241 @@
+# 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（推荐）
+
+```bash
+# 1. 创建数据持久化目录
+sudo mkdir -p /opt/nextapp/data
+
+# 2. 启动服务
+docker-compose up -d
+
+# 3. 查看日志
+docker-compose logs -f
+```
+
+### 方式二：手动 docker 命令
+
+```bash
+# 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`：
+
+```yaml
+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`。
+
+## 数据库管理
+
+### 手动执行迁移
+
+若容器已运行，需手动执行数据库迁移：
+
+```bash
+docker exec -it nextapp sh -c "npx prisma migrate deploy"
+```
+
+### 手动执行种子数据
+
+```bash
+docker exec -it nextapp sh -c "npx prisma db seed"
+```
+
+初始化后可使用以下默认账号登录管理后台：
+- 地址：`http://localhost:3000/admin/login`
+- 用户名：`admin`
+- 密码：`admin123`
+
+### 数据持久化
+
+SQLite 数据库文件通过 volume 挂载到宿主机，路径为 `/opt/nextapp/data/dev.db`。建议定期备份此文件：
+
+```bash
+cp /opt/nextapp/data/dev.db /opt/nextapp/data/backup-$(date +%Y%m%d).db
+```
+
+## 生产部署建议
+
+### 反向代理（Nginx）
+
+```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 自动申请证书）：
+
+```nginx
+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;
+    }
+}
+```
+
+### 更新部署
+
+```bash
+# 拉取最新代码
+git pull
+
+# 重新构建并启动
+docker-compose down
+docker-compose up -d --build
+
+# 执行数据库迁移（如有 schema 变更）
+docker exec -it nextapp sh -c "npx prisma migrate deploy"
+```
+
+### 查看日志
+
+```bash
+# 实时日志
+docker-compose logs -f
+
+# 最近 100 行
+docker-compose logs --tail=100
+```
+
+## 常见问题
+
+### 1. 数据库文件权限问题
+
+确保宿主机上的数据目录对容器内 `nextjs` 用户（UID 1001）可写：
+
+```bash
+sudo chown -R 1001:1001 /opt/nextapp/data
+```
+
+### 2. 端口冲突
+
+修改 `docker-compose.yml` 中的宿主机端口映射：
+
+```yaml
+ports:
+  - "8080:3000"   # 将宿主机 8080 映射到容器 3000
+```
+
+### 3. 构建性能
+
+首次构建较慢，可配置 Docker BuildKit 加速：
+
+```bash
+export DOCKER_BUILDKIT=1
+docker-compose build
+```
+
+### 4. NEXTAUTH_URL 配置错误
+
+若通过反向代理访问，`NEXTAUTH_URL` 需设置为公网可访问的地址（含 https），否则 NextAuth 回调会失败。
+
+## 镜像优化说明
+
+- 使用 `node:20-alpine` 作为基础镜像（约 120MB）
+- 采用多阶段构建，最终运行时镜像仅包含必要产物
+- `output: 'standalone'` 模式将应用代码打包为单文件 `server.js`
+- 运行阶段使用非 root 用户 `nextjs`，提升安全性