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

## 核心优化 - 移除详情页自动调用博查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>
2026-02-06 15:54:13 +08:00
parent c1a06ad684
commit 939717fa57
27 changed files with 1670 additions and 140 deletions
--- a/docs/deployment/DEPLOYMENT.md
+++ b/docs/deployment/DEPLOYMENT.md
@@ -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`
+
+祝部署顺利！🚀