imetting/DOCKER_README.md

# Docker部署快速开始

本目录包含完整的Docker Compose部署配置，支持一键部署iMeeting应用。

## 📋 文件说明

| 文件 | 说明 |
|------|------|
| `docker-compose.yml` | Docker Compose配置文件 |
| `.env.example` | 环境变量模板 |
| `.dockerignore` | Docker构建忽略文件 |
| `start.sh` ⭐ | 一键启动脚本（推荐） |
| `stop.sh` | 停止服务脚本 |
| `manage.sh` | 服务管理脚本 |
| `DOCKER_README.md` | 本文档 |

## 🏗️ 系统架构

```
方式一：直接访问
  用户 → http://服务器IP → iMeeting Frontend(Web) (80) → Frontend/Backend

方式二：域名访问（HTTPS）
  用户 → https://domain → 接入服务器Nginx (SSL) → iMeeting服务器 (80) → Frontend/Backend
```

**4个服务容器**：
- **Frontend**: React前端应用
- **Backend**: FastAPI后端服务
- **MySQL**: 数据库
- **Redis**: 缓存

**数据持久化**：
- `./data/` - 所有数据存储在此目录

## 🚀 快速开始

### 方式一：使用启动脚本（推荐）

```bash
# 1. 复制并配置环境变量
cp .env.example .env
vim .env  # 配置 BASE_URL、密码等

# 2. 一键启动
./start.sh
```

说明：
- 完整 Docker 一体化部署不会读取 `backend/.env`

脚本会自动完成：
- ✅ 检查Docker依赖
- ✅ 创建必要目录
- ✅ 启动所有服务
- ✅ 等待健康检查

说明：
- 后端镜像现在依赖系统级 `ffmpeg/ffprobe` 做音频预处理，已在 `backend/Dockerfile` 中安装，无需宿主机额外安装。

### 方式二：手动启动

```bash
# 1. 配置环境变量
cp .env.example .env
vim .env  # 配置主环境变量

# 2. 启动所有服务
docker-compose up -d

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

## 🌐 访问地址

启动成功后：

**直接访问（HTTP）**：
- **HTTP访问**: http://localhost 或 http://服务器IP
- **API文档**: http://localhost/docs 或 http://服务器IP/docs
- **API路径**: http://localhost/api/ 或 http://服务器IP/api/

**域名访问（HTTPS）**：
- 需要在接入服务器配置Nginx反向代理
- 参考本文“域名和 HTTPS 配置”章节
- 访问示例：https://imeeting.yourdomain.com

## ⚙️ 环境变量配置

### 必须配置项

编辑根目录 `.env` 文件，修改以下配置：

```bash
# Docker 一体化部署下，后端容器访问内置 MySQL/Redis 使用服务名
MYSQL_HOST=mysql
REDIS_HOST=redis

# 生产环境必改密码
MYSQL_ROOT_PASSWORD=change_this_password
MYSQL_PASSWORD=change_this_password
REDIS_PASSWORD=change_this_password
```

### 可选配置项

```bash
# 应用访问地址（用于生成外链，以及音频转录时给云端拉取音频文件）
# 如果使用云端音频转录，必须改成外部可访问的域名或公网地址，不能填写 localhost / 127.0.0.1 / 容器名
BASE_URL=http://localhost  # 生产环境改为: https://your-domain.com

# Nginx端口（默认80/443）
HTTP_PORT=80
HTTPS_PORT=443

# 如需调整容器对外端口
# BACKEND_PORT=8000
# HTTP_PORT=80
```

### 外接 MySQL / Redis 部署

如果使用 `./start-external.sh`，直接修改根目录 `.env` 即可，不需要 `backend/.env`：

```bash
cp .env.example .env
vim .env
```

根目录 `.env` 里需要重点配置：

- `MYSQL_HOST` / `MYSQL_PORT` / `MYSQL_USER` / `MYSQL_PASSWORD` / `MYSQL_DATABASE`
- `REDIS_HOST` / `REDIS_PORT` / `REDIS_DB` / `REDIS_PASSWORD`
- `BASE_URL`

说明：
- `start-external.sh` 会优先读取 `.env` 中的 `DB_*`；如果未设置，则自动回退到 `MYSQL_*`

### 音频预处理依赖

- Docker 部署：后端容器内已安装 `ffmpeg`
- 非 Docker 部署：请确保服务器可执行 `ffmpeg` 和 `ffprobe`

## 📦 数据目录

所有数据存储在 `./data/` 目录：

```
data/
├── mysql/       # MySQL数据库文件
├── redis/       # Redis持久化文件
├── uploads/     # 用户上传的文件（音频、图片等）
└── logs/        # 日志文件
    ├── backend/
    ├── frontend/
    └── frontend/
```

**重要提示**：
- 定期备份 `data/` 目录
- 生产环境建议挂载独立数据盘到 `./data/`

## 🔧 日常管理

### 使用管理脚本（推荐）

```bash
./manage.sh
```

交互式菜单提供以下功能：
1. 查看服务状态
2. 查看实时日志
3. 重启所有服务
4. 重启单个服务
5. 进入容器终端
6. **备份数据库**
7. 恢复数据库
8. 清理Redis缓存
9. 更新服务
10. 查看资源使用
11. 导出日志

### 常用命令

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

# 查看日志
docker-compose logs -f               # 所有服务
docker-compose logs -f frontend      # 前端Web日志
docker-compose logs -f backend       # 后端日志
tail -f data/logs/frontend/*.log     # 前端容器日志目录

# 重启服务
docker-compose restart               # 重启所有
docker-compose restart frontend      # 重启前端

# 停止服务
./stop.sh                            # 交互式停止
docker-compose down                  # 停止并删除容器
```

## 🔐 域名和HTTPS配置

iMeeting服务器本身仅提供HTTP服务。如需通过域名访问（HTTPS），需要在接入服务器配置Nginx反向代理。

### 配置接入服务器

完整配置步骤请参考本文档中的反向代理章节

**简要步骤**：
1. 在接入服务器安装Nginx
2. 使用Let's Encrypt获取SSL证书
3. 配置Nginx反向代理到iMeeting服务器IP
4. 配置DNS A记录指向接入服务器

**配置示例**：
```nginx
server {
    listen 443 ssl http2;
    server_name imeeting.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/imeeting.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/imeeting.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://iMeeting服务器IP:80;
        # ... 其他配置
    }
}
```

详见：本文档中的反向代理章节

## 🔍 故障排查

### 查看日志

```bash
# 服务日志
docker-compose logs -f

# 文件日志
tail -f data/logs/frontend/*.log
tail -f data/logs/backend/*.log
```

### 检查服务状态

```bash
docker-compose ps
```

所有服务应显示 `healthy` 状态。

### 测试连接

```bash
# 测试Nginx
curl http://localhost/health

# 测试HTTPS
curl -k https://localhost/health

# 测试API文档
curl http://localhost/docs
```

### 常见问题

| 问题 | 解决方法 |
|------|----------|
| 端口被占用 | 修改.env中的HTTP_PORT |
| 502错误 | 检查backend和frontend是否健康 |
| 数据库连接失败 | 检查根目录 `.env` 中的数据库配置；外接中间件模式确认 `MYSQL_HOST` / `DB_HOST` 是否正确 |
| 前端无法访问API | 检查VITE_API_BASE_URL配置 |
| 音频转录拉不到音频文件 | 检查 `BASE_URL` 是否为云端可访问的完整地址 |
| 如何配置HTTPS | 参考本文档中的反向代理章节 |

详见：`DOCKER_README.md` 故障排查章节

## 📊 服务组件

| 服务 | 容器名 | 内部端口 | 外部端口 | 健康检查 |
|------|--------|----------|----------|----------|
| Frontend(Web) | imeeting-frontend | 80 | 80 | ✅ |
| Backend | imeeting-backend | 8000 | 8000 | ✅ |
| MySQL | imeeting-mysql | 3306 | - | ✅ |
| Redis | imeeting-redis | 6379 | - | ✅ |

外部仅暴露Nginx的80端口（HTTP），其他服务通过内部网络通信。
如需HTTPS，请在接入服务器配置SSL。

## 🔄 更新部署

### 更新代码

```bash
# 拉取最新代码
git pull

# 重新构建
docker-compose build

# 重启服务
docker-compose up -d
```

### 仅更新前端

```bash
cd frontend
npm run build
cd ..
docker-compose build frontend
docker-compose up -d frontend
docker-compose restart frontend
```

### 仅更新后端

```bash
docker-compose build backend
docker-compose up -d backend
```

## 💾 备份与恢复

### 备份数据库

```bash
# 使用管理脚本
./manage.sh  # 选择"6) 备份数据库"

# 或手动执行
docker-compose exec mysql mysqldump -uroot -p imeeting > backup.sql
```

### 备份所有数据

```bash
# 备份data目录
tar czf imeeting_backup_$(date +%Y%m%d).tar.gz data/

# 备份配置
tar czf imeeting_config_$(date +%Y%m%d).tar.gz .env frontend/nginx.conf
```

### 恢复数据

```bash
# 恢复数据库
docker-compose exec -T mysql mysql -uroot -p imeeting < backup.sql

# 恢复data目录
tar xzf imeeting_backup_20240101.tar.gz
```

## 🛡️ 安全提示

生产环境部署前，请务必：

1. ✅ **修改所有默认密码**
   - MYSQL_ROOT_PASSWORD
   - MYSQL_PASSWORD
   - REDIS_PASSWORD

2. ✅ **配置真实SSL证书**
   - 使用Let's Encrypt或商业证书
   - 不要使用自签名证书

3. ✅ **设置文件权限**
   ```bash
   chmod 600 .env
   确保接入层反向代理证书文件权限正确
   ```

4. ✅ **启用防火墙**
   ```bash
   ufw allow 80/tcp
   ufw allow 443/tcp
   ufw enable
   ```

5. ✅ **定期备份数据**
   - 设置自动备份脚本
   - 异地备份

6. ✅ **监控日志**
   - 定期检查错误日志
   - 设置日志轮转

## 📚 更多信息

详细的部署说明、配置选项、性能优化等，请查看：

- **部署说明**: [DOCKER_README.md](DOCKER_README.md)
- **前端代理配置**: [frontend/nginx.conf](frontend/nginx.conf)

## 🆘 获取帮助

如遇问题：

1. 查看日志：`docker-compose logs -f`
2. 查看健康状态：`docker-compose ps`
3. 查看详细文档：`DOCKER_README.md`
4. 提交Issue到项目仓库

## 📞 快速命令参考

```bash
# 启动
./start.sh                    # 一键启动（推荐）
docker-compose up -d          # 启动所有服务

# 管理
./manage.sh                   # 管理菜单（推荐）
docker-compose ps             # 查看状态
docker-compose logs -f        # 查看日志
docker-compose restart        # 重启服务

# 停止
./stop.sh                     # 停止服务（推荐）
docker-compose down           # 停止并删除容器

# 备份
./manage.sh                   # 选择备份功能
tar czf backup.tar.gz data/   # 备份所有数据

# 更新
git pull && docker-compose build && docker-compose up -d
```

---

**祝您使用愉快！** 🎉