zjpb.net/docs/deployment/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或命令行导入：

-- 如果你有数据库备份文件，可以直接导入
-- 否则在部署后通过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虚拟环境

cd /www/wwwroot/zjpb

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

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

# 升级pip
pip install --upgrade pip

3.3 安装Python依赖

pip install -r requirements.txt

3.4 配置环境变量

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

nano .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：

python3 -c "import secrets; print(secrets.token_hex(32))"

3.5 创建必要的目录

# 创建日志目录
mkdir -p logs

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

# 设置权限
chmod 755 logs static/uploads

---

四、初始化数据库

4.1 运行初始化脚本

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配置：

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没有内置，手动创建：

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

配置内容：

[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 启动服务

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

# 启动应用
supervisorctl start zjpb

# 查看状态
supervisorctl status zjpb

---

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

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

7.1 创建systemd服务文件

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

内容：

[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 启动服务

# 重新加载systemd
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start zjpb

# 设置开机自启
sudo systemctl enable zjpb

# 查看状态
sudo systemctl status zjpb

---

八、验证部署

8.1 检查服务状态

# 查看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：

supervisorctl restart zjpb

使用systemd：

sudo systemctl restart zjpb

9.2 查看日志

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

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

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

9.3 更新代码

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 配置防火墙

# 只允许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 应用无法启动

检查日志：

tail -f logs/error.log

常见问题：

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

11.2 静态文件404

检查Nginx配置和目录权限：

ls -la static/
chmod -R 755 static/

11.3 数据库连接失败

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

# 检查MySQL服务
sudo systemctl status mysql

---

十二、备份策略

12.1 数据库备份

创建定时任务：

crontab -e

添加每日备份：

0 2 * * * mysqldump -u ai_nav_user -p密码 ai_nav > /www/backup/zjpb_$(date +\%Y\%m\%d).sql

12.2 文件备份

# 备份上传的文件
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

祝部署顺利！🚀