urbanLifeline/docs/Jitsi-Meet-Docker部署指南.md

# 🎥 Jitsi Meet Docker 部署与使用指南

## 📋 架构说明

本项目已将Jitsi Meet完整集成到Docker Compose中，包含以下4个服务：

| 服务 | 容器名 | 端口 | 说明 |
|------|--------|------|------|
| **jitsi-web** | urban-lifeline-jitsi-web | 8280 (HTTP)<br>8443 (HTTPS) | Web前端服务 |
| **jitsi-prosody** | urban-lifeline-jitsi-prosody | 5222/5347/5280 (内部) | XMPP信令服务器 |
| **jitsi-jicofo** | urban-lifeline-jitsi-jicofo | 无需暴露 | 会议控制服务 |
| **jitsi-jvb** | urban-lifeline-jitsi-jvb | 10000/udp<br>4443/tcp | 视频桥接服务 |

**数据持久化目录**：
```
F:\Project\urbanLifeline\.data\docker\jitsi\
├── web/                # Web配置
├── prosody/           # XMPP配置
├── jicofo/            # Jicofo配置
├── jvb/               # JVB配置
└── transcripts/       # 转录文件
```

---

## 🚀 快速开始

### 步骤1：启动Jitsi Meet服务

```bash
# 进入Docker Compose目录
cd F:\Project\urbanLifeline\urbanLifelineServ\.bin\docker\urbanlifeline

# 启动Jitsi Meet（仅启动jitsi相关服务）
docker-compose up -d jitsi-web jitsi-prosody jitsi-jicofo jitsi-jvb

# 查看服务状态
docker-compose ps

# 查看日志（排查问题用）
docker-compose logs -f jitsi-web
```

**预期输出**：
```
NAME                              STATUS          PORTS
urban-lifeline-jitsi-web          Up (healthy)    0.0.0.0:8280->80/tcp, 0.0.0.0:8443->443/tcp
urban-lifeline-jitsi-prosody      Up (healthy)    5222/tcp, 5347/tcp, 5280/tcp
urban-lifeline-jitsi-jicofo       Up (healthy)
urban-lifeline-jitsi-jvb          Up (healthy)    0.0.0.0:10000->10000/udp, 0.0.0.0:4443->4443/tcp
```

### 步骤2：验证Jitsi Meet运行

在浏览器打开：
- **主页**: http://localhost:8280/
- **测试房间**: http://localhost:8280/test-meeting

如果能看到Jitsi Meet界面，说明部署成功！

---

## 🔧 配置说明

### 1. JWT认证配置（已配置）

**Docker配置**（docker-compose.yml）：
```yaml
jitsi-web:
  environment:
    JWT_APP_ID: urbanLifeline                        # 应用ID
    JWT_APP_SECRET: your-secret-key-change-in-production  # JWT密钥
```

**Java后端配置**（application-dev.yml）：
```yaml
jitsi:
  app:
    id: urbanLifeline                                # 必须与Docker一致
    secret: your-secret-key-change-in-production     # 必须与Docker一致
  server:
    url: http://localhost:8280                       # Jitsi服务地址
  token:
    expiration: 7200000                              # Token有效期2小时
```

⚠️ **重要**：
- `JWT_APP_ID` 和 `JWT_APP_SECRET` 在Docker和Java后端**必须完全一致**
- 生产环境请修改 `JWT_APP_SECRET` 为强随机字符串
- 建议使用密钥管理工具（如Vault）管理密钥

### 2. 修改JWT密钥（生产环境必须）

#### 方法A：修改Docker配置
```bash
# 1. 编辑 docker-compose.yml
# 将所有 JWT_APP_SECRET 改为你的密钥
JWT_APP_SECRET: "A8sF9dK2mP5nX7qW3tY6uZ1vB4cE0hG"

# 2. 同步修改 application-dev.yml
jitsi:
  app:
    secret: "A8sF9dK2mP5nX7qW3tY6uZ1vB4cE0hG"

# 3. 重启服务
docker-compose restart jitsi-web jitsi-prosody
```

#### 方法B：使用环境变量（推荐生产环境）
```bash
# 创建 .env 文件
echo "JITSI_JWT_SECRET=your-strong-secret-key" > .env

# 修改 docker-compose.yml 使用环境变量
JWT_APP_SECRET: ${JITSI_JWT_SECRET}
```

---

## 🧪 测试JWT验证

### 1. 测试无Token访问（应被拒绝）

在浏览器打开：http://localhost:8280/test-room

**预期结果**：显示"会议需要密码"或"需要登录"

### 2. 测试带JWT Token访问（应成功）

使用你的Java后端创建会议，后端会自动生成JWT Token并返回iframe URL：

```bash
# 调用创建会议接口
POST http://localhost:8180/urban-lifeline/workcase/chat/meeting/create
Content-Type: application/json

{
  "roomId": "test-room-123",
  "workcaseId": "WC001",
  "meetingName": "测试会议",
  "maxParticipants": 10
}

# 响应包含带JWT的URL
{
  "code": 0,
  "data": {
    "meetingId": "xxx",
    "iframeUrl": "http://localhost:8280/workcase_WC001_1234567890?jwt=eyJhbGc..."
  }
}
```

在浏览器打开响应中的 `iframeUrl`，应该能正常进入会议。

---

## 📊 服务管理命令

```bash
# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f jitsi-web          # Web服务日志
docker-compose logs -f jitsi-prosody      # XMPP日志
docker-compose logs -f jitsi-jicofo       # Jicofo日志
docker-compose logs -f jitsi-jvb          # JVB日志

# 重启服务
docker-compose restart jitsi-web

# 停止服务
docker-compose stop jitsi-web jitsi-prosody jitsi-jicofo jitsi-jvb

# 删除服务（保留数据）
docker-compose down

# 删除服务和数据
docker-compose down -v
rm -rf F:\Project\urbanLifeline\.data\docker\jitsi
```

---

## 🔍 常见问题排查

### 问题1：服务启动失败

**症状**：
```bash
docker-compose ps
# 显示 Exit (1) 或 Restarting
```

**解决方案**：
```bash
# 查看详细日志
docker-compose logs jitsi-web

# 检查端口占用
netstat -ano | findstr "8280"

# 删除容器重新启动
docker-compose down
docker-compose up -d jitsi-web jitsi-prosody jitsi-jicofo jitsi-jvb
```

### 问题2：JWT验证失败

**症状**：进入会议后立即被踢出，或显示"认证失败"

**原因**：JWT密钥不匹配

**解决方案**：
```bash
# 1. 检查Docker配置
docker-compose exec jitsi-prosody cat /config/prosody.cfg.lua | grep jwt

# 2. 检查Java配置
# 确保 application-dev.yml 中的 jitsi.app.secret 与Docker一致

# 3. 重启服务
docker-compose restart jitsi-prosody
```

### 问题3：视频无法连接

**症状**：音频正常，但视频黑屏或连接失败

**原因**：UDP端口10000被防火墙阻止

**解决方案**：
```bash
# Windows防火墙添加规则
netsh advfirewall firewall add rule name="Jitsi JVB UDP" dir=in action=allow protocol=UDP localport=10000

# 或关闭防火墙测试（不推荐生产环境）
```

### 问题4：健康检查失败

**症状**：
```bash
docker-compose ps
# 显示 (unhealthy)
```

**解决方案**：
```bash
# 检查健康检查端点
curl http://localhost:8280/
curl http://localhost:8888/about/health  # Jicofo
curl http://localhost:8080/about/health  # JVB

# 增加启动等待时间
# 编辑 docker-compose.yml，修改 start_period: 120s
```

---

## 🌐 公网部署（可选）

如果需要从公网访问，需要额外配置：

### 1. 配置域名和SSL

```yaml
jitsi-web:
  environment:
    PUBLIC_URL: https://your-domain.com
    ENABLE_LETSENCRYPT: 1
    LETSENCRYPT_DOMAIN: your-domain.com
    LETSENCRYPT_EMAIL: your-email@example.com
    DISABLE_HTTPS: 0
```

### 2. 配置JVB公网IP

```yaml
jitsi-jvb:
  environment:
    DOCKER_HOST_ADDRESS: your-public-ip
```

### 3. 开放防火墙端口

- **TCP 443**: HTTPS访问
- **UDP 10000**: WebRTC媒体流
- **TCP 4443**: WebRTC Fallback（可选）

---

## 🎯 集成到项目

你的Java后端已经完全配置好，可以直接使用：

### 前端Vue调用示例

```typescript
import { createVideoMeeting } from '@/api/workcase/meeting'

// 创建会议
const res = await createVideoMeeting({
  roomId: 'room-123',
  workcaseId: 'WC001',
  meetingName: '技术支持会议',
  maxParticipants: 10
})

// 在iframe中显示
const iframeUrl = res.data.iframeUrl
```

### 前端UniApp调用示例

```typescript
import { workcaseChatAPI } from '@/api/workcase'

// 创建会议
const res = await workcaseChatAPI.createVideoMeeting({
  roomId: roomId.value,
  workcaseId: workcaseId.value,
  meetingName: '工单技术支持',
  maxParticipants: 10
})

// 跳转到会议页面
uni.navigateTo({
  url: `/pages/meeting/MeetingView/MeetingView?meetingUrl=${encodeURIComponent(res.data.iframeUrl)}`
})
```

---

## 📈 性能优化（可选）

### 1. 限制CPU和内存

```yaml
jitsi-jvb:
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 2G
      reservations:
        cpus: '1'
        memory: 1G
```

### 2. 配置视频质量

编辑 `.data/docker/jitsi/web/config/config.js`：

```javascript
var config = {
    resolution: 720,
    constraints: {
        video: {
            height: { ideal: 720, max: 720, min: 180 }
        }
    }
};
```

---

## ✅ 检查清单

启动前确认：
- [x] Docker Desktop已安装并运行
- [x] 端口8280、8443、10000未被占用
- [x] application-dev.yml配置正确
- [x] JWT密钥在Docker和Java后端一致

启动后确认：
- [ ] 4个容器都是Up状态
- [ ] 访问http://localhost:8280能看到Jitsi界面
- [ ] Java后端能成功创建会议并生成JWT
- [ ] 前端能正常嵌入iframe并进入会议

---

## 🆘 获取帮助

如遇问题，收集以下信息：
1. Docker服务状态：`docker-compose ps`
2. 服务日志：`docker-compose logs jitsi-web`
3. 健康检查：`curl http://localhost:8280/`
4. Java后端日志中的JWT Token生成情况

**祝部署顺利！** 🚀