Skip to content

分布式部署指南.md

Latest commit

 

History

History
303 lines (228 loc) · 9.55 KB

分布式部署指南.md

File metadata and controls

303 lines (228 loc) · 9.55 KB
Raw

AgendaScope 分布式部署指南（v4.0）

目标读者：本地算力机管理员 / 后续接入的协作者 前置：云端（阿里云 2C2G）已部署 v3.0 数据库结构化重构版本（commit d4efac0）

一、架构总览

┌─────────────────────────────────────────────────────────────────┐
│  本地算力机（导师实验室，8 核 32GB）                              │
│  ├─ collector（采集 worker）                                     │
│  ├─ nlp-worker（embedding/语言/情感）                            │
│  ├─ cluster-worker（聚类，BERTopic 启用）                        │
│  ├─ entity-worker（实体抽取 + 种子匹配）                         │
│  ├─ relation-worker（LLM 关系抽取，走云 API）                    │
│  ├─ snapshot-worker（快照聚合）                                  │
│  ├─ detection-worker（议程事件检测）                             │
│  ├─ naming-worker（议题命名 LLM）                                │
│  └─ alerting-worker（预警评估）                                  │
│                                                                 │
│  所有 worker 通过公网 PostgreSQL 连接云端                        │
└─────────────────────────────────────────────────────────────────┘
                          ↓ SSL 加密 PG 连接
┌─────────────────────────────────────────────────────────────────┐
│  阿里云 2C2G（39.106.2.28，仅 3 个服务）                         │
│  ├─ db（PostgreSQL 16 + pgvector，mem 768MB）                    │
│  ├─ backend（FastAPI，mem 384MB，只读 API）                      │
│  ├─ frontend（nginx + 静态文件 + HTTPS，mem 64MB）               │
│  └─ redis（缓存 + API Key 限流，mem 96MB）                       │
└─────────────────────────────────────────────────────────────────┘
                          ↓ HTTPS
┌─────────────────────────────────────────────────────────────────┐
│  用户浏览器 / 数据 API 客户端                                    │
└─────────────────────────────────────────────────────────────────┘

二、云端（阿里云）一次性配置

2.1 拉取最新代码

ssh root@39.106.2.28
cd /root/agendascope
git pull origin main    # 拉取 v4.0 分布式架构代码

2.2 生成 PG SSL 证书

bash deploy/postgresql/generate_ssl_cert.sh
# 生成 deploy/postgresql/ssl/{server.crt, server.key, ca.crt}

2.3 创建 PG 公网账号

# 编辑 init_public_users.sql 改两个 CHANGE_ME 为强密码（≥20 位）
vim deploy/postgresql/init_public_users.sql

# 在 PG 容器中执行
docker exec -i agendascope-db-1 psql -U agenda -d agendascope < deploy/postgresql/init_public_users.sql

# 验证
docker exec -i agendascope-db-1 psql -U agenda -d agendascope -c "SELECT usename FROM pg_user"
# 应看到 agenda / agendascope_write / agendascope_read

2.4 配置防火墙（关键安全步骤）

宝塔面板：

  1. 登录 https://39.106.2.28:8888/a3427cb8
  2. 安全 → 防火墙 → 添加规则
  3. 端口 5432，协议 TCP，只允许导师实验室公网 IP 段（如 202.108.x.x/24）
  4. 拒绝其他所有 IP 访问 5432

或 iptables：

# 只允许实验室 IP 访问 5432
iptables -A INPUT -p tcp --dport 5432 -s 202.108.0.0/16 -j ACCEPT
iptables -A INPUT -p tcp --dport 5432 -j DROP

2.5 切换云端到瘦身版 compose

cd /root/agendascope
# 停掉所有 worker（数据不会丢，只是不再处理新文章）
docker compose --env-file .env -f deploy/docker-compose.yml -f deploy/compose.deploy.yml down

# 启动瘦身版（只 db + backend + frontend + redis）
docker compose --env-file .env -f deploy/docker-compose.yml -f deploy/compose.deploy.yml up -d

# 验证
docker compose -f deploy/docker-compose.yml -f deploy/compose.deploy.yml ps
# 应只看到 db / backend / frontend / redis 4 个服务运行

2.6 验证云端正常

# 健康检查
curl https://www.wordread.cn/health

# 公网 PG 测试（在本地机器上）
psql "postgresql://agendascope_write:PASSWORD@39.106.2.28:5432/agendascope?sslmode=require" -c "SELECT count(*) FROM sources"
# 应输出 408

三、本地算力机接入

3.1 系统准备

# Ubuntu 22.04
sudo apt update && sudo apt upgrade -y
sudo apt install -y docker.io docker-compose-v2 git curl

# 启动 Docker
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
newgrp docker

3.2 安装 mihomo 代理（采集境外媒体需要）

# 下载 mihomo
mkdir -p /opt/mihomo && cd /opt/mihomo
wget https://github.com/MetaCubeX/mihomo/releases/latest/download/mihomo-linux-amd64.gz
gunzip mihomo-linux-amd64.gz
chmod +x mihomo-linux-amd64
sudo mv mihomo-linux-amd64 /usr/local/bin/mihomo

# 配置（/etc/mihomo/config.yaml）
# 订阅链接找机场要；UA 必须 ClashMetaForAndroid

# 启动
sudo systemctl enable --now mihomo
curl -x http://127.0.0.1:7890 https://www.google.com  # 验证

3.3 克隆代码

cd /opt
git clone https://github.com/yangyh-2025/agendascope.git
cd agendascope/local_workers

3.4 配置环境变量

cp .env.example .env
vim .env

关键字段：

  • DATABASE_URL：改 CHANGE_ME 为 agendascope_write 账号的强密码
  • LLM_API_KEY：填智谱 GLM-4 API Key（https://open.bigmodel.cn/ 申请）
  • GLOBAL_SITE_PROXY：本地 mihomo 地址（http://host.docker.internal:7890）

3.5 下载模型

mkdir -p models
# 用 HuggingFace 镜像下载 bge-m3
pip install -U huggingface_hub
huggingface-cli download BAAI/bge-m3 --local-dir models/bge-m3 --resume-download

3.6 复制 SSL CA 证书

# 从云端拉取 ca.crt
scp root@39.106.2.28:/root/agendascope/deploy/postgresql/ssl/ca.crt ./ssl/ca.crt

3.7 同步后端镜像

方法 1：从云端 docker save/load（推荐）

# 云端
ssh root@39.106.2.28 "docker save agendascope-backend:latest | gzip" > backend.tar.gz

# 本地
docker load -i backend.tar.gz

方法 2：本地构建

cd /opt/agendascope
docker build -t agendascope-backend:latest -f deploy/Dockerfile.backend backend/

3.8 启动所有 worker

cd /opt/agendascope/local_workers
docker compose --env-file .env up -d

# 查看状态
docker compose --env-file .env ps

# 查看采集日志
docker compose --env-file .env logs -f collector

3.9 验证

# 检查云端 articles 表是否有新数据
psql "postgresql://agendascope_write:PASSWORD@39.106.2.28:5432/agendascope?sslmode=require" \
  -c "SELECT count(*), max(crawled_at) FROM articles"

# 检查 article_processing 状态机是否在推进
psql "..." -c "SELECT nlp_status, count(*) FROM article_processing GROUP BY nlp_status"

四、日常运维

4.1 启停

# 停止
docker compose --env-file .env down

# 重启单个 worker
docker compose --env-file .env restart collector

# 看资源占用
docker stats

4.2 更新代码

cd /opt/agendascope
git pull origin main
# 重建镜像
docker build -t agendascope-backend:latest -f deploy/Dockerfile.backend backend/
# 重启
cd local_workers
docker compose --env-file .env up -d --force-recreate

4.3 故障排查

症状 排查
psql: connection timeout 云端防火墙 5432 是否放行本地 IP
SSL certificate verify failed ssl/ca.crt 是否与云端一致
采集全部 403/timeout 本地 mihomo 是否在跑；curl -x http://localhost:7890 https://www.google.com
OOM Killed docker stats 看哪个 worker 超内存；降 COLLECT_MAX_WORKERS 或 NLP_WORKER_BATCH_SIZE
relation-worker 一直不跑 检查 LLM_API_KEY 是否有效；docker logs local_workers-relation-worker-1

五、扩展到多机

如果导师批了多台机器，可以分工：

机器 A（采集机）：

docker compose --env-file .env up -d collector

机器 B（计算机）：

docker compose --env-file .env up -d nlp-worker cluster-worker entity-worker

机器 C（LLM 机）：

docker compose --env-file .env up -d relation-worker naming-worker detection-worker

机器 D（快照+预警）：

docker compose --env-file .env up -d snapshot-worker alerting-worker

v3.0 的 article_processing 状态机 + FOR UPDATE SKIP LOCKED 保证多机并发安全，不会重复处理。

六、回滚（如需恢复云端单机模式）

# 云端
cd /root/agendascope
git checkout b1583a6    # 回到 v2.0 单机版
docker compose --env-file .env -f deploy/docker-compose.yml -f deploy/compose.deploy.yml up -d --force-recreate

数据库表结构保持 v3.0 不变（向后兼容），只是 worker 重新跑在云端。