Nexus/docs/project/deploy.md

Nexus 部署指南 — Ubuntu 20.04 / 22.04 / 24.04

项目: Nexus — 服务器运维管理平台
版本: 6.0.0
技术栈: Python 3.12+ / FastAPI / Async SQLAlchemy / MySQL 8.4 / Redis 7 / PHP 8.2+ / Nginx
生产域名: api.synaglobal.vip (强制 HTTPS)
网站目录: /www/wwwroot/api.synaglobal.vip
更新日期: 2026-05-20

---

1. 系统依赖修复（⚠️ 首先运行）

Ubuntu 服务器部署时经常缺少编译和运行依赖。在安装任何服务之前，先运行以下命令修复所有基础依赖：

1.1 一键修复脚本

#!/bin/bash
# Nexus — Ubuntu 系统依赖一键修复脚本
# 适用于 Ubuntu 20.04 / 22.04 / 24.04
# 用法: sudo bash fix-deps.sh

set -e

echo "===== Nexus 系统依赖修复 ====="

# 更新软件源
apt update

# ── 核心编译工具 ──
apt install -y \
  build-essential \
  cmake \
  autoconf \
  automake \
  libtool \
  pkg-config \
  gcc \
  g++ \
  make \
  git \
  curl \
  wget \
  unzip \
  ca-certificates \
  gnupg

# ── 通用开发库（所有组件共享）──
apt install -y \
  libssl-dev \
  libxml2-dev \
  libcurl4-openssl-dev \
  zlib1g-dev \
  libpcre3-dev \
  libpcre2-dev \
  libbz2-dev \
  libzip-dev \
  liblz4-dev \
  libzstd-dev \
  liblzma-dev \
  libffi-dev \
  libncurses5-dev \
  libncursesw5-dev \
  libreadline-dev \
  libsqlite3-dev \
  libicu-dev \
  libbrotli-dev

# ── Nginx 专用依赖 ──
apt install -y \
  libgd-dev \
  libgeoip-dev \
  libxslt1-dev

# ── PHP 8.x 专用依赖 ──
apt install -y \
  libonig-dev \
  libsodium-dev \
  libargon2-dev \
  libjpeg-dev \
  libpng-dev \
  libfreetype6-dev \
  libwebp-dev \
  libgmp-dev \
  libtidy-dev \
  libpq-dev \
  default-libmysqlclient-dev

# ── MySQL 8.4 专用依赖 ──
apt install -y \
  bison \
  gperf \
  libevent-dev \
  libnuma-dev \
  libaio-dev \
  protobuf-compiler \
  libprotobuf-dev

# ── Python 3.12+ 专用依赖 ──
apt install -y \
  libgdbm-dev \
  libgdbm-compat-dev \
  libmpdec-dev \
  uuid-dev

# ── Redis 7 专用依赖 ──
apt install -y \
  libjemalloc-dev

echo "===== 依赖修复完成 ====="

1.2 手动逐项安装（如果脚本不适用）

按组件分类的依赖列表：

通用依赖（所有组件都需要）

sudo apt install -y build-essential cmake autoconf automake libtool pkg-config \
  gcc g++ make git curl wget unzip ca-certificates gnupg \
  libssl-dev libxml2-dev libcurl4-openssl-dev zlib1g-dev \
  libpcre3-dev libpcre2-dev libbz2-dev libzip-dev \
  liblz4-dev libzstd-dev liblzma-dev libffi-dev \
  libncurses5-dev libncursesw5-dev libreadline-dev \
  libsqlite3-dev libicu-dev libbrotli-dev

Nginx 专用

sudo apt install -y libgd-dev libgeoip-dev libxslt1-dev

PHP 8.x 专用

sudo apt install -y libonig-dev libsodium-dev libargon2-dev \
  libjpeg-dev libpng-dev libfreetype6-dev libwebp-dev \
  libgmp-dev libtidy-dev libpq-dev default-libmysqlclient-dev

MySQL 8.4 专用

sudo apt install -y bison gperf libevent-dev libnuma-dev \
  libaio-dev protobuf-compiler libprotobuf-dev

Python 3.12+ 专用

sudo apt install -y libgdbm-dev libgdbm-compat-dev \
  libmpdec-dev uuid-dev

Redis 专用

sudo apt install -y libjemalloc-dev

---

2. 服务安装

2.1 Nginx

# 方式 A: apt 直接安装（推荐）
sudo apt install -y nginx

# 方式 B: 编译安装（需要更多自定义模块时）
# 编译依赖已在 1.1 中安装
wget http://nginx.org/download/nginx-1.26.2.tar.gz
tar -xzf nginx-1.26.2.tar.gz
cd nginx-1.26.2
./configure --prefix=/usr/local/nginx \
  --with-http_ssl_module \
  --with-http_v2_module \
  --with-http_realip_module \
  --with-http_gzip_static_module \
  --with-http_brotli_module \
  --with-stream \
  --with-stream_ssl_module
make && sudo make install

2.2 MySQL 8.4 LTS

# 方式 A: apt 安装（推荐 — MySQL 官方 APT 源）
wget https://dev.mysql.com/get/mysql-apt-config_0.8.33-1ubuntu_all.deb
sudo dpkg -i mysql-apt-config_0.8.33-1ubuntu_all.deb
# 在配置界面选择 mysql-8.4-lts
sudo apt update
sudo apt install -y mysql-server mysql-client

# 安全初始化
sudo mysql_secure_installation

# 方式 B: 宝塔面板一键安装
# 在宝塔面板 → 软件商店 → MySQL 8.4 → 安装

2.3 Redis 7

# 方式 A: apt 安装
sudo apt install -y redis-server

# 方式 B: 编译安装（最新版本）
wget https://github.com/redis/redis/archive/refs/tags/7.4.2.tar.gz
tar -xzf 7.4.2.tar.gz
cd redis-7.4.2
make MALLOC=jemalloc
sudo make install

# 启动
redis-server --daemonize yes

2.4 PHP 8.2+

# 方式 A: apt 安装（Ubuntu 22.04+ 默认有 PHP 8.1）
sudo apt install -y php8.2 php8.2-fpm php8.2-cli \
  php8.2-mysql php8.2-redis php8.2-gd php8.2-mbstring \
  php8.2-xml php8.2-zip php8.2-curl php8.2-bz2 \
  php8.2-intl php8.2-opcache php8.2-json php8.2-readline

# 如果需要 PHP 8.3（更新版本）:
sudo add-apt-repository -y ppa:ondrej/php
sudo apt update
sudo apt install -y php8.3 php8.3-fpm php8.3-cli \
  php8.3-mysql php8.3-redis php8.3-gd php8.3-mbstring \
  php8.3-xml php8.3-zip php8.3-curl php8.3-bz2 \
  php8.3-intl php8.3-opcache

# 方式 B: 宝塔面板安装
# 宝塔面板 → 软件商店 → PHP 8.2/8.3 → 安装

2.5 Python 3.12+

# 方式 A: apt 安装（Ubuntu 24.04 默认有 Python 3.12）
sudo apt install -y python3.12 python3.12-dev python3.12-venv \
  python3-pip python3-venv

# Ubuntu 22.04 需要添加 deadsnakes PPA:
sudo add-apt-repository -y ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.12 python3.12-dev python3.12-venv

# 方式 B: 编译安装
wget https://www.python.org/ftp/python/3.12.7/Python-3.12.7.tar.xz
tar -xf Python-3.12.7.tar.xz
cd Python-3.12.7
./configure --enable-optimizations --with-ensurepip=install
make -j$(nproc)
sudo make altinstall  # altinstall 防止覆盖系统 python3

---

3. Nexus 项目部署

3.1 克隆仓库

cd /opt
git clone http://66.154.115.8:3000/admin/Nexus.git
cd Nexus

3.2 Python 环境配置

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

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

# 如果 pip 安装遇到编译错误（缺少依赖），回到步骤 1 修复依赖后重新安装

3.3 配置文件

# 复制配置模板
cp .env.example .env

# 编辑 .env 文件
nano .env

.env 必填项（⚠️ .env 文件不会被提交到 Git，已在 .gitignore 中排除）：

# ⚠️ SECRET_KEY 必须设置，否则 Nexus 无法启动
NEXUS_SECRET_KEY=<生成一个随机密钥: python3 -c "import secrets; print(secrets.token_urlsafe(32))">

# 数据库连接（aiomysql 驱动）
NEXUS_DATABASE_URL=mysql+aiomysql://Nexus:<你的密码>@127.0.0.1:3306/Nexus

# Redis
NEXUS_REDIS_URL=redis://127.0.0.1:6379/0

# API Key（Agent 认证用）
NEXUS_API_KEY=<生成: python3 -c "import secrets; print(secrets.token_urlsafe(24))">

⚠️ 安全提示: .env 文件包含密码和密钥，绝不能提交到 Git。项目 .gitignore 已排除 .env。

3.4 创建 MySQL 数据库

sudo mysql -u root -p

# 在 MySQL 中执行:
CREATE DATABASE Nexus CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'Nexus'@'localhost' IDENTIFIED BY '<你的数据库密码>';
GRANT ALL PRIVILEGES ON Nexus.* TO 'Nexus'@'localhost';
FLUSH PRIVILEGES;
EXIT;

注意: Nexus 启动时会自动创建所有数据表（Base.metadata.create_all），无需手动建表。

3.5 启动 Nexus

# 方式 A: 直接运行（开发/调试）
source venv/bin/activate
uvicorn server.main:app --host 0.0.0.0 --port 8600

# 方式 B: Supervisor 守护进程（生产环境推荐）
sudo apt install -y supervisor

# 创建 supervisor 配置
sudo nano /etc/supervisor/conf.d/nexus.conf

nexus.conf 内容：

[program:nexus]
command=/www/wwwroot/api.synaglobal.vip/venv/bin/uvicorn server.main:app --host 0.0.0.0 --port 8600 --workers 4
directory=/www/wwwroot/api.synaglobal.vip
user=root
autostart=true
autorestart=true
stderr_logfile=/var/log/nexus/error.log
stdout_logfile=/var/log/nexus/access.log
# ⚠️ 不要在这里硬编码密码！Supervisor 配置文件可能被其他用户读取
# 改用 .env 文件方式：uvicorn 会自动读取 .env

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start nexus

3.6 Nginx 反向代理配置

sudo nano /etc/nginx/sites-available/nexus

server {
    listen 80;
    server_name api.synaglobal.vip;

    # 强制 HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.synaglobal.vip;

    # SSL证书（宝塔面板 → 网站 → SSL → Let's Encrypt 一键申请）
    # 证书路径在宝塔面板申请后自动生成，以下为宝塔默认路径:
    ssl_certificate     /www/server/panel/vhost/cert/api.synaglobal.vip/fullchain.pem;
    ssl_certificate_key /www/server/panel/vhost/cert/api.synaglobal.vip/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    # Nexus API
    location /api/ {
        proxy_pass http://127.0.0.1:8600;
        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_send_timeout 300s;
    }

    # Nexus OpenAPI 文档
    location /docs {
        proxy_pass http://127.0.0.1:8600;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Nexus WebSocket
    location /ws/ {
        proxy_pass http://127.0.0.1:8600;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Nexus 新前端（Tailwind CSS v4）
    location /app/ {
        root /www/wwwroot/api.synaglobal.vip;
        try_files $uri $uri/ /app/login.html;
    }

    # PHP 页面（旧前端，逐步弃用）
    location / {
        root /www/wwwroot/api.synaglobal.vip;
        index index.php;
        try_files $uri $uri/ /index.php?$query_string;

        location ~ \.php$ {
            fastcgi_pass unix:/tmp/php-cgi-82.sock;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            include fastcgi_params;
        }
    }
}

sudo ln -s /etc/nginx/sites-available/nexus /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

---

4. 依赖冲突排查

4.1 常见问题

问题	原因	解决方案
pip install 报错 libbrotli	缺少 libbrotli-dev	sudo apt install -y libbrotli-dev
pip install 报错 libssl	缺少 libssl-dev	sudo apt install -y libssl-dev
pip install 报错 libcurl	缺少 libcurl4-openssl-dev	sudo apt install -y libcurl4-openssl-dev
PHP mbstring 编译失败	缺少 libonig-dev	sudo apt install -y libonig-dev
PHP xml/dom 编译失败	缺少 libxml2-dev	sudo apt install -y libxml2-dev
PHP zip 编译失败	缺少 libzip-dev	sudo apt install -y libzip-dev
libcurl4-openssl-dev 与 libcurl4-nss-dev 冲突	不能同时安装两个 curl dev 包	sudo apt remove libcurl4-nss-dev && sudo apt install libcurl4-openssl-dev
MySQL 编译报错缺少 bison/gperf	缺少 MySQL 编译依赖	sudo apt install -y bison gperf
Python decimal 模块报错	缺少 libmpdec-dev（Python 3.12+ 新依赖）	sudo apt install -y libmpdec-dev

4.2 快速检查缺少的依赖

# 检查某个库是否已安装
dpkg -l | grep libbrotli-dev
apt-cache search libbrotli

# 查看某个 pip 包需要哪些系统依赖
pip show <package-name>

---

5. 版本兼容性参考

组件	Ubuntu 20.04	Ubuntu 22.04	Ubuntu 24.04	说明
Python	3.8 (系统) → 需 deadsnakes PPA 安装 3.12	3.10 (系统) → deadsnakes PPA 安装 3.12	3.12 (系统)	推荐 3.12+
MySQL	8.0 (系统) → 可手动安装 8.4	8.0 (系统) → 可手动安装 8.4	8.4 可用	推荐 8.4 LTS
Redis	6.x (系统) → 需编译 7.x	6.x→7.x (系统)	7.x (系统)	推荐 7.0+
PHP	7.4 (系统) → 需 ondrej PPA 安装 8.2	8.1 (系统) → 需 PPA 安装 8.2/8.3	8.3 (系统)	推荐 8.2+
Nginx	1.18 (系统) → 可编译最新	1.22 (系统) → 可编译最新	1.24 (系统)	推荐 1.24+

---

6. 宝塔面板部署（推荐新手）

如果使用宝塔面板，大部分依赖和软件安装可以一键完成：

1. 安装宝塔面板: wget -O install.sh https://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh ed848235
2. 宝塔面板 → 软件商店 → 安装: Nginx / MySQL 8.4 / Redis 7 / PHP 8.2
3. 创建网站 → 设置根目录为 /opt/Nexus/web
4. 配置反向代理 → 将 /api/ 代理到 127.0.0.1:8600
5. SSL → Let's Encrypt 一键申请

宝塔面板会自动安装大部分系统依赖，但 Python pip 依赖仍需手动处理。如果 pip 安装报错，回到步骤 1 安装缺失的 -dev 包。

---

7. 验证部署

# 检查 Nexus API 是否运行
curl http://127.0.0.1:8600/docs  # 应返回 OpenAPI 文档页面

# 检查数据库连接
curl http://127.0.0.1:8600/api/settings/  # 应返回设置列表（初始为空）

# 检查 HTTPS（域名验证）
curl https://api.synaglobal.vip/docs  # 应返回 OpenAPI 文档页面
``