docs: 添加 Nginx 部署指南和飞书权限说明
新增: - NGINX.md: Nginx 反向代理部署指南（含 HTTPS 配置） - FEISHU_PERMISSIONS.md: 飞书权限配置指南 修正: - README.md: 更正飞书权限（im:file → im:message + im:resource） - 添加文档链接
This commit is contained in:
饭团
113
FEISHU_PERMISSIONS.md
Normal file
113
FEISHU_PERMISSIONS.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# 飞书权限配置指南
|
||||
|
||||
## 📋 正确的权限配置
|
||||
|
||||
在飞书开放平台创建应用后，需要配置以下权限：
|
||||
|
||||
### 必选权限
|
||||
|
||||
| 权限代码 | 权限名称 | 用途 |
|
||||
|---------|---------|------|
|
||||
| `im:message` | 消息 | 发送和接收消息（包含文件消息） |
|
||||
| `im:resource` | 资源 | 访问消息中的资源（文件、图片等） |
|
||||
|
||||
### 可选权限
|
||||
|
||||
| 权限代码 | 权限名称 | 用途 |
|
||||
|---------|---------|------|
|
||||
| `contact:group:readonly` | 群组信息 | 读取群组信息 |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 常见错误
|
||||
|
||||
### ❌ 错误的权限：`im:file`
|
||||
|
||||
**问题：** 飞书权限中**没有** `im:file` 这个权限代码！
|
||||
|
||||
**正确做法：** 使用 `im:message` + `im:resource` 组合来实现文件上传下载功能。
|
||||
|
||||
### 为什么没有 `im:file`？
|
||||
|
||||
飞书的权限设计中，文件被视为一种"资源"（resource），而不是独立的权限类型。文件消息通过 `im:message` 接收，文件内容通过 `im:resource` 访问。
|
||||
|
||||
---
|
||||
|
||||
## 🔧 配置步骤
|
||||
|
||||
### 1. 进入权限管理
|
||||
|
||||
1. 访问 [飞书开放平台](https://open.feishu.cn/)
|
||||
2. 进入你的应用管理页面
|
||||
3. 点击左侧菜单"权限管理"
|
||||
|
||||
### 2. 添加权限
|
||||
|
||||
点击"添加权限"，搜索并添加：
|
||||
|
||||
1. **im:message**
|
||||
- 搜索"消息"
|
||||
- 勾选"发送消息"和"读取消息"
|
||||
- 点击"确定"
|
||||
|
||||
2. **im:resource**
|
||||
- 搜索"资源"
|
||||
- 勾选"访问消息中的资源"
|
||||
- 点击"确定"
|
||||
|
||||
### 3. 提交审核
|
||||
|
||||
部分权限需要管理员审核：
|
||||
- 点击"申请权限"
|
||||
- 填写申请理由（例如：用于文件上传功能）
|
||||
- 提交等待审核（通常很快）
|
||||
|
||||
---
|
||||
|
||||
## 📝 权限说明
|
||||
|
||||
### im:message
|
||||
|
||||
**作用：** 允许机器人发送和接收消息
|
||||
|
||||
**包含能力：**
|
||||
- 接收用户发送给机器人的消息
|
||||
- 接收群组中 @ 机器人的消息
|
||||
- 向用户发送消息
|
||||
- 向群组发送消息
|
||||
- **接收文件消息**（文件作为一种消息类型）
|
||||
|
||||
### im:resource
|
||||
|
||||
**作用：** 允许机器人访问消息中的资源
|
||||
|
||||
**包含能力：**
|
||||
- 下载消息中的文件
|
||||
- 下载消息中的图片
|
||||
- 下载消息中的视频
|
||||
- 访问其他附件资源
|
||||
|
||||
---
|
||||
|
||||
## ✅ 验证权限
|
||||
|
||||
配置完成后，在应用管理页面的"权限管理"中应该看到：
|
||||
|
||||
```
|
||||
✅ im:message - 已申请
|
||||
✅ im:resource - 已申请
|
||||
```
|
||||
|
||||
如果显示"审核中"，需要等待管理员审核通过。
|
||||
|
||||
---
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [飞书开放平台 - 权限管理](https://open.feishu.cn/document/ukTMukTMukTM/uEjNwUjLxYDM14SM2ATN)
|
||||
- [消息事件订阅](https://open.feishu.cn/document/ukTMukTMukTM/uYjNwUjL2YDM14iN2ATN)
|
||||
- [资源访问 API](https://open.feishu.cn/document/ukTMukTMukTM/uQjNwUjLyYDM14iN2ATN)
|
||||
|
||||
---
|
||||
|
||||
**🍙 祝你配置顺利！**
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**🍙 祝你部署顺利！**
|
||||
24
README.md
24
README.md
@@ -20,10 +20,14 @@
|
||||
|
||||
| 权限 | 说明 |
|
||||
|------|------|
|
||||
| `im:message` | 发送和接收消息 |
|
||||
| `im:file` | 文件上传下载 |
|
||||
| `im:message` | 发送和接收消息（包含文件消息） |
|
||||
| `im:resource` | 访问消息中的资源（文件、图片等） |
|
||||
| `contact:group:readonly` | 读取群组信息（可选） |
|
||||
|
||||
> **⚠️ 注意：** 飞书权限中没有 `im:file`，文件上传下载功能通过 `im:message` + `im:resource` 权限实现。
|
||||
>
|
||||
> 详细权限配置请查看 [`FEISHU_PERMISSIONS.md`](./FEISHU_PERMISSIONS.md)
|
||||
|
||||
### 3. 配置事件订阅
|
||||
|
||||
1. 进入"事件订阅"页面
|
||||
@@ -91,6 +95,19 @@ docker run -d \
|
||||
qiniu-feishu-bot
|
||||
```
|
||||
|
||||
### 🌐 Nginx 反向代理（生产环境推荐）
|
||||
|
||||
详细配置请查看 [`NGINX.md`](./NGINX.md)
|
||||
|
||||
```bash
|
||||
# 快速配置
|
||||
sudo nano /etc/nginx/sites-available/qiniu-bot
|
||||
# 复制 NGINX.md 中的配置
|
||||
sudo ln -s /etc/nginx/sites-available/qiniu-bot /etc/nginx/sites-enabled/
|
||||
sudo nginx -t
|
||||
sudo systemctl restart nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 配置
|
||||
@@ -176,7 +193,8 @@ qiniu-feishu-bot/
|
||||
├── start.bat # Windows 启动脚本
|
||||
├── README.md # 项目说明
|
||||
├── DEPLOY.md # 详细部署指南（Linux/macOS/Windows）
|
||||
└── WINDOWS.md # Windows 专用指南
|
||||
├── WINDOWS.md # Windows 专用指南
|
||||
└── NGINX.md # Nginx 反向代理部署指南
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user