qiniu-feishu-bot/README.md

# 七牛云上传 - 飞书独立应用

基于飞书交互卡片的七牛云文件上传工具，不依赖 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
```

**进入容器调试**
```bash
docker exec -it qiniu-bot /bin/sh
```

**检查容器健康状态**
```bash
docker inspect --format='{{.State.Health.Status}}' qiniu-bot
```

**查看资源使用**
```bash
docker stats qiniu-bot
```

**清理未使用的镜像**
```bash
docker image prune -a
```

---

#### 🌏 国内网络问题（镜像拉取超时）

**问题：** `failed to solve: DeadlineExceeded: node:18-alpine: failed to resolve source metadata`

**解决方案 1：配置 Docker 镜像加速器**

```bash
# 配置镜像加速器
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ]
}
EOF

# 重启 Docker
sudo systemctl daemon-reload
sudo systemctl restart docker

# 验证
docker info | grep "Registry Mirrors"
```

**解决方案 2：使用国内 Node.js 镜像**

修改 `Dockerfile` 第一行：
```dockerfile
# 使用阿里云镜像
FROM registry.cn-hangzhou.aliyuncs.com/library/node:18-alpine
```

**解决方案 3：手动拉取镜像**

```bash
# 先手动拉取（使用加速器）
docker pull registry.cn-hangzhou.aliyuncs.com/library/node:18-alpine

# 打标签
docker tag registry.cn-hangzhou.aliyuncs.com/library/node:18-alpine node:18-alpine

# 重新构建
docker-compose up -d --build
```

---

#### 📋 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 rename <旧名称> <新名称>` | 重命名存储桶（自动更新引用） |
| `/config set <键路径> <值>` | 修改配置项 |

**示例：**
```bash
/config add mybucket xxxxxx yyyyyy my-bucket z0 https://cdn.example.com
/config rename old-bucket new-bucket
/config remove mybucket
```

#### 📁 预设路径 (`/path`)

| 命令 | 说明 |
|------|------|
| `/path list` | 查看所有预设路径 |
| `/path add <名称> <路径>` | 添加预设路径 |
| `/path remove <名称>` | 删除预设路径 |
| `/path rename <旧名称> <新名称>` | 重命名路径（自动更新引用） |

**示例：**
```bash
/path add backup /backup/
/path rename old-path new-path
/path add ipa /ipa/gamehall_jinxian2.ipa
/path remove backup
```

#### 📤 上传配置模板 (`/profile`)

| 命令 | 说明 |
|------|------|
| `/profile list` | 查看所有上传配置模板 |
| `/profile add <名称> <存储桶> [路径]` | 添加上传配置模板 |
| `/profile remove <名称>` | 删除上传配置模板 |
| `/profile rename <旧名称> <新名称>` | 重命名配置模板 |

**示例：**
```bash
/profile add 默认上传 default
/profile add IPA 上传 default ipa
/profile rename old-profile new-profile
/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