init

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

@@ -0,0 +1,109 @@
+# 服务启动方式说明
+
+## 📋 概述
+
+从现在开始，后端服务默认在**前台运行**，这样可以：
+- 直接看到服务的实时日志
+- 使用 `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 (开发模式)