2bc5c7e0be
新增: - NGINX.md: Nginx 反向代理部署指南（含 HTTPS 配置） - FEISHU_PERMISSIONS.md: 飞书权限配置指南 修正: - README.md: 更正飞书权限（im:file → im:message + im:resource） - 添加文档链接
391 lines
7.3 KiB
Markdown
391 lines
7.3 KiB
Markdown
# Nginx 部署指南
|
||
|
||
## 📋 完整部署流程
|
||
|
||
### 1️⃣ 准备服务器
|
||
|
||
**推荐配置：**
|
||
- CPU: 1 核
|
||
- 内存：1GB
|
||
- 存储：10GB
|
||
- 系统：Ubuntu 20.04+ / CentOS 7+
|
||
|
||
### 2️⃣ 安装 Node.js
|
||
|
||
```bash
|
||
# Ubuntu/Debian
|
||
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
|
||
sudo apt-get install -y nodejs
|
||
|
||
# CentOS/RHEL
|
||
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
|
||
sudo yum install -y nodejs
|
||
|
||
# 验证
|
||
node --version # 应 >= 18
|
||
npm --version
|
||
```
|
||
|
||
### 3️⃣ 克隆项目
|
||
|
||
```bash
|
||
git clone -b master http://git.joywaygames.cn:3000/daoqi/qiniu-feishu-bot.git
|
||
cd qiniu-feishu-bot
|
||
```
|
||
|
||
### 4️⃣ 配置应用
|
||
|
||
```bash
|
||
# 复制配置文件
|
||
cp .env.example .env
|
||
cp config/qiniu-config.json.example config/qiniu-config.json
|
||
|
||
# 编辑飞书配置
|
||
nano .env
|
||
```
|
||
|
||
**`.env` 文件：**
|
||
```env
|
||
# 飞书配置（从飞书开放平台获取）
|
||
FEISHU_APP_ID=cli_xxxxxxxxxx
|
||
FEISHU_APP_SECRET=xxxxxxxxxxxxxx
|
||
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxx
|
||
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxx
|
||
|
||
# 七牛云配置
|
||
QINIU_ACCESS_KEY=xxxxxxxxxxxxxx
|
||
QINIU_SECRET_KEY=xxxxxxxxxxxxxx
|
||
QINIU_BUCKET=your-bucket-name
|
||
QINIU_REGION=z0
|
||
QINIU_DOMAIN=https://your-cdn.com
|
||
|
||
# 服务配置
|
||
PORT=3000
|
||
NODE_ENV=production
|
||
```
|
||
|
||
### 5️⃣ 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 6️⃣ 使用 PM2 管理进程
|
||
|
||
```bash
|
||
# 安装 PM2
|
||
npm install -g pm2
|
||
|
||
# 启动应用
|
||
pm2 start src/index.js --name qiniu-bot
|
||
|
||
# 设置开机自启
|
||
pm2 startup
|
||
pm2 save
|
||
|
||
# 查看状态
|
||
pm2 status
|
||
pm2 logs qiniu-bot
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 Nginx 配置
|
||
|
||
### 安装 Nginx
|
||
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo apt-get update
|
||
sudo apt-get install -y nginx
|
||
|
||
# CentOS/RHEL
|
||
sudo yum install -y nginx
|
||
sudo systemctl enable nginx
|
||
sudo systemctl start nginx
|
||
```
|
||
|
||
### 配置 Nginx
|
||
|
||
```bash
|
||
sudo nano /etc/nginx/sites-available/qiniu-bot
|
||
# 或 CentOS: sudo nano /etc/nginx/conf.d/qiniu-bot.conf
|
||
```
|
||
|
||
**配置内容：**
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name your-domain.com; # 替换为你的域名或服务器 IP
|
||
|
||
# 日志
|
||
access_log /var/log/nginx/qiniu-bot-access.log;
|
||
error_log /var/log/nginx/qiniu-bot-error.log;
|
||
|
||
# 飞书事件回调
|
||
location /feishu/event {
|
||
proxy_pass http://127.0.0.1:3000/feishu/event;
|
||
proxy_http_version 1.1;
|
||
|
||
# 保留原始请求头
|
||
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;
|
||
|
||
# 飞书签名验证需要这些头
|
||
proxy_set_header X-Feishu-Request-Timestamp $http_x_feishu_request_timestamp;
|
||
proxy_set_header X-Feishu-Request-Nonce $http_x_feishu_request_nonce;
|
||
proxy_set_header X-Feishu-Request-Signature $http_x_feishu_request_signature;
|
||
|
||
# 超时设置
|
||
proxy_connect_timeout 60s;
|
||
proxy_send_timeout 60s;
|
||
proxy_read_timeout 60s;
|
||
}
|
||
|
||
# 健康检查
|
||
location /health {
|
||
proxy_pass http://127.0.0.1:3000/health;
|
||
access_log off;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 启用配置
|
||
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo ln -s /etc/nginx/sites-available/qiniu-bot /etc/nginx/sites-enabled/
|
||
sudo nginx -t
|
||
sudo systemctl restart nginx
|
||
|
||
# CentOS/RHEL
|
||
sudo nginx -t
|
||
sudo systemctl restart nginx
|
||
```
|
||
|
||
### 配置防火墙
|
||
|
||
```bash
|
||
# Ubuntu (UFW)
|
||
sudo ufw allow 80/tcp
|
||
sudo ufw allow 443/tcp
|
||
sudo ufw reload
|
||
|
||
# CentOS (Firewall)
|
||
sudo firewall-cmd --permanent --add-service=http
|
||
sudo firewall-cmd --permanent --add-service=https
|
||
sudo firewall-cmd --reload
|
||
|
||
# 云服务器安全组
|
||
# 在阿里云/腾讯云控制台开放 80 和 443 端口
|
||
```
|
||
|
||
---
|
||
|
||
## 🔒 配置 HTTPS（推荐）
|
||
|
||
### 使用 Let's Encrypt 免费证书
|
||
|
||
```bash
|
||
# 安装 Certbot
|
||
sudo apt-get install -y certbot python3-certbot-nginx # Ubuntu
|
||
sudo yum install -y certbot python3-certbot-nginx # CentOS
|
||
|
||
# 获取证书
|
||
sudo certbot --nginx -d your-domain.com
|
||
|
||
# 自动续期
|
||
sudo crontab -e
|
||
# 添加：0 3 * * * certbot renew --quiet
|
||
```
|
||
|
||
**HTTPS 配置（Certbot 自动配置后）：**
|
||
|
||
```nginx
|
||
server {
|
||
listen 443 ssl http2;
|
||
server_name your-domain.com;
|
||
|
||
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
|
||
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
|
||
|
||
# SSL 优化
|
||
ssl_protocols TLSv1.2 TLSv1.3;
|
||
ssl_ciphers HIGH:!aNULL:!MD5;
|
||
ssl_prefer_server_ciphers on;
|
||
ssl_session_cache shared:SSL:10m;
|
||
ssl_session_timeout 10m;
|
||
|
||
location /feishu/event {
|
||
proxy_pass http://127.0.0.1:3000/feishu/event;
|
||
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;
|
||
proxy_set_header X-Feishu-Request-Timestamp $http_x_feishu_request_timestamp;
|
||
proxy_set_header X-Feishu-Request-Nonce $http_x_feishu_request_nonce;
|
||
proxy_set_header X-Feishu-Request-Signature $http_x_feishu_request_signature;
|
||
}
|
||
|
||
location /health {
|
||
proxy_pass http://127.0.0.1:3000/health;
|
||
access_log off;
|
||
}
|
||
}
|
||
|
||
# HTTP 重定向到 HTTPS
|
||
server {
|
||
listen 80;
|
||
server_name your-domain.com;
|
||
return 301 https://$server_name$request_uri;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 验证部署
|
||
|
||
### 1. 检查服务状态
|
||
|
||
```bash
|
||
# 检查 Node.js 应用
|
||
pm2 status
|
||
|
||
# 检查 Nginx
|
||
sudo systemctl status nginx
|
||
|
||
# 检查端口
|
||
sudo netstat -tlnp | grep -E ':(80|443|3000)'
|
||
```
|
||
|
||
### 2. 测试健康检查
|
||
|
||
```bash
|
||
curl http://localhost/health
|
||
curl http://your-domain.com/health
|
||
```
|
||
|
||
应返回：`{"status":"ok",...}`
|
||
|
||
### 3. 测试飞书回调
|
||
|
||
在飞书开放平台重新配置事件订阅：
|
||
- **请求地址**：`https://your-domain.com/feishu/event`
|
||
- 点击"保存"，应显示验证成功
|
||
|
||
---
|
||
|
||
## 🔧 故障排查
|
||
|
||
### Nginx 启动失败
|
||
|
||
```bash
|
||
# 检查配置
|
||
sudo nginx -t
|
||
|
||
# 查看错误日志
|
||
sudo tail -f /var/log/nginx/error.log
|
||
```
|
||
|
||
### 飞书回调失败
|
||
|
||
```bash
|
||
# 查看应用日志
|
||
pm2 logs qiniu-bot
|
||
|
||
# 查看 Nginx 日志
|
||
sudo tail -f /var/log/nginx/qiniu-bot-error.log
|
||
|
||
# 测试本地访问
|
||
curl -X POST http://localhost:3000/feishu/event \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"type":"url_verification","challenge":"test"}'
|
||
```
|
||
|
||
### 端口被占用
|
||
|
||
```bash
|
||
# 查找占用端口的进程
|
||
sudo lsof -i :80
|
||
sudo lsof -i :3000
|
||
|
||
# 停止冲突服务
|
||
sudo systemctl stop apache2 # 如果 Apache 占用 80
|
||
```
|
||
|
||
### 权限问题
|
||
|
||
```bash
|
||
# 确保 Nginx 能访问
|
||
sudo chown -R www-data:www-data /var/log/nginx/
|
||
sudo chmod 644 /etc/nginx/sites-available/qiniu-bot
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 日常维护
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
# 应用日志
|
||
pm2 logs qiniu-bot
|
||
|
||
# Nginx 日志
|
||
sudo tail -f /var/log/nginx/qiniu-bot-access.log
|
||
sudo tail -f /var/log/nginx/qiniu-bot-error.log
|
||
```
|
||
|
||
### 重启服务
|
||
|
||
```bash
|
||
# 重启应用
|
||
pm2 restart qiniu-bot
|
||
|
||
# 重启 Nginx
|
||
sudo systemctl restart nginx
|
||
|
||
# 全部重启
|
||
pm2 restart all
|
||
sudo systemctl restart nginx
|
||
```
|
||
|
||
### 更新代码
|
||
|
||
```bash
|
||
cd /path/to/qiniu-feishu-bot
|
||
git pull
|
||
npm install # 如果有新依赖
|
||
pm2 restart qiniu-bot
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 性能优化
|
||
|
||
### Nginx 优化
|
||
|
||
```nginx
|
||
# 在 http 块中添加
|
||
worker_processes auto;
|
||
worker_connections 1024;
|
||
|
||
# 启用压缩
|
||
gzip on;
|
||
gzip_types text/plain application/json;
|
||
```
|
||
|
||
### Node.js 优化
|
||
|
||
```bash
|
||
# 使用集群模式（可选）
|
||
pm2 start src/index.js --name qiniu-bot -i max
|
||
```
|
||
|
||
---
|
||
|
||
**🍙 祝你部署顺利！**
|