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

2026-05-14 14:01:40 +08:00
parent 368eddfd75
commit 6cc65f7776
2 changed files with 215 additions and 2 deletions
@@ -0,0 +1,213 @@
+# 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
@@ -1,8 +1,8 @@
 # Git 配置指南

-## Gitee 仓库信息
+## GitTea 仓库信息

- **仓库地址**: https://gitee.com/hangshuo652/aurak.git
+- **仓库地址**: https://gittea.dev/hangshuo652/aurak.git
 - **分支**: master
 - **用户名**: hangshuo652