docs: 添加服务器部署指南 (腾讯云 + HTTPS + 视频号本地同步方案)

DEPLOY.md

@@ -0,0 +1,561 @@
+# 餐智库部署指南
+
+> 目标环境：腾讯云 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 同步脚本测试通过
+- [ ] 本地清理脚本测试通过
+- [ ] 安全组 / 防火墙规则确认