Developer
213 lines
4.2 KiB
Markdown
213 lines
4.2 KiB
Markdown
# Docker 混合模式开发指南
|
|
|
|
## 概述
|
|
|
|
采用 **Docker 运行基础设施 + 本地热重载开发** 的混合模式，解决传统 Docker Compose 全量构建慢、调试不便的问题。
|
|
|
|
| 服务 | 运行方式 | 说明 |
|
|
|------|---------|------|
|
|
| es (Elasticsearch) | Docker | 基础服务，稳定不动 |
|
|
| tika (文档解析) | Docker | 基础服务，稳定不动 |
|
|
| libreoffice (文档转换) | Docker | 基础服务，稳定不动 |
|
|
| server (NestJS后端) | 本地 `npm run start:dev` | 代码改动秒级热重载 |
|
|
| web (React前端) | 本地 `npm run dev` | 代码改动秒级热重载 |
|
|
|
|
---
|
|
|
|
## 先决条件
|
|
|
|
- Docker Desktop 已安装并运行
|
|
- Node.js >= 20
|
|
- 项目代码已克隆到本地 `D:\AuraK`
|
|
|
|
---
|
|
|
|
## 启动步骤
|
|
|
|
### Step 1: 启动基础设施 (Docker)
|
|
|
|
```bash
|
|
# 进入项目目录
|
|
cd D:\AuraK
|
|
|
|
# 只启动基础设施服务 (es, tika, libreoffice)
|
|
docker compose up es tika libreoffice -d
|
|
|
|
# 确认所有服务正常运行
|
|
docker compose ps
|
|
```
|
|
|
|
预期输出：
|
|
```
|
|
NAME IMAGE STATUS
|
|
aurak-es elasticsearch:9.2.1 Up (healthy)
|
|
aurak-tika apache/tika:latest Up
|
|
aurak-libreoffice aurak-libreoffice Up
|
|
```
|
|
|
|
### Step 2: 启动后端 (本地)
|
|
|
|
```bash
|
|
# 打开新终端
|
|
cd D:\AuraK\server
|
|
|
|
# 确认 .env 中 Docker 服务地址为 127.0.0.1
|
|
# ELASTICSEARCH_HOST=http://127.0.0.1:9200
|
|
# TIKA_HOST=http://127.0.0.1:9998
|
|
# LIBREOFFICE_URL=http://127.0.0.1:8100
|
|
|
|
# 安装依赖（首次或依赖变更时）
|
|
npm install
|
|
|
|
# 启动开发模式（热重载）
|
|
npm run start:dev
|
|
```
|
|
|
|
后端启动成功标志：`Nest application successfully started`，监听 `http://localhost:3001`
|
|
|
|
### Step 3: 启动前端 (本地)
|
|
|
|
```bash
|
|
# 打开新终端
|
|
cd D:\AuraK\web
|
|
|
|
# 确认 .env 配置
|
|
# VITE_PORT=13001
|
|
# VITE_BACKEND_URL=http://localhost:3001
|
|
|
|
# 安装依赖（首次或依赖变更时）
|
|
npm install
|
|
|
|
# 启动开发模式（热重载）
|
|
npm run dev
|
|
```
|
|
|
|
前端启动成功标志：`Local: http://localhost:13001/`
|
|
|
|
### Step 4: 访问系统
|
|
|
|
打开浏览器访问 `http://localhost:13001`
|
|
|
|
---
|
|
|
|
## 重启场景
|
|
|
|
### 只需重启后端
|
|
```bash
|
|
# 在 server/ 终端按 Ctrl+C，然后重新运行
|
|
npm run start:dev
|
|
```
|
|
|
|
### 只需重启前端
|
|
```bash
|
|
# 在 web/ 终端按 Ctrl+C，然后重新运行
|
|
npm run dev
|
|
```
|
|
|
|
### 只需重启某个 Docker 服务
|
|
```bash
|
|
# 重启单个服务
|
|
docker compose restart es
|
|
|
|
# 重启所有 Docker 服务（不重建）
|
|
docker compose restart
|
|
```
|
|
|
|
### 完全重建 Docker 服务
|
|
```bash
|
|
# 停止并移除所有 Docker 容器
|
|
docker compose down
|
|
|
|
# 重新构建并启动
|
|
docker compose up es tika libreoffice -d
|
|
```
|
|
|
|
---
|
|
|
|
## 停止
|
|
|
|
```bash
|
|
# 停止 Docker 基础设施
|
|
cd D:\AuraK
|
|
docker compose down
|
|
|
|
# 分别停止本地进程 (Ctrl+C)
|
|
# server 终端: Ctrl+C
|
|
# web 终端: Ctrl+C
|
|
```
|
|
|
|
---
|
|
|
|
## 环境配置参考
|
|
|
|
### server/.env (后端)
|
|
```
|
|
PORT=3001
|
|
DATABASE_PATH=./data/metadata.db
|
|
ELASTICSEARCH_HOST=http://127.0.0.1:9200
|
|
TIKA_HOST=http://127.0.0.1:9998
|
|
LIBREOFFICE_URL=http://127.0.0.1:8100
|
|
JWT_SECRET=123456789
|
|
UPLOAD_FILE_PATH=./uploads
|
|
MAX_FILE_SIZE=104857600
|
|
TEMP_DIR=./temp
|
|
DEFAULT_VECTOR_DIMENSIONS=2048
|
|
MAX_CHUNK_SIZE=8191
|
|
MAX_OVERLAP_SIZE=200
|
|
MAX_MEMORY_USAGE_MB=1024
|
|
CHUNK_BATCH_SIZE=100
|
|
GC_THRESHOLD_MB=800
|
|
```
|
|
|
|
### web/.env (前端)
|
|
```
|
|
VITE_API_BASE_URL=/api
|
|
VITE_ALLOWED_HOSTS=localhost,127.0.0.1,0.0.0.0
|
|
VITE_PORT=13001
|
|
VITE_HOST=0.0.0.0
|
|
VITE_BACKEND_URL=http://localhost:3001
|
|
VITE_DEFAULT_LANGUAGE=zh
|
|
```
|
|
|
|
---
|
|
|
|
## 常见问题
|
|
|
|
### Elasticsearch 内存不足
|
|
```
|
|
ES_JAVA_OPTS 已在 docker-compose.yml 中限制为 512MB
|
|
若仍不足，可修改 docker-compose.yml:
|
|
- ES_JAVA_OPTS=-Xms256m -Xmx256m
|
|
```
|
|
|
|
### 端口冲突
|
|
```
|
|
es:9200 → 本地映射 9200
|
|
tika:9998 → 本地映射 9998
|
|
libreoffice:8100 → 本地映射 8100
|
|
server:3001 → 本地直接启动
|
|
web:13001 → 本地直接启动
|
|
```
|
|
|
|
### Docker Desktop 未运行
|
|
```bash
|
|
# 如果 docker 命令报错，请先启动 Docker Desktop
|
|
# 或确认 Docker Desktop 已开启 WSL2 集成
|
|
```
|
|
|
|
---
|
|
|
|
## 生产部署
|
|
|
|
需要全量 Docker 构建时：
|
|
```bash
|
|
# 完整构建所有服务
|
|
docker compose build
|
|
|
|
# 完整启动所有服务（包含 server/web）
|
|
docker compose up -d
|
|
```
|
|
|
|
---
|
|
|
|
**最后更新**: 2026-05-14 |