# iMeeting 部署文档

本文档说明当前保留的两种 Docker 部署方式：

- 全量部署：启动 `frontend`、`backend`、`mysql`、`redis`，适合单机完整部署。
- 半部署：只启动 `frontend`、`backend`，MySQL 和 Redis 使用外部已有服务。

所有脚本统一放在根目录 `scripts/` 下，运行脚本时请在项目根目录执行命令。

## 文件说明

| 文件 | 说明 |
|------|------|
| `docker-compose.yml` | Docker Compose 服务定义 |
| `.env.example` | 根目录环境变量模板 |
| `scripts/deploy-full.sh` | 全量部署脚本，包含 MySQL / Redis |
| `scripts/stop-full.sh` | 全量部署停止脚本 |
| `scripts/deploy-app-only.sh` | 半部署脚本，只启动前后端 |
| `scripts/stop-app-only.sh` | 半部署停止脚本 |
| `scripts/sql/` | 全量部署 MySQL 初始化 SQL |

## 环境要求

- Docker
- Docker Compose v2，或兼容的 `docker-compose`
- 服务器开放 `HTTP_PORT` 对应端口，默认 `80`

后端镜像已在 `backend/Dockerfile` 中安装 `ffmpeg` / `ffprobe`，Docker 部署时宿主机不需要额外安装音频预处理依赖。

## 全量部署：带中间件

全量部署会启动以下服务：

- `mysql`
- `redis`
- `backend`
- `frontend`

全量部署的 MySQL 初始化 SQL 位于 `scripts/sql/`，并通过 `docker-compose.yml` 挂载到 MySQL 容器的 `/docker-entrypoint-initdb.d`。MySQL 官方镜像只会在数据库目录为空、首次初始化时执行该目录下的 `.sql` 文件；已有 `data/mysql/` 数据时，修改 SQL 文件不会自动重放。

操作步骤：

```bash
cp .env.example .env
vim .env
./scripts/deploy-full.sh
```

建议至少修改以下配置：

```bash
MYSQL_ROOT_PASSWORD=change_this_password
MYSQL_PASSWORD=change_this_password
REDIS_PASSWORD=change_this_password
BASE_URL=https://your-domain.com
```

全量部署的数据会写入根目录 `data/`：

```text
data/
├── mysql/
├── redis/
├── uploads/
└── logs/
    ├── backend/
    └── frontend/
```

停止全量部署：

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

该脚本会交互式提供三种操作：

- 仅停止服务并保留容器和数据
- 停止并删除容器，保留数据目录
- 停止并删除 Compose 数据卷

注意：项目当前使用绑定目录 `./data/mysql` 和 `./data/redis` 持久化数据。删除 Compose 数据卷不会自动删除这些绑定目录；如需彻底清理数据，需要额外确认并删除 `data/` 下对应目录。

## 半部署：不含中间件

半部署只启动以下服务：

- `backend`
- `frontend`

MySQL 和 Redis 必须提前准备好，并在根目录 `.env` 中配置连接信息。

操作步骤：

```bash
cp .env.example .env
vim .env
./scripts/deploy-app-only.sh
```

重点配置：

```bash
MYSQL_HOST=your-mysql-host
MYSQL_PORT=3306
MYSQL_DATABASE=imeeting
MYSQL_USER=imeeting
MYSQL_PASSWORD=your-password

REDIS_HOST=your-redis-host
REDIS_PORT=6379
REDIS_PASSWORD=your-password
REDIS_DB=0

BASE_URL=https://your-domain.com
```

脚本会把 `MYSQL_*` 转换为后端容器使用的 `DB_*` 环境变量。如果 `.env` 中显式配置了 `DB_HOST`、`DB_PORT`、`DB_USER`、`DB_PASSWORD`、`DB_NAME`，则优先使用 `DB_*`。

停止半部署：

```bash
./scripts/stop-app-only.sh
```

该脚本只停止或删除 `backend` / `frontend` 容器，不会操作外部 MySQL 和 Redis。

## 访问地址

默认访问地址：

- Web：`http://localhost`
- API 文档：`http://localhost/docs`
- API 代理路径：`http://localhost/api/`

如果使用服务器 IP 或域名访问，请将 `.env` 中的 `BASE_URL` 设置为最终外部访问地址。云端语音转录需要回调或拉取音频时，`BASE_URL` 不能是 `localhost`、`127.0.0.1`、容器名或不可从外部访问的内网地址。

## 常用命令

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

# 查看所有服务日志
docker compose logs -f

# 查看前后端日志
docker compose logs -f backend frontend

# 重启服务
docker compose restart
docker compose restart backend
docker compose restart frontend
```

如果当前环境只支持旧版命令，可把 `docker compose` 替换为 `docker-compose`。

## HTTPS 和域名

项目容器默认提供 HTTP 服务。如需 HTTPS，建议在接入层 Nginx、负载均衡或网关上配置证书，再反向代理到 iMeeting 服务器的 `HTTP_PORT`。

示例：

```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-server-ip:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## 验证与排查

部署后检查：

```bash
docker compose ps
docker compose logs -f backend frontend
curl -f http://localhost/docs
```

全量部署时，`mysql`、`redis`、`backend`、`frontend` 应处于 healthy 或 running 状态。半部署时，只需要确认 `backend` 和 `frontend` 正常，外部 MySQL / Redis 的连通性由 `.env` 配置决定。

常见问题：

- `.env` 不存在：脚本会从 `.env.example` 复制一份，请修改后继续。
- 半部署缺少外部中间件配置：脚本会提示缺失的变量名。
- `BASE_URL` 配置为本地地址：本地访问可用，但云端语音服务可能无法拉取音频。
- 服务启动超时：先看 `docker compose ps`，再看 `docker compose logs -f backend frontend`。