admin/Nexus
1
0
Fork 0
Code Issues Pull Requests Actions 91 Packages Projects Releases Wiki Activity
Files
8363746cf62b6d5de8d9df88500d4b4c7b6e62a0
Nexus/docs/project/deploy.md
T

511 lines
14 KiB
Markdown
Raw Normal View History

release: nexus btpanel session fix and app-v2
2026-07-08 22:31:31 +08:00
# 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 文档页面
``
Reference in New Issue Copy Permalink