catonline_ai/vw-agentic-rag/docs/topics/SERVICE_STARTUP_GUIDE.md

# 服务启动方式说明

## 📋 概述

从现在开始，后端服务默认在**前台运行**，这样可以：
- 直接看到服务的实时日志
- 使用 `Ctrl+C` 优雅地停止服务
- 更适合开发和调试

## 🚀 启动方式

### 1. 前台运行（默认，推荐）
```bash
# 方式1：直接使用脚本
./scripts/start_service.sh

# 方式2：使用 Makefile
make start
```

**特点：**
- ✅ 服务在当前终端运行
- ✅ 实时显示日志输出
- ✅ 使用 `Ctrl+C` 停止服务
- ✅ 适合开发和调试

### 2. 后台运行
```bash
# 方式1：直接使用脚本
./scripts/start_service.sh --background

# 方式2：使用 Makefile
make start-bg
```

**特点：**
- 🔧 服务在后台运行
- 📋 日志写入 `server.log` 文件
- 🛑 需要使用 `make stop` 或 `./scripts/stop_service.sh` 停止
- 🏭 适合生产环境

### 3. 开发模式（前台，自动重载）
```bash
# 方式1：直接使用脚本
./scripts/start_service.sh --dev

# 方式2：使用 Makefile
make dev-backend
```

**特点：**
- 🔄 代码变更时自动重载
- 💻 适合开发阶段
- ⚡ 启动速度更快

## 🛑 停止服务

```bash
# 停止服务（适用于后台模式）
make stop

# 或直接使用脚本
./scripts/stop_service.sh

# 前台模式：直接按 Ctrl+C
```

## 📊 检查服务状态

```bash
# 检查服务状态
make status

# 查看健康状况
make health

# 查看日志（后台模式）
make logs
```

## 💡 使用建议

### 开发阶段
推荐使用**前台模式**或**开发模式**：
```bash
make start      # 前台运行
# 或
make dev-backend  # 开发模式，自动重载
```

### 生产部署
推荐使用**后台模式**：
```bash
make start-bg   # 后台运行
```

### 调试问题
使用**前台模式**查看实时日志：
```bash
make start      # 可以直接看到所有输出
```

## 🔧 端口说明

- **后端服务**: http://127.0.0.1:8000
  - API文档: http://127.0.0.1:8000/docs
  - 健康检查: http://127.0.0.1:8000/health

- **前端服务**: http://localhost:3000 (开发模式)