# 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  
> **生产域名**: 由 `NEXUS_CORS_ORIGINS` 环境变量配置（示例: `api.synaglobal.vip`）
> **网站目录**: 由 `NEXUS_DEPLOY_PATH` 环境变量配置（示例: `/www/wwwroot/api.synaglobal.vip`）  
> **更新日期**: 2026-05-20  

---

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

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

### 1.1 一键修复脚本

```bash
#!/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 手动逐项安装（如果脚本不适用）

按组件分类的依赖列表：

#### 通用依赖（所有组件都需要）
```bash
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 专用
```bash
sudo apt install -y libgd-dev libgeoip-dev libxslt1-dev
```

#### PHP 8.x 专用
```bash
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 专用
```bash
sudo apt install -y bison gperf libevent-dev libnuma-dev \
  libaio-dev protobuf-compiler libprotobuf-dev
```

#### Python 3.12+ 专用
```bash
sudo apt install -y libgdbm-dev libgdbm-compat-dev \
  libmpdec-dev uuid-dev
```

#### Redis 专用
```bash
sudo apt install -y libjemalloc-dev
```

---

## 2. 服务安装

### 2.1 Nginx

```bash
# 方式 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

```bash
# 方式 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

```bash
# 方式 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+

```bash
# 方式 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+

```bash
# 方式 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 克隆仓库

```bash
cd /opt
git clone http://<GITEA_HOST>/admin/Nexus.git  # 替换为实际 Gitea 地址
cd Nexus
```

### 3.2 Python 环境配置

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

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

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

### 3.3 配置文件

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

# 编辑 .env 文件
nano .env
```

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

```ini
# ⚠️ 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 数据库

```bash
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

```bash
# 方式 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` 内容：

```ini
[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
```

```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start nexus
```

### 3.6 Nginx 反向代理配置

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

```nginx
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;
        }
    }
}
```

```bash
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 快速检查缺少的依赖

```bash
# 检查某个库是否已安装
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. 验证部署

```bash
# 检查 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 文档页面
``