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 连接

ssh ubuntu@<服务器公网IP>

3.2 安装系统依赖

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 创建部署目录

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

---

四、代码部署

4.1 克隆代码

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

4.2 前端构建

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

4.3 后端配置

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：

# 必填
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 初始化数据库

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

4.5 迁移本地数据（可选）

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

# 在本地 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：

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：

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：

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 启动所有服务

# 创建日志目录
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 替换为你的实际域名：

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 启用站点

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

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

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

---

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

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

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

#!/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：

#!/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 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>

安装定时任务：

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 服务器防火墙

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 密钥登录

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

---

九、日常运维

9.1 查看服务状态

# 后端 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 查看日志

# 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 更新代码

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 数据库备份

# 手动备份
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 同步脚本测试通过
• 本地清理脚本测试通过
• 安全组 / 防火墙规则确认