From 423039ce687a738f9daf0110415864c24965d274 Mon Sep 17 00:00:00 2001
From: Jowe <123822645+Selei1983@users.noreply.github.com>
Date: Fri, 6 Feb 2026 19:20:50 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0v3.0=E6=9C=8D?=
 =?UTF-8?q?=E5=8A=A1=E7=AB=AF=E9=83=A8=E7=BD=B2=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

包含内容：
- 完整的部署步骤（9个步骤）
- 功能测试清单（6项测试）
- 故障排查指南（5个常见问题）
- 性能优化建议
- 安全检查清单
- 后续维护建议

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 DEPLOY_v3.0.md | 484 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 484 insertions(+)
 create mode 100644 DEPLOY_v3.0.md

diff --git a/DEPLOY_v3.0.md b/DEPLOY_v3.0.md
new file mode 100644
index 0000000..2001c7e
--- /dev/null
+++ 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