hangshuo652/aurak

Fork 0

Files

T

Developer 6cc65f7776 docs: 添加Docker混合模式开发指南，修正Git配置地址

2026-05-14 14:01:40 +08:00

4.2 KiB

Raw Permalink Blame History

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)

# 进入项目目录
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: 启动后端 (本地)

# 打开新终端
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: 启动前端 (本地)

# 打开新终端
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

重启场景

只需重启后端

# 在 server/ 终端按 Ctrl+C，然后重新运行
npm run start:dev

只需重启前端

# 在 web/ 终端按 Ctrl+C，然后重新运行
npm run dev

只需重启某个 Docker 服务

# 重启单个服务
docker compose restart es

# 重启所有 Docker 服务（不重建）
docker compose restart

完全重建 Docker 服务

# 停止并移除所有 Docker 容器
docker compose down

# 重新构建并启动
docker compose up es tika libreoffice -d

停止

# 停止 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 未运行

# 如果 docker 命令报错，请先启动 Docker Desktop
# 或确认 Docker Desktop 已开启 WSL2 集成

生产部署

需要全量 Docker 构建时：

# 完整构建所有服务
docker compose build

# 完整启动所有服务（包含 server/web）
docker compose up -d

最后更新: 2026-05-14

4.2 KiB Raw Permalink Blame History