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+ |

---

## 快速安装

### 一键脚本安装（推荐）

```bash
# 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. 安装宝塔面板（如未安装）

```bash
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. 运行安装脚本

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

或者如果文件还没上传：

```bash
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` 后面粘贴：

```nginx
    # 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：**

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

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

### 2. 安装 MySQL 8.0

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

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

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

### 4. 部署 Nexus

```bash
# 创建目录
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

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

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

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

---

## 安装后配置

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

```bash
# 编辑 crontab
sudo crontab -e

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

### 数据库备份 Crontab

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

### 防火墙配置

```bash
# 只开放必要端口
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 页面）

---

## 升级

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

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

---

## 卸载

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

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

---

## 故障排查

### 端口 8600 无响应

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

### 数据库连接失败

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

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

### Redis 连接失败

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

### Supervisor 启动失败

```bash
# 检查配置语法
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`