# 七牛云上传机器人 - 跨平台部署指南

支持 **Linux**、**macOS** 和 **Windows** 系统。

---

## 📋 前置要求

### 所有平台

1. **Node.js 18+**
   - 下载地址：https://nodejs.org/
   - 验证：`node --version`

2. **七牛云账号**
   - 官网：https://www.qiniu.com/
   - 需要：AccessKey、SecretKey、存储桶

3. **飞书企业管理员权限**
   - 用于创建自建应用

4. **公网访问能力**（三选一）
   - 云服务器（阿里云、腾讯云等）
   - 内网穿透工具（ngrok、cloudflared）
   - 本地网络有公网 IP

---

## 🐧 Linux 部署

### 方式 A：一键脚本（推荐）

```bash
# 1. 下载项目
git clone <repo-url> qiniu-feishu-bot
cd qiniu-feishu-bot

# 2. 运行启动脚本
chmod +x start.sh
./start.sh

# 脚本会自动：
# - 检查 Node.js
# - 创建配置文件
# - 安装依赖
# - 启动服务
```

### 方式 B：手动部署

```bash
# 1. 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 2. 安装依赖
npm install

# 3. 配置环境变量
cp .env.example .env
nano .env  # 编辑配置

# 4. 配置七牛云
cp config/qiniu-config.json.example config/qiniu-config.json
nano config/qiniu-config.json

# 5. 启动服务
npm start

# 6. 后台运行（可选）
# 使用 systemd
sudo nano /etc/systemd/system/qiniu-bot.service
```

**systemd 服务配置：**

```ini
[Unit]
Description=七牛云上传机器人
After=network.target

[Service]
Type=simple
User=admin
WorkingDirectory=/path/to/qiniu-feishu-bot
Environment=NODE_ENV=production
ExecStart=/usr/bin/node src/index.js
Restart=always

[Install]
WantedBy=multi-user.target
```

```bash
# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable qiniu-bot
sudo systemctl start qiniu-bot
sudo systemctl status qiniu-bot
```

### 方式 C：Docker 部署

```bash
# 1. 安装 Docker
curl -fsSL https://get.docker.com | sh

# 2. 构建镜像
docker build -t qiniu-feishu-bot .

# 3. 运行容器
docker run -d \
  --name qiniu-bot \
  -p 3000:3000 \
  --restart unless-stopped \
  --env-file .env \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/qiniu-data:/root/.qiniu \
  qiniu-feishu-bot

# 4. 查看日志
docker logs -f qiniu-bot
```

---

## 🍎 macOS 部署

### 方式 A：一键脚本

```bash
# 1. 下载项目
git clone <repo-url> qiniu-feishu-bot
cd qiniu-feishu-bot

# 2. 运行启动脚本
chmod +x start.sh
./start.sh
```

### 方式 B：Homebrew 安装 Node.js

```bash
# 1. 安装 Node.js
brew install node@18

# 2. 安装依赖
npm install

# 3. 配置
cp .env.example .env
nano .env

cp config/qiniu-config.json.example config/qiniu-config.json
nano config/qiniu-config.json

# 4. 启动
npm start

# 5. 后台运行（可选）
brew install pm2
pm2 start src/index.js --name qiniu-bot
pm2 save
pm2 startup
```

---

## 🪟 Windows 部署

### 方式 A：一键启动（推荐）

```powershell
# 1. 下载项目
# 下载 ZIP 或 git clone
git clone <repo-url> qiniu-feishu-bot
cd qiniu-feishu-bot

# 2. 双击运行
start.bat

# 脚本会自动：
# - 检查 Node.js
# - 创建配置文件
# - 安装依赖
# - 启动服务
```

### 方式 B：手动部署

```powershell
# 1. 安装 Node.js
# 下载：https://nodejs.org/
# 验证：node --version

# 2. 安装依赖
npm install

# 3. 配置环境变量
copy .env.example .env
notepad .env

# 4. 配置七牛云
mkdir config
copy config\qiniu-config.json.example config\qiniu-config.json
notepad config\qiniu-config.json

# 5. 启动服务
npm start
```

### 方式 C：作为 Windows 服务运行

使用 **NSSM** (Non-Sucking Service Manager)：

```powershell
# 1. 下载 NSSM
# https://nssm.cc/download

# 2. 安装服务
nssm install QiniuBot "C:\Program Files\nodejs\node.exe" "C:\path\to\qiniu-feishu-bot\src\index.js"

# 3. 配置工作目录
nssm set QiniuBot AppDirectory "C:\path\to\qiniu-feishu-bot"
nssm set QiniuBot AppEnvironmentExtra "NODE_ENV=production"

# 4. 启动服务
nssm start QiniuBot

# 5. 管理命令
nssm stop QiniuBot
nssm restart QiniuBot
nssm remove QiniuBot  # 删除服务
```

### 方式 D：Docker Desktop

```powershell
# 1. 安装 Docker Desktop
# https://www.docker.com/products/docker-desktop

# 2. 构建镜像
docker build -t qiniu-feishu-bot .

# 3. 运行容器
docker run -d ^
  --name qiniu-bot ^
  -p 3000:3000 ^
  --restart unless-stopped ^
  --env-file .env ^
  -v %cd%\config:/app/config ^
  qiniu-feishu-bot

# 4. 查看日志
docker logs -f qiniu-bot
```

---

## 🌐 配置公网访问

### 云服务器（推荐生产环境）

**阿里云/腾讯云 ECS：**

1. 购买云服务器（最低配置：1 核 1G）
2. 配置安全组，开放端口 3000
3. 部署应用
4. 配置域名和 HTTPS（可选但推荐）

**Nginx 反向代理：**

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location /feishu/event {
        proxy_pass http://localhost:3000;
        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;
    }
}
```

### 内网穿透（测试用）

**ngrok：**

```bash
# 下载：https://ngrok.com/
ngrok http 3000

# 复制生成的 https 地址到飞书事件订阅
```

**cloudflared：**

```bash
# 下载：https://github.com/cloudflare/cloudflared/releases
cloudflared tunnel --url http://localhost:3000
```

**cpolar（国内推荐）：**

```bash
# 官网：https://www.cpolar.com/
cpolar http 3000
```

---

## 📝 配置文件说明

### .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
```

### 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.com"
    }
  }
}
```

---

## ✅ 验证部署

### 1. 检查服务状态

```bash
# Linux/macOS
curl http://localhost:3000/health

# Windows PowerShell
Invoke-WebRequest http://localhost:3000/health
```

应返回：`{"status":"ok",...}`

### 2. 测试飞书消息

1. 在飞书中找到机器人
2. 发送任意消息
3. 应收到交互式卡片

### 3. 测试上传

```
/upload --original default
[附上一个文件]
```

---

## 🔧 故障排查

### 端口被占用

```bash
# Linux/macOS
lsof -i :3000
kill -9 <PID>

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F
```

### 权限问题

```bash
# Linux/macOS
chmod +x start.sh
chmod -R 755 .

# Windows
# 以管理员身份运行 start.bat
```

### 依赖安装失败

```bash
# 清除缓存重试
npm cache clean --force
npm install

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com
npm install
```

---

## 📞 获取帮助

- 查看日志：`docker logs qiniu-bot` 或查看控制台输出
- 检查配置：确保 `.env` 和 `qiniu-config.json` 正确
- 网络问题：确认防火墙开放端口 3000

---

**🍙 祝你部署顺利！**