jowelin/zjpb.net
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: v2.6.0 - API安全优化和文档整合

Browse Source 
## 核心优化
- 移除详情页自动调用博查API的逻辑，改为按需加载
- 添加基于IP的频率限制（每小时3次）
- 实现验证码防护机制（超过阈值后要求验证）
- 新增频率限制工具类 utils/rate_limiter.py

## 成本控制
- API调用减少约90%+（只在用户点击时调用）
- 防止恶意滥用和攻击
- 可配置的频率限制和验证码策略

## 文档整合
- 创建 docs/ 目录结构
- 归档历史版本文档到 docs/archive/
- 移动部署文档到 docs/deployment/
- 添加文档索引 docs/README.md

## 技术变更
- 新增依赖: Flask-Limiter==3.5.0
- 修改: app.py (移除自动调用，新增API端点)
- 修改: templates/detail_new.html (按需加载UI)
- 新增: utils/rate_limiter.py (频率限制和验证码)
- 新增: docs/archive/DEVELOP_v2.6.0_API_SECURITY.md

## 部署说明
1. pip install Flask-Limiter==3.5.0
2. 重启应用
3. 无需数据库迁移

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jowe
2026-02-06 15:54:13 +08:00
parent c1a06ad684
commit 939717fa57
27 changed files with 1670 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

358
docs/deployment/1PANEL_DEPLOY.md Normal file
View File

@@ -0,0 +1,358 @@
# 1Panel Web界面部署指南
## 使用1Panel Web界面部署ZJPB项目
### 前提条件
- 1Panel已安装并可访问
- 1Panel版本支持Python项目管理
---
## 方式一：使用1Panel的运行时环境（推荐）
### 步骤1：准备项目文件
1. **压缩项目**
- 在本地压缩整个项目文件夹
- 排除：`venv/`, `__pycache__/`, `.env`, `test_*.py`, `logs/`
### 步骤2：在1Panel中创建数据库
1. 登录1Panel管理面板
2. 进入 **数据库** 菜单
3. 点击 **创建数据库**
4. 填写信息：
```
数据库名：ai_nav
用户名：ai_nav_user
密码：（自动生成或自定义）
权限：本地访问
```
5. 点击确定，**记录数据库密码**
### 步骤3：上传项目文件
1. 进入 **文件** 菜单
2. 导航到网站目录（如 `/www/wwwroot/`）
3. 创建项目目录 `zjpb`
4. 上传并解压 `zjpb.zip`
### 步骤4：配置环境变量
1. 在项目目录中，找到 `.env.example` 文件
2. 复制为 `.env`
3. 点击编辑，填写配置：
```env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=ai_nav_user
DB_PASSWORD=你的数据库密码
DB_NAME=ai_nav
# 安全配置
SECRET_KEY=你的密钥（使用下方命令生成）
FLASK_ENV=production
# DeepSeek API（可选）
DEEPSEEK_API_KEY=sk-xxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com
```
生成SECRET_KEY：
```bash
# 在1Panel终端执行
python3 -c "import secrets; print(secrets.token_hex(32))"
```
### 步骤5：使用1Panel创建Python项目
#### 5.1 进入网站管理
1. 点击 **网站** 菜单
2. 点击 **创建网站**
3. 选择 **运行时** 类型
#### 5.2 配置Python项目
填写以下信息：
**基本设置：**
```
网站类型：运行时
运行时：Python
域名：your-domain.com（或IP地址）
代码目录：/www/wwwroot/zjpb
```
**Python设置：**
```
Python版本：选择 3.8+ 的版本
应用类型：选择 "Flask" 或 "其他"
启动文件：app.py
启动命令：gunicorn -c gunicorn_config.py app:app
端口：5000（默认）
```
**环境变量：**（如果1Panel支持在界面配置）
```
FLASK_ENV=production
```
**其他选项：**
```
☑ 自动启动
☑ 守护进程
进程数：4
```
#### 5.3 安装依赖
1. 创建网站后，1Panel会自动创建虚拟环境
2. 进入网站设置
3. 找到 **依赖管理** 或 **包管理**
4. 上传 `requirements.txt` 或手动安装
5. 点击 **安装依赖**
或者使用1Panel的终端：
```bash
# 进入项目目录
cd /www/wwwroot/zjpb
# 激活虚拟环境（1Panel自动创建的）
source venv/bin/activate
# 安装依赖
pip install -r requirements.txt
```
### 步骤6：初始化数据库
1. 在1Panel中打开 **终端** 或 SSH连接
2. 执行：
```bash
cd /www/wwwroot/zjpb
source venv/bin/activate
python init_db.py
```
### 步骤7：启动和管理
1. 在1Panel网站列表中找到你的项目
2. 点击 **启动** 按钮
3. 查看状态：运行中 ✓
### 步骤8：配置反向代理（如果需要）
如果1Panel没有自动配置Nginx：
1. 进入网站设置
2. 找到 **反向代理** 或 **代理配置**
3. 配置：
```
目标地址：http://127.0.0.1:5000
```
### 步骤9：配置SSL证书（推荐）
1. 在网站设置中找到 **SSL**
2. 选择 **Let's Encrypt**
3. 点击申请证书
4. 启用 **强制HTTPS**
### 步骤10：访问验证
1. 前台：`https://your-domain.com`
2. 后台：`https://your-domain.com/admin/login`
- 默认用户名：`admin`
- 默认密码：`admin123`
3. **立即修改密码**：访问 `/admin/change-password`
---
## 方式二：使用1Panel的OpenResty/Nginx + Supervisor
如果1Panel的Python运行时不支持或不稳定，可以使用传统方式：
### 步骤1-4：同上（数据库、文件上传、环境配置）
### 步骤5：手动创建虚拟环境
```bash
cd /www/wwwroot/zjpb
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
### 步骤6：创建Supervisor配置
1. 在1Panel中进入 **容器** 或 **进程管理**
2. 如果有Supervisor功能，创建新任务
或手动创建配置文件：
```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"
```
启动：
```bash
supervisorctl reread
supervisorctl update
supervisorctl start zjpb
```
### 步骤7：创建反向代理网站
1. 在1Panel **网站** 菜单中点击 **创建网站**
2. 选择 **反向代理**
3. 填写：
```
域名：your-domain.com
代理地址：http://127.0.0.1:5000
```
### 步骤8：配置SSL
同方式一
---
## 常见问题
### Q1: 1Panel在哪里创建Python项目？
**A:**
- 进入 **网站** 菜单
- 点击 **创建网站**
- 选择 **运行时** 或 **Runtime**
- 选择 **Python**
### Q2: 找不到虚拟环境？
**A:**
- 1Panel创建的虚拟环境通常在项目目录下的 `venv/` 文件夹
- 路径：`/www/wwwroot/zjpb/venv/`
- 可以在文件管理器中查看
### Q3: 如何查看应用日志？
**A:**
- 方式1：在网站管理中点击 **日志** 按钮
- 方式2：查看文件 `logs/error.log`
- 方式3：使用1Panel的终端：`tail -f logs/error.log`
### Q4: 如何重启应用？
**A:**
- 方式1：在1Panel网站列表中点击 **重启** 按钮
- 方式2：使用管理脚本：`./manage.sh restart`
- 方式3：Supervisor：`supervisorctl restart zjpb`
### Q5: 端口被占用怎么办？
**A:**
修改 `gunicorn_config.py` 中的端口：
```python
bind = "0.0.0.0:5001" # 改为其他端口
```
然后在反向代理中也修改为对应端口。
---
## 管理和维护
### 更新代码
1. 在1Panel文件管理中上传新文件
2. 在网站管理中点击 **重启**
### 查看状态
1. 进入网站列表
2. 查看状态指示灯
3. 点击网站名称查看详细信息
### 备份数据库
1. 进入 **数据库** 菜单
2. 找到 `ai_nav` 数据库
3. 点击 **备份** 按钮
### 监控日志
1. 在网站设置中找到 **日志** 选项
2. 查看访问日志和错误日志
3. 可以设置日志轮转
---
## 推荐配置
### 生产环境推荐配置
```
服务器配置：
- CPU: 2核+
- 内存: 2GB+
- 硬盘: 20GB+
Python版本：
- Python 3.8+
数据库：
- MySQL 5.7+
- MariaDB 10.3+
Web服务器：
- Nginx (1Panel自带)
进程管理：
- Supervisor 或 1Panel内置
工作进程数：
- gunicorn workers: 4
- gunicorn threads: 2
```
---
## 安全建议
1. ✅ 修改默认管理员密码
2. ✅ 使用强密码的SECRET_KEY
3. ✅ 启用HTTPS (Let's Encrypt)
4. ✅ 定期备份数据库
5. ✅ 设置文件权限：
```bash
chmod 600 .env
chmod 755 static/uploads
```
6. ✅ 配置防火墙（1Panel通常自动配置）
---
## 获取帮助
如果遇到问题：
1. 查看 `logs/error.log` 日志文件
2. 检查1Panel的系统日志
3. 验证数据库连接
4. 检查端口是否被占用
5. 确认虚拟环境依赖已安装
祝部署顺利！🎉

180
docs/deployment/1PANEL_QUICK.md Normal file
View File

@@ -0,0 +1,180 @@
# 1Panel快速部署向导
## 🎯 使用1Panel Web界面 - 5步完成部署
### 📋 准备工作
- [x] 1Panel已安装
- [x] 项目文件已压缩（zjpb.zip）
---
## 第1步：创建数据库（2分钟）
1. 登录1Panel → **数据库**
2. 点击 **创建数据库**
3. 填写：
- 数据库名：`ai_nav`
- 用户名：`ai_nav_user`
- 密码：自动生成（**记录下来！**）
4. 确定
---
## 第2步：上传项目（3分钟）
1. **文件** → 导航到 `/www/wwwroot/`
2. 创建文件夹 `zjpb`
3. 上传 `zjpb.zip`
4. 解压缩
5. 编辑 `.env.example` → 另存为 `.env`
6. 填写数据库密码和密钥
---
## 第3步：创建Python网站（5分钟）
### 方式A：使用1Panel的Python运行时（推荐）
1. **网站** → **创建网站**
2. 类型：**运行时 (Runtime)**
3. 配置：
```
运行时：Python 3.8+
应用类型：Flask
域名：your-domain.com
代码目录：/www/wwwroot/zjpb
启动文件：app.py
启动命令：gunicorn -c gunicorn_config.py app:app
端口：5000
☑ 自动启动
```
4. 创建
### 方式B：使用反向代理（备选）
如果没有Python运行时选项：
1. **网站** → **创建网站**
2. 类型：**反向代理**
3. 配置：
```
域名：your-domain.com
代理地址：http://127.0.0.1:5000
```
然后SSH到服务器手动启动（参考完整文档）
---
## 第4步：安装依赖和初始化（5分钟）
### 4.1 打开1Panel终端
点击1Panel右上角 **终端** 图标，或SSH连接
### 4.2 安装依赖
```bash
cd /www/wwwroot/zjpb
# 激活1Panel创建的虚拟环境
source venv/bin/activate
# 安装依赖
pip install -r requirements.txt
```
### 4.3 初始化数据库
```bash
python init_db.py
```
看到成功提示后，记住默认账号：
- 用户名：`admin`
- 密码：`admin123`
---
## 第5步：启动和访问（2分钟）
### 5.1 启动应用
**在1Panel界面：**
1. 进入 **网站** 列表
2. 找到你的项目
3. 点击 **启动** 按钮
4. 状态变为 **运行中 ✓**
### 5.2 配置SSL（推荐）
1. 点击网站名称进入设置
2. 找到 **SSL** 选项
3. 选择 **Let's Encrypt**
4. 申请证书
5. 启用 **强制HTTPS**
### 5.3 访问网站
- 前台：`https://your-domain.com`
- 后台：`https://your-domain.com/admin/login`
### 5.4 修改密码（重要！）
1. 登录后台（admin / admin123）
2. 点击左侧菜单 **修改密码**
3. 设置新密码
---
## ✅ 完成！
现在你的网站已经部署完成并运行了！
---
## 🔧 常用操作
### 重启应用
- 1Panel界面：网站列表 → 点击 **重启**
### 查看日志
- 1Panel界面：网站设置 → **日志**
- 或查看文件：`/www/wwwroot/zjpb/logs/error.log`
### 备份数据库
- 1Panel界面：数据库 → 选择 `ai_nav` → **备份**
### 更新代码
1. 上传新文件到项目目录
2. 重启应用
---
## ❓ 常见问题
**Q: 找不到Python运行时选项？**
- 使用反向代理方式，然后手动启动应用
- 参考：`1PANEL_DEPLOY.md` 方式二
**Q: 虚拟环境在哪？**
- 1Panel自动创建在：`/www/wwwroot/zjpb/venv/`
**Q: 启动失败？**
1. 查看日志：`logs/error.log`
2. 检查 `.env` 配置
3. 确认数据库连接
4. 验证依赖已安装
**Q: 需要修改端口？**
- 编辑 `gunicorn_config.py`，修改 `bind` 参数
---
## 📚 更多帮助
- 完整文档：`1PANEL_DEPLOY.md`
- 传统部署：`DEPLOYMENT.md`
- 检查清单：`DEPLOY_CHECKLIST.md`
祝部署顺利！🚀

92
docs/deployment/CHECK_GIT.md Normal file
View File

@@ -0,0 +1,92 @@
# 检查生产服务器Git配置
## 方法1：通过SSH命令检查
```bash
# SSH登录到生产服务器
ssh root@your-server-ip
# 检查git是否安装
git --version
# 如果显示版本号，说明已安装，例如：
# git version 2.30.2
# 如果显示 "command not found"，说明未安装
```
## 方法2：通过1Panel面板检查
```bash
# 1. 登录1Panel管理面板
# 2. 进入 "主机" -> "终端"
# 3. 输入命令：
git --version
```
## 方法3：检查项目目录是否有.git
```bash
# SSH登录后
cd /www/wwwroot/zjpb
ls -la | grep .git
# 如果显示 .git 目录，说明项目已经是git仓库
# 可以直接使用 git pull
```
---
## 如果Git未安装
### CentOS/RHEL系统：
```bash
yum install -y git
```
### Ubuntu/Debian系统：
```bash
apt update
apt install -y git
```
### 验证安装：
```bash
git --version
```
---
## 如果项目目录没有.git（需要初始化）
```bash
cd /www/wwwroot/zjpb
# 初始化git仓库
git init
# 添加远程仓库（如果你有GitHub/Gitee等）
git remote add origin https://github.com/yourusername/zjpb.git
# 或者使用SSH方式
git remote add origin git@github.com:yourusername/zjpb.git
# 拉取代码
git pull origin master
```
---
## 推荐：使用Git部署的优势
✅ **版本控制** - 可以随时回滚到之前的版本
✅ **增量更新** - 只传输修改的文件，速度快
✅ **操作简单** - 一条命令完成更新
✅ **团队协作** - 多人开发更方便
## 如果不用Git，手动部署也可以
可以使用FTP/SFTP工具上传文件：
- FileZilla（免费）
- WinSCP（免费）
- 1Panel自带的文件管理器

463
docs/deployment/DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,463 @@
# 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`
祝部署顺利！🚀

232
docs/deployment/GIT_PATCH_DEPLOY.md Normal file
View File

@@ -0,0 +1,232 @@
# ZJPB v2.1 Git Patch 部署指南（最简单）
## ✨ 优势
- ✅ **最干净** - 使用Git patch，保持版本历史完整
- ✅ **最安全** - 自动备份未提交的修改
- ✅ **最快速** - 只需上传2个文件（89KB）
- ✅ **可追溯** - 所有更改都有Git记录
---
## 📦 需要上传的文件（仅2个）
1. `v2.1.0.patch` (89KB) - 代码补丁文件
2. `git_patch_deploy.sh` - 自动化部署脚本
---
## 🚀 部署步骤
### 第一步：备份生产数据库（在1Panel中操作）
1. 登录1Panel管理面板
2. 进入 **数据库** → 找到 `ai_nav` 数据库
3. 点击 **备份** 按钮
4. 下载备份文件保存
### 第二步：上传文件到服务器
**方法1：使用1Panel文件管理器**
1. 登录1Panel
2. 进入 **文件** → 导航到 `/opt/1panel/apps/zjpb/`
3. 上传文件：
- `v2.1.0.patch`
- `git_patch_deploy.sh`
**方法2：使用命令行（如果你用SSH）**
```bash
# 在本地（Windows）使用SCP上传
scp v2.1.0.patch root@your-server-ip:/opt/1panel/apps/zjpb/
scp git_patch_deploy.sh root@your-server-ip:/opt/1panel/apps/zjpb/
```
### 第三步：执行部署脚本
在1Panel终端或SSH中执行：
```bash
# 进入项目目录
cd /opt/1panel/apps/zjpb
# 赋予执行权限
chmod +x git_patch_deploy.sh
# 执行部署
./git_patch_deploy.sh
```
**脚本会自动完成：**
1. ✅ 停止应用
2. ✅ 检查Git状态
3. ✅ 备份未提交的修改（如有）
4. ✅ 应用v2.1.0补丁
5. ✅ 提交到Git
6. ✅ 安装依赖
7. ✅ 运行数据库迁移（创建prompt_templates表）
8. ✅ 重启应用
9. ✅ 检查状态
**预期输出：**
```
================================
ZJPB v2.1 Git Patch 部署
================================
当前目录: /opt/1panel/apps/zjpb
1. 停止应用...
2. 检查Git状态...
3. 备份当前修改（如有）...
4. 应用v2.1.0补丁...
✅ 补丁应用成功
5. 提交更改到Git...
6. 激活虚拟环境...
7. 检查依赖...
8. 运行数据库迁移...
正在创建 prompt_templates 表...
[OK] 表创建成功
[OK] 默认prompt模板初始化成功
9. 重启应用...
10. 检查应用状态...
zjpb 正在运行 (PID: xxxx)
================================
✅ 部署完成！
================================
```
### 第四步：验证部署
**前台验证：**
1. 访问首页，检查页脚：
- `© 2025 ZJPB - 焦提示词 | AI工具导航`
- `浙ICP备2025154782号-1`
- 打开F12检查Network，确认Clarity统计已加载
2. 访问任意网站详情页，检查图标：
- 返回首页：`←` 而不是 `arrow_back`
- 访问网站：`↗` 而不是 `north_east`
- 浏览次数：`👁` 而不是 `visibility`
**后台验证：**
1. 登录 `/admin/login`
2. 左侧菜单应该有 **Prompt管理**
3. 点击进入，查看3条默认模板：
- 标签生成
- 主要功能生成
- 详细介绍生成
4. 进入 **网站管理** → 编辑任意网站
5. 标签区域应该正常显示标签名称（蓝色标签，有文字）
**AI功能验证：**
1. 编辑或创建网站
2. 测试 **AI生成标签** 按钮
3. 测试 **AI生成详细介绍** 按钮
4. 测试 **AI生成主要功能** 按钮
---
## 🔍 部署后检查
查看Git提交历史：
```bash
cd /opt/1panel/apps/zjpb
git log --oneline -5
```
应该看到最新的提交：
```
xxxxxxx release: v2.1.0 - Prompt管理系统、页脚优化、图标修复
```
查看应用状态：
```bash
./manage.sh status
```
查看应用日志（如有问题）：
```bash
./manage.sh logs
```
---
## 🔄 回滚方案（如出现问题）
```bash
cd /opt/1panel/apps/zjpb
# 停止应用
./manage.sh stop
# 回滚到上一个提交
git reset --hard HEAD~1
# 如果有stash的备份，恢复它
git stash list
git stash pop
# 重启应用
./manage.sh start
```
---
## 📝 注意事项
1. ✅ 服务器路径是 `/opt/1panel/apps/zjpb` 不是 `/www/wwwroot/zjpb`
2. ✅ 已确认服务器有Git仓库
3. ✅ patch文件会自动保存现有未提交的修改
4. ✅ 部署过程中会自动运行数据库迁移
5. ✅ 所有更改都会提交到Git，可随时回滚
---
## 🎯 完整部署命令（复制粘贴）
```bash
# 1. 进入项目目录
cd /opt/1panel/apps/zjpb
# 2. 检查文件是否上传成功
ls -lh v2.1.0.patch git_patch_deploy.sh
# 3. 赋予执行权限
chmod +x git_patch_deploy.sh
# 4. 执行部署
./git_patch_deploy.sh
# 5. 部署完成后验证
./manage.sh status
git log --oneline -3
```
---
## ✅ 部署检查清单
- [ ] 生产数据库已备份
- [ ] v2.1.0.patch 已上传到服务器
- [ ] git_patch_deploy.sh 已上传到服务器
- [ ] 部署脚本执行成功
- [ ] 前台页脚显示正确（ICP+统计）
- [ ] 详情页图标显示正确（Emoji）
- [ ] 后台Prompt管理菜单存在
- [ ] 标签显示正常（有文字）
- [ ] AI生成功能测试通过
---
## 💡 优势说明
相比手动上传11个文件，Git patch方式：
- 只需上传2个文件（89KB）
- 自动处理文件合并
- 保留完整Git历史
- 可以一键回滚
- 更安全可靠

208
docs/deployment/INCREMENTAL_DEPLOY.md Normal file
View File

@@ -0,0 +1,208 @@
# ZJPB v2.1 增量部署指南
## 📋 本次更新内容
### 新增功能
1. **Prompt管理系统** - 后台可管理AI提示词模板
2. **详情页图标优化** - Material Icons替换为Emoji
3. **标签显示修复** - 修复编辑页标签名称无法显示问题
4. **页脚优化** - 添加ICP备案号和Microsoft Clarity统计
### 数据库变更
- 新增表：`prompt_templates` （Prompt模板表）
- 无现有表结构变更，完全兼容旧数据
---
## 🔒 增量部署步骤
### 第一步：备份生产数据库（必须！）
在1Panel中备份数据库：
```bash
# 方法1：使用1Panel面板
1. 进入1Panel -> 数据库
2. 找到 ai_nav 数据库
3. 点击"备份"按钮
4. 下载备份文件到本地保存
# 方法2：使用命令行
mysqldump -h 112.124.42.38 -u ai_nav_user -p ai_nav > backup_$(date +%Y%m%d_%H%M%S).sql
```
### 第二步：停止生产应用
```bash
# SSH登录到生产服务器
ssh root@your-server-ip
# 进入应用目录
cd /www/wwwroot/zjpb
# 停止应用
./manage.sh stop
```
### 第三步：备份现有代码
```bash
# 创建备份目录
cd /www/wwwroot
cp -r zjpb zjpb_backup_$(date +%Y%m%d_%H%M%S)
```
### 第四步：上传新代码
**方法1：使用Git（推荐）**
```bash
# 在本地提交所有修改
git add .
git commit -m "release: v2.1 - Prompt管理系统、页脚优化、图标修复"
git push origin master
# 在服务器上拉取
cd /www/wwwroot/zjpb
git pull origin master
```
**方法2：手动上传**
```bash
# 在本地压缩（排除不需要的文件）
zip -r zjpb_v2.1.zip . -x "*.pyc" "*__pycache__*" "*.git*" ".env" "venv/*" "test_*.py" "*.db" "nul"
# 上传到服务器 /www/wwwroot/zjpb_new.zip
# 然后解压覆盖
cd /www/wwwroot/zjpb
unzip -o ../zjpb_new.zip
```
### 第五步：安装新依赖（如有）
```bash
cd /www/wwwroot/zjpb
source venv/bin/activate
pip install -r requirements.txt
```
### 第六步：运行数据库迁移
```bash
# 激活虚拟环境
source venv/bin/activate
# 运行迁移脚本（创建 prompt_templates 表）
python migrate_prompts.py
```
**预期输出：**
```
正在创建 prompt_templates 表...
[OK] 表创建成功
正在初始化默认prompt模板...
[OK] 默认prompt模板初始化成功
- 标签生成: 1
- 主要功能生成: 2
- 详细介绍生成: 3
```
### 第七步：重启应用
```bash
./manage.sh start
```
### 第八步：验证部署
**检查项：**
1. **访问前台首页**
- 检查页脚是否显示ICP备案号
- 检查Clarity统计是否加载（F12查看Network）
2. **访问详情页**
- 检查图标是否正常显示（不是Material Icons文本）
3. **登录后台**
- 检查是否有"Prompt管理"菜单
- 进入Prompt管理，查看是否有3条默认数据
4. **测试网站编辑**
- 编辑任意网站，检查标签是否正常显示（不是空白蓝框）
5. **测试AI功能**
- 创建新网站，测试"AI生成标签"功能
- 测试"AI生成详细介绍"功能
- 测试"AI生成主要功能"功能
---
## 🔄 回滚方案（如出现问题）
### 快速回滚代码
```bash
cd /www/wwwroot
./zjpb/manage.sh stop
# 删除新版本
rm -rf zjpb
# 恢复备份
mv zjpb_backup_YYYYMMDD_HHMMSS zjpb
# 重启
cd zjpb
./manage.sh start
```
### 恢复数据库
```bash
# 如果新表导致问题，可以删除新表
mysql -h 112.124.42.38 -u ai_nav_user -p ai_nav
# 在MySQL中执行
DROP TABLE IF EXISTS prompt_templates;
```
---
## 📝 注意事项
1. ✅ **本次更新不会影响现有数据** - 只是新增表，不修改现有表
2. ✅ **完全向后兼容** - 即使不运行迁移脚本，前台也能正常访问
3. ✅ **可以随时回滚** - 保留了完整备份
4. ⚠️ **必须备份数据库** - 虽然风险很低，但备份是必须的
5. ⚠️ **检查.env配置** - 确保生产环境的.env配置正确
---
## 🐛 常见问题
### Q1: 迁移脚本报错 "表已存在"
**A:** 说明之前已经运行过迁移，可以跳过此步骤
### Q2: Prompt管理菜单看不到
**A:** 清除浏览器缓存，重新登录后台
### Q3: 标签还是显示不出来
**A:** 清除浏览器缓存，强制刷新（Ctrl+F5）
### Q4: Clarity统计没加载
**A:** 检查网络是否能访问 clarity.ms，可能被墙
---
## 📞 技术支持
如遇问题，请检查日志：
```bash
# 查看应用日志
./manage.sh logs
# 查看错误日志
tail -f logs/error.log
```

195
docs/deployment/MANUAL_DEPLOY.md Normal file
View File

@@ -0,0 +1,195 @@
# ZJPB v2.1 手动上传部署指南
## 📋 需要上传的文件（共10个）
### 核心文件（必须上传）
1. ✅ `app.py` - 新增Prompt管理视图
2. ✅ `models.py` - 新增PromptTemplate模型
3. ✅ `migrate_prompts.py` - 数据库迁移脚本（新文件）
### 模板文件（必须上传）
4. ✅ `templates/base_new.html` - 页脚和统计代码
5. ✅ `templates/detail_new.html` - 图标修复
6. ✅ `templates/admin/site/create.html` - 标签显示修复
7. ✅ `templates/admin/site/edit.html` - 标签显示修复
### 辅助文件（可选）
8. ⭕ `INCREMENTAL_DEPLOY.md` - 部署文档
9. ⭕ `export_data.py` - 数据导出工具
10. ⭕ `migrate_db.py` - 数据库工具
### 部署脚本（新增）
11. ✅ `quick_deploy_server.sh` - 服务器端快速部署脚本
---
## 🚀 部署步骤（使用1Panel文件管理器）
### 第一步：备份生产数据库
1. 登录1Panel管理面板
2. 进入 **数据库** → 找到 `ai_nav` 数据库
3. 点击 **备份** 按钮
4. 下载备份文件到本地保存
### 第二步：备份现有代码
1. 在1Panel中进入 **文件管理**
2. 进入 `/www/wwwroot/`
3. 右键点击 `zjpb` 文件夹
4. 选择 **压缩** → 命名为 `zjpb_backup_20250130.tar.gz`
5. 下载到本地保存
### 第三步：上传新文件
#### 方法1：使用1Panel文件管理器（推荐）
1. 在1Panel文件管理器中进入 `/www/wwwroot/zjpb/`
2. **上传核心文件**（覆盖）：
- 上传 `app.py` 到 `/www/wwwroot/zjpb/`
- 上传 `models.py` 到 `/www/wwwroot/zjpb/`
- 上传 `migrate_prompts.py` 到 `/www/wwwroot/zjpb/`（新文件）
- 上传 `quick_deploy_server.sh` 到 `/www/wwwroot/zjpb/`（新文件）
3. **上传模板文件**（覆盖）：
- 进入 `/www/wwwroot/zjpb/templates/`
- 上传 `base_new.html` 到 `templates/`
- 上传 `detail_new.html` 到 `templates/`
- 进入 `templates/admin/site/`
- 上传 `create.html` 到 `templates/admin/site/`
- 上传 `edit.html` 到 `templates/admin/site/`
#### 方法2：使用FTP工具（FileZilla/WinSCP）
```
服务器地址: your-server-ip
用户名: root
密码: your-password
端口: 22 (SFTP)
```
连接后进入 `/www/wwwroot/zjpb/`，直接拖拽文件上传覆盖。
### 第四步：设置脚本权限并执行部署
在1Panel终端或SSH中执行：
```bash
# 进入项目目录
cd /www/wwwroot/zjpb
# 设置脚本执行权限
chmod +x quick_deploy_server.sh
# 执行部署脚本
./quick_deploy_server.sh
```
**脚本会自动完成以下操作：**
1. ✅ 停止应用
2. ✅ 备份当前代码
3. ✅ 安装依赖（如有更新）
4. ✅ 运行数据库迁移
5. ✅ 重启应用
6. ✅ 检查状态
### 第五步：验证部署
**前台验证：**
1. 访问首页，检查页脚是否显示：
- `© 2025 ZJPB - 焦提示词 | AI工具导航`
- `浙ICP备2025154782号-1`
2. 访问任意网站详情页，检查：
- 图标是否正常显示（不是Material Icons文本）
- 返回首页按钮显示 `←` 而不是 `arrow_back`
**后台验证：**
1. 登录后台 `/admin/login`
2. 检查左侧菜单是否有 **Prompt管理**
3. 点击进入，应该看到3条默认数据：
- 标签生成
- 主要功能生成
- 详细介绍生成
4. 进入 **网站管理** → 编辑任意网站
5. 检查标签区域是否正常显示标签名称（不是空白蓝框）
**AI功能验证：**
1. 创建新网站或编辑现有网站
2. 测试 "AI生成标签" 按钮
3. 测试 "AI生成详细介绍" 按钮
4. 测试 "AI生成主要功能" 按钮
---
## 🐛 常见问题
### Q1: 上传后文件权限错误
```bash
# 设置正确的权限
cd /www/wwwroot/zjpb
chmod 644 *.py
chmod 755 *.sh
```
### Q2: 脚本执行失败
```bash
# 手动执行步骤
cd /www/wwwroot/zjpb
./manage.sh stop
source venv/bin/activate
python migrate_prompts.py
./manage.sh start
```
### Q3: 数据库迁移报错 "表已存在"
这是正常的，说明之前已经运行过，可以忽略。
### Q4: 应用无法启动
```bash
# 查看错误日志
./manage.sh logs
# 或
tail -f logs/error.log
```
---
## 🔄 快速回滚（如出现问题）
```bash
cd /www/wwwroot/zjpb
./manage.sh stop
# 恢复备份
cd /www/wwwroot
rm -rf zjpb
tar -xzf zjpb_backup_20250130.tar.gz
# 重启
cd zjpb
./manage.sh start
```
---
## 📊 部署检查清单
- [ ] 生产数据库已备份
- [ ] 现有代码已备份
- [ ] 所有文件上传完成
- [ ] 部署脚本执行成功
- [ ] 前台页脚显示正常
- [ ] 详情页图标显示正常
- [ ] 后台Prompt管理菜单存在
- [ ] 标签显示正常
- [ ] AI功能测试通过
---
## 💡 提示
如果你经常需要部署更新，建议配置Git远程仓库（GitHub/Gitee），下次就可以直接 `git pull` 更新，更加方便快捷。

94
docs/deployment/QUICK_DEPLOY.md Normal file
View File

@@ -0,0 +1,94 @@
# 1Panel部署快速指南
## 简化部署步骤
### 1. 准备工作（本地）
1. 压缩项目：
```bash
# 排除不需要的文件
zip -r zjpb.zip . -x "*.pyc" "*__pycache__*" "*.git*" ".env" "venv/*" "test_*.py"
```
### 2. 服务器操作
#### 2.1 上传并解压
```bash
cd /www/wwwroot
mkdir zjpb
cd zjpb
# 上传zjpb.zip到此目录
unzip zjpb.zip
```
#### 2.2 一键部署脚本
```bash
# 赋予执行权限
chmod +x deploy.sh
# 执行部署
./deploy.sh
```
### 3. 配置数据库
在1Panel中创建数据库：
- 名称：ai_nav
- 用户：ai_nav_user
- 密码：（记录下来）
### 4. 配置环境变量
编辑 `.env` 文件：
```bash
nano .env
```
填写数据库信息和密钥。
### 5. 初始化
```bash
source venv/bin/activate
python init_db.py
```
### 6. 启动服务
**方法1: 使用管理脚本**
```bash
chmod +x manage.sh
./manage.sh start
```
**方法2: 使用1Panel**
在1Panel中创建反向代理网站，指向 `http://127.0.0.1:5000`
### 7. 访问
- 前台：http://your-domain.com
- 后台：http://your-domain.com/admin/login
- 默认账号：admin / admin123
---
## 快速命令参考
```bash
# 启动应用
./manage.sh start
# 停止应用
./manage.sh stop
# 重启应用
./manage.sh restart
# 查看状态
./manage.sh status
# 查看日志
./manage.sh logs
```
详细部署文档请查看：`DEPLOYMENT.md`