231 lines
4.9 KiB
Markdown
231 lines
4.9 KiB
Markdown
# HTTPS 部署指南
|
|
|
|
## 问题说明
|
|
|
|
TUIKit（腾讯云音视频通话组件）使用 WebRTC 技术，根据浏览器安全策略，WebRTC 功能必须在以下环境下才能正常工作：
|
|
- HTTPS 协议
|
|
- localhost 本地环境
|
|
|
|
当前错误：`http protocol does not support the ability to capture microphone, camera and screen`
|
|
|
|
## 解决方案：配置 HTTPS
|
|
|
|
### 方案 1：使用 Let's Encrypt 免费 SSL 证书（推荐）
|
|
|
|
#### 步骤 1：安装 Certbot
|
|
|
|
**Ubuntu/Debian:**
|
|
```bash
|
|
sudo apt update
|
|
sudo apt install certbot python3-certbot-nginx
|
|
```
|
|
|
|
**CentOS/RHEL:**
|
|
```bash
|
|
sudo yum install certbot python3-certbot-nginx
|
|
```
|
|
|
|
#### 步骤 2：获取 SSL 证书
|
|
|
|
```bash
|
|
# 自动配置 Nginx
|
|
sudo certbot --nginx -d api.zzzhengyangtang.cn
|
|
|
|
# 或者手动获取证书
|
|
sudo certbot certonly --nginx -d api.zzzhengyangtang.cn
|
|
```
|
|
|
|
按照提示输入邮箱地址，同意服务条款。
|
|
|
|
#### 步骤 3：配置 Nginx
|
|
|
|
将项目根目录的 `nginx-production.conf` 文件复制到 Nginx 配置目录：
|
|
|
|
```bash
|
|
# 复制配置文件
|
|
sudo cp nginx-production.conf /etc/nginx/sites-available/admin
|
|
|
|
# 创建软链接
|
|
sudo ln -s /etc/nginx/sites-available/admin /etc/nginx/sites-enabled/
|
|
|
|
# 修改配置文件中的路径
|
|
sudo nano /etc/nginx/sites-available/admin
|
|
```
|
|
|
|
需要修改的内容：
|
|
1. 静态文件路径：`alias /path/to/your/server/public/admin;`
|
|
2. 后端 API 端口：`proxy_pass http://127.0.0.1:8000;`
|
|
|
|
#### 步骤 4：测试并重启 Nginx
|
|
|
|
```bash
|
|
# 测试配置
|
|
sudo nginx -t
|
|
|
|
# 重启 Nginx
|
|
sudo systemctl restart nginx
|
|
```
|
|
|
|
#### 步骤 5：设置证书自动续期
|
|
|
|
Let's Encrypt 证书有效期为 90 天，需要定期续期：
|
|
|
|
```bash
|
|
# 测试自动续期
|
|
sudo certbot renew --dry-run
|
|
|
|
# Certbot 会自动添加 cron 任务，也可以手动添加
|
|
sudo crontab -e
|
|
|
|
# 添加以下行（每天凌晨 2 点检查并续期）
|
|
0 2 * * * certbot renew --quiet
|
|
```
|
|
|
|
### 方案 2：使用已有的 SSL 证书
|
|
|
|
如果您已经有 SSL 证书（.crt 和 .key 文件）：
|
|
|
|
1. 将证书文件上传到服务器：
|
|
```bash
|
|
sudo mkdir -p /etc/nginx/ssl
|
|
sudo cp your-certificate.crt /etc/nginx/ssl/
|
|
sudo cp your-private-key.key /etc/nginx/ssl/
|
|
```
|
|
|
|
2. 修改 `nginx-production.conf` 中的证书路径：
|
|
```nginx
|
|
ssl_certificate /etc/nginx/ssl/your-certificate.crt;
|
|
ssl_certificate_key /etc/nginx/ssl/your-private-key.key;
|
|
```
|
|
|
|
### 方案 3：使用阿里云/腾讯云 SSL 证书
|
|
|
|
如果您的域名托管在云服务商：
|
|
|
|
1. 在云服务商控制台申请免费 SSL 证书
|
|
2. 下载 Nginx 格式的证书文件
|
|
3. 按照方案 2 的步骤配置
|
|
|
|
## 验证 HTTPS 配置
|
|
|
|
### 1. 检查证书是否正确安装
|
|
|
|
```bash
|
|
# 使用 openssl 检查
|
|
openssl s_client -connect api.zzzhengyangtang.cn:443 -servername api.zzzhengyangtang.cn
|
|
|
|
# 使用 curl 检查
|
|
curl -I https://api.zzzhengyangtang.cn/admin
|
|
```
|
|
|
|
### 2. 在浏览器中访问
|
|
|
|
访问：`https://api.zzzhengyangtang.cn/admin`
|
|
|
|
检查：
|
|
- 地址栏是否显示锁图标
|
|
- 证书是否有效
|
|
- 是否有安全警告
|
|
|
|
### 3. 测试 WebRTC 功能
|
|
|
|
打开浏览器控制台，应该看到：
|
|
```
|
|
[TUIKit] Loaded successfully
|
|
[WebRTC 警告] 不会出现（因为已经是 HTTPS）
|
|
```
|
|
|
|
## 常见问题
|
|
|
|
### Q1: 证书申请失败
|
|
|
|
**原因：** 域名 DNS 未正确解析到服务器
|
|
|
|
**解决：**
|
|
```bash
|
|
# 检查域名解析
|
|
nslookup api.zzzhengyangtang.cn
|
|
ping api.zzzhengyangtang.cn
|
|
```
|
|
|
|
确保域名 A 记录指向服务器 IP。
|
|
|
|
### Q2: Nginx 配置测试失败
|
|
|
|
**检查：**
|
|
```bash
|
|
# 查看详细错误
|
|
sudo nginx -t
|
|
|
|
# 查看 Nginx 错误日志
|
|
sudo tail -f /var/log/nginx/error.log
|
|
```
|
|
|
|
### Q3: HTTPS 访问显示 502 错误
|
|
|
|
**原因：** 后端服务未启动或端口配置错误
|
|
|
|
**解决：**
|
|
```bash
|
|
# 检查后端服务
|
|
sudo netstat -tlnp | grep 8000
|
|
|
|
# 检查防火墙
|
|
sudo ufw status
|
|
sudo firewall-cmd --list-all
|
|
```
|
|
|
|
### Q4: 证书过期
|
|
|
|
**解决：**
|
|
```bash
|
|
# 手动续期
|
|
sudo certbot renew
|
|
|
|
# 强制续期
|
|
sudo certbot renew --force-renewal
|
|
```
|
|
|
|
## 安全建议
|
|
|
|
1. **启用 HSTS**（已在配置中包含）
|
|
- 强制浏览器使用 HTTPS
|
|
- 防止中间人攻击
|
|
|
|
2. **定期更新证书**
|
|
- Let's Encrypt 证书 90 天有效期
|
|
- 设置自动续期任务
|
|
|
|
3. **配置防火墙**
|
|
```bash
|
|
# 允许 HTTPS 端口
|
|
sudo ufw allow 443/tcp
|
|
sudo ufw allow 80/tcp # 用于 HTTP 重定向和证书验证
|
|
```
|
|
|
|
4. **监控证书状态**
|
|
- 使用 SSL Labs 测试：https://www.ssllabs.com/ssltest/
|
|
- 检查证书评级和安全性
|
|
|
|
## 部署检查清单
|
|
|
|
- [ ] 域名 DNS 已正确解析
|
|
- [ ] SSL 证书已申请并安装
|
|
- [ ] Nginx 配置已更新
|
|
- [ ] 静态文件路径已修改
|
|
- [ ] API 代理端口已配置
|
|
- [ ] Nginx 配置测试通过
|
|
- [ ] Nginx 已重启
|
|
- [ ] HTTPS 访问正常
|
|
- [ ] HTTP 自动重定向到 HTTPS
|
|
- [ ] WebRTC 功能正常（无协议错误）
|
|
- [ ] 证书自动续期已配置
|
|
|
|
## 联系支持
|
|
|
|
如果遇到问题，请检查：
|
|
1. Nginx 错误日志：`/var/log/nginx/error.log`
|
|
2. 浏览器控制台错误信息
|
|
3. 服务器防火墙设置
|
|
4. 域名 DNS 解析状态
|