From 6cc65f7776c56c3f7245cda0469c0b5f74aad8a5 Mon Sep 17 00:00:00 2001 From: Developer Date: Thu, 14 May 2026 14:01:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0Docker=E6=B7=B7?= =?UTF-8?q?=E5=90=88=E6=A8=A1=E5=BC=8F=E5=BC=80=E5=8F=91=E6=8C=87=E5=8D=97?= =?UTF-8?q?=EF=BC=8C=E4=BF=AE=E6=AD=A3Git=E9=85=8D=E7=BD=AE=E5=9C=B0?= =?UTF-8?q?=E5=9D=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/docker-hybrid-guide.md | 213 ++++++++++++++++++++++++++++++++++++ docs/git-setup.md | 4 +- 2 files changed, 215 insertions(+), 2 deletions(-) create mode 100644 docs/docker-hybrid-guide.md diff --git a/docs/docker-hybrid-guide.md b/docs/docker-hybrid-guide.md new file mode 100644 index 0000000..c3f5dd3 --- /dev/null +++ b/docs/docker-hybrid-guide.md @@ -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 \ No newline at end of file diff --git a/docs/git-setup.md b/docs/git-setup.md index 1f363db..5efc613 100644 --- a/docs/git-setup.md +++ b/docs/git-setup.md @@ -1,8 +1,8 @@ # Git 配置指南 -## Gitee 仓库信息 +## GitTea 仓库信息 -- **仓库地址**: https://gitee.com/hangshuo652/aurak.git +- **仓库地址**: https://gittea.dev/hangshuo652/aurak.git - **分支**: master - **用户名**: hangshuo652