Codex Release Bot
511 lines
14 KiB
Markdown
511 lines
14 KiB
Markdown
# 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 文档页面
|
||
`` |