crypto_monitor_user/docs/ubuntu-server.md

Ubuntu 服务器部署与环境说明

本文档为 生产环境唯一推荐路径:Ubuntu,root 用户,代码目录 /opt/crypto_monitor_user,进程托管 PM2.不使用 Windows 部署,不使用 systemd/screen/nohup 托管应用(SSH 隧道除外).

---

1. 系统要求

项	要求
操作系统	优先 Ubuntu 22.04 LTS(自带 Python 3.10)。24.04 可用,但须自行安装 Python 3.10,不可用系统默认 3.12
运行用户	root(下文命令均按 root 编写)
项目路径	/opt/crypto_monitor_user(整仓克隆到此目录)
进程管理	PM2(全局安装,见 §3)
网络	能 git clone 私有仓库;能访问授权站 https://sq.bz121.com;访问交易所不稳定时需 SSH SOCKS(见各所《部署文档》)
授权	部署后配置仓库根 license.env，打开 /license 激活（见 license.md）

新机建议直接装 22.04。 用户版 lib/ 核心包为 Python 3.10 加密字节码;用 3.12 启动会出现 ValueError: bad marshal data (unknown type code)(如 crypto_okx 反复重启)。

---

2. Python 环境

项	说明
版本	仅 Python 3.10 或 3.11(推荐 3.10)。setup_env.sh 会拒绝 3.9 及以下、以及 3.12+
虚拟环境	每个子项目独立 .venv(deploy/setup_env.sh 自动创建;优先选用 python3.10)
依赖文件	三所监控共用仓库根目录 requirements.txt;中控用 manual_trading_hub/requirements.txt
SOCKS	走代理时必须安装 PySocks(已写入 requirements)

2.1 系统包(root)

Ubuntu 22.04(推荐):

apt update
apt install -y python3 python3-pip python3-venv curl git ca-certificates
# 22.04 上 python3 即为 3.10
apt install -y python3.10-venv
python3 --version   # 应为 Python 3.10.x

若坚持 Ubuntu 24.04: 勿用系统 python3(3.12)。需先安装 3.10,再部署:

apt update
apt install -y software-properties-common
add-apt-repository -y ppa:deadsnakes/ppa
apt update
apt install -y python3.10 python3.10-venv python3.10-dev curl git ca-certificates
python3.10 --version
# 随后一键部署;setup_env 会优先使用 python3.10

2.2 一键创建各目录 venv

推荐(新服务器一条命令):

curl -fsSL https://git.bz121.com/dekun/crypto_monitor_user/raw/branch/main/deploy/manage.sh | bash
# 菜单选 1) 一键部署

或已 clone 后:

cd /opt/crypto_monitor_user
bash deploy/manage.sh
# 或仅建环境:
bash deploy/setup_env.sh --install-system-deps

完成后各目录使用 .venv/bin/python 运行 app.py / hub.py;PM2 的 ecosystem 脚本已指向该解释器.

---

3. Node.js 与 PM2

项	说明
Node.js	建议 18 LTS 或 20 LTS(用于安装 PM2;应用本体为 Python)
PM2	全局安装,托管所有 Flask 与中控/子代理

3.1 安装 Node + PM2(root)

# 方式 A:NodeSource(示例 Node 20)
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
node -v    # v20.x
npm -v

npm install -g pm2
pm2 -v
pm2 startup    # 按提示执行,保证重启后 PM2 自启

deploy/setup_env.sh 在检测到 Node 时也会尝试 npm install -g pm2(未装 Node 则跳过并提示手动安装).

3.2 PM2 启动顺序(推荐)

# 1) 三所 Flask(在各子目录执行,或分别 start)
cd /opt/crypto_monitor_user/crypto_monitor_binance && pm2 start ecosystem.config.cjs
cd /opt/crypto_monitor_user/crypto_monitor_gate && pm2 start ecosystem.config.cjs
cd /opt/crypto_monitor_user/crypto_monitor_okx && pm2 start ecosystem.config.cjs

# 2) 中控 + 三子代理(一条配置 4 进程:hub + 3 agent)
cd /opt/crypto_monitor_user/manual_trading_hub
pm2 start ecosystem.config.cjs

pm2 save
pm2 list

升级代码后:

cd /opt/crypto_monitor_user && git pull
# 若 requirements 有变,对各目录 .venv/bin/pip install -r ...
pm2 restart all # 或按进程名 restart

不要 再用 systemd unit,screen,nohup 启动 app.py / hub.py / agent.py,避免与 PM2 抢端口.

3.3 常见 PM2 进程名

目录	ecosystem 内典型名称
crypto_monitor_binance	crypto_binance
crypto_monitor_gate	crypto_gate
crypto_monitor_okx	crypto_okx
manual_trading_hub	manual-trading-hub,manual-agent-*

以各目录 ecosystem.config.cjs 为准.

3.4 整目录重装(清库 / 去脏 PM2)

保留 .env,丢弃旧库与旧 PM2 名单时,见 deploy/reinstall-plan-b.md:

cd /opt/crypto_monitor_user
bash deploy/reinstall.sh --yes

首次安装仍只用 deploy/setup_env.sh,二者互不影响.

---

4. 目录与权限

mkdir -p /opt
cd /opt
git clone https://git.bz121.com/dekun/crypto_monitor_user.git crypto_monitor_user
chown -R root:root /opt/crypto_monitor_user

• 数据库默认:各所 crypto.db(SQLite)
• 备份目录建议:/root/backups(见 备份与恢复.md)
• .env:仅本机编辑,勿提交 Git;升级前 cp .env .env.backup.$(date +%Y%m%d)

---

5. SSH 动态转发(SOCKS)

若交易所 API 需经境外 VPS:

• 在本机用 ssh -N -D 127.0.0.1:1080 别名 建立隧道(配置见各所《部署文档》~/.ssh/config)
• 隧道进程可用 tmux 或 autossh 保持常驻;不必 也不建议把 ssh 交给 PM2
• 各所 .env 设置对应 *_SOCKS_PROXY=socks5h://127.0.0.1:1080

---

6. 部署后检查

# 中控验收(需已 start hub)
bash /opt/crypto_monitor_user/manual_trading_hub/scripts/verify_hub_deploy.sh

pm2 logs manual-trading-hub --lines 50
curl -sS http://127.0.0.1:5100/api/monitor/board | head

---

7. 相关文档

文档	内容
deploy/README.md	manage.sh 一键部署;setup_env.sh 参数
备份与恢复.md	数据库与 .env 备份
各 crypto_monitor_*/部署文档.md	交易所 SOCKS,.env,PM2 细节
manual_trading_hub/部署文档.md	中控 PM2,端口,反代