f7e71a9bb0
- README.md: 新增详细的 Docker 部署章节 - Docker Compose 方式（推荐） - Docker 命令方式 - 多阶段构建（生产环境） - 故障排查命令 - 部署检查清单 - Dockerfile: 优化安全配置 - 使用非 root 用户运行 - 添加健康检查 - 修正端口为 3030 - 优化目录权限 - 新增 docker-compose.yml 示例文件 - 更新 .gitignore 忽略 docker-compose.override.yml
512 lines
9.9 KiB
Markdown
512 lines
9.9 KiB
Markdown
# 七牛云上传 - 飞书独立应用
|
||
|
||
基于飞书交互卡片的七牛云文件上传工具，不依赖 OpenClaw。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 创建飞书应用
|
||
|
||
1. 访问 [飞书开放平台](https://open.feishu.cn/)
|
||
2. 登录企业管理员账号
|
||
3. 点击"创建应用" → "自建应用"
|
||
4. 填写应用信息：
|
||
- 应用名称：七牛云上传助手
|
||
- 应用图标：🍙
|
||
5. 进入应用管理页面
|
||
|
||
### 2. 配置权限
|
||
|
||
在"权限管理"中添加以下权限：
|
||
|
||
```json
|
||
{
|
||
"scopes": {
|
||
"tenant": [
|
||
"im:message",
|
||
"im:message:readonly",
|
||
"im:resource",
|
||
"im:message.p2p_msg:readonly",
|
||
"cardkit:card:read",
|
||
"cardkit:card:write",
|
||
"cardkit:template:read",
|
||
"aily:file:read",
|
||
"aily:file:write"
|
||
],
|
||
"user": [
|
||
"aily:file:read",
|
||
"aily:file:write",
|
||
"im:message.p2p_msg:get_as_user"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
| 权限代码 | 说明 |
|
||
|---------|------|
|
||
| `im:message` | 发送消息 |
|
||
| `im:message:readonly` | 读取消息 |
|
||
| `im:resource` | **关键**：访问消息中的资源（文件） |
|
||
| `im:message.p2p_msg:readonly` | 读取私聊消息 |
|
||
| `cardkit:*` | 发送交互式卡片 |
|
||
| `aily:file:*` | 文件读写 |
|
||
|
||
详细权限配置请查看 [`FEISHU_SCOPES.md`](./FEISHU_SCOPES.md)
|
||
|
||
### 3. 配置事件订阅
|
||
|
||
1. 进入"事件订阅"页面
|
||
2. 选择 **"HTTP 回调"** 方式
|
||
3. 开启"启用事件订阅"
|
||
4. 填写请求地址：`https://your-domain.com/feishu/event`
|
||
5. 配置订阅事件：
|
||
- `im.message.receive_v1` - 接收消息
|
||
6. 保存后复制 Verification Token 和 Encrypt Key
|
||
|
||
> **💡 提示：** 也可以使用 WebSocket 长连接模式（不需要公网 IP），在 `.env` 中设置 `FEISHU_MODE=websocket`
|
||
|
||
### 4. 配置机器人
|
||
|
||
1. 进入"机器人"页面
|
||
2. 开启"启用机器人"
|
||
3. 配置机器人名称和头像
|
||
|
||
### 5. 安装应用
|
||
|
||
1. 进入"版本管理与发布"
|
||
2. 点击"发布应用"
|
||
3. 在飞书中搜索并添加该机器人
|
||
|
||
---
|
||
|
||
## 📦 部署
|
||
|
||
### 🐳 Docker 部署（推荐）
|
||
|
||
#### 方式 1：使用 Docker Compose（推荐）
|
||
|
||
**1. 创建 `docker-compose.yml`**
|
||
|
||
```yaml
|
||
version: '3.8'
|
||
|
||
services:
|
||
qiniu-bot:
|
||
build: .
|
||
container_name: qiniu-bot
|
||
restart: always
|
||
ports:
|
||
- "3030:3030"
|
||
env_file:
|
||
- .env
|
||
volumes:
|
||
- ./config:/app/config
|
||
- ./logs:/app/logs
|
||
networks:
|
||
- qiniu-network
|
||
|
||
networks:
|
||
qiniu-network:
|
||
driver: bridge
|
||
```
|
||
|
||
**2. 配置环境变量**
|
||
|
||
```bash
|
||
# 复制环境变量模板
|
||
cp .env.example .env
|
||
|
||
# 编辑配置（填入真实信息）
|
||
nano .env
|
||
```
|
||
|
||
**3. 启动服务**
|
||
|
||
```bash
|
||
# 构建并启动
|
||
docker-compose up -d --build
|
||
|
||
# 查看日志
|
||
docker-compose logs -f qiniu-bot
|
||
|
||
# 停止服务
|
||
docker-compose down
|
||
|
||
# 重启服务
|
||
docker-compose restart
|
||
```
|
||
|
||
---
|
||
|
||
#### 方式 2：使用 Docker 命令
|
||
|
||
**1. 准备配置文件**
|
||
|
||
```bash
|
||
# 创建配置目录
|
||
mkdir -p config
|
||
|
||
# 复制环境变量模板
|
||
cp .env.example .env
|
||
|
||
# 编辑配置
|
||
nano .env
|
||
```
|
||
|
||
**2. 构建镜像**
|
||
|
||
```bash
|
||
docker build -t qiniu-feishu-bot:latest .
|
||
```
|
||
|
||
**3. 运行容器**
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name qiniu-bot \
|
||
--restart always \
|
||
-p 3030:3030 \
|
||
--env-file .env \
|
||
-v $(pwd)/config:/app/config \
|
||
-v $(pwd)/logs:/app/logs \
|
||
qiniu-feishu-bot:latest
|
||
```
|
||
|
||
**4. 常用命令**
|
||
|
||
```bash
|
||
# 查看日志
|
||
docker logs -f qiniu-bot
|
||
|
||
# 查看容器状态
|
||
docker ps -a | grep qiniu-bot
|
||
|
||
# 重启容器
|
||
docker restart qiniu-bot
|
||
|
||
# 停止容器
|
||
docker stop qiniu-bot
|
||
|
||
# 删除容器
|
||
docker rm qiniu-bot
|
||
|
||
# 查看容器详情
|
||
docker inspect qiniu-bot
|
||
```
|
||
|
||
---
|
||
|
||
#### 方式 3：使用 Dockerfile 多阶段构建（生产环境）
|
||
|
||
**1. 创建 `.dockerignore`**
|
||
|
||
```
|
||
node_modules
|
||
npm-debug.log
|
||
.env
|
||
.env.*
|
||
.git
|
||
.gitignore
|
||
README.md
|
||
*.md
|
||
logs/
|
||
temp/
|
||
.DS_Store
|
||
```
|
||
|
||
**2. 构建优化镜像**
|
||
|
||
```bash
|
||
docker build --no-cache -t qiniu-feishu-bot:prod .
|
||
```
|
||
|
||
**3. 部署到生产环境**
|
||
|
||
```bash
|
||
# 推送到镜像仓库（可选）
|
||
docker tag qiniu-feishu-bot:prod your-registry/qiniu-bot:latest
|
||
docker push your-registry/qiniu-bot:latest
|
||
|
||
# 在服务器上拉取并运行
|
||
docker pull your-registry/qiniu-bot:latest
|
||
docker run -d \
|
||
--name qiniu-bot \
|
||
--restart always \
|
||
-p 3030:3030 \
|
||
--env-file .env \
|
||
-v /path/to/config:/app/config \
|
||
qiniu-feishu-bot:prod
|
||
```
|
||
|
||
---
|
||
|
||
#### 🔧 Docker 故障排查
|
||
|
||
```bash
|
||
# 查看容器日志
|
||
docker logs --tail 100 qiniu-bot
|
||
|
||
# 进入容器调试
|
||
docker exec -it qiniu-bot /bin/sh
|
||
|
||
# 检查容器健康状态
|
||
docker inspect --format='{{.State.Health.Status}}' qiniu-bot
|
||
|
||
# 查看资源使用
|
||
docker stats qiniu-bot
|
||
|
||
# 清理未使用的镜像
|
||
docker image prune -a
|
||
```
|
||
|
||
---
|
||
|
||
#### 📋 Docker 部署检查清单
|
||
|
||
- [ ] `.env` 文件已配置（包含飞书和七牛云密钥）
|
||
- [ ] `config/` 目录存在且有权限
|
||
- [ ] `logs/` 目录存在（用于日志持久化）
|
||
- [ ] 端口 3030 未被占用
|
||
- [ ] 防火墙已开放 3030 端口（如果需要公网访问）
|
||
- [ ] 飞书开放平台事件订阅地址配置正确
|
||
|
||
### 🐧 Linux / 🍎 macOS
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 复制环境变量
|
||
cp .env.example .env
|
||
|
||
# 编辑配置
|
||
nano .env
|
||
|
||
# 启动服务（使用 PM2）
|
||
pm2 start pm2.config.cjs
|
||
|
||
# 查看日志
|
||
pm2 logs qiniu-bot
|
||
```
|
||
|
||
### 🪟 Windows
|
||
|
||
```cmd
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 复制环境变量
|
||
copy .env.example .env
|
||
|
||
# 编辑配置
|
||
notepad .env
|
||
|
||
# 启动服务（使用 PM2）
|
||
pm2 start pm2.config.cjs
|
||
|
||
# 查看日志
|
||
pm2 logs qiniu-bot
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ 配置
|
||
|
||
### 📄 配置文件说明
|
||
|
||
项目包含以下环境变量配置文件：
|
||
|
||
| 文件 | 作用 | 包含敏感信息 | 提交到 Git |
|
||
|------|------|-------------|-----------|
|
||
| `.env.example` | 配置模板，展示所有需要的环境变量 | ❌ 否（占位符） | ✅ 应该 |
|
||
| `.env` | 当前环境配置（运行时使用） | ✅ 是 | ❌ 不应该 |
|
||
| `.env.production` | 生产环境专用配置 | ✅ 是 | ❌ 不应该 |
|
||
|
||
**快速开始：**
|
||
```bash
|
||
# 新部署时复制模板
|
||
cp .env.example .env
|
||
|
||
# 编辑配置（填入真实信息）
|
||
nano .env
|
||
```
|
||
|
||
> ⚠️ **安全提示：** `.env` 和 `.env.production` 包含敏感信息（密钥、密码等），**切勿提交到 Git**！项目已配置 `.gitignore` 自动忽略这些文件。
|
||
|
||
---
|
||
|
||
### 环境变量 (.env)
|
||
|
||
```env
|
||
# 飞书配置
|
||
FEISHU_APP_ID=cli_xxxxxxxxxx
|
||
FEISHU_APP_SECRET=xxxxxxxxxxxxxx
|
||
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxx
|
||
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxx
|
||
|
||
# 飞书事件接收模式：http (HTTP 回调) 或 websocket (WebSocket 长连接)
|
||
FEISHU_MODE=http
|
||
|
||
# 七牛云配置（可选，也可通过卡片配置）
|
||
QINIU_ACCESS_KEY=xxxxxxxxxxxxxx
|
||
QINIU_SECRET_KEY=xxxxxxxxxxxxxx
|
||
QINIU_BUCKET=your-bucket-name
|
||
QINIU_REGION=z0
|
||
QINIU_DOMAIN=https://your-cdn.com
|
||
|
||
# 服务配置
|
||
PORT=3030
|
||
NODE_ENV=production
|
||
```
|
||
|
||
### 七牛云配置 (config/qiniu-config.json)
|
||
|
||
```json
|
||
{
|
||
"buckets": {
|
||
"default": {
|
||
"accessKey": "YOUR_ACCESS_KEY",
|
||
"secretKey": "YOUR_SECRET_KEY",
|
||
"bucket": "your-bucket-name",
|
||
"region": "z0",
|
||
"domain": "https://your-cdn-domain.com"
|
||
}
|
||
},
|
||
"uploadPaths": {
|
||
"原文件名": "",
|
||
"ipa": "/ipa/gamehall_jinxianv2.ipa"
|
||
},
|
||
"uploadProfiles": {
|
||
"默认": {
|
||
"bucket": "default",
|
||
"path": ""
|
||
},
|
||
"IPA 上传": {
|
||
"bucket": "default",
|
||
"path": "ipa"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 💡 使用方式
|
||
|
||
### 常用命令
|
||
|
||
#### 📤 上传命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `/upload` 或 `/u` | 开始上传流程 |
|
||
| `/help` 或 `/qh` | 查看详细帮助 |
|
||
|
||
#### ⚙️ 存储桶配置 (`/config` 或 `/qc`)
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `/config list` | 查看所有存储桶配置 |
|
||
| `/config add <名称> <accessKey> <secretKey> <bucket> <region> <domain>` | 添加存储桶配置 |
|
||
| `/config remove <名称>` | 删除存储桶配置 |
|
||
| `/config set <键路径> <值>` | 修改配置项 |
|
||
|
||
**示例：**
|
||
```bash
|
||
/config add mybucket xxxxxx yyyyyy my-bucket z0 https://cdn.example.com
|
||
/config remove mybucket
|
||
```
|
||
|
||
#### 📁 预设路径 (`/path`)
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `/path list` | 查看所有预设路径 |
|
||
| `/path add <名称> <路径>` | 添加预设路径 |
|
||
| `/path remove <名称>` | 删除预设路径 |
|
||
|
||
**示例：**
|
||
```bash
|
||
/path add backup /backup/
|
||
/path add ipa /ipa/gamehall_jinxian2.ipa
|
||
/path remove backup
|
||
```
|
||
|
||
#### 📤 上传配置模板 (`/profile`)
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `/profile list` | 查看所有上传配置模板 |
|
||
| `/profile add <名称> <存储桶> [路径键名]` | 添加上传配置模板 |
|
||
| `/profile remove <名称>` | 删除上传配置模板 |
|
||
|
||
**示例：**
|
||
```bash
|
||
/profile add 默认上传 default
|
||
/profile add IPA 上传 default ipa
|
||
/profile remove IPA 上传
|
||
```
|
||
|
||
### 使用流程
|
||
|
||
**方式 1：选择配置 → 发送文件**
|
||
1. 发送 `/upload`
|
||
2. 选择上传配置
|
||
3. 发送文件
|
||
4. 确认上传
|
||
|
||
**方式 2：发送文件 → 选择配置**
|
||
1. 直接发送文件
|
||
2. 选择上传配置
|
||
3. 确认上传
|
||
|
||
---
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
qiniu-feishu-bot/
|
||
├── src/
|
||
│ ├── index.js # 主入口
|
||
│ ├── feishu-api.js # 飞书 API 封装
|
||
│ └── qiniu-uploader.js # 七牛云上传
|
||
├── config/
|
||
│ └── qiniu-config.json # 七牛云配置
|
||
├── .env # 环境变量
|
||
├── .env.example # 环境变量示例
|
||
├── .env.production # 生产环境配置
|
||
├── .gitignore
|
||
├── Dockerfile
|
||
├── package.json
|
||
├── pm2.config.cjs # PM2 配置
|
||
├── README.md # 项目说明
|
||
└── FEISHU_SCOPES.md # 飞书权限配置
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 故障排查
|
||
|
||
### 上传失败
|
||
|
||
1. 检查七牛云配置是否正确
|
||
2. 确认存储桶区域代码匹配
|
||
3. 检查 AccessKey/SecretKey 权限
|
||
4. 在七牛云控制台关闭存储桶的"防覆盖"设置
|
||
|
||
### 消息无响应
|
||
|
||
1. 检查事件订阅配置
|
||
2. 确认服务器可被飞书访问（HTTP 模式需要公网 IP）
|
||
3. 查看日志：`pm2 logs qiniu-bot`
|
||
4. 检查飞书应用权限是否已授权
|
||
|
||
### 文件下载失败
|
||
|
||
确保已添加 `im:resource` 权限，该权限用于访问消息中的文件资源。
|
||
|
||
---
|
||
|
||
## 📝 许可证
|
||
|
||
MIT
|