docs: 添加 Nginx 部署指南和飞书权限说明
新增: - NGINX.md: Nginx 反向代理部署指南（含 HTTPS 配置） - FEISHU_PERMISSIONS.md: 飞书权限配置指南 修正: - README.md: 更正飞书权限（im:file → im:message + im:resource） - 添加文档链接
This commit is contained in:
饭团
390
NGINX.md
Normal file
390
NGINX.md
Normal file
@@ -0,0 +1,390 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**🍙 祝你部署顺利！**
|
||||
Reference in New Issue
Block a user