gangyan/.harness/development-guide.md

# 开发构建指南

## 环境要求

| 组件 | 版本 | 位置 |
|------|------|------|
| JDK | 11 | `/usr/lib/jvm/java-11-openjdk-amd64` |
| Maven | - | 系统安装 |
| Node.js | - | 系统安装 |
| Python | 3.11 | Conda env `langchain-chat` |
| Conda | - | `/opt/software/miniconda3` |
| Docker | - | 系统安装 |

## 启动顺序

### 1. Docker 数据层

```bash
cd /opt/download/oss_files/gangyan-deploy/gangyan

# MySQL
cd mysql/mysql-8.4.4 && docker compose up -d && cd ../..

# Redis
docker start redis-server 2>/dev/null || docker run -d --name redis-server -p 6379:6379 redis:7-alpine

# Milvus（含 etcd + MinIO）
cd milvus && docker compose up -d && cd ..
```

验证：`docker ps` 确认 mysql-server、redis-server、milvus-standalone、milvus-etcd、milvus-minio 均 running。

### 2. Java 后端

```bash
# 使用现有 jar 启动
sudo bash /opt/download/oss_files/gangyan-deploy/gangyan/backend/start_local.sh

# 或手动启动
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
cd /opt/download/oss_files/gangyan-deploy/gangyan/backend
nohup java -Xms512m -Xmx2048m -Dspring.profiles.active=yj -jar chat_web_yj.jar > nohup.out 2>&1 &
```

### 3. Python RAG

```bash
source /opt/software/miniconda3/etc/profile.d/conda.sh
conda activate langchain-chat
cd /opt/download/oss_files/gangyan-deploy/gangyan/langchain-chat
export PYTHONPATH="$(pwd):$PYTHONPATH"
nohup python startup.py --all-api > langchain.log 2>&1 &

# PDF 转换微服务（可选）
bash /opt/download/oss_files/gangyan-deploy/gangyan/scripts/pdf-convert-service.sh
```

### 4. 前端

```bash
cd /opt/download/oss_files/gangyan-deploy/gangyan/chat_web_front
npm run dev
# 或后台运行
nohup npm run dev > nohup.out 2>&1 &
```

### 一键启动

```bash
bash /opt/download/oss_files/gangyan-deploy/gangyan/start_all.sh
```

## 构建

### Java 后端重新打包

修改源码后必须重新打 jar：

```bash
cd /opt/download/oss_files/gangyan-deploy/gangyan/chat_web_backend
mvn -DskipTests package
# 输出：target/chat_web_backend.jar
# 复制到 backend/ 目录
cp target/chat_web_backend.jar ../backend/chat_web_yj.jar
```

注意：`lib/` 下有两个 system scope jar（aspose-words、app-sign-sdk），打包时需确保 `includeSystemScope=true`（pom.xml 已配置）。

### 前端生产构建

```bash
cd /opt/download/oss_files/gangyan-deploy/gangyan/chat_web_front
npm run build
# 输出到 dist/ 目录
```

## 健康检查

```bash
curl -s -o /dev/null -w "Java %{http_code}\n"      http://127.0.0.1:8099/chat_web_backend/app/user
curl -s -o /dev/null -w "Langchain %{http_code}\n"  http://127.0.0.1:7861/docs
curl -s -o /dev/null -w "Frontend %{http_code}\n"   http://127.0.0.1:3000/
```

## 日志文件

| 服务 | 日志位置 |
|------|----------|
| Java 后端 | `backend/nohup.out`、`logs/spring.log`、`logs/backend.log` |
| Python RAG | `langchain-chat/langchain.log`、`logs/langchain-chat.log` |
| 前端 | `chat_web_front/nohup.out` |
| PDF 转换 | `logs/pdf-convert-service.log` |

## 运维脚本

`scripts/` 目录下提供各模块独立重启脚本：

| 脚本 | 用途 |
|------|------|
| `backend-restart.sh` | 重启 Java 后端 |
| `langchain-restart.sh` | 重启 Python RAG |
| `frontend-restart.sh` | 重启前端 |
| `mysql-restart.sh` | 重启 MySQL |
| `redis-restart.sh` | 重启 Redis |
| `milvus-restart.sh` | 重启 Milvus |
| `common-restart.sh` | 通用重启 |
| `log-trim-daemon.sh` | 日志清理 |
| `pdf-convert-service.sh` | PDF 转换服务 |
| `backend-pack.sh` | 后端打包 |

## 配置文件位置速查

```
chat_web_backend/src/main/resources/
├── application.yml              # 公共配置
├── application-yj.yml           # 当前在用（本机数据库）
├── application-dev.yml          # 开发环境（历史）
├── application-test.yml         # 测试环境
├── application-prod.yml         # 生产环境（ENC加密）
├── mapper/                      # MyBatis XML
│   ├── sys/                     # 系统表映射
│   └── gpt/                     # 业务表映射
└── ueditorConfig/               # UEditor 配置

langchain-chat/configs/
├── model_config.py              # 模型、API Key、模型路径
├── server_config.py             # 服务端口、Worker 配置
└── kb_config.py                 # 知识库、向量库、MySQL、搜索引擎

chat_web_front/
├── .env                         # 环境变量（端口、代理、上下文）
├── vite.config.ts               # Vite 配置（代理、插件）
├── tsconfig.json                # TypeScript 配置
└── tailwind.config.js           # Tailwind CSS
```