# 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