zjpb.net/DEPLOYMENT.md

# ZJPB - 焦提示词 部署文档

## 1Panel部署指南

### 前置要求
- 1Panel管理面板已安装
- MySQL 5.7+ 或 MariaDB
- Python 3.8+
- Nginx（1Panel自带）

---

## 一、数据库准备

### 1.1 在1Panel中创建MySQL数据库

1. 登录1Panel管理面板
2. 进入「数据库」菜单
3. 点击「创建数据库」
4. 填写信息：
   - 数据库名：`ai_nav`
   - 用户名：`ai_nav_user`
   - 密码：自动生成或自定义（记录下来）
   - 权限：本地访问
5. 点击创建

### 1.2 导入数据库结构

使用1Panel的phpMyAdmin或命令行导入：

```sql
-- 如果你有数据库备份文件，可以直接导入
-- 否则在部署后通过init_db.py初始化
```

---

## 二、上传项目文件

### 2.1 压缩项目

在本地Windows环境压缩项目文件夹为 `zjpb.zip`，**排除以下文件/文件夹**：
- `__pycache__/`
- `*.pyc`
- `.git/`
- `.env`（生产环境重新配置）
- `venv/` 或 `env/`
- `test_*.py`（测试文件）

### 2.2 上传到服务器

1. 在1Panel中进入「文件」菜单
2. 导航到 `/opt/1panel/apps/` 或你的网站目录（如 `/www/wwwroot/`）
3. 创建项目目录：`zjpb`
4. 上传 `zjpb.zip` 并解压
5. 最终路径示例：`/www/wwwroot/zjpb/`

---

## 三、环境配置

### 3.1 SSH连接到服务器

使用1Panel的终端或SSH工具连接服务器

### 3.2 创建Python虚拟环境

```bash
cd /www/wwwroot/zjpb

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate

# 升级pip
pip install --upgrade pip
```

### 3.3 安装Python依赖

```bash
pip install -r requirements.txt
```

### 3.4 配置环境变量

创建生产环境的 `.env` 文件：

```bash
nano .env
```

填写以下内容（**修改为实际值**）：

```env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=ai_nav_user
DB_PASSWORD=你的数据库密码
DB_NAME=ai_nav

# 安全配置（生成随机密钥）
SECRET_KEY=your-production-secret-key-change-this

# 运行环境
FLASK_ENV=production

# DeepSeek API配置（可选）
DEEPSEEK_API_KEY=你的DeepSeek_API密钥
DEEPSEEK_BASE_URL=https://api.deepseek.com
```

**生成安全的SECRET_KEY**：
```bash
python3 -c "import secrets; print(secrets.token_hex(32))"
```

### 3.5 创建必要的目录

```bash
# 创建日志目录
mkdir -p logs

# 创建静态文件上传目录
mkdir -p static/uploads

# 设置权限
chmod 755 logs static/uploads
```

---

## 四、初始化数据库

### 4.1 运行初始化脚本

```bash
source venv/bin/activate
python init_db.py
```

这会创建所有表并创建默认管理员账号：
- 用户名：`admin`
- 密码：`admin123`

**⚠️ 重要：登录后立即修改默认密码！**

---

## 五、配置Nginx反向代理

### 5.1 在1Panel中创建网站

1. 进入1Panel「网站」菜单
2. 点击「创建网站」
3. 填写信息：
   - 网站类型：反向代理
   - 域名：`your-domain.com`（或IP）
   - 代理地址：`http://127.0.0.1:5000`
   - 启用SSL：推荐（自动申请Let's Encrypt证书）

### 5.2 自定义Nginx配置（可选）

如果需要自定义，编辑Nginx配置：

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 如果启用SSL，这里会自动重定向到443

    client_max_body_size 10M;  # 允许上传文件大小

    location / {
        proxy_pass http://127.0.0.1:5000;
        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;

        # WebSocket支持（如果需要）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # 静态文件直接由Nginx处理
    location /static/ {
        alias /www/wwwroot/zjpb/static/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}
```

---

## 六、配置Supervisor守护进程

### 6.1 在1Panel中使用Supervisor

1. 进入1Panel「容器」→「应用编排」或「进程管理」
2. 创建新的守护进程配置

### 6.2 创建Supervisor配置文件

如果1Panel没有内置，手动创建：

```bash
nano /etc/supervisor/conf.d/zjpb.conf
```

配置内容：

```ini
[program:zjpb]
command=/www/wwwroot/zjpb/venv/bin/gunicorn -c gunicorn_config.py app:app
directory=/www/wwwroot/zjpb
user=www
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/www/wwwroot/zjpb/logs/supervisor.log
environment=FLASK_ENV="production"
```

### 6.3 启动服务

```bash
# 重新加载Supervisor配置
supervisorctl reread
supervisorctl update

# 启动应用
supervisorctl start zjpb

# 查看状态
supervisorctl status zjpb
```

---

## 七、使用systemd守护进程（替代方案）

如果不使用Supervisor，可以用systemd：

### 7.1 创建systemd服务文件

```bash
sudo nano /etc/systemd/system/zjpb.service
```

内容：

```ini
[Unit]
Description=ZJPB AI Navigation Flask Application
After=network.target mysql.service

[Service]
Type=notify
User=www
Group=www
WorkingDirectory=/www/wwwroot/zjpb
Environment="PATH=/www/wwwroot/zjpb/venv/bin"
Environment="FLASK_ENV=production"
ExecStart=/www/wwwroot/zjpb/venv/bin/gunicorn -c gunicorn_config.py app:app
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

### 7.2 启动服务

```bash
# 重新加载systemd
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start zjpb

# 设置开机自启
sudo systemctl enable zjpb

# 查看状态
sudo systemctl status zjpb
```

---

## 八、验证部署

### 8.1 检查服务状态

```bash
# 查看gunicorn进程
ps aux | grep gunicorn

# 查看日志
tail -f logs/error.log
tail -f logs/access.log
```

### 8.2 访问网站

1. 前台访问：`http://your-domain.com`
2. 后台访问：`http://your-domain.com/admin/login`
   - 用户名：`admin`
   - 密码：`admin123`（首次登录后立即修改）

---

## 九、常用管理命令

### 9.1 重启应用

**使用Supervisor：**
```bash
supervisorctl restart zjpb
```

**使用systemd：**
```bash
sudo systemctl restart zjpb
```

### 9.2 查看日志

```bash
# 应用日志
tail -f logs/error.log

# Nginx访问日志
tail -f /www/server/nginx/logs/your-domain.com.log

# Supervisor日志
tail -f logs/supervisor.log
```

### 9.3 更新代码

```bash
cd /www/wwwroot/zjpb

# 备份数据库
mysqldump -u ai_nav_user -p ai_nav > backup_$(date +%Y%m%d).sql

# 拉取新代码或上传新文件
# ...

# 激活虚拟环境
source venv/bin/activate

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

# 重启应用
supervisorctl restart zjpb
# 或
sudo systemctl restart zjpb
```

---

## 十、安全加固

### 10.1 修改默认管理员密码

登录后台后立即修改密码：
1. 访问：`/admin/change-password`
2. 输入旧密码：`admin123`
3. 设置新的强密码

### 10.2 配置防火墙

```bash
# 只允许80和443端口（1Panel通常已配置）
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
```

### 10.3 配置SSL证书

在1Panel中为网站启用SSL：
1. 进入网站设置
2. 启用SSL
3. 选择Let's Encrypt免费证书
4. 自动申请并配置

---

## 十一、故障排查

### 11.1 应用无法启动

检查日志：
```bash
tail -f logs/error.log
```

常见问题：
- 数据库连接失败：检查`.env`配置
- 端口被占用：修改`gunicorn_config.py`中的端口
- 权限问题：确保文件所有者为`www`用户

### 11.2 静态文件404

检查Nginx配置和目录权限：
```bash
ls -la static/
chmod -R 755 static/
```

### 11.3 数据库连接失败

```bash
# 测试数据库连接
mysql -u ai_nav_user -p ai_nav

# 检查MySQL服务
sudo systemctl status mysql
```

---

## 十二、备份策略

### 12.1 数据库备份

创建定时任务：
```bash
crontab -e
```

添加每日备份：
```cron
0 2 * * * mysqldump -u ai_nav_user -p密码 ai_nav > /www/backup/zjpb_$(date +\%Y\%m\%d).sql
```

### 12.2 文件备份

```bash
# 备份上传的文件
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz static/uploads/
```

---

## 支持与帮助

如有问题，请检查：
1. 应用日志：`logs/error.log`
2. Nginx日志：`/www/server/nginx/logs/`
3. 系统日志：`journalctl -u zjpb -f`

祝部署顺利！🚀