qiniu-feishu-bot/DEPLOY.md

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

支持 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：一键脚本（推荐）

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

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

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

方式 B：手动部署

# 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 服务配置：

[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

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

方式 C：Docker 部署

# 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：一键脚本

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

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

方式 B：Homebrew 安装 Node.js

# 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：一键启动（推荐）

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

# 2. 双击运行
start.bat

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

方式 B：手动部署

# 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)：

# 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

# 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 反向代理：

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：

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

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

cloudflared：

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

cpolar（国内推荐）：

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

---

📝 配置文件说明

.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

{
  "buckets": {
    "default": {
      "accessKey": "YOUR_ACCESS_KEY",
      "secretKey": "YOUR_SECRET_KEY",
      "bucket": "your-bucket-name",
      "region": "z0",
      "domain": "https://your-cdn.com"
    }
  }
}

---

✅ 验证部署

1. 检查服务状态

# 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
[附上一个文件]

---

🔧 故障排查

端口被占用

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

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

权限问题

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

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

依赖安装失败

# 清除缓存重试
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

---

🍙 祝你部署顺利！