docs: 添加v3.0服务端部署指南

包含内容： - 完整的部署步骤（9个步骤） - 功能测试清单（6项测试） - 故障排查指南（5个常见问题） - 性能优化建议 - 安全检查清单 - 后续维护建议 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-06 19:20:50 +08:00
parent 2067fb1712
commit 423039ce68
1 changed files with 484 additions and 0 deletions
--- a/DEPLOY_v3.0.md
+++ b/DEPLOY_v3.0.md
@@ -0,0 +1,484 @@
 # ZJPB v3.0 服务端部署指南
 **版本：** v3.0.0
 **部署日期：** 2025-02-06
 **重要程度：** 🔴 重大更新（需要数据库迁移）
 ---
 ## 📋 部署前准备
 ### 1. 系统要求
 - Python 3.8+
 - MySQL/MariaDB 数据库
 - Git
 - 足够的磁盘空间（建议至少 1GB）
 ### 2. 备份现有数据
 **⚠️ 重要：在部署前务必备份数据库！**
 ```bash
 # 备份数据库
 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：登录服务器
 ```bash
 ssh your_username@server.zjpb.net
 ```
 ### 步骤 2：进入项目目录
 ```bash
 cd /path/to/zjpb
 # 例如：cd /var/www/zjpb
 ```
 ### 步骤 3：拉取最新代码
 ```bash
 # 查看当前分支
 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：激活虚拟环境
 ```bash
 # 如果使用 virtualenv
 source venv/bin/activate
 # 或者如果使用 conda
 conda activate zjpb
 ```
 ### 步骤 5：安装/更新依赖
 ```bash
 # 检查是否有新的依赖（v3.0 没有新增依赖）
 pip install -r requirements.txt
 ```
 ### 步骤 6：运行数据库迁移 ⭐
 **这是最关键的一步！**
 ```bash
 python create_user_tables.py
 ```
 **预期输出：**
 ```
 开始创建用户系统表...
 SUCCESS: Database tables created successfully!
 Created tables:
 - users
 - folders
 - collections
 Migration completed!
 ```
 **如果出现错误：**
 - 检查数据库连接配置
 - 确认数据库用户有 CREATE TABLE 权限
 - 查看错误信息并根据提示修复
 ### 步骤 7：验证数据库表
 ```bash
 # 进入数据库
 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：**
 ```bash
 sudo systemctl restart zjpb
 sudo systemctl status zjpb
 ```
 **如果使用 Supervisor：**
 ```bash
 sudo supervisorctl restart zjpb
 sudo supervisorctl status zjpb
 ```
 **如果使用 PM2：**
 ```bash
 pm2 restart zjpb
 pm2 status
 ```
 **如果使用 Gunicorn 手动启动：**
 ```bash
 # 先停止旧进程
 pkill -f gunicorn
 # 启动新进程
 gunicorn -w 4 -b 0.0.0.0:5000 app:app --daemon
 ```
 ### 步骤 9：验证部署成功
 ```bash
 # 检查应用是否正常运行
 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) ...
 ```
 **解决方案：**
 ```bash
 # 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'
 ```
 **解决方案：**
 ```bash
 # 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 加载失败
 **解决方案：**
 ```bash
 # 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：普通用户仍能访问管理后台
 **这是严重的安全问题！**
 **检查步骤：**
 ```bash
 # 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. 数据库索引验证
 ```sql
 -- 进入数据库
 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，建议添加静态文件缓存：
 ```nginx
 location /static/ {
    expires 30d;
    add_header Cache-Control "public, immutable";
 }
 ```
 ### 3. 数据库连接池
 检查 `app.py` 中的数据库配置：
 ```python
 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. 监控用户注册
 ```bash
 # 查看用户数量
 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. 监控收藏数据
 ```bash
 # 查看收藏总数
 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. 定期备份
 建议设置定时任务自动备份：
 ```bash
 # 编辑 crontab
 crontab -e
 # 添加每天凌晨3点备份
 0 3 * * * mysqldump -u root -p'your_password' zjpb > /backup/zjpb_$(date +\%Y\%m\%d).sql
 ```
 ### 4. 日志监控
 ```bash
 # 查看应用日志
 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