zjpb.net/DEPLOY_v3.0.md

ZJPB v3.0 服务端部署指南

版本： v3.0.1 (已修复5个代码问题) 部署日期： 2025-02-06 重要程度： 🔴 重大更新（需要数据库迁移）

---

🆕 v3.0.1 更新说明

最新提交： 7a6fd0c

已修复以下问题：

1. ✅ Collection 模型唯一约束逻辑错误
2. ✅ 用户注册重复提交数据库
3. ✅ JavaScript 未使用的变量
4. ✅ 文件夹计数逻辑缺失
5. ✅ JavaScript 错误处理不完善

详细修复记录请查看：BUGFIX_v3.0.1.md

---

📋 部署前准备

1. 系统要求

• Python 3.8+
• MySQL/MariaDB 数据库
• Git
• 足够的磁盘空间（建议至少 1GB）

2. 备份现有数据

⚠️ 重要：在部署前务必备份数据库！

# 备份数据库
mysqldump -u root -p zjpb > zjpb_backup_$(date +%Y%m%d_%H%M%S).sql

# 或者如果使用 SQLite
cp instance/zjpb.db instance/zjpb_backup_$(date +%Y%m%d_%H%M%S).db

---

🚀 部署步骤

步骤 1：登录服务器

ssh your_username@server.zjpb.net

步骤 2：进入项目目录

cd /opt/1panel/apps/zjpb

步骤 3：拉取最新代码

# 查看当前分支
git branch

# 拉取最新代码
git pull origin master

预期输出：

remote: Enumerating objects: 15, done.
remote: Counting objects: 100% (15/15), done.
...
Updating 34cd05b..2067fb1
Fast-forward
 11 files changed, 2542 insertions(+), 6 deletions(-)
 create mode 100644 CHANGELOG_v3.0.md
 create mode 100644 USER_SYSTEM_README.md
 ...

步骤 4：激活虚拟环境

# 如果使用 virtualenv
source venv/bin/activate

# 或者如果使用 conda
conda activate zjpb

步骤 5：安装/更新依赖

# 检查是否有新的依赖（v3.0 没有新增依赖）
pip install -r requirements.txt

步骤 6：运行数据库迁移 ⭐

这是最关键的一步！

python create_user_tables.py

预期输出：

开始创建用户系统表...
SUCCESS: Database tables created successfully!

Created tables:
- users
- folders
- collections

Migration completed!

如果出现错误：

• 检查数据库连接配置
• 确认数据库用户有 CREATE TABLE 权限
• 查看错误信息并根据提示修复

⚠️ 如果之前已运行过 v3.0.0（未修复版本）：

需要运行约束修复脚本：

python fix_collection_constraint.py

这将修复 Collection 表的唯一约束问题。

步骤 7：验证数据库表

# 进入数据库
mysql -u root -p zjpb

# 或者使用 Python 验证
python -c "from app import create_app; from models import db, User, Folder, Collection; app = create_app(); app.app_context().push(); print('Users table:', db.engine.has_table('users')); print('Folders table:', db.engine.has_table('folders')); print('Collections table:', db.engine.has_table('collections'))"

预期输出：

Users table: True
Folders table: True
Collections table: True

步骤 8：重启应用服务

根据您的部署方式选择对应的重启命令：

如果使用 Systemd：

sudo systemctl restart zjpb
sudo systemctl status zjpb

如果使用 Supervisor：

sudo supervisorctl restart zjpb
sudo supervisorctl status zjpb

如果使用 PM2：

pm2 restart zjpb
pm2 status

如果使用 Gunicorn 手动启动：

# 先停止旧进程
pkill -f gunicorn

# 启动新进程
gunicorn -w 4 -b 0.0.0.0:5000 app:app --daemon

步骤 9：验证部署成功

# 检查应用是否正常运行
curl http://localhost:5000/

# 检查新增的路由
curl http://localhost:5000/register
curl http://localhost:5000/login

---

✅ 功能测试清单

部署完成后，请按以下步骤测试所有功能：

1. 用户注册测试

1. 访问 https://your-domain.com/register
2. 输入用户名（至少3个字符）
3. 输入密码（至少6个字符）
4. 确认密码
5. 点击"注册"按钮
6. ✅ 应该自动登录并跳转到首页
7. ✅ 导航栏右上角应显示用户名

2. 用户登录测试

1. 点击导航栏的"退出登录"
2. 访问 https://your-domain.com/login
3. 输入刚才注册的用户名和密码
4. 点击"登录"按钮
5. ✅ 应该跳转到首页并显示登录状态

3. 收藏功能测试

1. 登录后访问任意工具详情页
2. 找到"收藏"按钮（在"访问网站"按钮下方）
3. 点击"收藏"按钮
4. ✅ 按钮应变为金色并显示"已收藏"
5. ✅ 页面顶部应显示"收藏成功"提示
6. 再次点击按钮
7. ✅ 应取消收藏并恢复原状

4. 用户中心测试

1. 点击导航栏的用户头像/用户名
2. 选择"个人中心"
3. ✅ 应显示用户信息和统计数据
4. ✅ 收藏数应该正确显示
5. ✅ 最近收藏列表应显示刚才收藏的工具

5. 收藏列表测试

1. 在用户中心点击"我的收藏"
2. 或访问 https://your-domain.com/user/collections
3. ✅ 应显示所有收藏的工具
4. ✅ 文件夹标签应正常显示
5. ✅ 点击工具卡片应跳转到详情页

6. 权限隔离测试 ⚠️

测试普通用户无法访问管理后台：

1. 使用普通用户账号登录
2. 尝试访问 https://your-domain.com/admin/
3. ✅ 应该被拒绝访问（403错误或跳转）
4. 尝试访问 https://your-domain.com/admin/seo-tools
5. ✅ 应该被拒绝访问

测试管理员登录：

1. 退出普通用户账号
2. 访问 https://your-domain.com/admin/login
3. 使用管理员账号登录
4. ✅ 应该能正常访问管理后台

---

🔧 故障排查

问题 1：数据库迁移失败

错误信息：

ERROR: Failed to create tables: (pymysql.err.OperationalError) ...

解决方案：

# 1. 检查数据库连接
python -c "from app import create_app; app = create_app(); print('Database URI:', app.config['SQLALCHEMY_DATABASE_URI'])"

# 2. 检查数据库用户权限
mysql -u root -p
GRANT ALL PRIVILEGES ON zjpb.* TO 'your_db_user'@'localhost';
FLUSH PRIVILEGES;

# 3. 重新运行迁移
python create_user_tables.py

问题 2：应用启动失败

错误信息：

ImportError: cannot import name 'User' from 'models'

解决方案：

# 1. 确认代码已正确拉取
git log -1 --oneline
# 应该显示：2067fb1 feat: v3.0 - 用户系统和收藏功能

# 2. 重新安装依赖
pip install -r requirements.txt --force-reinstall

# 3. 清除 Python 缓存
find . -type d -name __pycache__ -exec rm -r {} +
find . -type f -name "*.pyc" -delete

问题 3：收藏按钮不显示

可能原因：

• 静态文件缓存
• JavaScript 加载失败

解决方案：

# 1. 清除浏览器缓存（Ctrl + Shift + Delete）

# 2. 检查模板文件是否正确更新
grep -n "collectBtn" templates/detail_new.html

# 3. 强制刷新页面（Ctrl + F5）

问题 4：管理员需要重新登录

这是正常现象！

由于 v3.0 修改了 Admin.get_id() 的返回格式（从 id 改为 admin:id），所有管理员需要重新登录一次。

解决步骤：

1. 访问 /admin/login
2. 使用管理员账号重新登录
3. 之后就可以正常使用了

问题 5：普通用户仍能访问管理后台

这是严重的安全问题！

检查步骤：

# 1. 确认代码版本
git log -1 --grep="v3.0"

# 2. 检查 app.py 中的权限检查
grep -A 3 "isinstance(current_user, AdminModel)" app.py | head -20

# 3. 重启应用
sudo systemctl restart zjpb

---

📊 性能优化建议

1. 数据库索引验证

-- 进入数据库
mysql -u root -p zjpb

-- 检查索引
SHOW INDEX FROM users;
SHOW INDEX FROM folders;
SHOW INDEX FROM collections;

应该看到以下索引：

• users: username, email
• folders: user_id, public_slug
• collections: user_id, site_id, folder_id, (user_id, folder_id)

2. 静态文件缓存

如果使用 Nginx，建议添加静态文件缓存：

location /static/ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}

3. 数据库连接池

检查 app.py 中的数据库配置：

SQLALCHEMY_POOL_SIZE = 10
SQLALCHEMY_POOL_RECYCLE = 3600
SQLALCHEMY_MAX_OVERFLOW = 20

---

🔐 安全检查清单

部署后请确认以下安全措施：

• 普通用户无法访问 /admin/ 路径
• 普通用户无法访问管理员 API 端点
• 管理员无法使用收藏功能（这是设计行为）
• 密码已正确哈希存储（不是明文）
• HTTPS 已启用（生产环境必须）
• 数据库备份已完成

---

📝 部署记录模板

建议在部署后记录以下信息：

部署日期：2025-02-06
部署版本：v3.0.0
部署人员：[您的名字]
服务器：server.zjpb.net
数据库迁移：✅ 成功
应用重启：✅ 成功
功能测试：✅ 通过
权限测试：✅ 通过

备注：
- 数据库备份文件：zjpb_backup_20250206_HHMMSS.sql
- 管理员已重新登录
- 所有功能测试通过

---

🎯 后续维护建议

1. 监控用户注册

# 查看用户数量
mysql -u root -p zjpb -e "SELECT COUNT(*) as user_count FROM users;"

# 查看最近注册的用户
mysql -u root -p zjpb -e "SELECT id, username, created_at FROM users ORDER BY created_at DESC LIMIT 10;"

2. 监控收藏数据

# 查看收藏总数
mysql -u root -p zjpb -e "SELECT COUNT(*) as collection_count FROM collections;"

# 查看最活跃的用户
mysql -u root -p zjpb -e "SELECT user_id, COUNT(*) as count FROM collections GROUP BY user_id ORDER BY count DESC LIMIT 10;"

3. 定期备份

建议设置定时任务自动备份：

# 编辑 crontab
crontab -e

# 添加每天凌晨3点备份
0 3 * * * mysqldump -u root -p'your_password' zjpb > /backup/zjpb_$(date +\%Y\%m\%d).sql

4. 日志监控

# 查看应用日志
tail -f /var/log/zjpb/app.log

# 或者如果使用 systemd
journalctl -u zjpb -f

---

📞 技术支持

如遇到问题，请查看：

1. 用户系统文档：USER_SYSTEM_README.md
2. 版本更新日志：CHANGELOG_v3.0.md
3. Flask-Login 文档：https://flask-login.readthedocs.io/
4. SQLAlchemy 文档：https://docs.sqlalchemy.org/

---

✅ 部署完成确认

当您完成以上所有步骤后，请确认：

• ✅ 代码已成功拉取（commit: 2067fb1）
• ✅ 数据库表已创建（users, folders, collections）
• ✅ 应用已重启并正常运行
• ✅ 用户注册功能正常
• ✅ 用户登录功能正常
• ✅ 收藏功能正常
• ✅ 用户中心正常显示
• ✅ 权限隔离正常（普通用户无法访问管理后台）
• ✅ 管理员已重新登录

恭喜！v3.0 部署成功！ 🎉

---

文档版本： v1.0 最后更新： 2025-02-06 作者： Claude Sonnet 4.5