# Presence Service 脚本说明

## 脚本列表

| 脚本 | 用途 | 使用场景 |
|-----|------|---------|
| `start-all.sh` | 一键启动所有服务 | 开发环境初始化 |
| `stop-service.sh` | 停止 Presence Service | 重启服务、关闭开发环境 |
| `health-check.sh` | 检查所有服务健康状态 | 部署验证、故障排查 |
| `quick-test.sh` | 快速 API 功能测试 | 验证核心功能 |
| `rebuild-kafka.sh` | 重建 Kafka 容器 | Kafka 配置变更后 |

另外，项目根目录还有：

| 脚本 | 用途 | 使用场景 |
|-----|------|---------|
| `deploy.sh` | 完整部署管理脚本 | 生产部署、容器管理 |

---

## 快速开始

### 1️⃣ 一键启动（推荐）

```bash
./scripts/start-all.sh
```

这个脚本会：
1. ✅ 启动 Docker 容器 (PostgreSQL, Redis, Kafka)
2. ✅ 等待所有基础设施就绪
3. ✅ 初始化数据库 (Prisma)
4. ✅ 启动 Presence Service
5. ✅ 验证服务可用

### 2️⃣ 健康检查

```bash
./scripts/health-check.sh
```

**期望输出：**
```
🏥 Starting health check...

=== Database Service ===
Checking PostgreSQL ... ✓ OK
=== Cache Service ===
Checking Redis ... ✓ OK
=== Message Queue Service ===
Checking Kafka ... ✓ OK
=== Application Service ===
Checking Presence Service ... ✓ OK

======================================
Health Check Complete!
Passed: 4
Failed: 0
======================================
✓ All services are healthy!
```

### 3️⃣ 快速测试

```bash
./scripts/quick-test.sh
```

验证核心 API 功能是否正常工作。

### 4️⃣ 停止服务

```bash
./scripts/stop-service.sh
```

---

## deploy.sh 使用指南

`deploy.sh` 是一个功能完整的部署管理脚本，支持以下命令：

```bash
# 构建 Docker 镜像
./deploy.sh build
./deploy.sh build-no-cache

# 启动/停止服务
./deploy.sh start          # 启动完整环境
./deploy.sh start-deps     # 只启动依赖（开发模式）
./deploy.sh stop           # 停止所有
./deploy.sh restart        # 重启

# 监控
./deploy.sh logs           # 实时日志
./deploy.sh logs-tail      # 最近 100 行日志
./deploy.sh status         # 服务状态
./deploy.sh health         # 健康检查

# 数据库
./deploy.sh migrate        # 生产环境迁移
./deploy.sh migrate-dev    # 开发环境迁移
./deploy.sh db-push        # 推送 Schema
./deploy.sh prisma-studio  # 打开 Prisma Studio

# 开发
./deploy.sh shell          # 进入容器 Shell
./deploy.sh test           # 运行所有测试
./deploy.sh test-unit      # 单元测试
./deploy.sh test-integration # 集成测试
./deploy.sh test-e2e       # E2E 测试

# 清理
./deploy.sh clean          # 删除容器和镜像
```

---

## 服务端口

| 服务 | 开发端口 | 说明 |
|-----|---------|------|
| Presence Service | 3011 | NestJS 应用 |
| PostgreSQL | 5432 | 数据库 |
| Redis | 6379 | 缓存 |
| Kafka | 9092 | 消息队列 |
| Zookeeper | 2181 | Kafka 协调 |

---

## 手动操作

### 只启动基础设施

```bash
docker compose -f docker-compose.dev.yml up -d
```

### 只启动应用

```bash
npm run start:dev
```

### 停止所有容器

```bash
docker compose -f docker-compose.dev.yml down
```

### 清理数据

```bash
# 停止容器并删除数据卷
docker compose -f docker-compose.dev.yml down -v
```

---

## 故障排查

### PostgreSQL 连接失败

```bash
# 检查容器状态
docker ps -a | grep presence-postgres

# 查看日志
docker logs presence-postgres-dev

# 重启容器
docker compose -f docker-compose.dev.yml restart postgres
```

### Redis 连接失败

```bash
# 检查容器状态
docker ps -a | grep presence-redis

# 测试连接
docker exec presence-redis-dev redis-cli ping

# 重启容器
docker compose -f docker-compose.dev.yml restart redis
```

### Kafka 连接失败

```bash
# Kafka 启动较慢，等待 30-60 秒
docker logs presence-kafka-dev

# 检查 Zookeeper
docker exec presence-zookeeper-dev nc -z localhost 2181

# 重启 Kafka 和 Zookeeper
docker compose -f docker-compose.dev.yml restart zookeeper kafka
```

### 端口冲突

```bash
# 查找占用端口的进程
lsof -i :3011
lsof -i :5432
lsof -i :6379
lsof -i :9092

# 停止冲突进程
kill <PID>
```

---

## Windows 用户

这些脚本是 Bash 脚本，在 Windows 上需要：

1. **Git Bash** (推荐)
2. **WSL (Windows Subsystem for Linux)**
3. **Docker Desktop** (已包含 Linux 环境)

```powershell
# 使用 Git Bash 运行
bash ./scripts/start-all.sh

# 或者直接使用 npm 命令
npm run start:dev
```

---

## 完整开发流程

```bash
# 1. 克隆项目
git clone <repository-url>
cd backend/services/presence-service

# 2. 安装依赖
npm install

# 3. 复制环境配置
cp .env.example .env.development

# 4. 启动所有服务
./scripts/start-all.sh

# 5. 运行健康检查
./scripts/health-check.sh

# 6. 运行测试
npm test
npm run test:e2e

# 7. 开发完成后停止
./scripts/stop-service.sh
docker compose -f docker-compose.dev.yml down
```

---

## 相关文档

- [开发指南](../docs/DEVELOPMENT.md)
- [测试指南](../docs/TESTING.md)
- [部署指南](../docs/DEPLOYMENT.md)