Nexus/docs/install-guide.md

Nexus 6.0 安装指南

系统要求

组件	最低版本	推荐
操作系统	Ubuntu 20.04 / Debian 11 / CentOS 7	Ubuntu 22.04+
Python	3.10	3.12
MySQL	8.0	8.4
Redis	6.0	7.0
Nginx	1.18	最新稳定版
内存	1GB	2GB+
磁盘	5GB	20GB+

---

快速安装

一键脚本安装（推荐）

# 1. 下载并运行安装脚本
sudo bash install.sh --domain nexus.example.com

# 2. 打开浏览器完成 Web 安装向导
# http://nexus.example.com/app/install.html

脚本会自动检测环境、安装依赖、配置 Supervisor 和 Nginx。

参数说明

--domain DOMAIN       必填，域名或 IP
--deploy-dir PATH     安装目录（默认自动检测）
--port PORT           uvicorn 端口（默认 8600）
--skip-nginx          跳过 Nginx 配置
--skip-supervisor     跳过 Supervisor 配置
--repo URL            Git 仓库地址（可选）

---

宝塔面板安装指南

1. 安装宝塔面板（如未安装）

curl -sSO https://raw.githubusercontent.com/zhucaidan/btpanel-v7.0.3/main/install_panel.sh && bash install_panel.sh

2. 通过宝塔安装 MySQL 和 Redis

1. 宝塔面板 → 软件商店 → 搜索 MySQL 8.0 → 安装
2. 软件商店 → 搜索 Redis → 安装
3. 数据库 → 添加数据库：
   • 数据库名：nexus
   • 用户名：nexus
   • 密码：自动生成或自定义

3. 创建网站

1. 网站 → 添加站点
   • 域名：nexus.example.com
   • 根目录：/www/wwwroot/nexus.example.com
   • PHP版本：纯静态（不需要 PHP）
2. 记录网站根目录路径

4. 运行安装脚本

# 将 Nexus 文件上传到网站根目录后运行
cd /www/wwwroot/nexus.example.com
sudo bash deploy/install.sh --domain nexus.example.com --deploy-dir /www/wwwroot/nexus.example.com

或者如果文件还没上传：

sudo bash deploy/install.sh --domain nexus.example.com --repo https://your-gitea-url/Nexus.git

脚本会自动检测宝塔面板，配置写入正确的路径。

5. 配置 Supervisor

如果脚本未自动配置：

1. 宝塔面板 → 软件商店 → 搜索 Supervisor管理器 → 安装
2. Supervisor管理器 → 添加守护进程：
   • 名称：nexus
   • 启动命令：/www/wwwroot/nexus.example.com/venv/bin/uvicorn server.main:app --host 0.0.0.0 --port 8600
   • 运行目录：/www/wwwroot/nexus.example.com

6. 配置 Nginx

1. 网站 → nexus.example.com → 设置 → 配置文件
2. 在 #PHP-INFO-END 后面粘贴：

    # Nexus Python API + WebSocket
    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;
    }
    location ^~ /health {
        proxy_pass http://127.0.0.1:8600;
    }
    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 Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

3. 保存并重载

7. 配置 SSL

1. 网站 → nexus.example.com → SSL → Let's Encrypt
2. 申请证书 → 开启强制 HTTPS

8. 完成 Web 安装向导

打开浏览器访问 https://nexus.example.com/app/install.html，按向导完成：

• Step 2：环境检测
• Step 3：填写 MySQL 和 Redis 连接信息
• Step 4：创建管理员账号
• Step 5：安装完成

---

手动安装指南

1. 安装系统依赖

Ubuntu / Debian：

sudo apt update
sudo apt install -y python3 python3-venv python3-pip python3-dev \
    build-essential libssl-dev libffi-dev default-libmysqlclient-dev \
    git curl nginx supervisor

CentOS / Rocky / AlmaLinux：

sudo dnf install -y python3 python3-devel python3-pip \
    gcc openssl-devel libffi-devel mysql-devel \
    git curl nginx supervisor

2. 安装 MySQL 8.0

# Ubuntu
sudo apt install -y mysql-server
sudo mysql_secure_installation

# 创建数据库
sudo mysql -e "CREATE DATABASE nexus CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER 'nexus'@'localhost' IDENTIFIED BY 'YOUR_PASSWORD';"
sudo mysql -e "GRANT ALL PRIVILEGES ON nexus.* TO 'nexus'@'localhost';"
sudo mysql -e "FLUSH PRIVILEGES;"

3. 安装 Redis

# Ubuntu
sudo apt install -y redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server

# 验证
redis-cli ping  # 应返回 PONG

4. 部署 Nexus

# 创建目录
sudo mkdir -p /opt/nexus
cd /opt/nexus

# 克隆代码（或从发布包解压）
sudo git clone https://your-gitea-url/Nexus.git .

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

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

5. 配置 Supervisor

sudo tee /etc/supervisor/conf.d/nexus.conf << 'EOF'
[program:nexus]
command=/opt/nexus/venv/bin/uvicorn server.main:app --host 0.0.0.0 --port 8600 --workers 2 --loop uvloop --http httptools --log-level info
directory=/opt/nexus
user=root
autostart=true
autorestart=true
startretries=10
startsecs=3
stopwaitsecs=10
stopsignal=INT
environment=PATH="/opt/nexus/venv/bin:%(ENV_PATH)s",HOME="/root"
stderr_logfile=/var/log/nexus/error.log
stdout_logfile=/var/log/nexus/access.log
stderr_logfile_maxbytes=50MB
stdout_logfile_maxbytes=50MB
EOF

# 创建日志目录
sudo mkdir -p /var/log/nexus

# 重载 Supervisor
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start nexus

6. 配置 Nginx

sudo tee /etc/nginx/sites-available/nexus << 'EOF'
upstream nexus_api {
    server 127.0.0.1:8600;
    keepalive 32;
}

server {
    listen 80;
    server_name nexus.example.com;

    location / {
        proxy_pass http://nexus_api;
        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;
    }

    location /ws/ {
        proxy_pass http://nexus_api;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 3600s;
    }

    location ~ ^/(\.env|\.git) {
        return 404;
    }

    client_max_body_size 500m;

    access_log /var/log/nginx/nexus_access.log;
    error_log /var/log/nginx/nexus_error.log;
}
EOF

# 启用站点
sudo ln -sf /etc/nginx/sites-available/nexus /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

7. 完成 Web 安装向导

打开浏览器访问 http://nexus.example.com/app/install.html

8. 配置 SSL

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d nexus.example.com

---

安装后配置

健康检查 Crontab（第3层守护）

# 编辑 crontab
sudo crontab -e

# 添加（每分钟检查一次）
* * * * * /opt/nexus/deploy/health_monitor.sh

数据库备份 Crontab

# 每天凌晨3点自动备份，保留30天
0 3 * * * /opt/nexus/deploy/db_backup.sh

防火墙配置

# 只开放必要端口
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable

# 8600 端口不需要对外开放（Nginx 反向代理）

安全收尾清单

• 安装向导已自动锁定
• .env 文件包含 SECRET_KEY/API_KEY/ENCRYPTION_KEY — 安装后不可修改
• SSL 证书已配置，强制 HTTPS
• 8600 端口未对外开放
• 管理员密码已修改（非默认弱密码）
• Telegram 告警已配置（Settings 页面）

---

升级

sudo bash /opt/nexus/deploy/upgrade.sh

升级脚本会：git pull → pip install → supervisorctl restart → 健康检查。

---

卸载

sudo bash /opt/nexus/deploy/uninstall.sh          # 保留文件
sudo bash /opt/nexus/deploy/uninstall.sh --purge   # 同时删除部署目录

注意：MySQL 数据库不会被自动删除。需手动 DROP DATABASE nexus;

---

故障排查

端口 8600 无响应

supervisorctl status nexus           # 检查进程状态
tail -f /var/log/nexus/error.log     # 查看错误日志
curl http://127.0.0.1:8600/health    # 本地健康检查

Nginx 502 Bad Gateway

• 检查 uvicorn 是否运行：supervisorctl status nexus
• 检查端口匹配：Nginx upstream 端口和 uvicorn 端口是否一致
• 检查 Nginx 错误日志：tail -f /var/log/nginx/nexus_error.log

数据库连接失败

# 检查 MySQL 是否运行
sudo systemctl status mysql

# 测试连接
mysql -u nexus -p -h 127.0.0.1 nexus

Redis 连接失败

# 检查 Redis 是否运行
sudo systemctl status redis-server
redis-cli ping

Supervisor 启动失败

# 检查配置语法
supervisorctl reread

# 查看详细日志
tail -f /var/log/nexus/error.log

# 手动启动测试
cd /opt/nexus && source venv/bin/activate
uvicorn server.main:app --host 0.0.0.0 --port 8600

安装向导无法访问

• 检查 .env 文件是否存在：如果存在，安装向导会被锁定
• 删除 .env 可重新进入安装模式：rm /opt/nexus/.env && supervisorctl restart nexus