CIBank/DEPLOY.md

# 餐智库部署指南

> 目标环境：腾讯云 Linux 服务器 + 已有域名 + HTTPS
> 视频号采集：本地 Mac 执行，同步至服务器，本地仅保留 3 天

---

## 一、架构总览

```
┌───────────────────────────────────────────────────────┐
│  腾讯云服务器 (Ubuntu 22.04 / Debian 12)                │
│                                                        │
│  Nginx :443 (HTTPS)                                    │
│    ├── /          → 前端静态文件 (dist/)                │
│    ├── /api/      → 反向代理 → gunicorn :8788          │
│    └── /api/video/ → 反向代理 → gunicorn :8788         │
│                                                        │
│  gunicorn (Flask) :8788                                │
│    ├── API 服务 (18 个 REST 接口)                       │
│    ├── SQLite (data/cibank.db)                         │
│    └── Playwright (公众号采集)                          │
│                                                        │
│  systemd-timer → daily_pipeline.py (每日 02:00)        │
│                                                        │
├───────────────────────────────────────────────────────┤
│  本地 Mac (视频号采集节点)                               │
│    wx_channels_download + 微信                          │
│    → 下载视频 → FunASR 转写                             │
│    → sync_to_server.py 推送到服务器                      │
│    → 清理 3 天前的本地视频                               │
└───────────────────────────────────────────────────────┘
```

---

## 二、服务器选型建议

| 项目 | 推荐配置 | 说明 |
|------|----------|------|
| 机型 | 2C4G (标准型 SA2/S5) | Playwright 采集吃内存，2G 可能 OOM |
| 系统 | Ubuntu 22.04 LTS | Playwright 兼容性最好 |
| 磁盘 | 50GB SSD | SQLite + 视频 + 日志 |
| 带宽 | 5Mbps+ | 视频文件传输 |
| 安全组 | 开放 80/443 | SSH 用密钥登录，不开放 22 到公网 |

---

## 三、服务器初始化

### 3.1 SSH 连接

```bash
ssh ubuntu@<服务器公网IP>
```

### 3.2 安装系统依赖

```bash
sudo apt update && sudo apt upgrade -y

# 基础工具
sudo apt install -y build-essential git curl wget unzip

# Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt install -y nodejs

# Python 3.11+
sudo apt install -y python3 python3-venv python3-pip python3-dev

# Nginx
sudo apt install -y nginx

# Playwright 系统依赖
sudo apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 \
  libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 \
  libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2 \
  libxshmfence1 libxfixes3

# Certbot (HTTPS)
sudo apt install -y certbot python3-certbot-nginx
```

### 3.3 创建部署目录

```bash
sudo mkdir -p /opt/cibank
sudo chown ubuntu:ubuntu /opt/cibank
```

---

## 四、代码部署

### 4.1 克隆代码

```bash
cd /opt/cibank
git clone https://git.all8ai.top/freedak/CIBank.git .
```

### 4.2 前端构建

```bash
cd /opt/cibank
npm install
npm run build
# 生成 dist/ 目录
```

### 4.3 后端配置

```bash
cd /opt/cibank/backend

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装 Python 依赖
pip install -r requirements.txt

# 安装 Playwright Chromium
playwright install chromium

# 安装 gunicorn
pip install gunicorn

# 配置环境变量
cp .env.example .env
```

编辑 `.env`：

```bash
# 必填
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

# 生产环境修改
FLASK_SECRET_KEY=$(openssl rand -hex 32)
PORT=8788

# 采集参数（按需调整）
CRAWL_ARTICLE_PAUSE=2.0
CRAWL_LIST_PAUSE=1.5
CRAWL_MAX_SCROLLS=15
CRAWL_LOOKBACK_DAYS=7

# ASR 配置（服务器端如不需要视频号转写可留空）
FFMPEG_PATH=/usr/bin/ffmpeg
FFPROBE_PATH=/usr/bin/ffprobe
# FUNASR_PATH 可以不配，视频号转写在本地完成
```

### 4.4 初始化数据库

```bash
cd /opt/cibank/backend
source venv/bin/activate
python3 -c "from app import ensure_schema; ensure_schema()"
```

### 4.5 迁移本地数据（可选）

如果本地已有数据，从 Mac 同步到服务器：

```bash
# 在本地 Mac 执行
scp backend/data/cibank.db ubuntu@<服务器IP>:/opt/cibank/backend/data/
scp -r backend/data/audio ubuntu@<服务器IP>:/opt/cibank/backend/data/
```

---

## 五、进程管理 (systemd)

### 5.1 后端 API 服务

创建 `/etc/systemd/system/cibank-api.service`：

```bash
sudo tee /etc/systemd/system/cibank-api.service > /dev/null << 'EOF'
[Unit]
Description=CIBank API Server (gunicorn)
After=network.target

[Service]
Type=exec
User=ubuntu
WorkingDirectory=/opt/cibank/backend
EnvironmentFile=/opt/cibank/backend/.env
ExecStart=/opt/cibank/backend/venv/bin/gunicorn \
  -w 2 \
  -b 127.0.0.1:8788 \
  --timeout 300 \
  --access-logfile /opt/cibank/backend/data/logs/gunicorn-access.log \
  --error-logfile /opt/cibank/backend/data/logs/gunicorn-error.log \
  app:app
Restart=always
RestartSec=5

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

### 5.2 每日流水线服务

创建 `/etc/systemd/system/cibank-pipeline.service`：

```bash
sudo tee /etc/systemd/system/cibank-pipeline.service > /dev/null << 'EOF'
[Unit]
Description=CIBank Daily Pipeline
After=network.target

[Service]
Type=oneshot
User=ubuntu
WorkingDirectory=/opt/cibank/backend
EnvironmentFile=/opt/cibank/backend/.env
ExecStart=/opt/cibank/backend/venv/bin/python3 /opt/cibank/backend/daily_pipeline.py daily
StandardOutput=append:/opt/cibank/backend/data/logs/pipeline.log
StandardError=append:/opt/cibank/backend/data/logs/pipeline-error.log
EOF
```

创建定时器 `/etc/systemd/system/cibank-pipeline.timer`：

```bash
sudo tee /etc/systemd/system/cibank-pipeline.timer > /dev/null << 'EOF'
[Unit]
Description=Run CIBank Daily Pipeline at 02:00

[Timer]
OnCalendar=*-*-* 02:00:00
Persistent=true

[Install]
WantedBy=timers.target
EOF
```

### 5.3 启动所有服务

```bash
# 创建日志目录
mkdir -p /opt/cibank/backend/data/logs

# 加载 systemd 配置
sudo systemctl daemon-reload

# 启动后端 API
sudo systemctl enable cibank-api
sudo systemctl start cibank-api

# 启动定时任务
sudo systemctl enable cibank-pipeline.timer
sudo systemctl start cibank-pipeline.timer

# 验证状态
sudo systemctl status cibank-api
sudo systemctl status cibank-pipeline.timer
```

---

## 六、Nginx 配置

### 6.1 创建站点配置

将 `cibank.example.com` 替换为你的实际域名：

```bash
sudo tee /etc/nginx/sites-available/cibank > /dev/null << 'EOF'
server {
    listen 80;
    server_name cibank.example.com;

    # 前端静态文件
    root /opt/cibank/dist;
    index index.html;

    # SPA 路由回退
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:8788;
        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_read_timeout 300s;
        proxy_buffering off;
    }

    # 视频文件代理（大文件超时设长）
    location /api/video/ {
        proxy_pass http://127.0.0.1:8788;
        proxy_set_header Host $host;
        proxy_read_timeout 600s;
        proxy_buffering on;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # 安全头
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
}
EOF
```

### 6.2 启用站点

```bash
sudo ln -sf /etc/nginx/sites-available/cibank /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx
```

### 6.3 配置 HTTPS

```bash
# 申请 Let's Encrypt 证书（自动修改 Nginx 配置）
sudo certbot --nginx -d cibank.example.com

# 自动续期（certbot 默认已配置 systemd timer）
sudo systemctl status certbot.timer
```

---

## 七、视频号本地采集 + 同步方案

### 7.1 本地 Mac 采集流程（不变）

```bash
# 1. 启动 wx_channels_download
sudo networksetup -setv6off Wi-Fi
sudo <工具路径>/wx_video_download

# 2. 下载并自动转写
cd /Users/freedak/Documents/AIDashboard/CIBank/backend
python3 video_downloader.py
```

### 7.2 数据同步脚本

在本地 Mac 创建 `sync_to_server.sh`：

```bash
#!/bin/bash
# 将本地采集的视频号数据同步到服务器
# 用法: ./sync_to_server.sh

SERVER="ubuntu@cibank.example.com"
REMOTE_DIR="/opt/cibank/backend"
LOCAL_DIR="$(cd "$(dirname "$0")" && pwd)"

echo "=== 同步数据库到服务器 ==="
# 使用 rsync 增量同步数据库
rsync -avz --progress \
  "$LOCAL_DIR/data/cibank.db" \
  "$SERVER:$REMOTE_DIR/data/"

echo "=== 同步视频文件到服务器 ==="
rsync -avz --progress \
  "$LOCAL_DIR/data/audio/" \
  "$SERVER:$REMOTE_DIR/data/audio/"

echo "=== 同步完成 ==="
ssh "$SERVER" "systemctl restart cibank-api"
echo "后端服务已重启"
```

### 7.3 本地 3 天自动清理

在本地 Mac 创建 `cleanup_local.sh`：

```bash
#!/bin/bash
# 清理 3 天前的视频和音频文件
# 用法: ./cleanup_local.sh

AUDIO_DIR="$(cd "$(dirname "$0")" && pwd)/data/audio"
VIDEO_DIR="<你的视频下载目录>"

echo "=== 清理 3 天前的音频文件 ==="
find "$AUDIO_DIR" -type f -name "*.mp3" -mtime +3 -delete
find "$AUDIO_DIR" -type f -name "*.wav" -mtime +3 -delete

echo "=== 清理 3 天前的视频文件 ==="
find "$VIDEO_DIR" -type f \( -name "*.mp4" -o -name "*.flv" \) -mtime +3 -delete

echo "=== 清理完成 ==="
```

### 7.4 本地定时任务 (launchd)

创建 `com.cibank.sync-and-cleanup.plist`：

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.cibank.sync-and-cleanup</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>/Users/freedak/Documents/AIDashboard/CIBank/backend/sync_to_server.sh</string>
    </array>
    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>3</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>
    <key>StandardOutPath</key>
    <string>/tmp/cibank-sync.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/cibank-sync-error.log</string>
</dict>
</plist>
```

安装定时任务：

```bash
cp com.cibank.sync-and-cleanup.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.cibank.sync-and-cleanup.plist
```

---

## 八、防火墙与安全

### 8.1 腾讯云安全组

| 端口 | 协议 | 来源 | 说明 |
|------|------|------|------|
| 443 | TCP | 0.0.0.0/0 | HTTPS |
| 80 | TCP | 0.0.0.0/0 | HTTP (certbot 验证 + 跳转) |
| 22 | TCP | 你的 IP only | SSH |

### 8.2 服务器防火墙

```bash
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
```

### 8.3 SSH 密钥登录

```bash
# 禁用密码登录
sudo sed -i 's/PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo systemctl restart sshd
```

---

## 九、日常运维

### 9.1 查看服务状态

```bash
# 后端 API
sudo systemctl status cibank-api

# 定时任务
sudo systemctl status cibank-pipeline.timer
sudo systemctl list-timers cibank-pipeline.timer

# Nginx
sudo systemctl status nginx

# 手动触发每日流水线
sudo systemctl start cibank-pipeline.service
```

### 9.2 查看日志

```bash
# API 日志
tail -f /opt/cibank/backend/data/logs/gunicorn-access.log
tail -f /opt/cibank/backend/data/logs/gunicorn-error.log

# 流水线日志
tail -f /opt/cibank/backend/data/logs/pipeline.log

# Nginx 日志
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log
```

### 9.3 更新代码

```bash
cd /opt/cibank
git pull

# 前端重新构建
npm install && npm run build

# 后端依赖更新（如有变化）
cd backend
source venv/bin/activate
pip install -r requirements.txt

# 重启服务
sudo systemctl restart cibank-api
```

### 9.4 数据库备份

```bash
# 手动备份
sqlite3 /opt/cibank/backend/data/cibank.db ".backup /opt/cibank/backend/data/backups/cibank-$(date +%Y%m%d).db"

# 自动备份（cron）
crontab -e
# 添加：0 1 * * * sqlite3 /opt/cibank/backend/data/cibank.db ".backup /opt/cibank/backend/data/backups/cibank-$(date +\%Y\%m\%d).db"
```

---

## 十、部署检查清单

- [ ] 服务器系统依赖安装完成
- [ ] 代码克隆到 `/opt/cibank`
- [ ] 前端 `npm run build` 成功
- [ ] 后端虚拟环境 + 依赖安装完成
- [ ] Playwright Chromium 安装成功
- [ ] `.env` 配置 `DASHSCOPE_API_KEY` 和 `FLASK_SECRET_KEY`
- [ ] 数据库初始化或迁移完成
- [ ] gunicorn 启动正常 (`curl http://127.0.0.1:8788/api/health` 返回 `{"ok": true}`)
- [ ] systemd 服务配置并启动
- [ ] Nginx 配置生效
- [ ] HTTPS 证书申请成功
- [ ] 访问 `https://cibank.example.com` 页面正常加载
- [ ] 定时任务验证
- [ ] 本地 Mac 同步脚本测试通过
- [ ] 本地清理脚本测试通过
- [ ] 安全组 / 防火墙规则确认